Merge pull request #46 from botfront/disambiguation2

Disambiguation

Author: pheel

README.md

@@ -3,8 +3,105 @@
 ![PyPI](https://img.shields.io/pypi/v/rasa-addons.svg)
 ![Travis](https://img.shields.io/travis/mrbot-ai/rasa-addons.svg)
 
-A set of 🚀🚀🚀 components to be used with Botfront and/or Rasa
+A set of 🚀🚀🚀 components to be used with Botfront and/or Rasa.
 
 [Botfront](https://github.com/botfront/botfront) is an open source chatbot platform built with Rasa.
 
+## Disambiguation Policy
 
+This policy implements fallback and suggestion-based disambiguation.
+
+It works with actions ``rasa_addons.core.actions.ActionBotfrontDisambiguation``, ``rasa_addons.core.actions.ActionBotfrontDisambiguationFollowup`` and ``rasa_addons.core.actions.ActionBotfrontDisambiguationFollowup``.
+
+### Example usage
+
+```
+policies:
+...
+  - name: rasa_addons.core.policies.DisambiguationPolicy
+    fallback_trigger: 0.30
+    disambiguation_trigger: '$0 < 2 * $1'
+    deny_suggestions: 'deny_suggestions'
+    n_suggestions: 3
+    excluded_intents:
+      - ^chitchat\..*
+    disambiguation_title:
+      en: "Sorry, I'm not sure I understood. Did you mean..."
+      fr: "J'ai mal compris. Voulez-vous dire..."
+    intent_mappings:
+      basics.yes:
+        en: "Yes"
+        fr: "Oui"
+      basics.no:
+        en: "No"
+        fr: "Non"
+      I_need_help:
+        en: "Help me"
+        fr: "Aidez-moi"
+      I_come_from:
+        en: "I come from {from}"
+        fr: "Je viens de {from}"
+      want_shirt:
+        en: "I want a {color} shirt"
+        fr: "Je veux un chandail {color}"
+      deny_suggestions:
+        en: "Something else"
+        fr: "Autre chose"
+...
+```
+
+### Parameters
+
+##### fallback_trigger
+
+Float (default ``0.30``): if confidence of top-ranking intent is below this threshold, fallback is triggered. Fallback is an action that utters the template ``utter_fallback`` and returns to the previous conversation state.
+
+##### disambiguation_trigger
+
+String (default ``'$0 < 2 * $1'``): if this expression holds, disambiguation is triggered. (If it has already been triggered on the previous turn, fallback is triggered instead.) Here this expression resolves to "the score of the top-ranking intent is below twice the score of the second-ranking intent". Disambiguation is an action that lets the user to choose from the top-ranking intents using a button prompt.
+
+In addition, an 'Other' option is shown with payload defined in ``deny_suggestions`` param is shown. It is up to the conversation designer to implement a story to handle the continuation of this interaction.
+
+##### deny_suggestions
+
+String: the intent associated in the payload for the 'Other' option.
+
+##### n_suggestions
+
+Int (default 3): the maximum number of suggestions to display (excluding the 'Other' option).
+
+##### excluded_intents
+
+List (regex string): any intent (exactly) matching one of these regular expressions will not be shown as a suggestion.
+
+##### disambiguation_title
+
+Dict (language string -> string): localized disambiguation message title.
+
+##### intent_mappings
+
+Dict (intent string -> language string -> string): localized representative button title for intents. If no title is defined for a given intent, the intent name is rendered instead. These titles support entity substitution: any entity name enclosed in curly brackets (``{entity}``) will be filled with entity information from the user utterance.
+
+_Important:_ The title for the 'Other' option is also defined here.
+
+## Mapping Policy
+
+This policy implements regular expression-based direct mapping from intent to action.
+
+### Example usage
+
+```
+policies:
+...
+  - name: rasa_addons.core.policies.BotfrontMappingPolicy
+    triggers:
+      - trigger: '^map\..+'
+        action: 'action_botfront_mapping'
+        extra_actions:
+          - 'action_myaction'
+...
+```
+
+### ActionBotfrontMapping
+
+The default action ActionBotfrontMapping takes the intent that triggered the mapping policy, e.g. ``map.my_intent`` and tries to generate the template ``utter_map.my_intent``.

rasa_addons/core/actions/__init__.py

@@ -0,0 +1,14 @@
+from rasa_addons.core.actions.action_botfront_mapping import ActionBotfrontMapping
+from rasa_addons.core.actions.action_botfront_disambiguation import ActionBotfrontDisambiguation, ActionBotfrontDisambiguationFollowup, ActionBotfrontFallback
+
+from typing import List, Text, Optional, Dict, Any
+
+def actions() -> List["Action"]:
+    return [
+        ActionBotfrontMapping(),
+        ActionBotfrontDisambiguation(),
+        ActionBotfrontDisambiguationFollowup(),
+        ActionBotfrontFallback()
+    ]
+
+actions_bf = {a.name(): a for a in actions()}

rasa_addons/core/actions/action_botfront_disambiguation.py

@@ -0,0 +1,89 @@
+from rasa.core.events import (
+    UserUtteranceReverted,
+    UserUttered,
+    ActionExecuted,
+    Event,
+    SlotSet,
+)
+from rasa.core.actions.action import Action, ActionUtterTemplate, create_bot_utterance
+
+from typing import Any, List, Text, Dict, Optional
+import logging
+import copy
+
+from requests.auth import HTTPBasicAuth
+
+logging.basicConfig(level="WARN")
+logger = logging.getLogger()
+
+class ActionBotfrontDisambiguation(Action):
+    def name(self):
+        return "action_botfront_disambiguation"
+
+    async def run(
+        self,
+        output_channel: "OutputChannel",
+        nlg: "NaturalLanguageGenerator",
+        tracker: "DialogueStateTracker",
+        domain: "Domain",
+    ) -> List[Event]:
+        message = None
+        for event in list(tracker.events)[::-1]:
+            logger.debug(event)
+            if isinstance(event, SlotSet) and event.key == "disambiguation_message":
+                message = event.value
+                break
+        if message:
+            return [create_bot_utterance({ "text": message["title"], "buttons": message["buttons"] })]
+        else:
+            return []
+
+class ActionBotfrontDisambiguationFollowup(Action):
+    def name(self) -> Text:
+        return "action_botfront_disambiguation_followup"
+
+    async def run(
+        self,
+        output_channel: "OutputChannel",
+        nlg: "NaturalLanguageGenerator",
+        tracker: "DialogueStateTracker",
+        domain: "Domain",
+    ) -> List[Event]:
+
+        revert_events = [
+            UserUtteranceReverted(),
+            UserUtteranceReverted(),
+            ActionExecuted(action_name="action_listen"),
+        ]
+
+        last_user_event = None
+        for event in list(tracker.events)[::-1]:
+            if isinstance(event, UserUttered):
+                last_user_event = copy.deepcopy(event)
+                last_user_event.parse_data["intent"]["confidence"] = 1.0
+                break
+        if last_user_event:
+            revert_events += [last_user_event]
+
+        return revert_events
+
+class ActionBotfrontFallback(ActionUtterTemplate):
+    def name(self) -> Text:
+        return "action_botfront_fallback"
+
+    def __init__(self):
+        super(ActionBotfrontFallback, self).__init__("utter_fallback", silent_fail=True)
+
+    async def run(self, output_channel, nlg, tracker, domain):
+
+        evts = await super(ActionBotfrontFallback, self).run(
+            output_channel, nlg, tracker, domain
+        )
+        if (len(tracker.events) >= 4 and
+        isinstance(tracker.events[-4], ActionExecuted) and
+        tracker.events[-4].action_name ==
+        "action_botfront_disambiguation"):
+            return evts + [UserUtteranceReverted(), UserUtteranceReverted()]
+        else:
+            return evts + [UserUtteranceReverted()]
+

rasa_addons/core/actions/action_botfront_mapping.py

@@ -0,0 +1,31 @@
+from rasa.core.events import Event
+from rasa.core.actions.action import Action, ActionUtterTemplate, create_bot_utterance
+
+from typing import Any, List, Text, Dict, Optional
+import logging
+import copy
+
+from requests.auth import HTTPBasicAuth
+
+logging.basicConfig(level="WARN")
+logger = logging.getLogger()
+
+class ActionBotfrontMapping(Action):
+    def name(self):
+        return 'action_botfront_mapping'
+
+    async def run(
+        self,
+        output_channel: "OutputChannel",
+        nlg: "NaturalLanguageGenerator",
+        tracker: "DialogueStateTracker",
+        domain: "Domain",
+    ) -> List[Event]:
+        """Append 'utter_' to intent name and generates from that template"""
+
+        events = []
+        response_name = 'utter_' + tracker.latest_message.intent["name"]
+        events += [create_bot_utterance(m) for m in await nlg.generate(response_name, tracker, output_channel.name(),
+                   language=output_channel.language)]
+
+        return events

rasa_addons/core/policies/__init__.py

@@ -0,0 +1,2 @@
+from rasa_addons.core.policies.disambiguation import BotfrontDisambiguationPolicy
+from rasa_addons.core.policies.mapping import BotfrontMappingPolicy