Python client for Recombee API

Author: OndraFiedler

README.rst

@@ -0,0 +1,170 @@
+*****************
+RecombeeApiClient
+*****************
+
+A Python client for easy use of the `Recombee <https://www.recombee.com/>`_  recommendation API.
+
+If you don't have an account at Recombee yet, you can create a free account `here <https://www.recombee.com/>`_.
+
+Documentation of the API can be found at `docs.recombee.com <https://docs.recombee.com/)>`_.
+
+=============
+Installation
+=============
+
+Install the client with pip:
+
+.. code-block:: bash
+
+    $ pip install recombee-api-client
+
+========
+Examples
+========
+
+-------------
+Basic example
+-------------
+
+.. code-block:: python
+
+    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
+    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) ]
+
+    #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})
+
+    # Use Recombee recommender
+    client = RecombeeClient('client-test', 'jGGQ6ZKa8rQ1zTAyxTc0EMn55YPF7FJLUtaMLhbsGxmvwxgTwXYqmUk5xVZFw98L')
+
+    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]))
+        print('Send purchases')
+        client.send(Batch([AddPurchase(p['userId'], p['itemId']) for p in my_purchases]))
+
+        # Get recommendations for user 'user-25'
+        print('Recommend for a user')
+        recommended = client.send(UserBasedRecommendation('user-25', 5, {'rotationRate': 0}))
+        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
+    import random
+
+    NUM = 100
+    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)
+    #   - number of processor cores (integer number)
+    #   - description (string)
+
+    # Add properties of items
+    client.send(AddItemProperty('price', 'double'))
+    client.send(AddItemProperty('num-cores', 'int'))
+    client.send(AddItemProperty('description', 'string'))
+
+    # Prepare requests for setting a catalog of computers
+    requests = [SetItemValues(
+        "computer-%s" % i, #itemId
+        #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
+        }
+      ) for i in range(NUM)]
+    
+
+    # Send catalog to the recommender system
+    client.send(Batch(requests))
+
+    # Prepare some purchases of items by users
+    requests = []
+    items = ["computer-%s" % i for i in range(NUM)]
+    users = ["user-%s" % i for i in range(NUM)]
+
+    for item_id in items:
+        #Use cascadeCreate to create unexisting users
+        purchasing_users = [user_id for user_id in users if random.random() < PROBABILITY_PURCHASED]
+        requests += [AddPurchase(user_id, item_id, {'cascadeCreate': True}) for user_id in purchasing_users]
+
+    # Send purchases to the recommender system
+    client.send(Batch(requests))
+
+    # Get 5 recommendations for user-42, who is currently viewing computer-6
+    recommended = client.send(ItemBasedRecommendation('computer-6', 5, {'targetUserId': 'user-42'}) )
+    print("Recommended items: %s" % recommended)
+
+    # Get 5 recommendations for user-42, but recommend only computers that
+    # have at least 3 cores
+    recommended = client.send(
+        ItemBasedRecommendation('computer-6', 5, {'targetUserId': 'user-42', '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)
+    recommended = client.send(
+        ItemBasedRecommendation('computer-6', 5,
+          {'targetUserId': 'user-42', 'filter': "'price' > context_item[\"price\"]"})
+    )
+    print("Recommended up-sell items: %s" % recommended)
+  
+------------------
+Exception handling
+------------------
+
+For the sake of brevity, the above examples omit exception handling. However, various exceptions can occur while processing request, for example because of adding an already existing item, submitting interaction of nonexistent user or because of timeout.
+
+We are doing our best to provide the fastest and most reliable service, but production-level applications must implement a fallback solution since errors can always happen. The fallback might be, for example, showing the most popular items from the current category, or not displaying recommendations at all.
+
+Example:
+
+.. code-block:: python
+
+  try:
+    recommended = client.send(
+    ItemBasedRecommendation('computer-6', 5,
+      {'targetUserId': 'user-42', '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

recombee_api_client/__init__.py

@@ -0,0 +1,126 @@
+import os
+import time
+import hmac
+import json
+from hashlib import sha1
+import requests
+
+try:
+    from urllib import quote
+except ImportError:
+    from urllib.parse import quote
+
+from recombee_api_client.exceptions import ApiTimeoutException, ResponseException
+
+
+class RecombeeClient:
+    """
+    Client for sending requests to Recombee recommender system
+    """
+
+    def __init__(self, database_id, token, protocol = 'http', options = {}):
+        """
+        @param database_id: Name of your database_id at Recombee
+        @param token: Secret token obtained from Recombee for signing requests
+        @param protocol: Default protocol for sending requests. Possible values: 'http', 'https'.
+        """
+        self.database_id = database_id
+        self.token = token
+        self.protocol = protocol
+
+        self.base_uri = os.environ.get('RAPI_URI')
+        if self.base_uri is None:
+            self.base_uri =  options.get('base_uri')
+        if self.base_uri is None:
+            self.base_uri = 'rapi.recombee.com'
+
+
+    def send(self, request):
+        """
+        @param request: Request to be sent to Recombee recommender
+        """
+        timeout = request.timeout / 1000
+        uri = self.__process_request_uri(request)
+        uri = self.__sign_url(uri)
+        protocol = 'https' if request.ensure_https else self.protocol
+        uri = protocol + '://' + self.base_uri + uri
+        try:
+            if request.method == 'put':
+                return self.__put(request, uri, timeout)
+            elif request.method == 'get':
+                return self.__get(request, uri, timeout)
+            elif request.method == 'post':
+                return self.__post(request, uri, timeout)
+            elif request.method == 'delete':
+                return self.__delete(request, uri, timeout)
+        except requests.exceptions.Timeout:
+            raise ApiTimeoutException(request)
+
+    def __put(self, request, uri, timeout):
+        response = requests.put(uri, timeout=timeout)
+        self.__check_errors(response, request)
+        return response.json()
+
+    def __get(self, request, uri, timeout):
+        response = requests.get(uri, timeout=timeout)
+        self.__check_errors(response, request)
+        return response.json()
+
+    def __post(self, request, uri, timeout):
+        response = requests.post(uri, data=json.dumps(request.get_body_parameters()), 
+                                            headers={'Content-Type': 'application/json'},
+                                            timeout=timeout)
+        self.__check_errors(response, request)
+        return response.json()
+
+    def __delete(self, request, uri, timeout):
+        response = requests.delete(uri, timeout=timeout)
+        self.__check_errors(response, request)
+        return response.json()
+
+
+    def __check_errors(self, response, request):
+        status_code = response.status_code
+        if status_code == 200 or status_code == 201:
+            return
+        raise ResponseException(request, status_code, response.text)
+
+    def __process_request_uri(self, request):
+        uri = request.path
+        uri = uri[len('/{databaseId}/'):]
+        uri += self.__query_parameters_to_url(request)
+        return uri
+
+
+    def __query_parameters_to_url(self, request):
+            ps = ''
+            query_params = request.get_query_parameters()
+            for name in query_params:
+                val = query_params[name]
+                ps += '&' if ps.find('?')!=-1 else '?'
+                ps += "%s=%s" % (name, self.__format_query_parameter_value(val))
+            return ps
+
+    def __format_query_parameter_value(self, value):
+            if isinstance(value, list):
+                return ','.join([quote(str(v)) for v in value])
+            return quote(str(value))
+
+    # Sign request with HMAC, request URI must be exacly the same
+    # We have 30s to complete request with this token
+    def __sign_url(self, req_part):
+        uri = '/' + self.database_id + '/' + req_part
+        time = self.__hmac_time(uri)
+        sign = self.__hmac_sign(uri, time)
+        res = uri + time + '&hmac_sign=' +sign
+        return res
+
+    def __hmac_time(self, uri):
+        res = '&' if uri.find('?')!=-1 else '?'
+        res += "hmac_timestamp=%s" % int(time.time())
+        return res
+
+    def __hmac_sign(self, uri, time):
+        url = uri + time
+        sign = hmac.new(str.encode(self.token), str.encode(url), sha1).hexdigest()
+        return sign

recombee_api_client/api_client.py

@@ -0,0 +1,49 @@
+from recombee_api_client.api_requests.add_item import AddItem
+from recombee_api_client.api_requests.delete_item import DeleteItem
+from recombee_api_client.api_requests.set_item_values import SetItemValues
+from recombee_api_client.api_requests.get_item_values import GetItemValues
+from recombee_api_client.api_requests.list_items import ListItems
+from recombee_api_client.api_requests.add_item_property import AddItemProperty
+from recombee_api_client.api_requests.delete_item_property import DeleteItemProperty
+from recombee_api_client.api_requests.get_item_property_info import GetItemPropertyInfo
+from recombee_api_client.api_requests.list_item_properties import ListItemProperties
+from recombee_api_client.api_requests.add_series import AddSeries
+from recombee_api_client.api_requests.delete_series import DeleteSeries
+from recombee_api_client.api_requests.list_series import ListSeries
+from recombee_api_client.api_requests.list_series_items import ListSeriesItems
+from recombee_api_client.api_requests.insert_to_series import InsertToSeries
+from recombee_api_client.api_requests.remove_from_series import RemoveFromSeries
+from recombee_api_client.api_requests.add_group import AddGroup
+from recombee_api_client.api_requests.delete_group import DeleteGroup
+from recombee_api_client.api_requests.list_groups import ListGroups
+from recombee_api_client.api_requests.list_group_items import ListGroupItems
+from recombee_api_client.api_requests.insert_to_group import InsertToGroup
+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.merge_users import MergeUsers
+from recombee_api_client.api_requests.list_users import ListUsers
+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
+from recombee_api_client.api_requests.list_user_detail_views import ListUserDetailViews
+from recombee_api_client.api_requests.add_purchase import AddPurchase
+from recombee_api_client.api_requests.delete_purchase import DeletePurchase
+from recombee_api_client.api_requests.list_item_purchases import ListItemPurchases
+from recombee_api_client.api_requests.list_user_purchases import ListUserPurchases
+from recombee_api_client.api_requests.add_rating import AddRating
+from recombee_api_client.api_requests.delete_rating import DeleteRating
+from recombee_api_client.api_requests.list_item_ratings import ListItemRatings
+from recombee_api_client.api_requests.list_user_ratings import ListUserRatings
+from recombee_api_client.api_requests.add_cart_addition import AddCartAddition
+from recombee_api_client.api_requests.delete_cart_addition import DeleteCartAddition
+from recombee_api_client.api_requests.list_item_cart_additions import ListItemCartAdditions
+from recombee_api_client.api_requests.list_user_cart_additions import ListUserCartAdditions
+from recombee_api_client.api_requests.add_bookmark import AddBookmark
+from recombee_api_client.api_requests.delete_bookmark import DeleteBookmark
+from recombee_api_client.api_requests.list_item_bookmarks import ListItemBookmarks
+from recombee_api_client.api_requests.list_user_bookmarks import ListUserBookmarks
+from recombee_api_client.api_requests.user_based_recommendation import UserBasedRecommendation
+from recombee_api_client.api_requests.item_based_recommendation import ItemBasedRecommendation
+from recombee_api_client.api_requests.reset_database import ResetDatabase
+from recombee_api_client.api_requests.batch import Batch