scikit-rec

A composable, scikit-style recommender systems library.

scikit-rec provides a 3-layer architecture that cleanly separates business logic, scoring strategy, and ML models. Any recommender works with any compatible scorer and estimator, giving you a mix-and-match toolkit for building recommendation systems.

Recommender (business logic)  -->  Scorer (item scoring)  -->  Estimator (ML model)

Why scikit-rec?

Composable by design. Each layer is independently extensible. Swap XGBoost for a Two-Tower model without changing your recommender. Add a new bandit strategy without touching the scorer. The library spans XGBoost, LightGBM, and scikit-learn alongside deep learning models (NCF, Two-Tower, DeepFM, SASRec, HRNN), with GPU optional — a pure-NumPy matrix factorization (ALS/SGD) requires no PyTorch. The composable architecture also accommodates novel research: a Goal-Conditioned Supervised Learning (GCSL) recommender for multi-objective recommendation was implemented as a single Recommender subclass — no new scorer or estimator required. Contributions welcome: implement one abstract class and it works with everything else.

Beyond ranking. Contextual bandits (epsilon-greedy, static-action) and heterogeneous treatment effect estimation (T/S/X-Learner) are first-class paradigms, not afterthoughts. All share the same evaluation infrastructure, so you can directly compare a ranking policy against a bandit or uplift policy on the same logged data.

Production-grade evaluation. The most complete offline policy evaluation suite in any recommendation library: IPS, Doubly Robust, SNIPS, Direct Method, Policy-Weighted, and Replay Match, paired with ten ranking, classification, and regression metrics (Precision, Recall, MAP, MRR, NDCG, ROC-AUC, PR-AUC, Expected Reward, RMSE, MAE) — enabling counterfactual policy comparison from logged data with a single call. Multi-label classification and multi-target regression workloads (wide-format MultioutputScorer) get per-label diagnostics and macro-averaged metrics out of the same evaluate() API.

Production readiness. Config-driven pipeline factory with Optuna HPO, low-latency single-user inference (recommend_online), two-stage retrieval-then-ranking, and batch training.

Agent-friendly. Optionally pair with scikit-rec-agent so an LLM agent can build, train, and tune models against this library's contracts.

Learn by example. Ten end-to-end Jupyter notebooks on MovieLens 1M cover ranking, bandits, uplift, sequential recommendations, multi-objective optimization, hyperparameter tuning, two-stage retrieval, and contextual two-tower models. Our SASRec achieves HR@10 = 0.8953 and NDCG@10 = 0.6331 on MovieLens-1M (leave-last-out, 1 positive + 100 negatives). Each notebook downloads data, trains, evaluates, and shows sample recommendations — ready to run.

Installation

pip install scikit-rec

Optional extras:

pip install scikit-rec[torch]          # Deep learning models (DeepFM, NCF, SASRec, HRNN, Two-Tower)
pip install scikit-rec[aws]            # S3 data loading
pip install scikit-rec[torch,aws]      # All optional extras

Notes:

• scikit-rec[torch] is required only for PyTorch-based estimators and deep learning pipelines.
• scikit-rec[aws] adds S3 dataset loading support without pulling in Torch.

Quick Start

from skrec.estimator.classification.xgb_classifier import XGBClassifierEstimator
from skrec.scorer.universal import UniversalScorer
from skrec.recommender.ranking.ranking_recommender import RankingRecommender
from skrec.examples.datasets import (
    sample_binary_reward_interactions,
    sample_binary_reward_users,
    sample_binary_reward_items,
)

# Build the pipeline: Estimator -> Scorer -> Recommender
estimator = XGBClassifierEstimator({"learning_rate": 0.1, "max_depth": 5})
scorer = UniversalScorer(estimator)
recommender = RankingRecommender(scorer)

# Train
recommender.train(
    interactions_ds=sample_binary_reward_interactions,
    users_ds=sample_binary_reward_users,
    items_ds=sample_binary_reward_items,
)

# Recommend
interactions_df = sample_binary_reward_interactions.fetch_data()
users_df = sample_binary_reward_users.fetch_data()
recommendations = recommender.recommend(interactions=interactions_df, users=users_df, top_k=5)

Config-driven quick start

The orchestrator API lets you build a pipeline from a configuration dictionary instead of wiring classes manually.

from skrec.orchestrator import create_recommender_pipeline

config = {
    "recommender_type": "ranking",
    "scorer_type": "universal",
    "estimator_config": {
        "ml_task": "classification",
        "xgboost": {
            "n_estimators": 100,
            "max_depth": 5,
            "learning_rate": 0.1,
        },
    },
}

recommender = create_recommender_pipeline(config)
recommender.train(
    interactions_ds=sample_binary_reward_interactions,
    users_ds=sample_binary_reward_users,
    items_ds=sample_binary_reward_items,
)

Agent integration

scikit-rec is designed to be consumed by LLM agents via its config-driven factory and a capability_matrix() introspection API. The companion repo scikit-rec-agent provides a ready-made conversational agent that uses this surface to guide a user through dataset preparation, model selection, training, and evaluation — no hand-coded class wiring required.

How the agent surface works

capability_matrix() returns the authoritative set of valid types for every factory dimension. The factory validates its inputs against these same tuples, so the agent's knowledge is always in lockstep with what the library actually supports:

from skrec.orchestrator import capability_matrix

cm = capability_matrix()
cm["recommender_types"]    # ('ranking', 'bandits', 'sequential', 'hierarchical_sequential', 'uplift', 'gcsl')
cm["scorer_types"]         # ('universal', 'independent', 'multiclass', 'multioutput', 'sequential', 'hierarchical')
cm["estimator_types"]      # ('tabular', 'embedding', 'sequential')
cm["embedding_model_types"] # ('matrix_factorization', 'ncf', 'two_tower', ...)
cm["scorer_config_keys"]   # per-scorer accepted kwargs, e.g. {"multioutput": ("on_degenerate_target",)}

An agent can call capability_matrix() to populate its system prompt, then pass the user's choices directly to create_recommender_pipeline(). The factory validates compatibility upfront and raises a clear ValueError for any invalid combination before training begins.

Components

Recommenders

Scorers

Estimators

Evaluators

Metrics

Precision@k, Recall@k, MAP, MRR, NDCG, ROC-AUC, PR-AUC, Expected Reward, RMSE, MAE (the last two for multi-target regression via MultioutputScorer).

Retrievers

Two-stage retrieval: Popularity, Content-Based, Embedding-Based.

Example Notebooks

Notebooks are grouped by dataset under examples/:

MovieLens-1M (examples/movielens-1m/)

Amazon Books (examples/amazon-books/)

Generic (examples/generic/) — dataset-agnostic library mechanics

The MovieLens-1M notebooks download data automatically from GroupLens. The four Amazon Books notebooks share a cached download from McAuley-Lab's Amazon Reviews 2023 via HuggingFace datasets (the first run pays the download cost; subsequent runs reuse the cache). All notebooks include training, evaluation, and sample recommendations.

Documentation

Full documentation is available at intuit.github.io/scikit-rec.

• Architecture overview
• Capability matrix
• Quick start tutorial
• Dataset preparation
• Evaluation guide

Development

git clone https://github.com/intuit/scikit-rec.git
cd scikit-rec
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest tests/

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidance on feature requests, bug reports, and pull request workflow.

Code of Conduct

This project follows a Code of Conduct to ensure a respectful, inclusive community.

License

Apache 2.0