From 41773a039aab72dcab4092cff0cb29413f36081b Mon Sep 17 00:00:00 2001
From: Steve Penrod <steve.penrod@mycroft.ai>
Date: Thu, 21 Mar 2019 17:16:07 -0500
Subject: [PATCH] Adjust and document Padatious loose fallback priority

The loose (conf > 0.5) Padatious match was previously occurring as Fallback
priority 99. The AIML fallback at priority 90 would consume lots of
utterances, interferring with many skills.  Now Padatious runs at priority
89.

Additionally, added documentation of the intent and fallback system, including
guidelines for priorities.
---
 mycroft/skills/core.py              | 24 ++++++++++++++++++++----
 mycroft/skills/intent_service.py    | 10 +++++++---
 mycroft/skills/padatious_service.py |  9 +++++++--
 3 files changed, 34 insertions(+), 9 deletions(-)

diff --git a/mycroft/skills/core.py b/mycroft/skills/core.py
index f62f781e6c..0190d8e45e 100644
--- a/mycroft/skills/core.py
+++ b/mycroft/skills/core.py
@@ -1637,10 +1637,26 @@ class MycroftSkill:
 #######################################################################
 class FallbackSkill(MycroftSkill):
     """
-        FallbackSkill is used to declare a fallback to be called when
-        no skill is matching an intent. The fallbackSkill implements a
-        number of fallback handlers to be called in an order determined
-        by their priority.
+        Fallbacks come into play when no skill matches an Adapt or closely with
+        a Padatious intent.  All Fallback skills work together to give them a
+        view of the user's utterance.  Fallback handlers are called in an order
+        determined the priority provided when the the handler is registered.
+
+        Priority   Who?            Purpose
+        --------  --------    ------------------------------------------------
+           1-4    RESERVED    Unused for now, slot for pre-Padatious if needed
+             5    MYCROFT     Padatious near match (conf > 0.8)
+          6-88    USER        General
+            89    MYCROFT     Padatious loose match (conf > 0.5)
+         90-99    USER        Uncaught intents
+           100+   MYCROFT     Fallback Unknown or other future use
+
+        Handlers with the numerically lowest priority are invoked first.
+        Multiple fallbacks can exist at the same priority, but no order is
+        guaranteed.
+
+        A Fallback can either observe or consume an utterance. A consumed
+        utterance will not be see by any other Fallback handlers.
     """
     fallback_handlers = {}
 
diff --git a/mycroft/skills/intent_service.py b/mycroft/skills/intent_service.py
index 649f339b7c..6be7f9b24d 100644
--- a/mycroft/skills/intent_service.py
+++ b/mycroft/skills/intent_service.py
@@ -299,9 +299,13 @@ class IntentService:
 
         Utterances then work through this sequence to be handled:
         1) Active skills attempt to handle using converse()
-        2) Adapt intent handlers
-        3) Padatious intent handlers
-        4) Other fallbacks
+        2) Padatious high match intents (conf > 0.95)
+        3) Adapt intent handlers
+        5) Fallbacks:
+           - Padatious near match intents (conf > 0.8)
+           - General fallbacks
+           - Padatious loose match intents (conf > 0.5)
+           - Unknown intent handler
 
         Args:
             message (Message): The messagebus data
diff --git a/mycroft/skills/padatious_service.py b/mycroft/skills/padatious_service.py
index fe54544c0e..2e4855545d 100644
--- a/mycroft/skills/padatious_service.py
+++ b/mycroft/skills/padatious_service.py
@@ -28,6 +28,9 @@ from mycroft.util.log import LOG
 class PadatiousService(FallbackSkill):
     instance = None
 
+    fallback_tight_match = 5   # Fallback priority for the conf > 0.8 match
+    fallback_loose_match = 89  # Fallback priority for the conf > 0.5 match
+
     def __init__(self, bus, service):
         FallbackSkill.__init__(self)
         if not PadatiousService.instance:
@@ -58,10 +61,12 @@ class PadatiousService(FallbackSkill):
         self.bus.on('mycroft.skills.initialized', self.train)
 
         # Call Padatious an an early fallback, looking for a high match intent
-        self.register_fallback(self.handle_fallback, 5)
+        self.register_fallback(self.handle_fallback,
+                               PadatiousService.fallback_tight_match)
 
         # Try loose Padatious intent match before going to fallback-unknown
-        self.register_fallback(self.handle_fallback_last_chance, 99)
+        self.register_fallback(self.handle_fallback_last_chance,
+                               PadatiousService.fallback_loose_match)
 
         self.finished_training_event = Event()
         self.finished_initial_train = False