palavreado

Keyword-based intent parser for OVOS voice assistants — the drop-in replacement for Adapt.

Palavreado matches natural-language utterances against named intents built from required and optional keyword slots. Each slot holds a list of vocabulary words; if the right words are present in the utterance, the intent fires. Optional regex and simplematch autoregex patterns enable entity extraction.

---

Install

pip install palavreado

For the OVOS pipeline plugin:

pip install "palavreado[ovos]"

---

Quick start

from palavreado import IntentContainer, IntentCreator

container = IntentContainer()

intent = (
    IntentCreator("lights_off")
    .require("off",   ["off", "disable", "shutdown"])
    .require("light", ["light", "lights", "lamp"])
)
container.add_intent(intent)

result = container.calc_intent("turn off the lights")
print(result["name"])      # lights_off
print(result["conf"])      # 0.9438
print(result["keywords"])  # {'off': ['off'], 'light': ['light']}
print(result["utterance_remainder"])  # 'turn the'

An intent only fires when every required slot has at least one keyword match in the utterance.

Optional slots

intent = (
    IntentCreator("lights_off")
    .require("off",   ["off", "disable"])
    .require("light", ["light", "lights"])
    .optionally("room", ["kitchen", "bedroom", "bathroom"])
)
container.add_intent(intent)

result = container.calc_intent("turn off the bedroom lights")
print(result["keywords"]["room"])  # ['bedroom']

Autoregex / entity extraction

intent = (
    IntentCreator("buy")
    .require_autoregex("item", ["buy {item}", "purchase {item}", "get {item}"])
)
container.add_intent(intent)

result = container.calc_intent("buy some milk")
print(result["keywords"]["item"])  # ['some milk']

---

OVOS pipeline plugin

Palavreado ships an OVOS pipeline plugin that replaces Adapt as the keyword intent engine. It responds to the same bus events (register_vocab, register_intent, detach_intent, detach_skill) so existing skills need no changes.

Configure in mycroft.conf:

{
  "intents": {
    "palavreado": {
      "conf_high": 0.65,
      "conf_med":  0.45,
      "conf_low":  0.25
    }
  }
}

Entry point: palavreado.opm:PalavreadoPipeline

---

Documentation

Page	Description
Quickstart	5-minute guide: keyword intents, optional slots, autoregex
Intent API	Full IntentCreator and IntentContainer reference
Confidence Scoring	How scores are calculated: formula, penalties, bonuses
Normalisation	Apostrophe handling, whitespace, plural/singular lemmatizer
Context Gating	Require / exclude contexts, worked examples
OVOS Pipeline Plugin	Bus events, confidence tiers, migration from Adapt
Configuration	All config keys with types, defaults, and effect
Benchmark	Accuracy results and how to reproduce them
Troubleshooting	Common issues and fixes

---

Benchmark

Evaluated on a keyword-intent dataset of 284 cases (217 match utterances across 22 intents, 67 no-match utterances).

Engine	Accuracy	Precision	Recall	F1	TN / no-match	FP	Median latency
palavreado	81.7%	80.6%	94.0%	0.868	28 / 67	49	0.58 ms
adapt	80.3%	81.0%	90.3%	0.854	32 / 67	46	0.20 ms

python benchmark/compare.py

---

Credits

Originally an experimental research project by TigreGoticoLda, polished and donated to OpenVoiceOS as part of the NLnet NGI0 Commons Fund under grant agreement No 101135429.

---

License

Apache 2.0