# 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://t.me/RecTools_Support)
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.
For more details, see the [Documentation](https://rectools.readthedocs.io/)
and [Tutorials](https://github.com/MobileTeleSystems/RecTools/tree/main/examples).
## 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 models. 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]
```
**Important:** If you're using `poetry` and you want to add `rectools` to your project, then you should either install `rectools` without `lightfm` extras or use `poetry==1.4.0` and add to your `poetry.toml` file the next lines:
```
[experimental]
new-installer = false
```
## Recommender Models
The table below lists recommender models that are available in RecTools.
| Model | Type | Description | Extra features |
|----|----|-----------|--------|
| [implicit](https://github.com/benfred/implicit) ALS Wrapper | Matrix Factorization | `rectools.models.ImplicitALSWrapperModel` - Alternating Least Squares Matrix Factorizattion algorithm for implicit feedback | Support for user/item features! [Check our boost to metrics](examples/5_benchmark_iALS_with_features.ipynb) |
| [implicit](https://github.com/benfred/implicit) ItemKNN Wrapper | Collaborative Filtering | `rectools.models.ImplicitItemKNNWrapperModel` - Algorithm that calculates item-item similarity matrix using distances between item vectors in user-item interactions matrix | - |
| [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 | 10-25 times faster inference! [Check our boost to inference](examples/6_benchmark_lightfm_inference.ipynb)|
| EASE | Collaborative Filtering | `rectools.models.EASEModel` - Embarassingly Shallow Autoencoders implementation that explicitly calculates dense item-item similarity matrix | - |
| PureSVD | Matrix Factorization | `rectools.models.PureSVDModel` - Truncated Singular Value Decomposition of user-item interactions matrix | - |
| 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 | Hyperparams (time window, pop computation) |
| Popular in Category | Heuristic | `rectools.models.PopularInCategoryModel` - Model that computes poularity within category and applies mixing strategy to increase Diversity | Hyperparams (time window, pop computation, mixing/ratio strategy) |
| 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 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)
## Contribution
[Contributing guide](CONTRIBUTING.rst)
To install all requirements
- you must have `python3` and `poetry==1.4.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)
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)
Raw data
{
"_id": null,
"home_page": "https://github.com/MobileTeleSystems/RecTools",
"name": "rectools",
"maintainer": "Emiliy Feldman",
"docs_url": null,
"requires_python": "<3.11,>=3.7.2",
"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/52/2a/0dbe7ce9a12512346a2f2da2884bb2abc34cba859062c724582e9b9a935f/rectools-0.5.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://t.me/RecTools_Support)\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\nFor more details, see the [Documentation](https://rectools.readthedocs.io/) \nand [Tutorials](https://github.com/MobileTeleSystems/RecTools/tree/main/examples).\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 models. 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**Important:** If you're using `poetry` and you want to add `rectools` to your project, then you should either install `rectools` without `lightfm` extras or use `poetry==1.4.0` and add to your `poetry.toml` file the next lines:\n```\n[experimental]\nnew-installer = false\n```\n\n## Recommender Models\nThe table below lists recommender models that are available in RecTools. \n\n| Model | Type | Description | Extra features |\n|----|----|-----------|--------|\n| [implicit](https://github.com/benfred/implicit) ALS Wrapper | Matrix Factorization | `rectools.models.ImplicitALSWrapperModel` - Alternating Least Squares Matrix Factorizattion algorithm for implicit feedback | Support for user/item features! [Check our boost to metrics](examples/5_benchmark_iALS_with_features.ipynb) |\n| [implicit](https://github.com/benfred/implicit) ItemKNN Wrapper | Collaborative Filtering | `rectools.models.ImplicitItemKNNWrapperModel` - Algorithm that calculates item-item similarity matrix using distances between item vectors in user-item interactions matrix | - |\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 | 10-25 times faster inference! [Check our boost to inference](examples/6_benchmark_lightfm_inference.ipynb)|\n| EASE | Collaborative Filtering | `rectools.models.EASEModel` - Embarassingly Shallow Autoencoders implementation that explicitly calculates dense item-item similarity matrix | - |\n| PureSVD | Matrix Factorization | `rectools.models.PureSVDModel` - Truncated Singular Value Decomposition of user-item interactions matrix | - |\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 | - |\n| Popular | Heuristic | `rectools.models.PopularModel` - Classic baseline which computes popularity of items | Hyperparams (time window, pop computation) |\n| Popular in Category | Heuristic | `rectools.models.PopularInCategoryModel` - Model that computes poularity within category and applies mixing strategy to increase Diversity | Hyperparams (time window, pop computation, mixing/ratio strategy) |\n| Random | Heuristic | `rectools.models.RandomModel` - Simple random algorithm useful to benchmark Novelty, Coverage, etc. | - |\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\n\n## Contribution\n[Contributing guide](CONTRIBUTING.rst)\n\nTo install all requirements\n- you must have `python3` and `poetry==1.4.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\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) \n\n\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "An easy-to-use Python library for building recommendation systems",
"version": "0.5.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": "d2cae87f7f58ed829e42b833c4ab3d6574728c2b55ac1fde5ecc5e8097f51d5d",
"md5": "94d78a88e68a859429912b06062a776f",
"sha256": "787428343746fa6ac83dae6b5da7f2e628dcd05562006b104aa12afae2422d3f"
},
"downloads": -1,
"filename": "rectools-0.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "94d78a88e68a859429912b06062a776f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.11,>=3.7.2",
"size": 115917,
"upload_time": "2024-03-22T13:51:54",
"upload_time_iso_8601": "2024-03-22T13:51:54.759700Z",
"url": "https://files.pythonhosted.org/packages/d2/ca/e87f7f58ed829e42b833c4ab3d6574728c2b55ac1fde5ecc5e8097f51d5d/rectools-0.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "522a0dbe7ce9a12512346a2f2da2884bb2abc34cba859062c724582e9b9a935f",
"md5": "0d6aa2828a766a251e235468b200e47c",
"sha256": "989235374217b704e96a756ed9e6295fd202ae5449993dd626b0ff22b79f9bb3"
},
"downloads": -1,
"filename": "rectools-0.5.0.tar.gz",
"has_sig": false,
"md5_digest": "0d6aa2828a766a251e235468b200e47c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.11,>=3.7.2",
"size": 75722,
"upload_time": "2024-03-22T13:51:56",
"upload_time_iso_8601": "2024-03-22T13:51:56.586763Z",
"url": "https://files.pythonhosted.org/packages/52/2a/0dbe7ce9a12512346a2f2da2884bb2abc34cba859062c724582e9b9a935f/rectools-0.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-22 13:51:56",
"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
