# Easy Recommender
**English** | [日本語](README.ja.md)
⚠️ **This package is currently broken and under repair. Please do not use.** ⚠️
**This project only works with Python 3.11.11 because LightFM requires this specific version. Other versions are not supported.**
A simple and efficient recommendation system library using LightFM.
## Features
- Simple API for building recommendation systems
- Support for both implicit and explicit feedback
- Built on top of proven library (LightFM)
- Easy data preprocessing utilities
## Installation
```bash
pip install easy-recommender
```
## Quick Start
```python
from easy_recommender import recommend, process_df, build_feature_data
import pandas as pd
# Load your data
df = pd.read_csv('your_ratings.csv')
user_features = ['gender', 'age']
item_features = ['price', 'genre']
# Get recommendations
recommendations = recommend(
processed_df,
user_features,
item_features,
)
print(recommendations)
```
Higher values indicate items that are more recommended.
If you want to recommend users for items instead, please swap the user and item columns.
## Data Requirements
This library takes user behavior log CSV as an argument.
Behavior logs are records of users purchasing/viewing/liking item A.
Specifically, to use this library, you need CSV data in the following format:
- **CSV with headers**: Must include column names
- **Required columns**: `user_id` and `item_id` must be present
- **Feature columns**:
- User-related column names should be specified as `user_features` (list of strings)
- Item-related column names should be specified as `item_features` (list of strings)
- If you have columns that don't belong to either users or items, include them in `user_features`
- **Data quality**: Columns with many null or undefined values may affect recommendation accuracy. Please remove such columns in advance.
### Data Example
For example, the following data format is expected. Note that case sensitivity matters.
Also, there is no automatic conversion between numeric and string types. If you write rankings as "1", it's treated as a string. If categories are handled as numbers like 2,3, they are treated as numeric values, which may reduce recommendation accuracy.
```csv
user_id,item_id,gender,age,price,genre
1,101,M,25,1200,Action
1,102,M,25,800,Comedy
2,101,F,30,1200,Action
```
## Requirements
- Python =3.11.11
## License
MIT License
## References
This implementation is based on the approach described in:
https://zenn.dev/genda_jp/articles/2c2a1b5d185741
Raw data
{
"_id": null,
"home_page": null,
"name": "easy-recommender",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "recommendation, machine learning, collaborative filtering",
"author": "Your Name",
"author_email": "your.email@example.com",
"download_url": "https://files.pythonhosted.org/packages/53/d9/c4998987511120e8fef87456656e5462033bcddfc3ea28a2097b11e803c5/easy_recommender-0.1.3.tar.gz",
"platform": null,
"description": "# Easy Recommender\n\n**English** | [\u65e5\u672c\u8a9e](README.ja.md)\n\n\u26a0\ufe0f **This package is currently broken and under repair. Please do not use.** \u26a0\ufe0f\n\n**This project only works with Python 3.11.11 because LightFM requires this specific version. Other versions are not supported.**\n\nA simple and efficient recommendation system library using LightFM.\n\n## Features\n\n- Simple API for building recommendation systems\n- Support for both implicit and explicit feedback\n- Built on top of proven library (LightFM)\n- Easy data preprocessing utilities\n\n## Installation\n\n```bash\npip install easy-recommender\n```\n\n## Quick Start\n\n```python\nfrom easy_recommender import recommend, process_df, build_feature_data\nimport pandas as pd\n\n# Load your data\ndf = pd.read_csv('your_ratings.csv')\n\nuser_features = ['gender', 'age']\nitem_features = ['price', 'genre']\n\n# Get recommendations\nrecommendations = recommend(\n processed_df, \n user_features, \n item_features,\n)\n\nprint(recommendations)\n```\n\nHigher values indicate items that are more recommended.\n\nIf you want to recommend users for items instead, please swap the user and item columns.\n\n## Data Requirements\nThis library takes user behavior log CSV as an argument.\nBehavior logs are records of users purchasing/viewing/liking item A.\n\nSpecifically, to use this library, you need CSV data in the following format:\n\n- **CSV with headers**: Must include column names\n- **Required columns**: `user_id` and `item_id` must be present\n- **Feature columns**: \n - User-related column names should be specified as `user_features` (list of strings)\n - Item-related column names should be specified as `item_features` (list of strings)\n - If you have columns that don't belong to either users or items, include them in `user_features`\n- **Data quality**: Columns with many null or undefined values may affect recommendation accuracy. Please remove such columns in advance.\n\n### Data Example\nFor example, the following data format is expected. Note that case sensitivity matters.\nAlso, there is no automatic conversion between numeric and string types. If you write rankings as \"1\", it's treated as a string. If categories are handled as numbers like 2,3, they are treated as numeric values, which may reduce recommendation accuracy.\n\n```csv\nuser_id,item_id,gender,age,price,genre\n1,101,M,25,1200,Action\n1,102,M,25,800,Comedy\n2,101,F,30,1200,Action\n```\n\n## Requirements\n\n- Python =3.11.11\n\n## License\n\nMIT License\n\n## References\n\nThis implementation is based on the approach described in:\nhttps://zenn.dev/genda_jp/articles/2c2a1b5d185741\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A simple recommendation system using LightFM",
"version": "0.1.3",
"project_urls": {
"Homepage": "https://github.com/t-kabaya/easy-recommender",
"Repository": "https://github.com/t-kabaya/easy-recommender"
},
"split_keywords": [
"recommendation",
" machine learning",
" collaborative filtering"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "0c2f91b856873f46171bb84900818923109b66c65a7dde0b7e10508e4f84766a",
"md5": "74ecfa33a4a758abc0c05fcd2084bedb",
"sha256": "2129d3856f1331c85194913feb99e64e05e725d7f8f1cc3fecf8810a5672a9d8"
},
"downloads": -1,
"filename": "easy_recommender-0.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "74ecfa33a4a758abc0c05fcd2084bedb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 5662,
"upload_time": "2025-08-31T07:49:17",
"upload_time_iso_8601": "2025-08-31T07:49:17.848734Z",
"url": "https://files.pythonhosted.org/packages/0c/2f/91b856873f46171bb84900818923109b66c65a7dde0b7e10508e4f84766a/easy_recommender-0.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "53d9c4998987511120e8fef87456656e5462033bcddfc3ea28a2097b11e803c5",
"md5": "e2707553b5dcbdb9dccc6acd6b0116a7",
"sha256": "62ad74c1683ad58be787e4f8832796ad3036fce202fdddb3b5ad513df20affc2"
},
"downloads": -1,
"filename": "easy_recommender-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "e2707553b5dcbdb9dccc6acd6b0116a7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 5084,
"upload_time": "2025-08-31T07:49:19",
"upload_time_iso_8601": "2025-08-31T07:49:19.316168Z",
"url": "https://files.pythonhosted.org/packages/53/d9/c4998987511120e8fef87456656e5462033bcddfc3ea28a2097b11e803c5/easy_recommender-0.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-31 07:49:19",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "t-kabaya",
"github_project": "easy-recommender",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "easy-recommender"
}
JSON
