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

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

      • filters (list-of-object) – [max_length: 10] Filter on item properties [see Filtering on Item Property]

        Inner fields
        • property_name (string) – Item-property name

        • op (enum) – choices (case insensitive): [eq, lt, lte, gt, gte, in, empty, notempty, neq, notin, ftsearch] Filter Operator

        • value (json-value) – Filter Value

        • disable_preload (bool) – [Advanced feature - latency optimization] if True, the filter will be applied after the candidates preselection. Meant to be used for filters that only exclude a few items (e.g. some_id NOT IN [small_id_list]), and the values depends on the request (hence not cacheable, e.g. dynamic filter values).

      • reranking (list-of-object) – Reranking business rules to apply [see Reranking on Item Property]

        Inner fields
        • property_name (string) – Item-property name. Used for diversity reranking rules.

        • op (enum) – choices: [diversity] Reranking op

        • weight (float) – Weight to apply to diversity reranking rules; must be positive; defaults to 1; values between 0 and 1.5 are recommended

        • options (object) – Op-specific options

          Inner fields
          • activation_period (int) –

          • max_activation_count (int) –

          • default_malus (float) –

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

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

      • algorithms (string) – [Advanced Usage] Algorithms allowlist, formatted as a single string of |-separated values

      • candidates_preselection (object) – [Advanced Usage] Candidates preselection

        Inner fields
        • method (string) –

        • params (object) –

        • item_selector_config (object) –

      • force_session_optimization (object) – [Advanced Usage] Options to force session optimization at runtime

      • cache_control (object) – [Advanced Usage] Options to send cache control in the header of the request

        Inner fields
        • max_age (int) –

      • exclude_items_with_interaction_types (list-of-string) – [max_length: 50] Items that were interacted with one of those interaction types will be excluded from the recommendations

      • exclude_props_of_items_with_interaction_types (list-of-object) – Items possessing the same properties as those interacted with through specified interaction types will be excluded from the recommendations.

        Inner fields
        • property_name (string) – Item property to exclude

        • interaction_types (list-of-string) – List of interaction types that will trigger the exclusion of properties from items interacted with these types.

      • interactions_to_ratings_params (json-value) – [Advanced Usage] alpha feature dec. 2023 Parameters for live conversion from ratings to interactions

      • case_sequence (object) – [Advanced usage] Case sequence

        Inner fields
        • sequence (list-of-object) – [max_length: 2]

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

          • filters (list-of-object) – Filter on item properties [see Filtering on Item Property]

            Inner fields
            • property_name (string) – Item-property name

            • op (enum) – choices (case insensitive): [eq, lt, lte, gt, gte, in, empty, notempty, neq, notin, ftsearch] Filter Operator

            • value (json-value) – Filter Value

            • disable_preload (bool) – [Advanced feature - latency optimization] if True, the filter will be applied after the candidates preselection. Meant to be used for filters that only exclude a few items (e.g. some_id NOT IN [small_id_list]), and the values depends on the request (hence not cacheable, e.g. dynamic filter values).

          • reranking (list-of-object) – Reranking business rules to apply [see Reranking on Item Property]

            Inner fields
            • property_name (string) – Item-property name. Used for diversity reranking rules.

            • op (enum) – choices: [diversity] Reranking op

            • weight (float) – Weight to apply to diversity reranking rules; must be positive; defaults to 1; values between 0 and 1.5 are recommended

            • options (object) – Op-specific options

              Inner fields
              • activation_period (int) –

              • max_activation_count (int) –

              • default_malus (float) –

      • chat_params (object) – Chat custom params

      • reco_type (enum) – choices: [item_to_items, profile_to_items, session_to_items, profile_to_items_w_ctx_items, session_to_items_w_ctx_items, precomputed_item_to_items, precomputed_profile_to_items, item_properties_to_items] Type of recommendation to apply

      • scenario (string) – Name of scenario for the above reco_type to apply [see About Scenarios]

      • model (string) – LLM model like openai/gpt-3.5-turbo or meta-llama/Llama-3-70b-chat-hf

      • retrieval (object) – dynamically retrieve items be used when rendering prompt templates. Can be used for few-shot learning or/and RAG

        Inner fields
        • amt (int) – [min: 0 max: 64] Maximum amount of items retrieved

        • algorithms (string) – Retrieval algorithm

        • property (string) – name of the property to use for retrieval

        • filters (list-of-object) – Filter on item properties [see Filtering on Item Property]

          Inner fields
          • property_name (string) – Item-property name

          • op (enum) – choices (case insensitive): [eq, lt, lte, gt, gte, in, empty, notempty, neq, notin, ftsearch] Filter Operator

          • value (json-value) – Filter Value

        • reranking (list-of-object) – Reranking [see Reranking on Item Property]

          Inner fields
          • property_name (string) – Item-property name. Used for diversity reranking rules.

          • op (enum) – choices: [diversity] Reranking op

          • weight (float) – Weight to apply to diversity reranking rules; must be positive; defaults to 1; values between 0 and 1.5 are recommended

          • options (object) – Op-specific options

            Inner fields
            • activation_period (int) –

            • max_activation_count (int) –

            • default_malus (float) –

        • history_injection (object) – [WORK-IN-PROGRESS] inject retrieved items as history messages

          Inner fields
          • json_template (string) – [DEPRECATED] Jinja template rendering to JSON

          • python_literal_template (string) – [WORK-IN-PROGRESS] Jinja template rendering to python literal

        • candidates_preselection (object) – [Advanced Usage] Candidates preselection

          Inner fields
          • method (string) –

          • params (object) –

          • item_selector_config (object) –

        • properties_returned (list-of-string) – List of items properties to return for items retrieved

      • system_prompt (string) – system prompt template in Jinja

      • max_tokens (int) – max_tokens

      • temperature (float) – temperature

    • alias (object) –

      Inner fields
      • scenario_name (string) – Name of an existing scenario

    • condition (object) –

      Inner fields
      • condition_type (enum) – choices (case insensitive): [user_function, item_property, runtime_param] Type of condition

      • if (object) – Condition to be tested at runtime. Sub-fields depend on condition_type, see example below

        Inner fields
        • function_name (enum) – choices (case insensitive): [n_ratings, n_interactions] function name, for user_condition

        • property_name (string) – Item property name, for item_property

        • param_name (string) – Runtime param name, for condition on runtime_param

        • op (enum) – choices (case insensitive): [gte, gt, notempty, lt, lte, in, eq] OP

        • value (json-value) – Value to apply with the operator

      • then (string) – Scenario to evaluate if condition is true

      • else (string) – Scenario to evaluate if condition is false

    • ab_test (object) –

      Inner fields
      • id (string) – A/B test unique ID

      • scenario_a (string) – Name of scenario for variant A

      • scenario_b (string) – Name of scenario for variant B

