Added support for user properties. Automatically split Batch with more than 10k requests to multiple Batch requests. Added cascadeCreate parameter to Set item/user values.

Author: OndraFiedler

README.rst

@@ -30,41 +30,36 @@ Basic example
 
     from recombee_api_client.api_client import RecombeeClient
     from recombee_api_client.exceptions import APIException
-    from recombee_api_client.api_requests import AddUser, AddItem, AddPurchase, UserBasedRecommendation, Batch
+    from recombee_api_client.api_requests import AddPurchase, UserBasedRecommendation, Batch
     import random
 
-    # Prepare some items and users
-    NUM = 100
-    my_users = ["user-%s" % i for i in range(NUM) ]
-    my_items = ["item-%s" % i for i in range(NUM) ]
+    client = RecombeeClient('client-test', 'jGGQ6ZKa8rQ1zTAyxTc0EMn55YPF7FJLUtaMLhbsGxmvwxgTwXYqmUk5xVZFw98L')
 
     #Generate some random purchases of items by users
     PROBABILITY_PURCHASED = 0.1
-    my_purchases = []
-    for user_id in my_users:
-        p = [item_id for item_id in my_items if random.random() < PROBABILITY_PURCHASED]
-        for item_id in p:
-            my_purchases.append({'userId': user_id, 'itemId': item_id})
+    NUM = 100
+    purchase_requests = []
 
-    # Use Recombee recommender
-    client = RecombeeClient('client-test', 'jGGQ6ZKa8rQ1zTAyxTc0EMn55YPF7FJLUtaMLhbsGxmvwxgTwXYqmUk5xVZFw98L')
+    for user_id in ["user-%s" % i for i in range(NUM) ]:
+      for item_id in ["item-%s" % i for i in range(NUM) ]:
+        if random.random() < PROBABILITY_PURCHASED:
+
+          request = AddPurchase(user_id, item_id, cascade_create=True)
+          purchase_requests.append(request)
 
     try:
-        # Send the data to Recombee, use Batch for faster processing
-        print('Send users')
-        client.send(Batch([AddUser(user_id) for user_id in my_users]))
-        print('Send items')
-        client.send(Batch([AddItem(item_id) for item_id in my_items]))
+        # Send the data to Recombee, use Batch for faster processing of larger data
         print('Send purchases')
-        client.send(Batch([AddPurchase(p['userId'], p['itemId']) for p in my_purchases]))
+        client.send(Batch(purchase_requests))
 
         # Get recommendations for user 'user-25'
-        print('Recommend for a user')
         recommended = client.send(UserBasedRecommendation('user-25', 5))
         print("Recommended items: %s" % recommended)
+
     except APIException as e:
         print(e)
 
+
 ---------------------
 Using property values
 ---------------------
@@ -81,10 +76,10 @@ Using property values
     PROBABILITY_PURCHASED = 0.1
 
     client = RecombeeClient('client-test', 'jGGQ6ZKa8rQ1zTAyxTc0EMn55YPF7FJLUtaMLhbsGxmvwxgTwXYqmUk5xVZFw98L')
-    
+
     #Clear the entire database
     client.send(ResetDatabase())
-    
+
     # We will use computers as items in this example
     # Computers have three properties 
     #   - price (floating point number)
@@ -104,11 +99,11 @@ Using property values
           'price': random.uniform(500, 2000),
           'num-cores': random.randrange(1,9),
           'description': 'Great computer',
-          '!cascadeCreate': True   # Use !cascadeCreate for creating item
-                                   # with given itemId, if it doesn't exist
-        }
+        },
+        cascade_create=True   # Use cascadeCreate for creating item
+                              # with given itemId if it doesn't exist
       ) for i in range(NUM)]
-    
+
 
     # Send catalog to the recommender system
     client.send(Batch(requests))

recombee_api_client/api_client.py

@@ -11,12 +11,13 @@
     from urllib.parse import quote
 
 from recombee_api_client.exceptions import ApiTimeoutException, ResponseException
-
+from recombee_api_client.api_requests import Batch
 
 class RecombeeClient:
     """
     Client for sending requests to Recombee recommender system
     """
