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. Typically the business rules are configured by your dedicated machine learning engineer at Crossing Minds, but we encourage getting familiar with the logic regardless.

The API offers different sorts of business rules:

Filters: Filters keep only the items satisfying certain conditions in the recommendations. See Filtering on Item Property.
Exclude Rated Items: For user-to-* or session-to-* endpoints, interacted (or rated) items can be excluded from the recommended items.
Reranking: Reranking rules reorder the recommended items according to their property values. See Reranking on Item Property.
Algorithms and Candidates Preselection: Internal parameters that your dedicated machine learning engineer configure to select which model is used.

You can apply business rules in 3 different ways:

At runtime, by giving parameters to the recommendation endpoint. This is the preferred approach when exposing these controls to your end-users. For instance when your UI has buttons to filter recommendations.
At runtime, by specifying a scenario name (saved business rules configuration); see About Scenarios. This is the preferred approach when hard-coding a scenario name in the API call, for instance ?scenario=home_page, or ?scenario=product_page.
Set a scenario “as default” to apply it automatically to this endpoint; see Automatic Scenario.

When using multiple ways at a time, the rules are either over-written or merged depending on their types. See Business Rules Priority and Merging.

About Scenarios¶

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: by giving it at runtime (e.g. ?scenario=home_page) or by setting it “as default” for this endpoint.

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

Scenario Types¶

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. Let’s create two case scenarios for the profile_to_items endpoint:

CREATE A CASE SCENARIO SETTING FILTERS¶

PUT https://api.crossingminds.com/scenarios/profile_to_items/my_filter_scenario/ 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/my_rerank_scenario/ 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. 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.

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/my_abtest/ HTTP/1.1
Content-Type: text/javascript

{
  "scenario_type": "ab_test",
  "ab_test": {
    "id": "id123",
    "scenario_a": "my_filter_scenario",
    "scenario_b":"my_rerank_scenario"
   }
}

Condition Scenarios¶

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.

CREATE A CONDITION SCENARIO ON THE NUMBER OF RATINGS¶

PUT https://api.crossingminds.com/scenarios/profile_to_items/my_condition/ 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": "my_abtest",
    "else": "my_rerank_scenario"
  }
}

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.

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¶

Scenarios of type alias 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 specified.

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.

CREATE AN ALIAS SCENARIO¶

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

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

Runtime Scenarios¶

The parameter scenario of recommendation endpoints accepts a scenario name. For example, to apply scenario my_static_alias to a GET recommendation/items/<str:item_id>/items/ recommendation, using the endpoint with parameters ?scenario=my_static_alias returns the recommended items, with scenario my_static_alias 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]}

Automatic Scenarios¶

After creating a scenario for a recommendation type, you may set it “as default” 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.

Warning: the terminology “default” is kept for backward compatibility, but “automatic” is a better terminology. Indeed the scenario is still used even when another scenario is specified at runtime, and the rules are over-written or merged following Business Rules Priority and Merging.

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 And Merging¶

The priority hierarchy is:

runtime-params > runtime-scenario > default-scenario

Concatenation of Lists¶

Business rules that are given as lists are concatenated. This applies to reranking, filters, and exclude_items_with_interaction_types.

Because of this concatenation logic, the terminology “default scenario” is misleading. It is better to use the terminology “automatically applied scenario”.

For example, if you provide the filters ["category:eq:drama"] at runtime, and you set the filters ["status:eq:available"] in a default scenario, then both filters ["category:eq:drama", "status:eq:available"] will be applied.

Note that the order does not matter for filters, but it does matter for reranking.

If the default scenario is also given at runtime, the values in the list are not duplicated.

Over-writing Scalars¶

Business rules that are given as boolean, integers, or string values are over-written. This applies to amt, exclude_rated_items, algorithms, table, and candidates_preselection.

For instance amt will be checked in runtime parameters first. If it’s not given there, the value from the runtime scenario will be checked. If it’s not given there, the value from default scenario will be checked. If it’s not given there, the default value will be used.