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: -- Select -- 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
    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) –

        • filters (list-of-object) – [internal]

          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

        • rank_divider (float) – [internal]

        • similarity (object) – [internal]

        • malus (object) – [internal]

        • rank_scores (object) – [internal]

        • randomness (object) – [internal]

    • 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) –

    • advanced_exclude_rated_items (object) – [internal] alpha feature, not released yet as of November 2023.

      Inner fields

      • enabled (bool) –

      • exclude_above_value (float) –

      • exclude_below_value (float) –

      • ensure_exclude_remaining_ratings (bool) –

    • 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) –

            • filters (list-of-object) – [internal]

              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

            • rank_divider (float) – [internal]

            • similarity (object) – [internal]

            • malus (object) – [internal]

            • rank_scores (object) – [internal]

            • randomness (object) – [internal]

    • 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) –

          • filters (list-of-object) – [internal]

            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

          • rank_divider (float) – [internal]

          • similarity (object) – [internal]

          • malus (object) – [internal]

          • rank_scores (object) – [internal]

          • randomness (object) – [internal]

      • 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): [gt, lt, eq, in, gte, lte, 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: -- Select -- 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
  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) –

      • filters (list-of-object) – [internal]

        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

      • rank_divider (float) – [internal]

      • similarity (object) – [internal]

      • malus (object) – [internal]

      • rank_scores (object) – [internal]

      • randomness (object) – [internal]

  • 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) –

  • advanced_exclude_rated_items (object) – [internal] alpha feature, not released yet as of November 2023.

    Inner fields

    • enabled (bool) –

    • exclude_above_value (float) –

    • exclude_below_value (float) –

    • ensure_exclude_remaining_ratings (bool) –

  • 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) –

          • filters (list-of-object) – [internal]

            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

          • rank_divider (float) – [internal]

          • similarity (object) – [internal]

          • malus (object) – [internal]

          • rank_scores (object) – [internal]

          • randomness (object) – [internal]

  • 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) –

        • filters (list-of-object) – [internal]

          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

        • rank_divider (float) – [internal]

        • similarity (object) – [internal]

        • malus (object) – [internal]

        • rank_scores (object) – [internal]

        • randomness (object) – [internal]

    • 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): [gt, lt, eq, in, gte, lte, 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: -- Select -- 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
      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) –

          • filters (list-of-object) – [internal]

            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

          • rank_divider (float) – [internal]

          • similarity (object) – [internal]

          • malus (object) – [internal]

          • rank_scores (object) – [internal]

          • randomness (object) – [internal]

      • 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) –

      • advanced_exclude_rated_items (object) – [internal] alpha feature, not released yet as of November 2023.

        Inner fields

        • enabled (bool) –

        • exclude_above_value (float) –

        • exclude_below_value (float) –

        • ensure_exclude_remaining_ratings (bool) –

      • 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) –

              • filters (list-of-object) – [internal]

                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

              • rank_divider (float) – [internal]

              • similarity (object) – [internal]

              • malus (object) – [internal]

              • rank_scores (object) – [internal]

              • randomness (object) – [internal]

      • 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) –

            • filters (list-of-object) – [internal]

              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

            • rank_divider (float) – [internal]

            • similarity (object) – [internal]

            • malus (object) – [internal]

            • rank_scores (object) – [internal]

            • randomness (object) – [internal]

        • 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): [gt, lt, eq, in, gte, lte, 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].

[Internal] Preview Scenarios Parameters

POST scenarios/preview/

Note

Authorized Roles: root, manager, backend, frontend

This endpoint allows to preview scenario parameters before creating or updating them. Upon invocation, it returns recommendations based on the provided scenarios parameters and the resulting case parameters after evaluating the scenario.

This endpoint leverages the generic recommendation and generic scenarios feature to evaluate and get recommendations. See POST recommendation/generic/items/.

The parameter preview_scenarios_params allows to define all scenarios (with their respective parameters) that could be used in real-time during the request. Existing scenarios with the same names will be ignored and will use the defined in preview_scenarios_params.

The scenario parameter has to be a generic, and it can be the name of either an existing scenario (to test modifying an existing generic evaluation flow) or one of preview_scenarios_params.

Also, this endpoint is useful to verify the behaviour of a scenario or scenario flows.

Use case 1: check a scenario parameters before creating or updating.

Steps:

1. Define in preview_scenarios_params, the scenario parameters desired to check.

2. Also, define in preview_scenarios_params a generic scenario with the reco type pointing to the scenario parameters defined in step 1.

