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] 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) –
  
  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: [eq, lt, lte, gt, gte, in, 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: [eq, lt, lte, gt, gte, in, 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
- 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] 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
    - op (enum) – choices (case insensitive): [gte, lt, eq, in, notempty, lte, gt] 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.

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: [eq, lt, lte, gt, gte, in, 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: [eq, lt, lte, gt, gte, in, 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
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] 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
  - op (enum) – choices (case insensitive): [gte, lt, eq, in, notempty, lte, gt] 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"
    }
}

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].

Response JSON Object

warnings (list-of-string) – Optional. List of warnings
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] 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) –
    
    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: [eq, lt, lte, gt, gte, in, 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: [eq, lt, lte, gt, gte, in, 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
  - 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] 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
      - op (enum) – choices (case insensitive): [gte, lt, eq, in, notempty, lte, gt] 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¶

{
    "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].