Metadata-Version: 2.4
Name: ovos-markov-pipeline-plugin
Version: 0.3.0a1
Summary: OVOS intent pipeline plugin using Markov chain perplexity ensemble
License: Apache-2.0
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: markovonnx>=1.0.1
Requires-Dist: ovos-plugin-manager>=0.0.1
Requires-Dist: ovos-bus-client>=0.1.0
Requires-Dist: ovos-utils>=0.1.0
Provides-Extra: stem
Requires-Dist: snowballstemmer; extra == "stem"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Requires-Dist: snowballstemmer; extra == "test"
Dynamic: license-file

# ovos-markov-pipeline-plugin

An OVOS intent pipeline plugin that classifies utterances with an ensemble of
per-intent Markov chains, scored by perplexity.

It trains one word-level Markov chain per intent from example utterances. At
query time it computes the perplexity of the utterance under every model and
picks the intent whose model is least "surprised" — lowest perplexity wins.
Confidence is derived from perplexity, so the plugin slots cleanly into the
OVOS high / medium / low confidence pipeline tiers.

## Why a Markov pipeline?

Most OVOS intent matchers either pattern-match (Adapt, padacioso) or train a
neural / SVM classifier (padatious, linha-fina). A Markov-chain language model
sits in between: it is a lightweight statistical model that learns the *word
order* of each intent's sample set, trains in milliseconds, needs no GPU, and
degrades gracefully with very few samples. It is a practical baseline for
small skill sets and a useful comparison point against the other matchers.

## Install

```bash
pip install ovos-markov-pipeline-plugin
```

Optional stemming support (recommended for non-English use):

```bash
pip install ovos-markov-pipeline-plugin[stem]
```

## Quick example

Enable the pipeline in `mycroft.conf`:

```json
{
  "intents": {
    "pipeline": [
      "ovos-markov-pipeline-plugin-high",
      "ovos-markov-pipeline-plugin-medium",
      "ovos-markov-pipeline-plugin-low"
    ]
  }
}
```

Skills register their intents over the bus exactly as they do for padatious —
no skill-side changes are required.

## Documentation

Full documentation lives in [`docs/`](docs/index.md):

- [Concepts](docs/concepts.md) — how Markov-chain perplexity matching works
- [Quickstart](docs/quickstart.md) — install, configure, run
- [Configuration](docs/configuration.md) — every config key explained
- [Pipeline integration](docs/pipeline.md) — OPM entry point and bus protocol
- [Entity extraction](docs/entities.md) — HMM BIO slot tagging
- [Calibration](docs/calibration.md) — measuring and tuning confidence
- [Model caching](docs/caching.md) — ONNX disk cache
- [Tuning](docs/tuning.md) — order, smoothing, stemming, fallbacks
- [Troubleshooting](docs/troubleshooting.md) — common issues and FAQ

## License

Apache-2.0
