Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

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.

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

Metadata

Release files for nebulento 0.10.6a1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for nebulento 0.10.6a1
File Size Uploaded Provenance Actions
nebulento-0.10.6a1.tar.gz 103.0 kB Without provenance Details for nebulento-0.10.6a1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for nebulento 0.10.6a1
File Interpreter ABI Platform Actions
nebulento-0.10.6a1-py3-none-any.whl Python 3 none any Details for nebulento-0.10.6a1-py3-none-any.whl

Total release size: 195.0 kB

Release files / nebulento-0.10.6a1.tar.gz

Download URL nebulento-0.10.6a1.tar.gz
Size 103.0 kB
Tags Source
SHA-256 checksum
How to use checksums
0c2cc40054cbc961d942b52770cda02c839aa2e23e3a5713057b60991c487301
BLAKE2b-256 checksum
How to use checksums
bf706ebd41739c300e44d3bdb845ef7c58d54c5f783b3cf9fb800e71ff77568f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.14

Release files / nebulento-0.10.6a1-py3-none-any.whl

Download URL nebulento-0.10.6a1-py3-none-any.whl
Size 92.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
0377238ba1a98e8687077598626ec1e0d1fb9a7caf0ba0f3a243f059319fecef
BLAKE2b-256 checksum
How to use checksums
dee015d1db45f854fbedf4860009ecaf007a61dd5cbb829c543a1b9687a66cf2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.14

Security for nebulento 0.10.6a1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page