3. Call this endpoint by passing the generic scenario name in the scenario field, the list of scenarios with parameters defined in the preview_scenarios_params field, and any other runtime fields needed to get the recommendations.

If the scenario exists, all parameters will be overwritten with those defined in preview_scenarios_params.

Use case 2: check scenario parameters within an already existing scenario flow. Suppose the following scenario flow has already been created (alias_1 -> ab_test_1 -> [scenario_a, scenario_b]), and it is only necessary to test the changes for scenario_b.

Steps:

1. Define in preview_scenarios_params, the new scenario parameters version for scenario_b.

2. Call this endpoint by passing the first generic scenario name of the flow in the scenario field, the list of scenarios with parameters defined in the preview_scenarios_params field, and any other runtime fields needed to get the recommendations.

Limitations:

• It is important to note that scenarios of type ab_test are immutable and cannot be updated once created. Due to this restriction, the endpoint does not implement duplicate name checking for scenarios.

Request JSON Object

• preview_scenarios_params (list-of-object) –

  Preview scenarios parameters

  Inner fields

  • 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: -- Select -- 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
      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) –

          • filters (list-of-object) – [internal]

            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

          • rank_divider (float) – [internal]

          • similarity (object) – [internal]

          • malus (object) – [internal]

          • rank_scores (object) – [internal]

          • randomness (object) – [internal]

      • 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) –

      • advanced_exclude_rated_items (object) – [internal] alpha feature, not released yet as of November 2023.

        Inner fields

        • enabled (bool) –

        • exclude_above_value (float) –

        • exclude_below_value (float) –

        • ensure_exclude_remaining_ratings (bool) –

      • 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) –

              • filters (list-of-object) – [internal]

                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

              • rank_divider (float) – [internal]

              • similarity (object) – [internal]

              • malus (object) – [internal]

              • rank_scores (object) – [internal]

              • randomness (object) – [internal]

      • 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) –

            • filters (list-of-object) – [internal]

              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

            • rank_divider (float) – [internal]

            • similarity (object) – [internal]

            • malus (object) – [internal]

            • rank_scores (object) – [internal]

            • randomness (object) – [internal]

        • 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): [gt, lt, eq, in, gte, lte, 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

• scenario (string) – Name of generic scenario to apply. Can be either a generic scenario defined in preview_scenarios_params, or an existing generic scenario from the database

• user_id (ID) – Optional. [see Flexible Identifiers], [max_length: 64] User ID. Used to personalize recommendations when the generic input resolves to: profile_to_items, profile_to_items_w_ctx_items, precomputed_profile_to_items. Otherwise used in the context of an A/B test scenario to select the group A or B and keep track of the respective group in analytics.

• session_id (ID) – Optional. [see Flexible Identifiers], [max_length: 64] Anonymous Session ID. Used to personalize recommendations when the generic input resolves to: session_to_items, session_to_items_w_ctx_items. Otherwise used in the context of an A/B test scenario to select the group A or B and keep track of the respective group in analytics, when a user_id is not available.

• item_id (ID) – Optional. [see Flexible Identifiers], [max_length: 64] Item ID. Used to get similar items when the generic input resolves to: item_to_items, precomputed_item_to_items

• skip_default_scenario (bool) – Optional. Specify whether default scenario should by applied or skipped [see Default Scenario]

• cursor (string) – Optional. Pagination cursor, typically from the next_cursor value of the previous response

• interactions (object-array) –

  Optional. Item interactions array. Alternatively to personalizing the recommendations using a session_id, you can also provide item interactions directly in the body of the request. This is typically useful when the item interactions are stored in the local storage of the frontend instead of being created as they occur. When both interactions and session_id are used, the item interactions are combined for personalization. Mutually exclusive with providing ratings.

  Inner fields

  • item_id (ID) – [see Flexible Identifiers], [max_length: 64] Item ID

  • interaction_type (O) – Interaction Type

  • timestamp (float64) – [min: -150000000000.0 (year -2786) max: 3500000000.0 (year 2080)] Interaction timestamp (default: now)

• ratings (object-array) –

  Optional. Item ratings array. Rarely used. Similar to interactions but using ratings numbers instead of interactions types. Mutually exclusive with providing interactions or session_id.

  Inner fields

  • item_id (ID) – [see Flexible Identifiers], [max_length: 64] Item ID

  • rating (float32) – [min: 1 max: 10] Rating value

• user_properties (object) – Optional. User properties. Useful to solve the cold-start problem

• context_items (object-array) –

  Optional. Context items array. Can be used to provide additional context like items in a cart.Contact our support for advanced usage.

  Inner fields

  • item_id (ID) – [see Flexible Identifiers], [max_length: 64] Item ID

• item_properties (object) – Optional. Properties to search similar items.

• amt (int) – Optional. [min: 0 max: 64] Maximum amount of items returned

• filters (list-of-object) –

  Optional. 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) –

  Optional. 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) –

    • filters (list-of-object) – [internal]

      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

    • rank_divider (float) – [internal]

    • similarity (object) – [internal]

    • malus (object) – [internal]

    • rank_scores (object) – [internal]

    • randomness (object) – [internal]

