RecTools

<p align="center"> <a href="https://rectools.readthedocs.io/en/stable/">Documentation</a> | <a href="https://github.com/MobileTeleSystems/RecTools/tree/main/examples">Examples</a> | <a href="https://github.com/MobileTeleSystems/RecTools/tree/main/examples/tutorials">Tutorials</a> | <a href="https://github.com/MobileTeleSystems/RecTools/blob/main/CONTRIBUTING.rst">Contributing</a> | <a href="https://github.com/MobileTeleSystems/RecTools/releases">Releases</a> | <a href="https://github.com/orgs/MobileTeleSystems/projects/1">Developers Board</a> </p>

RecTools is an easy-to-use Python library which makes the process of building recommender systems easier and
faster than ever before.

✨ Highlights: HSTU model released! ✨

HSTU arhictecture from "Actions speak louder then words..." is now available in RecTools as HSTUModel:

Fully compatible with our fit / recommend paradigm and require NO special data processing
Supports context-aware recommendations in case Relative Time Bias is enabled
Supports all loss options, item embedding options, category features utilization and other common modular functionality of RecTools transformer models
In HSTU tutorial we show that original metrics reported for HSTU on public Movielens datasets may actually be underestimated
Configurable, customizable, callback-friendly, checkpoints-included, logs-out-of-the-box, custom-validation-ready, multi-gpu-compatible! See Transformers Advanced Training User Guide and Transformers Customization Guide

✨ Highlights: RecTools framework at ACM RecSys'25 ✨

RecTools implementations are featured in ACM RecSys'25: "eSASRec: Enhancing Transformer-based Recommendations in a Modular Fashion":

The article presents a systematic benchmark of Transformer modifications using RecTools models. It offers a detailed evaluation of training objectives, Transformer architectures, loss functions, and negative sampling strategies in realistic, production-like settings
We introduce a new SOTA baseline, eSASRec, which combines SASRec’s training objective with LiGR Transformer layers and Sampled Softmax loss, forming a simple yet powerful recipe
eSASRec shows 23% boost over SOTA models, such as ActionPiece, on academic benchmarks
LiGR Transformer layers used in eSASRec are now in RecTools

Plase note that we always compare the quality of our implementations to academic papers results. Public benchmarks for transformer models SASRec and BERT4Rec show that RecTools implementations achieve highest scores on multiple datasets compared to other published results.

Get started

Prepare data with

shell
wget https://files.grouplens.org/datasets/movielens/ml-1m.zip
unzip ml-1m.zip

python
import pandas as pd
    
from rectools import Columns
from rectools.dataset import Dataset
from rectools.models import SASRecModel

# Read the data
ratings = pd.read_csv(
    "ml-1m/ratings.dat", 
    sep="::",
    engine="python",  # Because of 2-chars separators
    header=None,
    names=[Columns.User, Columns.Item, Columns.Weight, Columns.Datetime],
)
    
# Create dataset
dataset = Dataset.construct(ratings)
    
# Fit model
model = SASRecModel(n_factors=64, epochs=100, loss="sampled_softmax")
model.fit(dataset)

# Make recommendations
recos = model.recommend(
    users=ratings[Columns.User].unique(),
    dataset=dataset,
    k=10,
    filter_viewed=True,
)

Installation

RecTools is on PyPI, so you can use pip to install it.

pip install rectools

The default version doesn't contain all the dependencies, because some of them are needed only for specific functionality. Available user extensions are the following:

lightfm: adds wrapper for LightFM model,
torch: adds models based on neural nets,
visuals: adds visualization tools,
nmslib: adds fast ANN recommenders.
catboost: adds CatBoost as a reranker for CandidateRankingModel

Install extension:

pip install rectools[extension-name]

Install all extensions:

pip install rectools[all]

Recommender Models

The table below lists recommender models that are available in RecTools.

