# RecTools
[](https://pypi.org/project/rectools)
[](https://pypi.org/project/rectools)
[](https://rectools.readthedocs.io)
[](https://github.com/MobileTeleSystems/RecTools/blob/main/LICENSE)
[](https://app.codecov.io/gh/MobileTeleSystems/RecTools)
[](https://github.com/MobileTeleSystems/RecTools/actions/workflows/test.yml?query=branch%3Amain++)
[](https://github.com/MobileTeleSystems/RecTools/graphs/contributors)
[](https://pepy.tech/project/rectools)
[](https://t.me/RecTools_Support)
<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 recommendation systems easier,
faster and more structured than ever before.
It includes built-in toolkits for data processing and metrics calculation,
a variety of recommender models, some wrappers for already existing implementations of popular algorithms
and model selection framework.
The aim is to collect ready-to-use solutions and best practices in one place to make processes
of creating your first MVP and deploying model to production as fast and easy as possible.
## 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 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](https://github.com/MobileTeleSystems/RecTools/blob/main/examples/tutorials/baselines_extended_tutorial.ipynb) 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 |
|----|----|---------|--------|
| [implicit](https://github.com/benfred/implicit) ALS Wrapper | Matrix Factorization | `rectools.models.ImplicitALSWrapperModel` - Alternating Least Squares Matrix Factorizattion algorithm for implicit feedback. <br>🎏| 📙 [Theory & Practice](https://rectools.readthedocs.io/en/latest/examples/tutorials/baselines_extended_tutorial.html#Implicit-ALS)<br> 🚀 [50% boost to metrics with user & item features](examples/5_benchmark_iALS_with_features.ipynb) |
| [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 & Practice](https://rectools.readthedocs.io/en/latest/examples/tutorials/baselines_extended_tutorial.html#ItemKNN) |
| [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.<br>🎏 🔆 ❄️| 📙 [Theory & Practice](https://rectools.readthedocs.io/en/latest/examples/tutorials/baselines_extended_tutorial.html#LightFM)<br>🚀 [10-25 times faster inference with RecTools](examples/6_benchmark_lightfm_inference.ipynb)|
| EASE | Linear Autoencoder | `rectools.models.EASEModel` - Embarassingly Shallow Autoencoders implementation that explicitly calculates dense item-item similarity matrix | 📙 [Theory & Practice](https://rectools.readthedocs.io/en/latest/examples/tutorials/baselines_extended_tutorial.html#EASE) |
| PureSVD | Matrix Factorization | `rectools.models.PureSVDModel` - Truncated Singular Value Decomposition of user-item interactions matrix | 📙 [Theory & Practice](https://rectools.readthedocs.io/en/latest/examples/tutorials/baselines_extended_tutorial.html#PureSVD) |
| 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 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 tutorial](examples/4_dataset_with_features.ipynb)
- 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.**
## Contribution
[Contributing guide](CONTRIBUTING.rst)
To install all requirements
- you must have `python>=3.8` and `poetry>=1.5.0` 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](https://github.com/feldlime) [Maintainer]
- [Daria Tikhonovich](https://github.com/blondered) [Maintainer]
- [Alexander Butenko](https://github.com/iomallach)
- [Andrey Semenov](https://github.com/In48semenov)
- [Mike Sokolov](https://github.com/mikesokolovv)
- [Maya Spirina](https://github.com/spirinamayya)
- [Grigoriy Gusarov](https://github.com/Gooogr)
Previous contributors: [Ildar Safilo](https://github.com/irsafilo) [ex-Maintainer], [Daniil Potapov](https://github.com/sharthZ23) [ex-Maintainer], [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)
Raw data
{
"_id": null,
"home_page": "https://github.com/MobileTeleSystems/RecTools",
"name": "RecTools",
"maintainer": "Emiliy Feldman",
"docs_url": null,
"requires_python": "<3.13,>=3.8.1",
"maintainer_email": "feldlime@yandex.ru",
"keywords": "recsys, recommendation systems, machine learning, AI, personalization",
"author": "Emiliy Feldman",
"author_email": "feldlime@yandex.ru",
"download_url": "https://files.pythonhosted.org/packages/35/52/10d9b08fd58bbeee7aae086c3eb543e5d6f2a049f509ff4b04a15c10466d/rectools-0.8.0.tar.gz",
"platform": null,
"description": "# RecTools\n\n[](https://pypi.org/project/rectools)\n[](https://pypi.org/project/rectools)\n[](https://rectools.readthedocs.io)\n\n[](https://github.com/MobileTeleSystems/RecTools/blob/main/LICENSE)\n[](https://app.codecov.io/gh/MobileTeleSystems/RecTools)\n[](https://github.com/MobileTeleSystems/RecTools/actions/workflows/test.yml?query=branch%3Amain++)\n\n[](https://github.com/MobileTeleSystems/RecTools/graphs/contributors)\n[](https://pepy.tech/project/rectools)\n[](https://t.me/RecTools_Support)\n\n<p align=\"center\">\n <a href=\"https://rectools.readthedocs.io/en/stable/\">Documentation</a> |\n <a href=\"https://github.com/MobileTeleSystems/RecTools/tree/main/examples\">Examples</a> |\n <a href=\"https://github.com/MobileTeleSystems/RecTools/tree/main/examples/tutorials\">Tutorials</a> |\n <a href=\"https://github.com/MobileTeleSystems/RecTools/blob/main/CONTRIBUTING.rst\">Contributing</a> |\n <a href=\"https://github.com/MobileTeleSystems/RecTools/releases\">Releases</a> |\n <a href=\"https://github.com/orgs/MobileTeleSystems/projects/1\">Developers Board</a>\n</p>\n\nRecTools is an easy-to-use Python library which makes the process of building recommendation systems easier, \nfaster and more structured than ever before.\nIt includes built-in toolkits for data processing and metrics calculation, \na variety of recommender models, some wrappers for already existing implementations of popular algorithms \nand model selection framework.\nThe aim is to collect ready-to-use solutions and best practices in one place to make processes \nof creating your first MVP and deploying model to production as fast and easy as possible.\n\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\nfrom implicit.nearest_neighbours import TFIDFRecommender\n \nfrom rectools import Columns\nfrom rectools.dataset import Dataset\nfrom rectools.models import ImplicitItemKNNWrapperModel\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 = ImplicitItemKNNWrapperModel(TFIDFRecommender(K=10))\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. \nSee [recommender baselines extended tutorial](https://github.com/MobileTeleSystems/RecTools/blob/main/examples/tutorials/baselines_extended_tutorial.ipynb) for deep dive into theory & practice of our supported models.\n\n| Model | Type | Description (\ud83c\udf8f for user/item features, \ud83d\udd06 for warm inference, \u2744\ufe0f for cold inference support) | Tutorials & Benchmarks |\n|----|----|---------|--------|\n| [implicit](https://github.com/benfred/implicit) ALS Wrapper | Matrix Factorization | `rectools.models.ImplicitALSWrapperModel` - Alternating Least Squares Matrix Factorizattion algorithm for implicit feedback. <br>\ud83c\udf8f| \ud83d\udcd9 [Theory & Practice](https://rectools.readthedocs.io/en/latest/examples/tutorials/baselines_extended_tutorial.html#Implicit-ALS)<br> \ud83d\ude80 [50% boost to metrics with user & item features](examples/5_benchmark_iALS_with_features.ipynb) |\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 | \ud83d\udcd9 [Theory & 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.<br>\ud83c\udf8f \ud83d\udd06 \u2744\ufe0f| \ud83d\udcd9 [Theory & Practice](https://rectools.readthedocs.io/en/latest/examples/tutorials/baselines_extended_tutorial.html#LightFM)<br>\ud83d\ude80 [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 | \ud83d\udcd9 [Theory & 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 | \ud83d\udcd9 [Theory & 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.<br>\ud83c\udf8f \ud83d\udd06 | - |\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.<br>\u2744\ufe0f| - |\n| Popular in Category | Heuristic | `rectools.models.PopularInCategoryModel` - Model that computes poularity within category and applies mixing strategy to increase Diversity.<br>\u2744\ufe0f| - |\n| Random | Heuristic | `rectools.models.RandomModel` - Simple random algorithm useful to benchmark Novelty, Coverage, etc.<br>\u2744\ufe0f| - |\n\n- All of the models follow the same interface. **No exceptions**\n- No need for manual creation of sparse matrixes 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 tutorial](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\n## Contribution\n[Contributing guide](CONTRIBUTING.rst)\n\nTo install all requirements\n- you must have `python>=3.8` and `poetry>=1.5.0` 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- [Alexander Butenko](https://github.com/iomallach)\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\nPrevious contributors: [Ildar Safilo](https://github.com/irsafilo) [ex-Maintainer], [Daniil Potapov](https://github.com/sharthZ23) [ex-Maintainer], [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)\n\n\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "An easy-to-use Python library for building recommendation systems",
"version": "0.8.0",
"project_urls": {
"Documentation": "https://rectools.readthedocs.io",
"Homepage": "https://github.com/MobileTeleSystems/RecTools",
"Repository": "https://github.com/MobileTeleSystems/RecTools"
},
"split_keywords": [
"recsys",
" recommendation systems",
" machine learning",
" ai",
" personalization"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f4e2ace94e7e696fb31879e2c4df33e73057318edae94c4f2d74916b2982a47d",
"md5": "035128fe82190fb794c8a80f909a1837",
"sha256": "7745a8b8604b1c9864a2d6598ce817b078a68ad8979c8ebe08f5ff45a7c5dd36"
},
"downloads": -1,
"filename": "rectools-0.8.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "035128fe82190fb794c8a80f909a1837",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.13,>=3.8.1",
"size": 143036,
"upload_time": "2024-08-28T14:58:57",
"upload_time_iso_8601": "2024-08-28T14:58:57.196546Z",
"url": "https://files.pythonhosted.org/packages/f4/e2/ace94e7e696fb31879e2c4df33e73057318edae94c4f2d74916b2982a47d/rectools-0.8.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "355210d9b08fd58bbeee7aae086c3eb543e5d6f2a049f509ff4b04a15c10466d",
"md5": "e1f8d345411651f45b66639e2b5acda4",
"sha256": "9b011ad58d2b54f06da5412eb494a97fa95102acf37ed32d127b274840241c59"
},
"downloads": -1,
"filename": "rectools-0.8.0.tar.gz",
"has_sig": false,
"md5_digest": "e1f8d345411651f45b66639e2b5acda4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.13,>=3.8.1",
"size": 95642,
"upload_time": "2024-08-28T14:58:58",
"upload_time_iso_8601": "2024-08-28T14:58:58.846968Z",
"url": "https://files.pythonhosted.org/packages/35/52/10d9b08fd58bbeee7aae086c3eb543e5d6f2a049f509ff4b04a15c10466d/rectools-0.8.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-28 14:58:58",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "MobileTeleSystems",
"github_project": "RecTools",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "rectools"
}
JSON