+    BATCH_MAX_SIZE = 10000
 
     def __init__(self, database_id, token, protocol = 'http', options = {}):
         """
@@ -39,6 +40,10 @@ def send(self, request):
         """
         @param request: Request to be sent to Recombee recommender
         """
+        
+        if isinstance(request, Batch) and len(request.requests) > self.BATCH_MAX_SIZE:
+            return self.__send_multipart_batch(request)
+
         timeout = request.timeout / 1000
         uri = self.__process_request_uri(request)
         uri = self.__sign_url(uri)
@@ -85,6 +90,23 @@ def __check_errors(self, response, request):
             return
         raise ResponseException(request, status_code, response.text)
 
+    @staticmethod
+    def __get_list_chunks(l, n):
+        """Yield successive n-sized chunks from l."""
+
+        try: #Python 2/3 compatibility
+            xrange
+        except NameError:
+            xrange = range
+
+        for i in xrange(0, len(l), n):
+            yield l[i:i + n]
+
+    def __send_multipart_batch(self, batch):
+        requests_parts = [rqs for rqs in self.__get_list_chunks(batch.requests, self.BATCH_MAX_SIZE)]
+        responses = [self.send(Batch(rqs)) for rqs in requests_parts]
+        return sum(responses, [])
+
     def __process_request_uri(self, request):
         uri = request.path
         uri = uri[len('/{databaseId}/'):]

recombee_api_client/api_requests/__init__.py

@@ -21,8 +21,14 @@
 from recombee_api_client.api_requests.remove_from_group import RemoveFromGroup
 from recombee_api_client.api_requests.add_user import AddUser
 from recombee_api_client.api_requests.delete_user import DeleteUser
+from recombee_api_client.api_requests.set_user_values import SetUserValues
+from recombee_api_client.api_requests.get_user_values import GetUserValues
 from recombee_api_client.api_requests.merge_users import MergeUsers
 from recombee_api_client.api_requests.list_users import ListUsers
+from recombee_api_client.api_requests.add_user_property import AddUserProperty
+from recombee_api_client.api_requests.delete_user_property import DeleteUserProperty
+from recombee_api_client.api_requests.get_user_property_info import GetUserPropertyInfo
+from recombee_api_client.api_requests.list_user_properties import ListUserProperties
 from recombee_api_client.api_requests.add_detail_view import AddDetailView
 from recombee_api_client.api_requests.delete_detail_view import DeleteDetailView
 from recombee_api_client.api_requests.list_item_detail_views import ListItemDetailViews

recombee_api_client/api_requests/add_user_property.py

@@ -0,0 +1,39 @@
+from recombee_api_client.api_requests.request import Request
+
+class AddUserProperty(Request):
+    """
+    Adding an user property is somehow equivalent to adding a column to the table of users. The users may be characterized by various properties of different types.
+
+    """
+
+    def __init__(self,property_name, type):
+        """
+        Required parameters:
+        @param property_name: Name of the user property to be created. Currently, the following names are reserved:`id`, `userid`, case insensitively. Also, the length of the property name must not exceed 63 characters.
+        
+        
+        @param type: Value type of the user property to be created. One of: `int`, `double`, `string`, `boolean`, `timestamp`, `set`
+        
+        
+        """
+        self.property_name = property_name
+        self.type = type
+        self.timeout = 1000
+        self.ensure_https = False
+        self.method = 'put'
+        self.path = "/{databaseId}/users/properties/%s" % (self.property_name)
+
+    def get_body_parameters(self):
+        """
+        Values of body parameters as a dictionary (name of parameter: value of the parameter).
+        """
+        p = dict()
+        return p
+
+    def get_query_parameters(self):
+        """
+        Values of query parameters as a dictionary (name of parameter: value of the parameter).
+        """
+        params = dict()
+        params['type'] = self.type
+        return params

recombee_api_client/api_requests/batch.py

@@ -12,7 +12,6 @@ class Batch(Request):
     - executing the requests in a batch is equivalent as if they were executed one-by-one individually; there are, however, many optimizations to make batch execution as fast as possible,
     - the status code of the batch request itself is 200 even if the individual requests result in error - you have to inspect the code values in the resulting array,
     - if the status code of the whole batch is not 200, then there is an error in the batch request itself; in such a case, the error message returned should help you to resolve the problem,
-    - currently, batch size is limited to **10,000** requests; if you wish to execute even larger number of requests, please split the batch into multiple parts.
     """
 
     def __init__(self, requests, distinctRecomms=None):

