RecTools Documentation

RecTools is a Python library designed to make building recommendation systems faster and more structured.

Key features include:

• Unified Interface: A consistent API for various models including Implicit ALS, Implicit KNN, LightFM, SVD, DSSM, and baseline models (popularity and random).
• Model Validation: Built-in support for time-split methodology and a wide range of evaluation metrics.
• Advanced Metrics: Beyond standard accuracy, it supports Diversity, Novelty, and Serendipity.
• Performance Tools: Includes ANN (Approximate Nearest Neighbor) indexes for vector models and high-speed metric calculation utilities.

The MTS Kion dataset is an implicit, contextualized sequential dataset for movie recommendation. It consists of three primary files:

1. Interactions.csv: Contains user-item implicit interactions, including watch percentages and watch durations.
2. Users.csv: Contains user demographic information such as sex, age band, income level band, and kids flag.
3. Items.csv: Contains item meta-information including title, original title, year, genres, keywords, descriptions, countries, studios, actors, and directors.

Metadata for users and items is available in two versions:

• data_original: Original metadata in Russian.
• data_en: English version translated using Facebook FAIR’s WMT19 Ru->En model.

The rectools.dataset module provides the core abstractions for handling recommendation datasets within the RecTools framework. It is used to load, structure, and manage the data required for training and evaluating recommender models.

For specific implementation details on how to instantiate and manipulate datasets, refer to the detailed API documentation for the rectools.dataset module.

The HSTUModel implements the HSTU architecture. It is fully compatible with the standard fit / recommend paradigm and requires no special data processing.

Key features:

• Supports context-aware recommendations if Relative Time Bias is enabled.
• Supports modular functionality including all loss options, item embedding options, and category features utilization.
• Compatible with callbacks, checkpoints, logging, and multi-GPU training.

When defining features in RecTools, choose based on the nature of your data:

• SparseFeatures: Generally preferred for categorical features. Even for numerical values, you will often achieve better results by binarizing or discretizing them into sparse representations.
• Dense Features: Use these for specific exceptions, such as ALS (Alternating Least Squares) features.

In most recommendation scenarios, SparseFeatures is the better default choice.

A Dataset in RecTools is composed of several key tables that represent the recommendation environment:

• Interactions: The primary table storing the history of user-item interactions. It can include a column for interaction importance (weight) and timestamps. If no weight column is provided, all interactions are treated as equally important.
• User Features: Data describing users (e.g., age, gender) used to improve model performance.
• Item Features: Data describing items (e.g., category, price) used to improve model performance.
• Identifiers: Mappings between external and internal IDs.

These components are combined into a Dataset object, which is the central entity used to build models and infer recommendations.

RecTools provides model wrappers that offer several advantages over using raw models:

• Unified Interface: All wrappers share a consistent set of parameters, making them easier to use interchangeably.
• Extended Functionality: Wrappers include built-in support for advanced recommendation logic, such as:
  • Filtering out items a user has already seen.
  • Implementing whitelists.
  • Managing features in ALS and I2I (Item-to-Item) models.
• Standardized Output: They provide a unified output format that is directly compatible with RecTools metric calculation functions.
• Performance: Some wrappers are optimized to speed up the execution of specific models.

RecTools categorizes users and items based on their presence in training data and feature availability. This concept determines how models handle personalization:

Key Behaviors:

• All models can generate recommendations for hot users/items.
• If a model is designed to handle cold entities but not specifically warm ones, it will treat warm entities as cold (meaning no personalization is expected).

RecTools uses a fixed set of column names to avoid constant mapping between your data and the library's internal logic. You must rename your input data columns to match these exact names:

• user_id: Unique identifier for the user.
• item_id: Unique identifier for the item.
• weight: Numerical value representing the importance of the interaction.
• datetime: Date and time of the interaction.
• rank: The rank of a recommendation according to its score.
• score: Numeric value estimating the quality of a recommendation.

Recommendation systems require a mapping between external IDs (from your data sources) and internal IDs (used in the interaction matrix).

RecTools manages this mapping automatically.

• External IDs: Can be any unique hashable values.
• Internal IDs: Always integers ranging from 0 to n_objects-1.

Every user and item must have a unique ID to be processed correctly.

The Recommendation table contains the generated recommendations for each user.

• It has a fixed set of columns, though the schema varies depending on whether you are performing i2i (item-to-item) or u2i (user-to-item) recommendations.
• This table is the standard input for calculating recommendation metrics.