Scenarios¶

These endpoints are to create, read, update, delete runtime scenarios.

To use scenarios, please refer to Scenarios.

Get Scenario¶

GET scenarios/<str:reco_type>/<str:name>/¶

Note

Authorized Roles: root, manager, backend

Return scenario [see About Scenarios].

Response JSON Object

warnings (list-of-string) – Optional. List of warnings
reco_type (enum) – choices: [item_to_items, profile_to_items, session_to_items, profile_to_item_properties, profile_to_items_w_ctx_items, session_to_items_w_ctx_items, precomputed_item_to_items, precomputed_profile_to_items, session_to_item_properties, profiles_group_to_items, chat_to_items, item_properties_to_items, generic_input_to_items, llm_text_completion, llm_chat_completion] Type of recommendation a scenario applies to
name (string) – Scenario name
scenario (object) –
Inner fields
- scenario_type (enum) – choices: [case, ab_test, condition, alias] Type of scenario
- metadata (object) – Metadata of scenario
- case (object) –
  Reco Type:
  Inner fields
  
  amt (int) – [min: 0 max: 64] Maximum amount of items returned
  
  filters (list-of-object) – [max_length: 10] Filter on item properties [see Filtering on Item Property]
  
  Inner fields
  
  property_name (string) – Item-property name
  
  op (enum) – choices (case insensitive): [eq, lt, lte, gt, gte, in, empty, notempty, neq, notin, ftsearch] Filter Operator
  
  value (json-value) – Filter Value
  
  disable_preload (bool) – [Advanced feature - latency optimization] if True, the filter will be applied after the candidates preselection. Meant to be used for filters that only exclude a few items (e.g. some_id NOT IN [small_id_list]), and the values depends on the request (hence not cacheable, e.g. dynamic filter values).
  
  reranking (list-of-object) – Reranking business rules to apply [see Reranking on Item Property]
  
  Inner fields
  
  property_name (string) – Item-property name. Used for diversity reranking rules.
  
  op (enum) – choices: [diversity] Reranking op
  
  weight (float) – Weight to apply to diversity reranking rules; must be positive; defaults to 1; values between 0 and 1.5 are recommended
  
  options (object) – Op-specific options
  
  Inner fields
  
  activation_period (int) –
  
  max_activation_count (int) –
  
  default_malus (float) –
  
  exclude_rated_items (bool) – Exclude already rated items from response
  
  table (string) – Table name to read recommendations. This is typically set inside the scenario,it is rare that customers should ever set it themselves
  
  algorithms (string) – [Advanced Usage] Algorithms allowlist, formatted as a single string of |-separated values
  
  candidates_preselection (object) – [Advanced Usage] Candidates preselection
  
  Inner fields
  
  method (string) –
  
  params (object) –
  
  item_selector_config (object) –
  
  force_session_optimization (object) – [Advanced Usage] Options to force session optimization at runtime
  
  cache_control (object) – [Advanced Usage] Options to send cache control in the header of the request
  
  Inner fields
  
  max_age (int) –
  
  exclude_items_with_interaction_types (list-of-string) – [max_length: 50] Items that were interacted with one of those interaction types will be excluded from the recommendations
  
  exclude_props_of_items_with_interaction_types (list-of-object) – Items possessing the same properties as those interacted with through specified interaction types will be excluded from the recommendations.
  
  Inner fields
  
  property_name (string) – Item property to exclude
  
  interaction_types (list-of-string) – List of interaction types that will trigger the exclusion of properties from items interacted with these types.
  
  interactions_to_ratings_params (json-value) – [Advanced Usage] alpha feature dec. 2023 Parameters for live conversion from ratings to interactions
  
  case_sequence (object) – [Advanced usage] Case sequence
  
  Inner fields
  
  sequence (list-of-object) – [max_length: 2]
  
  Inner fields
  
  amt (int) – [min: 0 max: 64] Maximum amount of items returned
  
  filters (list-of-object) – Filter on item properties [see Filtering on Item Property]
  
  Inner fields
  
  property_name (string) – Item-property name
  
  op (enum) – choices (case insensitive): [eq, lt, lte, gt, gte, in, empty, notempty, neq, notin, ftsearch] Filter Operator
  
  value (json-value) – Filter Value
  
  disable_preload (bool) – [Advanced feature - latency optimization] if True, the filter will be applied after the candidates preselection. Meant to be used for filters that only exclude a few items (e.g. some_id NOT IN [small_id_list]), and the values depends on the request (hence not cacheable, e.g. dynamic filter values).
  
  reranking (list-of-object) – Reranking business rules to apply [see Reranking on Item Property]
  
  Inner fields
  
  property_name (string) – Item-property name. Used for diversity reranking rules.
  
  op (enum) – choices: [diversity] Reranking op
  
  weight (float) – Weight to apply to diversity reranking rules; must be positive; defaults to 1; values between 0 and 1.5 are recommended
  
  options (object) – Op-specific options
  
  Inner fields
  
  activation_period (int) –
  
  max_activation_count (int) –
  
  default_malus (float) –
  
  chat_params (object) – Chat custom params
  
  reco_type (enum) – choices: [item_to_items, profile_to_items, session_to_items, profile_to_items_w_ctx_items, session_to_items_w_ctx_items, precomputed_item_to_items, precomputed_profile_to_items, item_properties_to_items] Type of recommendation to apply
  
  scenario (string) – Name of scenario for the above reco_type to apply [see About Scenarios]
  
  model (string) – LLM model like openai/gpt-3.5-turbo or meta-llama/Llama-3-70b-chat-hf
  
  retrieval (object) – dynamically retrieve items be used when rendering prompt templates. Can be used for few-shot learning or/and RAG
  
  Inner fields
  
  amt (int) – [min: 0 max: 64] Maximum amount of items retrieved
  
  algorithms (string) – Retrieval algorithm
  
  property (string) – name of the property to use for retrieval
  
  filters (list-of-object) – Filter on item properties [see Filtering on Item Property]
  
  Inner fields
  
  property_name (string) – Item-property name
  
  op (enum) – choices (case insensitive): [eq, lt, lte, gt, gte, in, empty, notempty, neq, notin, ftsearch] Filter Operator
  
  value (json-value) – Filter Value
  
  reranking (list-of-object) – Reranking [see Reranking on Item Property]
  
  Inner fields
  
  property_name (string) – Item-property name. Used for diversity reranking rules.
  
  op (enum) – choices: [diversity] Reranking op
  
  weight (float) – Weight to apply to diversity reranking rules; must be positive; defaults to 1; values between 0 and 1.5 are recommended
  
  options (object) – Op-specific options
  
  Inner fields
  
  activation_period (int) –
  
  max_activation_count (int) –
  
  default_malus (float) –
  
  history_injection (object) – [WORK-IN-PROGRESS] inject retrieved items as history messages
  
  Inner fields
  
  json_template (string) – [DEPRECATED] Jinja template rendering to JSON
  
  python_literal_template (string) – [WORK-IN-PROGRESS] Jinja template rendering to python literal
  
  candidates_preselection (object) – [Advanced Usage] Candidates preselection
  
  Inner fields
  
  method (string) –
  
  params (object) –
  
  item_selector_config (object) –
  
  properties_returned (list-of-string) – List of items properties to return for items retrieved
  
  system_prompt (string) – system prompt template in Jinja
  
  max_tokens (int) – max_tokens
  
  temperature (float) – temperature
