RecTools

Documentation | Examples | Tutorials | Contributing | Releases | Developers Board

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

✨ Highlights: Transformer models released! ✨

BERT4Rec and SASRec are now available in RecTools:

• Fully compatible with our fit / recommend paradigm and require NO special data processing
• Explicitly described in our Transformers Theory & Practice Tutorial: loss options, item embedding options, category features utilization and more!
• 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
• Public benchmarks which compare RecTools models to other open-source implementations following BERT4Rec replicability paper show that RecTools implementations achieve highest scores on multiple datasets: Performance on public transformers benchmarks

Get started

Prepare data with

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

import pandas as pd
from implicit.nearest_neighbours import TFIDFRecommender
    
from rectools import Columns
from rectools.dataset import Dataset
from rectools.models import ImplicitItemKNNWrapperModel

# 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 = ImplicitItemKNNWrapperModel(TFIDFRecommender(K=10))
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.

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.
See recommender baselines extended tutorial for deep dive into theory & practice of our supported models.

Model	Type	Description (🎏 for user/item features, 🔆 for warm inference, ❄️ for cold inference support)	Tutorials & Benchmarks
SASRec	Neural Network	rectools.models.SASRecModel - Transformer-based sequential model with unidirectional attention mechanism and "Shifted Sequence" training objective 🎏	📕 Transformers Theory & Practice 📗 Advanced training guide 📘 Customization guide 🚀 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 🎏	📕 Transformers Theory & Practice 📗 Advanced training guide 📘 Customization guide 🚀 Top performance on public benchmarks
implicit ALS Wrapper	Matrix Factorization	rectools.models.ImplicitALSWrapperModel - Alternating Least Squares Matrix Factorizattion algorithm for implicit feedback. 🎏	📙 Theory & Practice 🚀 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. 🎏 🔆 ❄️	📙 Theory & Practice 🚀 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. 🎏 🔆	-
Popular	Heuristic	rectools.models.PopularModel - Classic baseline which computes popularity of items and also accepts params like time window and type of popularity computation. ❄️	-
Popular in Category	Heuristic	rectools.models.PopularInCategoryModel - Model that computes poularity within category and applies mixing strategy to increase Diversity. ❄️	-
Random	Heuristic	rectools.models.RandomModel - Simple random algorithm useful to benchmark Novelty, Coverage, etc. ❄️	-

• 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

Extended validation tools

calc_metrics for classification, ranking, "beyond-accuracy", DQ, popularity bias and between-model metrics

User guide | Documentation

DebiasConfig for debiased metrics calculation

User guide | Documentation

cross_validate for model metrics comparison

User guide

VisualApp for model recommendations comparison

Example | Demo | Documentation

MetricsApp for metrics trade-off analysis

Example | Documentation

Contribution

Contributing guide

To install all requirements

• you must have python3 and poetry installed
• make sure you have no active virtual environments (deactivate conda base if applicable)
• run

make install

For autoformatting run

make format

For linters check run

make lint

For tests run

make test

For coverage run

make coverage

To remove virtual environment run

make clean

RecTools Team

• Emiliy Feldman [Maintainer]
• Daria Tikhonovich [Maintainer]
• Andrey Semenov
• Mike Sokolov
• Maya Spirina
• Grigoriy Gusarov
• Aki Ariga
• Nikolay Undalov

Previous contributors: Ildar Safilo [ex-Maintainer], Daniil Potapov [ex-Maintainer], Alexander Butenko, Igor Belkov, Artem Senin, Mikhail Khasykov, Julia Karamnova, Maxim Lukin, Yuri Ulianov, Egor Kratkov, Azat Sibagatulin, Vadim Vetrov