Metadata-Version: 2.4
Name: ovos_adapt_parser
Version: 1.6.4a1
Summary: A text-to-intent parsing framework.
Author: Sean Fitzgerald
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/OpenVoiceOS/ovos-adapt-pipeline-plugin
Keywords: natural language processing,intent,nlp,ovos
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Topic :: Text Processing :: Linguistic
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: six>=1.10.0
Requires-Dist: ovos-plugin-manager<3.0.0,>=2.4.0a1
Requires-Dist: ovos-utils<1.0.0,>=0.3.4
Requires-Dist: ovos_bus_client<3.0.0,>=2.5.1a1
Requires-Dist: ovos-spec-tools>=1.4.0a1
Requires-Dist: langcodes
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Requires-Dist: ovos-bus-client>=2.5.1a1; extra == "test"
Requires-Dist: ovos-spec-tools>=1.4.0a1; extra == "test"
Requires-Dist: ovos-workshop==9.0.0a1; extra == "test"
Dynamic: license-file

[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE.md)

# 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](https://github.com/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](docs/pipelines.md) for when to use each.

## Install

```bash
pip install ovos-adapt-parser
```

## Usage

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

```python
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/`](examples) folder.

## Documentation

A full guide, from first concepts to internals, lives in [`docs/`](docs/index.md):

- [Concepts](docs/concepts.md), entities, intents, cliques, and confidence
- [Quickstart](docs/quickstart.md), install, enable, match your first utterance
- [Writing intents](docs/writing-intents.md), the `IntentBuilder` API with examples
- [Configuration](docs/configuration.md), confidence tiers and every config key
- [Pipeline variants](docs/pipelines.md), the flat, domain, and hierarchical plugins
- [Bus protocol](docs/bus-protocol.md), the messagebus API skills register over
- [Internals](docs/internals.md), tagging, clique expansion, and the confidence math
- [Engine comparison reference](docs/benchmark.md), how the variants diverge

## Related projects

- [OpenVoiceOS/ovos-plugin-manager](https://github.com/OpenVoiceOS/ovos-plugin-manager), discovers and loads this plugin by its OPM entry point.
- [OpenVoiceOS/ovos-padatious-pipeline-plugin](https://github.com/OpenVoiceOS/ovos-padatious-pipeline-plugin), a model-based intent matcher that runs alongside Adapt in the same pipeline.
- [OpenVoiceOS/ovos-workshop](https://github.com/OpenVoiceOS/ovos-workshop), the skill framework that registers vocabulary and intents with this plugin.
- [MycroftAI/adapt](https://github.com/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:

```python
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](LICENSE.md).