- alias (object) –
  Inner fields
  
  scenario_name (string) – Name of an existing scenario
- condition (object) –
  Inner fields
  
  condition_type (enum) – choices (case insensitive): [user_function, item_property, runtime_param] Type of condition
  
  if (object) – Condition to be tested at runtime. Sub-fields depend on condition_type, see example below
  
  Inner fields
  
  function_name (enum) – choices (case insensitive): [n_ratings, n_interactions] function name, for user_condition
  
  property_name (string) – Item property name, for item_property
  
  param_name (string) – Runtime param name, for condition on runtime_param
  
  op (enum) – choices (case insensitive): [lt, eq, gt, gte, lte, in, notempty] OP
  
  value (json-value) – Value to apply with the operator
  
  then (string) – Scenario to evaluate if condition is true
  
  else (string) – Scenario to evaluate if condition is false
- ab_test (object) –
  Inner fields
  
  id (string) – A/B test unique ID
  
  scenario_a (string) – Name of scenario for variant A
  
  scenario_b (string) – Name of scenario for variant B

EXAMPLE RESPONSE FOR CASE SCENARIO¶

{
    "name": "my_scenar101",
    "reco_type": "profile_to_items",
    "scenario": {
        "scenario_type": "case",
        "case": {
            "amt": 6,
            "filters": [{"property_name": "year", "op": "eq", "value": 1988}],
            "reranking": [{"property_name": "genres", "op": "diversity", "weight": 0.25}],
            "exclude_rated_items": false,
            "algorithms": "algo105|algo106",
             "candidates_preselection": {
                "method": "knn",
                "params": {"algorithms": ["algo103"]}
        }
    }
}

EXAMPLE RESPONSE FOR AB-TEST SCENARIO¶

{
    "name": "my_scenar_ab",
    "reco_type": "profile_to_items",
    "scenario": {
        "scenario_type": "ab_test",
        "ab_test": {
            "id": "my_ab_test",
            "scenario_a": "scenar1",
            "scenario_b": "scenar2"
        }
    }
}

EXAMPLE RESPONSE FOR ALIAS SCENARIO¶

{
    "name": "my_scenar_alias",
    "reco_type": "profile_to_items",
    "scenario": {
        "scenario_type": "alias",
        "alias": {
            "scenario_name": "my_favorite_scenario"
        }
    }
}

Errors:

NotFoundError with error name SCENARIO_NOT_FOUND if a scenario is missing

Create or Replace Scenario¶

PUT scenarios/<str:reco_type>/<str:name>/¶

Note

Authorized Roles: root, manager, backend

Create or replace a scenario [see About Scenarios]. ab_test scenarios cannot be updated, and scenario flows cannot create cyclic graphs.

Only one of case/condition/ab_test/alias can be non-null, according to scenario_type

Request JSON Object

scenario_type (enum) – choices: [case, ab_test, condition, alias] Type of scenario
metadata (object) – Optional. Metadata of scenario
case (object) –
Optional.
Reco Type:
Inner fields
- amt (int) – [min: 0 max: 64] Maximum amount of items returned
- filters (list-of-object) – [max_length: 10] Filter on item properties [see Filtering on Item Property]
  For reco types: item_to_items, profile_to_items, session_to_items, profile_to_item_properties, profile_to_items_w_ctx_items, session_to_items_w_ctx_items, session_to_item_properties, profiles_group_to_items, item_properties_to_items
  Inner fields
  
  property_name (string) – Item-property name
  
  op (enum) – choices (case insensitive): [eq, lt, lte, gt, gte, in, empty, notempty, neq, notin, ftsearch] Filter Operator
  
  value (json-value) – Filter Value
  
  disable_preload (bool) – [Advanced feature - latency optimization] if True, the filter will be applied after the candidates preselection. Meant to be used for filters that only exclude a few items (e.g. some_id NOT IN [small_id_list]), and the values depends on the request (hence not cacheable, e.g. dynamic filter values).
- reranking (list-of-object) – Reranking business rules to apply [see Reranking on Item Property]
  For reco types: item_to_items, profile_to_items, session_to_items, profile_to_items_w_ctx_items, session_to_items_w_ctx_items, profiles_group_to_items, item_properties_to_items
  Inner fields
  
  property_name (string) – Item-property name. Used for diversity reranking rules.
  
  op (enum) – choices: [diversity] Reranking op
  
  weight (float) – Weight to apply to diversity reranking rules; must be positive; defaults to 1; values between 0 and 1.5 are recommended
  
  options (object) – Op-specific options
  
  Inner fields
  
  activation_period (int) –
  
  max_activation_count (int) –
  
  default_malus (float) –
- exclude_rated_items (bool) – Exclude already rated items from response
- table (string) – Table name to read recommendations. This is typically set inside the scenario,it is rare that customers should ever set it themselves
- algorithms (string) – [Advanced Usage] Algorithms allowlist, formatted as a single string of |-separated values
- candidates_preselection (object) – [Advanced Usage] Candidates preselection
  For reco types: item_to_items, profile_to_items, session_to_items, profile_to_item_properties, profile_to_items_w_ctx_items, session_to_items_w_ctx_items, session_to_item_properties, profiles_group_to_items, item_properties_to_items
  Inner fields
  
  method (string) –
  
  params (object) –
  
  item_selector_config (object) –
- force_session_optimization (object) – [Advanced Usage] Options to force session optimization at runtime
- cache_control (object) – [Advanced Usage] Options to send cache control in the header of the request
  For reco types: precomputed_profile_to_items, item_to_items, precomputed_item_to_items
  Inner fields
  
  max_age (int) –
- exclude_items_with_interaction_types (list-of-string) – [max_length: 50] Items that were interacted with one of those interaction types will be excluded from the recommendations
- exclude_props_of_items_with_interaction_types (list-of-object) – Items possessing the same properties as those interacted with through specified interaction types will be excluded from the recommendations.
  For reco types: profile_to_items, session_to_items, profile_to_items_w_ctx_items, session_to_items_w_ctx_items
  Inner fields
  
  property_name (string) – Item property to exclude
  
  interaction_types (list-of-string) – List of interaction types that will trigger the exclusion of properties from items interacted with these types.
- interactions_to_ratings_params (json-value) – [Advanced Usage] alpha feature dec. 2023 Parameters for live conversion from ratings to interactions
- case_sequence (object) – [Advanced usage] Case sequence
  For reco types: item_to_items, profile_to_items, session_to_items, profile_to_item_properties, profile_to_items_w_ctx_items, session_to_items_w_ctx_items, session_to_item_properties
  Inner fields
  
  sequence (list-of-object) – [max_length: 2]
  
  Inner fields
  
  amt (int) – [min: 0 max: 64] Maximum amount of items returned
  
  filters (list-of-object) – Filter on item properties [see Filtering on Item Property]
  
  Inner fields
  
  property_name (string) – Item-property name
  
  op (enum) – choices (case insensitive): [eq, lt, lte, gt, gte, in, empty, notempty, neq, notin, ftsearch] Filter Operator
  
  value (json-value) – Filter Value
  
  disable_preload (bool) – [Advanced feature - latency optimization] if True, the filter will be applied after the candidates preselection. Meant to be used for filters that only exclude a few items (e.g. some_id NOT IN [small_id_list]), and the values depends on the request (hence not cacheable, e.g. dynamic filter values).
  
  reranking (list-of-object) – Reranking business rules to apply [see Reranking on Item Property]
  
  Inner fields
  
  property_name (string) – Item-property name. Used for diversity reranking rules.
  
  op (enum) – choices: [diversity] Reranking op
  
  weight (float) – Weight to apply to diversity reranking rules; must be positive; defaults to 1; values between 0 and 1.5 are recommended
  
  options (object) – Op-specific options
  
  Inner fields
  
  activation_period (int) –
  
  max_activation_count (int) –
  
  default_malus (float) –
- chat_params (object) – Chat custom params
- reco_type (enum) – choices: [item_to_items, profile_to_items, session_to_items, profile_to_items_w_ctx_items, session_to_items_w_ctx_items, precomputed_item_to_items, precomputed_profile_to_items, item_properties_to_items] Type of recommendation to apply
- scenario (string) – Name of scenario for the above reco_type to apply [see About Scenarios]
- model (string) – LLM model like openai/gpt-3.5-turbo or meta-llama/Llama-3-70b-chat-hf
- retrieval (object) – dynamically retrieve items be used when rendering prompt templates. Can be used for few-shot learning or/and RAG
  For reco types: llm_text_completion, llm_chat_completion
  Inner fields
  
  amt (int) – [min: 0 max: 64] Maximum amount of items retrieved
  
  algorithms (string) – Retrieval algorithm
  
  property (string) – name of the property to use for retrieval
  
  filters (list-of-object) – Filter on item properties [see Filtering on Item Property]
  
  Inner fields
  
  property_name (string) – Item-property name
  
  op (enum) – choices (case insensitive): [eq, lt, lte, gt, gte, in, empty, notempty, neq, notin, ftsearch] Filter Operator
  
  value (json-value) – Filter Value
  
  reranking (list-of-object) – Reranking [see Reranking on Item Property]
  
  Inner fields
  
  property_name (string) – Item-property name. Used for diversity reranking rules.
  
  op (enum) – choices: [diversity] Reranking op
  
  weight (float) – Weight to apply to diversity reranking rules; must be positive; defaults to 1; values between 0 and 1.5 are recommended
  
  options (object) – Op-specific options
  
  Inner fields
  
  activation_period (int) –
  
  max_activation_count (int) –
  
  default_malus (float) –
  
  history_injection (object) – [WORK-IN-PROGRESS] inject retrieved items as history messages
  
  Inner fields
  
  json_template (string) – [DEPRECATED] Jinja template rendering to JSON
  
  python_literal_template (string) – [WORK-IN-PROGRESS] Jinja template rendering to python literal
  
  candidates_preselection (object) – [Advanced Usage] Candidates preselection
  
  Inner fields
  
  method (string) –
  
  params (object) –
  
  item_selector_config (object) –
  
  properties_returned (list-of-string) – List of items properties to return for items retrieved
- system_prompt (string) – system prompt template in Jinja
- max_tokens (int) – max_tokens
- temperature (float) – temperature
alias (object) –
Optional.
Inner fields
- scenario_name (string) – Name of an existing scenario
condition (object) –
Optional.
Inner fields
- condition_type (enum) – choices (case insensitive): [user_function, item_property, runtime_param] Type of condition
- if (object) – Condition to be tested at runtime. Sub-fields depend on condition_type, see example below
  Inner fields
  
  function_name (enum) – choices (case insensitive): [n_ratings, n_interactions] function name, for user_condition
  
  property_name (string) – Item property name, for item_property
  
  param_name (string) – Runtime param name, for condition on runtime_param
  
  op (enum) – choices (case insensitive): [lt, eq, gt, gte, lte, in, notempty] OP
  
  value (json-value) – Value to apply with the operator
- then (string) – Scenario to evaluate if condition is true
- else (string) – Scenario to evaluate if condition is false
ab_test (object) –
Optional.
Inner fields
- id (string) – A/B test unique ID
- scenario_a (string) – Name of scenario for variant A
- scenario_b (string) – Name of scenario for variant B

EXAMPLE QUERY BODY FOR CASE SCENARIO¶

{
    "scenario_type": "case",
    "case": {
        "amt": 10,
        "filters": [
            {"property_name": "tags", "op": "eq", "value": "pi"},
            {"property_name": "price", "op": "gt", "value": 3.14}
        ],
        "reranking": [
            {"property_name": "director", "op": "diversity", "weight": 0.8}
        ],
        "exclude_rated_items": false,
        "exclude_items_with_interaction_types": [
            "purchase",
            "add_to_cart"
        ],
        "algorithms": "algo101|algo102",
        "candidates_preselection": {
                "method": "knn",
                "params": {"algorithms": ["algo103"]}
        }
    }
}

EXAMPLE QUERY BODY FOR CASE SCENARIO WITH NESTED FILTER VALUE¶

{
    "scenario_type": "case",
    "case": {
        "filters": [
            {
                "property_name": "category",
                "op": "eq",
                "value": {
                    "type": "user_property",
                    "value": "selected_category"
                }
            }
        ]
    }
}

EXAMPLE QUERY BODY FOR CONDITION SCENARIO FOR USER FUNCTION¶

{
    "scenario_type": "condition",
    "condition": {
        "condition_type": "user_function",
        "if": {"function_name": "n_ratings", "op": "gte", "value": 21},
        "then": "scenario1",
        "else": "scenario2"
    }
}

EXAMPLE QUERY BODY FOR CONDITION SCENARIO FOR ITEM PROPERTY¶

{
    "scenario_type": "condition",
    "condition": {
        "condition_type": "item_property",
        "if": {"property_name": "prop_int", "op": "lt", "value": 21},
        "then": "scenario1",
        "else": "scenario2"
    }
}

CREATE A CONDITION SCENARIO BASED ON RUNTIME PARAMS¶

{
    "scenario_type": "condition",
    "condition": {
        "condition_type": "runtime_param",
        "if": {"param_name": "user_id", "op": "notempty"},
        "then": "scenario1",
        "else": "scenario2"
    }
}

EXAMPLE QUERY BODY FOR AB-TEST SCENARIO¶

{
    "scenario_type": "ab_test",
    "ab_test": {
        "id": "ab-test-id12345",
        "scenario_a": "scenar1",
        "scenario_b": "scenar2"
    }
}

EXAMPLE QUERY BODY FOR ALIAS SCENARIO¶

{
    "scenario_type": "alias",
    "alias": {
        "scenario_name": "my_favorite_scenario"
    }
}

Response JSON Object

warnings (list-of-string) – Optional. List of warnings

EXAMPLE RESPONSE¶

{
    "warnings": ["Missing property value `test`"]
}

Errors:

WrongData with error name WRONG_DATA_TYPE if any business rule is invalid
WrongData if the scenario exists and is of type “ab_test”
WrongData if the scenario would create a loop

Delete A Scenario¶

DELETE scenarios/<str:reco_type>/<str:name>/¶

Note

Authorized Roles: root, manager, backend

Delete single scenario [see About Scenarios].

Errors:

NotFoundError with error name SCENARIO_NOT_FOUND if named scenario is missing

Get All Scenarios¶

GET scenarios/¶

Note

Authorized Roles: root, manager, backend

Return all scenarios [see About Scenarios]. The result is paginated and it allows to use filters by reco_type, scenario_type or metadata content.

The response is paginated, you can control the response amount and offset using the query parameters amt and cursor.

Query Parameters

cursor (string) – Optional. Pagination cursor, typically from the next_cursor value from the previous response
amt (int) – Optional. [min: 1 max: 512] Amount of scenarios to return
reco_type (enum) – Optional. choices: [item_to_items, profile_to_items, session_to_items, profile_to_item_properties, profile_to_items_w_ctx_items, session_to_items_w_ctx_items, precomputed_item_to_items, precomputed_profile_to_items, session_to_item_properties, profiles_group_to_items, chat_to_items, item_properties_to_items, generic_input_to_items, llm_text_completion, llm_chat_completion] Filter by reco type
scenario_type (enum) – Optional. choices: [case, ab_test, condition, alias] Filter by type of scenario
metadata_filters (list-of-object) –
Optional. Filter by metadata content. The result is the conjunction of the filter list, meaning the filters are concatenated with AND.
In URL-compatible format, use . to denote nested levels within the JSON object in keys part, and use \. to escape a . in keys, and \ to escape \. [see URL-Compatible Format]
Inner fields
- keys (list-of-string) – Keys of the metadata content. Each value in the list represents a nested level within the JSON object
- op (enum) – choices (case insensitive): [eq, lt, gt, lte, gte] Filter Operator
- value (json-value) – Filter Value

EXAMPLE QUERY PARAMS¶

  ?cursor=Q21vU1pHb1FjSEp...&amt=10

or with some filters

EXAMPLE QUERY PARAMS¶

  ?amt=10&reco_type=profile_to_items&metadata_filters=configs.level:eq:5&metadata_filters=mode:eq:read

Response JSON Object

warnings (list-of-string) – Optional. List of warnings
has_next (bool) – Indicates whether or not there are more pages to request
next_cursor (string) – Pagination cursor to use in next request to get more scenarios
scenarios (list-of-object) –
Inner fields
- warnings (list-of-string) – List of warnings
- reco_type (enum) – choices: [item_to_items, profile_to_items, session_to_items, profile_to_item_properties, profile_to_items_w_ctx_items, session_to_items_w_ctx_items, precomputed_item_to_items, precomputed_profile_to_items, session_to_item_properties, profiles_group_to_items, chat_to_items, item_properties_to_items, generic_input_to_items, llm_text_completion, llm_chat_completion] Type of recommendation a scenario applies to
- name (string) – Scenario name
- scenario (object) –
  Inner fields
  
  scenario_type (enum) – choices: [case, ab_test, condition, alias] Type of scenario
  
  metadata (object) – Metadata of scenario
  
  case (object) –
  Reco Type:
  
  Inner fields
  
  amt (int) – [min: 0 max: 64] Maximum amount of items returned
  
  filters (list-of-object) – [max_length: 10] Filter on item properties [see Filtering on Item Property]
  
  Inner fields
  
  property_name (string) – Item-property name
  
  op (enum) – choices (case insensitive): [eq, lt, lte, gt, gte, in, empty, notempty, neq, notin, ftsearch] Filter Operator
  
  value (json-value) – Filter Value
  
  disable_preload (bool) – [Advanced feature - latency optimization] if True, the filter will be applied after the candidates preselection. Meant to be used for filters that only exclude a few items (e.g. some_id NOT IN [small_id_list]), and the values depends on the request (hence not cacheable, e.g. dynamic filter values).
  
  reranking (list-of-object) – Reranking business rules to apply [see Reranking on Item Property]
  
  Inner fields
  
  property_name (string) – Item-property name. Used for diversity reranking rules.
  
  op (enum) – choices: [diversity] Reranking op
  
  weight (float) – Weight to apply to diversity reranking rules; must be positive; defaults to 1; values between 0 and 1.5 are recommended
  
  options (object) – Op-specific options
  
  Inner fields
  
  activation_period (int) –
  
  max_activation_count (int) –
  
  default_malus (float) –
  
  exclude_rated_items (bool) – Exclude already rated items from response
  
  table (string) – Table name to read recommendations. This is typically set inside the scenario,it is rare that customers should ever set it themselves
  
  algorithms (string) – [Advanced Usage] Algorithms allowlist, formatted as a single string of |-separated values
  
  candidates_preselection (object) – [Advanced Usage] Candidates preselection
  
  Inner fields
  
  method (string) –
  
  params (object) –
  
  item_selector_config (object) –
  
  force_session_optimization (object) – [Advanced Usage] Options to force session optimization at runtime
  
  cache_control (object) – [Advanced Usage] Options to send cache control in the header of the request
  
  Inner fields
  
  max_age (int) –
  
  exclude_items_with_interaction_types (list-of-string) – [max_length: 50] Items that were interacted with one of those interaction types will be excluded from the recommendations
  
  exclude_props_of_items_with_interaction_types (list-of-object) – Items possessing the same properties as those interacted with through specified interaction types will be excluded from the recommendations.
  
  Inner fields
  
  property_name (string) – Item property to exclude
  
  interaction_types (list-of-string) – List of interaction types that will trigger the exclusion of properties from items interacted with these types.
  
  interactions_to_ratings_params (json-value) – [Advanced Usage] alpha feature dec. 2023 Parameters for live conversion from ratings to interactions
  
  case_sequence (object) – [Advanced usage] Case sequence
  
  Inner fields
  
  sequence (list-of-object) – [max_length: 2]
  
  Inner fields
  
  amt (int) – [min: 0 max: 64] Maximum amount of items returned
  
  filters (list-of-object) – Filter on item properties [see Filtering on Item Property]
  
  Inner fields
  
  property_name (string) – Item-property name
  
  op (enum) – choices (case insensitive): [eq, lt, lte, gt, gte, in, empty, notempty, neq, notin, ftsearch] Filter Operator
  
  value (json-value) – Filter Value
  
  disable_preload (bool) – [Advanced feature - latency optimization] if True, the filter will be applied after the candidates preselection. Meant to be used for filters that only exclude a few items (e.g. some_id NOT IN [small_id_list]), and the values depends on the request (hence not cacheable, e.g. dynamic filter values).
  
  reranking (list-of-object) – Reranking business rules to apply [see Reranking on Item Property]
  
  Inner fields
  
  property_name (string) – Item-property name. Used for diversity reranking rules.
  
  op (enum) – choices: [diversity] Reranking op
  
  weight (float) – Weight to apply to diversity reranking rules; must be positive; defaults to 1; values between 0 and 1.5 are recommended
  
  options (object) – Op-specific options
  
  Inner fields
  
  activation_period (int) –
  
  max_activation_count (int) –
  
  default_malus (float) –
  
  chat_params (object) – Chat custom params
  
  reco_type (enum) – choices: [item_to_items, profile_to_items, session_to_items, profile_to_items_w_ctx_items, session_to_items_w_ctx_items, precomputed_item_to_items, precomputed_profile_to_items, item_properties_to_items] Type of recommendation to apply
  
  scenario (string) – Name of scenario for the above reco_type to apply [see About Scenarios]
  
  model (string) – LLM model like openai/gpt-3.5-turbo or meta-llama/Llama-3-70b-chat-hf
  
  retrieval (object) – dynamically retrieve items be used when rendering prompt templates. Can be used for few-shot learning or/and RAG
  
  Inner fields
  
  amt (int) – [min: 0 max: 64] Maximum amount of items retrieved
  
  algorithms (string) – Retrieval algorithm
  
  property (string) – name of the property to use for retrieval
  
  filters (list-of-object) – Filter on item properties [see Filtering on Item Property]
  
  Inner fields
  
  property_name (string) – Item-property name
  
  op (enum) – choices (case insensitive): [eq, lt, lte, gt, gte, in, empty, notempty, neq, notin, ftsearch] Filter Operator
  
  value (json-value) – Filter Value
  
  reranking (list-of-object) – Reranking [see Reranking on Item Property]
  
  Inner fields
  
  property_name (string) – Item-property name. Used for diversity reranking rules.
  
  op (enum) – choices: [diversity] Reranking op
  
  weight (float) – Weight to apply to diversity reranking rules; must be positive; defaults to 1; values between 0 and 1.5 are recommended
  
  options (object) – Op-specific options
  
  Inner fields
  
  activation_period (int) –
  
  max_activation_count (int) –
  
  default_malus (float) –
  
  history_injection (object) – [WORK-IN-PROGRESS] inject retrieved items as history messages
  
  Inner fields
  
  json_template (string) – [DEPRECATED] Jinja template rendering to JSON
  
  python_literal_template (string) – [WORK-IN-PROGRESS] Jinja template rendering to python literal
  
  candidates_preselection (object) – [Advanced Usage] Candidates preselection
  
  Inner fields
  
  method (string) –
  
  params (object) –
  
  item_selector_config (object) –
  
  properties_returned (list-of-string) – List of items properties to return for items retrieved
  
  system_prompt (string) – system prompt template in Jinja
  
  max_tokens (int) – max_tokens
  
  temperature (float) – temperature
  
  alias (object) –
  
  Inner fields
  
  scenario_name (string) – Name of an existing scenario
  
  condition (object) –
  
  Inner fields
  
  condition_type (enum) – choices (case insensitive): [user_function, item_property, runtime_param] Type of condition
  
  if (object) – Condition to be tested at runtime. Sub-fields depend on condition_type, see example below
  
  Inner fields
  
  function_name (enum) – choices (case insensitive): [n_ratings, n_interactions] function name, for user_condition
  
  property_name (string) – Item property name, for item_property
  
  param_name (string) – Runtime param name, for condition on runtime_param
  
  op (enum) – choices (case insensitive): [lt, eq, gt, gte, lte, in, notempty] OP
  
  value (json-value) – Value to apply with the operator
  
  then (string) – Scenario to evaluate if condition is true
  
  else (string) – Scenario to evaluate if condition is false
  
  ab_test (object) –
  
  Inner fields
  
  id (string) – A/B test unique ID
  
  scenario_a (string) – Name of scenario for variant A
  
  scenario_b (string) – Name of scenario for variant B

EXAMPLE RESPONSE¶

{
    "has_next": true,
    "next_cursor": "Q21vU1pHb1FjSEp..",
    "scenarios": [
        {
            "name": "my_scenar_case_1",
            "reco_type": "profile_to_items",
            "scenario": {
                "scenario_type": "case",
                "case": {
                    "amt": 13,
                    "filters": [{"property_name": "year", "op": "eq", "value": 1988}],
                    "reranking": [{"property_name": "genres", "op": "diversity", "weight": 0.25}],
                    "exclude_rated_items": false,
                    "algorithms": "algo105|algo106",
                    "candidates_preselection": {
                        "method": "knn",
                        "params": {"algorithms": ["algo103"]}
                    }
                }
            }
        }, {
            "name": "my_scenar_ab",
            "reco_type": "profile_to_items",
            "scenario": {
                "scenario_type": "ab_test",
                "ab_test": {
                    "id": "my_ab_test",
                    "scenario_a": "my_scenar_case_1",
                    "scenario_b": "my_scenar_case_2"
                }
            }
        }, {
            "name": "my_condition_scenar",
            "reco_type": "profile_to_items",
            "scenario": {
                "scenario_type": "condition",
                "condition": {
                    "condition_type": "user_function",
                    "if": {"function_name": "n_ratings", "op": "gte", "value": 5},
                    "then": "my_scenar_case_1",
                    "else": "my_scenar_ab"
                }
            },
        }, {
            "name": "my_scenar_alias",
            "reco_type": "profile_to_items",
            "scenario": {
                "scenario_type": "alias",
                "alias": {
                    "scenario_name": "my_condition_scenar"
                }
            }
        }
    ]
}

Get Default Scenario¶

GET scenarios-default/<str:reco_type>/¶

Note

Authorized Roles: root, manager, backend

Get default scenario [see Automatic Scenarios].

Response JSON Object

warnings (list-of-string) – Optional. List of warnings
name (string) – Scenario name

EXAMPLE RESPONSE¶

{
    "name": "scenario_109"
}

NotFoundError with error name SCENARIO_NOT_FOUND if there is no default scenario for this reco_type

Set Default Scenario¶

PATCH scenarios-default/<str:reco_type>/¶

Note

Authorized Roles: root, manager, backend

Set scenario as default [see Automatic Scenarios].

Request JSON Object

name (string) – Scenario name

EXAMPLE QUERY BODY¶

{
    "name": "scenario_107"
}

Errors:

NotFoundError with error name SCENARIO_NOT_FOUND if named scenario is missing

Unset Default Scenario¶

DELETE scenarios-default/<str:reco_type>/¶: Note

Authorized Roles: root, manager, backend

Unset a scenario from being by default [see Automatic Scenarios].