• exclude_rated_items (bool) – Optional. Exclude already rated items from response

• table (string) – Optional. Table name to read recommendations. This is typically set inside the scenario,it is rare that customers should ever set it themselves

EXAMPLE QUERY BODY

  {
      "scenario": "generic_home_page",
      "user_id": 123456789,
      "preview_scenarios_params": [
          {
              "name": "home_page",
              "reco_type": "profile_to_items",
              "scenario": {
                  "scenario_type": "case",
                  "case": {"amt": 10}
              }
          },
          {
              "name": "generic_home_page",
              "reco_type": "generic_input_to_items",
              "scenario": {
                  "scenario_type": "case",
                  "case": {"reco_type": "profile_to_items", "scenario": "home_page"}
              }
          }
      ]
  }

Response JSON Object

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

• items_id (ID-array) – Array of items IDs

• evaluated_scenarios (object) –

  Optional.

  Inner fields

  • runtime (list-of-object) – List of evaluated scenarios from runtime scenario [see About Scenarios]

    Inner fields

    • scenario_type (enum) – choices: [case, ab_test, condition, alias] Type of scenario

    • scenario_name (string) – Name of scenario

    • to (string) – Characterization of next scenario evaluated

    • case (object) – resulting case after evaluating the scenario.

      Reco Type: -- Select -- 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
      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) –

          • filters (list-of-object) – [internal]

            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

          • rank_divider (float) – [internal]

          • similarity (object) – [internal]

          • malus (object) – [internal]

          • rank_scores (object) – [internal]

          • randomness (object) – [internal]

      • 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) –

      • advanced_exclude_rated_items (object) – [internal] alpha feature, not released yet as of November 2023.

        Inner fields

        • enabled (bool) –

        • exclude_above_value (float) –

        • exclude_below_value (float) –

        • ensure_exclude_remaining_ratings (bool) –

      • 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) –

              • filters (list-of-object) – [internal]

                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

              • rank_divider (float) – [internal]

              • similarity (object) – [internal]

              • malus (object) – [internal]

              • rank_scores (object) – [internal]

              • randomness (object) – [internal]

      • 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) –

            • filters (list-of-object) – [internal]

              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

            • rank_divider (float) – [internal]

            • similarity (object) – [internal]

            • malus (object) – [internal]

            • rank_scores (object) – [internal]

            • randomness (object) – [internal]

        • 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

    • kwargs_hash (string) – Advanced usage

  • default (list-of-object) – List of evaluated scenarios from default scenario [see About Scenarios]

    Inner fields

    • scenario_type (enum) – choices: [case, ab_test, condition, alias] Type of scenario

    • scenario_name (string) – Name of scenario

    • to (string) – Characterization of next scenario evaluated

    • case (object) – resulting case after evaluating the scenario.

      Reco Type: -- Select -- 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
      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) –

          • filters (list-of-object) – [internal]

            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

          • rank_divider (float) – [internal]

          • similarity (object) – [internal]

          • malus (object) – [internal]

          • rank_scores (object) – [internal]

          • randomness (object) – [internal]

      • 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) –

      • advanced_exclude_rated_items (object) – [internal] alpha feature, not released yet as of November 2023.

        Inner fields

        • enabled (bool) –

        • exclude_above_value (float) –

        • exclude_below_value (float) –

        • ensure_exclude_remaining_ratings (bool) –

      • 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) –

              • filters (list-of-object) – [internal]

                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

              • rank_divider (float) – [internal]

              • similarity (object) – [internal]

              • malus (object) – [internal]

              • rank_scores (object) – [internal]

              • randomness (object) – [internal]

      • 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) –

            • filters (list-of-object) – [internal]

              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

            • rank_divider (float) – [internal]

            • similarity (object) – [internal]

            • malus (object) – [internal]

            • rank_scores (object) – [internal]

            • randomness (object) – [internal]

        • 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

    • kwargs_hash (string) – Advanced usage

  • 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

  • generic_runtime (list-of-object) – List of evaluated generic scenarios from runtime scenario [see About Scenarios]

    Inner fields

    • scenario_type (enum) – choices: [case, ab_test, condition, alias] Type of scenario

    • scenario_name (string) – Name of scenario

    • to (string) – Characterization of next scenario evaluated

    • case (object) – resulting case after evaluating the scenario.

      Reco Type: -- Select -- 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
      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) –

          • filters (list-of-object) – [internal]

            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

          • rank_divider (float) – [internal]

          • similarity (object) – [internal]

          • malus (object) – [internal]

          • rank_scores (object) – [internal]

          • randomness (object) – [internal]

      • 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) –

      • advanced_exclude_rated_items (object) – [internal] alpha feature, not released yet as of November 2023.

        Inner fields

        • enabled (bool) –

        • exclude_above_value (float) –

        • exclude_below_value (float) –

        • ensure_exclude_remaining_ratings (bool) –

      • 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) –

              • filters (list-of-object) – [internal]

                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

              • rank_divider (float) – [internal]

              • similarity (object) – [internal]

              • malus (object) – [internal]

              • rank_scores (object) – [internal]

              • randomness (object) – [internal]

      • 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) –

            • filters (list-of-object) – [internal]

              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

            • rank_divider (float) – [internal]

            • similarity (object) – [internal]

            • malus (object) – [internal]

            • rank_scores (object) – [internal]

            • randomness (object) – [internal]

        • 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

    • kwargs_hash (string) – Advanced usage

  • generic_default (list-of-object) – List of evaluated generic scenarios from default scenario [see About Scenarios]

    Inner fields

    • scenario_type (enum) – choices: [case, ab_test, condition, alias] Type of scenario

    • scenario_name (string) – Name of scenario

    • to (string) – Characterization of next scenario evaluated

    • case (object) – resulting case after evaluating the scenario.

      Reco Type: -- Select -- 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
      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) –

          • filters (list-of-object) – [internal]

            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

          • rank_divider (float) – [internal]

          • similarity (object) – [internal]

          • malus (object) – [internal]

          • rank_scores (object) – [internal]

          • randomness (object) – [internal]

      • 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) –

      • advanced_exclude_rated_items (object) – [internal] alpha feature, not released yet as of November 2023.

        Inner fields

        • enabled (bool) –

        • exclude_above_value (float) –

        • exclude_below_value (float) –

        • ensure_exclude_remaining_ratings (bool) –

      • 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) –

              • filters (list-of-object) – [internal]

                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

              • rank_divider (float) – [internal]

              • similarity (object) – [internal]

              • malus (object) – [internal]

              • rank_scores (object) – [internal]

              • randomness (object) – [internal]

      • 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) –

            • filters (list-of-object) – [internal]

              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

            • rank_divider (float) – [internal]

            • similarity (object) – [internal]

            • malus (object) – [internal]

            • rank_scores (object) – [internal]

            • randomness (object) – [internal]

        • 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

    • kwargs_hash (string) – Advanced usage

