Class: RecombeeApiClient::CompositeRecommendation

Inherits:
ApiRequest
  • Object
show all
Defined in:
lib/recombee_api_client/api/composite_recommendation.rb

Overview

Composite Recommendation returns both a *source entity* (e.g., an Item or [Item Segment](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>*.

See detailed **examples and configuration guidance** in the [Composite Scenarios documentation](docs.recombee.com/scenarios#composite-recommendations).

Structure

The endpoint operates in two stages:

  1. Recommends the source (e.g., an Item Segment or item) to the user.

  2. Recommends results (items or Item Segments) related to that source.

For example, *Articles from <category>* can be decomposed into:

- [Recommend Item Segments To User](https://docs.recombee.com/api#recommend-item-segments-to-user) to find the category.
- [Recommend Items To Item Segment](https://docs.recombee.com/api#recommend-items-to-item-segment) to recommend articles from that category.

Since the first step uses [Recommend Item Segments To User](docs.recombee.com/api#recommend-items-to-user), you must include the ‘userId` parameter in the *Composite Recommendation* request.

Each *Composite Recommendation* counts as a single recommendation API request for billing.

**Stage-specific Parameters**

Additional parameters can be supplied via [sourceSettings](docs.recombee.com/api#composite-recommendation-param-sourceSettings) and [resultSettings](docs.recombee.com/api#composite-recommendation-param-resultSettings). In the example above:

- `sourceSettings` may include any parameter valid for [Recommend Item Segments To User](https://docs.recombee.com/api#recommend-items-to-user) (e.g., `filter`, `booster`).
- `resultSettings` may include any parameter valid for [Recommend Items To Item Segment](https://docs.recombee.com/api#recommend-items-to-item-segment).

See [this example](docs.recombee.com/api#composite-recommendation-example-setting-parameters-for-individual-stages) for more details.

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from HashNormalizer

#camelize, #normalize_hash_to_camel_case

Constructor Details

#initialize(scenario, count, optional = {}) ⇒ CompositeRecommendation

  • *Required arguments*

    • 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](docs.recombee.com/scenarios) in the [Admin UI](admin.recombee.com). You can also see the performance of each scenario in the Admin UI separately, so you can check how well each application performs.

The AI that optimizes models to get the best results may optimize different scenarios separately or even use different models in each of the scenarios.

- +count+ -> Number of items to be recommended (N for the top-N recommendation).

  • *Optional arguments (given as hash optional)*

    • itemId -> ID of the item for which the recommendations are to be generated.

    • userId -> ID of the user for which the recommendations are to be generated.

    • logic -> Logic specifies the particular behavior of the recommendation models. You can pick tailored logic for your domain and use case.

See [this section](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](docs.recombee.com/scenarios) in the [Admin UI](admin.recombee.com).

- +segmentId+ -> ID of the segment from `contextSegmentationId` for which the recommendations are to be generated.

- +searchQuery+ -> Search query provided by the user. It is used for the full-text search. Only applicable if the *scenario* corresponds to a search scenario.

- +cascadeCreate+ -> 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.

- +sourceSettings+ -> Parameters applied for recommending the *Source* stage. The accepted parameters correspond with the recommendation sub-endpoint used to recommend the *Source*.

- +resultSettings+ -> Parameters applied for recommending the *Result* stage. The accepted parameters correspond with the recommendation sub-endpoint used to recommend the *Result*.

- +expertSettings+ -> Dictionary of custom options.



80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
 
# File 'lib/recombee_api_client/api/composite_recommendation.rb', line 80

def initialize(scenario, count, optional = {})
  @scenario = scenario
  @count = count
  optional = normalize_hash_to_camel_case(optional)
  @item_id = optional['itemId']
  @user_id = optional['userId']
  @logic = optional['logic']
  @segment_id = optional['segmentId']
  @search_query = optional['searchQuery']
  @cascade_create = optional['cascadeCreate']
  @source_settings = optional['sourceSettings']
  @result_settings = optional['resultSettings']
  @expert_settings = optional['expertSettings']
  @optional = optional
  @timeout = 3000
  @ensure_https = false
  @optional.each do |par, _|
    raise UnknownOptionalParameter.new(par) unless %w[itemId userId logic segmentId searchQuery
                                                      cascadeCreate sourceSettings resultSettings expertSettings].include? par
  end
end

Instance Attribute Details

#cascade_create ⇒ Object (readonly)

Returns the value of attribute cascade_create.



40
41
42
 
# File 'lib/recombee_api_client/api/composite_recommendation.rb', line 40

def cascade_create
  @cascade_create
end

#count ⇒ Object (readonly)

Returns the value of attribute count.



40
41
42
 
# File 'lib/recombee_api_client/api/composite_recommendation.rb', line 40

def count
  @count
end

#ensure_https ⇒ Object

Returns the value of attribute ensure_https.



42
43
44
 
# File 'lib/recombee_api_client/api/composite_recommendation.rb', line 42

def ensure_https
  @ensure_https
end

#expert_settings ⇒ Object (readonly)

Returns the value of attribute expert_settings.



40
41
42
 
# File 'lib/recombee_api_client/api/composite_recommendation.rb', line 40

def expert_settings
  @expert_settings
end

#item_id ⇒ Object (readonly)

Returns the value of attribute item_id.



40
41
42
 
# File 'lib/recombee_api_client/api/composite_recommendation.rb', line 40

def item_id
  @item_id
end

#logic ⇒ Object (readonly)

Returns the value of attribute logic.



40
41
42
 
# File 'lib/recombee_api_client/api/composite_recommendation.rb', line 40

def logic
  @logic
end

#result_settings ⇒ Object (readonly)

Returns the value of attribute result_settings.



40
41
42
 
# File 'lib/recombee_api_client/api/composite_recommendation.rb', line 40

def result_settings
  @result_settings
end

#scenario ⇒ Object (readonly)

Returns the value of attribute scenario.



40
41
42
 
# File 'lib/recombee_api_client/api/composite_recommendation.rb', line 40

def scenario
  @scenario
end

#search_query ⇒ Object (readonly)

Returns the value of attribute search_query.



40
41
42
 
# File 'lib/recombee_api_client/api/composite_recommendation.rb', line 40

def search_query
  @search_query
end

#segment_id ⇒ Object (readonly)

Returns the value of attribute segment_id.



40
41
42
 
# File 'lib/recombee_api_client/api/composite_recommendation.rb', line 40

def segment_id
  @segment_id
end

#source_settings ⇒ Object (readonly)

Returns the value of attribute source_settings.



40
41
42
 
# File 'lib/recombee_api_client/api/composite_recommendation.rb', line 40

def source_settings
  @source_settings
end

#timeout ⇒ Object

Returns the value of attribute timeout.



42
43
44
 
# File 'lib/recombee_api_client/api/composite_recommendation.rb', line 42

def timeout
  @timeout
end

#user_id ⇒ Object (readonly)

Returns the value of attribute user_id.



40
41
42
 
# File 'lib/recombee_api_client/api/composite_recommendation.rb', line 40

def user_id
  @user_id
end

Instance Method Details

#body_parameters ⇒ Object

Values of body parameters as a Hash



108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
 
# File 'lib/recombee_api_client/api/composite_recommendation.rb', line 108

def body_parameters
  p = {}
  p['scenario'] = @scenario
  p['count'] = @count
  p['itemId'] = @optional['itemId'] if @optional.include? 'itemId'
  p['userId'] = @optional['userId'] if @optional.include? 'userId'
  p['logic'] = @optional['logic'] if @optional.include? 'logic'
  p['segmentId'] = @optional['segmentId'] if @optional.include? 'segmentId'
  p['searchQuery'] = @optional['searchQuery'] if @optional.include? 'searchQuery'
  p['cascadeCreate'] = @optional['cascadeCreate'] if @optional.include? 'cascadeCreate'
  p['sourceSettings'] = @optional['sourceSettings'] if @optional.include? 'sourceSettings'
  p['resultSettings'] = @optional['resultSettings'] if @optional.include? 'resultSettings'
  p['expertSettings'] = @optional['expertSettings'] if @optional.include? 'expertSettings'

  p
end

#method ⇒ Object

HTTP method



103
104
105
 
# File 'lib/recombee_api_client/api/composite_recommendation.rb', line 103

def method
  :post
end

#path ⇒ Object

Relative path to the endpoint



132
133
134
 
# File 'lib/recombee_api_client/api/composite_recommendation.rb', line 132

def path
  '/{databaseId}/recomms/composite/'
end

#query_parameters ⇒ Object

Values of query parameters as a Hash. name of parameter => value of the parameter



127
128
129
 
# File 'lib/recombee_api_client/api/composite_recommendation.rb', line 127

def query_parameters
  {}
end