fix: expand inline <voc> refs before registering intents to the engine

OVOS-INTENT-1 §3.7 makes an inline <name> in a .intent an authoring
convenience that MUST expand in place from the sibling vocabulary of
that name before the template reaches an intent engine. The
padatious/padacioso bus protocol carries only samples, never the .voc
content, so register_intent_file sent the raw <name> straight through
and both engines trained on the literal token — padacioso never matched
and padatious matched only by coincidence.

Add SkillResources.vocabularies() to build the {name: members} map from
the locale tree (user > skill > workshop precedence) and pass it into
register_padatious_intent, which now inlines every <name> as an (a|b|c)
group via ovos_spec_tools.inline_keywords before emitting the samples.
Files without inline references are unaffected.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: JarbasAl

ovos_workshop/intents.py

@@ -1,6 +1,6 @@
 from os.path import exists
 from threading import RLock
-from typing import List, Optional
+from typing import Dict, List, Optional
 import warnings
 from ovos_bus_client.message import Message, dig_for_message
 from ovos_bus_client.util import get_mycroft_bus
@@ -11,7 +11,7 @@
 # their long-standing `from ovos_workshop.intents import IntentBuilder` import while
 # the single source of truth is the spec. The `IntentServiceInterface` producer
 # (and the munge_* helpers) below consume these definitions.
-from ovos_spec_tools import Intent, IntentBuilder, open_intent_envelope
+from ovos_spec_tools import Intent, IntentBuilder, inline_keywords, open_intent_envelope
 
 
 def to_alnum(skill_id: str) -> str:
@@ -270,13 +270,20 @@ def remove_adapt_context(self, context: str):
         self.bus.emit(msg.forward('remove_context', {'context': context}))
 
     def register_padatious_intent(self, intent_name: str, filename: str,
-                                  lang: str, string_blacklist: Optional[List[str]] = None):
+                                  lang: str, string_blacklist: Optional[List[str]] = None,
+                                  vocabs: Optional[Dict[str, List[str]]] = None):
         """
         Register a Padatious intent file with the intent service.
         @param intent_name: Unique intent identifier
             (usually `skill_id`:`filename`)
         @param filename: Absolute file path to entity file
         @param lang: BCP-47 language code of registered intent
+        @param string_blacklist: phrases that should suppress a match
+        @param vocabs: ``{name: members}`` of the sibling vocabularies, so an
+            inline ``<name>`` reference (OVOS-INTENT-1 §3.7) is baked into the
+            samples as an ``(a|b|c)`` group before they reach the engine — the
+            padatious/padacioso bus protocol carries only samples, never the
+            ``.voc`` content, so the reference must be resolved here.
         """
         if not isinstance(filename, str):
             raise ValueError('Filename path must be a string')
