Nebulento

Nebulento is a fuzzy-matching intent parser built on rapidfuzz.

Nebulento finds the closest matching intent by comparing an utterance against all training sentences with a configurable fuzzy similarity strategy. It handles spelling errors, word-order variation, contractions, and natural phrasing that exact-match parsers miss. Use it for small-to-medium intent sets: dozens to hundreds of training sentences per intent.

---

Install

pip install nebulento

For the OVOS pipeline plugin:

pip install "nebulento[ovos]"

---

Quick start

from nebulento import IntentContainer, MatchStrategy

container = IntentContainer(fuzzy_strategy=MatchStrategy.TOKEN_SET_RATIO)

container.add_intent("hello", ["hello", "hi", "how are you", "what's up"])
container.add_intent("buy", ["buy {item}", "purchase {item}", "get {item} for me"])
container.add_entity("item", ["milk", "cheese"])

container.calc_intent("hello")
# {'name': 'hello', 'conf': 1.0, 'entities': {}, 'best_match': 'hello',
#  'utterance': 'hello', 'utterance_consumed': 'hello', 'utterance_remainder': '',
#  'match_strategy': 'TOKEN_SET_RATIO'}

container.calc_intent("buy milk")
# {'name': 'buy', 'conf': 0.719, 'entities': {'item': ['milk']},
#  'best_match': 'buy {item}', ...}

Template syntax

Syntax	Meaning
(one|of|these)	Alternation. Expands to one variant per combination
[optional]	Optional word or phrase
{entity}	Capture group. Matched against registered entity samples

---

Match strategies

Choose a strategy via IntentContainer(fuzzy_strategy=MatchStrategy.X).

Strategy	Best for	FP risk
DAMERAU_LEVENSHTEIN_SIMILARITY	Spelling errors, lowest false-positive rate	Low, default
RATIO	Highest recall and F1, fast	High
TOKEN_SET_RATIO	Natural phrasing, word-order variation	High
TOKEN_SORT_RATIO	Same words, different order	High
PARTIAL_RATIO	Substring presence. Avoid for intent gating	Very high

See docs/strategies.md for the full comparison table and benchmark rows.

---

OVOS pipeline plugin

Nebulento ships as an OVOS pipeline plugin (ovos-nebulento-pipeline-plugin).

{
  "intents": {
    "pipeline": [
      "ovos-nebulento-pipeline-plugin"
    ]
  }
}

Configure the fuzzy strategy and confidence thresholds:

{
  "intents": {
    "nebulento": {
      "strategy": "TOKEN_SET_RATIO",
      "conf_high": 0.95,
      "conf_med":  0.80,
      "conf_low":  0.50
    }
  }
}

Entry point: nebulento.opm:NebulentoPipeline

---

Documentation

Page	Description
Quickstart	5-minute guide: intents, entities, strategies
Intent API	Full IntentContainer and HierarchicalIntentContainer reference
Match Strategies	All 9 strategies with benchmark data and decision table
Template Syntax	(a|b), [opt], {slot}, :0 padatious syntax, expansion rules
Entity Extraction	Registration, confidence boost, result fields
Normalisation	Apostrophes, whitespace, case handling
Hierarchical Matching	HierarchicalIntentContainer two-stage matching
OVOS Pipeline Plugin	Bus events, confidence tiers, comparison with Padatious
Configuration	All config keys with types, defaults, and effect
Benchmark	Full accuracy results across all strategies
Troubleshooting	False positives, low recall, entity issues, lru_cache gotchas

---

Benchmark

Benchmarked on two OpenVoiceOS datasets: intents-for-eval and massive. Results below are intents-for-eval (1750 utterances, 50 intents, 1700 match / 50 off-topic):

Engine	Accuracy	Precision	Recall	F1	False positives	Median
padaos (regex)	51.4%	99.9%	50.0%	0.666	1 / 50	0.39 ms
padatious (neural)	66.1%	99.7%	65.2%	0.789	3 / 50	3.6 ms
nebulento ratio	72.9%	96.9%	74.5%	0.842	40 / 50	4.0 ms
nebulento damerau-levenshtein	69.2%	98.6%	69.3%	0.814	17 / 50	10 ms

python benchmark/compare.py          # both datasets
python benchmark/compare.py massive  # one dataset

See docs/benchmark.md for both datasets, all nine strategies, and the hierarchical variant.

---

Credits

Originally an experimental research project by TigreGóticoLda, polished and donated to OpenVoiceOS. Its modernization, integration into OpenVoiceOS, and intent benchmarking were funded by the NGI0 Commons Fund.

This project was funded through the NGI0 Commons Fund, a fund established by NLnet with financial support from the European Commission's Next Generation Internet programme, under the aegis of DG Communications Networks, Content and Technology under grant agreement No 101135429.

---

License

Apache 2.0