Purpose
LTR-LightGBM is the tabular, feature-rich ranking path in CoopRecSys. Use it when recommendation quality depends heavily on engineered transaction/customer/product features and query-group ranking.
Group-aware splitting
Keep rows belonging to the same customer/query group together to avoid leakage:
from sklearn.model_selection import GroupShuffleSplit
gss = GroupShuffleSplit(n_splits=1, test_size=0.2, random_state=42)
train_idx, test_idx = next(gss.split(data, groups=data['CustomerID']))
train_df = data.iloc[train_idx]
test_df = data.iloc[test_idx]The important principle is that the grouping key follows the ranking query semantics; CustomerID is one common choice for customer-oriented recommendation data.
Configuration
LTR is driven by configs/lgbm_config.py and the shared configuration.ini. Relevant sections include [FEATURES], [MODEL_LGBM], [TRAINING], [TUNING], [INFERENCE], [PATHS], and [RATING].
The current defaults include LambdaRank with NDCG-oriented evaluation, configurable ndcg_eval_at, learning rate, leaves/depth, feature/bagging fractions, regularization, early stopping, and Optuna-style tuning settings.
Rating/score preparation
The qrates package can generate a pseudo-rating or composite transaction score before LTR training. RATING.ColumnName controls the pseudo-rating output name, while frequency/quantity/spend/recency/loyalty weights support interpretable score construction.
Ranking metrics
The documented ranking workflow includes NDCG, MAP, and AUC. Choose metrics that match the actual query structure and business objective rather than optimizing a generic single metric.
Experiment tracking
MLflow support is configured through the typed LTR configuration/path settings. Keep run parameters, feature versions, data windows, and generated reports tied to the same experiment identifier.
Production workflow
transaction rows
↓
prepare + features + optional qrates
↓
query/customer grouping
↓
train / validation split
↓
LightGBM ranking model
↓
metrics + optional MLflow
↓
ranking inference
↓
explainability / report artifacts