Scenarios are a resource of the API used to save and name business rules configurations. Use the endpoint PUT scenarios/<str:reco_type>/<str:name>/ to create or modify one.

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

Once created, you have two ways to apply a scenario:

1. by giving it at runtime when calling your recommendation (e.g. ?scenario=home_page)
2. by setting it “as default” so this set of business rules are always applied for a sopecific type of recommendations.

‍

The business rules (filters, reranking, etc) are configured in scenarios of type case. On top of this, you can create scenarios referencing other scenarios to implement branching logic.

A group of scenario references (from ab_test, condition, alias) create directed acyclic graphs, of which case scenarios are the end vertices.

Note that you cannot create a cycle of references, and you cannot delete a scenario if another scenario refers to it.

In the examples below, we are going to create:

• two case scenarios my_filter_scenario and my_rerank_scenario, setting respectively filters and reranking.
• an ab_test scenario my_abtest referring to both case scenarios; routing the first one for the A group and the second one for the B group;
• a condition scenario my_condition pointing to the ab_test scenario when the condition is true, and one of the case scenarios otherwise;
• an alias scenario my_static_alias pointing towards the condition scenario, just to give it a static name.

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

Scenarios of type case are saved and named business-rules. You can find them in the Business Rules > Scenario Tab of your dashboard

‍

Evaluate Your Scenarios

Case scenarios can then be loaded when evaluating your recommendations. By going into your "User Based", "Related Items" or "Session Based" recommendation tab,

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. Note that the parameters of the A/B test are configured in a separated resource. This design allows to use the same A/B split across different scenarios, hence different recommendation types. If a user ID (resp. session ID) 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 (resp. session). This allows to perform an A/B test across multiple endpoints, such as similar items and profile-based.

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

For more information about the setup of A/B test flow, read our A/B testing documenation page.

‍

Condition Fows

Scenarios of type condition evaluate a condition at runtime and branch 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.

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 functions and more item conditions will be implemented soon.