Business Rules and Scenarios¶

About Business-Rules¶

To get the most of our recommender system, we strongly advise considering applying some business rules to tailor recommendations to your needs.

The API offers different sorts of business rules:

Reranking: Reranking rules reorder the recommended items according to their property values. See Reranking on Item Property.
Filters: Filters remove the items satisfying certain conditions from the recommendations. See Filtering on Item Property.
Exclude Rated Items: For GET recommendation/users/<str:user_id>/items/ or POST recommendation/sessions/items/ recommendations, rated items can be excluded from the returned items.
Algorithms and Candidates Preselection: [WIP] When various models have been trained, it’s possible to select which one to use.
Table: [WIP] To fetch a bundle of pre-computed recommendations.

You can apply business rules in 3 different ways:

At runtime, by giving parameters to the recommendation endpoint.
At runtime, by specifying a scenario (previously saved business rules); see About Scenarios.
By default, if you saved a scenario and set it as default to apply it automatically to all recommendations; see Default Scenario.

See Scenarios Priority for their order of priority.

Any scenario is defined for a specific recommendation type (profile-to-items, …).

Note that some business-rules (or some special properties) are only accessible through the use of scenarios:

Self-reference in filters,
Algorithms.

About Scenarios¶

Scenarios are a resource of the API that allow a lot of flexibility in managing business-rules. Use the endpoint PUT scenarios/<str:reco_type>/<str:name>/ to create or modify one.

There are four types of scenarios, which contain different logic but can be used in a similar way.

Scenario Types¶

Once created, you have two ways to apply a scenario: by giving it at runtime or by setting it as the unique default scenario for a unique type of recommendations chosen when the scenario is created among:

A group of scenario references (from ab_test, condition, alias) create directed acyclic graphs, of which case scenarios are the leaves. Consequently, you cannot delete a scenario if another scenario refers to it.

Below, we create:

two case scenarios scenar1 and scenar2,
an ab_test scenario scenar_abtest1 referring to both case scenarios,
a condition scenario scenar_condition1 pointing to the ab_test scenario and one of the case scenarios,
an alias scenario scenar_alias1 pointing towards the condition scenario.

In this simplistic example, regardless of which profile-to-items scenario you use, one of the two case scenarios will eventually be applied.

Case Scenarios¶

Case scenarios are saved business-rules, for easier use. Let’s create two profile-to-items scenarios:

CREATE A CASE SCENARIO SETTING FILTERS¶

PUT https://api.crossingminds.com/scenarios/profile_to_items/scenar1/ HTTP/1.1
Content-Type: text/javascript

{
  "scenario_type": "case",
  "case": {
    "filters": ["genres:eq:comedy"]
  }
}

CREATE A CASE SCENARIO SETTING DIVERSITY¶

PUT https://api.crossingminds.com/scenarios/profile_to_items/scenar2/ HTTP/1.1
Content-Type: text/javascript

{
  "scenario_type": "case",
  "case": {
    "reranking": ["genres:diversity:0.5"]
  }
}

A/B Test Scenarios¶

This is the type of scenario needed to run an A/B test. ab_test scenarios refer to 3 resources:

the parameters of the A/B test, created beforehand with the endpoint POST ab-tests/params/;
two scenarios, respectively labelled A and B, for the same recommendation type.

The parameters of the A/B test deterministically characterizes whether a given user belongs to group A or to group B, and the probability of belonging to group A.

If a user falls into group A for an A/B test, then any ab_test scenario referring to that A/B test will apply scenario A to this user. This allows to perform an A/B test across multiple endpoints, such as similar items and profile-based.

The necessity of a user_id is discussed here: Missing User ID Rule.

CREATE PARAMETERS FOR AN A/B TEST¶

POST https://api.crossingminds.com/ab-tests/params/ HTTP/1.1
Content-Type: text/javascript

{
  "name": "ab_test101",
  "probability_a": 0.3333,
  "missing_user_id_rule": "random"
}

RESPONSE¶

{"id": "id123"}

CREATE AN A/B TEST SCENARIO¶

PUT https://api.crossingminds.com/scenarios/profile_to_items/scenar_abtest1/ HTTP/1.1
Content-Type: text/javascript

{
  "scenario_type": "ab_test",
  "ab_test": {
    "id": "id123",
    "scenario_a": "scenar1",
     "scenario_b":"scenar2"
   }
}

