{"id":46676915,"url":"https://github.com/sisinflab/warprec","last_synced_at":"2026-04-03T16:02:31.545Z","repository":{"id":338280278,"uuid":"1009030814","full_name":"sisinflab/warprec","owner":"sisinflab","description":"Unifying Academic Rigor and Industrial Scale for Responsible, Reproducible, and Efficient Recommendation","archived":false,"fork":false,"pushed_at":"2026-03-03T12:02:54.000Z","size":6185,"stargazers_count":8,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-03T12:59:02.979Z","etag":null,"topics":["collaborative-filtering","context-aware-recommendation","deep-learning","graph-neural-networks","machine-learning","python","pytorch","recommendation","recommender-system","sequential-recommendation"],"latest_commit_sha":null,"homepage":"https://warprec.readthedocs.io/en/latest/index.html","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sisinflab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-06-26T13:18:33.000Z","updated_at":"2026-03-03T10:17:42.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/sisinflab/warprec","commit_stats":null,"previous_names":["sisinflab/warprec"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/sisinflab/warprec","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sisinflab%2Fwarprec","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sisinflab%2Fwarprec/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sisinflab%2Fwarprec/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sisinflab%2Fwarprec/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sisinflab","download_url":"https://codeload.github.com/sisinflab/warprec/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sisinflab%2Fwarprec/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30276607,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-08T20:45:49.896Z","status":"ssl_error","status_checked_at":"2026-03-08T20:45:49.525Z","response_time":56,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["collaborative-filtering","context-aware-recommendation","deep-learning","graph-neural-networks","machine-learning","python","pytorch","recommendation","recommender-system","sequential-recommendation"],"created_at":"2026-03-08T23:07:28.561Z","updated_at":"2026-04-03T16:02:31.178Z","avatar_url":"https://github.com/sisinflab.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🚀 WarpRec\n\n[![GitHub release (latest by date)](https://img.shields.io/github/v/release/sisinflab/warprec)](https://github.com/sisinflab/warprec/releases)\n[![PyPI version](https://badge.fury.io/py/warprec.svg)](https://pypi.org/project/warprec/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Python 3.12](https://img.shields.io/badge/python-3.12-blue.svg)](https://www.python.org/downloads/release/python-3120/)\n[![Documentation Status](https://readthedocs.org/projects/warprec/badge/?version=latest)](https://warprec.readthedocs.io/en/latest/)\n[![PyTorch](https://img.shields.io/badge/PyTorch-2.7-ee4c2c?logo=pytorch\u0026logoColor=white)](https://pytorch.org/)\n[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)\n[![CodeCarbon](https://img.shields.io/badge/carbon%20tracked-CodeCarbon-brightgreen?logo=leaflet\u0026logoColor=white)](https://codecarbon.io/)\n[![MCP Powered](https://img.shields.io/badge/MCP-powered-blueviolet?logo=anthropic\u0026logoColor=white)](https://modelcontextprotocol.io/)\n[![GitHub Stars](https://img.shields.io/github/stars/sisinflab/warprec?style=social)](https://github.com/sisinflab/warprec)\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://warprec.readthedocs.io/en/latest/\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/📖%20Read%20the%20Docs-warprec-blue?style=for-the-badge\" alt=\"Read the Docs\"/\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\nWarpRec 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.\n\nWarpRec 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.\n\nWhether you're learning how recommender systems work or conducting high-performance research and development, WarpRec offers the right tools to match your workflow.\n\n## 🏗️ Architecture\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/architecture.png\" alt=\"WarpRec Architecture\" width=\"100%\"/\u003e\n\u003c/p\u003e\n\nWarpRec 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:\n\n1. **Reader** — Ingests user-item interactions and metadata from local or cloud storage via a backend-agnostic Narwhals abstraction layer.\n2. **Data Engine** — Applies configurable filtering and splitting strategies to produce clean, leak-free train/validation/test sets.\n3. **Recommendation Engine** — Trains and optimizes models using PyTorch, with seamless scaling from single-GPU to multi-node Ray clusters.\n4. **Evaluation Engine** — Computes 40 GPU-accelerated metrics in a single pass with automated statistical significance testing.\n5. **Writer** — Serializes results, checkpoints, and carbon reports to local or cloud storage.\n\nAn **Application Layer** exposes trained models through a REST API (FastAPI) and an MCP server for agentic AI workflows.\n\n## 📚 Table of Contents\n\n- [✨ Key Features](#-key-features)\n- [⚙️ Installation](#️-installation)\n  - [🚀 Quick Install (PyPI)](#-quick-install-pypi)\n  - [📦 Install via Poetry](#-install-via-poetry)\n  - [🛠️ Development Setup (Conda)](#️-development-setup-conda)\n- [🚂 Usage](#-usage)\n  - [🏋️ Training a model](#️-training-a-model)\n  - [✏️ Design a model](#️-design-a-model)\n  - [🔍 Evaluate a model](#-evaluate-a-model)\n  - [🧰 Makefile Commands](#-makefile-commands)\n- [🤝 Contributing](#-contributing)\n- [📜 License](#-license)\n- [📖 Citation](#-citation)\n- [📧 Contact](#-contact)\n\n## ✨ Key Features\n\n- **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.\n- **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).\n- **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.\n- **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.\n- **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.\n- **Distributed Training \u0026 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.\n- **Green AI \u0026 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.\n- **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.\n- **REST API \u0026 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.\n- **Experiment Tracking**: Native integrations with `TensorBoard`, `Weights \u0026 Biases`, and `MLflow` for real-time monitoring of metrics, training dynamics, and multi-run management.\n- **Custom Pipelines \u0026 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.\n\n## ⚙️ Installation\n\nWarpRec 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.\n\n### 🚀 Quick Install (PyPI)\nThe easiest way to get started is using pip:\n```bash\npip install warprec\n```\n\nWarpRec provides extra dependencies for specific use cases:\n\n| extra | usage |\n|---|---|\n| dashboard | Dashboard functionalities like MLflow and Weights \u0026 Biases. |\n| remote-io | Remote communication with cloud services like Azure. |\n| serving | Optional dependencies to serve your recommendation models. |\n| all | All of the above. |\n\nYou can install them at any moment using the following command:\n```bash\npip install \"warprec[dashboard, remote-io]\"\n```\n\n### 📦 Install via Poetry\n\nIf you use [Poetry](https://python-poetry.org/) for dependency management, you can easily install WarpRec and its dependencies directly from the source:\n\n1. **Clone the repository**\n   Open your terminal and clone the WarpRec repository:\n   ```bash\n   git clone \u003crepository_url\u003e\n   cd warprec\n\n2. **Install the project**\n    ```bash\n    poetry install\n    # Or you can install all extra dependencies\n    poetry install --extras all\n\n### 🛠️ Development Setup (Conda)\n\nIf you want to contribute or need a specific environment (CPU/GPU), we recommend using Conda. The conda environment already contains all the extra dependencies:\n\n1. **Clone the repository**\n   Open your terminal and clone the WarpRec repository:\n   ```bash\n   git clone \u003crepository_url\u003e\n   cd warprec\n   ```\n\n2. **Create the Conda environment**\n    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.\n    ```bash\n    # For GPU support\n    conda env create --file environment.gpu.yml\n    # Or for CPU only\n    conda env create --file environment.cpu.yml\n    ```\n\n3.  **Activate the environment:**\n\n    ```bash\n    conda activate warprec\n    ```\n\n## 🚂 Usage\n\n### 🏋️‍♂️ Training a model\n\nTo train a model, use the `train` pipeline. Here's an example:\n\n1. Prepare a configuration file (e.g. `config/train_config.yml`) with details\n    about the model, dataset and training parameters.\n2. Start a Ray HEAD node:\n    ```bash\n    ray start --head\n3. Run the following command:\n    ```bash\n    # Running with pip\n    warprec -c config/train_config.yml -p train\n    # Or with cloned repo\n    python -m warprec.run -c config/train_config.yml -p train\n\nThis command starts the training process using the specified configuration file.\n\n### ✏️ Design a model\n\nTo implement a custom model, WarpRec provides a dedicated design interface via the `design` pipeline. The recommended workflow is as follows:\n\n1. Prepare a configuration file (e.g. `config/design_config.yml`) with details\n    about the custom models, dataset and training parameters.\n2. Run the following command:\n    ```bash\n    # Running with pip\n    warprec -c config/design_config.yml -p design\n    # Or with cloned repo\n    python -m warprec.run -c config/design_config.yml -p design\n\nThis command initializes a lightweight training pipeline, specifically intended for rapid prototyping and debugging of custom architectures within the framework.\n\n### 🔍 Evaluate a model\n\nTo run only evaluation on a model, use the `eval` pipeline. Here's an example:\n\n1. Prepare a configuration file (e.g. `config/eval_config.yml`) with details\n    about the model, dataset and training parameters.\n2. Run the following command:\n    ```bash\n    # Running with pip\n    warprec -c config/eval_config.yml -p eval\n    # Or with cloned repo\n    python -m warprec.run -c config/eval_config.yml -p eval\n\nThis command starts the evaluation process using the specified configuration file.\n\n### 🧰 Makefile Commands\n\nThe project includes a Makefile to simplify common operations:\n\n- 🧹 Run linting:\n    ```bash\n    make lint\n- 🧑‍🔬 Run tests:\n    ```bash\n    make test\n\n## 🤝 Contributing\nWe welcome contributions from the community! Whether you're fixing bugs, improving documentation, or proposing new features, your input is highly valued.\n\nTo get started:\n\n1. Fork the repository and create a new branch for your feature or fix.\n2. Follow the existing coding style and conventions.\n3. Make sure the code passes all checks by running `make lint`.\n4. Open a pull request with a clear description of your changes.\n\nIf you encounter any issues or have questions, feel free to open an issue in the Issues section of the repository.\n\n## 📜 License\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## 📖 Citation\nCitation details will be provided in an upcoming release. Stay tuned!\n\n## 📧 Contact\nFor questions or suggestions, feel free to contact us at:\n\n* **Marco Avolio** - marco.avolio@wideverse.com\n* **Potito Aghilar** - potito.aghilar@wideverse.com\n* **Sabino Roccotelli** - sabino.roccotelli@wideverse.com\n* **Vito Walter Anelli** - vitowalter.anelli@poliba.it\n* **Joseph Trotta** - joseph.trotta@ovs.it\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsisinflab%2Fwarprec","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsisinflab%2Fwarprec","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsisinflab%2Fwarprec/lists"}