{"id":14155179,"url":"https://github.com/MobileTeleSystems/RecTools","last_synced_at":"2025-08-06T01:30:41.444Z","repository":{"id":49841319,"uuid":"513457910","full_name":"MobileTeleSystems/RecTools","owner":"MobileTeleSystems","description":"RecTools - library to build Recommendation Systems easier and faster than ever before","archived":false,"fork":false,"pushed_at":"2024-07-30T10:56:09.000Z","size":3775,"stargazers_count":263,"open_issues_count":40,"forks_count":33,"subscribers_count":7,"default_branch":"main","last_synced_at":"2024-07-30T12:42:00.182Z","etag":null,"topics":["deep-learning","machine-learning","personalization","recomendations","recommendation-algorithms","recommendation-engine","recommendation-system","recommender-system","recsys"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MobileTeleSystems.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.rst","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-07-13T09:24:15.000Z","updated_at":"2024-07-31T15:41:03.338Z","dependencies_parsed_at":"2023-09-28T21:27:30.310Z","dependency_job_id":"906b834a-3fcd-4746-bc0c-4aea1d25eb0a","html_url":"https://github.com/MobileTeleSystems/RecTools","commit_stats":{"total_commits":123,"total_committers":5,"mean_commits":24.6,"dds":"0.22764227642276424","last_synced_commit":"5bed13ce145a2f4fd05342f3ba3117b8ebf63359"},"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MobileTeleSystems%2FRecTools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MobileTeleSystems%2FRecTools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MobileTeleSystems%2FRecTools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MobileTeleSystems%2FRecTools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MobileTeleSystems","download_url":"https://codeload.github.com/MobileTeleSystems/RecTools/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":215735785,"owners_count":15923388,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["deep-learning","machine-learning","personalization","recomendations","recommendation-algorithms","recommendation-engine","recommendation-system","recommender-system","recsys"],"created_at":"2024-08-17T08:02:23.641Z","updated_at":"2025-08-06T01:30:41.435Z","avatar_url":"https://github.com/MobileTeleSystems.png","language":"Python","readme":"# RecTools\n\n[![Python versions](https://img.shields.io/pypi/pyversions/rectools.svg)](https://pypi.org/project/rectools)\n[![PyPI](https://img.shields.io/pypi/v/rectools.svg)](https://pypi.org/project/rectools)\n[![Docs](https://img.shields.io/github/actions/workflow/status/MobileTeleSystems/RecTools/publish.yml?label=docs)](https://rectools.readthedocs.io)\n\n[![License](https://img.shields.io/github/license/MobileTeleSystems/RecTools.svg)](https://github.com/MobileTeleSystems/RecTools/blob/main/LICENSE)\n[![Coverage](https://img.shields.io/codecov/c/github/MobileTeleSystems/RecTools.svg)](https://app.codecov.io/gh/MobileTeleSystems/RecTools)\n[![Tests](https://img.shields.io/github/actions/workflow/status/MobileTeleSystems/RecTools/test.yml?branch=main\u0026label=tests)](https://github.com/MobileTeleSystems/RecTools/actions/workflows/test.yml?query=branch%3Amain++)\n\n[![Contributors](https://img.shields.io/github/contributors/MobileTeleSystems/RecTools.svg)](https://github.com/MobileTeleSystems/RecTools/graphs/contributors)\n[![Downloads](https://static.pepy.tech/badge/rectools)](https://pepy.tech/project/rectools)\n[![Telegram](https://img.shields.io/badge/channel-telegram-blue)](https://t.me/RecTools_Support)\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://rectools.readthedocs.io/en/stable/\"\u003eDocumentation\u003c/a\u003e |\n  \u003ca href=\"https://github.com/MobileTeleSystems/RecTools/tree/main/examples\"\u003eExamples\u003c/a\u003e |\n    \u003ca href=\"https://github.com/MobileTeleSystems/RecTools/tree/main/examples/tutorials\"\u003eTutorials\u003c/a\u003e |\n  \u003ca href=\"https://github.com/MobileTeleSystems/RecTools/blob/main/CONTRIBUTING.rst\"\u003eContributing\u003c/a\u003e |\n  \u003ca href=\"https://github.com/MobileTeleSystems/RecTools/releases\"\u003eReleases\u003c/a\u003e |\n  \u003ca href=\"https://github.com/orgs/MobileTeleSystems/projects/1\"\u003eDevelopers Board\u003c/a\u003e\n\u003c/p\u003e\n\nRecTools is an easy-to-use Python library which makes the process of building recommender systems easier and\nfaster than ever before.\n\n## ✨ Highlights: HSTU model released! ✨\n\n**HSTU arhictecture from [\"Actions speak louder then words...\"](https://arxiv.org/abs/2402.17152) is now available in RecTools as `HSTUModel`:**\n- Fully compatible with our  `fit` / `recommend` paradigm and require NO special data processing\n- Supports context-aware recommendations in case Relative Time Bias is enabled\n- Supports all loss options, item embedding options, category features utilization and other common modular functionality of RecTools transformer models\n- In [HSTU tutorial](examples/tutorials/transformers_HSTU_tutorial.ipynb) we show that original metrics reported for HSTU on public Movielens datasets may actually be **underestimated**\n- Configurable, customizable, callback-friendly, checkpoints-included, logs-out-of-the-box, custom-validation-ready, multi-gpu-compatible! See  [Transformers Advanced Training User Guide](examples/tutorials/transformers_advanced_training_guide.ipynb) and [Transformers Customization Guide](examples/tutorials/transformers_customization_guide.ipynb)\n\nPlase note that we always compare the quality of our implementations to academic papers results. [Public benchmarks for transformer models SASRec and BERT4Rec](https://github.com/blondered/bert4rec_repro?tab=readme-ov-file#rectools-transformers-benchmark-results) show that RecTools implementations achieve highest scores on multiple datasets compared to other published results.\n\n\n## Get started\n\nPrepare data with\n\n```shell\nwget https://files.grouplens.org/datasets/movielens/ml-1m.zip\nunzip ml-1m.zip\n```\n\n```python\nimport pandas as pd\n    \nfrom rectools import Columns\nfrom rectools.dataset import Dataset\nfrom rectools.models import SASRecModel\n\n# Read the data\nratings = pd.read_csv(\n    \"ml-1m/ratings.dat\", \n    sep=\"::\",\n    engine=\"python\",  # Because of 2-chars separators\n    header=None,\n    names=[Columns.User, Columns.Item, Columns.Weight, Columns.Datetime],\n)\n    \n# Create dataset\ndataset = Dataset.construct(ratings)\n    \n# Fit model\nmodel = SASRecModel(n_factors=64, epochs=100, loss=\"sampled_softmax\")\nmodel.fit(dataset)\n\n# Make recommendations\nrecos = model.recommend(\n    users=ratings[Columns.User].unique(),\n    dataset=dataset,\n    k=10,\n    filter_viewed=True,\n)\n```\n\n## Installation\n\nRecTools is on PyPI, so you can use `pip` to install it.\n```\npip install rectools\n```\nThe default version doesn't contain all the dependencies, because some of them are needed only for specific functionality. Available user extensions are the following:\n\n- `lightfm`: adds wrapper for LightFM model,\n- `torch`: adds models based on neural nets,\n- `visuals`: adds visualization tools,\n- `nmslib`: adds fast ANN recommenders.\n\nInstall extension:\n```\npip install rectools[extension-name]\n```\n\nInstall all extensions:\n```\npip install rectools[all]\n```\n\n\n## Recommender Models\nThe table below lists recommender models that are available in RecTools.  \n\n| Model               | Type | Description (🎏 for user/item features, 🔆 for warm inference, ❄️ for cold inference support)                                                                               | Tutorials \u0026 Benchmarks |\n|---------------------|----|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------|\n| 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...\"](https://arxiv.org/pdf/2402.17152), combined with \"Shifted Sequence\" training objective as in original public benchmarks\u003cbr\u003e🎏                                    | 📓 [HSTU Theory \u0026 Practice](examples/tutorials/transformers_HSTU_tutorial.ipynb) \u003cbr\u003e  📕 [Transformers Theory \u0026 Practice](examples/tutorials/transformers_tutorial.ipynb)\u003cbr\u003e  📗 [Advanced training guide](examples/tutorials/transformers_advanced_training_guide.ipynb) \u003cbr\u003e 🚀 [Top performance on public datasets](examples/tutorials/transformers_HSTU_tutorial.ipynb)\n| SASRec              | Neural Network | `rectools.models.SASRecModel` - Transformer-based sequential model with unidirectional attention mechanism and \"Shifted Sequence\" training objective \u003cbr\u003e🎏                 | 📕 [Transformers Theory \u0026 Practice](examples/tutorials/transformers_tutorial.ipynb)\u003cbr\u003e  📗 [Advanced training guide](examples/tutorials/transformers_advanced_training_guide.ipynb) \u003cbr\u003e  📘 [Customization guide](examples/tutorials/transformers_customization_guide.ipynb) \u003cbr\u003e 🚀 [Top performance on public benchmarks](https://github.com/blondered/bert4rec_repro?tab=readme-ov-file#rectools-transformers-benchmark-results) |\n| BERT4Rec            | Neural Network | `rectools.models.BERT4RecModel` - Transformer-based sequential model with bidirectional attention mechanism and \"MLM\" (masked item) training objective \u003cbr\u003e🎏               | 📕 [Transformers Theory \u0026 Practice](examples/tutorials/transformers_tutorial.ipynb)\u003cbr\u003e  📗 [Advanced training guide](examples/tutorials/transformers_advanced_training_guide.ipynb) \u003cbr\u003e  📘 [Customization guide](examples/tutorials/transformers_customization_guide.ipynb) \u003cbr\u003e 🚀 [Top performance on public benchmarks](https://github.com/blondered/bert4rec_repro?tab=readme-ov-file#rectools-transformers-benchmark-results) |\n| [implicit](https://github.com/benfred/implicit) ALS Wrapper | Matrix Factorization | `rectools.models.ImplicitALSWrapperModel` - Alternating Least Squares Matrix Factorizattion algorithm for implicit feedback. \u003cbr\u003e🎏                                         | 📙 [Theory \u0026 Practice](https://rectools.readthedocs.io/en/latest/examples/tutorials/baselines_extended_tutorial.html#Implicit-ALS)\u003cbr\u003e 🚀 [50% boost to metrics with user \u0026 item features](examples/5_benchmark_iALS_with_features.ipynb) |\n| [implicit](https://github.com/benfred/implicit) BPR-MF Wrapper | Matrix Factorization | `rectools.models.ImplicitBPRWrapperModel` - Bayesian Personalized Ranking Matrix Factorization algorithm.                                                                   | 📙 [Theory \u0026 Practice](https://rectools.readthedocs.io/en/latest/examples/tutorials/baselines_extended_tutorial.html#Bayesian-Personalized-Ranking-Matrix-Factorization-(BPR-MF)) |\n| [implicit](https://github.com/benfred/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 \u0026 Practice](https://rectools.readthedocs.io/en/latest/examples/tutorials/baselines_extended_tutorial.html#ItemKNN) |\n| [LightFM](https://github.com/lyst/lightfm) Wrapper | Matrix Factorization | `rectools.models.LightFMWrapperModel` - Hybrid matrix factorization algorithm which utilises user and item features and supports a variety of losses.\u003cbr\u003e🎏 🔆 ❄️           | 📙 [Theory \u0026 Practice](https://rectools.readthedocs.io/en/latest/examples/tutorials/baselines_extended_tutorial.html#LightFM)\u003cbr\u003e🚀 [10-25 times faster inference with RecTools](examples/6_benchmark_lightfm_inference.ipynb)|\n| EASE                | Linear Autoencoder | `rectools.models.EASEModel` - Embarassingly Shallow Autoencoders implementation that explicitly calculates dense item-item similarity matrix                                | 📙 [Theory \u0026 Practice](https://rectools.readthedocs.io/en/latest/examples/tutorials/baselines_extended_tutorial.html#EASE) |\n| PureSVD             | Matrix Factorization | `rectools.models.PureSVDModel` - Truncated Singular Value Decomposition of user-item interactions matrix                                                                    | 📙 [Theory \u0026 Practice](https://rectools.readthedocs.io/en/latest/examples/tutorials/baselines_extended_tutorial.html#PureSVD) |\n| 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.\u003cbr\u003e🎏 🔆          | - |\n| Popular             | Heuristic | `rectools.models.PopularModel` - Classic baseline which computes popularity of items and also accepts params like time window and type of popularity computation.\u003cbr\u003e❄️     | - |\n| Popular in Category | Heuristic | `rectools.models.PopularInCategoryModel` - Model that computes poularity within category and applies mixing strategy to increase Diversity.\u003cbr\u003e❄️                           | - |\n| Random              |  Heuristic | `rectools.models.RandomModel` - Simple random algorithm useful to benchmark Novelty, Coverage, etc.\u003cbr\u003e❄️                                                                   | - |\n\n- All of the models follow the same interface. **No exceptions**\n- 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)`\n- Fitting any model is as simple as `model.fit(dataset)`\n- For getting recommendations `filter_viewed` and `items_to_recommend` options are available\n- For item-to-item recommendations use `recommend_to_items` method\n- For feeding user/item features to model just specify dataframes when constructing `Dataset`. [Check our example](examples/4_dataset_with_features.ipynb)\n- 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.**\n- 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](examples/9_model_configs_and_saving.ipynb)\n\n\n## Extended validation tools\n\n### `calc_metrics` for classification, ranking, \"beyond-accuracy\", DQ, popularity bias and between-model metrics\n\n\n[User guide](https://github.com/MobileTeleSystems/RecTools/blob/main/examples/3_metrics.ipynb) | [Documentation](https://rectools.readthedocs.io/en/stable/features.html#metrics)\n\n\n### `DebiasConfig` for debiased metrics calculation\n\n[User guide](https://github.com/MobileTeleSystems/RecTools/blob/main/examples/8_debiased_metrics.ipynb) | [Documentation](https://rectools.readthedocs.io/en/stable/api/rectools.metrics.debias.DebiasConfig.html)\n\n### `cross_validate` for model metrics comparison\n\n\n[User guide](https://github.com/MobileTeleSystems/RecTools/blob/main/examples/2_cross_validation.ipynb) \n\n\n### `VisualApp` for model recommendations comparison\n\n\u003cimg src=\"https://recsysart.ru/images/visual_app.gif\" width=500\u003e\n\n\n[Example](https://github.com/MobileTeleSystems/RecTools/blob/main/examples/7_visualization.ipynb) | [Demo](https://recsysart.ru/voila/) | [Documentation](https://rectools.readthedocs.io/en/stable/api/rectools.visuals.visual_app.VisualApp.html)\n\n\n\n### `MetricsApp` for metrics trade-off analysis\n\n\n\u003cimg src=\"https://recsysart.ru/images/metrics_app.gif\" width=600\u003e\n\n[Example](https://github.com/MobileTeleSystems/RecTools/blob/main/examples/2_cross_validation.ipynb) |\n[Documentation](https://rectools.readthedocs.io/en/stable/api/rectools.visuals.metrics_app.MetricsApp.html)\n\n\n## Contribution\n[Contributing guide](CONTRIBUTING.rst)\n\nTo install all requirements\n- you must have `python3` and `poetry` installed\n- make sure you have no active virtual environments (deactivate conda `base` if applicable)\n- run\n```\nmake install\n```\n\n\nFor autoformatting run \n```\nmake format\n```\n\nFor linters check run \n```\nmake lint\n```\n\nFor tests run \n```\nmake test\n```\n\nFor coverage run \n```\nmake coverage\n```\n\nTo remove virtual environment run\n```\nmake clean\n```\n\n## RecTools Team\n\n- [Emiliy Feldman](https://github.com/feldlime) [Maintainer]\n- [Daria Tikhonovich](https://github.com/blondered) [Maintainer]\n- [Andrey Semenov](https://github.com/In48semenov)\n- [Mike Sokolov](https://github.com/mikesokolovv)\n- [Maya Spirina](https://github.com/spirinamayya)\n- [Grigoriy Gusarov](https://github.com/Gooogr)\n- [Aki Ariga](https://github.com/chezou)\n- [Nikolay Undalov](https://github.com/nsundalov)\n- [Aleksey Kuzin](https://github.com/teodor-r)\n\nPrevious contributors: [Ildar Safilo](https://github.com/irsafilo) [ex-Maintainer], [Daniil Potapov](https://github.com/sharthZ23) [ex-Maintainer], [Alexander Butenko](https://github.com/iomallach), [Igor Belkov](https://github.com/OzmundSedler), [Artem Senin](https://github.com/artemseninhse), [Mikhail Khasykov](https://github.com/mkhasykov), [Julia Karamnova](https://github.com/JuliaKup), [Maxim Lukin](https://github.com/groundmax), [Yuri Ulianov](https://github.com/yukeeul), [Egor Kratkov](https://github.com/jegorus), [Azat Sibagatulin](https://github.com/azatnv), [Vadim Vetrov](https://github.com/Waujito)\n\n","funding_links":[],"categories":["recommender-system"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMobileTeleSystems%2FRecTools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FMobileTeleSystems%2FRecTools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMobileTeleSystems%2FRecTools/lists"}