Metadata-Version: 2.4
Name: freerec
Version: 0.9.7
Summary: PyTorch library for recommender systems
Project-URL: Homepage, https://github.com/MTandHJ/freerec
Author-email: MTandHJ <congxueric@gmail.com>
License-Expression: MIT
License-File: LICENSE
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.9
Requires-Dist: matplotlib>=3.5.0
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=1.5.0
Requires-Dist: polars>=1.9.0
Requires-Dist: prettytable>=3.4.1
Requires-Dist: pyyaml>=6.0
Requires-Dist: requests>=2.28.0
Requires-Dist: tensorboard>=2.10.0
Requires-Dist: tqdm>=4.64.0
Provides-Extra: all
Requires-Dist: einops>=0.6.0; extra == 'all'
Requires-Dist: scikit-learn>=1.0.0; extra == 'all'
Requires-Dist: torch-geometric>=2.4.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: pre-commit>=3.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: pydata-sphinx-theme>=0.15; extra == 'docs'
Requires-Dist: sphinx-copybutton>=0.5; extra == 'docs'
Requires-Dist: sphinx-intl>=2.0; extra == 'docs'
Requires-Dist: sphinx>=7.2; extra == 'docs'
Requires-Dist: sphinxcontrib-mermaid>=0.9; extra == 'docs'
Provides-Extra: graph
Requires-Dist: torch-geometric>=2.4.0; extra == 'graph'
Provides-Extra: metrics
Requires-Dist: scikit-learn>=1.0.0; extra == 'metrics'
Provides-Extra: nn
Requires-Dist: einops>=0.6.0; extra == 'nn'
Description-Content-Type: text/markdown



![](docs/src/logo.png)

<p align="center">
    <a href="https://pypi.org/project/freerec/"><img src="https://img.shields.io/pypi/v/freerec?color=blue" alt="PyPI"></a>
    <a href="https://pypi.org/project/freerec/"><img src="https://img.shields.io/pypi/pyversions/freerec" alt="Python"></a>
    <a href="https://github.com/MTandHJ/freerec/blob/master/LICENSE"><img src="https://img.shields.io/github/license/MTandHJ/freerec" alt="License"></a>
</p>

<p align="center">
    <a href="https://mtandhj.github.io/freerec/">Documentation</a> &bull;
    <a href="https://github.com/MTandHJ/RecBoard">RecBoard</a>
</p>

---

**FreeRec** is a PyTorch-based library for building, training, and evaluating recommendation systems. It provides modular components — data pipelines, model architectures, training loops, and evaluation metrics — so you can focus on your research instead of boilerplate.

## Key Features

- **Flexible data pipeline** built on `torchdata`, supporting field-level processing, k-core filtering, and multiple splitting strategies
- **Modular model architecture** with base classes for collaborative filtering, sequential recommendation, and CTR prediction
- **Built-in training loop** with distributed training (DDP), TensorBoard logging, and grid-search hyperparameter tuning
- **Standard evaluation metrics** including NDCG, Hit Rate, MRR, Recall, Precision, and AUC

## Installation

**Requirements:** Python >= 3.9 | [PyTorch >= 2.0](https://pytorch.org/)

```bash
# 1. Install PyTorch (choose the CUDA version that matches your environment)
#    See https://pytorch.org/get-started/locally/
pip install torch

# 2. Install FreeRec
pip install freerec

# 3. Install torchdata (handled automatically with --no-deps)
freerec setup
```

> [!NOTE]
> FreeRec relies on torchdata 0.7.0, as later releases no longer support the datapipe functionality.
> `freerec setup` installs it with `--no-deps` to avoid overriding your existing PyTorch installation.

### Optional dependencies

```bash
pip install freerec[graph]    # torch-geometric for graph-based models
pip install freerec[metrics]  # scikit-learn for additional metrics (e.g., ROC-AUC)
pip install freerec[nn]       # einops for attention modules
pip install freerec[all]      # all of the above
```

## Overview

### Data Pipeline

![](docs/src/pipeline.png)

### Training Flow

![](docs/src/flow.png)

For detailed usage, please refer to the [documentation](https://mtandhj.github.io/freerec/).

## References

- [TorchRec](https://github.com/pytorch/torchrec)
- [DeepCTR-Torch](https://github.com/shenweichen/DeepCTR-Torch)
- [FuxiCTR](https://github.com/xue-pai/FuxiCTR)
- [BARS](https://github.com/openbenchmark/BARS)
- [RecBole](https://github.com/RUCAIBox/RecBole)

## Acknowledgements

- Code annotation and documentation were written with the assistance of [Claude Code (Opus 4.6)](https://claude.ai/claude-code) by Anthropic.