• metadata (object) – Optional. [internal] WORK-IN-PROGRESS

EXAMPLE RESPONSE

  {
      "items_id": [
          "c3391d83-553b-40e7-818e-fcf658ec397d",
          "c2a73584-bbd0-4f04-b497-26bf70152932"
      ],
      "next_cursor": "HLe-e1Sq...",
      "evaluated_scenarios": {
          "generic_runtime": [
              {
              "scenario_type": "case",
              "scenario_name": "generic_home_page",
              "case": {"reco_type": "profile_to_items", "scenario": "home_page"}
              }
          ],
          "reco_type": "profile_to_items",
          "runtime": [
              {
              "scenario_type": "case",
              "scenario_name": "home_page",
              "case": {"amt": 10}
              }
          ],
          "default": [
              {
              "scenario_type": "case",
              "scenario_name": "only_recent_movies",
              "case": {"filters": [{"property_name": "year", "op": "gte", "value": 2024}]}
              }
          ]
      }
  }

Errors:

• ServerUnavailable with error name DATABASE_NOT_READY if no ML model has been trained for this database

• NotFoundError with error name ITEM_PROPERTY_NOT_FOUND if an item property required by a business rule does not exist

• WrongData with error name WRONG_DATA_TYPE if any filter is invalid, with error name WRONG_OP_USE if a filter operator is not used appropriately, with error name WRONG_PARAMETER if a parameter is not valid.

• NotFoundError with error name SCENARIO_NOT_FOUND if provided scenario does not exist

• WrongData with error name WRONG_DATA_TYPE if any business rule is invalid, or if there is no allowlisted trained instance