Use new recommendation endpoints

Author: OndraFiedler

README.rst

@@ -32,10 +32,10 @@ Basic example
 
     from recombee_api_client.api_client import RecombeeClient
     from recombee_api_client.exceptions import APIException
-    from recombee_api_client.api_requests import AddPurchase, UserBasedRecommendation, Batch
+    from recombee_api_client.api_requests import AddPurchase, RecommendItemsToUser, Batch
     import random
 
-    client = RecombeeClient('client-test', 'jGGQ6ZKa8rQ1zTAyxTc0EMn55YPF7FJLUtaMLhbsGxmvwxgTwXYqmUk5xVZFw98L')
+    client = RecombeeClient('--my-database-id--', '--my-secret-token--'')
 
     #Generate some random purchases of items by users
     PROBABILITY_PURCHASED = 0.1
@@ -55,29 +55,29 @@ Basic example
         client.send(Batch(purchase_requests))
 
         # Get recommendations for user 'user-25'
-        recommended = client.send(UserBasedRecommendation('user-25', 5))
+        recommended = client.send(RecommendItemsToUser('user-25', 5))
         print("Recommended items: %s" % recommended)
 
     except APIException as e:
         print(e)
 
 
+
 ---------------------
 Using property values
 ---------------------
 
 .. code-block:: python
 
-
     from recombee_api_client.api_client import RecombeeClient
     from recombee_api_client.api_requests import AddItemProperty, SetItemValues, AddPurchase
-    from recombee_api_client.api_requests import ItemBasedRecommendation, Batch, ResetDatabase
+    from recombee_api_client.api_requests import RecommendItemsToItem, Batch, ResetDatabase
     import random
 
     NUM = 100
     PROBABILITY_PURCHASED = 0.1
 
-    client = RecombeeClient('client-test', 'jGGQ6ZKa8rQ1zTAyxTc0EMn55YPF7FJLUtaMLhbsGxmvwxgTwXYqmUk5xVZFw98L')
+    client = RecombeeClient('--my-database-id--', '--my-secret-token--'')
 
     #Clear the entire database
     client.send(ResetDatabase())
@@ -124,23 +124,21 @@ Using property values
     client.send(Batch(requests))
 
     # Get 5 recommendations for user-42, who is currently viewing computer-6
-    recommended = client.send(ItemBasedRecommendation('computer-6', 5, target_user_id='user-42'))
+    recommended = client.send(RecommendItemsToItem('computer-6', 'user-42', 5))
     print("Recommended items: %s" % recommended)
 
-    # Get 5 recommendations for user-42, but recommend only computers that
-    # have at least 3 cores
+    # Recommend only computers that have at least 3 cores
     recommended = client.send(
-        ItemBasedRecommendation('computer-6', 5, target_user_id='user-42', filter="'num-cores'>=3")
+        RecommendItemsToItem('computer-6', 'user-42', 5, filter="'num-cores'>=3")
     )
     print("Recommended items with at least 3 processor cores: %s" % recommended)
 
-    # Get 5 recommendations for user-42, but recommend only items that
-    # are more expensive then currently viewed item (up-sell)
+    # Recommend only items that are more expensive then currently viewed item (up-sell)
     recommended = client.send(
-        ItemBasedRecommendation('computer-6', 5, target_user_id='user-42', filter="'price' > context_item[\"price\"]")
+        RecommendItemsToItem('computer-6', 'user-42', 5, filter="'price' > context_item[\"price\"]")
     )
     print("Recommended up-sell items: %s" % recommended)
-  
+
 ------------------
 Exception handling
 ------------------
@@ -155,11 +153,11 @@ Example:
 
   try:
     recommended = client.send(
-    ItemBasedRecommendation('computer-6', 5,target_user_id='user-42', filter="'price' > context_item[\"price\"]")
+        RecommendItemsToItem('computer-6', 'user-42', 5, filter="'price' > context_item[\"price\"]")
     )
   except ResponseException as e:
     #Handle errorneous request => use fallback
   except ApiTimeoutException as e:
     #Handle timeout => use fallback
   except APIException as e:
-    #APIException is parent of both ResponseException and ApiTimeoutException
+    #APIException is parent of both ResponseException and ApiTimeoutException

recombee_api_client/api_client.py

@@ -63,7 +63,7 @@ def send(self, request):
 
     @staticmethod
     def __get_http_headers(additional_headers=None):
-        headers = {'User-Agent': 'recombee-python-api-client/1.6.0'}
+        headers = {'User-Agent': 'recombee-python-api-client/2.0.0'}
         if additional_headers:
             headers.update(additional_headers)
         return headers

recombee_api_client/api_requests/item_based_recommendation.py

@@ -5,6 +5,8 @@
 
 class ItemBasedRecommendation(Request):
     """
+    Deprecated since version 2.0.0. Use RecommendItemsToItem request instead.
+    
     Recommends set of items that are somehow related to one given item, *X*. Typical scenario for using item-based recommendation is when user *A* is viewing *X*. Then you may display items to the user that he might be also interested in. Item-recommendation request gives you Top-N such items, optionally taking the target user *A* into account.
     
      It is also possible to use POST HTTP method (for example in case of very long ReQL filter) - query parameters then become body parameters.

recombee_api_client/api_requests/recommend_items_to_item.py

@@ -5,8 +5,6 @@
 
 class RecommendItemsToItem(Request):
     """
-    This feature is currently in beta.
-    
     Recommends set of items that are somehow related to one given item, *X*. Typical scenario  is when user *A* is viewing *X*. Then you may display items to the user that he might be also interested in. Recommend items to item request gives you Top-N such items, optionally taking the target user *A* into account.
     
     It is also possible to use POST HTTP method (for example in case of very long ReQL filter) - query parameters then become body parameters.
@@ -41,9 +39,9 @@ def __init__(self, item_id, target_user_id, count, user_impact=DEFAULT, filter=D
         
         Do not create some special dummy user for getting recommendations,
         
-        as it could cause  mislead the recommendation models,
+        as it could mislead the recommendation models,
         
-        leading to wrong recommendations.
+        and result in wrong recommendations.
         
         
         For anonymous/unregistered users it is possible to use for example their session ID.
@@ -73,7 +71,7 @@ def __init__(self, item_id, target_user_id, count, user_impact=DEFAULT, filter=D
         
         E{lb}
         
-        "recommId": "8ac80708afe9148130528757ebf6aaba",
+        "recommId": "0c6189e7-dc1a-429a-b613-192696309361",
         
         "recomms":
         
@@ -126,7 +124,7 @@ def __init__(self, item_id, target_user_id, count, user_impact=DEFAULT, filter=D
         
         E{lb}
         
-        "recommId": "c7dbfc503d262b80b77b4949ee9855fb",
+        "recommId": "6842c725-a79f-4537-a02c-f34d668a3f80",
         
         "recomms": 
         

recombee_api_client/api_requests/recommend_items_to_user.py

@@ -5,8 +5,6 @@
 
 class RecommendItemsToUser(Request):
     """
-    This feature is currently in beta.
-    
     Based on user's past interactions (purchases, ratings, etc.) with the items, recommends top-N items that are most likely to be of high value for a given user.
     
     It is also possible to use POST HTTP method (for example in case of very long ReQL filter) - query parameters then become body parameters.
@@ -39,7 +37,7 @@ def __init__(self, user_id, count, filter=DEFAULT, booster=DEFAULT, cascade_crea
         
         E{lb}
         
-        "recommId": "1644e7b31759a08480da5f3b0a13045b",
+        "recommId": "ce52ada4-e4d9-4885-943c-407db2dee837",
         
         "recomms": 
         
@@ -92,7 +90,7 @@ def __init__(self, user_id, count, filter=DEFAULT, booster=DEFAULT, cascade_crea
         
         E{lb}
         
-        "recommId": "e3ba43af1a4e59dd08a00adced1729a7",
+        "recommId": "a86ee8d5-cd8e-46d1-886c-8b3771d0520b",
         
         "recomms":
         

recombee_api_client/api_requests/recommend_users_to_item.py

@@ -5,8 +5,6 @@
 
 class RecommendUsersToItem(Request):
     """
-    This feature is currently in beta.
-    
     Recommend users that are likely to be interested in a given item.
     
     It is also possible to use POST HTTP method (for example in case of very long ReQL filter) - query parameters then become body parameters.
@@ -39,7 +37,7 @@ def __init__(self, item_id, count, filter=DEFAULT, booster=DEFAULT, cascade_crea
         
         E{lb}
         
-        "recommId": "9eeebc318508302529e3241f4570834d",
+        "recommId": "039b71dc-b9cc-4645-a84f-62b841eecfce",
         
         "recomms":
         
@@ -84,7 +82,7 @@ def __init__(self, item_id, count, filter=DEFAULT, booster=DEFAULT, cascade_crea
         
         E{lb}
         
-        "recommId": "d4c826635efc3e01a83470008c5697f1",
+        "recommId": "b2b355dd-972a-4728-9c6b-2dc229db0678",
         
         "recomms":
         
@@ -133,7 +131,7 @@ def __init__(self, item_id, count, filter=DEFAULT, booster=DEFAULT, cascade_crea
         self.included_properties = included_properties
         self.diversity = diversity
         self.expert_settings = expert_settings
-        self.timeout = 3000
+        self.timeout = 50000
         self.ensure_https = False
         self.method = 'post'
         self.path = "/recomms/items/%s/users/" % (self.item_id)

recombee_api_client/api_requests/recommend_users_to_user.py

@@ -5,8 +5,6 @@
 
 class RecommendUsersToUser(Request):
     """
-    This feature is currently in beta.
-    
     Get similar users as some given user, based on the user's past interactions (purchases, ratings, etc.) and values of properties.
     
     It is also possible to use POST HTTP method (for example in case of very long ReQL filter) - query parameters then become body parameters.
@@ -39,7 +37,7 @@ def __init__(self, user_id, count, filter=DEFAULT, booster=DEFAULT, cascade_crea
         
         E{lb}
         
-        "recommId": "32fc671480eb29d843e47def43503992",
+        "recommId": "9cb9c55d-50ba-4478-84fd-ab456136156e",
         
         "recomms": 
         
@@ -84,7 +82,7 @@ def __init__(self, user_id, count, filter=DEFAULT, booster=DEFAULT, cascade_crea
         
         E{lb}
         
-        "recommId": "27d81ade643621f45cc6ba5d30d7d683",
+        "recommId": "b326d82d-5d57-4b45-b362-c9d6f0895855",
         
         "recomms":
         
@@ -145,7 +143,7 @@ def __init__(self, user_id, count, filter=DEFAULT, booster=DEFAULT, cascade_crea
         self.rotation_rate = rotation_rate
         self.rotation_time = rotation_time
         self.expert_settings = expert_settings
-        self.timeout = 3000
+        self.timeout = 50000
         self.ensure_https = False
         self.method = 'post'
         self.path = "/recomms/users/%s/users/" % (self.user_id)

recombee_api_client/api_requests/user_based_recommendation.py

@@ -5,6 +5,8 @@
 
 class UserBasedRecommendation(Request):
     """
+    Deprecated since version 2.0.0. Use RecommendItemsToUser request instead.
+    
     Based on user's past interactions (purchases, ratings, etc.) with the items, recommends top-N items that are most likely to be of high value for a given user.
     
     It is also possible to use POST HTTP method (for example in case of very long ReQL filter) - query parameters then become body parameters.

setup.py

@@ -11,7 +11,7 @@
 setup(
     name='recombee-api-client',
 
-    version='1.6.0',
+    version='2.0.0',
 
     description='Client for Recombee recommendation API',
     long_description=long_description,

tests/test_cases/add_entity.py

@@ -19,7 +19,7 @@ def test_add_entity(self):
         req = self.create_request('valid_id')
         resp = self.client.send(req)
         # it 'fails with invalid entity id'
-        req = self.create_request('...not_valid...')
+        req = self.create_request('$$$not_valid$$$')
         try:
             self.client.send(req)
             self.assertFail()