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:

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:

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.

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

Currently only the user_function condition is implemented, and only the n_ratings function is implemented.

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"
  }
}

Alias Scenarios

Alias scenarios simply forward to the scenario they refer to.

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.