warprec 1.0.0__tar.gz

warprec-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Information Systems Lab @ Polytechnic University of Bari
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

warprec-1.0.0/PKG-INFO

@@ -0,0 +1,220 @@
+Metadata-Version: 2.3
+Name: warprec
+Version: 1.0.0
+Summary: Unifying Academic Rigor and Industrial Scale for Responsible, Reproducible, and Efficient Recommendation
+Author: MarcoWV
+Author-email: marco.avolio@wideverse.com
+Requires-Python: >=3.12,<3.13
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Provides-Extra: dashboard
+Provides-Extra: remote-io
+Provides-Extra: serving
+Requires-Dist: azure-identity (>=1.25.1,<2.0.0) ; extra == "remote-io"
+Requires-Dist: azure-storage-blob (>=12.26.0,<13.0.0) ; extra == "remote-io"
+Requires-Dist: codecarbon (>=3.0.0,<4.0.0) ; extra == "dashboard"
+Requires-Dist: fastapi (>=0.135.1,<0.136.0) ; extra == "serving"
+Requires-Dist: fastmcp (>=3.1.0,<4.0.0) ; extra == "serving"
+Requires-Dist: hyperopt (>=0.2.7,<0.3.0)
+Requires-Dist: loguru (>=0.7.3,<0.8.0)
+Requires-Dist: mlflow (>=2.22.0,<3.0.0) ; extra == "dashboard"
+Requires-Dist: narwhals (>=2.15.0,<3.0.0)
+Requires-Dist: numpy (>=2.2.2,<3.0.0)
+Requires-Dist: optuna (>=4.5.0,<5.0.0)
+Requires-Dist: pandas (>=2.2.3,<3.0.0)
+Requires-Dist: polars (>=1.36,<2.0)
+Requires-Dist: pydantic (>=2.10.6,<3.0.0)
+Requires-Dist: ray[data,serve,train,tune] (>=2.45.0,<3.0.0)
+Requires-Dist: scikit-learn (>=1.6.1,<2.0.0)
+Requires-Dist: scipy (>=1.15.1,<2.0.0)
+Requires-Dist: tabulate (>=0.9.0,<0.10.0)
+Requires-Dist: tensorboard (>=2.19.0,<3.0.0)
+Requires-Dist: tensorboardx (>=2.6.2.2,<3.0.0.0)
+Requires-Dist: torch (>=2.7.0,<3.0.0)
+Requires-Dist: torchmetrics (>=1.8.2,<2.0.0)
+Requires-Dist: types-pyyaml (>=6.0.12.20241230,<7.0.0.0)
+Requires-Dist: types-tabulate (>=0.9.0.20241207,<0.10.0.0)
+Requires-Dist: wandb (>=0.19.10,<0.20.0) ; extra == "dashboard"
+Description-Content-Type: text/markdown
+
+# 🚀 WarpRec
+
+[![GitHub release (latest by date)](https://img.shields.io/github/v/release/sisinflab/warprec)](https://github.com/sisinflab/warprec/releases)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.12](https://img.shields.io/badge/python-3.12-blue.svg)](https://www.python.org/downloads/release/python-3120/)
+[![Documentation Status](https://readthedocs.org/projects/warprec/badge/?version=latest)](https://warprec.readthedocs.io/en/latest/)
+[![PyTorch](https://img.shields.io/badge/PyTorch-2.7-ee4c2c?logo=pytorch&logoColor=white)](https://pytorch.org/)
+[![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)
+[![CodeCarbon](https://img.shields.io/badge/carbon%20tracked-CodeCarbon-brightgreen?logo=leaflet&logoColor=white)](https://codecarbon.io/)
+[![MCP Powered](https://img.shields.io/badge/MCP-powered-blueviolet?logo=anthropic&logoColor=white)](https://modelcontextprotocol.io/)
+[![GitHub Stars](https://img.shields.io/github/stars/sisinflab/warprec?style=social)](https://github.com/sisinflab/warprec)
+
+<p align="center">
+  <a href="https://warprec.readthedocs.io/en/latest/">
+    <img src="https://img.shields.io/badge/📖%20Read%20the%20Docs-warprec-blue?style=for-the-badge" alt="Read the Docs"/>
+  </a>
+</p>
+
+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
+
+<p align="center">
+  <img src="assets/architecture.png" alt="WarpRec Architecture" width="100%"/>
+</p>
+
+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)
+  - [📋 Prerequisites](#-prerequisites)
+  - [🛠️ Setup Guide](#️-setup-guide)
+- [🚂 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 and reproducible using **Conda**. This ensures that all dependencies and the Python environment are managed consistently. Environment is available both for CPU e GPU.
+
+### 📋 Prerequisites
+
+- **Git**: To clone the repository.
+- **Conda**: You need either [Anaconda](https://www.anaconda.com/) or [Miniconda](https://docs.conda.io/en/latest/miniconda.html) installed on your system.
+
+### 🛠️ Setup Guide
+
+Follow these steps to clone the project and set up the environment:
+
+1. **Clone the repository**
+   Open your terminal and clone the WarpRec repository:
+   ```bash
+   git clone <repository_url>
+   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
+    conda env create --file environment.gpu.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
+    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
+    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
+    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
+

warprec-1.0.0/README.md

@@ -0,0 +1,180 @@
+# 🚀 WarpRec
+
+[![GitHub release (latest by date)](https://img.shields.io/github/v/release/sisinflab/warprec)](https://github.com/sisinflab/warprec/releases)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.12](https://img.shields.io/badge/python-3.12-blue.svg)](https://www.python.org/downloads/release/python-3120/)
+[![Documentation Status](https://readthedocs.org/projects/warprec/badge/?version=latest)](https://warprec.readthedocs.io/en/latest/)
+[![PyTorch](https://img.shields.io/badge/PyTorch-2.7-ee4c2c?logo=pytorch&logoColor=white)](https://pytorch.org/)
+[![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)
+[![CodeCarbon](https://img.shields.io/badge/carbon%20tracked-CodeCarbon-brightgreen?logo=leaflet&logoColor=white)](https://codecarbon.io/)
+[![MCP Powered](https://img.shields.io/badge/MCP-powered-blueviolet?logo=anthropic&logoColor=white)](https://modelcontextprotocol.io/)
+[![GitHub Stars](https://img.shields.io/github/stars/sisinflab/warprec?style=social)](https://github.com/sisinflab/warprec)
+
+<p align="center">
+  <a href="https://warprec.readthedocs.io/en/latest/">
+    <img src="https://img.shields.io/badge/📖%20Read%20the%20Docs-warprec-blue?style=for-the-badge" alt="Read the Docs"/>
+  </a>
+</p>
+
+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
+
+<p align="center">
+  <img src="assets/architecture.png" alt="WarpRec Architecture" width="100%"/>
+</p>
+
+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)
+  - [📋 Prerequisites](#-prerequisites)
+  - [🛠️ Setup Guide](#️-setup-guide)
+- [🚂 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 and reproducible using **Conda**. This ensures that all dependencies and the Python environment are managed consistently. Environment is available both for CPU e GPU.
+
+### 📋 Prerequisites
+
+- **Git**: To clone the repository.
+- **Conda**: You need either [Anaconda](https://www.anaconda.com/) or [Miniconda](https://docs.conda.io/en/latest/miniconda.html) installed on your system.
+
+### 🛠️ Setup Guide
+
+Follow these steps to clone the project and set up the environment:
+
+1. **Clone the repository**
+   Open your terminal and clone the WarpRec repository:
+   ```bash
+   git clone <repository_url>
+   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
+    conda env create --file environment.gpu.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
+    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
+    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
+    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

warprec-1.0.0/pyproject.toml

@@ -0,0 +1,89 @@
+[tool.poetry]
+name = "warprec"
+version = "1.0.0"
+description = "Unifying Academic Rigor and Industrial Scale for Responsible, Reproducible, and Efficient Recommendation"
+authors = [
+    "MarcoWV <marco.avolio@wideverse.com>",
+    "potitoaghilar <potito.aghilar@wideverse.com>",
+    "SabeeenoGH <sabino.roccotelli@wideverse.com>",
+    "vitowalteranelli <vitowalter.anelli@poliba.it>",
+    "JTOVS <joseph.trotta@ovs.it>"
+]
+readme = "README.md"
+
+[tool.poetry.dependencies]
+python = "~3.12"
+pandas = "^2.2.3"
+scipy = "^1.15.1"
+numpy = "^2.2.2"
+pydantic = "^2.10.6"
+tabulate = "^0.9.0"
+scikit-learn = "^1.6.1"
+hyperopt = "^0.2.7"
+ray = {extras = ["data", "serve", "train", "tune"], version = "^2.45.0"}
+types-pyyaml = "^6.0.12.20241230"
+types-tabulate = "^0.9.0.20241207"
+loguru = "^0.7.3"
+tensorboard = "^2.19.0"
+tensorboardx = "^2.6.2.2"
+torch = "^2.7.0"
+torchmetrics = "^1.8.2"
+optuna = "^4.5.0"
+polars = "^1.36"
+narwhals = "^2.15.0"
+wandb = {version = "^0.19.10", optional = true}
+codecarbon = {version = "^3.0.0", optional = true}
+mlflow = {version = "^2.22.0", optional = true}
+azure-storage-blob = {version = "^12.26.0", optional = true}
+azure-identity = {version = "^1.25.1", optional = true}
+fastapi = {version = "^0.135.1", optional = true}
+fastmcp = {version = "^3.1.0", optional = true}
+
+
+[tool.poetry.group.dev.dependencies]
+pre-commit = "^4.1.0"
+pytest = "^8.3.4"
+ruff = "^0.9.3"
+pydoclint = "^0.6.0"
+mypy = "^1.14.1"
+pylint = "^3.3.3"
+bandit = "^1.8.2"
+nvitop = "^1.4.2"
+matplotlib = "^3.10.3"
+
+
+[tool.poetry.requires-plugins]
+poetry-plugin-export = ">=1.8"
+
+
+[tool.poetry.extras]
+dashboard = [
+    "wandb",
+    "codecarbon",
+    "mlflow",
+]
+remote-io = [
+    "azure-storage-blob",
+    "azure-identity",
+]
+serving = [
+    "fastapi",
+    "fastmcp",
+]
+
+
+[tool.semantic_release]
+version_toml = [
+    "pyproject.toml:tool.poetry.version",
+]
+branch = "main"
+changelog_file = "CHANGELOG.md"
+upload_to_repository = false
+upload_to_release = true
+commit_message = "chore(release): {version} [skip ci]"
+commit_author = "github-actions [bot] <github-actions[bot]@users.noreply.github.com>"
+
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"

warprec-1.0.0/warprec/__init__.py

@@ -0,0 +1,6 @@
+from . import data
+from . import evaluation
+from . import recommenders
+from . import utils
+
+__all__ = ["data", "evaluation", "recommenders", "utils"]

warprec-1.0.0/warprec/common/__init__.py

@@ -0,0 +1,8 @@
+from .initialize import initialize_datasets, dataset_preparation
+from .optimizers import standard_optimizer
+
+__all__ = [
+    "initialize_datasets",
+    "dataset_preparation",
+    "standard_optimizer",
+]