Condition Scenarios¶

Condition scenarios evaluate a condition at runtime and redirect towards one of two scenarios following an if/then/else logic. The two scenarios must be for the same recommendation types.

For conditions on the source user in profile_to_* and session_to_* recommendation types, currently only the condition type user_function with function n_ratings is implemented: switching cases thus depends only on the number of (inferred) ratings of the source user.

More functions and more user conditions will be implemented soon.

CREATE A CONDITION SCENARIO ON THE NUMBER OF RATINGS¶

PUT https://api.crossingminds.com/scenarios/profile_to_items/scenar_condition1/ HTTP/1.1
Content-Type: text/javascript

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

For conditions on the source item in item_to_* recommendation types, currently only the item_property condition type is implemented: switching cases thus depends only on the value of a property of the source item.

More conditions might be added in the future.

CREATE A CONDITION SCENARIO FOR AN ITEM PROPERTY¶

PUT https://api.crossingminds.com/scenarios/item_to_items/scenar_condition2/ HTTP/1.1
Content-Type: text/javascript

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

Alias Scenarios¶

Alias scenarios simply forward to the scenario they refer to. When no pointer to a scenario is given, we call the alias scenario empty; in which case, no additional business rules is applied.

Empty alias scenarios (not pointing to any scenario) can be useful to create when you foresee that different use cases might need different business rules in the future, even if they all use the default scenario for now. For instance if you are calling one recommendation endpoint both from the home page of your application and from the product page, we suggest to preemptively create one alias “home_page” and one alias “product_page”, and query the respective scenario names in the endpoint. Doing so will allow you to modify the business rules of both use cases independently straight from our dashboard, without you having to release changes in your codebase since you called “home|product_page” from the beginning.

CREATE AN ALIAS SCENARIO¶

PUT https://api.crossingminds.com/scenarios/profile_to_items/scenar_alias1/ HTTP/1.1
Content-Type: text/javascript

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

Runtime Scenarios¶

The option scenario of items recommendation endpoints accepts a scenario’s name. For example, to apply scenario scenar101 to a GET recommendation/items/<str:item_id>/items/ recommendation, using the endpoint with parameters scenario=scenar101 returns the recommended items, with scenario scenar101 being applied.

USE A GIVEN SCENARIO AT RUNTIME¶

GET https://api.crossingminds.com/recommendation/items/123/items/?amt=3&scenario=scenar101 HTTP/1.1

RESPONSE¶

{"items_id": [456, 321, 789]}

Default Scenarios¶

After creating a scenario for a recommendation type, you may set it as default scenario with the endpoint PATCH scenarios-default/<str:reco_type>/ so that it will be automatically applied to all recommendations of this type on the dataset.

The example below is then equivalent to the example above where the scenario was given at runtime.

SETTING A SCENARIO AS DEFAULT¶

PUT https://api.crossingminds.com/scenarios-default/item_to_items/ HTTP/1.1
Content-Type: text/javascript

{
  "name": "scenar101"
}

USE A DEFAULT SCENARIO AT RUNTIME¶

GET https://api.crossingminds.com/recommendation/items/123/items/?amt=3 HTTP/1.1

RESPONSE¶

{"items_id": [456, 321, 789]}

The default scenario can be skipped at runtime with the option skip_default_scenario set to true:

SKIP THE DEFAULT SCENARIO AT RUNTIME¶

GET https://api.crossingminds.com/recommendation/items/123/items/?amt=3&skip_default_scenario=true HTTP/1.1

RESPONSE¶

{"items_id": [456, 321, 789]}

Scenarios Priority¶

The priority hierarchy is:

runtime-params > runtime-scenario > default-scenario

For example, if you provide the reranking ["price:diversity:1"] at runtime and you set the reranking ["price:diversity:2"] as default scenario before in scenario scenar101, then both reranking rules ["price:diversity:1", "price:diversity:2"] will be applied, in this order.

This concatenation is appropriate for lists such as reranking or filters. For the appropriate recommendation types, the boolean exclude_rated_items will be checked in runtime parameters first. If it’s not given there, the runtime scenario will be checked. If it’s not given there, the default scenario will be checked. If it’s not given there, the default value will be used.

If the default scenario is given at runtime, it is not repeated.