# recommenders-team/recommenders architecture

> Architecture diagram of the GitHub repository recommenders-team/recommenders, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/recommenders-team/recommenders
- Repository: https://github.com/recommenders-team/recommenders

## Overview

Recommenders is a Python toolkit and example collection for prototyping, evaluating, tuning, and operationalizing recommendation systems. Its principal workflow is to prepare data, train a recommender, evaluate its predictions, and tune model parameters; operationalization is a documented production task. The package also supplies dataset loaders and splitters, a broad algorithm portfolio, and Python/Spark evaluation. The README establishes these product stages, while the excerpts show selected implementations; links to unsampled model families and operationalization are therefore documented capability links, not claims of inspected calls.

Main entry points: [`recommenders/models`](https://github.com/recommenders-team/recommenders/tree/main/recommenders/models) (Algorithm portfolio), [`recommenders/datasets`](https://github.com/recommenders-team/recommenders/tree/main/recommenders/datasets) (Dataset loaders), [`recommenders/tuning/nni/ncf_training.py`](https://github.com/recommenders-team/recommenders/blob/main/recommenders/tuning/nni/ncf_training.py) (NCF tuning run), [`recommenders/evaluation/python_evaluation.py`](https://github.com/recommenders-team/recommenders/blob/main/recommenders/evaluation/python_evaluation.py) (Python metrics)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data preparation"]
  node_dataset["Dataset loaders"]
  node_movielens["MovieLens loader<br/>[movielens.py]"]
  node_download["Download helpers<br/>[download_utils.py]"]
  node_frameutils["DataFrame utilities<br/>[pandas_df_utils.py]"]
  node_splitters["Data splitters"]
end

subgraph group_models["Recommendation models"]
  node_sar["Single-node SAR<br/>[sar_singlenode.py]"]
  node_sarplus["Spark SAR+<br/>[SARPlus.py]"]
  node_ncf["Neural CF<br/>[ncf_singlenode.py]"]
  node_ncfdata["NCF dataset<br/>[dataset.py]"]
  node_sasrec["SASRec<br/>[model.py]"]
  node_modelportfolio["Algorithm portfolio"]
end

subgraph group_quality["Evaluation and tuning"]
  node_pythonmetrics["Python metrics"]
  node_sparkmetrics["Spark metrics"]
  node_tuning["Parameter tuning"]
  node_ncftraining["NCF tuning run<br/>[ncf_training.py]"]
  node_svdtraining["SVD tuning run<br/>[svd_training.py]"]
end

subgraph group_runtime["Operations and utilities"]
  node_operationalize["Operationalization"]
  node_utils["Shared utilities"]
end

node_researcher(("Researcher / developer"))

node_researcher -->|"prepares data"| node_dataset
node_dataset -->|"loads MovieLens"| node_movielens
node_movielens -->|"downloads data"| node_download
node_dataset -->|"splits data"| node_splitters
node_researcher -->|"builds model"| node_modelportfolio
node_modelportfolio -->|"includes SAR"| node_sar
node_modelportfolio -->|"includes Spark SAR"| node_sarplus
node_modelportfolio -->|"includes NCF"| node_ncf
node_modelportfolio -->|"includes sequential models"| node_sasrec
node_ncftraining -->|"constructs dataset"| node_ncfdata
node_ncftraining -->|"trains model"| node_ncf
node_researcher -->|"evaluates predictions"| node_pythonmetrics
node_researcher -->|"evaluates Spark models"| node_sparkmetrics
node_ncftraining -->|"scores validation"| node_pythonmetrics
node_svdtraining -->|"scores validation"| node_pythonmetrics
node_researcher -->|"tunes parameters"| node_tuning
node_researcher -->|"operationalizes model"| node_operationalize
node_dataset -->|"formats data"| node_frameutils
node_sar -->|"uses constants"| node_utils

click node_dataset "https://github.com/recommenders-team/recommenders/tree/main/recommenders/datasets"
click node_movielens "https://github.com/recommenders-team/recommenders/blob/main/recommenders/datasets/movielens.py"
click node_download "https://github.com/recommenders-team/recommenders/blob/main/recommenders/datasets/download_utils.py"
click node_frameutils "https://github.com/recommenders-team/recommenders/blob/main/recommenders/datasets/pandas_df_utils.py"
click node_splitters "https://github.com/recommenders-team/recommenders/tree/main/recommenders/datasets"
click node_sar "https://github.com/recommenders-team/recommenders/blob/main/recommenders/models/sar/sar_singlenode.py"
click node_sarplus "https://github.com/recommenders-team/recommenders/blob/main/contrib/sarplus/python/pysarplus/SARPlus.py"
click node_ncf "https://github.com/recommenders-team/recommenders/blob/main/recommenders/models/ncf/ncf_singlenode.py"
click node_ncfdata "https://github.com/recommenders-team/recommenders/blob/main/recommenders/models/ncf/dataset.py"
click node_sasrec "https://github.com/recommenders-team/recommenders/blob/main/recommenders/models/sasrec/model.py"
click node_modelportfolio "https://github.com/recommenders-team/recommenders/tree/main/recommenders/models"
click node_pythonmetrics "https://github.com/recommenders-team/recommenders/blob/main/recommenders/evaluation/python_evaluation.py"
click node_sparkmetrics "https://github.com/recommenders-team/recommenders/blob/main/recommenders/evaluation/spark_evaluation.py"
click node_tuning "https://github.com/recommenders-team/recommenders/tree/main/recommenders/tuning"
click node_ncftraining "https://github.com/recommenders-team/recommenders/blob/main/recommenders/tuning/nni/ncf_training.py"
click node_svdtraining "https://github.com/recommenders-team/recommenders/blob/main/recommenders/tuning/nni/svd_training.py"
click node_operationalize "https://github.com/recommenders-team/recommenders/tree/main/tools"
click node_utils "https://github.com/recommenders-team/recommenders/tree/main/recommenders/utils"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_dataset,node_movielens,node_download,node_frameutils,node_splitters toneBlue
class node_sar,node_sarplus,node_ncf,node_ncfdata,node_sasrec,node_modelportfolio toneAmber
class node_pythonmetrics,node_sparkmetrics,node_tuning,node_ncftraining,node_svdtraining toneMint
class node_operationalize,node_utils toneRose
class node_researcher toneIndigo
```

## Components

### Data preparation

- [Dataset loaders](https://github.com/recommenders-team/recommenders/tree/main/recommenders/datasets): `recommenders/datasets`
- [MovieLens loader](https://github.com/recommenders-team/recommenders/blob/main/recommenders/datasets/movielens.py): `recommenders/datasets/movielens.py`
- [Download helpers](https://github.com/recommenders-team/recommenders/blob/main/recommenders/datasets/download_utils.py): `recommenders/datasets/download_utils.py`
- [DataFrame utilities](https://github.com/recommenders-team/recommenders/blob/main/recommenders/datasets/pandas_df_utils.py): `recommenders/datasets/pandas_df_utils.py`
- [Data splitters](https://github.com/recommenders-team/recommenders/tree/main/recommenders/datasets): `recommenders/datasets`

### Recommendation models

- [Single-node SAR](https://github.com/recommenders-team/recommenders/blob/main/recommenders/models/sar/sar_singlenode.py): `recommenders/models/sar/sar_singlenode.py`
- [Spark SAR+](https://github.com/recommenders-team/recommenders/blob/main/contrib/sarplus/python/pysarplus/SARPlus.py): `contrib/sarplus/python/pysarplus/SARPlus.py`
- [Neural CF](https://github.com/recommenders-team/recommenders/blob/main/recommenders/models/ncf/ncf_singlenode.py): `recommenders/models/ncf/ncf_singlenode.py`
- [NCF dataset](https://github.com/recommenders-team/recommenders/blob/main/recommenders/models/ncf/dataset.py): `recommenders/models/ncf/dataset.py`
- [SASRec](https://github.com/recommenders-team/recommenders/blob/main/recommenders/models/sasrec/model.py): `recommenders/models/sasrec/model.py`
- [Algorithm portfolio](https://github.com/recommenders-team/recommenders/tree/main/recommenders/models): `recommenders/models`

### Evaluation and tuning

- [Python metrics](https://github.com/recommenders-team/recommenders/blob/main/recommenders/evaluation/python_evaluation.py): `recommenders/evaluation/python_evaluation.py`
- [Spark metrics](https://github.com/recommenders-team/recommenders/blob/main/recommenders/evaluation/spark_evaluation.py): `recommenders/evaluation/spark_evaluation.py`
- [Parameter tuning](https://github.com/recommenders-team/recommenders/tree/main/recommenders/tuning): `recommenders/tuning`
- [NCF tuning run](https://github.com/recommenders-team/recommenders/blob/main/recommenders/tuning/nni/ncf_training.py): `recommenders/tuning/nni/ncf_training.py`
- [SVD tuning run](https://github.com/recommenders-team/recommenders/blob/main/recommenders/tuning/nni/svd_training.py): `recommenders/tuning/nni/svd_training.py`

### Operations and utilities

- [Operationalization](https://github.com/recommenders-team/recommenders/tree/main/tools): `tools`
- [Shared utilities](https://github.com/recommenders-team/recommenders/tree/main/recommenders/utils): `recommenders/utils`

### Other components

- **Researcher / developer**

## Connections

- Researcher / developer → Dataset loaders: prepares data (evidence: `README.md`)
- Dataset loaders → MovieLens loader: loads MovieLens (evidence: `README.md`)
- MovieLens loader → Download helpers: downloads data (evidence: `recommenders/datasets/movielens.py`)
- Dataset loaders → Data splitters: splits data (evidence: `README.md`)
- Researcher / developer → Algorithm portfolio: builds model (evidence: `README.md`)
- Algorithm portfolio → Single-node SAR: includes SAR (evidence: `README.md`)
- Algorithm portfolio → Spark SAR+: includes Spark SAR (evidence: `README.md`)
- Algorithm portfolio → Neural CF: includes NCF (evidence: `README.md`)
- Algorithm portfolio → SASRec: includes sequential models (evidence: `README.md`)
- NCF tuning run → NCF dataset: constructs dataset (evidence: `recommenders/tuning/nni/ncf_training.py`)
- NCF tuning run → Neural CF: trains model (evidence: `recommenders/tuning/nni/ncf_training.py`)
- Researcher / developer → Python metrics: evaluates predictions (evidence: `README.md`)
- Researcher / developer → Spark metrics: evaluates Spark models (evidence: `README.md`)
- NCF tuning run → Python metrics: scores validation (evidence: `recommenders/tuning/nni/ncf_training.py`)
- SVD tuning run → Python metrics: scores validation (evidence: `recommenders/tuning/nni/svd_training.py`)
- Researcher / developer → Parameter tuning: tunes parameters (evidence: `README.md`)
- Researcher / developer → Operationalization: operationalizes model (evidence: `README.md`)
- Dataset loaders → DataFrame utilities: formats data (evidence: `recommenders/datasets/pandas_df_utils.py`)
- Single-node SAR → Shared utilities: uses constants (evidence: `recommenders/models/sar/sar_singlenode.py`)
