recombee_api_client 5.1.0 → 6.0.0

data/lib/recombee_api_client/api/update_more_items.rb

@@ -5,11 +5,11 @@
 module RecombeeApiClient
   require_relative 'request'
   require_relative '../errors'
-  
+
   ##
-  #Updates (some) property values of all the items that pass the filter.
+  # Updates (some) property values of all the items that pass the filter.
   #
-  #Example: *Setting all the items that are older than a week as unavailable*
+  # Example: *Setting all the items that are older than a week as unavailable*
   #
   #  ```json
   #    {
@@ -20,44 +20,43 @@ module RecombeeApiClient
   #
   class UpdateMoreItems < ApiRequest
     attr_reader :filter, :changes
-    attr_accessor :timeout
-    attr_accessor :ensure_https
-  
-  ##
-  # * *Required arguments*
-  #   - +filter+ -> A [ReQL](https://docs.recombee.com/reql) expression, which returns `true` for the items that shall be updated.
-  #   - +changes+ -> A dictionary where the keys are properties that shall be updated.
-  #
+    attr_accessor :timeout, :ensure_https
+
+    ##
+    # * *Required arguments*
+    #   - +filter+ -> A [ReQL](https://docs.recombee.com/reql) expression, which returns `true` for the items that shall be updated.
+    #   - +changes+ -> A dictionary where the keys are properties that shall be updated.
+    #
     def initialize(filter, changes)
       @filter = filter
       @changes = changes
-      @timeout = 100000
+      @timeout = 100_000
       @ensure_https = false
     end
-  
+
     # HTTP method
     def method
       :post
     end
-  
+
     # Values of body parameters as a Hash
     def body_parameters
-      p = Hash.new
+      p = {}
       p['filter'] = @filter
       p['changes'] = @changes
+
       p
     end
-  
+
     # Values of query parameters as a Hash.
     # name of parameter => value of the parameter
     def query_parameters
-      params = {}
-      params
+      {}
     end
-  
+
     # Relative path to the endpoint
     def path
-      "/{databaseId}/more-items/"
+      '/{databaseId}/more-items/'
     end
   end
 end

data/lib/recombee_api_client/api/update_property_based_segmentation.rb

@@ -5,62 +5,61 @@
 module RecombeeApiClient
   require_relative 'request'
   require_relative '../errors'
-  
+
   ##
-  #Updates a Property Based Segmentation
+  # Updates a Property Based Segmentation
   #
   class UpdatePropertyBasedSegmentation < ApiRequest
     attr_reader :segmentation_id, :property_name, :title, :description
-    attr_accessor :timeout
-    attr_accessor :ensure_https
-  
-  ##
-  # * *Required arguments*
-  #   - +segmentation_id+ -> ID of the updated Segmentation
-  #
-  # * *Optional arguments (given as hash optional)*
-  #   - +propertyName+ -> Name of the property on which the Segmentation should be based
-  #
-  #   - +title+ -> Human-readable name that is shown in the Recombee Admin UI.
-  #
-  #   - +description+ -> Description that is shown in the Recombee Admin UI.
-  #
-  #
+    attr_accessor :timeout, :ensure_https
+
+    ##
+    # * *Required arguments*
+    #   - +segmentation_id+ -> ID of the updated Segmentation
+    #
+    # * *Optional arguments (given as hash optional)*
+    #   - +propertyName+ -> Name of the property on which the Segmentation should be based
+    #
+    #   - +title+ -> Human-readable name that is shown in the Recombee Admin UI.
+    #
+    #   - +description+ -> Description that is shown in the Recombee Admin UI.
+    #
+    #
     def initialize(segmentation_id, optional = {})
       @segmentation_id = segmentation_id
-      optional = normalize_optional(optional)
+      optional = normalize_hash_to_camel_case(optional)
       @property_name = optional['propertyName']
       @title = optional['title']
       @description = optional['description']
       @optional = optional
-      @timeout = 10000
+      @timeout = 10_000
       @ensure_https = false
       @optional.each do |par, _|
-        fail UnknownOptionalParameter.new(par) unless ["propertyName","title","description"].include? par
+        raise UnknownOptionalParameter.new(par) unless %w[propertyName title description].include? par
       end
     end
-  
+
     # HTTP method
     def method
       :post
     end
-  
+
     # Values of body parameters as a Hash
     def body_parameters
-      p = Hash.new
+      p = {}
       p['propertyName'] = @optional['propertyName'] if @optional.include? 'propertyName'
       p['title'] = @optional['title'] if @optional.include? 'title'
       p['description'] = @optional['description'] if @optional.include? 'description'
