Merge fcde2d3 into 70cb1ba

data/test_domains/default_with_slots.yml

@@ -22,10 +22,10 @@ templates:
   utter_greet:
     - "hey there {name}!"  # {name} will be filled by slot (same name) or by custom action code
   utter_goodbye:
-    - "goodbye 😢"
-    - "bye bye 😢"   # multiple templates - bot will randomly pick one of them
-  utter_default:
-    - "default message"
+    - "goodbye 😢"   # multiple templates - bot will randomly pick one of them
+    - "bye bye 😢"
+  utter_default:   # utterance sent by action_default_fallback
+    - "sorry, I didn't get that, can you rephrase it?"
 
 actions:
   - utter_default

docs/fallbacks.rst

@@ -4,60 +4,47 @@
 .. _fallbacks:
 
 Fallback Actions
-==========================
+================
 
+Sometimes you want to revert to a fallback action, such as replying,
+`"Sorry, I didn't understand that"`. You can handle fallback cases by adding
+either the ``FallbackPolicy`` or the ``TwoStageFallbackPolicy`` to your
+policy ensemble.
 
+Fallback Policy
+---------------
 
-Sometimes you want to fall back to a fallback action like saying
-`"Sorry, I didn't understand that"`. To do this, add the
-``FallbackPolicy`` to your policy ensemble. The fallback action will
+
+The ``FallbackPolicy`` has one fallback action, which will
 be executed if the intent recognition has a confidence below ``nlu_threshold``
 or if none of the dialogue policies predict an action with
 confidence higher than ``core_threshold``.
 
 The thresholds and fallback action can be adjusted in the policy configuration
-file as parameters of the ``FallbackPolicy``:
+file as parameters of the ``FallbackPolicy``.
 
 .. code-block:: yaml
 
   policies:
     - name: "FallbackPolicy"
-      # min confidence needed to accept an NLU prediction
-      nlu_threshold: 0.3
-      # min confidence needed to accept an action prediction from Rasa Core
+      nlu_threshold: 0.4
       core_threshold: 0.3
-      # name of the action to be called if the confidence of intent / action
-      # is below the threshold
-      fallback_action_name: 'action_default_fallback'
-
-If you want to run this from python, use:
-
-.. code-block:: python
-
-   from rasa_core.policies.fallback import FallbackPolicy
-   from rasa_core.policies.keras_policy import KerasPolicy
-   from rasa_core.agent import Agent
-
-   fallback = FallbackPolicy(fallback_action_name="action_default_fallback",
-                             core_threshold=0.3,
-                             nlu_threshold=0.3)
+      fallback_action_name: "action_default_fallback"
 
-   agent = Agent("domain.yml", policies=[KerasPolicy(), fallback])
-
-
-``action_default_fallback`` is a default action in Rasa Core, which will send the
+``action_default_fallback`` is a default action in Rasa Core which sends the
 ``utter_default`` template message to the user. Make sure to specify
-this template in your domain file. It will also revert back to the
+the ``utter_default`` in your domain file. It will also revert back to the
 state of the conversation before the user message that caused the
 fallback, so that it will not influence the prediction of future actions.
 You can take a look at the source of the action below:
 
 .. autoclass:: rasa_core.actions.action.ActionDefaultFallback
 
 
-You can also create your own custom action to use as a fallback. If you do, then
-make sure to pass the custom fallback action to ``FallbackPolicy`` inside your
-policy configuration file. For example:
+You can also create your own custom action to use as a fallback (see
+:ref:`customactions` for more info on custom actions). If you
+do, make sure to pass the custom fallback action to ``FallbackPolicy`` inside
+your policy configuration file. For example:
 
 .. code-block:: yaml
 
@@ -73,8 +60,8 @@ policy configuration file. For example:
   the next predictions of your bot may become inaccurate, as it is very likely that
   the fallback action is not present in your stories.
 
-If you have a specific intent that will trigger this, let's say it's
-called ``out_of_scope``, then you should add this as a story:
+If you have a specific intent, let's say it's called ``out_of_scope``, that
+should always trigger the fallback action, you should add this as a story:
 
 .. code-block:: story
 
@@ -83,4 +70,56 @@ called ``out_of_scope``, then you should add this as a story:
       - action_default_fallback
 
 
+Two-stage Fallback Policy
+-------------------------
+
+The ``TwoStageFallbackPolicy`` handles low NLU confidence in multiple stages
+by trying to disambiguate the user input (low core confidence is handled in
+the same manner as the ``FallbackPolicy``).
+
+- If a NLU prediction has a low confidence score, the user is asked to affirm
+  the classification of the intent.  (Default action:
+  ``action_default_ask_affirmation``)
+
+    - If they affirm, the story continues as if the intent was classified
+      with high confidence from the beginning.
+    - If they deny, the user is asked to rephrase their message.
+
+- Rephrasing  (default action: ``action_default_ask_rephrase``)
+
+    - If the classification of the rephrased intent was confident, the story
+      continues as if the user had this intent from the beginning.
+    - If the rephrased intent was not classified with high confidence, the user
+      is asked to affirm the classified intent.
+
+- Second affirmation  (default action: ``action_default_ask_affirmation``)
+
+    - If the user affirms the intent, the story continues as if the user had
+      this intent from the beginning.
+    - If the user denies, the original intent is classified as the specified
+      ``deny_suggestion_intent_name``, and an ultimate fallback action
+      ``fallback_nlu_action_name`` is triggered (e.g. a handoff to a human).
+
+Rasa Core provides the default implementations of
+``action_default_ask_affirmation`` and ``action_default_ask_rephrase``.
+The default implementation of ``action_default_ask_rephrase`` action utters
+the response template ``utter_ask_rephrase``, so be sure to specify this
+template in your domain file.
+The implementation of both actions can be overwritten with :ref:`customactions`.
+
+You can specify the core fallback action as well as the ultimate NLU
+fallback action as parameters to ``TwoStageFallbackPolicy`` in your
+policy configuration file.
+
+.. code-block:: yaml
+
+    policies:
+      - name: TwoStageFallbackPolicy
+        nlu_threshold: 0.3
+        core_threshold: 0.3
+        fallback_core_action_name: "action_default_fallback"
+        fallback_nlu_action_name: "action_default_fallback"
+        deny_suggestion_intent_name: "out_of_scope"
+
+
 .. include:: feedback.inc