# Overview
**KabirRec** is a Python recommendation service that uses **surprise** and **scikit-learn**.
It has three main services:
- Cold Start Recommendation: Recommends the most popular items
- Similar Items Recommendation: Recommends similar items to the item given
- User Specific Recommendation: Recommends the best items to a user based on their history.
# Getting started
Its easy to use each service, first you need to create the RecommendationService object. Then read your csv data. We use ml-100k which has user info, user ratings, item info. We need to specify the columns as well as each csv separators.
```
recommendation_service = RecommendationService()
recommendation_service.read_csv_data(
user_info_path="../dataset/ml-100k/u.user",
user_ratings_path="../dataset/ml-100k/u.data",
item_info_path="../dataset/ml-100k/u.item",
info_columns=["user_id", "age", "gender", "occupation", "zip_code"],
ratings_columns=["user_id", "item_id", "rating", "timestamp"],
item_columns=["movie_id", "movie_title", "release_date", "video_release_date", "imdb_url", "unknown",
"action", "adventure", "animation", "children's", "comedy", "crime", "documentary",
"drama", "fantasy", "film_noir", "horror", "musical", "mystery", "romance", "sci-fi",
"thriller", "war", "western"],
info_sep="|", ratings_sep="\t", item_sep="|"
)
```
Then you can call on generators for services to get the service object. First call the fit function and then you can use their prediction services.
## User Specific Example
```
user_specific = recommendation_service.user_specific_module(options={"verbose": True, "k": 26})
user_specific.fit(20, 30)
user_specific.draw_clusters_graph()
prediction_rating = user_specific.recommend(1, 4)
print(prediction_rating)
prediction_rating = user_specific.predict_rating(1, 1)
print(prediction_rating.est)
```
Output:
```
Fitting the algorithm...
Finding optimal cluster...
Optimal cluster k=23 found.
Clustering with k=23...
Clustering done.
Building tables...
Tables are built.
Fitting is done.
[(1189, 'Prefontaine (1997)', 5), (1500, 'Santa with Muscles (1996)', 5), (814, 'Great Day in Harlem, A (1994)', 5), (1536, 'Aiqing wansui (1994)', 5)]
3.603819651096398
```
## Similar Item Example
```
similar_items = recommendation_service.similar_items_module(options={"verbose": True})
similar_items.fit()
items = similar_items.recommend("Toy Story (1995)", k=5)
for movie in items:
print(movie)
```
Output:
```
Fitting the algorithm...
Estimating biases using als...
Computing the pearson_baseline similarity matrix...
Done computing similarity matrix.
Fitting is done.
Finding 5 nearest items...
5 nearest items found.
Beauty and the Beast (1991)
Raiders of the Lost Ark (1981)
That Thing You Do! (1996)
Lion King, The (1994)
Craft, The (1996)
```
## Cold Start Example
```
cold_start = recommendation_service.cold_start_module(options {"verbose": True})
cold_start.fit()
items = cold_start.recommend(5)
for movie in items:
print(movie)
```
Output:
```
Ranking items...
All items are ranked.
item_id rating
49 50 2541
99 100 2111
180 181 2032
257 258 1936
173 174 1786
```
## API Server
**/api_server** folder contains an API server designed to use Kabirrec as a live service. It can load database, fit the algorithm and use them live by sending HTTP request to it's different routes.
Each route takes a post request with a JSON object as it's options and responds a JSON object. There are lots of options that can be used to further optimize the algorithm to your own needs but if none is given, the default setting will be applied.
These routes and their JSON options are as follows:
Notes:
- All the routes begin with the server name:port and then the route
- All the routes require POST request.
- The default value is written in parentheses.
For configuring sim_options and bsl_options please check the following [link](https://surprise.readthedocs.io/en/stable/prediction_algorithms.html# "configuration options").
Routes and options:
- **/load-csv** : Load csv database (it should be in the format of MovieLens ml-100k)
- path: path of the database ("./dataset")
- name: path of the database ("ml-100k")
- url: path of the database (None)
- extract: path of the database (false)
- verbose: output logs (false)
returns JSON object {"message": "message content"}
- **/start-coldstart** : Start ColdStart module
- verbose: output logs (false)
returns JSON object {"message": "message content"}
- **/coldstart**: Use ColdStart module
- n: number of item recommendations (10)
- verbose: output logs (false)
returns JSON object {"items_list": [list of popular items]}
- **/start-similaritems** : Start SimilarItems module
- algo: path of the database ("knnbasic")
- k: The (max) number of neighbors to take into account for aggregation (40)
- min_k: The minimum number of neighbors to take into account for aggregation. If there are not enough neighbors, the prediction is set to the global mean of all ratings (1)
- sim_options: A dictionary of options for the similarity measure ({"name": "pearson_baseline", "user_based": False})
- bsl_options: A dictionary of options for the baseline estimates computation. Only when algo is KNNBaseline (empty dict {})
- verbose: output logs (false)
returns JSON object {"message": "message content"}
- **/similaritems** : Use SimilarItems module
- item_name: name of the item (must be given)
- n: number of item recommendations (10)
returns JSON object {"items_list": [list of popular items]}
- **/start-userspecific** : Start UserSpecific module
- k: number of the manual clusters, if given k_start and k_end are not taken into account (None)
- k_start: start number of the range to look for optimal cluster, range[k_start, k_end] (2)
- k_end: end number of the range to look for optimal cluster, range[k_start, k_end] (number of users / 2)
- verbose: output logs (false)
returns JSON object {"message": "message content"}
- **/userspecific** : Use UserSpecific module
- item_name: name of the user (must be given)
- n: number of item recommendations (10)
returns JSON object {"items_list": [list of popular items]}
## More Information
For more information on how to use the library, look at comments in the codes and Surprise library [website](https://surpriselib.com "surprise library website").
# Installation
You can use pip (you'll need a C compiler and numpy library):
```
$ pip install kabirrec
```
You can also clone the repo and build the library:
```
$ pip install numpy cython
$ git clone https://github.com/smohammadhejazi/recommendation-as-a-service
$ cd recommendation-as-a-service
$ python setup.py install
```
Raw data
{
"_id": null,
"home_page": "https://github.com/smohammadhejazi/recommendation-as-a-service",
"name": "kabirrec",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "recommendation-service,recommendation-system,recommender-system",
"author": "Seyyed Mohammad Hejazi Hoseini",
"author_email": "smohammadhejazi78@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/71/32/5d083957a8984a978136b36f366b7061ae488636fa0adc85ae9495018630/kabirrec-1.0.10.tar.gz",
"platform": null,
"description": "![KabirRec](https://drive.google.com/uc?export=view&id=1nBP3-89Hadr-BpFCgWeH_QNY8XhIr2f5 \"KabirRec\")\r\n\r\n# Overview\r\n**KabirRec** is a Python recommendation service that uses **surprise** and **scikit-learn**.\r\n\r\nIt has three main services:\r\n- Cold Start Recommendation: Recommends the most popular items\r\n- Similar Items Recommendation: Recommends similar items to the item given\r\n- User Specific Recommendation: Recommends the best items to a user based on their history.\r\n\r\n# Getting started\r\nIts easy to use each service, first you need to create the RecommendationService object. Then read your csv data. We use ml-100k which has user info, user ratings, item info. We need to specify the columns as well as each csv separators.\r\n```\r\nrecommendation_service = RecommendationService()\r\n\r\nrecommendation_service.read_csv_data(\r\n user_info_path=\"../dataset/ml-100k/u.user\",\r\n user_ratings_path=\"../dataset/ml-100k/u.data\",\r\n item_info_path=\"../dataset/ml-100k/u.item\",\r\n info_columns=[\"user_id\", \"age\", \"gender\", \"occupation\", \"zip_code\"],\r\n ratings_columns=[\"user_id\", \"item_id\", \"rating\", \"timestamp\"],\r\n item_columns=[\"movie_id\", \"movie_title\", \"release_date\", \"video_release_date\", \"imdb_url\", \"unknown\",\r\n \"action\", \"adventure\", \"animation\", \"children's\", \"comedy\", \"crime\", \"documentary\",\r\n \"drama\", \"fantasy\", \"film_noir\", \"horror\", \"musical\", \"mystery\", \"romance\", \"sci-fi\",\r\n \"thriller\", \"war\", \"western\"],\r\n info_sep=\"|\", ratings_sep=\"\\t\", item_sep=\"|\"\r\n)\r\n```\r\n\r\nThen you can call on generators for services to get the service object. First call the fit function and then you can use their prediction services.\r\n## User Specific Example\r\n```\r\nuser_specific = recommendation_service.user_specific_module(options={\"verbose\": True, \"k\": 26})\r\nuser_specific.fit(20, 30)\r\nuser_specific.draw_clusters_graph()\r\nprediction_rating = user_specific.recommend(1, 4)\r\nprint(prediction_rating)\r\nprediction_rating = user_specific.predict_rating(1, 1)\r\nprint(prediction_rating.est)\r\n```\r\nOutput:\r\n```\r\nFitting the algorithm...\r\nFinding optimal cluster...\r\nOptimal cluster k=23 found.\r\nClustering with k=23...\r\nClustering done.\r\nBuilding tables...\r\nTables are built.\r\nFitting is done.\r\n[(1189, 'Prefontaine (1997)', 5), (1500, 'Santa with Muscles (1996)', 5), (814, 'Great Day in Harlem, A (1994)', 5), (1536, 'Aiqing wansui (1994)', 5)]\r\n3.603819651096398\r\n```\r\n![Clusters Info](https://drive.google.com/uc?export=view&id=1ja8V-cmDBhkc4wJHSGR0-6shcHGgeppi \"Clusters Info\")\r\n## Similar Item Example\r\n```\r\nsimilar_items = recommendation_service.similar_items_module(options={\"verbose\": True})\r\nsimilar_items.fit()\r\nitems = similar_items.recommend(\"Toy Story (1995)\", k=5)\r\nfor movie in items:\r\n print(movie)\r\n```\r\nOutput:\r\n```\r\nFitting the algorithm...\r\nEstimating biases using als...\r\nComputing the pearson_baseline similarity matrix...\r\nDone computing similarity matrix.\r\nFitting is done.\r\nFinding 5 nearest items...\r\n5 nearest items found.\r\nBeauty and the Beast (1991)\r\nRaiders of the Lost Ark (1981)\r\nThat Thing You Do! (1996)\r\nLion King, The (1994)\r\nCraft, The (1996)\r\n```\r\n## Cold Start Example\r\n```\r\ncold_start = recommendation_service.cold_start_module(options {\"verbose\": True})\r\ncold_start.fit()\r\nitems = cold_start.recommend(5)\r\nfor movie in items:\r\n print(movie)\r\n```\r\nOutput:\r\n```\r\nRanking items...\r\nAll items are ranked.\r\n item_id rating\r\n49 50 2541\r\n99 100 2111\r\n180 181 2032\r\n257 258 1936\r\n173 174 1786\r\n```\r\n## API Server\r\n**/api_server** folder contains an API server designed to use Kabirrec as a live service. It can load database, fit the algorithm and use them live by sending HTTP request to it's different routes.\r\n\r\nEach route takes a post request with a JSON object as it's options and responds a JSON object. There are lots of options that can be used to further optimize the algorithm to your own needs but if none is given, the default setting will be applied.\r\n\r\nThese routes and their JSON options are as follows:\r\nNotes: \r\n- All the routes begin with the server name:port and then the route\r\n- All the routes require POST request.\r\n- The default value is written in parentheses.\r\n\r\nFor configuring sim_options and bsl_options please check the following [link](https://surprise.readthedocs.io/en/stable/prediction_algorithms.html# \"configuration options\").\r\n\r\nRoutes and options:\r\n- **/load-csv** : Load csv database (it should be in the format of MovieLens ml-100k)\r\n\t- path: path of the database (\"./dataset\")\r\n - name: path of the database (\"ml-100k\")\r\n\t- url: path of the database (None)\r\n\t- extract: path of the database (false)\r\n\t- verbose: output logs (false)\r\n \r\n\treturns JSON object {\"message\": \"message content\"}\r\n\r\n\r\n- **/start-coldstart** : Start ColdStart module\r\n\t- verbose: output logs (false)\r\n\r\n\treturns JSON object {\"message\": \"message content\"}\r\n\r\n\r\n- **/coldstart**: Use ColdStart module\r\n\t- n: number of item recommendations (10)\r\n\t- verbose: output logs (false)\r\n\r\n\treturns JSON object {\"items_list\": [list of popular items]}\r\n\r\n\r\n- **/start-similaritems** : Start SimilarItems module\r\n\t- algo: path of the database (\"knnbasic\")\r\n\t- k: The (max) number of neighbors to take into account for aggregation (40)\r\n\t- min_k: The minimum number of neighbors to take into account for aggregation. If there are not enough neighbors, the prediction is set to the global mean of all ratings (1)\r\n\t- sim_options: A dictionary of options for the similarity measure ({\"name\": \"pearson_baseline\", \"user_based\": False})\r\n\t- bsl_options: A dictionary of options for the baseline estimates computation. Only when algo is KNNBaseline (empty dict {})\r\n\t- verbose: output logs (false)\r\n\r\n\treturns JSON object {\"message\": \"message content\"}\r\n\r\n\r\n- **/similaritems** : Use SimilarItems module\r\n\t- item_name: name of the item (must be given)\r\n\t- n: number of item recommendations (10)\r\n\r\n\treturns JSON object {\"items_list\": [list of popular items]}\r\n\r\n\r\n- **/start-userspecific** : Start UserSpecific module\r\n\t- k: number of the manual clusters, if given k_start and k_end are not taken into account (None)\r\n\t- k_start: start number of the range to look for optimal cluster, range[k_start, k_end] (2)\r\n\t- k_end: end number of the range to look for optimal cluster, range[k_start, k_end] (number of users / 2)\r\n\t- verbose: output logs (false)\r\n\r\n\treturns JSON object {\"message\": \"message content\"}\r\n\r\n\r\n- **/userspecific** : Use UserSpecific module\r\n\t- item_name: name of the user (must be given)\r\n\t- n: number of item recommendations (10)\r\n\r\n\treturns JSON object {\"items_list\": [list of popular items]}\r\n\r\n\r\n## More Information\r\nFor more information on how to use the library, look at comments in the codes and Surprise library [website](https://surpriselib.com \"surprise library website\").\r\n\r\n# Installation\r\nYou can use pip (you'll need a C compiler and numpy library):\r\n```\r\n$ pip install kabirrec\r\n```\r\nYou can also clone the repo and build the library:\r\n```\r\n$ pip install numpy cython\r\n$ git clone https://github.com/smohammadhejazi/recommendation-as-a-service\r\n$ cd recommendation-as-a-service\r\n$ python setup.py install\r\n```\r\n\r\n\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A recommendation system with cold start, similar items and user specific recommendation",
"version": "1.0.10",
"split_keywords": [
"recommendation-service",
"recommendation-system",
"recommender-system"
],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "98b23af0d1e9d29be8797c719e80b9f7",
"sha256": "93a4025b173063f751d40644b3f580d2731ce093b4f23b8622227e570fe8d178"
},
"downloads": -1,
"filename": "kabirrec-1.0.10.tar.gz",
"has_sig": false,
"md5_digest": "98b23af0d1e9d29be8797c719e80b9f7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 5603794,
"upload_time": "2022-12-30T10:19:38",
"upload_time_iso_8601": "2022-12-30T10:19:38.865979Z",
"url": "https://files.pythonhosted.org/packages/71/32/5d083957a8984a978136b36f366b7061ae488636fa0adc85ae9495018630/kabirrec-1.0.10.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-12-30 10:19:38",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "smohammadhejazi",
"github_project": "recommendation-as-a-service",
"lcname": "kabirrec"
}
JSON
