Release: v6.2.0

- Added recommend-next-item-segments endpoint support
- Added `searchQuery` parameter support for composite recommendations

Author: MichalDemko

recombee_api_client/api_client.py

@@ -105,7 +105,7 @@ def __get_base_uri(options: dict, region: str) -> str:
 
     @staticmethod
     def __get_http_headers(additional_headers: dict = None) -> dict:
-        headers = {"User-Agent": "recombee-python-api-client/6.1.0"}
+        headers = {"User-Agent": "recombee-python-api-client/6.2.0"}
         if additional_headers:
             headers.update(additional_headers)
         return headers

recombee_api_client/api_requests/__init__.py

@@ -82,6 +82,9 @@
 from recombee_api_client.api_requests.recommend_item_segments_to_item_segment import (
     RecommendItemSegmentsToItemSegment,
 )
+from recombee_api_client.api_requests.recommend_next_item_segments import (
+    RecommendNextItemSegments,
+)
 from recombee_api_client.api_requests.composite_recommendation import (
     CompositeRecommendation,
 )

recombee_api_client/api_requests/composite_recommendation.py

@@ -13,7 +13,7 @@
 
 class CompositeRecommendation(Request):
     """
-    Composite Recommendation returns both a *source entity* (e.g., an Item or [Item Segment](https://docs.recombee.com/segmentations.html)) and a list of related recommendations in a single response.
+    Composite Recommendation returns both a *source entity* (e.g., an Item or [Item Segment](https://docs.recombee.com/segmentations)) and a list of related recommendations in a single response.
 
     It is ideal for use cases such as personalized homepage sections (*Articles from <category>*), *Because You Watched <movie>*, or *Artists Related to Your Favorite Artist <artist>*.
 
@@ -79,6 +79,9 @@ class CompositeRecommendation(Request):
     :param segment_id: ID of the segment from `contextSegmentationId` for which the recommendations are to be generated.
 
 
+    :param search_query: Search query provided by the user. It is used for the full-text search. Only applicable if the *scenario* corresponds to a search scenario.
+
+
     :param cascade_create: If the entity for the source recommendation 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 entity, as the entity will be already known to the system.
 
 
@@ -101,6 +104,7 @@ def __init__(
         user_id: str = DEFAULT,
         logic: Logic = DEFAULT,
         segment_id: str = DEFAULT,
+        search_query: str = DEFAULT,
         cascade_create: bool = DEFAULT,
         source_settings: CompositeRecommendationStageParameters = DEFAULT,
         result_settings: CompositeRecommendationStageParameters = DEFAULT,
@@ -115,6 +119,7 @@ def __init__(
         self.user_id = user_id
         self.logic = logic
         self.segment_id = segment_id
+        self.search_query = search_query
         self.cascade_create = cascade_create
         self.source_settings = source_settings
         self.result_settings = result_settings
@@ -135,6 +140,8 @@ def get_body_parameters(self) -> dict:
             p["logic"] = serialize_to_json(self.logic)
         if self.segment_id is not DEFAULT:
             p["segmentId"] = serialize_to_json(self.segment_id)
+        if self.search_query is not DEFAULT:
+            p["searchQuery"] = serialize_to_json(self.search_query)
         if self.cascade_create is not DEFAULT:
             p["cascadeCreate"] = serialize_to_json(self.cascade_create)
         if self.source_settings is not DEFAULT:

recombee_api_client/api_requests/recommend_next_item_segments.py

@@ -0,0 +1,64 @@
+from recombee_api_client.api_requests.request import Request
+from recombee_api_client.utils.serialize_to_json import serialize_to_json
+from typing import Union, List
+from datetime import datetime
+import uuid
+
+DEFAULT = uuid.uuid4()
+
+
+class RecommendNextItemSegments(Request):
+    """
+    Returns Item segments that shall be shown to a user as next recommendations when the user e.g. scrolls the page down (*infinite scroll*) or goes to the next page.
+
+    It accepts `recommId` of a base recommendation request (e.g., request from the first page) and the number of segments that shall be returned (`count`).
+    The base request can be one of:
+      - [Recommend Item Segments to Item](https://docs.recombee.com/api#recommend-item-segments-to-item)
+      - [Recommend Item Segments to User](https://docs.recombee.com/api#recommend-item-segments-to-user)
+      - [Recommend Item Segments to Item Segment](https://docs.recombee.com/api#recommend-item-segments-to-item-segment)
+      - [Search Item Segments](https://docs.recombee.com/api#search-item-segments)
+
+    All the other parameters are inherited from the base request.
+
+    *Recommend next Item segments* can be called many times for a single `recommId` and each call returns different (previously not recommended) segments.
+    The number of *Recommend next Item segments* calls performed so far is returned in the `numberNextRecommsCalls` field.
+
+    *Recommend next Item segments* can be requested up to 30 minutes after the base request or a previous *Recommend next Item segments* call.
+
+    For billing purposes, each call to *Recommend next Item segments* 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 item segments to be recommended
+
+
+    """
+
+    def __init__(self, recomm_id: str, count: int):
+        super().__init__(
+            path="/recomms/next/item-segments/%s" % (recomm_id),
+            method="post",
+            timeout=3000,
+            ensure_https=False,
+        )
+        self.recomm_id = recomm_id
+        self.count = count
+
+    def get_body_parameters(self) -> dict:
+        """
+        Values of body parameters as a dictionary (name of parameter: value of the parameter).
+        """
+        p = dict()
+        p["count"] = serialize_to_json(self.count)
+
+        return p
+
+    def get_query_parameters(self) -> dict:
+        """
+        Values of query parameters as a dictionary (name of parameter: value of the parameter).
+        """
+        params = dict()
+
+        return params

setup.py

@@ -10,7 +10,7 @@
 
 setup(
     name="recombee-api-client",
-    version="6.1.0",
+    version="6.2.0",
     description="Client for Recombee recommendation API",
     long_description=long_description,
     url="https://github.com/Recombee/python-api-client",

tests/test.py

@@ -326,6 +326,15 @@
             RecommendItemSegmentsToItemSegmentTestCase
         )
     )
+    from tests.test_cases.test_recommend_next_item_segments import (
+        RecommendNextItemSegmentsTestCase,
+    )
+
+    suite.addTests(
+        unittest.defaultTestLoader.loadTestsFromTestCase(
+            RecommendNextItemSegmentsTestCase
+        )
+    )
     from tests.test_cases.test_composite_recommendation import (
         CompositeRecommendationTestCase,
     )

tests/test_cases/composite_recommendation.py

@@ -26,6 +26,7 @@ def create_request(
         user_id=None,
         logic=None,
         segment_id=None,
+        search_query=None,
         cascade_create=None,
         source_settings=None,
         result_settings=None,

tests/test_cases/next_item_segments_recommendation.py

@@ -0,0 +1,41 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+#
+# This file is auto-generated, do not edit
+#
+
+import time
+from abc import ABC, abstractmethod
+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 NextItemSegmentsRecommendationTest(RecombeeTest, ABC):
+
+    @abstractmethod
+    def create_request(self, recomm_id, count):
+        pass
+
+    def test_next_item_segments_recommendation(self):
+
+        # it 'rejects request with invalid recommId'
+        req = RecommendNextItemSegments("invalid_recomm_id", 5)
+        try:
+            self.client.send(req)
+            self.fail()
+        except ResponseException as ex:
+            self.assertEqual(ex.status_code, 400)
+        # it 'rejects request to recommId which does not return item-segments'
+        req = RecommendItemsToUser("entity_id", 3)
+        resp = self.client.send(req)
+        req = self.create_request(resp["recommId"], 5)
+        try:
+            self.client.send(req)
+            self.fail()
+        except ResponseException as ex:
+            self.assertEqual(ex.status_code, 400)

tests/test_cases/test_composite_recommendation.py

@@ -21,6 +21,7 @@ def create_request(
         user_id=DEFAULT,
         logic=DEFAULT,
         segment_id=DEFAULT,
+        search_query=DEFAULT,
         cascade_create=DEFAULT,
         source_settings=DEFAULT,
         result_settings=DEFAULT,
@@ -33,6 +34,7 @@ def create_request(
             user_id=user_id,
             logic=logic,
             segment_id=segment_id,
+            search_query=search_query,
             cascade_create=cascade_create,
             source_settings=source_settings,
             result_settings=result_settings,

tests/test_cases/test_recommend_next_item_segments.py

@@ -0,0 +1,19 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+#
+# This file is auto-generated, do not edit
+#
+
+from tests.test_cases.next_item_segments_recommendation import (
+    NextItemSegmentsRecommendationTest,
+)
+from recombee_api_client.api_requests.recommend_next_item_segments import (
+    RecommendNextItemSegments,
+    DEFAULT,
+)
+
+
+class RecommendNextItemSegmentsTestCase(NextItemSegmentsRecommendationTest):
+
+    def create_request(self, recomm_id, count):
+        return RecommendNextItemSegments(recomm_id, count)