https://github.com/openvoiceos/ovos-spec-tools
Reference implementation of the OVOS formal specifications — sentence template expander, locale resource loader, dialog renderer, language matching, and a locale linter
https://github.com/openvoiceos/ovos-spec-tools
i18n intent-parser linter nlu openvoiceos ovos python voice-assistant
Last synced: 19 days ago
JSON representation
Reference implementation of the OVOS formal specifications — sentence template expander, locale resource loader, dialog renderer, language matching, and a locale linter
- Host: GitHub
- URL: https://github.com/openvoiceos/ovos-spec-tools
- Owner: OpenVoiceOS
- License: apache-2.0
- Created: 2026-05-22T10:53:04.000Z (about 2 months ago)
- Default Branch: dev
- Last Pushed: 2026-06-25T16:42:55.000Z (20 days ago)
- Last Synced: 2026-06-25T18:21:17.167Z (20 days ago)
- Topics: i18n, intent-parser, linter, nlu, openvoiceos, ovos, python, voice-assistant
- Language: Python
- Size: 277 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 15
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.md
Awesome Lists containing this project
README
# ovos-spec-tools
Reference implementation of the OVOS [formal
specifications](https://github.com/OpenVoiceOS/architecture) — the
low-level, dependency-light primitives those specifications describe.
OVOS components reimplement template expansion, resource loading, and language
matching in several places, and the copies drift. This package is the single
conformant implementation those components — and any third-party tool — can
depend on.
## Status
| Tool | Spec | Code |
|------|------|-------|
| Sentence template expander | OVOS-INTENT-1 v2 | `expansion.py` |
| Locale resource loader | OVOS-INTENT-2 | `resources.py` |
| Dialog renderer | OVOS-INTENT-2 §4.2 | `dialog.py` |
| Prompt renderer | OVOS-INTENT-2 §4.4 | `prompt.py` |
| Language-tag matching | OVOS-INTENT-2 §2.2 | `language.py` |
| Bus message envelope | OVOS-MSG-1 | `message.py` |
| `ovos-spec-lint` locale linter | OVOS-INTENT-1 / -2 | `lint.py` |
## Install
```bash
pip install ovos-spec-tools # core — no dependencies
pip install ovos-spec-tools[langcodes] # adds the smart language fallback
```
Requires Python 3.10+.
## Quick taste
```python
from ovos_spec_tools import (expand, LocaleResources, render, render_prompt,
closest_lang, Message)
expand("(turn|switch) [the] light") # all 4 sentences it denotes
res = LocaleResources("my-skill/locale")
res.load_intent("play", "en-US") # a skill's intent samples
render(res.load_dialog("weather", "en-US"), # a spoken response
slots={"temperature": 21})
render_prompt(res.load_prompt("system", "en-US"), # a language-model prompt
slots={"query": "what time is it"})
closest_lang("en-AU", ["pt-BR", "en-US"]) # 'en-US'
# OVOS-MSG-1 envelope: a bus message and its 'send back to the asker' reply
m = Message("ovos.intent.list", {}, {"source": "skill.id"})
res = m.response({"intents": ["..."]}) # 'ovos.intent.list.response'
res.serialize() # single UTF-8 JSON object
```
```bash
ovos-spec-lint my-skill/locale # validate a locale folder
```
## Documentation
A zero-to-hero guide lives in [`docs/`](docs/README.md):
1. [Getting started](docs/getting-started.md) — install, and a first taste of
every tool.
2. [Sentence templates](docs/templates.md) — the grammar: alternatives,
optionals, slots, vocabulary references, malformed forms.
3. [Locale resources](docs/locale-resources.md) — the `locale/` folder, the
six file roles, loading across languages, override precedence.
4. [Dialog](docs/dialog.md) — choosing and filling a spoken response, and
rendering language-model prompts.
5. [Language matching](docs/language-matching.md) — tag standardization,
distance, and closest-match resolution.
6. [Bus messages](docs/message.md) — the on-the-wire envelope, the
`forward` / `reply` / `response` derivations, and the session carrier.
7. [Linting](docs/linting.md) — validating a locale folder, on the CLI or in CI.
7. [API reference](docs/api-reference.md) — every public name, in brief.
Runnable example scripts are in [`examples/`](examples/README.md).
---
## Credits
Developed by [TigreGótico](https://tigregotico.pt) for
[OpenVoiceOS](https://openvoiceos.org).
[](https://nlnet.nl/project/OpenVoiceOS)
This project was funded through the [NGI0 Commons Fund](https://nlnet.nl/commonsfund),
a fund established by [NLnet](https://nlnet.nl) with financial support from the
European Commission's [Next Generation Internet](https://ngi.eu) programme, under
the aegis of [DG Communications Networks, Content and Technology](https://commission.europa.eu/about-european-commission/departments-and-executive-agencies/communications-networks-content-and-technology_en)
under grant agreement No [101135429](https://cordis.europa.eu/project/id/101135429).
---
## License
Apache 2.0