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):

recombee_api_client/api_requests/recommend_users_to_user.py

@@ -8,10 +8,12 @@ class RecommendUsersToUser(Request):
     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.
+    
+    The returned users are sorted by similarity (first user being the most similar).
 
     """
 
-    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: User to which we find similar users
@@ -129,6 +131,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
@@ -143,6 +148,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 = 50000
         self.ensure_https = False
         self.method = 'post'
@@ -176,6 +182,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/set_view_portion.py

@@ -10,7 +10,7 @@ class SetViewPortion(Request):
 
     """
 
-    def __init__(self, user_id, item_id, portion, session_id=DEFAULT, timestamp=DEFAULT, cascade_create=DEFAULT, recomm_id=DEFAULT):
+    def __init__(self, user_id, item_id, portion, session_id=DEFAULT, timestamp=DEFAULT, cascade_create=DEFAULT, recomm_id=DEFAULT, additional_data=DEFAULT):
         """
         Required parameters:
         @param user_id: User who viewed a portion of the item
@@ -29,6 +29,8 @@ def __init__(self, user_id, item_id, portion, session_id=DEFAULT, timestamp=DEFA
         
         @param recomm_id: If this view portion 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
@@ -37,6 +39,7 @@ def __init__(self, user_id, item_id, portion, session_id=DEFAULT, timestamp=DEFA
         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'
@@ -58,6 +61,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):