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.

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

Scenarios¶

Scenario Types¶

There are three types of scenarios, which contain different logic can be used the same way.

Once created through the endpoint PUT scenarios/<str:reco_type>/<str:name>/, 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:

Scenario Cases¶

Scenarios cases are saved business-rules, for easier use.

$ curl -XPUT https://api.crossingminds.com/scenarios/item_to_items/scenar1/ \
  -d '{"scenario_type":"case","case":{"filters":["genres:eq:comedy"]}}' -s -H "Authorization: Bearer $JWT_TOKEN"

Scenario AB-Tests¶

[WIP]

Scenario Condition¶

[WIP]

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.

$ curl https://api.crossingminds.com/recommendation/items/123/items/?\
  amt=3&scenario=scenar101 -s \
  -H "Authorization: Bearer $JWT_TOKEN" \
  | jq -r '.items_id'

RESPONSE¶

[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 below is then equivalent to the code just above.

$ curl -XPUT https://api.crossingminds.com/scenarios-default/item_to_items/ \
  -d '{"name=scenar101"}' -s -H "Authorization: Bearer $JWT_TOKEN"
$ curl https://api.crossingminds.com/recommendation/items/123/items/?amt=3 -s \
  -H "Authorization: Bearer $JWT_TOKEN" \
  | jq -r '.items_id'

RESPONSE¶

[456, 321, 789]

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

$ curl https://api.crossingminds.com/recommendation/items/123/items/\
  ?amt=3&skip_default_scenario=true -s \
  -H "Authorization: Bearer $JWT_TOKEN" \
  | jq -r '.items_id'

RESPONSE¶

[456, 789, 321]

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.