Model	Type	Description (🎏 for user/item features, 🔆 for warm inference, ❄️ for cold inference support)	Tutorials & Benchmarks
HSTU	Neural Network	`rectools.models.HSTUModel` - Sequential model with unidirectional pointwise aggregated attention mechanism, incorporating relative attention bias from positional and temporal information, introduced in "Actions speak louder then words...", combined with "Shifted Sequence" training objective as in original public benchmarks<br>🎏	📓 HSTU Theory & Practice <br> 📕 Transformers Theory & Practice<br> 📗 Advanced training guide <br> 🚀 Top performance on public datasets
SASRec	Neural Network	`rectools.models.SASRecModel` - Transformer-based sequential model with unidirectional attention mechanism and "Shifted Sequence" training objective. <br> For eSASRec variant specify `rectools.models.nn.transformers.ligr.LiGRLayers` for `transformer_layers_type` and `sampled_softmax` for `loss` <br>🎏	📕 Transformers Theory & Practice<br> 📗 Advanced training guide <br> 📘 Customization guide <br> 🚀 Top performance on public benchmarks
BERT4Rec	Neural Network	`rectools.models.BERT4RecModel` - Transformer-based sequential model with bidirectional attention mechanism and "MLM" (masked item) training objective <br>🎏	📕 Transformers Theory & Practice<br> 📗 Advanced training guide <br> 📘 Customization guide <br> 🚀 Top performance on public benchmarks
implicit ALS Wrapper	Matrix Factorization	`rectools.models.ImplicitALSWrapperModel` - Alternating Least Squares Matrix Factorizattion algorithm for implicit feedback. <br>🎏	📙 Theory & Practice<br> 🚀 50% boost to metrics with user & item features
implicit BPR-MF Wrapper	Matrix Factorization	`rectools.models.ImplicitBPRWrapperModel` - Bayesian Personalized Ranking Matrix Factorization algorithm.	📙 Theory & Practice
implicit ItemKNN Wrapper	Nearest Neighbours	`rectools.models.ImplicitItemKNNWrapperModel` - Algorithm that calculates item-item similarity matrix using distances between item vectors in user-item interactions matrix	📙 Theory & Practice
LightFM Wrapper	Matrix Factorization	`rectools.models.LightFMWrapperModel` - Hybrid matrix factorization algorithm which utilises user and item features and supports a variety of losses.<br>🎏 🔆 ❄️	📙 Theory & Practice<br>🚀 10-25 times faster inference with RecTools
EASE	Linear Autoencoder	`rectools.models.EASEModel` - Embarassingly Shallow Autoencoders implementation that explicitly calculates dense item-item similarity matrix	📙 Theory & Practice
PureSVD	Matrix Factorization	`rectools.models.PureSVDModel` - Truncated Singular Value Decomposition of user-item interactions matrix	📙 Theory & Practice
DSSM	Neural Network	`rectools.models.DSSMModel` - Two-tower Neural model that learns user and item embeddings utilising their explicit features and learning on triplet loss.<br>🎏 🔆	-
Popular	Heuristic	`rectools.models.PopularModel` - Classic baseline which computes popularity of items and also accepts params like time window and type of popularity computation.<br>❄️	-
Popular in Category	Heuristic	`rectools.models.PopularInCategoryModel` - Model that computes poularity within category and applies mixing strategy to increase Diversity.<br>❄️	-
Random	Heuristic	`rectools.models.RandomModel` - Simple random algorithm useful to benchmark Novelty, Coverage, etc.<br>❄️	-

All of the models follow the same interface. No exceptions
No need for manual creation of sparse matrixes, torch dataloaders or mapping ids. Preparing data for models is as simple as dataset = Dataset.construct(interactions_df)
Fitting any model is as simple as model.fit(dataset)
For getting recommendations filter_viewed and items_to_recommend options are available
For item-to-item recommendations use recommend_to_items method
For feeding user/item features to model just specify dataframes when constructing Dataset. Check our example
For warm / cold inference just provide all required ids in users or target_items parameters of recommend or recommend_to_items methods and make sure you have features in the dataset for warm users/items. Nothing else is needed, everything works out of the box.
Our models can be initialized from configs and have useful methods like get_config, get_params, save, load. Common functions model_from_config, model_from_params and load_model are available. Check our example