EXAMPLE RESPONSE FOR CASE SCENARIO
{
    "name": "my_scenar101",
    "reco_type": "profile_to_items",
    "scenario": {
        "scenario_type": "case",
        "case": {
            "amt": 6,
            "filters": [{"property_name": "year", "op": "eq", "value": 1988}],
            "reranking": [{"property_name": "genres", "op": "diversity", "weight": 0.25}],
            "exclude_rated_items": false,
            "algorithms": "algo105|algo106",
             "candidates_preselection": {
                "method": "knn",
                "params": {"algorithms": ["algo103"]}
        }
    }
}
EXAMPLE RESPONSE FOR AB-TEST SCENARIO
{
    "name": "my_scenar_ab",
    "reco_type": "profile_to_items",
    "scenario": {
        "scenario_type": "ab_test",
        "ab_test": {
            "id": "my_ab_test",
            "scenario_a": "scenar1",
            "scenario_b": "scenar2"
        }
    }
}
EXAMPLE RESPONSE FOR ALIAS SCENARIO
{
    "name": "my_scenar_alias",
    "reco_type": "profile_to_items",
    "scenario": {
        "scenario_type": "alias",
        "alias": {
            "scenario_name": "my_favorite_scenario"
        }
    }
}

Errors:

  • NotFoundError with error name SCENARIO_NOT_FOUND if a scenario is missing

Create or Replace Scenario

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

Note

Authorized Roles: root, manager, backend

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

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

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

  • metadata (object) – Optional. Metadata of scenario

  • case (object) –

    Optional.

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

    • filters (list-of-object) – [max_length: 10] Filter on item properties [see Filtering on Item Property]

      Inner fields
      • property_name (string) – Item-property name

      • op (enum) – choices (case insensitive): [eq, lt, lte, gt, gte, in, empty, notempty, neq, notin, ftsearch] Filter Operator

      • value (json-value) – Filter Value

      • disable_preload (bool) – [Advanced feature - latency optimization] if True, the filter will be applied after the candidates preselection. Meant to be used for filters that only exclude a few items (e.g. some_id NOT IN [small_id_list]), and the values depends on the request (hence not cacheable, e.g. dynamic filter values).

    • reranking (list-of-object) – Reranking business rules to apply [see Reranking on Item Property]

      Inner fields
      • property_name (string) – Item-property name. Used for diversity reranking rules.

      • op (enum) – choices: [diversity] Reranking op

      • weight (float) – Weight to apply to diversity reranking rules; must be positive; defaults to 1; values between 0 and 1.5 are recommended

      • options (object) – Op-specific options

        Inner fields
        • activation_period (int) –

        • max_activation_count (int) –

        • default_malus (float) –

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

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

    • algorithms (string) – [Advanced Usage] Algorithms allowlist, formatted as a single string of |-separated values

    • candidates_preselection (object) – [Advanced Usage] Candidates preselection

      Inner fields
      • method (string) –

      • params (object) –

      • item_selector_config (object) –

    • force_session_optimization (object) – [Advanced Usage] Options to force session optimization at runtime

    • cache_control (object) – [Advanced Usage] Options to send cache control in the header of the request

      Inner fields
      • max_age (int) –

    • exclude_items_with_interaction_types (list-of-string) – [max_length: 50] Items that were interacted with one of those interaction types will be excluded from the recommendations

    • exclude_props_of_items_with_interaction_types (list-of-object) – Items possessing the same properties as those interacted with through specified interaction types will be excluded from the recommendations.

      Inner fields
      • property_name (string) – Item property to exclude

      • interaction_types (list-of-string) – List of interaction types that will trigger the exclusion of properties from items interacted with these types.

    • interactions_to_ratings_params (json-value) – [Advanced Usage] alpha feature dec. 2023 Parameters for live conversion from ratings to interactions

    • case_sequence (object) – [Advanced usage] Case sequence

      Inner fields
      • sequence (list-of-object) – [max_length: 2]

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

        • filters (list-of-object) – Filter on item properties [see Filtering on Item Property]

          Inner fields
          • property_name (string) – Item-property name

          • op (enum) – choices (case insensitive): [eq, lt, lte, gt, gte, in, empty, notempty, neq, notin, ftsearch] Filter Operator

          • value (json-value) – Filter Value

          • disable_preload (bool) – [Advanced feature - latency optimization] if True, the filter will be applied after the candidates preselection. Meant to be used for filters that only exclude a few items (e.g. some_id NOT IN [small_id_list]), and the values depends on the request (hence not cacheable, e.g. dynamic filter values).

        • reranking (list-of-object) – Reranking business rules to apply [see Reranking on Item Property]

          Inner fields
          • property_name (string) – Item-property name. Used for diversity reranking rules.

          • op (enum) – choices: [diversity] Reranking op

          • weight (float) – Weight to apply to diversity reranking rules; must be positive; defaults to 1; values between 0 and 1.5 are recommended

          • options (object) – Op-specific options

            Inner fields
            • activation_period (int) –

            • max_activation_count (int) –

            • default_malus (float) –

    • chat_params (object) – Chat custom params

    • reco_type (enum) – choices: [item_to_items, profile_to_items, session_to_items, profile_to_items_w_ctx_items, session_to_items_w_ctx_items, precomputed_item_to_items, precomputed_profile_to_items, item_properties_to_items] Type of recommendation to apply

    • scenario (string) – Name of scenario for the above reco_type to apply [see About Scenarios]

    • model (string) – LLM model like openai/gpt-3.5-turbo or meta-llama/Llama-3-70b-chat-hf

    • retrieval (object) – dynamically retrieve items be used when rendering prompt templates. Can be used for few-shot learning or/and RAG

      Inner fields
      • amt (int) – [min: 0 max: 64] Maximum amount of items retrieved

      • algorithms (string) – Retrieval algorithm

      • property (string) – name of the property to use for retrieval

      • filters (list-of-object) – Filter on item properties [see Filtering on Item Property]

        Inner fields
        • property_name (string) – Item-property name

        • op (enum) – choices (case insensitive): [eq, lt, lte, gt, gte, in, empty, notempty, neq, notin, ftsearch] Filter Operator

        • value (json-value) – Filter Value

      • reranking (list-of-object) – Reranking [see Reranking on Item Property]

        Inner fields
        • property_name (string) – Item-property name. Used for diversity reranking rules.

        • op (enum) – choices: [diversity] Reranking op

        • weight (float) – Weight to apply to diversity reranking rules; must be positive; defaults to 1; values between 0 and 1.5 are recommended

        • options (object) – Op-specific options

          Inner fields
          • activation_period (int) –

          • max_activation_count (int) –

          • default_malus (float) –

      • history_injection (object) – [WORK-IN-PROGRESS] inject retrieved items as history messages

        Inner fields
        • json_template (string) – [DEPRECATED] Jinja template rendering to JSON

        • python_literal_template (string) – [WORK-IN-PROGRESS] Jinja template rendering to python literal

      • candidates_preselection (object) – [Advanced Usage] Candidates preselection

        Inner fields
        • method (string) –

        • params (object) –

        • item_selector_config (object) –

      • properties_returned (list-of-string) – List of items properties to return for items retrieved

    • system_prompt (string) – system prompt template in Jinja

    • max_tokens (int) – max_tokens

    • temperature (float) – temperature

  • alias (object) –

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

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

        • filters (list-of-object) – [max_length: 10] Filter on item properties [see Filtering on Item Property]

          Inner fields
          • property_name (string) – Item-property name

          • op (enum) – choices (case insensitive): [eq, lt, lte, gt, gte, in, empty, notempty, neq, notin, ftsearch] Filter Operator

          • value (json-value) – Filter Value

          • disable_preload (bool) – [Advanced feature - latency optimization] if True, the filter will be applied after the candidates preselection. Meant to be used for filters that only exclude a few items (e.g. some_id NOT IN [small_id_list]), and the values depends on the request (hence not cacheable, e.g. dynamic filter values).

        • reranking (list-of-object) – Reranking business rules to apply [see Reranking on Item Property]

          Inner fields
          • property_name (string) – Item-property name. Used for diversity reranking rules.

          • op (enum) – choices: [diversity] Reranking op

          • weight (float) – Weight to apply to diversity reranking rules; must be positive; defaults to 1; values between 0 and 1.5 are recommended

          • options (object) – Op-specific options

            Inner fields
            • activation_period (int) –

            • max_activation_count (int) –

            • default_malus (float) –

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

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

        • algorithms (string) – [Advanced Usage] Algorithms allowlist, formatted as a single string of |-separated values

        • candidates_preselection (object) – [Advanced Usage] Candidates preselection

          Inner fields
          • method (string) –

          • params (object) –

          • item_selector_config (object) –

        • force_session_optimization (object) – [Advanced Usage] Options to force session optimization at runtime

        • cache_control (object) – [Advanced Usage] Options to send cache control in the header of the request

          Inner fields
          • max_age (int) –

        • exclude_items_with_interaction_types (list-of-string) – [max_length: 50] Items that were interacted with one of those interaction types will be excluded from the recommendations

        • exclude_props_of_items_with_interaction_types (list-of-object) – Items possessing the same properties as those interacted with through specified interaction types will be excluded from the recommendations.

          Inner fields
          • property_name (string) – Item property to exclude

          • interaction_types (list-of-string) – List of interaction types that will trigger the exclusion of properties from items interacted with these types.

        • interactions_to_ratings_params (json-value) – [Advanced Usage] alpha feature dec. 2023 Parameters for live conversion from ratings to interactions

        • case_sequence (object) – [Advanced usage] Case sequence

          Inner fields
          • sequence (list-of-object) – [max_length: 2]

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

            • filters (list-of-object) – Filter on item properties [see Filtering on Item Property]

              Inner fields
              • property_name (string) – Item-property name

              • op (enum) – choices (case insensitive): [eq, lt, lte, gt, gte, in, empty, notempty, neq, notin, ftsearch] Filter Operator

              • value (json-value) – Filter Value

              • disable_preload (bool) – [Advanced feature - latency optimization] if True, the filter will be applied after the candidates preselection. Meant to be used for filters that only exclude a few items (e.g. some_id NOT IN [small_id_list]), and the values depends on the request (hence not cacheable, e.g. dynamic filter values).

            • reranking (list-of-object) – Reranking business rules to apply [see Reranking on Item Property]

              Inner fields
              • property_name (string) – Item-property name. Used for diversity reranking rules.

              • op (enum) – choices: [diversity] Reranking op

              • weight (float) – Weight to apply to diversity reranking rules; must be positive; defaults to 1; values between 0 and 1.5 are recommended

              • options (object) – Op-specific options

                Inner fields
                • activation_period (int) –

                • max_activation_count (int) –

                • default_malus (float) –

        • chat_params (object) – Chat custom params

        • reco_type (enum) – choices: [item_to_items, profile_to_items, session_to_items, profile_to_items_w_ctx_items, session_to_items_w_ctx_items, precomputed_item_to_items, precomputed_profile_to_items, item_properties_to_items] Type of recommendation to apply

        • scenario (string) – Name of scenario for the above reco_type to apply [see About Scenarios]

        • model (string) – LLM model like openai/gpt-3.5-turbo or meta-llama/Llama-3-70b-chat-hf

        • retrieval (object) – dynamically retrieve items be used when rendering prompt templates. Can be used for few-shot learning or/and RAG

          Inner fields
          • amt (int) – [min: 0 max: 64] Maximum amount of items retrieved

          • algorithms (string) – Retrieval algorithm

          • property (string) – name of the property to use for retrieval

          • filters (list-of-object) – Filter on item properties [see Filtering on Item Property]

            Inner fields
            • property_name (string) – Item-property name

            • op (enum) – choices (case insensitive): [eq, lt, lte, gt, gte, in, empty, notempty, neq, notin, ftsearch] Filter Operator

            • value (json-value) – Filter Value

          • reranking (list-of-object) – Reranking [see Reranking on Item Property]

            Inner fields
            • property_name (string) – Item-property name. Used for diversity reranking rules.

            • op (enum) – choices: [diversity] Reranking op

            • weight (float) – Weight to apply to diversity reranking rules; must be positive; defaults to 1; values between 0 and 1.5 are recommended

            • options (object) – Op-specific options

              Inner fields
              • activation_period (int) –

              • max_activation_count (int) –

              • default_malus (float) –

          • history_injection (object) – [WORK-IN-PROGRESS] inject retrieved items as history messages

            Inner fields
            • json_template (string) – [DEPRECATED] Jinja template rendering to JSON

            • python_literal_template (string) – [WORK-IN-PROGRESS] Jinja template rendering to python literal

          • candidates_preselection (object) – [Advanced Usage] Candidates preselection

            Inner fields
            • method (string) –

            • params (object) –

            • item_selector_config (object) –

          • properties_returned (list-of-string) – List of items properties to return for items retrieved

        • system_prompt (string) – system prompt template in Jinja

        • max_tokens (int) – max_tokens

        • temperature (float) – temperature

      • alias (object) –

        Inner fields
        • scenario_name (string) – Name of an existing scenario

      • condition (object) –

        Inner fields
        • condition_type (enum) – choices (case insensitive): [user_function, item_property, runtime_param] Type of condition

        • if (object) – Condition to be tested at runtime. Sub-fields depend on condition_type, see example below

          Inner fields
          • function_name (enum) – choices (case insensitive): [n_ratings, n_interactions] function name, for user_condition

          • property_name (string) – Item property name, for item_property

          • param_name (string) – Runtime param name, for condition on runtime_param

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