rtrec: Realtime Recommendation Library in Python
================================================
[](https://pypi.org/project/rtrec/)
[](https://pypi.org/project/rtrec/)
[](https://github.com/myui/rtrec/actions)
[](LICENSE.txt)
[](https://colab.research.google.com/github/myui/rtrec/blob/main/notebooks/quickstart_colab.ipynb)
A realtime recommendation system supporting online updates.
## Highlights
- ❇️ Supporting online updates.
- ⚡️ Fast implementation (>=190k samples/sec training on laptop).
- ◍ efficient sparse data support.
- 🕑 decaying weights of user-item interactions based on recency.
- 🔄 [Hybrid CF(Collaborative-Filtering)/CB(Content-based) model](https://github.com/myui/rtrec/blob/main/notebooks/h-and-m.ipynb) for cold-start users.
-  experimental [Rust implementation](https://github.com/myui/rtrec/tree/rust)
## Supported Recommendation Algorithims
- Sparse [SLIM](https://ieeexplore.ieee.org/document/6137254) with [time-weighted](https://dl.acm.org/doi/10.1145/1099554.1099689) interactions.
- [Factorization Machines](https://ieeexplore.ieee.org/document/5694074) using [LightFM](https://github.com/lyst/lightfm)
- Hybrid model of SLIM (CF) and Factorization Machines (CB). Based on the number of user-item interactions, balances prediction weights between CF and CB.
## Installation
```bash
# using pip
pip install rtrec
pip install rtrec[serving]
# using uv
uv add rtrec
uv sync --no-extra serving
uv add rtrec[serving]
uv sync --extra serving
```
## Usage
Find usages in [notebooks](https://github.com/myui/rtrec/tree/main/notebooks)/[examples](https://github.com/myui/rtrec/tree/main/examples).
### Examples using Raw-level APIs
```py
# Dataset consists of user, item, tstamp, rating
import time
current_unixtime = time.time()
interactions = [('user_1', 'item_1', current_unixtime, 5.0),
('user_2', 'item_2', current_unixtime, -2.0),
('user_2', 'item_1', current_unixtime, 3.0),
('user_2', 'item_4', current_unixtime, 3.0),
('user_1', 'item_3', current_unixtime, 4.0)]
# Fit SLIM model
from rtrec.models import SLIM
model = SLIM()
model.fit(interactions)
# can fit from streams using yield as follows:
def yield_interactions():
for interaction in interactions:
yield interaction
model.fit(yield_interactions())
# Recommend top-5 items for a user
recommendations = model.recommend('user_1', top_k=5)
assert recommendations == ["item_4", "item_2"]
```
### Examples using high level DataFrame APIs
```py
# load dataset
from rtrec.experiments.datasets import load_dataset
df = load_dataset(name='movielens_1m')
# Split data set by temporal user split
from rtrec.experiments.split import temporal_user_split
train_df, test_df = temporal_user_split(df)
# Initialize SLIM model with custom options
from rtrec.recommender import Recommender
from rtrec.models import SLIM
model = SLIM(min_value=0, max_value=15, decay_in_days=180, nn_feature_selection=50)
recommender = Recommender(model)
# Bulk fit
recommender.bulk_fit(train_df)
# Partial fit
from rtrec.experiments.split import temporal_split
test_df1, test_df2 = temporal_split(test_df, test_frac=0.5)
recommender.fit(test_df1, update_interaction=True, parallel=True)
# Evaluation
metrics = recommender.evaluate(test_df2, recommend_size=10, filter_interacted=True)
print(metrics)
# User to Item Recommendation
recommended = recommender.recommend(user=10, top_k=10, filter_interacted=True)
assert len(recommended) == 10
# Item to Item recommendation
similar_items = recommender.similar_items(query_items=[3,10], top_k=5)
assert len(similar_items) == 2
```
Raw data
{
"_id": null,
"home_page": null,
"name": "rtrec",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "machine learning, personalization, recommendation systems, recommender, recsys",
"author": null,
"author_email": "myui <myui@apache.org>",
"download_url": "https://files.pythonhosted.org/packages/56/a2/5870ae477eca217fe936b64e67dc8e08bb4151bd0119fe508d5f1e48189b/rtrec-0.2.7.tar.gz",
"platform": null,
"description": "rtrec: Realtime Recommendation Library in Python\n================================================\n\n[](https://pypi.org/project/rtrec/)\n[](https://pypi.org/project/rtrec/)\n[](https://github.com/myui/rtrec/actions)\n[](LICENSE.txt)\n[](https://colab.research.google.com/github/myui/rtrec/blob/main/notebooks/quickstart_colab.ipynb)\n\nA realtime recommendation system supporting online updates.\n\n## Highlights\n\n- \u2747\ufe0f Supporting online updates.\n- \u26a1\ufe0f Fast implementation (>=190k samples/sec training on laptop).\n- \u25cd efficient sparse data support.\n- \ud83d\udd51 decaying weights of user-item interactions based on recency.\n- \ud83d\udd04 [Hybrid CF(Collaborative-Filtering)/CB(Content-based) model](https://github.com/myui/rtrec/blob/main/notebooks/h-and-m.ipynb) for cold-start users.\n-  experimental [Rust implementation](https://github.com/myui/rtrec/tree/rust)\n\n\n## Supported Recommendation Algorithims\n\n- Sparse [SLIM](https://ieeexplore.ieee.org/document/6137254) with [time-weighted](https://dl.acm.org/doi/10.1145/1099554.1099689) interactions.\n- [Factorization Machines](https://ieeexplore.ieee.org/document/5694074) using [LightFM](https://github.com/lyst/lightfm)\n- Hybrid model of SLIM (CF) and Factorization Machines (CB). Based on the number of user-item interactions, balances prediction weights between CF and CB.\n\n## Installation\n\n```bash\n# using pip\npip install rtrec\npip install rtrec[serving]\n\n# using uv\nuv add rtrec\nuv sync --no-extra serving\n\nuv add rtrec[serving]\nuv sync --extra serving\n```\n\n## Usage\n\nFind usages in [notebooks](https://github.com/myui/rtrec/tree/main/notebooks)/[examples](https://github.com/myui/rtrec/tree/main/examples).\n\n### Examples using Raw-level APIs\n\n```py\n# Dataset consists of user, item, tstamp, rating\nimport time\ncurrent_unixtime = time.time()\ninteractions = [('user_1', 'item_1', current_unixtime, 5.0),\n ('user_2', 'item_2', current_unixtime, -2.0),\n ('user_2', 'item_1', current_unixtime, 3.0),\n ('user_2', 'item_4', current_unixtime, 3.0),\n ('user_1', 'item_3', current_unixtime, 4.0)]\n\n# Fit SLIM model\nfrom rtrec.models import SLIM\nmodel = SLIM()\nmodel.fit(interactions)\n\n# can fit from streams using yield as follows:\ndef yield_interactions():\n for interaction in interactions:\n yield interaction\nmodel.fit(yield_interactions())\n\n# Recommend top-5 items for a user\nrecommendations = model.recommend('user_1', top_k=5)\nassert recommendations == [\"item_4\", \"item_2\"]\n```\n\n### Examples using high level DataFrame APIs\n\n```py\n# load dataset\nfrom rtrec.experiments.datasets import load_dataset\ndf = load_dataset(name='movielens_1m')\n\n# Split data set by temporal user split\nfrom rtrec.experiments.split import temporal_user_split\ntrain_df, test_df = temporal_user_split(df)\n\n# Initialize SLIM model with custom options\nfrom rtrec.recommender import Recommender\nfrom rtrec.models import SLIM\nmodel = SLIM(min_value=0, max_value=15, decay_in_days=180, nn_feature_selection=50)\nrecommender = Recommender(model)\n\n# Bulk fit\nrecommender.bulk_fit(train_df)\n\n# Partial fit\nfrom rtrec.experiments.split import temporal_split\ntest_df1, test_df2 = temporal_split(test_df, test_frac=0.5)\n\nrecommender.fit(test_df1, update_interaction=True, parallel=True)\n\n# Evaluation\nmetrics = recommender.evaluate(test_df2, recommend_size=10, filter_interacted=True)\nprint(metrics)\n\n# User to Item Recommendation\nrecommended = recommender.recommend(user=10, top_k=10, filter_interacted=True)\nassert len(recommended) == 10\n\n# Item to Item recommendation\nsimilar_items = recommender.similar_items(query_items=[3,10], top_k=5)\nassert len(similar_items) == 2\n```",
"bugtrack_url": null,
"license": null,
"summary": "A realtime recommendation system supporting online updates",
"version": "0.2.7",
"project_urls": {
"homepage": "https://github.com/myui/rtrec",
"repository": "https://github.com/myui/rtrec"
},
"split_keywords": [
"machine learning",
" personalization",
" recommendation systems",
" recommender",
" recsys"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c6f0727fb8c313f09fe944ca2e69cba0bc2c5f3426c499ba2d885ca6562eb3cf",
"md5": "71f4acc7b257adaf164c76fad51dfd22",
"sha256": "a442ad2c2db0b6dc907205796dcbe96a4bcc79fed97656dfdc1eb49018164db5"
},
"downloads": -1,
"filename": "rtrec-0.2.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "71f4acc7b257adaf164c76fad51dfd22",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 60991,
"upload_time": "2025-07-29T08:24:50",
"upload_time_iso_8601": "2025-07-29T08:24:50.737274Z",
"url": "https://files.pythonhosted.org/packages/c6/f0/727fb8c313f09fe944ca2e69cba0bc2c5f3426c499ba2d885ca6562eb3cf/rtrec-0.2.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "56a25870ae477eca217fe936b64e67dc8e08bb4151bd0119fe508d5f1e48189b",
"md5": "904f5dcb02bc79d4d959badccbf233b3",
"sha256": "842ffc2e84942fda4041b3bdf0b70666890764e73e7f5b359d8f1968aabee60e"
},
"downloads": -1,
"filename": "rtrec-0.2.7.tar.gz",
"has_sig": false,
"md5_digest": "904f5dcb02bc79d4d959badccbf233b3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 75807,
"upload_time": "2025-07-29T08:24:51",
"upload_time_iso_8601": "2025-07-29T08:24:51.929393Z",
"url": "https://files.pythonhosted.org/packages/56/a2/5870ae477eca217fe936b64e67dc8e08bb4151bd0119fe508d5f1e48189b/rtrec-0.2.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-29 08:24:51",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "myui",
"github_project": "rtrec",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "rtrec"
}
JSON
