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/
orPOST 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:
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
andscenar2
,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:
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"]
}
}
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.
POST https://api.crossingminds.com/ab-tests/params/ HTTP/1.1
Content-Type: text/javascript
{
"name": "ab_test101",
"probability_a": 0.3333
}
{"id": "id123"}
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.
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.
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.
GET https://api.crossingminds.com/recommendation/items/123/items/?amt=3&scenario=scenar101 HTTP/1.1
{"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.
PUT https://api.crossingminds.com/scenarios-default/item_to_items/ HTTP/1.1
Content-Type: text/javascript
{
"name": "scenar101"
}
GET https://api.crossingminds.com/recommendation/items/123/items/?amt=3 HTTP/1.1
{"items_id": [456, 321, 789]}
The default scenario can be skipped at runtime with the option skip_default_scenario
set to true
:
GET https://api.crossingminds.com/recommendation/items/123/items/?amt=3&skip_default_scenario=true HTTP/1.1
{"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.