Merge pull request #2059 from MycroftAI/feature/padatious-priority

Adjust and document Padatious loose fallback priority

mycroft/skills/core.py

@@ -1637,10 +1637,26 @@ def cancel_all_repeating_events(self):
 #######################################################################
 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 = {}
 

mycroft/skills/intent_service.py

@@ -301,9 +301,13 @@ def handle_utterance(self, message):
 
         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

mycroft/skills/padatious_service.py

@@ -28,6 +28,9 @@
 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 @@ def __init__(self, bus, service):
         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