Disambiguate user input

When your virtual assistant receives a user utterance and cannot identify the intent with a sufficient level of certainty, it can offer a simple disambiguation system with options related to most likely intents. This options will be presented as quick replies and clicking one of them will resume the conversation with the selected intent.

In this section will show how to set up disambiguation for your project by following those steps.

1. Setting up policies and pipelines.
2. Setting canonical values.
3. Creating a fallback story and a disambiguation response.

Finally we will address more advanced configuration options.

Setup policies and pipelines

The disambiguation requires NLU pipelines and policies to be configured.

Add the following component to ALL (every language) your NLU pipelines (NLU -> Settings). The position doesn’t matter.

pipeline:
  ...
  - name: rasa_addons.nlu.components.intent_ranking_canonical_example_injector.IntentRankingCanonicalExampleInjector
  ...

Then add the following policy to your policies (from the Stories screen).

policies:
---
- name: rasa_addons.core.policies.BotfrontDisambiguationPolicy
  fallback_trigger: 0.30
  disambiguation_trigger: '$0 < 2 * $1'
  n_suggestions: 2 # default value
  excluded_intents:
      - ^chitchat\..* # default value
      - ^basics\..*

Do not use with Rasa FallbackPolicy

Firstly it is now depcrecated and also the FallbackPolicy may conflict with the BotfrontDisambiguationPolicy. You can configure a fallback in the BotfrontDisambiguationPolicy that will take precedence on the disambiguation.

Select a canonical values for each intent

In the following video we create two stories with two new intents: order_food and order_drinks. When adding a few examples to each intent, notice how we mark the most generic one as canonical. Canonical examples are displayed in stories and used for disambiguation.

Disambiguation response and fallback story

When a disambiguation is triggered, the bot will present options to the user in the form of quick replies. Each button will be labeled with the canonical example and will trigger the corresponding intent when clicked.

You can also provide other options, such as a button the user can click if none of the suggestions are relevant.

The following video shows how you can create such a response. We start by creating the fallback story, then we create the disambiguation response (which must be named utter_disambiguation) with a fallback button.

You can add more options

In the example we only added a fallback option, but you can add more. The disambiguation options will just be added to the quick replies you define here.

If you don’t want to provide additional options such as a fallback you can use a Text response instead of a Text with buttons one. Note that Text responses with sequences will not work.

Disambiguation at work

Finally we can train and see our disambiguation at work by asking something ambiguous:

Adjusting the disambiguation threshold

Although the disambiguation_trigger lets you create fancy formulas, the default is generally a good start. Here are a few recipes to adjust the threshold:

• If the disambiguation fires too often, you can adjust it in the following direction: $0 < 1.5 * $1. This will reduce the confidence scores difference between the two higest ranking intents required to trigger a disambiguation.

• If the disambiguation should be triggered more often, go in the other direction: $0 < 3 * $1. This will increase the confidence scores difference between the two higest ranking intents required to trigger a disambiguation.

• If you want to force a disambiguation: $0 < 1.1

• If you want to disable disambiguation: $0 > 1.1

Fallback

Disambiguation uses differences between confidence scores. But sometimes, confidence is so low that disambiguating does not even makes sense. You can define this so low with the fallback_trigger parameter. It is set by default to 0.30, which means that if the highest ranking intent has a confidence score below 0.30, il will just utter utter_fallback

Exclusions

You generally want limit the possible intents to suggest. For example, having “Saying hi” or “yes” as disambiguation options is generally irrelevant. You can exclude such intents with the exclude_intents parameter in your policy.

You can use plain names or regular expressions. For example ^chitchat\..* is equivalent to:

excluded_intents:
    - chitchat.greet
    - chitchat.bye
    - chitchat.whatever
    - ...

If all potential suggestions are excluded, the fallback will be triggered.

Policy options

Here is the list of all parameters available in the policy