recombee_api_client/api_requests/delete_user_property.py

@@ -0,0 +1,33 @@
+from recombee_api_client.api_requests.request import Request
+
+class DeleteUserProperty(Request):
+    """
+    Deleting an user property is roughly equivalent to removing a column from the table of users.
+
+    """
+
+    def __init__(self,property_name):
+        """
+        Required parameters:
+        @param property_name: Name of the property to be deleted.
+        
+        """
+        self.property_name = property_name
+        self.timeout = 1000
+        self.ensure_https = False
+        self.method = 'delete'
+        self.path = "/{databaseId}/users/properties/%s" % (self.property_name)
+
+    def get_body_parameters(self):
+        """
+        Values of body parameters as a dictionary (name of parameter: value of the parameter).
+        """
+        p = dict()
+        return p
+
+    def get_query_parameters(self):
+        """
+        Values of query parameters as a dictionary (name of parameter: value of the parameter).
+        """
+        params = dict()
+        return params

recombee_api_client/api_requests/get_user_property_info.py

@@ -0,0 +1,33 @@
+from recombee_api_client.api_requests.request import Request
+
+class GetUserPropertyInfo(Request):
+    """
+    Gets information about specified user property.
+
+    """
+
+    def __init__(self,property_name):
+        """
+        Required parameters:
+        @param property_name: Name of the property about which the information is to be retrieved.
+        
+        """
+        self.property_name = property_name
+        self.timeout = 1000
+        self.ensure_https = False
+        self.method = 'get'
+        self.path = "/{databaseId}/users/properties/%s" % (self.property_name)
+
+    def get_body_parameters(self):
+        """
+        Values of body parameters as a dictionary (name of parameter: value of the parameter).
+        """
+        p = dict()
+        return p
+
+    def get_query_parameters(self):
+        """
+        Values of query parameters as a dictionary (name of parameter: value of the parameter).
+        """
+        params = dict()
+        return params

recombee_api_client/api_requests/get_user_values.py

@@ -0,0 +1,34 @@
+from recombee_api_client.api_requests.request import Request
+
+class GetUserValues(Request):
+    """
+    Get all the current property values of a given user.
+
+    """
+
+    def __init__(self,user_id):
+        """
+        Required parameters:
+        @param user_id: ID of the user properties of which are to be obtained.
+        
+        
+        """
+        self.user_id = user_id
+        self.timeout = 1000
+        self.ensure_https = False
+        self.method = 'get'
+        self.path = "/{databaseId}/users/%s" % (self.user_id)
+
+    def get_body_parameters(self):
+        """
+        Values of body parameters as a dictionary (name of parameter: value of the parameter).
+        """
+        p = dict()
+        return p
+
+    def get_query_parameters(self):
+        """
+        Values of query parameters as a dictionary (name of parameter: value of the parameter).
+        """
+        params = dict()
+        return params

recombee_api_client/api_requests/item_based_recommendation.py

