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

  • name (string) – [min-length: 1 max-length: 64] Scenario Name

  • 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] Type of recommendation a scenario applies to

  • scenario (object) –

    Inner fields:

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

    • metadata (object) – Metadata of scenario

    • condition (object) –

      Inner fields:

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

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

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

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

    • alias (object) –

      Inner fields:

      • scenario_name (string) – Name of an existing scenario

    • case (object) – See About Scenarios for the syntax

      Inner fields:

      • reranking (list-of-(string|object)) – List of reranking rules

        See Reranking Syntax for the syntax

        Inner fields:

        • property_name (string) – Item-property name

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

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

        • options (object) – Op-specific options

      • filters (list-of-object) – [max_length: 10] List of filters

        The field value is incompatible with notempty. See Filter Syntax for the syntax.

        Inner fields:

        • property_name (string) – Item-property name

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

        • value (json-value) – Filter Value

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

      • algorithms (string) – [WORK IN PROGRESS] Algorithms whitelist, formatted as a single string of |-separated values

      • candidates_preselection (object) – [WORK IN PROGRESS] Candidates preselection method and params

      • table (string) – Table name to read recommendations

    • 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": {
            "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
{
    "scenario_type": "alias",
    "alias": {
        "scenario_name": "my_favourite_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

  • condition (object) –

    Optional.

    Inner fields:

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

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

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

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

  • alias (object) –

    Optional.

    Inner fields:

    • scenario_name (string) – Name of an existing scenario

  • case (object) –

    Optional. See About Scenarios for the syntax

    Inner fields:

    • reranking (list-of-(string|object)) – List of reranking rules

      See Reranking Syntax for the syntax

      Inner fields:

      • property_name (string) – Item-property name

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

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

      • options (object) – Op-specific options

    • filters (list-of-object) – [max_length: 10] List of filters

      The field value is incompatible with notempty. See Filter Syntax for the syntax.

      Inner fields:

      • property_name (string) – Item-property name

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

      • value (json-value) – Filter Value

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

    • algorithms (string) – [WORK IN PROGRESS] Algorithms whitelist, formatted as a single string of |-separated values

    • candidates_preselection (object) – [WORK IN PROGRESS] Candidates preselection method and params

    • table (string) – Table name to read recommendations

  • 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": {
        "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": true,
        "algorithms": "algo101|algo102",
        "candidates_preselection": {
                "method": "knn",
                "params": {"algorithms": ["algo103"]}
        }
    }
}
EXAMPLE QUERY BODY FOR CASE SCENARIO WITH NESTED FILTER VALUE
{
    "scenario_type": "case",
    "case": {
        "filters": [
            {
                "property_name": "category",
                "op": "eq",
                "value": {
                    "type": "user_property",
                    "value": "selected_category"
                }
            }
        ]
    }
}
EXAMPLE QUERY BODY FOR CONDITION SCENARIO FOR USER FUNCTION
{
    "scenario_type": "condition",
    "condition": {
        "condition_type": "user_function",
        "if": {"function_name": "n_ratings", "op": "gte", "value": 21},
        "then": "scenario1",
        "else": "scenario2"
    }
}
EXAMPLE QUERY BODY FOR CONDITION SCENARIO FOR ITEM PROPERTY
{
    "scenario_type": "condition",
    "condition": {
        "condition_type": "item_property",
        "if": {"property_name": "prop_int", "op": "lt", "value": 21},
        "then": "scenario1",
        "else": "scenario2"
    }
}
EXAMPLE QUERY BODY FOR AB-TEST SCENARIO
{
    "scenario_type": "ab_test",
    "ab_test": {
        "id": "ab-test-id12345",
        "scenario_a": "scenar1",
        "scenario_b": "scenar2"
    }
}
EXAMPLE QUERY BODY FOR ALIAS SCENARIO
{
    "scenario_type": "alias",
    "alias": {
        "scenario_name": "my_favourite_scenario"
    }
}
Response JSON Object
  • warnings (list-of-string) – Optional. List of warnings

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

Errors:

  • WrongData with error name WRONG_DATA_TYPE if any business rule is invalid

  • WrongData if the scenario exists and is of type “ab_test”

  • WrongData if the scenario would create a loop

Delete A Scenario

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

Note

Authorized Roles: root, manager, backend

Delete single scenario [see About Scenarios].

Errors:

  • NotFoundError with error name SCENARIO_NOT_FOUND if named scenario is missing

Get All Scenarios

GET scenarios/

Note

Authorized Roles: root, manager, backend

Return all scenarios [see About Scenarios].

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

  • scenarios (list-of-object) –

    Inner fields:

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

    • name (string) – [min-length: 1 max-length: 64] Scenario Name

    • 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] Type of recommendation a scenario applies to

    • scenario (object) –

      Inner fields:

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

      • metadata (object) – Metadata of scenario

      • condition (object) –

        Inner fields:

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

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

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

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

      • alias (object) –

        Inner fields:

        • scenario_name (string) – Name of an existing scenario

      • case (object) – See About Scenarios for the syntax

        Inner fields:

        • reranking (list-of-(string|object)) – List of reranking rules

          See Reranking Syntax for the syntax

          Inner fields:

          • property_name (string) – Item-property name

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

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

          • options (object) – Op-specific options

        • filters (list-of-object) – [max_length: 10] List of filters

          The field value is incompatible with notempty. See Filter Syntax for the syntax.

          Inner fields:

          • property_name (string) – Item-property name

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

          • value (json-value) – Filter Value

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

        • algorithms (string) – [WORK IN PROGRESS] Algorithms whitelist, formatted as a single string of |-separated values

        • candidates_preselection (object) – [WORK IN PROGRESS] Candidates preselection method and params

        • table (string) – Table name to read recommendations

      • ab_test (object) –

        Inner fields:

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

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

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

EXAMPLE RESPONSE
{
    "scenarios": [
        {
            "name": "my_scenar101",
            "reco_type": "profile_to_items",
            "scenario": {
                "scenario_type": "case",
                "case": {
                    "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": "scenar1",
                    "scenario_b": "scenar2"
                }
            }
        }, {
            "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": "scenario1",
                    "else": "scenario2"
                }
            },
        }, {

            "scenario_type": "alias",
            "alias": {
                "scenario_name": "my_favourite_scenario"
            }
        }
    ]
}

Get Default Scenario

GET scenarios-default/<str:reco_type>/

Note

Authorized Roles: root, manager, backend

Get default scenario [see Default Scenarios].

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

  • name (string) – [min-length: 1 max-length: 64] 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 Default Scenarios].

Request JSON Object
  • name (string) – [min-length: 1 max-length: 64] 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 Default Scenarios].