additionalData for interactions, returnAbGroup for recommendation endpoints

Author: OndraFiedler

README.rst

@@ -35,7 +35,7 @@ Basic example
     from recombee_api_client.api_requests import AddPurchase, RecommendItemsToUser, Batch
     import random
 
-    client = RecombeeClient('--my-database-id--', '--my-secret-token--'')
+    client = RecombeeClient('--my-database-id--', '--db-private-token--')
 
     #Generate some random purchases of items by users
     PROBABILITY_PURCHASED = 0.1
@@ -77,7 +77,7 @@ Using property values
     NUM = 100
     PROBABILITY_PURCHASED = 0.1
 
-    client = RecombeeClient('--my-database-id--', '--my-secret-token--'')
+    client = RecombeeClient('--my-database-id--', '--db-private-token--')
 
     #Clear the entire database
     client.send(ResetDatabase())

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/2.2.0'}
+        headers = {'User-Agent': 'recombee-python-api-client/2.3.0'}
         if additional_headers:
             headers.update(additional_headers)
         return headers

recombee_api_client/api_requests/add_bookmark.py

@@ -9,7 +9,7 @@ class AddBookmark(Request):
 
     """
 
-    def __init__(self, user_id, item_id, timestamp=DEFAULT, cascade_create=DEFAULT, recomm_id=DEFAULT):
+    def __init__(self, user_id, item_id, timestamp=DEFAULT, cascade_create=DEFAULT, recomm_id=DEFAULT, additional_data=DEFAULT):
         """
         Required parameters:
         @param user_id: User who bookmarked the item
@@ -24,12 +24,15 @@ def __init__(self, user_id, item_id, timestamp=DEFAULT, cascade_create=DEFAULT,
         
         @param recomm_id: If this bookmark is based on a recommendation request, `recommId` is the id of the clicked recommendation.
         
+        @param additional_data: A dictionary of additional data for the interaction.
+        
         """
         self.user_id = user_id
         self.item_id = item_id
         self.timestamp = timestamp
         self.cascade_create = cascade_create
         self.recomm_id = recomm_id
+        self.additional_data = additional_data
         self.timeout = 1000
         self.ensure_https = False
         self.method = 'post'
@@ -48,6 +51,8 @@ def get_body_parameters(self):
             p['cascadeCreate'] = self.cascade_create
         if self.recomm_id is not DEFAULT:
             p['recommId'] = self.recomm_id
+        if self.additional_data is not DEFAULT:
+            p['additionalData'] = self.additional_data
         return p
 
     def get_query_parameters(self):

recombee_api_client/api_requests/add_cart_addition.py

@@ -9,7 +9,7 @@ class AddCartAddition(Request):
 
     """
 
-    def __init__(self, user_id, item_id, timestamp=DEFAULT, cascade_create=DEFAULT, amount=DEFAULT, price=DEFAULT, recomm_id=DEFAULT):
+    def __init__(self, user_id, item_id, timestamp=DEFAULT, cascade_create=DEFAULT, amount=DEFAULT, price=DEFAULT, recomm_id=DEFAULT, additional_data=DEFAULT):
         """
         Required parameters:
         @param user_id: User who added the item to the cart
@@ -28,6 +28,8 @@ def __init__(self, user_id, item_id, timestamp=DEFAULT, cascade_create=DEFAULT,
         
         @param recomm_id: If this cart addition is based on a recommendation request, `recommId` is the id of the clicked recommendation.
         
+        @param additional_data: A dictionary of additional data for the interaction.
+        
         """
         self.user_id = user_id
         self.item_id = item_id
@@ -36,6 +38,7 @@ def __init__(self, user_id, item_id, timestamp=DEFAULT, cascade_create=DEFAULT,
         self.amount = amount
         self.price = price
         self.recomm_id = recomm_id
+        self.additional_data = additional_data
         self.timeout = 1000
         self.ensure_https = False
         self.method = 'post'
@@ -58,6 +61,8 @@ def get_body_parameters(self):
             p['price'] = self.price
         if self.recomm_id is not DEFAULT:
             p['recommId'] = self.recomm_id
+        if self.additional_data is not DEFAULT:
+            p['additionalData'] = self.additional_data
         return p
 
     def get_query_parameters(self):

recombee_api_client/api_requests/add_detail_view.py

@@ -9,7 +9,7 @@ class AddDetailView(Request):
 
     """
 
-    def __init__(self, user_id, item_id, timestamp=DEFAULT, duration=DEFAULT, cascade_create=DEFAULT, recomm_id=DEFAULT):
+    def __init__(self, user_id, item_id, timestamp=DEFAULT, duration=DEFAULT, cascade_create=DEFAULT, recomm_id=DEFAULT, additional_data=DEFAULT):
         """
         Required parameters:
         @param user_id: User who viewed the item
@@ -26,13 +26,16 @@ def __init__(self, user_id, item_id, timestamp=DEFAULT, duration=DEFAULT, cascad
         
         @param recomm_id: If this detail view is based on a recommendation request, `recommId` is the id of the clicked recommendation.
         
+        @param additional_data: A dictionary of additional data for the interaction.
+        
         """
         self.user_id = user_id
         self.item_id = item_id
         self.timestamp = timestamp
         self.duration = duration
         self.cascade_create = cascade_create
         self.recomm_id = recomm_id
+        self.additional_data = additional_data
         self.timeout = 1000
         self.ensure_https = False
         self.method = 'post'
@@ -53,6 +56,8 @@ def get_body_parameters(self):
             p['cascadeCreate'] = self.cascade_create
         if self.recomm_id is not DEFAULT:
             p['recommId'] = self.recomm_id
+        if self.additional_data is not DEFAULT:
+            p['additionalData'] = self.additional_data
         return p
 
     def get_query_parameters(self):

recombee_api_client/api_requests/add_purchase.py

@@ -9,7 +9,7 @@ class AddPurchase(Request):
 
     """
 
-    def __init__(self, user_id, item_id, timestamp=DEFAULT, cascade_create=DEFAULT, amount=DEFAULT, price=DEFAULT, profit=DEFAULT, recomm_id=DEFAULT):
+    def __init__(self, user_id, item_id, timestamp=DEFAULT, cascade_create=DEFAULT, amount=DEFAULT, price=DEFAULT, profit=DEFAULT, recomm_id=DEFAULT, additional_data=DEFAULT):
         """
         Required parameters:
         @param user_id: User who purchased the item
@@ -30,6 +30,8 @@ def __init__(self, user_id, item_id, timestamp=DEFAULT, cascade_create=DEFAULT,
         
         @param recomm_id: If this purchase is based on a recommendation request, `recommId` is the id of the clicked recommendation.
         
+        @param additional_data: A dictionary of additional data for the interaction.
+        
         """
         self.user_id = user_id
         self.item_id = item_id
@@ -39,6 +41,7 @@ def __init__(self, user_id, item_id, timestamp=DEFAULT, cascade_create=DEFAULT,
         self.price = price
         self.profit = profit
         self.recomm_id = recomm_id
+        self.additional_data = additional_data
         self.timeout = 1000
         self.ensure_https = False
         self.method = 'post'
@@ -63,6 +66,8 @@ def get_body_parameters(self):
             p['profit'] = self.profit
         if self.recomm_id is not DEFAULT:
             p['recommId'] = self.recomm_id
+        if self.additional_data is not DEFAULT:
+            p['additionalData'] = self.additional_data
         return p
 
     def get_query_parameters(self):

recombee_api_client/api_requests/add_rating.py

@@ -9,7 +9,7 @@ class AddRating(Request):
 
     """
 
-    def __init__(self, user_id, item_id, rating, timestamp=DEFAULT, cascade_create=DEFAULT, recomm_id=DEFAULT):
+    def __init__(self, user_id, item_id, rating, timestamp=DEFAULT, cascade_create=DEFAULT, recomm_id=DEFAULT, additional_data=DEFAULT):
         """
         Required parameters:
         @param user_id: User who submitted the rating
@@ -26,13 +26,16 @@ def __init__(self, user_id, item_id, rating, timestamp=DEFAULT, cascade_create=D
         
         @param recomm_id: If this rating is based on a recommendation request, `recommId` is the id of the clicked recommendation.
         
+        @param additional_data: A dictionary of additional data for the interaction.
+        
         """
         self.user_id = user_id
         self.item_id = item_id
         self.rating = rating
         self.timestamp = timestamp
         self.cascade_create = cascade_create
         self.recomm_id = recomm_id
+        self.additional_data = additional_data
         self.timeout = 1000
         self.ensure_https = False
         self.method = 'post'
@@ -52,6 +55,8 @@ def get_body_parameters(self):
             p['cascadeCreate'] = self.cascade_create
         if self.recomm_id is not DEFAULT:
             p['recommId'] = self.recomm_id
+        if self.additional_data is not DEFAULT:
+            p['additionalData'] = self.additional_data
         return p
 
     def get_query_parameters(self):

recombee_api_client/api_requests/recommend_items_to_item.py

@@ -8,10 +8,12 @@ class RecommendItemsToItem(Request):
     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.
+    
+    The returned items are sorted by relevancy (first item being the most relevant).
 
     """
 
-    def __init__(self, item_id, target_user_id, count, user_impact=DEFAULT, filter=DEFAULT, booster=DEFAULT, cascade_create=DEFAULT, scenario=DEFAULT, return_properties=DEFAULT, included_properties=DEFAULT, diversity=DEFAULT, min_relevance=DEFAULT, rotation_rate=DEFAULT, rotation_time=DEFAULT, expert_settings=DEFAULT):
+    def __init__(self, item_id, target_user_id, count, user_impact=DEFAULT, filter=DEFAULT, booster=DEFAULT, cascade_create=DEFAULT, scenario=DEFAULT, return_properties=DEFAULT, included_properties=DEFAULT, diversity=DEFAULT, min_relevance=DEFAULT, rotation_rate=DEFAULT, rotation_time=DEFAULT, expert_settings=DEFAULT, return_ab_group=DEFAULT):
         """
         Required parameters:
         @param item_id: ID of the item for which the recommendations are to be generated.
@@ -175,6 +177,9 @@ def __init__(self, item_id, target_user_id, count, user_impact=DEFAULT, filter=D
         @param expert_settings: Dictionary of custom options.
         
         
+        @param return_ab_group: If there is a custom AB-testing running, return name of group to which the request belongs.
+        
+        
         """
         self.item_id = item_id
         self.target_user_id = target_user_id
@@ -191,6 +196,7 @@ def __init__(self, item_id, target_user_id, count, user_impact=DEFAULT, filter=D
         self.rotation_rate = rotation_rate
         self.rotation_time = rotation_time
         self.expert_settings = expert_settings
+        self.return_ab_group = return_ab_group
         self.timeout = 3000
         self.ensure_https = False
         self.method = 'post'
@@ -227,6 +233,8 @@ def get_body_parameters(self):
             p['rotationTime'] = self.rotation_time
         if self.expert_settings is not DEFAULT:
             p['expertSettings'] = self.expert_settings
+        if self.return_ab_group is not DEFAULT:
+            p['returnAbGroup'] = self.return_ab_group
         return p
 
     def get_query_parameters(self):

recombee_api_client/api_requests/recommend_items_to_user.py

@@ -8,10 +8,12 @@ class RecommendItemsToUser(Request):
     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.
+    
+    The returned items are sorted by relevancy (first item being the most relevant).
 
     """
 
-    def __init__(self, user_id, count, filter=DEFAULT, booster=DEFAULT, cascade_create=DEFAULT, scenario=DEFAULT, return_properties=DEFAULT, included_properties=DEFAULT, diversity=DEFAULT, min_relevance=DEFAULT, rotation_rate=DEFAULT, rotation_time=DEFAULT, expert_settings=DEFAULT):
+    def __init__(self, user_id, count, filter=DEFAULT, booster=DEFAULT, cascade_create=DEFAULT, scenario=DEFAULT, return_properties=DEFAULT, included_properties=DEFAULT, diversity=DEFAULT, min_relevance=DEFAULT, rotation_rate=DEFAULT, rotation_time=DEFAULT, expert_settings=DEFAULT, return_ab_group=DEFAULT):
         """
         Required parameters:
         @param user_id: ID of the user for which personalized recommendations are to be generated.
@@ -141,6 +143,9 @@ def __init__(self, user_id, count, filter=DEFAULT, booster=DEFAULT, cascade_crea
         @param expert_settings: Dictionary of custom options.
         
         
+        @param return_ab_group: If there is a custom AB-testing running, return name of group to which the request belongs.
+        
+        
         """
         self.user_id = user_id
         self.count = count
@@ -155,6 +160,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.return_ab_group = return_ab_group
         self.timeout = 3000
         self.ensure_https = False
         self.method = 'post'
@@ -188,6 +194,8 @@ def get_body_parameters(self):
             p['rotationTime'] = self.rotation_time
         if self.expert_settings is not DEFAULT:
             p['expertSettings'] = self.expert_settings
+        if self.return_ab_group is not DEFAULT:
+            p['returnAbGroup'] = self.return_ab_group
         return p
 
     def get_query_parameters(self):

recombee_api_client/api_requests/recommend_users_to_item.py

@@ -8,10 +8,12 @@ class RecommendUsersToItem(Request):
     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.
+    
+    The returned users are sorted by predicted interest in the item (first user being the most interested).
 
     """
 
-    def __init__(self, item_id, count, filter=DEFAULT, booster=DEFAULT, cascade_create=DEFAULT, scenario=DEFAULT, return_properties=DEFAULT, included_properties=DEFAULT, diversity=DEFAULT, expert_settings=DEFAULT):
+    def __init__(self, item_id, count, filter=DEFAULT, booster=DEFAULT, cascade_create=DEFAULT, scenario=DEFAULT, return_properties=DEFAULT, included_properties=DEFAULT, diversity=DEFAULT, expert_settings=DEFAULT, return_ab_group=DEFAULT):
         """
         Required parameters:
         @param item_id: ID of the item for which the recommendations are to be generated.
@@ -120,6 +122,9 @@ def __init__(self, item_id, count, filter=DEFAULT, booster=DEFAULT, cascade_crea
         @param expert_settings: Dictionary of custom options.
         
         
+        @param return_ab_group: If there is a custom AB-testing running, return name of group to which the request belongs.
+        
+        
         """
         self.item_id = item_id
         self.count = count
@@ -131,6 +136,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.return_ab_group = return_ab_group
         self.timeout = 50000
         self.ensure_https = False
         self.method = 'post'
@@ -158,6 +164,8 @@ def get_body_parameters(self):
             p['diversity'] = self.diversity
         if self.expert_settings is not DEFAULT:
             p['expertSettings'] = self.expert_settings
+        if self.return_ab_group is not DEFAULT:
+            p['returnAbGroup'] = self.return_ab_group
         return p
 
     def get_query_parameters(self):