@@ -17,6 +17,15 @@ def __init__(self,item_id, count, target_user_id=None, user_impact=None, filter=
         Optional parameters:
         @param target_user_id: ID of the user who will see the recommendations.
         
+        
+        Specifying the *targetUserId* is beneficial because:
+        
+        
+        * It makes the recommendations personalized
+        
+        * Allows calculations of Actions and Conversions in the graphical user interface, as Recombee can pair the user who got recommendations and who afterwards viewed/purchased an item.
+        
+        
         @param user_impact: If *targetUserId* parameter is present, the recommendations are biased towards the user given. Using *userImpact*, you may control this bias. For an extreme case of `userImpact=0.0`, the interactions made by the user are not taken into account at all (with the exception of history-based blacklisting), for `userImpact=1.0`, you'll get user-based recommendation. The default value is `0.1`
         
         
@@ -105,13 +114,13 @@ def __init__(self,item_id, count, target_user_id=None, user_impact=None, filter=
         @param diversity: **Expert option** Real number from [0.0, 1.0] which determines how much mutually dissimilar should the recommended items be. The default value is 0.0, i.e., no diversification. Value 1.0 means maximal diversification.
         
         
-        @param min_relevance: **Expert option** Specifies the threshold of how much relevant must the recommended items be to the user. Possible values one of: "low", "medium", "high". The default value is "low", meaning that the system attempts to recommend number of items equal to *count* at any cost. If there are not enough data (such as interactions or item properties), this may even lead to bestseller-based recommendations to be appended to reach the full *count*. This behavior may be suppressed by using "medium" or "high" values. In such case, the system only recommends items of at least the requested qualit, and may return less than *count* items when there is not enough data to fulfill it.
+        @param min_relevance: **Expert option** If the *targetUserId* is provided:  Specifies the threshold of how much relevant must the recommended items be to the user. Possible values one of: "low", "medium", "high". The default value is "low", meaning that the system attempts to recommend number of items equal to *count* at any cost. If there are not enough data (such as interactions or item properties), this may even lead to bestseller-based recommendations to be appended to reach the full *count*. This behavior may be suppressed by using "medium" or "high" values. In such case, the system only recommends items of at least the requested qualit, and may return less than *count* items when there is not enough data to fulfill it.
         
         
-        @param rotation_rate: **Expert option** If your users browse the system in real-time, it may easily happen that you wish to offer them recommendations multiple times. Here comes the question: how much should the recommendations change? Should they remain the same, or should they rotate? Recombee API allows you to control this per-request in backward fashion. You may penalize an item for being recommended in the near past. For the specific user, `rotationRate=1` means maximal rotation, `rotationRate=0` means absolutely no rotation. You may also use, for example `rotationRate=0.2` for only slight rotation of recommended items.
+        @param rotation_rate: **Expert option** If the *targetUserId* is provided: If your users browse the system in real-time, it may easily happen that you wish to offer them recommendations multiple times. Here comes the question: how much should the recommendations change? Should they remain the same, or should they rotate? Recombee API allows you to control this per-request in backward fashion. You may penalize an item for being recommended in the near past. For the specific user, `rotationRate=1` means maximal rotation, `rotationRate=0` means absolutely no rotation. You may also use, for example `rotationRate=0.2` for only slight rotation of recommended items.
         
         
-        @param rotation_time: **Expert option** Taking *rotationRate* into account, specifies how long time it takes to an item to fully recover from the penalization. By example, `rotationTime=7200.0` means that items recommended more than 2 hours ago are definitely not penalized anymore. Currently, the penalization is linear, so for `rotationTime=7200.0`, an item is still penalized by `0.5` to the user after 1 hour.
+        @param rotation_time: **Expert option** If the *targetUserId* is provided: Taking *rotationRate* into account, specifies how long time it takes to an item to fully recover from the penalization. For example, `rotationTime=7200.0` means that items recommended more than 2 hours ago are definitely not penalized anymore. Currently, the penalization is linear, so for `rotationTime=7200.0`, an item is still penalized by `0.5` to the user after 1 hour.
         
         
         """

recombee_api_client/api_requests/list_user_properties.py

@@ -0,0 +1,29 @@
+from recombee_api_client.api_requests.request import Request
+
+class ListUserProperties(Request):
+    """
+    Gets the list of all the user properties in your database.
+
+    """
+
+    def __init__(self):
+        """
+        """
+        self.timeout = 1000
+        self.ensure_https = False
+        self.method = 'get'
+        self.path = "/{databaseId}/users/properties/list/" % ()
+
+    def get_body_parameters(self):
+        """
+        Values of body parameters as a dictionary (name of parameter: value of the parameter).
+        """
+        p = dict()
+        return p
+
+    def get_query_parameters(self):
+        """
+        Values of query parameters as a dictionary (name of parameter: value of the parameter).
+        """
+        params = dict()
+        return params