Adapt Intent Parser

Adapt is a keyword and rule based intent parser. It reads an utterance and matches it to a registered intent, then extracts the entity values the intent needs. This repository provides an OVOS pipeline plugin and bundles a maintained fork of the original MycroftAI/adapt parser, from the now-defunct MycroftAI.

Three OPM pipeline entry points are exposed:

• ovos-adapt-pipeline-plugin (AdaptPipeline), the flat pipeline. It wraps a single IntentDeterminationEngine and all skills share one trie.
• ovos-adapt-domain-pipeline-plugin (DomainAdaptPipeline), a per-skill pipeline. It wraps DomainIntentDeterminationEngine. Each skill_id gets its own sub-engine ("domain"). At match time every domain is scored in parallel and the global argmax wins. Configure it under intents.ovos_adapt_domain_pipeline.
• ovos-adapt-hierarchical-pipeline-plugin (HierarchicalAdaptPipeline), the same per-skill domain model, with two-stage routing. A stage-1 classifier picks one domain, then only that domain's sub-engine is scored. Configure it under intents.ovos_adapt_hierarchical_pipeline.

See Pipeline variants for when to use each.

Install

pip install ovos-adapt-parser

Usage

The adapt parser also works standalone, with no OVOS and no messagebus:

from ovos_adapt.intent import IntentBuilder
from ovos_adapt.engine import IntentDeterminationEngine

engine = IntentDeterminationEngine()

# register vocabulary: surface forms grouped by entity type
for word in ["weather", "forecast"]:
    engine.register_entity(word, "WeatherKeyword")
for city in ["Seattle", "San Francisco", "Tokyo"]:
    engine.register_entity(city, "Location")

# build an intent over those entity types
weather = IntentBuilder("WeatherIntent") \
    .require("WeatherKeyword") \
    .require("Location") \
    .build()
engine.register_intent_parser(weather)

# match
for intent in engine.determine_intent("what is the forecast in Tokyo"):
    if intent.get("confidence", 0) > 0:
        print(intent)

In a full OVOS install the plugin runs as a pipeline stage instead. Skills register vocabulary and intents over the messagebus, and the plugin matches incoming utterances automatically. More runnable examples ship in the examples/ folder.

Documentation

A full guide, from first concepts to internals, lives in docs/:

• Concepts, entities, intents, cliques, and confidence
• Quickstart, install, enable, match your first utterance
• Writing intents, the IntentBuilder API with examples
• Configuration, confidence tiers and every config key
• Pipeline variants, the flat, domain, and hierarchical plugins
• Bus protocol, the messagebus API skills register over
• Internals, tagging, clique expansion, and the confidence math
• Engine comparison reference, how the variants diverge

Related projects

• OpenVoiceOS/ovos-plugin-manager, discovers and loads this plugin by its OPM entry point.
• OpenVoiceOS/ovos-padatious-pipeline-plugin, a model-based intent matcher that runs alongside Adapt in the same pipeline.
• OpenVoiceOS/ovos-workshop, the skill framework that registers vocabulary and intents with this plugin.
• MycroftAI/adapt, the original parser this plugin's engine is forked from.

Reporting issues

Adapt is difficult to debug without full context. Include a serialized copy of the intent determination engine, using the debug dump utilities:

from ovos_adapt.engine import IntentDeterminationEngine

engine = IntentDeterminationEngine()
# load engine with vocabulary and parsers

import ovos_adapt.tools.debug as atd

atd.dump(engine, 'debug.ovos_adapt')

License

Apache License 2.0. See LICENSE.md.