scikit-rec 0.3.2__tar.gz → 0.4__tar.gz

{scikit_rec-0.3.2 → scikit_rec-0.4}/.gitignore

@@ -30,3 +30,4 @@ coverage.xml
 
 # Example notebook data (auto-fetched/regenerated on first run; not tracked)
 examples/*/data/
+

scikit_rec-0.4/CODE_OF_CONDUCT.md

@@ -0,0 +1,33 @@
+# Code of Conduct
+
+## Our Pledge
+
+We pledge to make participation in `scikit-rec` a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Showing empathy towards other community members
+
+Examples of unacceptable behavior:
+
+- Harassment, abusive language, or derogatory comments
+- Disrespectful or exclusionary actions
+- Personal attacks or public shaming
+- Disruptive behavior or trolling
+
+## Reporting
+
+If you experience or witness unacceptable behavior, please report it by opening an issue on GitHub with the label `code-of-conduct` or contacting the maintainers directly.
+
+## Enforcement
+
+Project maintainers may take any action they deem appropriate in response to incidents of unacceptable behavior, including warning or banning individuals from the project.
+
+## Attribution
+
+This Code of Conduct is adapted from the Contributor Covenant.

scikit_rec-0.4/CONTRIBUTING.md

@@ -0,0 +1,146 @@
+# Contributing to scikit-rec
+
+Thank you for your interest in contributing to `scikit-rec`! We welcome bug reports, feature requests, and code contributions.
+
+## How to contribute
+
+1. Fork the repository and create a new branch.
+2. Make your changes in a focused branch.
+3. Add tests for bug fixes and new functionality.
+4. Run the test suite locally:
+
+```bash
+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/
+```
+
+For PyTorch-based estimators (NCF, Two-Tower, SASRec, HRNN, DeepFM), install with the torch extra:
+
+```bash
+pip install -e ".[dev,torch]"
+```
+
+5. Commit with a clear message and open a pull request against `main`.
+
+## Guidelines
+
+- Keep pull requests small and focused.
+- Follow the existing code style and conventions.
+- Add or update documentation when behavior changes.
+- Use descriptive commit messages.
+
+## Reporting issues
+
+If you find a bug or have a feature idea, please open an issue at:
+
+https://github.com/intuit/scikit-rec/issues
+
+Include a clear description of the problem, a minimal reproduction example, and the expected behavior.
+
+---
+
+## Architecture guide for contributors
+
+`scikit-rec` uses a 3-layer architecture: **Recommender → Scorer → Estimator**. Each layer has a well-defined abstract base class. Adding a new component means subclassing the right base, implementing a small set of abstract methods, and (for factory-accessible types) registering the new type in `skrec/orchestrator/factory.py`.
+
+```
+skrec/
+  estimator/
+    base_estimator.py          ← BaseEstimator (tabular)
+    classification/            ← tabular classifiers
+    regression/                ← tabular regressors
+    embedding/                 ← BaseEmbeddingEstimator + embedding models
+    sequential/                ← SequentialEstimator + SASRec, HRNN
+  scorer/
+    base_scorer.py             ← BaseScorer
+    universal.py, independent.py, multiclass.py, multioutput.py, ...
+  recommender/
+    base_recommender.py        ← BaseRecommender
+    ranking/, bandits/, sequential/, gcsl/, uplift_model/
+  orchestrator/
+    factory.py                 ← create_recommender_pipeline + capability_matrix
+```
+
+### Adding a new estimator
+
+**Tabular classifier or regressor:**
+
+1. Subclass `BaseClassifier` (in `skrec/estimator/classification/base_classifier.py`) or `BaseRegressor`.
+2. Implement `fit(X, y)` and `predict_proba(X)` / `predict(X)`.
+3. Add the file to `skrec/estimator/classification/` or `skrec/estimator/regression/`.
+4. To expose it via `create_recommender_pipeline`, add a branch in `create_estimator()` in `factory.py` and extend `EstimatorConfig` with the new config key. Also add the new key to `capability_matrix()`.
+
+**Embedding estimator:**
+
+1. Subclass `BaseEmbeddingEstimator` (`skrec/estimator/embedding/base_embedding_estimator.py`).
+2. Implement `fit_embedding_model(users, items, interactions, ...)` and `predict_proba_with_embeddings(...)`.
+3. Add a lazy entry to `_EMBEDDING_ESTIMATOR_MAP` in `factory.py` — no eager import needed.
+
+**Sequential estimator (SASRec-style):**
+
+1. Subclass `SequentialEstimator` (`skrec/estimator/sequential/base_sequential_estimator.py`).
+2. Add a lazy entry to `_SEQUENTIAL_ESTIMATOR_MAP` in `factory.py`.
+
+### Adding a new scorer
+
+1. Subclass `BaseScorer` (`skrec/scorer/base_scorer.py`).
+2. Implement `score_items(interactions, users, items)` and `score_fast(features_df)` if supporting `recommend_online`.
+3. Add it to `SCORER_TYPES` in `factory.py`, add a branch in `create_scorer()`, and add an entry (even an empty `frozenset`) to `_SCORER_CONFIG_ALLOWED`.
+
+### Adding a new multi-target estimator family
+
+`MixedTypeMultiTargetScorer` is polymorphic over estimator families via the runtime-checkable `MultiTargetEstimator` Protocol. To add a fourth family (e.g. a tree-based joint model, an MoE encoder, etc.):
+
+1. Implement a class with the four attributes/methods on `skrec.estimator.classification._multi_target_protocol.MultiTargetEstimator`:
+   - `target_specs: dict[str, TargetType | TargetGroupSpec]` attribute
+   - `fit(X, y, X_valid=None, y_valid=None)`
+   - `predict_proba_dict(X) -> dict[str, np.ndarray]` (multilabel groups fanned out)
+   - `predict_targets_dict(X) -> dict[str, np.ndarray]` (multilabel groups fanned out)
+2. The scorer's `__init__` Protocol check accepts your class automatically — no changes to `MixedTypeMultiTargetScorer` are required.
+3. If the family fits the joint pattern (shared encoder + per-target heads), subclass `JointMultiTargetBaseEstimator` and supply an encoder via `_build_encoder(input_dim, label_input_dim)`. See `joint_multi_target_mlp.py` for the minimal template.
+4. To expose via the factory, add a mode to `MULTI_TARGET_MODEL_TYPES` and a branch in `_create_multi_target_estimator()` in `factory.py`.
+5. For `mode="independent"` extensions (adding a new sub-estimator type), extend `_INDEPENDENT_TARGET_COMPAT` and `_create_independent_sub_estimator()`.
+
+Gate 1 (`tests/test_mixed_type_multi_target_gates.py`) asserts every family satisfies the Protocol; add your class to that test when contributing.
+
+### Adding a new recommender
+
+1. Subclass `BaseRecommender` (`skrec/recommender/base_recommender.py`).
+2. Implement `train(...)`, `recommend(...)`, and optionally `score_items(...)`.
+3. Add it to `RECOMMENDER_TYPES` in `factory.py` and add a branch in `create_recommender()`.
+
+### Adding a new retriever
+
+1. Subclass `BaseCandidateRetriever` (`skrec/retriever/base_retriever.py`).
+2. Implement `retrieve(interactions, users, items)`.
+3. Add an entry to `_RETRIEVER_MAP` in `factory.py`.
+
+---
+
+## Test conventions
+
+Tests live in `tests/`. The main patterns:
+
+- **Unit tests** (`test_base_*.py`, `test_*_scorer.py`, etc.) use small synthetic fixtures defined in `tests/conftest.py` and `tests/utils.py`.
+- **Integration tests** (`test_*_integration.py`) run a full train → evaluate cycle on sample data and are the primary correctness check.
+- **Smoke tests** (`test_estimator_smoke.py`) instantiate every estimator and verify they don't error on a tiny dataset — useful for catching import or API regressions.
+
+When adding a new component, add at minimum:
+- A unit test covering the abstract interface.
+- An integration test that trains and evaluates end-to-end.
+- If the component is factory-accessible, a test in `test_orchestrator_factory.py`.
+
+S3-dependent tests (`test_s3.py`) use `moto` to mock AWS — no real credentials needed.
+
+---
+
+## Community
+
+By contributing, you agree to abide by the project's Code of Conduct:
+
+- `CODE_OF_CONDUCT.md`
+
+We aim to make this project welcoming, inclusive, and respectful.

{scikit_rec-0.3.2 → scikit_rec-0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scikit-rec
-Version: 0.3.2
+Version: 0.4
 Summary: A scikit-style recommender systems library
 License-Expression: Apache-2.0
 Project-URL: Homepage, https://github.com/intuit/scikit-rec
@@ -19,6 +19,8 @@ Requires-Dist: pyarrow<20.0.0,>=10.0.0
 Requires-Dist: optuna<5.0.0,>=3.0.0
 Provides-Extra: torch
 Requires-Dist: torch<3.0.0,>=2.2.0; extra == "torch"
+Provides-Extra: deep
+Requires-Dist: torch<3.0.0,>=2.2.0; extra == "deep"
 Provides-Extra: aws
 Requires-Dist: boto3<3.0.0,>=1.26.27; extra == "aws"
 Provides-Extra: dev
@@ -32,6 +34,8 @@ Dynamic: license-file
 
 # scikit-rec
 
+[![Python Package](https://img.shields.io/pypi/v/scikit-rec?color=blue&logo=python&logoColor=white)](https://pypi.org/project/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.
@@ -63,10 +67,15 @@ pip install scikit-rec
 Optional extras:
 
 ```bash
-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]          # 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
 
 ```python
@@ -97,6 +106,55 @@ 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.
+
+```python
+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](https://github.com/intuit/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:
+
+```python
+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
@@ -117,7 +175,8 @@ recommendations = recommender.recommend(interactions=interactions_df, users=user
 | `UniversalScorer` | Single global model using item features (auto-dispatches tabular vs. embedding) |
 | `IndependentScorer` | Separate model per item |
 | `MulticlassScorer` | Items as competing classes |
-| `MultioutputScorer` | Wide-format multi-label binary classification or multi-target regression (one `ITEM_<name>` column per target) |
+| `MultioutputScorer` | Wide-format multi-label binary classification or multi-target regression (one `ITEM_<name>` column per target); accepts `scorer_config={"on_degenerate_target": "constant"}` to handle single-class training columns |
+| `MixedTypeMultiTargetScorer` | Wide-format scorer for **heterogeneous per-target types** (binary + regression + multiclass + multilabel groups) in one model. Three estimator families: joint MLP, joint Transformer (FT-Transformer-style), independent (per-target sub-estimators). Per-target metric dispatch returns `Dict[str, float]`. See [scorers guide](docs/user-guide/scorers.md#5-mixedtypemultitargetscorer) |
 | `SequentialScorer` | For sequential estimators (SASRec) |
 | `HierarchicalScorer` | For HRNN estimators |
 
@@ -208,6 +267,14 @@ 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](CODE_OF_CONDUCT.md) to ensure a respectful, inclusive community.
+
 ## License
 
 [Apache 2.0](LICENSE)

{scikit_rec-0.3.2 → scikit_rec-0.4}/README.md

@@ -1,5 +1,7 @@
 # scikit-rec
 
+[![Python Package](https://img.shields.io/pypi/v/scikit-rec?color=blue&logo=python&logoColor=white)](https://pypi.org/project/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.
@@ -31,10 +33,15 @@ pip install scikit-rec
 Optional extras:
 
 ```bash
-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]          # 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
 
 ```python
@@ -65,6 +72,55 @@ 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.
+
+```python
+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](https://github.com/intuit/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:
+
+```python
+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
@@ -85,7 +141,8 @@ recommendations = recommender.recommend(interactions=interactions_df, users=user
 | `UniversalScorer` | Single global model using item features (auto-dispatches tabular vs. embedding) |
 | `IndependentScorer` | Separate model per item |
 | `MulticlassScorer` | Items as competing classes |
-| `MultioutputScorer` | Wide-format multi-label binary classification or multi-target regression (one `ITEM_<name>` column per target) |
+| `MultioutputScorer` | Wide-format multi-label binary classification or multi-target regression (one `ITEM_<name>` column per target); accepts `scorer_config={"on_degenerate_target": "constant"}` to handle single-class training columns |
+| `MixedTypeMultiTargetScorer` | Wide-format scorer for **heterogeneous per-target types** (binary + regression + multiclass + multilabel groups) in one model. Three estimator families: joint MLP, joint Transformer (FT-Transformer-style), independent (per-target sub-estimators). Per-target metric dispatch returns `Dict[str, float]`. See [scorers guide](docs/user-guide/scorers.md#5-mixedtypemultitargetscorer) |
 | `SequentialScorer` | For sequential estimators (SASRec) |
 | `HierarchicalScorer` | For HRNN estimators |
 
@@ -176,6 +233,14 @@ 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](CODE_OF_CONDUCT.md) to ensure a respectful, inclusive community.
+
 ## License
 
 [Apache 2.0](LICENSE)

{scikit_rec-0.3.2 → scikit_rec-0.4}/docs/advanced/orchestration.md

@@ -31,6 +31,10 @@ recommender.train(
 recommendations = recommender.recommend(interactions=query_df, top_k=5)
 ```
 
+## Agent-Friendly Orchestration
+
+`scikit-rec` exposes a config-driven recommender factory that is especially useful for automated and LLM-based systems. The factory validates compatibility between recommender, scorer, and estimator types, and `capability_matrix()` can be used by tooling or an agent to enumerate supported options.
+
 ## Configuration Reference
 
 ### Top-Level Config (`RecommenderConfig`)
@@ -146,43 +150,72 @@ The factory validates these constraints at pipeline creation time and raises `Va
 
 ## Programmatic Capability Introspection
 
-For tooling that needs to enumerate what the factory understands (system-prompt builders, config validators, UI pickers, etc.), `skrec.orchestrator` exposes three authoritative enum tuples plus a `capability_matrix()` accessor. These are the same values the factory validates against internally, so they stay in lockstep automatically.
+For tooling that needs to enumerate what the factory understands (system-prompt builders, config validators, UI pickers, etc.), `skrec.orchestrator` exposes four authoritative enum tuples plus a `capability_matrix()` accessor. These are the same values the factory validates against internally, so they stay in lockstep automatically.
 
 ```python
 from skrec.orchestrator import (
     RECOMMENDER_TYPES,
     SCORER_TYPES,
     ESTIMATOR_TYPES,
+    TABULAR_MODEL_TYPES,
+    MULTI_TARGET_MODEL_TYPES,
     capability_matrix,
 )
 
-RECOMMENDER_TYPES  # ('ranking', 'bandits', 'sequential', 'hierarchical_sequential', 'uplift', 'gcsl')
-SCORER_TYPES       # ('universal', 'independent', 'multiclass', 'multioutput', 'sequential', 'hierarchical')
-ESTIMATOR_TYPES    # ('tabular', 'embedding', 'sequential')
+RECOMMENDER_TYPES         # ('ranking', 'bandits', 'sequential', 'hierarchical_sequential', 'uplift', 'gcsl')
+SCORER_TYPES              # ('universal', 'independent', 'multiclass', 'multioutput', 'mixed_type_multi_target', 'sequential', 'hierarchical')
+ESTIMATOR_TYPES           # ('tabular', 'embedding', 'sequential')
+TABULAR_MODEL_TYPES       # ('xgboost', 'lightgbm', 'deepfm')
+MULTI_TARGET_MODEL_TYPES  # ('joint_mlp', 'joint_transformer', 'independent')
 
 capability_matrix()
 # {
 #     "recommender_types": (...),
 #     "scorer_types": (...),
 #     "estimator_types": (...),
+#     "tabular_model_types": ("xgboost", "lightgbm", "deepfm"),
 #     "embedding_model_types": ("matrix_factorization", "ncf", "two_tower", ...),
 #     "sequential_model_types": ("sasrec_classifier", "sasrec_regressor", ...),
+#     "multi_target_model_types": ("joint_mlp", "joint_transformer", "independent"),
 #     "inference_method_types": ("mean_scalarization", "percentile_value", "predefined_value"),
 #     "retriever_types": ("popularity", "content_based", "embedding"),
 #     "scorer_config_keys": {
 #         "multioutput": ("on_degenerate_target",),
+#         "mixed_type_multi_target": ("target_specs",),
 #         "multiclass": (),
-#         "independent": (),
-#         "universal": (),
-#         "sequential": (),
-#         "hierarchical": (),
+#         # ...
+#     },
+#     "evaluator_types": (...),
+#     "metric_types": (...),  # includes "multiclass_accuracy" (new in v2)
+#     # Multi-target capabilities (consumed by scikit-rec-agent for pre-flight validation):
+#     "target_types": ("binary", "regression", "multiclass", "multilabel"),
+#     "target_type_metric_compat": {
+#         "binary":     ("roc_auc", "pr_auc"),
+#         "regression": ("rmse", "mae"),
+#         "multiclass": ("multiclass_accuracy",),
+#         "multilabel": ("roc_auc", "pr_auc"),
 #     },
+#     "independent_target_compat": {
+#         "binary":     ("lightgbm", "logreg", "sklearn", "xgboost"),
+#         "regression": ("lightgbm", "sklearn", "xgboost"),
+#         "multiclass": ("lightgbm", "logreg"),  # xgboost excluded — see scorers.md
+#         "multilabel": ("lightgbm", "logreg", "sklearn", "xgboost"),
+#     },
+#     # Forward-compat flag for v3: empty in v2; populates with scorer names
+#     # supporting OBSERVED_* conditioning when v3 conditional estimators land.
+#     "scorer_supports_observed_conditioning": (),
 # }
 ```
 
-Evaluator and metric enums are **not** included in `capability_matrix()` — those already live as proper `Enum` subclasses in `skrec.evaluator.datatypes.RecommenderEvaluatorType` and `skrec.metrics.datatypes.RecommenderMetricType` and are enumerable directly (e.g. `list(RecommenderEvaluatorType)`).
+### Multi-target capabilities
+
+The four `target_*`/`independent_*`/`scorer_supports_*` keys above were added in v2 to support `MixedTypeMultiTargetScorer`. They let external tooling (like scikit-rec-agent) validate `target_specs`, metric/target compatibility, and per-target sub-estimator type choices without mirroring scikit-rec internals.
+
+The dispatch tables (`target_type_metric_compat`, `independent_target_compat`) are mirrors of in-code constants. Gate 7 in `tests/test_mixed_type_multi_target_gates.py` asserts the runtime, capability matrix, and human-canonical doc table all agree.
 
-The full compatibility reference (which scorer works with which estimator, retriever constraints, etc.) is on the [Capability Matrix](../user-guide/capability-matrix.md) page.
+For shape-detection symmetry between scikit-rec and scikit-rec-agent, `skrec.orchestrator` also exposes `contract_from_dataframe(df, target_specs=None)` which classifies a DataFrame into one of: `long_interactions`, `long_with_timestamp`, `wide_multioutput`, `wide_mixed_type_multi_target`, `multiclass`, `prebuilt_sequences`, `sessions`. Mixed-type vs multioutput disambiguation requires `target_specs`.
+
+The full compatibility reference (which scorer works with which estimator, retriever constraints, etc.) is on the [Capability Matrix](../user-guide/capability-matrix.md) page; the joint-vs-independent decision tree and per-`TargetType` metric dispatch table are on the [Decision rule](../user-guide/decision-rule.md) page.
 
 ## Complete Examples
 
@@ -503,6 +536,35 @@ ValueError: scorer_type 'independent' does not support embedding estimators.
     Use scorer_type='universal' with embedding estimators.
 ```
 
+## Factory scope
+
+The tabular estimator path supports **XGBoost**, **LightGBM**, and **DeepFM** natively. Pick one by adding its key to `estimator_config`:
+
+```python
+# XGBoost (default)
+create_recommender_pipeline({
+    "recommender_type": "ranking",
+    "scorer_type": "universal",
+    "estimator_config": {"ml_task": "classification", "xgboost": {"n_estimators": 200}},
+})
+
+# LightGBM — same shape, just swap the key
+create_recommender_pipeline({
+    "recommender_type": "ranking",
+    "scorer_type": "universal",
+    "estimator_config": {"ml_task": "classification", "lightgbm": {"n_estimators": 200, "num_leaves": 63}},
+})
+
+# DeepFM — requires scikit-rec[torch]; classification only
+create_recommender_pipeline({
+    "recommender_type": "ranking",
+    "scorer_type": "universal",
+    "estimator_config": {"ml_task": "classification", "deepfm": {"embedding_dim": 16, "epochs": 10}},
+})
+```
+
+Only one tabular key (`xgboost`, `lightgbm`, or `deepfm`) may be present in a single config — specifying more than one raises `ValueError`. For estimator types not covered here (custom sklearn models, etc.) you can still compose manually and pass the estimator directly to a scorer.
+
 ## Next Steps
 
 - **[HPO Guide](hpo.md)** — Add hyperparameter optimization to configs

{scikit_rec-0.3.2 → scikit_rec-0.4}/docs/advanced/production.md

@@ -325,7 +325,28 @@ def get_recommendations(user_id, user_features, top_k=5):
     return recommendations
 ```
 
-### 4. Parallel Processing
+### 4. Thread Safety
+
+**`RankingRecommender`** is thread-safe for concurrent inference after training, whether or not a retriever is attached:
+
+- **Without a retriever** — the scorer is accessed read-only; no state is mutated per call.
+- **With a retriever** — `_recommend_with_retriever` makes a shallow copy of the scorer at the start of each call, so per-user `item_subset` mutations are confined to that call stack and never touch the shared scorer instance.
+
+**`IndependentScorer`** is the one remaining exception — its parallel inference configuration mutates internal state. For multi-threaded serving with `IndependentScorer`, either:
+- Load one recommender instance **per worker process** (the safest approach, and the default for gunicorn/uvicorn multi-process deployments), or
+- Protect the shared instance with a lock.
+
+```python
+import threading
+
+_lock = threading.Lock()
+
+def thread_safe_recommend(interactions_df, users_df, top_k=5):
+    with _lock:  # only needed when using IndependentScorer
+        return recommender.recommend(interactions=interactions_df, users=users_df, top_k=top_k)
+```
+
+### 5. Parallel Processing
 
 #### For Independent Scorer
 

{scikit_rec-0.3.2 → scikit_rec-0.4}/docs/getting-started/installation.md

@@ -2,7 +2,7 @@
 
 ## Prerequisites
 
-- **Python 3.9** or higher
+- **Python 3.10** or higher
 
 ## Install from PyPI
 
@@ -26,6 +26,10 @@ For PyTorch-based models (NCF, Two-Tower, DCN, NeuralFactorization, SASRec, HRNN
 pip install scikit-rec[torch]
 ```
 
+The base install already includes XGBoost, LightGBM, scikit-learn, and Matrix Factorization (NumPy-only). PyTorch is only required for the deep learning estimators listed above.
+
+> **Note for contributors:** If you are testing PyTorch-based estimators locally, install with `pip install -e ".[dev,torch]"` — the plain `.[dev]` install skips torch and those tests will be skipped automatically.
+
 ### AWS Support
 
 For S3 data loading:

{scikit_rec-0.3.2 → scikit_rec-0.4}/docs/getting-started/quick-start.md

@@ -112,6 +112,34 @@ print("\nTop 5 items for each user:")
 print(recommendations)
 ```
 
+## Optional: Config-driven quick start
+
+Instead of assembling the pipeline manually, use `skrec.orchestrator` to build a recommender from a configuration dictionary. This is ideal for automated workflows and agent-based systems.
+
+```python
+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,
+)
+```
+
 ### Output Format
 
 The output is a NumPy array where: