https://github.com/sisinflab/warprec
Unifying Academic Rigor and Industrial Scale for Responsible, Reproducible, and Efficient Recommendation
https://github.com/sisinflab/warprec
collaborative-filtering context-aware-recommendation deep-learning graph-neural-networks machine-learning python pytorch recommendation recommender-system sequential-recommendation
Last synced: 3 months ago
JSON representation
Unifying Academic Rigor and Industrial Scale for Responsible, Reproducible, and Efficient Recommendation
- Host: GitHub
- URL: https://github.com/sisinflab/warprec
- Owner: sisinflab
- License: mit
- Created: 2025-06-26T13:18:33.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2026-03-03T12:02:54.000Z (4 months ago)
- Last Synced: 2026-03-03T12:59:02.979Z (4 months ago)
- Topics: collaborative-filtering, context-aware-recommendation, deep-learning, graph-neural-networks, machine-learning, python, pytorch, recommendation, recommender-system, sequential-recommendation
- Language: Python
- Homepage: https://warprec.readthedocs.io/en/latest/index.html
- Size: 5.9 MB
- Stars: 8
- Watchers: 0
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: CODEOWNERS
Awesome Lists containing this project
README
# 🚀 WarpRec
[](https://github.com/sisinflab/warprec/releases)
[](https://pypi.org/project/warprec/)
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/release/python-3120/)
[](https://warprec.readthedocs.io/en/latest/)
[](https://pytorch.org/)
[](https://github.com/astral-sh/ruff)
[](https://codecarbon.io/)
[](https://modelcontextprotocol.io/)
[](https://github.com/sisinflab/warprec)
WarpRec is a flexible and efficient framework designed for building, training, and evaluating recommendation models. It supports a wide range of configurations, customizable pipelines, and powerful optimization tools to enhance model performance and usability.
WarpRec is designed for both beginners and experienced practitioners. For newcomers, it offers a simple and intuitive interface to explore and experiment with state-of-the-art recommendation models. For advanced users, WarpRec provides a modular and extensible architecture that allows rapid prototyping, complex experiment design, and fine-grained control over every step of the recommendation pipeline.
Whether you're learning how recommender systems work or conducting high-performance research and development, WarpRec offers the right tools to match your workflow.
## 🏗️ Architecture
WarpRec is built on **4 foundational pillars** — Scalability, Green AI, Agentic Readiness, and Scientific Rigor — and organized into **5 modular engines** that manage the end-to-end recommendation lifecycle:
1. **Reader** — Ingests user-item interactions and metadata from local or cloud storage via a backend-agnostic Narwhals abstraction layer.
2. **Data Engine** — Applies configurable filtering and splitting strategies to produce clean, leak-free train/validation/test sets.
3. **Recommendation Engine** — Trains and optimizes models using PyTorch, with seamless scaling from single-GPU to multi-node Ray clusters.
4. **Evaluation Engine** — Computes 40 GPU-accelerated metrics in a single pass with automated statistical significance testing.
5. **Writer** — Serializes results, checkpoints, and carbon reports to local or cloud storage.
An **Application Layer** exposes trained models through a REST API (FastAPI) and an MCP server for agentic AI workflows.
## 📚 Table of Contents
- [✨ Key Features](#-key-features)
- [⚙️ Installation](#️-installation)
- [🚀 Quick Install (PyPI)](#-quick-install-pypi)
- [📦 Install via Poetry](#-install-via-poetry)
- [🛠️ Development Setup (Conda)](#️-development-setup-conda)
- [🚂 Usage](#-usage)
- [🏋️ Training a model](#️-training-a-model)
- [✏️ Design a model](#️-design-a-model)
- [🔍 Evaluate a model](#-evaluate-a-model)
- [🧰 Makefile Commands](#-makefile-commands)
- [🤝 Contributing](#-contributing)
- [📜 License](#-license)
- [📖 Citation](#-citation)
- [📧 Contact](#-contact)
## ✨ Key Features
- **55 Built-in Algorithms**: WarpRec ships with 55 state-of-the-art recommendation models spanning 6 paradigms — Unpersonalized, Content-Based, Collaborative Filtering (e.g., `LightGCN`, `EASE`$^R$, `MultiVAE`), Context-Aware (e.g., `DeepFM`, `xDeepFM`), Sequential (e.g., `SASRec`, `BERT4Rec`, `GRU4Rec`), and Hybrid. All models are fully configurable and extend a standardized base class, making it easy to prototype custom architectures within the same pipeline.
- **Backend-Agnostic Data Engine**: Built on [Narwhals](https://narwhals-dev.github.io/narwhals/), WarpRec operates over Pandas, Polars, and Spark without code changes — enabling a true "write-once, run-anywhere" workflow from laptop to distributed cluster. Data ingestion supports both local filesystems and cloud object storage (Azure Blob Storage).
- **Comprehensive Data Processing**: The data module provides 13 filtering strategies (filter-by-rating, k-core, cold-start heuristics) and 6 splitting protocols (random/temporal Hold-Out, Leave-k-Out, Fixed Timestamp, k-fold Cross-Validation), for a total of 19 configurable strategies to ensure rigorous and reproducible experimental setups.
- **40 GPU-Accelerated Metrics**: The evaluation suite covers 40 metrics across 7 families — Accuracy, Rating, Coverage, Novelty, Diversity, Bias, and Fairness — including multi-objective metrics for simultaneous optimization of competing goals. All metrics are computed with full GPU acceleration for large-scale experiments.
- **Statistical Rigor**: WarpRec automates hypothesis testing with paired (Student's t-test, Wilcoxon signed-rank) and independent-group (Mann-Whitney U) tests, and applies multiple comparison corrections via **Bonferroni** and **FDR (Benjamini-Hochberg)** to prevent p-hacking and ensure statistically robust conclusions.
- **Distributed Training & HPO**: Seamless vertical and horizontal scaling from single-GPU to multi-node Ray clusters. Hyperparameter optimization supports Grid, Random, Bayesian, HyperOpt, Optuna, and BoHB strategies, with ASHA pruning and model-level early stopping to maximize computational efficiency.
- **Green AI & Carbon Tracking**: WarpRec is the first recommendation framework with native [CodeCarbon](https://codecarbon.io/) integration, automatically quantifying energy consumption and CO₂ emissions for every experiment and persisting carbon footprint reports alongside standard results.
- **Agentic AI via MCP**: WarpRec natively implements a [Model Context Protocol](https://modelcontextprotocol.io/) server (`infer-api/mcp_server.py`), exposing trained recommenders as callable tools within LLM and autonomous agent workflows — transforming the framework from a static predictor into an interactive, agent-ready component.
- **REST API & Model Serving**: Trained models are instantly deployable as RESTful microservices via the built-in FastAPI server (`infer-api/server.py`), decoupling the modeling core from serving infrastructure with zero additional engineering effort.
- **Experiment Tracking**: Native integrations with `TensorBoard`, `Weights & Biases`, and `MLflow` for real-time monitoring of metrics, training dynamics, and multi-run management.
- **Custom Pipelines & Callbacks**: Beyond the three standard pipelines (Training, Design, Evaluation), WarpRec exposes an event-driven Callback system for injecting custom logic at any stage — enabling complex experiments without modifying framework internals.
## ⚙️ Installation
WarpRec is designed to be easily installed via **pip** or via **Conda**. This ensures that all dependencies and the Python environment are managed consistently. Conda environment is available both for CPU and GPU.
### 🚀 Quick Install (PyPI)
The easiest way to get started is using pip:
```bash
pip install warprec
```
WarpRec provides extra dependencies for specific use cases:
| extra | usage |
|---|---|
| dashboard | Dashboard functionalities like MLflow and Weights & Biases. |
| remote-io | Remote communication with cloud services like Azure. |
| serving | Optional dependencies to serve your recommendation models. |
| all | All of the above. |
You can install them at any moment using the following command:
```bash
pip install "warprec[dashboard, remote-io]"
```
### 📦 Install via Poetry
If you use [Poetry](https://python-poetry.org/) for dependency management, you can easily install WarpRec and its dependencies directly from the source:
1. **Clone the repository**
Open your terminal and clone the WarpRec repository:
```bash
git clone
cd warprec
2. **Install the project**
```bash
poetry install
# Or you can install all extra dependencies
poetry install --extras all
### 🛠️ Development Setup (Conda)
If you want to contribute or need a specific environment (CPU/GPU), we recommend using Conda. The conda environment already contains all the extra dependencies:
1. **Clone the repository**
Open your terminal and clone the WarpRec repository:
```bash
git clone
cd warprec
```
2. **Create the Conda environment**
Use the provided environment.gpu.yml (or environment.cpu.yml) file to create the virtual environment. This will install Python 3.12 and the necessary core dependencies.
```bash
# For GPU support
conda env create --file environment.gpu.yml
# Or for CPU only
conda env create --file environment.cpu.yml
```
3. **Activate the environment:**
```bash
conda activate warprec
```
## 🚂 Usage
### 🏋️♂️ Training a model
To train a model, use the `train` pipeline. Here's an example:
1. Prepare a configuration file (e.g. `config/train_config.yml`) with details
about the model, dataset and training parameters.
2. Start a Ray HEAD node:
```bash
ray start --head
3. Run the following command:
```bash
# Running with pip
warprec -c config/train_config.yml -p train
# Or with cloned repo
python -m warprec.run -c config/train_config.yml -p train
This command starts the training process using the specified configuration file.
### ✏️ Design a model
To implement a custom model, WarpRec provides a dedicated design interface via the `design` pipeline. The recommended workflow is as follows:
1. Prepare a configuration file (e.g. `config/design_config.yml`) with details
about the custom models, dataset and training parameters.
2. Run the following command:
```bash
# Running with pip
warprec -c config/design_config.yml -p design
# Or with cloned repo
python -m warprec.run -c config/design_config.yml -p design
This command initializes a lightweight training pipeline, specifically intended for rapid prototyping and debugging of custom architectures within the framework.
### 🔍 Evaluate a model
To run only evaluation on a model, use the `eval` pipeline. Here's an example:
1. Prepare a configuration file (e.g. `config/eval_config.yml`) with details
about the model, dataset and training parameters.
2. Run the following command:
```bash
# Running with pip
warprec -c config/eval_config.yml -p eval
# Or with cloned repo
python -m warprec.run -c config/eval_config.yml -p eval
This command starts the evaluation process using the specified configuration file.
### 🧰 Makefile Commands
The project includes a Makefile to simplify common operations:
- 🧹 Run linting:
```bash
make lint
- 🧑🔬 Run tests:
```bash
make test
## 🤝 Contributing
We welcome contributions from the community! Whether you're fixing bugs, improving documentation, or proposing new features, your input is highly valued.
To get started:
1. Fork the repository and create a new branch for your feature or fix.
2. Follow the existing coding style and conventions.
3. Make sure the code passes all checks by running `make lint`.
4. Open a pull request with a clear description of your changes.
If you encounter any issues or have questions, feel free to open an issue in the Issues section of the repository.
## 📜 License
This project is licensed under the MIT License - see the LICENSE file for details.
## 📖 Citation
Citation details will be provided in an upcoming release. Stay tuned!
## 📧 Contact
For questions or suggestions, feel free to contact us at:
* **Marco Avolio** - marco.avolio@wideverse.com
* **Potito Aghilar** - potito.aghilar@wideverse.com
* **Sabino Roccotelli** - sabino.roccotelli@wideverse.com
* **Vito Walter Anelli** - vitowalter.anelli@poliba.it
* **Joseph Trotta** - joseph.trotta@ovs.it