Support SearchItems endpoint

Author: OndraFiedler

README.rst

@@ -71,15 +71,15 @@ Using property values
 
     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 RecommendItemsToItem, Batch, ResetDatabase
+    from recombee_api_client.api_requests import RecommendItemsToItem, SearchItems, Batch, ResetDatabase
     import random
 
     NUM = 100
     PROBABILITY_PURCHASED = 0.1
 
     client = RecombeeClient('--my-database-id--', '--db-private-token--')
 
-    #Clear the entire database
+    # Clear the entire database
     client.send(ResetDatabase())
 
     # We will use computers as items in this example
@@ -127,9 +127,6 @@ Using property values
     client.send(Batch(requests))
 
     # Get 5 recommendations for user-42, who is currently viewing computer-6
-    recommended = client.send(RecommendItemsToItem('computer-6', 'user-42', 5))
-    print("Recommended items: %s" % recommended)
-
     # Recommend only computers that have at least 3 cores
     recommended = client.send(
         RecommendItemsToItem('computer-6', 'user-42', 5, filter="'num-cores'>=3")
@@ -142,6 +139,16 @@ Using property values
     )
     print("Recommended up-sell items: %s" % recommended)
 
+    # Filters, boosters and other settings can be also set in the Admin UI (admin.recombee.com)
+    # when scenario is specified
+    recommended = client.send(
+      RecommendItemsToItem('computer-6', 'user-42', 5, scenario='product_detail')
+      )
+
+    # Perform personalized full-text search with a user's search query (e.g. 'computers').
+    matches = client.send(SearchItems('user-42', 'computers', 5))
+    print("Matched items: %s" % matches)
+
 ------------------
 Exception handling
 ------------------
@@ -153,6 +160,7 @@ We are doing our best to provide the fastest and most reliable service, but prod
 Example:
 
 .. code-block:: python
