Configuration & Runtime Operations

Configuration locations

The shared configuration directory is:

src/cooprecsys/configs/
├── configuration.ini
├── fallback_config.py
├── lgbm_config.py
└── logged.py

Model packages may also have model-local configuration classes, such as models/ary2tower/config.py.

The project should be treated as configuration-driven but code-validated: the INI file supplies operational defaults, while typed dataclasses validate model/fallback settings before use.

configuration.ini: what each section controls

[DEFAULT]

General repository/runtime metadata. Treat encrypted credentials or tokens in configuration files as secrets that should not be committed in a real deployment; environment/secret-manager injection is safer for production.

[tqdm]

Controls progress bar presentation (colour, ncols, BarFormats). It affects CLI observability, not model mathematics.

[SHAP]

Controls subject/row sampling and feature-display settings used by explainability/reporting workflows, including the subject identifier and the maximum number of displayed features.

[model]

Contains shared native-model defaults:

[model]
dtype = float32
no_components = 10
loss = warp
learning_schedule = adagrad
epochs = 500
num_threads = 4

These are primarily shared defaults for the collaborative-filtering/native stack. Ary2Tower has its own typed TwoTowerConfig because its hyperparameters are different (embedding_dim, hidden_dim, output_dim, learning_rate, momentum, n_epochs, num_threads, random_state).

[duckdb]

Sets in-process analytical parallelism, currently via the DuckDB thread count.

[logging]

Sets the root logging verbosity. DEBUG is useful when tracing data preparation or native backend selection; WARNING is safer for normal production operation.

[FEATURES], [MODEL_LGBM], [TRAINING], [TUNING], [RATING], [INFERENCE], [PATHS]

These sections form the LTR-LightGBM configuration family. They cover feature labels/query IDs, ranker hyperparameters, boosting/early-stopping controls, Bayesian tuning, rating/scoring parameters, inference top_k, artifact paths, and experiment outputs.

[FALLBACK]

This section belongs to the broader fallback/ranking configuration surface. The typed FallbackConfig validates strategy, score mode, ANN parameters, cold-start behavior, caching, and execution settings.

from configparser import ConfigParser
from cooprecsys.configs.fallback_config import FallbackConfig

cfg = ConfigParser()
cfg.read('src/cooprecsys/configs/configuration.ini')
fallback = FallbackConfig.from_configparser(cfg)
fallback.validate()

Do not interpret every [FALLBACK] option as an Ary2Tower inference requirement. Ary2Tower’s current residual fallback implementation is a dedicated TwoTowerFallBack that uses a Bayesian-smoothed popularity prior and optional recency decay.

Model-local Ary2Tower configuration

from cooprecsys.models.ary2tower import TwoTowerConfig

config = TwoTowerConfig(
    embedding_dim=32,
    hidden_dim=64,
    output_dim=16,
    learning_rate=0.01,
    momentum=0.9,
    n_epochs=10,
    num_threads=4,
    random_state=42,
)

Construction validates hyperparameters eagerly. num_threads controls the OpenMP path when Cython extensions are available.

Configuration discipline

Record the effective configuration together with:

• model artifact/version;
• feature/encoder version;
• training data window;
• runtime/backend (cython-openmp or NumPy fallback);
• inference candidate/exclusion policy;
• report or experiment identifier.

That metadata is often more valuable for debugging a recommendation regression than the model file alone.