IRec is a config-driven PyTorch framework for reproducible research in sequential and graph-based recommendation.

Installation

Using uv (Recommended)

1. Create and activate a virtual environment:

   uv venv --python 3.12
   source ./.venv/bin/activate

2. Install dependencies:

   For development

   uv sync --all-extras --frozen

   For production

   uv sync --frozen

Using pip

1. Create and activate a virtual environment:

   python3 -m venv .venv
   source ./.venv/bin/activate

2. Install dependencies:

   For development:

   pip install -e ".[dev]"

   For production:

   pip install -e .

Preparing datasets

All pre-processed datasets used in our experiments are available for download from our cloud storage. This is the fastest way to get started.

• link

After downloading, extract the archives into the data directory.

Alternatively, you can process the raw data from scratch using the Jupyter notebooks provided in the notebooks directory. The notebooks will generate the required .txt data splits.

Model training

To train a model, simply run the following from the root directory:

train --params /path/to/config

The script has 1 input argument: params which is the path to the json file with model configuration. The example of such file can be found here. This directory contrains json files with model hyperparameters and data preparation instructions. It should contain the following keys:

-experiment_name Name of the experiment

-dataset Information about the dataset

-dataloader Settings for dataloader

-model Model hyperparameters

-optimizer Optimizer hyperparameters

-loss Naming of different loss components

-callbacks Different additional traning

-use_wandb Enable Weights & Biases logging for experiment tracking