+
       p
     end
-  
+
     # Values of query parameters as a Hash.
     # name of parameter => value of the parameter
     def query_parameters
-      params = {}
-      params
+      {}
     end
-  
+
     # Relative path to the endpoint
     def path
       "/{databaseId}/segmentations/property-based/#{@segmentation_id}"

data/lib/recombee_api_client/errors.rb

@@ -5,11 +5,9 @@ module RecombeeApiClient
 
   # Response is not 200 or 201
   class ResponseError < APIError
-    attr_reader :request
-    attr_reader :status_code
-    attr_reader :description
+    attr_reader :request, :status_code, :description
 
-    def initialize(request, status_code, description)
+    def initialize(_request, status_code, description)
       @status_code = status_code
       @description = description
     end
@@ -40,5 +38,4 @@ module RecombeeApiClient
       "ApiTimeout: client did not get response within #{@request.timeout} ms"
     end
   end
-
 end

data/lib/recombee_api_client/inputs/composite_recommendation_stage_parameters.rb

@@ -0,0 +1,240 @@
+#
+# This file is auto-generated, do not edit
+#
+
+require 'json'
+
+module RecombeeApiClient
+  require_relative 'input'
+  require_relative '../errors'
+
+  ##
+  # Initializes CompositeRecommendationStageParameters input#
+  class CompositeRecommendationStageParameters < Input
+    attr_reader :return_properties, :included_properties, :filter, :booster, :logic, :reql_expressions, :min_relevance,
+                :rotation_rate, :rotation_time
+
+    ##
+    #
+    # * *Optional arguments (given as hash optional)*
+    #   - +returnProperties+ -> 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 to easily display the recommended items to the user.
+    #
+    # Example response with `returnProperties` set in the `resultSettings`:
+    # ```json
+    #    {
+    #      "recommId": "ee94fa8b-efe7-4b35-abc6-2bc3456d66ed",
+    #      "source": {
+    #        "id": "category-sport"
+    #      },
+    #      "recomms": [
+    #        {
+    #          "id": "article-1024",
+    #          "values": {
+    #            "title": "Champions League: Stunning Comeback Secures Final Spot",
+    #            "categories": ["Sport", "Football"],
+    #            "author": "Jane Smith",
+    #            "url": "newsportal.com/articles/champions-league-comeback"
+    #          }
+    #        },
+    #        {
+    #          "id": "article-2031",
+    #          "values": {
+    #            "title": "Top 10 Moments from the Summer Olympics",
+    #            "categories": ["Sport", "Olympics"],
+    #            "author": "Mark Johnson",
+    #            "url": "newsportal.com/articles/olympic-top-moments"
+    #          }
+    #        },
+    #        {
+    #          "id": "article-3042",
+    #          "values": {
+    #            "title": "Rising Stars in Women's Tennis to Watch This Season",
+    #            "categories": ["Sport", "Tennis"],
+    #            "author": "Laura Chen",
+    #            "url": "newsportal.com/articles/womens-tennis-stars"
+    #          }
+    #        }
+    #      ],
+    #      "numberNextRecommsCalls": 0
+    #    }
+    #
+    # ```
+    #
+    #   - +includedProperties+ -> Allows specifying which properties should be returned when `returnProperties=true` is set. The properties are given as a comma-separated list.
+    #
+    # Example response for  `returnProperties=true` and `includedProperties=title,url` set in `resultSettings`:
+    # ```json
+    #  {
+    #    "recommId": "ee94fa8b-efe7-4b35-abc6-2bc3456d66ed",
+    #    "source": {
+    #      "id": "category-sport"
+    #    },
+    #    "recomms": [
+    #      {
+    #        "id": "article-1024",
+    #        "values": {
+    #          "title": "Champions League: Stunning Comeback Secures Final Spot",
+    #          "url": "newsportal.com/articles/champions-league-comeback"
+    #        }
+    #      },
+    #      {
+    #        "id": "article-2031",
+    #        "values": {
+    #          "title": "Top 10 Moments from the Summer Olympics",
+    #          "url": "newsportal.com/articles/olympic-top-moments"
+    #        }
+    #      },
+    #      {
+    #        "id": "article-3042",
+    #        "values": {
+    #          "title": "Rising Stars in Women's Tennis to Watch This Season",
+    #          "url": "newsportal.com/articles/womens-tennis-stars"
+    #        }
+    #      }
+    #    ],
+    #    "numberNextRecommsCalls": 0
+    #  }
+    #
+    # ```
+    #
+    #   - +filter+ -> Boolean-returning [ReQL](https://docs.recombee.com/reql) expression, which allows you to filter recommended entities based on the values of their attributes.
+    #
+    # Filters can also be assigned to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com).
+    #
+    #   - +booster+ -> Number-returning [ReQL](https://docs.recombee.com/reql) expression, which allows you to boost the recommendation rate of some entities based on the values of their attributes.
+    #
+    # Boosters can also be assigned to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com).
+    #
+    #   - +logic+ -> Logic specifies the 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) for a 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 also be set to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com).
+    #
+    #   - +reqlExpressions+ -> Only usable if the stage corresponds to the one of these recommendation endpoints:
+    #
+    # - [Recommend Items To User](https://docs.recombee.com/api#recommend-items-to-user)
+    # - [Recommend Items To Item](https://docs.recombee.com/api#recommend-items-to-item)
+    # - [Recommend Items to Item Segment](https://docs.recombee.com/api#recommend-items-to-item-segment)
+    # - [Recommend Users to Item](https://docs.recombee.com/api#recommend-users-to-item)
+    # - [Recommend Users To User](https://docs.recombee.com/api#recommend-users-to-user)
+    #
+    # A dictionary of [ReQL](https://docs.recombee.com/reql) expressions that will be executed for each recommended item.
+    # This can be used to compute additional properties of the recommended items that are not stored in the database.
+    #
+    # The keys are the names of the expressions, and the values are the actual ReQL expressions.
+    #
+    # Example request:
+    # ```json
+    # {
+    #  "reqlExpressions": {
+    #    "isInUsersCity": "context_user[\"city\"] in 'cities'",
+    #    "distanceToUser": "earth_distance('location', context_user[\"location\"])"
+    #  }
+    # }
+    # ```
+    #
+    # Example response:
+    # ```json
+    # {
+    #  "recommId": "ce52ada4-e4d9-4885-943c-407db2dee837",
+    #  "source": {
+    #    "id": "restaurant-123",
+    #    "reqlEvaluations": {
+    #      "isInUsersCity": true,
+    #      "distanceToUser": 3450.5
+    #    }
+    #  },
+    #  "recomms":
+    #    [
+    #      {
+    #        "id": "restaurant-178",
+    #        "reqlEvaluations": {
+    #          "isInUsersCity": true,
+    #          "distanceToUser": 5200.2
+    #        }
+    #      },
+    #      {
+    #        "id": "bar-42",
+    #        "reqlEvaluations": {
+    #          "isInUsersCity": false,
+    #          "distanceToUser": 2516.0
+    #        }
+    #      }
+    #    ],
+    #   "numberNextRecommsCalls": 0
+    # }
+    # ```
+    #
+    #   - +minRelevance+ -> **Expert option:** Only usable if the stage corresponds to the one of these recommendation endpoints:
+    #
+    # - [Recommend Items To User](https://docs.recombee.com/api#recommend-items-to-user)
+    # - [Recommend Items To Item](https://docs.recombee.com/api#recommend-items-to-item)
+    # - [Recommend Items to Item Segment](https://docs.recombee.com/api#recommend-items-to-item-segment)
+    #
+    # If the *userId* is provided:  Specifies the threshold of how 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 a number of items equal to *count* at any cost. If there is not enough data (such as interactions or item properties), this may even lead to bestseller-based recommendations being 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.
+    #
+    #   - +rotationRate+ -> **Expert option:** Only usable if the stage corresponds to the one of these recommendation endpoints:
+    # - [Recommend Items To User](https://docs.recombee.com/api#recommend-items-to-user)
+    # - [Recommend Items To Item](https://docs.recombee.com/api#recommend-items-to-item)
+    # - [Recommend Items to Item Segment](https://docs.recombee.com/api#recommend-items-to-item-segment)
+    # - [Recommend Users To User](https://docs.recombee.com/api#recommend-users-to-user)
+    #
+    # If the *userId* 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 a 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.
+    #
+    #   - +rotationTime+ -> **Expert option:** Only usable if the stage corresponds to the one of these recommendation endpoints:
+    # - [Recommend Items To User](https://docs.recombee.com/api#recommend-items-to-user)
+    # - [Recommend Items To Item](https://docs.recombee.com/api#recommend-items-to-item)
+    # - [Recommend Items to Item Segment](https://docs.recombee.com/api#recommend-items-to-item-segment)
+    # - [Recommend Users To User](https://docs.recombee.com/api#recommend-users-to-user)
+    #
+    # If the *userId* is provided: Taking *rotationRate* into account, specifies how long it takes for an item to recover from the penalization. For example, `rotationTime=7200.0` means that items recommended less than 2 hours ago are penalized.
+    #
+    #
+    def initialize(optional = {})
+      optional = normalize_hash_to_camel_case(optional)
+      @return_properties = optional['returnProperties']
+      @included_properties = optional['includedProperties']
+      @filter = optional['filter']
+      @booster = optional['booster']
+      @logic = optional['logic']
+      @reql_expressions = optional['reqlExpressions']
+      @min_relevance = optional['minRelevance']
+      @rotation_rate = optional['rotationRate']
+      @rotation_time = optional['rotationTime']
+      @optional = optional
+      @optional.each do |par, _|
+        raise UnknownOptionalParameter.new(par) unless %w[returnProperties includedProperties filter booster
+                                                          logic reqlExpressions minRelevance rotationRate rotationTime].include? par
+      end
+    end
+
+    # Return only JSON-serializable primitives.
+    def as_json(_options = {})
+      res = {}
+      res['returnProperties'] = @optional['returnProperties'] if @optional['returnProperties']
+      res['includedProperties'] = @optional['includedProperties'] if @optional['includedProperties']
+      res['filter'] = @optional['filter'] if @optional['filter']
+      res['booster'] = @optional['booster'] if @optional['booster']
+      res['logic'] = @optional['logic'] if @optional['logic']
+      res['reqlExpressions'] = @optional['reqlExpressions'] if @optional['reqlExpressions']
+      res['minRelevance'] = @optional['minRelevance'] if @optional['minRelevance']
+      res['rotationRate'] = @optional['rotationRate'] if @optional['rotationRate']
+      res['rotationTime'] = @optional['rotationTime'] if @optional['rotationTime']
+
+      res
+    end
+
+    def to_json(*args)
+      as_json.to_json(*args)
+    end
+  end
+end