@@ -285,6 +292,9 @@ def register_padatious_intent(self, intent_name: str, filename: str,
         with open(filename) as f:
             samples = [_ for _ in f.read().split("\n") if _
                        and not _.startswith("#")]
+        if vocabs:
+            # OVOS-INTENT-1 §3.7: resolve every inline <name> in place
+            samples = [inline_keywords(s, vocabs) for s in samples]
         data = {'file_name': filename,
                 "samples": samples,
                 'name': intent_name,

ovos_workshop/resource_files.py

@@ -806,6 +806,43 @@ def load_skill_vocabulary(self, alphanumeric_skill_id: str) -> dict:
 
         return skill_vocabulary
 
+    def vocabularies(self) -> Dict[str, List[str]]:
+        """Build a ``{name: members}`` map from every ``.voc`` in this
+        language's locale tree.
+
+        Feeds the inline ``<name>`` resolution required by OVOS-INTENT-1 §3.7:
+        a reference in an ``.intent`` (or ``.blacklist``) expands in place from
+        the sibling vocabulary of that name. Padatious and padacioso never read
+        ``.voc`` files at match time, so the reference must be baked into the
+        template before it reaches the engine. User overrides take precedence
+        over the skill's own resources, which take precedence over
+        workshop-shipped resources.
+        """
+        vocabularies: Dict[str, List[str]] = {}
+        vocab_type = self.types.vocabulary
+        for base in (vocab_type.user_directory,
+                     vocab_type.base_directory,
+                     vocab_type.workshop_directory):
+            if not base:
+                continue
+            for directory, _, files in walk(str(base)):
+                for file_name in files:
+                    if not file_name.endswith(".voc"):
+                        continue
+                    name = file_name[:-len(".voc")].lower()
+                    if name in vocabularies:
+                        continue
+                    members: List[str] = []
+                    with open(Path(directory, file_name)) as voc_file:
+                        for line in (ln.strip().lower() for ln in voc_file):
+                            if line and not line.startswith("#"):
+                                # a .voc line MAY hold comma/parenthesis
+                                # alternates; every phrasing is a member
+                                members.extend(flatten_list(expand_template(line)))
+                    if members:
+                        vocabularies[name] = members
+        return vocabularies
+
     def load_skill_regex(self, alphanumeric_skill_id: str) -> List[str]:
         """
         Load all regex files in the skill's resources

ovos_workshop/skills/ovos.py

@@ -1346,7 +1346,12 @@ def register_intent_file(self, intent_file: str, handler: callable,
             for enty in voc_blacklist or []:
                 disallowed_strings += self.voc_list(enty, lang=lang)
 
-            self.intent_service.register_padatious_intent(name, filename, lang, string_blacklist=disallowed_strings)
+            # OVOS-INTENT-1 §3.7: supply the sibling vocabularies so an inline
+            # <name> reference in the .intent is baked into the samples before
+            # they are sent to the engine over the bus
+            self.intent_service.register_padatious_intent(
+                name, filename, lang, string_blacklist=disallowed_strings,
+                vocabs=resources.vocabularies())
         if handler:
             self.add_event(name, handler, 'mycroft.skill.handler',
                            activation=True, is_intent=True)

test/unittests/test_inline_vocab_refs.py

@@ -0,0 +1,123 @@
+"""OVOS-INTENT-1 §3.7: an inline ``<name>`` reference in a ``.intent`` file is
+an authoring convenience that must expand in place from the sibling ``.voc`` of
+that name before the template reaches an intent engine. The padatious/padacioso
+bus protocol carries only samples — never the ``.voc`` content — so the
+reference has to be resolved during registration, otherwise the raw ``<name>``
+token is trained into the engine and the intent never matches."""
+import unittest
+from pathlib import Path
+from tempfile import TemporaryDirectory
+
+from ovos_utils.fakebus import FakeBus
+from ovos_workshop.intents import IntentServiceInterface
+from ovos_workshop.resource_files import ResourceFile, SkillResources
+
+
+class TestInlineVocabResources(unittest.TestCase):
+    def _resources(self, files):
+        tmp = TemporaryDirectory()
+        self.addCleanup(tmp.cleanup)
+        locale = Path(tmp.name, "locale", "en-us")
+        locale.mkdir(parents=True)
+        for name, content in files.items():
+            (locale / name).write_text(content)
+        return SkillResources(tmp.name, "en-us", skill_id="test.skill")
+
+    def test_vocabularies_map(self):
+        resources = self._resources({
+            "thing.voc": "widget\ngadget\n# comment\n",
+            "foo.intent": "what about <thing>\n",
+        })
+        self.assertEqual(resources.vocabularies().get("thing"),
+                         ["widget", "gadget"])
+
+    def test_vocabularies_expands_alternates(self):
+        resources = self._resources({
+            "greeting.voc": "(hello|hi)\ngood morning\n",
+        })
+        self.assertEqual(sorted(resources.vocabularies()["greeting"]),
+                         ["good morning", "hello", "hi"])
+
+
+class TestInlineVocabRegistration(unittest.TestCase):
+    """The samples emitted on the registration bus topic must already have the
+    inline ``<name>`` resolved to an ``(a|b|c)`` alternation group."""
+
+    def _capture_samples(self, files, pass_vocabs):
+        tmp = TemporaryDirectory()
+        self.addCleanup(tmp.cleanup)
+        locale = Path(tmp.name, "locale", "en-us")
+        locale.mkdir(parents=True)
+        for name, content in files.items():
+            (locale / name).write_text(content)
+        resources = SkillResources(tmp.name, "en-us", skill_id="test.skill")
+        filename = str(ResourceFile(resources.types.intent, "foo.intent").file_path)
+
+        bus = FakeBus()
+        captured = {}
+        bus.on("padatious:register_intent",
+               lambda m: captured.__setitem__("samples", m.data["samples"]))
+        iface = IntentServiceInterface(bus)
+        iface.set_id("test.skill")
+        kwargs = {"vocabs": resources.vocabularies()} if pass_vocabs else {}
+        iface.register_padatious_intent("test.skill:foo.intent", filename,
+                                        "en-us", **kwargs)
+        return captured["samples"]
+
+    def test_inline_reference_resolved_before_engine(self):
+        samples = self._capture_samples({
+            "thing.voc": "widget\ngadget\n",
+            "foo.intent": "what about <thing>\n",
+        }, pass_vocabs=True)
+        self.assertEqual(samples, ["what about (widget|gadget)"])
+
+    def test_raw_reference_without_vocabs_is_unresolved(self):
+        samples = self._capture_samples({
+            "thing.voc": "widget\ngadget\n",
+            "foo.intent": "what about <thing>\n",
+        }, pass_vocabs=False)
+        self.assertEqual(samples, ["what about <thing>"])
+
+
+class TestInlineVocabPadaciosoEndToEnd(unittest.TestCase):
+    """End-to-end proof through the real padacioso engine: a skill shipping a
+    ``foo.intent`` with ``<thing>`` and a sibling ``thing.voc`` matches an
+    utterance built from a vocabulary member."""
+
+    def _register_and_match(self, utterance, pass_vocabs):
+        from padacioso import IntentContainer
+
+        tmp = TemporaryDirectory()
+        self.addCleanup(tmp.cleanup)
+        locale = Path(tmp.name, "locale", "en-us")
+        locale.mkdir(parents=True)
+        (locale / "thing.voc").write_text("widget\ngadget\n")
+        (locale / "foo.intent").write_text("what about <thing>\n")
+        resources = SkillResources(tmp.name, "en-us", skill_id="test.skill")
+        filename = str(ResourceFile(resources.types.intent, "foo.intent").file_path)
+
+        bus = FakeBus()
+        captured = {}
+        bus.on("padatious:register_intent",
+               lambda m: captured.__setitem__("samples", m.data["samples"]))
+        iface = IntentServiceInterface(bus)
+        iface.set_id("test.skill")
+        kwargs = {"vocabs": resources.vocabularies()} if pass_vocabs else {}
+        iface.register_padatious_intent("test.skill:foo.intent", filename,
+                                        "en-us", **kwargs)
+
+        engine = IntentContainer()
+        engine.add_intent("foo", captured["samples"])
+        return engine.calc_intent(utterance)
+
+    def test_inline_voc_intent_matches(self):
+        match = self._register_and_match("what about widget", pass_vocabs=True)
+        self.assertEqual(match.get("name"), "foo")
+
+    def test_raw_reference_does_not_match(self):
+        match = self._register_and_match("what about widget", pass_vocabs=False)
+        self.assertIsNone(match.get("name"))
+
+
+if __name__ == "__main__":
+    unittest.main()