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

Match strategies

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

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

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):

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