data/lib/recombee_api_client/inputs/input.rb

@@ -0,0 +1,9 @@
+module RecombeeApiClient
+  ##
+  # Parent class for all inputs
+  #
+  class Input
+    require_relative '../utils/hash_normalizer'
+    include RecombeeApiClient::HashNormalizer
+  end
+end

data/lib/recombee_api_client/inputs/logic.rb

@@ -0,0 +1,45 @@
+#
+# This file is auto-generated, do not edit
+#
+
+require 'json'
+
+module RecombeeApiClient
+  require_relative 'input'
+  require_relative '../errors'
+
+  ##
+  # Initializes Logic input#
+  class Logic < Input
+    attr_reader :name, :settings
+
+    ##
+    #
+    # * *Optional arguments (given as hash optional)*
+    #   - +name+ -> Name of the logic that should be used
+    #   - +settings+ -> Parameters passed to the logic
+    #
+    def initialize(optional = {})
+      optional = normalize_hash_to_camel_case(optional)
+      @name = optional['name']
+      @settings = optional['settings']
+      @optional = optional
+      @optional.each do |par, _|
+        raise UnknownOptionalParameter.new(par) unless %w[name settings].include? par
+      end
+    end
+
+    # Return only JSON-serializable primitives.
+    def as_json(_options = {})
+      res = {}
+      res['name'] = @optional['name'] if @optional['name']
+      res['settings'] = @optional['settings'] if @optional['settings']
+
+      res
+    end
+
+    def to_json(*args)
+      as_json.to_json(*args)
+    end
+  end
+end

data/lib/recombee_api_client/utils/hash_normalizer.rb

@@ -0,0 +1,21 @@
+module RecombeeApiClient
+  ##
+  # Module to convert Ruby conventions to Recombee's API namings
+  #
+  module HashNormalizer
+    def normalize_hash_to_camel_case(h)
+      return h unless h.is_a?(Hash)
+
+      h_new = {}
+      h.each do |k, v|
+        key = k.is_a?(String) ? camelize(k) : camelize(k.to_s)
+        h_new[key] = v
+      end
+      h_new
+    end
+
+    def camelize(str)
+      str.gsub(/_(.)/) { |_e| ::Regexp.last_match(1).upcase }
+    end
+  end
+end

data/lib/recombee_api_client/version.rb

@@ -1,3 +1,3 @@
 module RecombeeApiClient
-  VERSION = '5.1.0'
+  VERSION = '6.0.0'
 end