+  from recombee_api_client.exceptions import *
 
   try:
     recommended = client.send(
@@ -163,4 +171,4 @@ Example:
   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/2.4.0'}
+        headers = {'User-Agent': 'recombee-python-api-client/3.0.0'}
         if additional_headers:
             headers.update(additional_headers)
         return headers

recombee_api_client/api_requests/__init__.py

@@ -57,6 +57,7 @@
 from recombee_api_client.api_requests.recommend_users_to_user import RecommendUsersToUser
 from recombee_api_client.api_requests.recommend_items_to_item import RecommendItemsToItem
 from recombee_api_client.api_requests.recommend_users_to_item import RecommendUsersToItem
+from recombee_api_client.api_requests.search_items import SearchItems
 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

recombee_api_client/api_requests/recommend_items_to_item.py

@@ -13,7 +13,7 @@ class RecommendItemsToItem(Request):
 
     """
 
-    def __init__(self, item_id, target_user_id, count, filter=DEFAULT, booster=DEFAULT, cascade_create=DEFAULT, scenario=DEFAULT, logic=DEFAULT, return_properties=DEFAULT, included_properties=DEFAULT, user_impact=DEFAULT, diversity=DEFAULT, min_relevance=DEFAULT, rotation_rate=DEFAULT, rotation_time=DEFAULT, expert_settings=DEFAULT, return_ab_group=DEFAULT):
+    def __init__(self, item_id, target_user_id, count, scenario=DEFAULT, cascade_create=DEFAULT, return_properties=DEFAULT, included_properties=DEFAULT, filter=DEFAULT, booster=DEFAULT, logic=DEFAULT, user_impact=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.
@@ -53,21 +53,16 @@ def __init__(self, item_id, target_user_id, count, filter=DEFAULT, booster=DEFAU
         
         
         Optional parameters:
-        @param filter: Boolean-returning [ReQL](https://docs.recombee.com/reql.html) expression which allows you to filter recommended items based on the values of their attributes.
-        
-        @param booster: Number-returning [ReQL](https://docs.recombee.com/reql.html) expression which allows you to boost recommendation rate of some items based on the values of their attributes.
+        @param scenario: Scenario defines a particular application of recommendations. It can be for example "homepage", "cart" or "emailing".
         
-        @param cascade_create: If item of given *itemId* or user of given *targetUserId* doesn't exist in the database, it creates the missing entity/entities and returns some (non-personalized) recommendations. This allows for example rotations in the following recommendations for the user of given *targetUserId*, as the user will be already known to the system.
         
-        @param scenario: Scenario defines a particular application of recommendations. It can be for example "homepage", "cart" or "emailing". You can see each scenario in the UI separately, so you can check how well each application performs. The AI which optimizes models in order to get the best results may optimize different scenarios separately, or even use different models in each of the scenarios.
+        You can set various settings to the [scenario](https://docs.recombee.com/scenarios.html) in the [Admin UI](https://admin.recombee.com). You can also see performance of each scenario in the Admin UI separately, so you can check how well each application performs.
         
-        @param logic: Logic specifies particular behavior of the recommendation models. You can pick tailored logic for your domain (e-commerce, multimedia, fashion ...) and use case.
         
-        See [this section](https://docs.recombee.com/recommendation_logic.html) for list of available logics and other details.
+        The AI which optimizes models in order to get the best results may optimize different scenarios separately, or even use different models in each of the scenarios.
         
         
-        The difference between `logic` and `scenario` is that `logic` specifies mainly behavior, while `scenario` specifies the place where recommendations are shown to the users.
-        
+        @param cascade_create: If item of given *itemId* or user of given *targetUserId* doesn't exist in the database, it creates the missing entity/entities and returns some (non-personalized) recommendations. This allows for example rotations in the following recommendations for the user of given *targetUserId*, as the user will be already known to the system.
         
         @param return_properties: With `returnProperties=true`, property values of the recommended items are returned along with their IDs in a JSON dictionary. The acquired property values can be used for easy displaying of the recommended items to the user. 
         
@@ -167,6 +162,29 @@ def __init__(self, item_id, target_user_id, count, filter=DEFAULT, booster=DEFAU
         ```
         
         
+        @param filter: Boolean-returning [ReQL](https://docs.recombee.com/reql.html) expression which allows you to filter recommended items based on the values of their attributes.
+        
+        
+        Filters can be also assigned to a [scenario](https://docs.recombee.com/scenarios.html) in the [Admin UI](https://admin.recombee.com).
+        
+        
+        @param booster: Number-returning [ReQL](https://docs.recombee.com/reql.html) expression which allows you to boost recommendation rate of some items based on the values of their attributes.
+        
+        
+        Boosters can be also assigned to a [scenario](https://docs.recombee.com/scenarios.html) in the [Admin UI](https://admin.recombee.com).
+        
+        
+        @param logic: Logic specifies particular behavior of the recommendation models. You can pick tailored logic for your domain and use case.
+        
+        See [this section](https://docs.recombee.com/recommendation_logics.html) for list of available logics and other details.
+        
+        
+        The difference between `logic` and `scenario` is that `logic` specifies mainly behavior, while `scenario` specifies the place where recommendations are shown to the users.
+        
+        
+        Logic can be also set to a [scenario](https://docs.recombee.com/scenarios.html) in the [Admin UI](https://admin.recombee.com).
+        
+        
         @param user_impact: **Expert option** If *targetUserId* parameter is present, the recommendations are biased towards the given user. 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`.
         
         
@@ -192,13 +210,13 @@ def __init__(self, item_id, target_user_id, count, filter=DEFAULT, booster=DEFAU
         self.item_id = item_id
         self.target_user_id = target_user_id
         self.count = count
-        self.filter = filter
-        self.booster = booster
-        self.cascade_create = cascade_create
         self.scenario = scenario
-        self.logic = logic
+        self.cascade_create = cascade_create
         self.return_properties = return_properties
         self.included_properties = included_properties
+        self.filter = filter
+        self.booster = booster
+        self.logic = logic
         self.user_impact = user_impact
         self.diversity = diversity
         self.min_relevance = min_relevance
@@ -218,20 +236,20 @@ def get_body_parameters(self):
         p = dict()
         p['targetUserId'] = self.target_user_id
         p['count'] = self.count
-        if self.filter is not DEFAULT:
-            p['filter'] = self.filter
-        if self.booster is not DEFAULT:
-            p['booster'] = self.booster
-        if self.cascade_create is not DEFAULT:
-            p['cascadeCreate'] = self.cascade_create
         if self.scenario is not DEFAULT:
             p['scenario'] = self.scenario
-        if self.logic is not DEFAULT:
-            p['logic'] = self.logic
+        if self.cascade_create is not DEFAULT:
+            p['cascadeCreate'] = self.cascade_create
         if self.return_properties is not DEFAULT:
             p['returnProperties'] = self.return_properties
         if self.included_properties is not DEFAULT:
             p['includedProperties'] = self.included_properties
+        if self.filter is not DEFAULT:
+            p['filter'] = self.filter
+        if self.booster is not DEFAULT:
+            p['booster'] = self.booster
+        if self.logic is not DEFAULT:
+            p['logic'] = self.logic
         if self.user_impact is not DEFAULT:
             p['userImpact'] = self.user_impact
         if self.diversity is not DEFAULT:

recombee_api_client/api_requests/recommend_items_to_user.py

@@ -7,35 +7,34 @@ 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.
     
+    The most typical use cases are recommendations at homepage, in some "Picked just for you" section or in email.
+    
     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, logic=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):
+    def __init__(self, user_id, count, scenario=DEFAULT, cascade_create=DEFAULT, return_properties=DEFAULT, included_properties=DEFAULT, filter=DEFAULT, booster=DEFAULT, logic=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.
+        @param user_id: ID of the user for whom personalized recommendations are to be generated.
         
         @param count: Number of items to be recommended (N for the top-N recommendation).
         
         
-        Optional parameters:
-        @param filter: Boolean-returning [ReQL](https://docs.recombee.com/reql.html) expression which allows you to filter recommended items based on the values of their attributes.
         
-        @param booster: Number-returning [ReQL](https://docs.recombee.com/reql.html) expression which allows you to boost recommendation rate of some items based on the values of their attributes.
+        Optional parameters:
+        @param scenario: Scenario defines a particular application of recommendations. It can be for example "homepage", "cart" or "emailing".
         
-        @param cascade_create: If the user does not exist in the database, returns a list of non-personalized recommendations and creates the user in the database. This allows for example rotations in the following recommendations for that user, as the user will be already known to the system.
         
-        @param scenario: Scenario defines a particular application of recommendations. It can be for example "homepage", "cart" or "emailing". You can see each scenario in the UI separately, so you can check how well each application performs. The AI which optimizes models in order to get the best results may optimize different scenarios separately, or even use different models in each of the scenarios.
+        You can set various settings to the [scenario](https://docs.recombee.com/scenarios.html) in the [Admin UI](https://admin.recombee.com). You can also see performance of each scenario in the Admin UI separately, so you can check how well each application performs.
         
-        @param logic: Logic specifies particular behavior of the recommendation models. You can pick tailored logic for your domain (e-commerce, multimedia, fashion ...) and use case.
         
-        See [this section](https://docs.recombee.com/recommendation_logic.html) for list of available logics and other details.
+        The AI which optimizes models in order to get the best results may optimize different scenarios separately, or even use different models in each of the scenarios.
         
         
-        The difference between `logic` and `scenario` is that `logic` specifies mainly behavior, while `scenario` specifies the place where recommendations are shown to the users.
+        @param cascade_create: If the user does not exist in the database, returns a list of non-personalized recommendations and creates the user in the database. This allows for example rotations in the following recommendations for that user, as the user will be already known to the system.
         
         
         @param return_properties: With `returnProperties=true`, property values of the recommended items are returned along with their IDs in a JSON dictionary. The acquired property values can be used for easy displaying of the recommended items to the user. 
@@ -136,6 +135,29 @@ def __init__(self, user_id, count, filter=DEFAULT, booster=DEFAULT, cascade_crea
         ```
         
         
+        @param filter: Boolean-returning [ReQL](https://docs.recombee.com/reql.html) expression which allows you to filter recommended items based on the values of their attributes.
+        
+        
+        Filters can be also assigned to a [scenario](https://docs.recombee.com/scenarios.html) in the [Admin UI](https://admin.recombee.com).
+        
+        
+        @param booster: Number-returning [ReQL](https://docs.recombee.com/reql.html) expression which allows you to boost recommendation rate of some items based on the values of their attributes.
+        
+        
+        Boosters can be also assigned to a [scenario](https://docs.recombee.com/scenarios.html) in the [Admin UI](https://admin.recombee.com).
+        
+        
+        @param logic: Logic specifies particular behavior of the recommendation models. You can pick tailored logic for your domain and use case.
+        
+        See [this section](https://docs.recombee.com/recommendation_logics.html) for list of available logics and other details.
+        
+        
+        The difference between `logic` and `scenario` is that `logic` specifies mainly behavior, while `scenario` specifies the place where recommendations are shown to the users.
+        
+        
+        Logic can be also set to a [scenario](https://docs.recombee.com/scenarios.html) in the [Admin UI](https://admin.recombee.com).
+        
+        
         @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.
         
         
@@ -157,13 +179,13 @@ def __init__(self, user_id, count, filter=DEFAULT, booster=DEFAULT, cascade_crea
         """
         self.user_id = user_id
         self.count = count
-        self.filter = filter
-        self.booster = booster
-        self.cascade_create = cascade_create
         self.scenario = scenario
-        self.logic = logic
+        self.cascade_create = cascade_create
         self.return_properties = return_properties
         self.included_properties = included_properties
+        self.filter = filter
+        self.booster = booster
+        self.logic = logic
         self.diversity = diversity
         self.min_relevance = min_relevance
         self.rotation_rate = rotation_rate
@@ -181,20 +203,20 @@ def get_body_parameters(self):
         """
         p = dict()
         p['count'] = self.count
-        if self.filter is not DEFAULT:
-            p['filter'] = self.filter
-        if self.booster is not DEFAULT:
-            p['booster'] = self.booster
-        if self.cascade_create is not DEFAULT:
-            p['cascadeCreate'] = self.cascade_create
         if self.scenario is not DEFAULT:
             p['scenario'] = self.scenario
-        if self.logic is not DEFAULT:
-            p['logic'] = self.logic
+        if self.cascade_create is not DEFAULT:
+            p['cascadeCreate'] = self.cascade_create
         if self.return_properties is not DEFAULT:
             p['returnProperties'] = self.return_properties
         if self.included_properties is not DEFAULT:
             p['includedProperties'] = self.included_properties
+        if self.filter is not DEFAULT:
+            p['filter'] = self.filter
+        if self.booster is not DEFAULT:
+            p['booster'] = self.booster
+        if self.logic is not DEFAULT:
+            p['logic'] = self.logic
         if self.diversity is not DEFAULT:
             p['diversity'] = self.diversity
         if self.min_relevance is not DEFAULT: