diff --git a/README.rst b/README.rst index 7d98d19..464dcaf 100644 --- a/README.rst +++ b/README.rst @@ -32,7 +32,7 @@ Basic example from recombee_api_client.api_client import RecombeeClient from recombee_api_client.exceptions import APIException - from recombee_api_client.api_requests import AddPurchase, RecommendItemsToUser, Batch + from recombee_api_client.api_requests import * import random client = RecombeeClient('--my-database-id--', '--db-private-token--') @@ -55,8 +55,12 @@ Basic example client.send(Batch(purchase_requests)) # Get recommendations for user 'user-25' - recommended = client.send(RecommendItemsToUser('user-25', 5)) - print("Recommended items: %s" % recommended) + response = client.send(RecommendItemsToUser('user-25', 5)) + print("Recommended items: %s" % response) + + # User scrolled down - get next 3 recommended items + response = client.send(RecommendNextItems(response['recommId'], 3)) + print("Next recommended items: %s" % response) except APIException as e: print(e) @@ -146,7 +150,7 @@ Using property values ) # Perform personalized full-text search with a user's search query (e.g. 'computers'). - matches = client.send(SearchItems('user-42', 'computers', 5)) + matches = client.send(SearchItems('user-42', 'computers', 5, scenario='search_top')) print("Matched items: %s" % matches) ------------------ @@ -160,7 +164,6 @@ 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: diff --git a/recombee_api_client/api_client.py b/recombee_api_client/api_client.py index f0c8bd8..d5ebd2a 100644 --- a/recombee_api_client/api_client.py +++ b/recombee_api_client/api_client.py @@ -16,15 +16,16 @@ class RecombeeClient: """ Client for sending requests to Recombee recommender system + + :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'. """ BATCH_MAX_SIZE = 10000 def __init__(self, database_id, token, protocol = 'https', 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 @@ -38,7 +39,7 @@ def __init__(self, database_id, token, protocol = 'https', options = {}): def send(self, request): """ - @param request: Request to be sent to Recombee recommender + :param request: Request to be sent to Recombee recommender """ if isinstance(request, Batch) and len(request.requests) > self.BATCH_MAX_SIZE: @@ -63,7 +64,7 @@ def send(self, request): @staticmethod def __get_http_headers(additional_headers=None): - headers = {'User-Agent': 'recombee-python-api-client/3.0.0'} + headers = {'User-Agent': 'recombee-python-api-client/3.1.0'} if additional_headers: headers.update(additional_headers) return headers diff --git a/recombee_api_client/api_requests/__init__.py b/recombee_api_client/api_requests/__init__.py index 3b5425a..f93a26d 100644 --- a/recombee_api_client/api_requests/__init__.py +++ b/recombee_api_client/api_requests/__init__.py @@ -54,8 +54,9 @@ from recombee_api_client.api_requests.list_item_view_portions import ListItemViewPortions from recombee_api_client.api_requests.list_user_view_portions import ListUserViewPortions from recombee_api_client.api_requests.recommend_items_to_user import RecommendItemsToUser -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_next_items import RecommendNextItems +from recombee_api_client.api_requests.recommend_users_to_user import RecommendUsersToUser 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 diff --git a/recombee_api_client/api_requests/add_bookmark.py b/recombee_api_client/api_requests/add_bookmark.py index 297afcd..ff6cfc7 100644 --- a/recombee_api_client/api_requests/add_bookmark.py +++ b/recombee_api_client/api_requests/add_bookmark.py @@ -6,27 +6,28 @@ class AddBookmark(Request): """ Adds a bookmark of a given item made by a given user. + + Required parameters: + + :param user_id: User who bookmarked the item + + :param item_id: Bookmarked item + + + Optional parameters: + + :param timestamp: UTC timestamp of the bookmark as ISO8601-1 pattern or UTC epoch time. The default value is the current time. + + :param cascade_create: Sets whether the given user/item should be created if not present in the database. + + :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. + """ 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 - - @param item_id: Bookmarked item - - - Optional parameters: - @param timestamp: UTC timestamp of the bookmark as ISO8601-1 pattern or UTC epoch time. The default value is the current time. - - @param cascade_create: Sets whether the given user/item should be created if not present in the database. - - @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 diff --git a/recombee_api_client/api_requests/add_cart_addition.py b/recombee_api_client/api_requests/add_cart_addition.py index 352f8c2..f4a1a78 100644 --- a/recombee_api_client/api_requests/add_cart_addition.py +++ b/recombee_api_client/api_requests/add_cart_addition.py @@ -6,31 +6,32 @@ class AddCartAddition(Request): """ Adds a cart addition of a given item made by a given user. + + Required parameters: + + :param user_id: User who added the item to the cart + + :param item_id: Item added to the cart + + + Optional parameters: + + :param timestamp: UTC timestamp of the cart addition as ISO8601-1 pattern or UTC epoch time. The default value is the current time. + + :param cascade_create: Sets whether the given user/item should be created if not present in the database. + + :param amount: Amount (number) added to cart. The default is 1. For example if `user-x` adds two `item-y` during a single order (session...), the `amount` should equal to 2. + + :param price: Price of the added item. If `amount` is greater than 1, sum of prices of all the items should be given. + + :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. + """ 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 - - @param item_id: Item added to the cart - - - Optional parameters: - @param timestamp: UTC timestamp of the cart addition as ISO8601-1 pattern or UTC epoch time. The default value is the current time. - - @param cascade_create: Sets whether the given user/item should be created if not present in the database. - - @param amount: Amount (number) added to cart. The default is 1. For example if `user-x` adds two `item-y` during a single order (session...), the `amount` should equal to 2. - - @param price: Price of the added item. If `amount` is greater than 1, sum of prices of all the items should be given. - - @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 self.timestamp = timestamp diff --git a/recombee_api_client/api_requests/add_detail_view.py b/recombee_api_client/api_requests/add_detail_view.py index 8398320..ad502f9 100644 --- a/recombee_api_client/api_requests/add_detail_view.py +++ b/recombee_api_client/api_requests/add_detail_view.py @@ -6,29 +6,30 @@ class AddDetailView(Request): """ Adds a detail view of a given item made by a given user. + + Required parameters: + + :param user_id: User who viewed the item + + :param item_id: Viewed item + + + Optional parameters: + + :param timestamp: UTC timestamp of the view as ISO8601-1 pattern or UTC epoch time. The default value is the current time. + + :param duration: Duration of the view + + :param cascade_create: Sets whether the given user/item should be created if not present in the database. + + :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. + """ 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 - - @param item_id: Viewed item - - - Optional parameters: - @param timestamp: UTC timestamp of the view as ISO8601-1 pattern or UTC epoch time. The default value is the current time. - - @param duration: Duration of the view - - @param cascade_create: Sets whether the given user/item should be created if not present in the database. - - @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 diff --git a/recombee_api_client/api_requests/add_group.py b/recombee_api_client/api_requests/add_group.py index 4b571a3..d62984d 100644 --- a/recombee_api_client/api_requests/add_group.py +++ b/recombee_api_client/api_requests/add_group.py @@ -6,14 +6,14 @@ class AddGroup(Request): """ Creates new group in the database. + Required parameters: + + :param group_id: ID of the group to be created. + + """ def __init__(self, group_id): - """ - Required parameters: - @param group_id: ID of the group to be created. - - """ self.group_id = group_id self.timeout = 1000 self.ensure_https = False diff --git a/recombee_api_client/api_requests/add_item.py b/recombee_api_client/api_requests/add_item.py index 76cbe1b..73076fe 100644 --- a/recombee_api_client/api_requests/add_item.py +++ b/recombee_api_client/api_requests/add_item.py @@ -8,15 +8,15 @@ class AddItem(Request): Adds new item of given `itemId` to the items catalog. All the item properties for the newly created items are set null. + + Required parameters: + + :param item_id: ID of the item to be created. + """ def __init__(self, item_id): - """ - Required parameters: - @param item_id: ID of the item to be created. - - """ self.item_id = item_id self.timeout = 1000 self.ensure_https = False diff --git a/recombee_api_client/api_requests/add_item_property.py b/recombee_api_client/api_requests/add_item_property.py index 0764aac..d01cc4a 100644 --- a/recombee_api_client/api_requests/add_item_property.py +++ b/recombee_api_client/api_requests/add_item_property.py @@ -6,43 +6,43 @@ class AddItemProperty(Request): """ Adding an item property is somehow equivalent to adding a column to the table of items. The items may be characterized by various properties of different types. + + Required parameters: + + :param property_name: Name of the item property to be created. Currently, the following names are reserved:`id`, `itemid`, case insensitively. Also, the length of the property name must not exceed 63 characters. + + + :param type: Value type of the item property to be created. One of: `int`, `double`, `string`, `boolean`, `timestamp`, `set`, `image` or `imageList`. + + + * `int`- Signed integer number. + + + * `double` - Floating point number. It uses 64-bit base-2 format (IEEE 754 standard). + + + * `string` - UTF-8 string. + + + * `boolean` - *true* / *false* + + + * `timestamp` - Value representing date and time. + + + * `set` - Set of strings. + + + * `image` - URL of an image (`jpeg`, `png` or `gif`). + + + * `imageList` - List of URLs that refer to images. + + """ def __init__(self, property_name, type): - """ - Required parameters: - @param property_name: Name of the item property to be created. Currently, the following names are reserved:`id`, `itemid`, case insensitively. Also, the length of the property name must not exceed 63 characters. - - - @param type: Value type of the item property to be created. One of: `int`, `double`, `string`, `boolean`, `timestamp`, `set`, `image` or `imageList`. - - - * `int`- Signed integer number. - - - * `double` - Floating point number. It uses 64-bit base-2 format (IEEE 754 standard). - - - * `string` - UTF-8 string. - - - * `boolean` - *true* / *false* - - - * `timestamp` - Value representing date and time. - - - * `set` - Set of strings. - - - * `image` - URL of an image (`jpeg`, `png` or `gif`). - - - * `imageList` - List of URLs that refer to images. - - - """ self.property_name = property_name self.type = type self.timeout = 100000 diff --git a/recombee_api_client/api_requests/add_purchase.py b/recombee_api_client/api_requests/add_purchase.py index 29d8821..1ae91fc 100644 --- a/recombee_api_client/api_requests/add_purchase.py +++ b/recombee_api_client/api_requests/add_purchase.py @@ -6,33 +6,34 @@ class AddPurchase(Request): """ Adds a purchase of a given item made by a given user. + + Required parameters: + + :param user_id: User who purchased the item + + :param item_id: Purchased item + + + Optional parameters: + + :param timestamp: UTC timestamp of the purchase as ISO8601-1 pattern or UTC epoch time. The default value is the current time. + + :param cascade_create: Sets whether the given user/item should be created if not present in the database. + + :param amount: Amount (number) of purchased items. The default is 1. For example if `user-x` purchases two `item-y` during a single order (session...), the `amount` should equal to 2. + + :param price: Price paid by the user for the item. If `amount` is greater than 1, sum of prices of all the items should be given. + + :param profit: Your profit from the purchased item. The profit is natural in e-commerce domain (for example if `user-x` purchases `item-y` for $100 and the gross margin is 30 %, then the profit is $30), but is applicable also in other domains (for example at a news company it may be income from displayed advertisement on article page). If `amount` is greater than 1, sum of profit of all the items should be given. + + :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. + """ 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 - - @param item_id: Purchased item - - - Optional parameters: - @param timestamp: UTC timestamp of the purchase as ISO8601-1 pattern or UTC epoch time. The default value is the current time. - - @param cascade_create: Sets whether the given user/item should be created if not present in the database. - - @param amount: Amount (number) of purchased items. The default is 1. For example if `user-x` purchases two `item-y` during a single order (session...), the `amount` should equal to 2. - - @param price: Price paid by the user for the item. If `amount` is greater than 1, sum of prices of all the items should be given. - - @param profit: Your profit from the purchased item. The profit is natural in e-commerce domain (for example if `user-x` purchases `item-y` for $100 and the gross margin is 30 %, then the profit is $30), but is applicable also in other domains (for example at a news company it may be income from displayed advertisement on article page). If `amount` is greater than 1, sum of profit of all the items should be given. - - @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 self.timestamp = timestamp diff --git a/recombee_api_client/api_requests/add_rating.py b/recombee_api_client/api_requests/add_rating.py index 6145b97..f61f02b 100644 --- a/recombee_api_client/api_requests/add_rating.py +++ b/recombee_api_client/api_requests/add_rating.py @@ -6,29 +6,30 @@ class AddRating(Request): """ Adds a rating of given item made by a given user. + + Required parameters: + + :param user_id: User who submitted the rating + + :param item_id: Rated item + + :param rating: Rating rescaled to interval [-1.0,1.0], where -1.0 means the worst rating possible, 0.0 means neutral, and 1.0 means absolutely positive rating. For example, in the case of 5-star evaluations, rating = (numStars-3)/2 formula may be used for the conversion. + + + Optional parameters: + + :param timestamp: UTC timestamp of the rating as ISO8601-1 pattern or UTC epoch time. The default value is the current time. + + :param cascade_create: Sets whether the given user/item should be created if not present in the database. + + :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. + """ 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 - - @param item_id: Rated item - - @param rating: Rating rescaled to interval [-1.0,1.0], where -1.0 means the worst rating possible, 0.0 means neutral, and 1.0 means absolutely positive rating. For example, in the case of 5-star evaluations, rating = (numStars-3)/2 formula may be used for the conversion. - - - Optional parameters: - @param timestamp: UTC timestamp of the rating as ISO8601-1 pattern or UTC epoch time. The default value is the current time. - - @param cascade_create: Sets whether the given user/item should be created if not present in the database. - - @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 diff --git a/recombee_api_client/api_requests/add_series.py b/recombee_api_client/api_requests/add_series.py index 67b4d18..89a25b6 100644 --- a/recombee_api_client/api_requests/add_series.py +++ b/recombee_api_client/api_requests/add_series.py @@ -6,14 +6,14 @@ class AddSeries(Request): """ Creates new series in the database. + Required parameters: + + :param series_id: ID of the series to be created. + + """ def __init__(self, series_id): - """ - Required parameters: - @param series_id: ID of the series to be created. - - """ self.series_id = series_id self.timeout = 1000 self.ensure_https = False diff --git a/recombee_api_client/api_requests/add_user.py b/recombee_api_client/api_requests/add_user.py index 4b9b256..146e7ba 100644 --- a/recombee_api_client/api_requests/add_user.py +++ b/recombee_api_client/api_requests/add_user.py @@ -6,15 +6,15 @@ class AddUser(Request): """ Adds a new user to the database. + + Required parameters: + + :param user_id: ID of the user to be added. + """ def __init__(self, user_id): - """ - Required parameters: - @param user_id: ID of the user to be added. - - """ self.user_id = user_id self.timeout = 1000 self.ensure_https = False diff --git a/recombee_api_client/api_requests/add_user_property.py b/recombee_api_client/api_requests/add_user_property.py index daf1144..80f5024 100644 --- a/recombee_api_client/api_requests/add_user_property.py +++ b/recombee_api_client/api_requests/add_user_property.py @@ -6,37 +6,37 @@ 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. + + 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`. + + + * `int` - Signed integer number. + + + * `double` - Floating point number. It uses 64-bit base-2 format (IEEE 754 standard). + + + * `string` - UTF-8 string. + + + * `boolean` - *true* / *false* + + + * `timestamp` - Value representing date and time. + + + * `set` - Set of strings. + + """ 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`. - - - * `int` - Signed integer number. - - - * `double` - Floating point number. It uses 64-bit base-2 format (IEEE 754 standard). - - - * `string` - UTF-8 string. - - - * `boolean` - *true* / *false* - - - * `timestamp` - Value representing date and time. - - - * `set` - Set of strings. - - - """ self.property_name = property_name self.type = type self.timeout = 100000 diff --git a/recombee_api_client/api_requests/batch.py b/recombee_api_client/api_requests/batch.py index 8283ae9..7b2f218 100644 --- a/recombee_api_client/api_requests/batch.py +++ b/recombee_api_client/api_requests/batch.py @@ -12,13 +12,12 @@ 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, + + :param requests: List of Requests. + :param distinctRecomms: Makes all the recommended items for a certain user distinct among multiple recommendation requests in the batch. """ def __init__(self, requests, distinctRecomms=None): - """ - @param requests: List of Requests. - @param distinctRecomms: Makes all the recommended items for a certain user distinct among multiple recommendation requests in the batch. - """ self.requests = requests self.distinctRecomms = distinctRecomms self.timeout = sum([req.timeout for req in self.requests]) diff --git a/recombee_api_client/api_requests/delete_bookmark.py b/recombee_api_client/api_requests/delete_bookmark.py index 2d52bea..e3bef2c 100644 --- a/recombee_api_client/api_requests/delete_bookmark.py +++ b/recombee_api_client/api_requests/delete_bookmark.py @@ -6,21 +6,22 @@ class DeleteBookmark(Request): """ Deletes a bookmark uniquely specified by `userId`, `itemId`, and `timestamp` or all the bookmarks with given `userId` and `itemId` if `timestamp` is omitted. + + Required parameters: + + :param user_id: ID of the user who made the bookmark. + + :param item_id: ID of the item of which was bookmarked. + + + Optional parameters: + + :param timestamp: Unix timestamp of the bookmark. If the `timestamp` is omitted, then all the bookmarks with given `userId` and `itemId` are deleted. + """ def __init__(self, user_id, item_id, timestamp=DEFAULT): - """ - Required parameters: - @param user_id: ID of the user who made the bookmark. - - @param item_id: ID of the item of which was bookmarked. - - - Optional parameters: - @param timestamp: Unix timestamp of the bookmark. If the `timestamp` is omitted, then all the bookmarks with given `userId` and `itemId` are deleted. - - """ self.user_id = user_id self.item_id = item_id self.timestamp = timestamp diff --git a/recombee_api_client/api_requests/delete_cart_addition.py b/recombee_api_client/api_requests/delete_cart_addition.py index 9a4796e..9601325 100644 --- a/recombee_api_client/api_requests/delete_cart_addition.py +++ b/recombee_api_client/api_requests/delete_cart_addition.py @@ -6,21 +6,22 @@ class DeleteCartAddition(Request): """ Deletes an existing cart addition uniquely specified by `userId`, `itemId`, and `timestamp` or all the cart additions with given `userId` and `itemId` if `timestamp` is omitted. + + Required parameters: + + :param user_id: ID of the user who made the cart addition. + + :param item_id: ID of the item of which was added to cart. + + + Optional parameters: + + :param timestamp: Unix timestamp of the cart addition. If the `timestamp` is omitted, then all the cart additions with given `userId` and `itemId` are deleted. + """ def __init__(self, user_id, item_id, timestamp=DEFAULT): - """ - Required parameters: - @param user_id: ID of the user who made the cart addition. - - @param item_id: ID of the item of which was added to cart. - - - Optional parameters: - @param timestamp: Unix timestamp of the cart addition. If the `timestamp` is omitted, then all the cart additions with given `userId` and `itemId` are deleted. - - """ self.user_id = user_id self.item_id = item_id self.timestamp = timestamp diff --git a/recombee_api_client/api_requests/delete_detail_view.py b/recombee_api_client/api_requests/delete_detail_view.py index 9bef838..3bee123 100644 --- a/recombee_api_client/api_requests/delete_detail_view.py +++ b/recombee_api_client/api_requests/delete_detail_view.py @@ -6,21 +6,22 @@ class DeleteDetailView(Request): """ Deletes an existing detail view uniquely specified by (`userId`, `itemId`, and `timestamp`) or all the detail views with given `userId` and `itemId` if `timestamp` is omitted. + + Required parameters: + + :param user_id: ID of the user who made the detail view. + + :param item_id: ID of the item of which the details were viewed. + + + Optional parameters: + + :param timestamp: Unix timestamp of the detail view. If the `timestamp` is omitted, then all the detail views with given `userId` and `itemId` are deleted. + """ def __init__(self, user_id, item_id, timestamp=DEFAULT): - """ - Required parameters: - @param user_id: ID of the user who made the detail view. - - @param item_id: ID of the item of which the details were viewed. - - - Optional parameters: - @param timestamp: Unix timestamp of the detail view. If the `timestamp` is omitted, then all the detail views with given `userId` and `itemId` are deleted. - - """ self.user_id = user_id self.item_id = item_id self.timestamp = timestamp diff --git a/recombee_api_client/api_requests/delete_group.py b/recombee_api_client/api_requests/delete_group.py index fc3f7b4..8487b16 100644 --- a/recombee_api_client/api_requests/delete_group.py +++ b/recombee_api_client/api_requests/delete_group.py @@ -8,15 +8,15 @@ class DeleteGroup(Request): Deletes the group of given `groupId` from the database. Deleting a group will only delete assignment of items to it, not the items themselves! + + Required parameters: + + :param group_id: ID of the group to be deleted. + """ def __init__(self, group_id): - """ - Required parameters: - @param group_id: ID of the group to be deleted. - - """ self.group_id = group_id self.timeout = 1000 self.ensure_https = False diff --git a/recombee_api_client/api_requests/delete_item.py b/recombee_api_client/api_requests/delete_item.py index 658a70f..e5635de 100644 --- a/recombee_api_client/api_requests/delete_item.py +++ b/recombee_api_client/api_requests/delete_item.py @@ -10,15 +10,15 @@ class DeleteItem(Request): If there are any *purchases*, *ratings*, *bookmarks*, *cart additions* or *detail views* of the item present in the database, they will be deleted in cascade as well. Also, if the item is present in some *series*, it will be removed from all the *series* where present. If an item becomes obsolete/no longer available, it is often meaningful to keep it in the catalog (along with all the interaction data, which are very useful), and only exclude the item from recommendations. In such a case, use [ReQL filter](https://docs.recombee.com/reql.html) instead of deleting the item completely. + + Required parameters: + + :param item_id: ID of the item to be deleted. + """ def __init__(self, item_id): - """ - Required parameters: - @param item_id: ID of the item to be deleted. - - """ self.item_id = item_id self.timeout = 1000 self.ensure_https = False diff --git a/recombee_api_client/api_requests/delete_item_property.py b/recombee_api_client/api_requests/delete_item_property.py index 0011b9b..f68c63e 100644 --- a/recombee_api_client/api_requests/delete_item_property.py +++ b/recombee_api_client/api_requests/delete_item_property.py @@ -6,15 +6,15 @@ class DeleteItemProperty(Request): """ Deleting an item property is roughly equivalent to removing a column from the table of items. + + Required parameters: + + :param property_name: Name of the property to be deleted. + """ def __init__(self, property_name): - """ - Required parameters: - @param property_name: Name of the property to be deleted. - - """ self.property_name = property_name self.timeout = 100000 self.ensure_https = False diff --git a/recombee_api_client/api_requests/delete_purchase.py b/recombee_api_client/api_requests/delete_purchase.py index cdc4977..e05d2e7 100644 --- a/recombee_api_client/api_requests/delete_purchase.py +++ b/recombee_api_client/api_requests/delete_purchase.py @@ -6,21 +6,22 @@ class DeletePurchase(Request): """ Deletes an existing purchase uniquely specified by `userId`, `itemId`, and `timestamp` or all the purchases with given `userId` and `itemId` if `timestamp` is omitted. + + Required parameters: + + :param user_id: ID of the user who made the purchase. + + :param item_id: ID of the item of which was purchased. + + + Optional parameters: + + :param timestamp: Unix timestamp of the purchase. If the `timestamp` is omitted, then all the purchases with given `userId` and `itemId` are deleted. + """ def __init__(self, user_id, item_id, timestamp=DEFAULT): - """ - Required parameters: - @param user_id: ID of the user who made the purchase. - - @param item_id: ID of the item of which was purchased. - - - Optional parameters: - @param timestamp: Unix timestamp of the purchase. If the `timestamp` is omitted, then all the purchases with given `userId` and `itemId` are deleted. - - """ self.user_id = user_id self.item_id = item_id self.timestamp = timestamp diff --git a/recombee_api_client/api_requests/delete_rating.py b/recombee_api_client/api_requests/delete_rating.py index 788a819..940fe92 100644 --- a/recombee_api_client/api_requests/delete_rating.py +++ b/recombee_api_client/api_requests/delete_rating.py @@ -6,21 +6,22 @@ class DeleteRating(Request): """ Deletes an existing rating specified by (`userId`, `itemId`, `timestamp`) from the database or all the ratings with given `userId` and `itemId` if `timestamp` is omitted. + + Required parameters: + + :param user_id: ID of the user who rated the item. + + :param item_id: ID of the item which was rated. + + + Optional parameters: + + :param timestamp: Unix timestamp of the rating. If the `timestamp` is omitted, then all the ratings with given `userId` and `itemId` are deleted. + """ def __init__(self, user_id, item_id, timestamp=DEFAULT): - """ - Required parameters: - @param user_id: ID of the user who rated the item. - - @param item_id: ID of the item which was rated. - - - Optional parameters: - @param timestamp: Unix timestamp of the rating. If the `timestamp` is omitted, then all the ratings with given `userId` and `itemId` are deleted. - - """ self.user_id = user_id self.item_id = item_id self.timestamp = timestamp diff --git a/recombee_api_client/api_requests/delete_series.py b/recombee_api_client/api_requests/delete_series.py index 856655f..e249633 100644 --- a/recombee_api_client/api_requests/delete_series.py +++ b/recombee_api_client/api_requests/delete_series.py @@ -8,15 +8,15 @@ class DeleteSeries(Request): Deletes the series of given `seriesId` from the database. Deleting a series will only delete assignment of items to it, not the items themselves! + + Required parameters: + + :param series_id: ID of the series to be deleted. + """ def __init__(self, series_id): - """ - Required parameters: - @param series_id: ID of the series to be deleted. - - """ self.series_id = series_id self.timeout = 1000 self.ensure_https = False diff --git a/recombee_api_client/api_requests/delete_user.py b/recombee_api_client/api_requests/delete_user.py index 597e988..2764d2e 100644 --- a/recombee_api_client/api_requests/delete_user.py +++ b/recombee_api_client/api_requests/delete_user.py @@ -8,15 +8,15 @@ class DeleteUser(Request): Deletes a user of given *userId* from the database. If there are any purchases, ratings, bookmarks, cart additions or detail views made by the user present in the database, they will be deleted in cascade as well. + + Required parameters: + + :param user_id: ID of the user to be added. + """ def __init__(self, user_id): - """ - Required parameters: - @param user_id: ID of the user to be added. - - """ self.user_id = user_id self.timeout = 1000 self.ensure_https = False diff --git a/recombee_api_client/api_requests/delete_user_property.py b/recombee_api_client/api_requests/delete_user_property.py index a0d4c26..69ed112 100644 --- a/recombee_api_client/api_requests/delete_user_property.py +++ b/recombee_api_client/api_requests/delete_user_property.py @@ -6,15 +6,15 @@ class DeleteUserProperty(Request): """ Deleting an user property is roughly equivalent to removing a column from the table of users. + + Required parameters: + + :param property_name: Name of the property to be deleted. + """ def __init__(self, property_name): - """ - Required parameters: - @param property_name: Name of the property to be deleted. - - """ self.property_name = property_name self.timeout = 100000 self.ensure_https = False diff --git a/recombee_api_client/api_requests/delete_view_portion.py b/recombee_api_client/api_requests/delete_view_portion.py index c8466dd..eb2fc25 100644 --- a/recombee_api_client/api_requests/delete_view_portion.py +++ b/recombee_api_client/api_requests/delete_view_portion.py @@ -6,21 +6,22 @@ class DeleteViewPortion(Request): """ Deletes an existing view portion specified by (`userId`, `itemId`, `sessionId`) from the database. + + Required parameters: + + :param user_id: ID of the user who rated the item. + + :param item_id: ID of the item which was rated. + + + Optional parameters: + + :param session_id: Identifier of a session. + """ def __init__(self, user_id, item_id, session_id=DEFAULT): - """ - Required parameters: - @param user_id: ID of the user who rated the item. - - @param item_id: ID of the item which was rated. - - - Optional parameters: - @param session_id: Identifier of a session. - - """ self.user_id = user_id self.item_id = item_id self.session_id = session_id diff --git a/recombee_api_client/api_requests/get_item_property_info.py b/recombee_api_client/api_requests/get_item_property_info.py index 694eb17..2854c2b 100644 --- a/recombee_api_client/api_requests/get_item_property_info.py +++ b/recombee_api_client/api_requests/get_item_property_info.py @@ -6,15 +6,15 @@ class GetItemPropertyInfo(Request): """ Gets information about specified item property. + + Required parameters: + + :param property_name: Name of the property about which the information is to be retrieved. + """ 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 diff --git a/recombee_api_client/api_requests/get_item_values.py b/recombee_api_client/api_requests/get_item_values.py index 70ef3e6..8923fe8 100644 --- a/recombee_api_client/api_requests/get_item_values.py +++ b/recombee_api_client/api_requests/get_item_values.py @@ -6,16 +6,16 @@ class GetItemValues(Request): """ Get all the current property values of a given item. + + Required parameters: + + :param item_id: ID of the item properties of which are to be obtained. + + """ def __init__(self, item_id): - """ - Required parameters: - @param item_id: ID of the item properties of which are to be obtained. - - - """ self.item_id = item_id self.timeout = 1000 self.ensure_https = False diff --git a/recombee_api_client/api_requests/get_user_property_info.py b/recombee_api_client/api_requests/get_user_property_info.py index 6d4b527..ebec153 100644 --- a/recombee_api_client/api_requests/get_user_property_info.py +++ b/recombee_api_client/api_requests/get_user_property_info.py @@ -6,15 +6,15 @@ class GetUserPropertyInfo(Request): """ Gets information about specified user property. + + Required parameters: + + :param property_name: Name of the property about which the information is to be retrieved. + """ 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 = 100000 self.ensure_https = False diff --git a/recombee_api_client/api_requests/get_user_values.py b/recombee_api_client/api_requests/get_user_values.py index 7a2710d..083d5da 100644 --- a/recombee_api_client/api_requests/get_user_values.py +++ b/recombee_api_client/api_requests/get_user_values.py @@ -6,16 +6,16 @@ class GetUserValues(Request): """ Get all the current property values of a given user. + + Required parameters: + + :param user_id: ID of the user properties of which are to be obtained. + + """ 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 diff --git a/recombee_api_client/api_requests/insert_to_group.py b/recombee_api_client/api_requests/insert_to_group.py index 0c86a82..873773e 100644 --- a/recombee_api_client/api_requests/insert_to_group.py +++ b/recombee_api_client/api_requests/insert_to_group.py @@ -6,23 +6,24 @@ class InsertToGroup(Request): """ Inserts an existing item/group into group of given `groupId`. + + Required parameters: + + :param group_id: ID of the group to be inserted into. + + :param item_type: `item` iff the regular item from the catalog is to be inserted, `group` iff group is inserted as the item. + + :param item_id: ID of the item iff `itemType` is `item`. ID of the group iff `itemType` is `group`. + + + Optional parameters: + + :param cascade_create: Indicates that any non-existing entity specified within the request should be created (as is corresponding PUT requests were invoked). This concerns both the `groupId` and the `groupId`. If `cascadeCreate` is set true, the behavior also depends on the `itemType`. Either items or group may be created if not present in the database. + """ def __init__(self, group_id, item_type, item_id, cascade_create=DEFAULT): - """ - Required parameters: - @param group_id: ID of the group to be inserted into. - - @param item_type: `item` iff the regular item from the catalog is to be inserted, `group` iff group is inserted as the item. - - @param item_id: ID of the item iff `itemType` is `item`. ID of the group iff `itemType` is `group`. - - - Optional parameters: - @param cascade_create: Indicates that any non-existing entity specified within the request should be created (as is corresponding PUT requests were invoked). This concerns both the `groupId` and the `groupId`. If `cascadeCreate` is set true, the behavior also depends on the `itemType`. Either items or group may be created if not present in the database. - - """ self.group_id = group_id self.item_type = item_type self.item_id = item_id diff --git a/recombee_api_client/api_requests/insert_to_series.py b/recombee_api_client/api_requests/insert_to_series.py index 38833eb..07b3321 100644 --- a/recombee_api_client/api_requests/insert_to_series.py +++ b/recombee_api_client/api_requests/insert_to_series.py @@ -6,25 +6,26 @@ class InsertToSeries(Request): """ Inserts an existing item/series into series of given seriesId at position determined by time. + + Required parameters: + + :param series_id: ID of the series to be inserted into. + + :param item_type: `item` iff the regular item from the catalog is to be inserted, `series` iff series is inserted as the item. + + :param item_id: ID of the item iff `itemType` is `item`. ID of the series iff `itemType` is `series`. + + :param time: Time index used for sorting items in the series. According to time, items are sorted within series in ascending order. In the example of TV show episodes, the episode number is a natural choice to be passed as time. + + + Optional parameters: + + :param cascade_create: Indicates that any non-existing entity specified within the request should be created (as is corresponding PUT requests were invoked). This concerns both the `seriesId` and the `itemId`. If `cascadeCreate` is set true, the behavior also depends on the `itemType`. Either item or series may be created if not present in the database. + """ def __init__(self, series_id, item_type, item_id, time, cascade_create=DEFAULT): - """ - Required parameters: - @param series_id: ID of the series to be inserted into. - - @param item_type: `item` iff the regular item from the catalog is to be inserted, `series` iff series is inserted as the item. - - @param item_id: ID of the item iff `itemType` is `item`. ID of the series iff `itemType` is `series`. - - @param time: Time index used for sorting items in the series. According to time, items are sorted within series in ascending order. In the example of TV show episodes, the episode number is a natural choice to be passed as time. - - - Optional parameters: - @param cascade_create: Indicates that any non-existing entity specified within the request should be created (as is corresponding PUT requests were invoked). This concerns both the `seriesId` and the `itemId`. If `cascadeCreate` is set true, the behavior also depends on the `itemType`. Either item or series may be created if not present in the database. - - """ self.series_id = series_id self.item_type = item_type self.item_id = item_id diff --git a/recombee_api_client/api_requests/item_based_recommendation.py b/recombee_api_client/api_requests/item_based_recommendation.py index a528abe..7d46c8e 100644 --- a/recombee_api_client/api_requests/item_based_recommendation.py +++ b/recombee_api_client/api_requests/item_based_recommendation.py @@ -10,135 +10,136 @@ class ItemBasedRecommendation(Request): Recommends set of items that are somehow related to one given item, *X*. Typical scenario for using item-based recommendation is when user *A* is viewing *X*. Then you may display items to the user that he might be also interested in. Item-recommendation 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. + + Required parameters: + + :param item_id: ID of the item for which the recommendations are to be generated. + + :param count: Number of items to be recommended (N for the top-N recommendation). + + + 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 the calculation 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. + + + For the above reasons, we encourage you to set the *targetUserId* even for anonymous/unregistered users (i.e. use their session ID). + + + :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`. + + + :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 allow_nonexistent: Instead of causing HTTP 404 error, returns some (non-personalized) recommendations if either item of given *itemId* or user of given *targetUserId* does not exist in the database. It creates neither of the missing entities in the database. + + :param cascade_create: If item of given *itemId* or user of given *targetUserId* doesn't exist in the database, it creates the missing enity/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. + + :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. + + + Example response: + + ``` + + [ + + E{lb} + + "itemId": "tv-178", + + "description": "4K TV with 3D feature", + + "categories": ["Electronics", "Televisions"], + + "price": 342, + + "url": "myshop.com/tv-178" + E{rb}, + + E{lb} + + "itemId": "mixer-42", + + "description": "Stainless Steel Mixer", + + "categories": ["Home & Kitchen"], + + "price": 39, + + "url": "myshop.com/mixer-42" + E{rb} + + ] + + ``` + + + :param included_properties: Allows to specify, which properties should be returned when `returnProperties=true` is set. The properties are given as a comma-separated list. + + + Example response for `includedProperties=description,price`: + + ``` + + [ + + E{lb} + + "itemId": "tv-178", + + "description": "4K TV with 3D feature", + + "price": 342 + E{rb}, + + E{lb} + + "itemId": "mixer-42", + + "description": "Stainless Steel Mixer", + + "price": 39 + E{rb} + + ] + + ``` + + + :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** 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 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. Default: `0.01`. + + + :param rotation_time: **Expert option** If the *targetUserId* is provided: Taking *rotationRate* into account, specifies how long time it takes to an item to recover from the penalization. For example, `rotationTime=7200.0` means that items recommended less than 2 hours ago are penalized. Default: `7200.0`. + + + :param expert_settings: Dictionary of custom options. + + """ def __init__(self, item_id, count, target_user_id=DEFAULT, user_impact=DEFAULT, filter=DEFAULT, booster=DEFAULT, allow_nonexistent=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): - """ - Required parameters: - @param item_id: ID of the item for which the recommendations are to be generated. - - @param count: Number of items to be recommended (N for the top-N recommendation). - - - 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 the calculation 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. - - - For the above reasons, we encourage you to set the *targetUserId* even for anonymous/unregistered users (i.e. use their session ID). - - - @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`. - - - @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 allow_nonexistent: Instead of causing HTTP 404 error, returns some (non-personalized) recommendations if either item of given *itemId* or user of given *targetUserId* does not exist in the database. It creates neither of the missing entities in the database. - - @param cascade_create: If item of given *itemId* or user of given *targetUserId* doesn't exist in the database, it creates the missing enity/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. - - @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. - - - Example response: - - ``` - - [ - - E{lb} - - "itemId": "tv-178", - - "description": "4K TV with 3D feature", - - "categories": ["Electronics", "Televisions"], - - "price": 342, - - "url": "myshop.com/tv-178" - E{rb}, - - E{lb} - - "itemId": "mixer-42", - - "description": "Stainless Steel Mixer", - - "categories": ["Home & Kitchen"], - - "price": 39, - - "url": "myshop.com/mixer-42" - E{rb} - - ] - - ``` - - - @param included_properties: Allows to specify, which properties should be returned when `returnProperties=true` is set. The properties are given as a comma-separated list. - - - Example response for `includedProperties=description,price`: - - ``` - - [ - - E{lb} - - "itemId": "tv-178", - - "description": "4K TV with 3D feature", - - "price": 342 - E{rb}, - - E{lb} - - "itemId": "mixer-42", - - "description": "Stainless Steel Mixer", - - "price": 39 - E{rb} - - ] - - ``` - - - @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** 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 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. Default: `0.01`. - - - @param rotation_time: **Expert option** If the *targetUserId* is provided: Taking *rotationRate* into account, specifies how long time it takes to an item to recover from the penalization. For example, `rotationTime=7200.0` means that items recommended less than 2 hours ago are penalized. Default: `7200.0`. - - - @param expert_settings: Dictionary of custom options. - - - """ self.item_id = item_id self.count = count self.target_user_id = target_user_id diff --git a/recombee_api_client/api_requests/list_group_items.py b/recombee_api_client/api_requests/list_group_items.py index 5c49d30..ddedaa5 100644 --- a/recombee_api_client/api_requests/list_group_items.py +++ b/recombee_api_client/api_requests/list_group_items.py @@ -6,14 +6,14 @@ class ListGroupItems(Request): """ List all the items present in the given group. + Required parameters: + + :param group_id: ID of the group items of which are to be listed. + + """ def __init__(self, group_id): - """ - Required parameters: - @param group_id: ID of the group items of which are to be listed. - - """ self.group_id = group_id self.timeout = 100000 self.ensure_https = False diff --git a/recombee_api_client/api_requests/list_groups.py b/recombee_api_client/api_requests/list_groups.py index badc5ca..dc00ee4 100644 --- a/recombee_api_client/api_requests/list_groups.py +++ b/recombee_api_client/api_requests/list_groups.py @@ -6,11 +6,10 @@ class ListGroups(Request): """ Gets the list of all the groups currently present in the database. + """ def __init__(self): - """ - """ self.timeout = 100000 self.ensure_https = False self.method = 'get' diff --git a/recombee_api_client/api_requests/list_item_bookmarks.py b/recombee_api_client/api_requests/list_item_bookmarks.py index f1105c9..f3372ce 100644 --- a/recombee_api_client/api_requests/list_item_bookmarks.py +++ b/recombee_api_client/api_requests/list_item_bookmarks.py @@ -6,15 +6,15 @@ class ListItemBookmarks(Request): """ List all the ever-made bookmarks of a given item. + Required parameters: + + :param item_id: ID of the item of which the bookmarks are to be listed. + + + """ def __init__(self, item_id): - """ - Required parameters: - @param item_id: ID of the item of which the bookmarks are to be listed. - - - """ self.item_id = item_id self.timeout = 100000 self.ensure_https = False diff --git a/recombee_api_client/api_requests/list_item_cart_additions.py b/recombee_api_client/api_requests/list_item_cart_additions.py index e3032ba..a541506 100644 --- a/recombee_api_client/api_requests/list_item_cart_additions.py +++ b/recombee_api_client/api_requests/list_item_cart_additions.py @@ -6,15 +6,15 @@ class ListItemCartAdditions(Request): """ List all the ever-made cart addition of a given item. + Required parameters: + + :param item_id: ID of the item of which the cart addition are to be listed. + + + """ def __init__(self, item_id): - """ - Required parameters: - @param item_id: ID of the item of which the cart addition are to be listed. - - - """ self.item_id = item_id self.timeout = 100000 self.ensure_https = False diff --git a/recombee_api_client/api_requests/list_item_detail_views.py b/recombee_api_client/api_requests/list_item_detail_views.py index d0c2364..c876385 100644 --- a/recombee_api_client/api_requests/list_item_detail_views.py +++ b/recombee_api_client/api_requests/list_item_detail_views.py @@ -6,15 +6,15 @@ class ListItemDetailViews(Request): """ List all the detail views of a given item ever made by different users. + Required parameters: + + :param item_id: ID of the item of which the detail views are to be listed. + + + """ def __init__(self, item_id): - """ - Required parameters: - @param item_id: ID of the item of which the detail views are to be listed. - - - """ self.item_id = item_id self.timeout = 100000 self.ensure_https = False diff --git a/recombee_api_client/api_requests/list_item_properties.py b/recombee_api_client/api_requests/list_item_properties.py index 9892e50..46fc830 100644 --- a/recombee_api_client/api_requests/list_item_properties.py +++ b/recombee_api_client/api_requests/list_item_properties.py @@ -6,12 +6,11 @@ class ListItemProperties(Request): """ Gets the list of all the item properties in your database. + """ def __init__(self): - """ - """ self.timeout = 100000 self.ensure_https = False self.method = 'get' diff --git a/recombee_api_client/api_requests/list_item_purchases.py b/recombee_api_client/api_requests/list_item_purchases.py index 02ac3f1..ccaf154 100644 --- a/recombee_api_client/api_requests/list_item_purchases.py +++ b/recombee_api_client/api_requests/list_item_purchases.py @@ -6,15 +6,15 @@ class ListItemPurchases(Request): """ List all the ever-made purchases of a given item. + Required parameters: + + :param item_id: ID of the item of which the pucrhases are to be listed. + + + """ def __init__(self, item_id): - """ - Required parameters: - @param item_id: ID of the item of which the pucrhases are to be listed. - - - """ self.item_id = item_id self.timeout = 100000 self.ensure_https = False diff --git a/recombee_api_client/api_requests/list_item_ratings.py b/recombee_api_client/api_requests/list_item_ratings.py index daef187..0762678 100644 --- a/recombee_api_client/api_requests/list_item_ratings.py +++ b/recombee_api_client/api_requests/list_item_ratings.py @@ -6,15 +6,15 @@ class ListItemRatings(Request): """ List all the ratings of an item ever submitted by different users. + Required parameters: + + :param item_id: ID of the item of which the ratings are to be listed. + + + """ def __init__(self, item_id): - """ - Required parameters: - @param item_id: ID of the item of which the ratings are to be listed. - - - """ self.item_id = item_id self.timeout = 100000 self.ensure_https = False diff --git a/recombee_api_client/api_requests/list_item_view_portions.py b/recombee_api_client/api_requests/list_item_view_portions.py index 9f2876e..f882b0d 100644 --- a/recombee_api_client/api_requests/list_item_view_portions.py +++ b/recombee_api_client/api_requests/list_item_view_portions.py @@ -6,16 +6,16 @@ class ListItemViewPortions(Request): """ List all the view portions of an item ever submitted by different users. + + Required parameters: + + :param item_id: ID of the item of which the view portions are to be listed. + + """ def __init__(self, item_id): - """ - Required parameters: - @param item_id: ID of the item of which the view portions are to be listed. - - - """ self.item_id = item_id self.timeout = 100000 self.ensure_https = False diff --git a/recombee_api_client/api_requests/list_items.py b/recombee_api_client/api_requests/list_items.py index 0fe7163..104eb3f 100644 --- a/recombee_api_client/api_requests/list_items.py +++ b/recombee_api_client/api_requests/list_items.py @@ -6,91 +6,91 @@ class ListItems(Request): """ Gets a list of IDs of items currently present in the catalog. + + Optional parameters: + + :param filter: Boolean-returning [ReQL](https://docs.recombee.com/reql.html) expression, which allows you to filter items to be listed. Only the items for which the expression is *true* will be returned. + + :param count: The number of items to be listed. + + :param offset: Specifies the number of items to skip (ordered by `itemId`). + + :param return_properties: With `returnProperties=true`, property values of the listed items are returned along with their IDs in a JSON dictionary. + + + Example response: + + ``` + + [ + + E{lb} + + "itemId": "tv-178", + + "description": "4K TV with 3D feature", + + "categories": ["Electronics", "Televisions"], + + "price": 342, + + "url": "myshop.com/tv-178" + E{rb}, + + E{lb} + + "itemId": "mixer-42", + + "description": "Stainless Steel Mixer", + + "categories": ["Home & Kitchen"], + + "price": 39, + + "url": "myshop.com/mixer-42" + E{rb} + + ] + + ``` + + + :param included_properties: Allows to specify, which properties should be returned when `returnProperties=true` is set. The properties are given as a comma-separated list. + + + Example response for `includedProperties=description,price`: + + ``` + + [ + + E{lb} + + "itemId": "tv-178", + + "description": "4K TV with 3D feature", + + "price": 342 + E{rb}, + + E{lb} + + "itemId": "mixer-42", + + "description": "Stainless Steel Mixer", + + "price": 39 + E{rb} + + ] + + ``` + + + """ def __init__(self, filter=DEFAULT, count=DEFAULT, offset=DEFAULT, return_properties=DEFAULT, included_properties=DEFAULT): - """ - - Optional parameters: - @param filter: Boolean-returning [ReQL](https://docs.recombee.com/reql.html) expression, which allows you to filter items to be listed. Only the items for which the expression is *true* will be returned. - - @param count: The number of items to be listed. - - @param offset: Specifies the number of items to skip (ordered by `itemId`). - - @param return_properties: With `returnProperties=true`, property values of the listed items are returned along with their IDs in a JSON dictionary. - - - Example response: - - ``` - - [ - - E{lb} - - "itemId": "tv-178", - - "description": "4K TV with 3D feature", - - "categories": ["Electronics", "Televisions"], - - "price": 342, - - "url": "myshop.com/tv-178" - E{rb}, - - E{lb} - - "itemId": "mixer-42", - - "description": "Stainless Steel Mixer", - - "categories": ["Home & Kitchen"], - - "price": 39, - - "url": "myshop.com/mixer-42" - E{rb} - - ] - - ``` - - - @param included_properties: Allows to specify, which properties should be returned when `returnProperties=true` is set. The properties are given as a comma-separated list. - - - Example response for `includedProperties=description,price`: - - ``` - - [ - - E{lb} - - "itemId": "tv-178", - - "description": "4K TV with 3D feature", - - "price": 342 - E{rb}, - - E{lb} - - "itemId": "mixer-42", - - "description": "Stainless Steel Mixer", - - "price": 39 - E{rb} - - ] - - ``` - - - """ self.filter = filter self.count = count self.offset = offset diff --git a/recombee_api_client/api_requests/list_series.py b/recombee_api_client/api_requests/list_series.py index 059e02b..88f4a97 100644 --- a/recombee_api_client/api_requests/list_series.py +++ b/recombee_api_client/api_requests/list_series.py @@ -6,11 +6,10 @@ class ListSeries(Request): """ Gets the list of all the series currently present in the database. + """ def __init__(self): - """ - """ self.timeout = 100000 self.ensure_https = False self.method = 'get' diff --git a/recombee_api_client/api_requests/list_series_items.py b/recombee_api_client/api_requests/list_series_items.py index 37de7e6..aba3386 100644 --- a/recombee_api_client/api_requests/list_series_items.py +++ b/recombee_api_client/api_requests/list_series_items.py @@ -6,14 +6,14 @@ class ListSeriesItems(Request): """ List all the items present in the given series, sorted according to their time index values. + Required parameters: + + :param series_id: ID of the series items of which are to be listed. + + """ def __init__(self, series_id): - """ - Required parameters: - @param series_id: ID of the series items of which are to be listed. - - """ self.series_id = series_id self.timeout = 100000 self.ensure_https = False diff --git a/recombee_api_client/api_requests/list_user_bookmarks.py b/recombee_api_client/api_requests/list_user_bookmarks.py index a2758cd..1fe4184 100644 --- a/recombee_api_client/api_requests/list_user_bookmarks.py +++ b/recombee_api_client/api_requests/list_user_bookmarks.py @@ -6,14 +6,14 @@ class ListUserBookmarks(Request): """ List all the bookmarks ever made by a given user. + Required parameters: + + :param user_id: ID of the user whose bookmarks are to be listed. + + """ def __init__(self, user_id): - """ - Required parameters: - @param user_id: ID of the user whose bookmarks are to be listed. - - """ self.user_id = user_id self.timeout = 100000 self.ensure_https = False diff --git a/recombee_api_client/api_requests/list_user_cart_additions.py b/recombee_api_client/api_requests/list_user_cart_additions.py index 80f2956..1e6da95 100644 --- a/recombee_api_client/api_requests/list_user_cart_additions.py +++ b/recombee_api_client/api_requests/list_user_cart_additions.py @@ -6,14 +6,14 @@ class ListUserCartAdditions(Request): """ List all the cart additions ever made by a given user. + Required parameters: + + :param user_id: ID of the user whose cart additions are to be listed. + + """ def __init__(self, user_id): - """ - Required parameters: - @param user_id: ID of the user whose cart additions are to be listed. - - """ self.user_id = user_id self.timeout = 100000 self.ensure_https = False diff --git a/recombee_api_client/api_requests/list_user_detail_views.py b/recombee_api_client/api_requests/list_user_detail_views.py index 96f8f7b..12fd535 100644 --- a/recombee_api_client/api_requests/list_user_detail_views.py +++ b/recombee_api_client/api_requests/list_user_detail_views.py @@ -6,14 +6,14 @@ class ListUserDetailViews(Request): """ Lists all the detail views of different items ever made by a given user. + Required parameters: + + :param user_id: ID of the user whose detail views are to be listed. + + """ def __init__(self, user_id): - """ - Required parameters: - @param user_id: ID of the user whose detail views are to be listed. - - """ self.user_id = user_id self.timeout = 100000 self.ensure_https = False diff --git a/recombee_api_client/api_requests/list_user_properties.py b/recombee_api_client/api_requests/list_user_properties.py index b0b33d9..8007200 100644 --- a/recombee_api_client/api_requests/list_user_properties.py +++ b/recombee_api_client/api_requests/list_user_properties.py @@ -6,12 +6,11 @@ class ListUserProperties(Request): """ Gets the list of all the user properties in your database. + """ def __init__(self): - """ - """ self.timeout = 100000 self.ensure_https = False self.method = 'get' diff --git a/recombee_api_client/api_requests/list_user_purchases.py b/recombee_api_client/api_requests/list_user_purchases.py index 45f22aa..d5d6254 100644 --- a/recombee_api_client/api_requests/list_user_purchases.py +++ b/recombee_api_client/api_requests/list_user_purchases.py @@ -6,14 +6,14 @@ class ListUserPurchases(Request): """ List all the purchases ever made by a given user. + Required parameters: + + :param user_id: ID of the user whose purchases are to be listed. + + """ def __init__(self, user_id): - """ - Required parameters: - @param user_id: ID of the user whose purchases are to be listed. - - """ self.user_id = user_id self.timeout = 100000 self.ensure_https = False diff --git a/recombee_api_client/api_requests/list_user_ratings.py b/recombee_api_client/api_requests/list_user_ratings.py index 44e13b1..959c043 100644 --- a/recombee_api_client/api_requests/list_user_ratings.py +++ b/recombee_api_client/api_requests/list_user_ratings.py @@ -6,14 +6,14 @@ class ListUserRatings(Request): """ List all the ratings ever submitted by a given user. + Required parameters: + + :param user_id: ID of the user whose ratings are to be listed. + + """ def __init__(self, user_id): - """ - Required parameters: - @param user_id: ID of the user whose ratings are to be listed. - - """ self.user_id = user_id self.timeout = 100000 self.ensure_https = False diff --git a/recombee_api_client/api_requests/list_user_view_portions.py b/recombee_api_client/api_requests/list_user_view_portions.py index 612fd70..76e9dbe 100644 --- a/recombee_api_client/api_requests/list_user_view_portions.py +++ b/recombee_api_client/api_requests/list_user_view_portions.py @@ -6,15 +6,15 @@ class ListUserViewPortions(Request): """ List all the view portions ever submitted by a given user. + + Required parameters: + + :param user_id: ID of the user whose view portions are to be listed. + """ def __init__(self, user_id): - """ - Required parameters: - @param user_id: ID of the user whose view portions are to be listed. - - """ self.user_id = user_id self.timeout = 100000 self.ensure_https = False diff --git a/recombee_api_client/api_requests/list_users.py b/recombee_api_client/api_requests/list_users.py index dc420e4..963243f 100644 --- a/recombee_api_client/api_requests/list_users.py +++ b/recombee_api_client/api_requests/list_users.py @@ -6,79 +6,79 @@ class ListUsers(Request): """ Gets a list of IDs of users currently present in the catalog. + + Optional parameters: + + :param filter: Boolean-returning [ReQL](https://docs.recombee.com/reql.html) expression, which allows you to filter users to be listed. Only the users for which the expression is *true* will be returned. + + :param count: The number of users to be listed. + + :param offset: Specifies the number of users to skip (ordered by `userId`). + + :param return_properties: With `returnProperties=true`, property values of the listed users are returned along with their IDs in a JSON dictionary. + + + Example response: + + ``` + + [ + + E{lb} + + "userId": "user-81", + + "country": "US", + + "sex": "M" + E{rb}, + + E{lb} + + "userId": "user-314", + + "country": "CAN", + + "sex": "F" + E{rb} + + ] + + ``` + + + :param included_properties: Allows to specify, which properties should be returned when `returnProperties=true` is set. The properties are given as a comma-separated list. + + + Example response for `includedProperties=country`: + + ``` + + [ + + E{lb} + + "userId": "user-81", + + "country": "US" + E{rb}, + + E{lb} + + "userId": "user-314", + + "country": "CAN" + E{rb} + + ] + + ``` + + + """ def __init__(self, filter=DEFAULT, count=DEFAULT, offset=DEFAULT, return_properties=DEFAULT, included_properties=DEFAULT): - """ - - Optional parameters: - @param filter: Boolean-returning [ReQL](https://docs.recombee.com/reql.html) expression, which allows you to filter users to be listed. Only the users for which the expression is *true* will be returned. - - @param count: The number of users to be listed. - - @param offset: Specifies the number of users to skip (ordered by `userId`). - - @param return_properties: With `returnProperties=true`, property values of the listed users are returned along with their IDs in a JSON dictionary. - - - Example response: - - ``` - - [ - - E{lb} - - "userId": "user-81", - - "country": "US", - - "sex": "M" - E{rb}, - - E{lb} - - "userId": "user-314", - - "country": "CAN", - - "sex": "F" - E{rb} - - ] - - ``` - - - @param included_properties: Allows to specify, which properties should be returned when `returnProperties=true` is set. The properties are given as a comma-separated list. - - - Example response for `includedProperties=country`: - - ``` - - [ - - E{lb} - - "userId": "user-81", - - "country": "US" - E{rb}, - - E{lb} - - "userId": "user-314", - - "country": "CAN" - E{rb} - - ] - - ``` - - - """ self.filter = filter self.count = count self.offset = offset diff --git a/recombee_api_client/api_requests/merge_users.py b/recombee_api_client/api_requests/merge_users.py index e9b32cd..f419e75 100644 --- a/recombee_api_client/api_requests/merge_users.py +++ b/recombee_api_client/api_requests/merge_users.py @@ -9,21 +9,22 @@ class MergeUsers(Request): Merging happens between two users referred to as the *target* and the *source*. After the merge, all the interactions of the source user are attributed to the target user, and the source user is **deleted**. + + Required parameters: + + :param target_user_id: ID of the targer user. + + :param source_user_id: ID of the source user. + + + Optional parameters: + + :param cascade_create: Sets whether the user *targetUserId* should be created if not present in the database. + """ def __init__(self, target_user_id, source_user_id, cascade_create=DEFAULT): - """ - Required parameters: - @param target_user_id: ID of the targer user. - - @param source_user_id: ID of the source user. - - - Optional parameters: - @param cascade_create: Sets whether the user *targetUserId* should be created if not present in the database. - - """ self.target_user_id = target_user_id self.source_user_id = source_user_id self.cascade_create = cascade_create diff --git a/recombee_api_client/api_requests/recommend_items_to_item.py b/recombee_api_client/api_requests/recommend_items_to_item.py index 0309be5..05fe12a 100644 --- a/recombee_api_client/api_requests/recommend_items_to_item.py +++ b/recombee_api_client/api_requests/recommend_items_to_item.py @@ -7,206 +7,216 @@ 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. + The returned items are sorted by relevance (first item being the most relevant). + + Besides the recommended items, also a unique `recommId` is returned in the response. It can be used to: + + - Let Recombee know that this recommendation was successful (e.g. user clicked one of the recommended items). See [Reported metrics](https://docs.recombee.com/admin_ui.html#reported-metrics). + - Get subsequent recommended items when the user scrolls down (*infinite scroll*) or goes to the next page. See [Recommend Next Items](https://docs.recombee.com/api.html#recommend-next-items). + 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). + Required parameters: + + :param item_id: ID of the item for which the recommendations are to be generated. + + :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 the calculation 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. + + + If you insist on not specifying the user, pass `null` + + (`None`, `nil`, `NULL` etc. depending on language) to *targetUserId*. + + Do not create some special dummy user for getting recommendations, + + as it could mislead the recommendation models, + + and result in wrong recommendations. + + + For anonymous/unregistered users it is possible to use for example their session ID. + + + :param count: Number of items to be recommended (N for the top-N recommendation). + + + Optional parameters: + + :param scenario: Scenario defines a particular application of recommendations. It can be for example "homepage", "cart" or "emailing". + + + 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. + + + 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. + + + :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. + + + Example response: + + ``` + + E{lb} + + "recommId": "0c6189e7-dc1a-429a-b613-192696309361", + + "recomms": + + [ + + E{lb} + + "id": "tv-178", + + "values": E{lb} + + "description": "4K TV with 3D feature", + + "categories": ["Electronics", "Televisions"], + + "price": 342, + + "url": "myshop.com/tv-178" + E{rb} + E{rb}, + + E{lb} + + "id": "mixer-42", + + "values": E{lb} + + "description": "Stainless Steel Mixer", + + "categories": ["Home & Kitchen"], + + "price": 39, + + "url": "myshop.com/mixer-42" + E{rb} + E{rb} + + ], + + "numberNextRecommsCalls": 0 + E{rb} + + ``` + + + :param included_properties: Allows to specify, which properties should be returned when `returnProperties=true` is set. The properties are given as a comma-separated list. + + + Example response for `includedProperties=description,price`: + + ``` + + E{lb} + + "recommId": "6842c725-a79f-4537-a02c-f34d668a3f80", + + "recomms": + + [ + + E{lb} + + "id": "tv-178", + + "values": E{lb} + + "description": "4K TV with 3D feature", + + "price": 342 + E{rb} + E{rb}, + + E{lb} + + "id": "mixer-42", + + "values": E{lb} + + "description": "Stainless Steel Mixer", + + "price": 39 + E{rb} + E{rb} + + ], + + "numberNextRecommsCalls": 0 + E{rb} + + ``` + + + :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`. + + + :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** 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 relevance, and may return less than *count* items when there is not enough data to fulfill it. + + + :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** If the *targetUserId* is provided: Taking *rotationRate* into account, specifies how long time it takes to an item to recover from the penalization. For example, `rotationTime=7200.0` means that items recommended less than 2 hours ago are penalized. + + + :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. + + """ 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. - - @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 the calculation 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. - - - If you insist on not specifying the user, pass `null` - - (`None`, `nil`, `NULL` etc. depending on language) to *targetUserId*. - - Do not create some special dummy user for getting recommendations, - - as it could mislead the recommendation models, - - and result in wrong recommendations. - - - For anonymous/unregistered users it is possible to use for example their session ID. - - - @param count: Number of items to be recommended (N for the top-N recommendation). - - - Optional parameters: - @param scenario: Scenario defines a particular application of recommendations. It can be for example "homepage", "cart" or "emailing". - - - 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. - - - 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. - - - @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. - - - Example response: - - ``` - - E{lb} - - "recommId": "0c6189e7-dc1a-429a-b613-192696309361", - - "recomms": - - [ - - E{lb} - - "id": "tv-178", - - "values": E{lb} - - "description": "4K TV with 3D feature", - - "categories": ["Electronics", "Televisions"], - - "price": 342, - - "url": "myshop.com/tv-178" - E{rb} - E{rb}, - - E{lb} - - "id": "mixer-42", - - "values": E{lb} - - "description": "Stainless Steel Mixer", - - "categories": ["Home & Kitchen"], - - "price": 39, - - "url": "myshop.com/mixer-42" - E{rb} - E{rb} - - ] - E{rb} - - ``` - - - @param included_properties: Allows to specify, which properties should be returned when `returnProperties=true` is set. The properties are given as a comma-separated list. - - - Example response for `includedProperties=description,price`: - - ``` - - E{lb} - - "recommId": "6842c725-a79f-4537-a02c-f34d668a3f80", - - "recomms": - - [ - - E{lb} - - "id": "tv-178", - - "values": E{lb} - - "description": "4K TV with 3D feature", - - "price": 342 - E{rb} - E{rb}, - - E{lb} - - "id": "mixer-42", - - "values": E{lb} - - "description": "Stainless Steel Mixer", - - "price": 39 - E{rb} - E{rb} - - ] - E{rb} - - ``` - - - @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`. - - - @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** 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 relevancy, and may return less than *count* items when there is not enough data to fulfill it. - - - @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** If the *targetUserId* is provided: Taking *rotationRate* into account, specifies how long time it takes to an item to recover from the penalization. For example, `rotationTime=7200.0` means that items recommended less than 2 hours ago are penalized. - - - @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 self.count = count diff --git a/recombee_api_client/api_requests/recommend_items_to_user.py b/recombee_api_client/api_requests/recommend_items_to_user.py index 2785a05..6bbae96 100644 --- a/recombee_api_client/api_requests/recommend_items_to_user.py +++ b/recombee_api_client/api_requests/recommend_items_to_user.py @@ -9,174 +9,184 @@ class RecommendItemsToUser(Request): The most typical use cases are recommendations at homepage, in some "Picked just for you" section or in email. + The returned items are sorted by relevance (first item being the most relevant). + + Besides the recommended items, also a unique `recommId` is returned in the response. It can be used to: + + - Let Recombee know that this recommendation was successful (e.g. user clicked one of the recommended items). See [Reported metrics](https://docs.recombee.com/admin_ui.html#reported-metrics). + - Get subsequent recommended items when the user scrolls down (*infinite scroll*) or goes to the next page. See [Recommend Next Items](https://docs.recombee.com/api.html#recommend-next-items). + 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). + Required parameters: + + :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 scenario: Scenario defines a particular application of recommendations. It can be for example "homepage", "cart" or "emailing". + + + 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. + + + 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. + + + :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. + + + Example response: + + ``` + + E{lb} + + "recommId": "ce52ada4-e4d9-4885-943c-407db2dee837", + + "recomms": + + [ + + E{lb} + + "id": "tv-178", + + "values": E{lb} + + "description": "4K TV with 3D feature", + + "categories": ["Electronics", "Televisions"], + + "price": 342, + + "url": "myshop.com/tv-178" + E{rb} + E{rb}, + + E{lb} + + "id": "mixer-42", + + "values": E{lb} + + "description": "Stainless Steel Mixer", + + "categories": ["Home & Kitchen"], + + "price": 39, + + "url": "myshop.com/mixer-42" + E{rb} + E{rb} + + ], + + "numberNextRecommsCalls": 0 + E{rb} + + ``` + + + :param included_properties: Allows to specify, which properties should be returned when `returnProperties=true` is set. The properties are given as a comma-separated list. + + + Example response for `includedProperties=description,price`: + + ``` + + E{lb} + + "recommId": "a86ee8d5-cd8e-46d1-886c-8b3771d0520b", + + "recomms": + + [ + + E{lb} + + "id": "tv-178", + + "values": E{lb} + + "description": "4K TV with 3D feature", + + "price": 342 + E{rb} + E{rb}, + + E{lb} + + "id": "mixer-42", + + "values": E{lb} + + "description": "Stainless Steel Mixer", + + "price": 39 + E{rb} + E{rb} + + ], + + "numberNextRecommsCalls": 0 + E{rb} + + ``` + + + :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. + + + :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 relevance, 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. Default: `0.1`. + + + :param rotation_time: **Expert option** Taking *rotationRate* into account, specifies how long time it takes to an item to recover from the penalization. For example, `rotationTime=7200.0` means that items recommended less than 2 hours ago are penalized. Default: `7200.0`. + + + :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. + + """ 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 whom personalized recommendations are to be generated. - - @param count: Number of items to be recommended (N for the top-N recommendation). - - - - Optional parameters: - @param scenario: Scenario defines a particular application of recommendations. It can be for example "homepage", "cart" or "emailing". - - - 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. - - - 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. - - - @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. - - - Example response: - - ``` - - E{lb} - - "recommId": "ce52ada4-e4d9-4885-943c-407db2dee837", - - "recomms": - - [ - - E{lb} - - "id": "tv-178", - - "values": E{lb} - - "description": "4K TV with 3D feature", - - "categories": ["Electronics", "Televisions"], - - "price": 342, - - "url": "myshop.com/tv-178" - E{rb} - E{rb}, - - E{lb} - - "id": "mixer-42", - - "values": E{lb} - - "description": "Stainless Steel Mixer", - - "categories": ["Home & Kitchen"], - - "price": 39, - - "url": "myshop.com/mixer-42" - E{rb} - E{rb} - - ] - E{rb} - - ``` - - - @param included_properties: Allows to specify, which properties should be returned when `returnProperties=true` is set. The properties are given as a comma-separated list. - - - Example response for `includedProperties=description,price`: - - ``` - - E{lb} - - "recommId": "a86ee8d5-cd8e-46d1-886c-8b3771d0520b", - - "recomms": - - [ - - E{lb} - - "id": "tv-178", - - "values": E{lb} - - "description": "4K TV with 3D feature", - - "price": 342 - E{rb} - E{rb}, - - E{lb} - - "id": "mixer-42", - - "values": E{lb} - - "description": "Stainless Steel Mixer", - - "price": 39 - E{rb} - E{rb} - - ] - E{rb} - - ``` - - - @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. - - - @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 relevancy, 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. Default: `0.1`. - - - @param rotation_time: **Expert option** Taking *rotationRate* into account, specifies how long time it takes to an item to recover from the penalization. For example, `rotationTime=7200.0` means that items recommended less than 2 hours ago are penalized. Default: `7200.0`. - - - @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 self.scenario = scenario diff --git a/recombee_api_client/api_requests/recommend_next_items.py b/recombee_api_client/api_requests/recommend_next_items.py new file mode 100644 index 0000000..0fb19bc --- /dev/null +++ b/recombee_api_client/api_requests/recommend_next_items.py @@ -0,0 +1,56 @@ +from recombee_api_client.api_requests.request import Request +import uuid + +DEFAULT = uuid.uuid4() + +class RecommendNextItems(Request): + """ + Returns items that shall be shown to a user as next recommendations when the user e.g. scrolls the page down (*infinite scroll*) or goes to a next page. + + It accepts `recommId` of a base recommendation request (e.g. request from the first page) and number of items that shall be returned (`count`). + The base request can be one of: + - [Recommend items to item](https://docs.recombee.com/api.html#recommend-items-to-item) + - [Recommend items to user](https://docs.recombee.com/api.html#recommend-items-to-user) + - [Search items](https://docs.recombee.com/api.html#search-items) + + All the other parameters are inherited from the base request. + + *Recommend next items* can be called many times for a single `recommId` and each call returns different (previously not recommended) items. + The number of *Recommend next items* calls performed so far is returned in the `numberNextRecommsCalls` field. + + *Recommend next items* can be requested up to 30 minutes after the base request or a previous *Recommend next items* call. + + For billing purposes, each call to *Recommend next items* is counted as a separate recommendation request. + + Required parameters: + + :param recomm_id: ID of the base recommendation request for which next recommendations should be returned + + :param count: Number of items to be recommended + + + + """ + + def __init__(self, recomm_id, count): + self.recomm_id = recomm_id + self.count = count + self.timeout = 3000 + self.ensure_https = False + self.method = 'post' + self.path = "/recomms/next/items/%s" % (self.recomm_id) + + def get_body_parameters(self): + """ + Values of body parameters as a dictionary (name of parameter: value of the parameter). + """ + p = dict() + p['count'] = self.count + 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 diff --git a/recombee_api_client/api_requests/recommend_users_to_item.py b/recombee_api_client/api_requests/recommend_users_to_item.py index d7047c0..507272b 100644 --- a/recombee_api_client/api_requests/recommend_users_to_item.py +++ b/recombee_api_client/api_requests/recommend_users_to_item.py @@ -10,148 +10,153 @@ class RecommendUsersToItem(Request): 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). + + Required parameters: + + :param item_id: ID of the item for which the recommendations are to be generated. + + :param count: Number of items to be recommended (N for the top-N recommendation). + + + Optional parameters: + + :param scenario: Scenario defines a particular application of recommendations. It can be for example "homepage", "cart" or "emailing". + + + 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. + + + 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. + + + :param cascade_create: If item of given *itemId* doesn't exist in the database, it creates the missing item. + + :param return_properties: With `returnProperties=true`, property values of the recommended users are returned along with their IDs in a JSON dictionary. The acquired property values can be used for easy displaying the recommended users. + + + Example response: + + ``` + + E{lb} + + "recommId": "039b71dc-b9cc-4645-a84f-62b841eecfce", + + "recomms": + + [ + + E{lb} + + "id": "user-17", + + "values": E{lb} + + "country": "US", + + "sex": "F" + E{rb} + E{rb}, + + E{lb} + + "id": "user-2", + + "values": E{lb} + + "country": "CAN", + + "sex": "M" + E{rb} + E{rb} + + ], + + "numberNextRecommsCalls": 0 + E{rb} + + ``` + + + :param included_properties: Allows to specify, which properties should be returned when `returnProperties=true` is set. The properties are given as a comma-separated list. + + + Example response for `includedProperties=country`: + + ``` + + E{lb} + + "recommId": "b2b355dd-972a-4728-9c6b-2dc229db0678", + + "recomms": + + [ + + E{lb} + + "id": "user-17", + + "values": E{lb} + + "country": "US" + E{rb} + E{rb}, + + E{lb} + + "id": "user-2", + + "values": E{lb} + + "country": "CAN" + E{rb} + E{rb} + + ], + + "numberNextRecommsCalls": 0 + E{rb} + + ``` + + + :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. + + + :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. + + """ def __init__(self, item_id, count, scenario=DEFAULT, cascade_create=DEFAULT, return_properties=DEFAULT, included_properties=DEFAULT, filter=DEFAULT, booster=DEFAULT, logic=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. - - @param count: Number of items to be recommended (N for the top-N recommendation). - - - Optional parameters: - @param scenario: Scenario defines a particular application of recommendations. It can be for example "homepage", "cart" or "emailing". - - - 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. - - - 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. - - - @param cascade_create: If item of given *itemId* doesn't exist in the database, it creates the missing item. - - @param return_properties: With `returnProperties=true`, property values of the recommended users are returned along with their IDs in a JSON dictionary. The acquired property values can be used for easy displaying the recommended users. - - - Example response: - - ``` - - E{lb} - - "recommId": "039b71dc-b9cc-4645-a84f-62b841eecfce", - - "recomms": - - [ - - E{lb} - - "id": "user-17", - - "values": E{lb} - - "country": "US", - - "sex": "F" - E{rb} - E{rb}, - - E{lb} - - "id": "user-2", - - "values": E{lb} - - "country": "CAN", - - "sex": "M" - E{rb} - E{rb} - - ] - E{rb} - - ``` - - - @param included_properties: Allows to specify, which properties should be returned when `returnProperties=true` is set. The properties are given as a comma-separated list. - - - Example response for `includedProperties=country`: - - ``` - - E{lb} - - "recommId": "b2b355dd-972a-4728-9c6b-2dc229db0678", - - "recomms": - - [ - - E{lb} - - "id": "user-17", - - "values": E{lb} - - "country": "US" - E{rb} - E{rb}, - - E{lb} - - "id": "user-2", - - "values": E{lb} - - "country": "CAN" - E{rb} - E{rb} - - ] - E{rb} - - ``` - - - @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. - - - @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 self.scenario = scenario diff --git a/recombee_api_client/api_requests/recommend_users_to_user.py b/recombee_api_client/api_requests/recommend_users_to_user.py index 9d106c7..b98ff95 100644 --- a/recombee_api_client/api_requests/recommend_users_to_user.py +++ b/recombee_api_client/api_requests/recommend_users_to_user.py @@ -10,157 +10,162 @@ class RecommendUsersToUser(Request): 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). + + Required parameters: + + :param user_id: User to whom we find similar users + + :param count: Number of users to be recommended (N for the top-N recommendation). + + + Optional parameters: + + :param scenario: Scenario defines a particular application of recommendations. It can be for example "homepage", "cart" or "emailing". + + + 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. + + + 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. + + + :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 users are returned along with their IDs in a JSON dictionary. The acquired property values can be used for easy displaying the recommended users. + + + Example response: + + ``` + + E{lb} + + "recommId": "9cb9c55d-50ba-4478-84fd-ab456136156e", + + "recomms": + + [ + + E{lb} + + "id": "user-17", + + "values": E{lb} + + "country": "US", + + "sex": "F" + E{rb} + E{rb}, + + E{lb} + + "id": "user-2", + + "values": E{lb} + + "country": "CAN", + + "sex": "M" + E{rb} + E{rb} + + ], + + "numberNextRecommsCalls": 0 + E{rb} + + ``` + + + :param included_properties: Allows to specify, which properties should be returned when `returnProperties=true` is set. The properties are given as a comma-separated list. + + + Example response for `includedProperties=country`: + + ``` + + E{lb} + + "recommId": "b326d82d-5d57-4b45-b362-c9d6f0895855", + + "recomms": + + [ + + E{lb} + + "id": "user-17", + + "values": E{lb} + + "country": "US" + E{rb} + E{rb}, + + E{lb} + + "id": "user-2", + + "values": E{lb} + + "country": "CAN" + E{rb} + E{rb} + + ], + + "numberNextRecommsCalls": 0 + E{rb} + + ``` + + + :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 users 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 users be. Possible values one of: "low", "medium", "high". + + + :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 user 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 users. + + + :param rotation_time: **Expert option** Taking *rotationRate* into account, specifies how long time it takes to an user to recover from the penalization. For example, `rotationTime=7200.0` means that users recommended less than 2 hours ago are penalized. + + + :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. + + """ 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: User to whom we find similar users - - @param count: Number of users to be recommended (N for the top-N recommendation). - - - Optional parameters: - @param scenario: Scenario defines a particular application of recommendations. It can be for example "homepage", "cart" or "emailing". - - - 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. - - - 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. - - - @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 users are returned along with their IDs in a JSON dictionary. The acquired property values can be used for easy displaying the recommended users. - - - Example response: - - ``` - - E{lb} - - "recommId": "9cb9c55d-50ba-4478-84fd-ab456136156e", - - "recomms": - - [ - - E{lb} - - "id": "user-17", - - "values": E{lb} - - "country": "US", - - "sex": "F" - E{rb} - E{rb}, - - E{lb} - - "id": "user-2", - - "values": E{lb} - - "country": "CAN", - - "sex": "M" - E{rb} - E{rb} - - ] - E{rb} - - ``` - - - @param included_properties: Allows to specify, which properties should be returned when `returnProperties=true` is set. The properties are given as a comma-separated list. - - - Example response for `includedProperties=country`: - - ``` - - E{lb} - - "recommId": "b326d82d-5d57-4b45-b362-c9d6f0895855", - - "recomms": - - [ - - E{lb} - - "id": "user-17", - - "values": E{lb} - - "country": "US" - E{rb} - E{rb}, - - E{lb} - - "id": "user-2", - - "values": E{lb} - - "country": "CAN" - E{rb} - E{rb} - - ] - E{rb} - - ``` - - - @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 users 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 users be. Possible values one of: "low", "medium", "high". - - - @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 user 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 users. - - - @param rotation_time: **Expert option** Taking *rotationRate* into account, specifies how long time it takes to an user to recover from the penalization. For example, `rotationTime=7200.0` means that users recommended less than 2 hours ago are penalized. - - - @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 self.scenario = scenario diff --git a/recombee_api_client/api_requests/remove_from_group.py b/recombee_api_client/api_requests/remove_from_group.py index 622195a..53f9f78 100644 --- a/recombee_api_client/api_requests/remove_from_group.py +++ b/recombee_api_client/api_requests/remove_from_group.py @@ -6,18 +6,18 @@ class RemoveFromGroup(Request): """ Removes an existing group item from the group. + Required parameters: + + :param group_id: ID of the group from which a group item is to be removed. + + :param item_type: Type of the item to be removed. + + :param item_id: ID of the item iff `itemType` is `item`. ID of the group iff `itemType` is `group`. + + """ def __init__(self, group_id, item_type, item_id): - """ - Required parameters: - @param group_id: ID of the group from which a group item is to be removed. - - @param item_type: Type of the item to be removed. - - @param item_id: ID of the item iff `itemType` is `item`. ID of the group iff `itemType` is `group`. - - """ self.group_id = group_id self.item_type = item_type self.item_id = item_id diff --git a/recombee_api_client/api_requests/remove_from_series.py b/recombee_api_client/api_requests/remove_from_series.py index 022cd05..7b2c9cc 100644 --- a/recombee_api_client/api_requests/remove_from_series.py +++ b/recombee_api_client/api_requests/remove_from_series.py @@ -6,20 +6,20 @@ class RemoveFromSeries(Request): """ Removes an existing series item from the series. + Required parameters: + + :param series_id: ID of the series from which a series item is to be removed. + + :param item_type: Type of the item to be removed. + + :param item_id: ID of the item iff `itemType` is `item`. ID of the series iff `itemType` is `series`. + + :param time: Time index of the item to be removed. + + """ def __init__(self, series_id, item_type, item_id, time): - """ - Required parameters: - @param series_id: ID of the series from which a series item is to be removed. - - @param item_type: Type of the item to be removed. - - @param item_id: ID of the item iff `itemType` is `item`. ID of the series iff `itemType` is `series`. - - @param time: Time index of the item to be removed. - - """ self.series_id = series_id self.item_type = item_type self.item_id = item_id diff --git a/recombee_api_client/api_requests/reset_database.py b/recombee_api_client/api_requests/reset_database.py index ca0eaa8..299b5b2 100644 --- a/recombee_api_client/api_requests/reset_database.py +++ b/recombee_api_client/api_requests/reset_database.py @@ -6,12 +6,11 @@ class ResetDatabase(Request): """ Completely erases all your data, including items, item properties, series, user database, purchases, ratings, detail views, and bookmarks. Make sure the request to be never executed in production environment! Resetting your database is irreversible. + """ def __init__(self): - """ - """ self.timeout = 100000 self.ensure_https = False self.method = 'delete' diff --git a/recombee_api_client/api_requests/search_items.py b/recombee_api_client/api_requests/search_items.py index 957c6f4..c4af79c 100644 --- a/recombee_api_client/api_requests/search_items.py +++ b/recombee_api_client/api_requests/search_items.py @@ -11,162 +11,172 @@ class SearchItems(Request): This endpoint should be used in a search box at your website/app. It can be called multiple times as the user is typing the query in order to get the most viable suggestions based on current state of the query, or once after submitting the whole query. + The returned items are sorted by relevance (first item being the most relevant). + + Besides the recommended items, also a unique `recommId` is returned in the response. It can be used to: + + - Let Recombee know that this search was successful (e.g. user clicked one of the recommended items). See [Reported metrics](https://docs.recombee.com/admin_ui.html#reported-metrics). + - Get subsequent search results when the user scrolls down or goes to the next page. See [Recommend Next Items](https://docs.recombee.com/api.html#recommend-next-items). + 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). + Required parameters: + + :param user_id: ID of the user for whom personalized search will be performed. + + :param search_query: Search query provided by the user. It is used for the full-text search. + + :param count: Number of items to be returned (N for the top-N results). + + + Optional parameters: + + :param scenario: Scenario defines a particular search field in your user interface. + + + 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 field 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. + + + :param cascade_create: If the user does not exist in the database, returns a list of non-personalized search results 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. + + + Example response: + + ``` + + E{lb} + + "recommId": "ce52ada4-e4d9-4885-943c-407db2dee837", + + "recomms": + + [ + + E{lb} + + "id": "tv-178", + + "values": E{lb} + + "description": "4K TV with 3D feature", + + "categories": ["Electronics", "Televisions"], + + "price": 342, + + "url": "myshop.com/tv-178" + E{rb} + E{rb}, + + E{lb} + + "id": "mixer-42", + + "values": E{lb} + + "description": "Stainless Steel Mixer", + + "categories": ["Home & Kitchen"], + + "price": 39, + + "url": "myshop.com/mixer-42" + E{rb} + E{rb} + + ], + + "numberNextRecommsCalls": 0 + E{rb} + + ``` + + + :param included_properties: Allows to specify, which properties should be returned when `returnProperties=true` is set. The properties are given as a comma-separated list. + + + Example response for `includedProperties=description,price`: + + ``` + + E{lb} + + "recommId": "a86ee8d5-cd8e-46d1-886c-8b3771d0520b", + + "recomms": + + [ + + E{lb} + + "id": "tv-178", + + "values": E{lb} + + "description": "4K TV with 3D feature", + + "price": 342 + E{rb} + E{rb}, + + E{lb} + + "id": "mixer-42", + + "values": E{lb} + + "description": "Stainless Steel Mixer", + + "price": 39 + E{rb} + E{rb} + + ], + + "numberNextRecommsCalls": 0 + E{rb} + + ``` + + + :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 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. + + """ def __init__(self, user_id, search_query, count, scenario=DEFAULT, cascade_create=DEFAULT, return_properties=DEFAULT, included_properties=DEFAULT, filter=DEFAULT, booster=DEFAULT, logic=DEFAULT, expert_settings=DEFAULT, return_ab_group=DEFAULT): - """ - Required parameters: - @param user_id: ID of the user for whom personalized search will be performed. - - @param search_query: Search query provided by the user. It is used for the full-text search. - - @param count: Number of items to be returned (N for the top-N results). - - - Optional parameters: - @param scenario: Scenario defines a particular search field in your user interface. - - - 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 field 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. - - - @param cascade_create: If the user does not exist in the database, returns a list of non-personalized search results 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. - - - Example response: - - ``` - - E{lb} - - "recommId": "ce52ada4-e4d9-4885-943c-407db2dee837", - - "recomms": - - [ - - E{lb} - - "id": "tv-178", - - "values": E{lb} - - "description": "4K TV with 3D feature", - - "categories": ["Electronics", "Televisions"], - - "price": 342, - - "url": "myshop.com/tv-178" - E{rb} - E{rb}, - - E{lb} - - "id": "mixer-42", - - "values": E{lb} - - "description": "Stainless Steel Mixer", - - "categories": ["Home & Kitchen"], - - "price": 39, - - "url": "myshop.com/mixer-42" - E{rb} - E{rb} - - ] - E{rb} - - ``` - - - @param included_properties: Allows to specify, which properties should be returned when `returnProperties=true` is set. The properties are given as a comma-separated list. - - - Example response for `includedProperties=description,price`: - - ``` - - E{lb} - - "recommId": "a86ee8d5-cd8e-46d1-886c-8b3771d0520b", - - "recomms": - - [ - - E{lb} - - "id": "tv-178", - - "values": E{lb} - - "description": "4K TV with 3D feature", - - "price": 342 - E{rb} - E{rb}, - - E{lb} - - "id": "mixer-42", - - "values": E{lb} - - "description": "Stainless Steel Mixer", - - "price": 39 - E{rb} - E{rb} - - ] - E{rb} - - ``` - - - @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 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.search_query = search_query self.count = count diff --git a/recombee_api_client/api_requests/set_item_values.py b/recombee_api_client/api_requests/set_item_values.py index 243526f..327262e 100644 --- a/recombee_api_client/api_requests/set_item_values.py +++ b/recombee_api_client/api_requests/set_item_values.py @@ -4,37 +4,37 @@ class SetItemValues(SetValues): """ Set/update (some) property values of a given item. The properties (columns) must be previously created by [Add item property](https://docs.recombee.com/api.html#add-item-property). + Required parameters: + + :param item_id: ID of the item which will be modified. + + + :param values: The values for the individual properties. + + + Example: + + ``` + + E{lb} + + "product_description": "4K TV with 3D feature", + + "categories": ["Electronics", "Televisions"], + + "price_usd": 342, + + E{rb} + + ``` + + Optional parameters: + + :param cascade_create: Sets whether the given item should be created if not present in the database. + """ def __init__(self,item_id, values, cascade_create=None): - """ - Required parameters: - @param item_id: ID of the item which will be modified. - - - @param values: The values for the individual properties. - - - Example: - - ``` - - E{lb} - - "product_description": "4K TV with 3D feature", - - "categories": ["Electronics", "Televisions"], - - "price_usd": 342, - - E{rb} - - ``` - - Optional parameters: - - @param cascade_create: Sets whether the given item should be created if not present in the database. - """ super(SetItemValues, self).__init__(values, cascade_create=cascade_create) self.item_id = item_id diff --git a/recombee_api_client/api_requests/set_user_values.py b/recombee_api_client/api_requests/set_user_values.py index bf40b7e..c97dd64 100644 --- a/recombee_api_client/api_requests/set_user_values.py +++ b/recombee_api_client/api_requests/set_user_values.py @@ -4,32 +4,30 @@ class SetUserValues(SetValues): """ Set/update (some) property values of a given user. The properties (columns) must be previously created by [Add user property](https://docs.recombee.com/api.html#add-user-property). + Required parameters: + :param user_id: ID of the user which will be modified. + + + :param values: The values for the individual properties. + + Example: + + ``` + + E{lb} + + "country": "US", + "sex": "F", + E{rb} + + ``` + + Optional parameters: + + :param cascade_create: Sets whether the given user should be created if not present in the database. """ def __init__(self,user_id, values, cascade_create=None): - """ - Required parameters: - @param user_id: ID of the user which will be modified. - - - @param values: The values for the individual properties. - - Example: - - ``` - - E{lb} - - "country": "US", - "sex": "F", - E{rb} - - ``` - - Optional parameters: - - @param cascade_create: Sets whether the given user should be created if not present in the database. - """ super(SetUserValues, self).__init__(values, cascade_create=cascade_create) self.user_id = user_id diff --git a/recombee_api_client/api_requests/set_values.py b/recombee_api_client/api_requests/set_values.py index f358d3a..6ab95a5 100644 --- a/recombee_api_client/api_requests/set_values.py +++ b/recombee_api_client/api_requests/set_values.py @@ -4,36 +4,34 @@ class SetValues(Request): """ Set/update (some) property values of an entity. + + Required parameters: + + :param values: The values for the individual properties. + + Example: + + ``` + + E{lb} + + "product_description": "4K TV with 3D feature", + + "categories": ["Electronics", "Televisions"], + + "price_usd": 342, + + "!cascadeCreate": True + E{rb} + ``` + + Optional parameters: + + :param cascade_create: Sets whether the given enity should be created if not present in the database. """ def __init__(self, values, cascade_create=None): - """ - Required parameters: - - @param values: The values for the individual properties. - - Example: - - ``` - - E{lb} - - "product_description": "4K TV with 3D feature", - - "categories": ["Electronics", "Televisions"], - - "price_usd": 342, - - "!cascadeCreate": True - E{rb} - - Optional parameters: - - @param cascade_create: Sets whether the given enity should be created if not present in the database. - ``` - - """ self.values = values self.cascade_create = cascade_create self.timeout = 1000 diff --git a/recombee_api_client/api_requests/set_view_portion.py b/recombee_api_client/api_requests/set_view_portion.py index d57b8c6..ffffa2d 100644 --- a/recombee_api_client/api_requests/set_view_portion.py +++ b/recombee_api_client/api_requests/set_view_portion.py @@ -7,31 +7,32 @@ class SetViewPortion(Request): """ Sets viewed portion of an item (for example a video or article) by a user (at a session). If you send new request with the same (`userId`, `itemId`, `sessionId`), the portion gets updated. + + Required parameters: + + :param user_id: User who viewed a portion of the item + + :param item_id: Viewed item + + :param portion: Viewed portion of the item (number between 0.0 (viewed nothing) and 1.0 (viewed full item) ). It should be the really viewed part of the item, no matter seeking, so for example if the user seeked immediately to half of the item and then viewed 10% of the item, the `portion` should still be `0.1`. + + + Optional parameters: + + :param session_id: ID of session in which the user viewed the item. Default is `null` (`None`, `nil`, `NULL` etc. depending on language). + + :param timestamp: UTC timestamp of the rating as ISO8601-1 pattern or UTC epoch time. The default value is the current time. + + :param cascade_create: Sets whether the given user/item should be created if not present in the database. + + :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. + """ 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 - - @param item_id: Viewed item - - @param portion: Viewed portion of the item (number between 0.0 (viewed nothing) and 1.0 (viewed full item) ). It should be the really viewed part of the item, no matter seeking, so for example if the user seeked immediately to half of the item and then viewed 10% of the item, the `portion` should still be `0.1`. - - - Optional parameters: - @param session_id: ID of session in which the user viewed the item. Default is `null` (`None`, `nil`, `NULL` etc. depending on language). - - @param timestamp: UTC timestamp of the rating as ISO8601-1 pattern or UTC epoch time. The default value is the current time. - - @param cascade_create: Sets whether the given user/item should be created if not present in the database. - - @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 self.portion = portion diff --git a/recombee_api_client/api_requests/user_based_recommendation.py b/recombee_api_client/api_requests/user_based_recommendation.py index 6f9e288..e86fa91 100644 --- a/recombee_api_client/api_requests/user_based_recommendation.py +++ b/recombee_api_client/api_requests/user_based_recommendation.py @@ -10,116 +10,117 @@ class UserBasedRecommendation(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. + + Required parameters: + + :param user_id: ID of the user for whom the 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. + + :param allow_nonexistent: If the user does not exist in the database, returns a list of non-personalized recommendations instead of causing HTTP 404 error. It doesn't create the user in the database. + + :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. + + :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. + + + Example response: + + ``` + + [ + + E{lb} + + "itemId": "tv-178", + + "description": "4K TV with 3D feature", + + "categories": ["Electronics", "Televisions"], + + "price": 342, + + "url": "myshop.com/tv-178" + E{rb}, + + E{lb} + + "itemId": "mixer-42", + + "description": "Stainless Steel Mixer", + + "categories": ["Home & Kitchen"], + + "price": 39, + + "url": "myshop.com/mixer-42" + E{rb} + + ] + + ``` + + + :param included_properties: Allows to specify, which properties should be returned when `returnProperties=true` is set. The properties are given as a comma-separated list. + + + Example response for `includedProperties=description,price`: + + ``` + + [ + + E{lb} + + "itemId": "tv-178", + + "description": "4K TV with 3D feature", + + "price": 342 + E{rb}, + + E{lb} + + "itemId": "mixer-42", + + "description": "Stainless Steel Mixer", + + "price": 39 + E{rb} + + ] + + ``` + + + :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 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. Default: `0.1`. + + + :param rotation_time: **Expert option** Taking *rotationRate* into account, specifies how long time it takes to an item to recover from the penalization. For example, `rotationTime=7200.0` means that items recommended less than 2 hours ago are penalized. Default: `7200.0`. + + + :param expert_settings: Dictionary of custom options. + + """ def __init__(self, user_id, count, filter=DEFAULT, booster=DEFAULT, allow_nonexistent=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): - """ - Required parameters: - @param user_id: ID of the user for whom the 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. - - @param allow_nonexistent: If the user does not exist in the database, returns a list of non-personalized recommendations instead of causing HTTP 404 error. It doesn't create the user in the database. - - @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. - - @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. - - - Example response: - - ``` - - [ - - E{lb} - - "itemId": "tv-178", - - "description": "4K TV with 3D feature", - - "categories": ["Electronics", "Televisions"], - - "price": 342, - - "url": "myshop.com/tv-178" - E{rb}, - - E{lb} - - "itemId": "mixer-42", - - "description": "Stainless Steel Mixer", - - "categories": ["Home & Kitchen"], - - "price": 39, - - "url": "myshop.com/mixer-42" - E{rb} - - ] - - ``` - - - @param included_properties: Allows to specify, which properties should be returned when `returnProperties=true` is set. The properties are given as a comma-separated list. - - - Example response for `includedProperties=description,price`: - - ``` - - [ - - E{lb} - - "itemId": "tv-178", - - "description": "4K TV with 3D feature", - - "price": 342 - E{rb}, - - E{lb} - - "itemId": "mixer-42", - - "description": "Stainless Steel Mixer", - - "price": 39 - E{rb} - - ] - - ``` - - - @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 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. Default: `0.1`. - - - @param rotation_time: **Expert option** Taking *rotationRate* into account, specifies how long time it takes to an item to recover from the penalization. For example, `rotationTime=7200.0` means that items recommended less than 2 hours ago are penalized. Default: `7200.0`. - - - @param expert_settings: Dictionary of custom options. - - - """ self.user_id = user_id self.count = count self.filter = filter diff --git a/setup.py b/setup.py index 4834209..51831d9 100644 --- a/setup.py +++ b/setup.py @@ -11,7 +11,7 @@ setup( name='recombee-api-client', - version='3.0.0', + version='3.1.0', description='Client for Recombee recommendation API', long_description=long_description, diff --git a/tests/test.py b/tests/test.py index 35f5aa2..a13021c 100644 --- a/tests/test.py +++ b/tests/test.py @@ -126,10 +126,12 @@ suite.addTests(unittest.defaultTestLoader.loadTestsFromTestCase(ListUserViewPortionsTestCase)) from tests.test_cases.test_recommend_items_to_user import RecommendItemsToUserTestCase suite.addTests(unittest.defaultTestLoader.loadTestsFromTestCase(RecommendItemsToUserTestCase)) - from tests.test_cases.test_recommend_users_to_user import RecommendUsersToUserTestCase - suite.addTests(unittest.defaultTestLoader.loadTestsFromTestCase(RecommendUsersToUserTestCase)) from tests.test_cases.test_recommend_items_to_item import RecommendItemsToItemTestCase suite.addTests(unittest.defaultTestLoader.loadTestsFromTestCase(RecommendItemsToItemTestCase)) + from tests.test_cases.test_recommend_next_items import RecommendNextItemsTestCase + suite.addTests(unittest.defaultTestLoader.loadTestsFromTestCase(RecommendNextItemsTestCase)) + from tests.test_cases.test_recommend_users_to_user import RecommendUsersToUserTestCase + suite.addTests(unittest.defaultTestLoader.loadTestsFromTestCase(RecommendUsersToUserTestCase)) from tests.test_cases.test_recommend_users_to_item import RecommendUsersToItemTestCase suite.addTests(unittest.defaultTestLoader.loadTestsFromTestCase(RecommendUsersToItemTestCase)) from tests.test_cases.test_search_items import SearchItemsTestCase diff --git a/tests/test_cases/add_entity.py b/tests/test_cases/add_entity.py index 193462b..a4ef7e0 100644 --- a/tests/test_cases/add_entity.py +++ b/tests/test_cases/add_entity.py @@ -19,7 +19,7 @@ def test_add_entity(self): req = self.create_request('valid_id') resp = self.client.send(req) # it 'fails with invalid entity id' - req = self.create_request('$$$not_valid$$$') + req = self.create_request('***not_valid$$$') try: self.client.send(req) self.assertFail() diff --git a/tests/test_cases/add_interaction.py b/tests/test_cases/add_interaction.py index c6b4e9b..7ad73b6 100644 --- a/tests/test_cases/add_interaction.py +++ b/tests/test_cases/add_interaction.py @@ -16,37 +16,37 @@ def create_request(self,user_id,item_id,timestamp=None,cascade_create=None,recom def test_add_interaction(self): # it 'does not fail with cascadeCreate' - req = self.create_request('u_id','i_id',cascade_create=True,additional_data={'answer': 42}) + req = self.create_request('u_id', 'i_id', cascade_create=True, additional_data={'answer': 42}) resp = self.client.send(req) # it 'does not fail with existing item and user' - req = self.create_request('entity_id','entity_id') + req = self.create_request('entity_id', 'entity_id') resp = self.client.send(req) # it 'does not fail with valid timestamp' - req = self.create_request('entity_id','entity_id',timestamp='2013-10-29T09:38:41.341Z') + req = self.create_request('entity_id', 'entity_id', timestamp='2013-10-29T09:38:41.341Z') resp = self.client.send(req) # it 'fails with nonexisting item id' - req = self.create_request('entity_id','nonex_id') + req = self.create_request('entity_id', 'nonex_id') try: self.client.send(req) self.assertFail() except ResponseException as ex: self.assertEqual(ex.status_code, 404) # it 'fails with nonexisting user id' - req = self.create_request('nonex_id','entity_id') + req = self.create_request('nonex_id', 'entity_id') try: self.client.send(req) self.assertFail() except ResponseException as ex: self.assertEqual(ex.status_code, 404) # it 'fails with invalid time' - req = self.create_request('entity_id','entity_id',timestamp=-15) + req = self.create_request('entity_id', 'entity_id', timestamp=-15) try: self.client.send(req) self.assertFail() except ResponseException as ex: self.assertEqual(ex.status_code, 400) # it 'really stores interaction to the system' - req = self.create_request('u_id2','i_id2',cascade_create=True,timestamp=5) + req = self.create_request('u_id2', 'i_id2', cascade_create=True, timestamp=5) resp = self.client.send(req) try: self.client.send(req) diff --git a/tests/test_cases/add_property.py b/tests/test_cases/add_property.py index a0f5f64..ebc5ac0 100644 --- a/tests/test_cases/add_property.py +++ b/tests/test_cases/add_property.py @@ -16,19 +16,19 @@ def create_request(self,property_name,type): def test_add_property(self): # it 'does not fail with valid name and type' - req = self.create_request('number','int') + req = self.create_request('number', 'int') resp = self.client.send(req) - req = self.create_request('str','string') + req = self.create_request('str', 'string') resp = self.client.send(req) # it 'fails with invalid type' - req = self.create_request('prop','integer') + req = self.create_request('prop', 'integer') try: self.client.send(req) self.assertFail() except ResponseException as ex: self.assertEqual(ex.status_code, 400) # it 'really stores property to the system' - req = self.create_request('number2','int') + req = self.create_request('number2', 'int') resp = self.client.send(req) try: self.client.send(req) diff --git a/tests/test_cases/add_rating.py b/tests/test_cases/add_rating.py index 5f24505..33f46b0 100644 --- a/tests/test_cases/add_rating.py +++ b/tests/test_cases/add_rating.py @@ -16,41 +16,41 @@ def create_request(self,user_id,item_id,rating,timestamp=None,cascade_create=Non def test_add_rating(self): # it 'does not fail with cascadeCreate' - req = self.create_request('u_id','i_id',1,cascade_create=True,additional_data={'answer': 42}) + req = self.create_request('u_id', 'i_id', 1, cascade_create=True, additional_data={'answer': 42}) resp = self.client.send(req) # it 'does not fail with existing item and user' - req = self.create_request('entity_id','entity_id',0) + req = self.create_request('entity_id', 'entity_id', 0) resp = self.client.send(req) # it 'fails with nonexisting item id' - req = self.create_request('entity_id','nonex_id',-1) + req = self.create_request('entity_id', 'nonex_id', -1) try: self.client.send(req) self.assertFail() except ResponseException as ex: self.assertEqual(ex.status_code, 404) # it 'fails with nonexisting user id' - req = self.create_request('nonex_id','entity_id',0.5) + req = self.create_request('nonex_id', 'entity_id', 0.5) try: self.client.send(req) self.assertFail() except ResponseException as ex: self.assertEqual(ex.status_code, 404) # it 'fails with invalid time' - req = self.create_request('entity_id','entity_id',0,timestamp=-15) + req = self.create_request('entity_id', 'entity_id', 0, timestamp=-15) try: self.client.send(req) self.assertFail() except ResponseException as ex: self.assertEqual(ex.status_code, 400) # it 'fails with invalid rating' - req = self.create_request('entity_id','entity_id',-2) + req = self.create_request('entity_id', 'entity_id', -2) try: self.client.send(req) self.assertFail() except ResponseException as ex: self.assertEqual(ex.status_code, 400) # it 'really stores interaction to the system' - req = self.create_request('u_id','i_id',0.3,cascade_create=True,timestamp=5) + req = self.create_request('u_id', 'i_id', 0.3, cascade_create=True, timestamp=5) resp = self.client.send(req) try: self.client.send(req) diff --git a/tests/test_cases/delete_entity.py b/tests/test_cases/delete_entity.py index f9c1b16..b10fd3a 100644 --- a/tests/test_cases/delete_entity.py +++ b/tests/test_cases/delete_entity.py @@ -24,7 +24,7 @@ def test_delete_entity(self): except ResponseException as ex: self.assertEqual(ex.status_code, 404) # it 'fails with invalid entity id' - req = self.create_request('$$$not_valid$$$') + req = self.create_request('***not_valid$$$') try: self.client.send(req) self.assertFail() diff --git a/tests/test_cases/delete_interaction.py b/tests/test_cases/delete_interaction.py index ecaedfd..181e4a2 100644 --- a/tests/test_cases/delete_interaction.py +++ b/tests/test_cases/delete_interaction.py @@ -16,9 +16,9 @@ def create_request(self,user_id,item_id,timestamp=None): def test_delete_interaction(self): # it 'does not fail with existing entity id' - req = self.create_request('user','item',timestamp=0) + req = self.create_request('user', 'item', timestamp=0) resp = self.client.send(req) - req = self.create_request('user','item') + req = self.create_request('user', 'item') try: self.client.send(req) self.assertFail() diff --git a/tests/test_cases/delete_property.py b/tests/test_cases/delete_property.py index 4733e62..7055a23 100644 --- a/tests/test_cases/delete_property.py +++ b/tests/test_cases/delete_property.py @@ -24,7 +24,7 @@ def test_delete_property(self): except ResponseException as ex: self.assertEqual(ex.status_code, 404) # it 'fails with invalid property' - req = self.create_request('$$$not_valid$$$') + req = self.create_request('***not_valid$$$') try: self.client.send(req) self.assertFail() diff --git a/tests/test_cases/delete_view_portion.py b/tests/test_cases/delete_view_portion.py index a77355e..2ce542a 100644 --- a/tests/test_cases/delete_view_portion.py +++ b/tests/test_cases/delete_view_portion.py @@ -16,9 +16,9 @@ def create_request(self,user_id,item_id,session_id=None): def test_delete_view_portion(self): # it 'does not fail with existing entity id' - req = self.create_request('user','item') + req = self.create_request('user', 'item') resp = self.client.send(req) - req = self.create_request('user','item') + req = self.create_request('user', 'item') try: self.client.send(req) self.assertFail() diff --git a/tests/test_cases/insert_to_group.py b/tests/test_cases/insert_to_group.py index 457bf1a..4b64e77 100644 --- a/tests/test_cases/insert_to_group.py +++ b/tests/test_cases/insert_to_group.py @@ -18,15 +18,15 @@ def test_insert_to_group(self): # it 'does not fail when inserting existing item into existing set' req = AddItem('new_item') resp = self.client.send(req) - req = self.create_request('entity_id','item','new_item') + req = self.create_request('entity_id', 'item', 'new_item') resp = self.client.send(req) # it 'does not fail when cascadeCreate is used' - req = self.create_request('new_set','item','new_item2',cascade_create=True) + req = self.create_request('new_set', 'item', 'new_item2', cascade_create=True) resp = self.client.send(req) # it 'really inserts item to the set' req = AddItem('new_item3') resp = self.client.send(req) - req = self.create_request('entity_id','item','new_item3') + req = self.create_request('entity_id', 'item', 'new_item3') resp = self.client.send(req) try: self.client.send(req) diff --git a/tests/test_cases/insert_to_series.py b/tests/test_cases/insert_to_series.py index cd53402..95b73be 100644 --- a/tests/test_cases/insert_to_series.py +++ b/tests/test_cases/insert_to_series.py @@ -18,15 +18,15 @@ def test_insert_to_series(self): # it 'does not fail when inserting existing item into existing set' req = AddItem('new_item') resp = self.client.send(req) - req = self.create_request('entity_id','item','new_item',3) + req = self.create_request('entity_id', 'item', 'new_item', 3) resp = self.client.send(req) # it 'does not fail when cascadeCreate is used' - req = self.create_request('new_set','item','new_item2',1,cascade_create=True) + req = self.create_request('new_set', 'item', 'new_item2', 1, cascade_create=True) resp = self.client.send(req) # it 'really inserts item to the set' req = AddItem('new_item3') resp = self.client.send(req) - req = self.create_request('entity_id','item','new_item3',2) + req = self.create_request('entity_id', 'item', 'new_item3', 2) resp = self.client.send(req) try: self.client.send(req) diff --git a/tests/test_cases/item_to_item_recommendation.py b/tests/test_cases/item_to_item_recommendation.py index 27f0927..e1e497c 100644 --- a/tests/test_cases/item_to_item_recommendation.py +++ b/tests/test_cases/item_to_item_recommendation.py @@ -16,12 +16,12 @@ def create_request(self,item_id,target_user_id,count,scenario=None,cascade_creat def test_item_to_item_recommendation(self): # it 'recommends' - req = self.create_request('entity_id','entity_id',9) + req = self.create_request('entity_id', 'entity_id', 9) resp = self.client.send(req) # it 'recommends to previously nonexisting entity with cascadeCreate' - req = self.create_request('nonexisting','entity_id',9,cascade_create=True) + req = self.create_request('nonexisting', 'entity_id', 9, cascade_create=True) resp = self.client.send(req) # it 'recommends with expert settings' - req = self.create_request('nonexisting2','entity_id',9,cascade_create=True,expert_settings={}) + req = self.create_request('nonexisting2', 'entity_id', 9, cascade_create=True, expert_settings={}) resp = self.client.send(req) diff --git a/tests/test_cases/merge_users.py b/tests/test_cases/merge_users.py index 68d8c92..ea77e21 100644 --- a/tests/test_cases/merge_users.py +++ b/tests/test_cases/merge_users.py @@ -18,10 +18,10 @@ def test_merge_users(self): # it 'does not fail with existing users' req = AddUser('target') resp = self.client.send(req) - req = self.create_request('target','entity_id') + req = self.create_request('target', 'entity_id') resp = self.client.send(req) # it 'fails with nonexisting user' - req = self.create_request('nonex_id','entity_id') + req = self.create_request('nonex_id', 'entity_id') try: self.client.send(req) self.assertFail() diff --git a/tests/test_cases/next_items_recommendation.py b/tests/test_cases/next_items_recommendation.py new file mode 100644 index 0000000..8b63132 --- /dev/null +++ b/tests/test_cases/next_items_recommendation.py @@ -0,0 +1,27 @@ +#!/usr/bin/env python +# -*- coding: utf-8 -*- +# +# This file is auto-generated, do not edit +# + +from tests.test_cases.recombee_test import RecombeeTest, InteractionsTest, RecommendationsTest +from recombee_api_client.exceptions import ResponseException +from recombee_api_client.api_requests import * + +class NextItemsRecommendationTest (RecommendationsTest ): + + def create_request(self,recomm_id,count): + pass + + def test_next_items_recommendation(self): + + # it 'recommends' + req = RecommendItemsToUser('entity_id', 3, return_properties=True) + resp = self.client.send(req) + req = self.create_request(resp['recommId'], 3) + resp = self.client.send(req) + self.assertEqual(len(resp['recomms']), 3) + req = self.create_request(resp['recommId'], 3) + resp = self.client.send(req) + self.assertEqual(len(resp['recomms']), 3) + diff --git a/tests/test_cases/recommendation.py b/tests/test_cases/recommendation.py index 67f6f57..7cda3fb 100644 --- a/tests/test_cases/recommendation.py +++ b/tests/test_cases/recommendation.py @@ -16,12 +16,12 @@ def create_request(self,user_id,count,scenario=None,cascade_create=None,return_p def test_recommendation(self): # it 'recommends' - req = self.create_request('entity_id',9) + req = self.create_request('entity_id', 9) resp = self.client.send(req) # it 'recommends to previously nonexisting entity with cascadeCreate' - req = self.create_request('nonexisting',9,cascade_create=True) + req = self.create_request('nonexisting', 9, cascade_create=True) resp = self.client.send(req) # it 'recommends with expert settings' - req = self.create_request('nonexisting2',9,cascade_create=True,expert_settings={}) + req = self.create_request('nonexisting2', 9, cascade_create=True, expert_settings={}) resp = self.client.send(req) diff --git a/tests/test_cases/recommendation_deprecated.py b/tests/test_cases/recommendation_deprecated.py index 1bb2d86..5fd2ef0 100644 --- a/tests/test_cases/recommendation_deprecated.py +++ b/tests/test_cases/recommendation_deprecated.py @@ -16,15 +16,15 @@ def create_request(self,user_id,count,filter=None,booster=None,allow_nonexistent def test_recommendation_deprecated(self): # it 'recommends' - req = self.create_request('entity_id',9) + req = self.create_request('entity_id', 9) resp = self.client.send(req) self.assertEqual(len(resp), 9) # it 'recommends to previously nonexisting entity with cascadeCreate' - req = self.create_request('nonexisting',9,cascade_create=True) + req = self.create_request('nonexisting', 9, cascade_create=True) resp = self.client.send(req) self.assertEqual(len(resp), 9) # it 'recommends with expert settings' - req = self.create_request('nonexisting2',9,cascade_create=True,expert_settings={}) + req = self.create_request('nonexisting2', 9, cascade_create=True, expert_settings={}) resp = self.client.send(req) self.assertEqual(len(resp), 9) diff --git a/tests/test_cases/remove_from_group.py b/tests/test_cases/remove_from_group.py index d776066..74984f1 100644 --- a/tests/test_cases/remove_from_group.py +++ b/tests/test_cases/remove_from_group.py @@ -16,10 +16,10 @@ def create_request(self,group_id,item_type,item_id): def test_remove_from_group(self): # it 'does not fail when removing item that is contained in the set' - req = self.create_request('entity_id','item','entity_id') + req = self.create_request('entity_id', 'item', 'entity_id') resp = self.client.send(req) # it 'fails when removing item that is not contained in the set' - req = self.create_request('entity_id','item','not_contained') + req = self.create_request('entity_id', 'item', 'not_contained') try: self.client.send(req) self.assertFail() diff --git a/tests/test_cases/remove_from_series.py b/tests/test_cases/remove_from_series.py index f047d14..368a142 100644 --- a/tests/test_cases/remove_from_series.py +++ b/tests/test_cases/remove_from_series.py @@ -16,17 +16,17 @@ def create_request(self,series_id,item_type,item_id,time): def test_remove_from_series(self): # it 'fails when removing item which have different time' - req = self.create_request('entity_id','item','entity_id',0) + req = self.create_request('entity_id', 'item', 'entity_id', 0) try: self.client.send(req) self.assertFail() except ResponseException as ex: self.assertEqual(ex.status_code, 404) # it 'does not fail when removing item that is contained in the set' - req = self.create_request('entity_id','item','entity_id',1) + req = self.create_request('entity_id', 'item', 'entity_id', 1) resp = self.client.send(req) # it 'fails when removing item that is not contained in the set' - req = self.create_request('entity_id','item','not_contained',1) + req = self.create_request('entity_id', 'item', 'not_contained', 1) try: self.client.send(req) self.assertFail() diff --git a/tests/test_cases/search.py b/tests/test_cases/search.py index cf61dcc..d91220a 100644 --- a/tests/test_cases/search.py +++ b/tests/test_cases/search.py @@ -16,15 +16,15 @@ def create_request(self,user_id,search_query,count,scenario=None,cascade_create= def test_search(self): # it 'finds "hello"' - req = self.create_request('entity_id','hell',9) + req = self.create_request('entity_id', 'hell', 9) resp = self.client.send(req) self.assertEqual(len(resp['recomms']), 1) # it 'does not find random string' - req = self.create_request('entity_id','sdhskldf',9) + req = self.create_request('entity_id', 'sdhskldf', 9) resp = self.client.send(req) self.assertEqual(len(resp['recomms']), 0) # it 'returnProperties' - req = self.create_request('entity_id','hell',9,return_properties=True) + req = self.create_request('entity_id', 'hell', 9, return_properties=True) resp = self.client.send(req) self.assertEqual(len(resp['recomms']), 1) diff --git a/tests/test_cases/set_values.py b/tests/test_cases/set_values.py index 04e1baf..e09bb7f 100644 --- a/tests/test_cases/set_values.py +++ b/tests/test_cases/set_values.py @@ -16,22 +16,22 @@ def create_request(self,item_id,values,cascade_create=None): def test_set_values(self): # it 'does not fail with existing entity and property' - req = self.create_request('entity_id',{'int_property': 5}) + req = self.create_request('entity_id', {'int_property': 5}) resp = self.client.send(req) # it 'does not fail with non-ASCII string' - req = self.create_request('entity_id',{'str_property': 'šřžذ的‎'}) + req = self.create_request('entity_id', {'str_property': 'šřžذ的‎'}) resp = self.client.send(req) # it 'sets multiple properties' - req = self.create_request('entity_id',{'int_property': 5,'str_property': 'test'}) + req = self.create_request('entity_id', {'int_property': 5,'str_property': 'test'}) resp = self.client.send(req) # it 'does not fail with !cascadeCreate' - req = self.create_request('new_entity',{'int_property': 5,'str_property': 'test','!cascadeCreate': True}) + req = self.create_request('new_entity', {'int_property': 5,'str_property': 'test','!cascadeCreate': True}) resp = self.client.send(req) # it 'does not fail with cascadeCreate optional parameter' - req = self.create_request('new_entity2',{'int_property': 5,'str_property': 'test'},cascade_create=True) + req = self.create_request('new_entity2', {'int_property': 5,'str_property': 'test'}, cascade_create=True) resp = self.client.send(req) # it 'fails with nonexisting entity' - req = self.create_request('nonexisting',{'int_property': 5}) + req = self.create_request('nonexisting', {'int_property': 5}) try: self.client.send(req) self.assertFail() diff --git a/tests/test_cases/set_view_portion.py b/tests/test_cases/set_view_portion.py index 216fcf7..ebbe585 100644 --- a/tests/test_cases/set_view_portion.py +++ b/tests/test_cases/set_view_portion.py @@ -16,41 +16,41 @@ def create_request(self,user_id,item_id,portion,session_id=None,timestamp=None,c def test_set_view_portion(self): # it 'does not fail with cascadeCreate' - req = self.create_request('u_id','i_id',1,cascade_create=True,additional_data={'answer': 42}) + req = self.create_request('u_id', 'i_id', 1, cascade_create=True, additional_data={'answer': 42}) resp = self.client.send(req) # it 'does not fail with existing item and user' - req = self.create_request('entity_id','entity_id',0) + req = self.create_request('entity_id', 'entity_id', 0) resp = self.client.send(req) # it 'fails with nonexisting item id' - req = self.create_request('entity_id','nonex_id',1) + req = self.create_request('entity_id', 'nonex_id', 1) try: self.client.send(req) self.assertFail() except ResponseException as ex: self.assertEqual(ex.status_code, 404) # it 'fails with nonexisting user id' - req = self.create_request('nonex_id','entity_id',0.5) + req = self.create_request('nonex_id', 'entity_id', 0.5) try: self.client.send(req) self.assertFail() except ResponseException as ex: self.assertEqual(ex.status_code, 404) # it 'fails with invalid time' - req = self.create_request('entity_id','entity_id',0,timestamp=-15) + req = self.create_request('entity_id', 'entity_id', 0, timestamp=-15) try: self.client.send(req) self.assertFail() except ResponseException as ex: self.assertEqual(ex.status_code, 400) # it 'fails with invalid portion' - req = self.create_request('entity_id','entity_id',-2) + req = self.create_request('entity_id', 'entity_id', -2) try: self.client.send(req) self.assertFail() except ResponseException as ex: self.assertEqual(ex.status_code, 400) # it 'fails with invalid sessionId' - req = self.create_request('entity_id','entity_id',0.7,session_id='a****') + req = self.create_request('entity_id', 'entity_id', 0.7, session_id='a****') try: self.client.send(req) self.assertFail() diff --git a/tests/test_cases/test_batch.py b/tests/test_cases/test_batch.py index 11ca44c..83d2c89 100644 --- a/tests/test_cases/test_batch.py +++ b/tests/test_cases/test_batch.py @@ -8,7 +8,6 @@ class BatchTestCase(RecombeeTest): def test_batch(self): reqs = [ - ResetDatabase(), AddItemProperty('num', 'int'), AddItemProperty('time', 'timestamp'), SetItemValues('item1', { @@ -32,11 +31,11 @@ def test_batch(self): resp = self.client.send(Batch(reqs)) codes = [r['code'] for r in resp] - self.assertEqual(codes, [200, 201, 201, 200, 409, 200, 200, 200, 200, 200, 404, 200, 200, 200]) - self.assertEqual(sorted(resp[6]['json']), ['item1', 'item2']) - self.assertEqual(resp[7]['json'], ['item2']) - self.assertEqual(resp[9]['json'], []) - self.assertEqual(resp[13]['json'], ['item2']) + self.assertEqual(codes, [201, 201, 200, 409, 200, 200, 200, 200, 200, 404, 200, 200, 200]) + self.assertEqual(sorted(resp[5]['json']), ['entity_id', 'item1', 'item2']) + self.assertEqual(resp[6]['json'], ['item2']) + self.assertEqual(resp[8]['json'], []) + self.assertEqual(resp[12]['json'], ['item2']) def test_large_batch(self): NUM = 23578 diff --git a/tests/test_cases/test_recommend_next_items.py b/tests/test_cases/test_recommend_next_items.py new file mode 100644 index 0000000..39f892a --- /dev/null +++ b/tests/test_cases/test_recommend_next_items.py @@ -0,0 +1,13 @@ +#!/usr/bin/env python +# -*- coding: utf-8 -*- +# +# This file is auto-generated, do not edit +# + +from tests.test_cases.next_items_recommendation import NextItemsRecommendationTest +from recombee_api_client.api_requests import * + +class RecommendNextItemsTestCase (NextItemsRecommendationTest): + + def create_request(self, recomm_id, count): + return RecommendNextItems(recomm_id, count)