ovos-spec-tools

Reference implementation of the OVOS formal specifications, 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`

Tool	Spec	Code
Language-tag matching	OVOS-INTENT-2 §2.2	`language.py`
Bus message envelope	OVOS-MSG-1	`message.py`
Intent dispatch topics	OVOS-MSG-1 §2.1.1 / OVOS-INTENT-4	`intent_topics.py`
`ovos-spec-lint` locale linter	OVOS-INTENT-1 / -2	`lint.py`

Install

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

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

ovos-spec-lint my-skill/locale               # validate a locale folder

Documentation

A zero-to-hero guide lives in docs/:

Getting started, install, and a first taste of every tool.
Sentence templates, the grammar: alternatives, optionals, slots, vocabulary references, malformed forms.
Locale resources, the locale/ folder, the six file roles, loading across languages, override precedence.
Dialog, choosing and filling a spoken response, and rendering language-model prompts.
Language matching, tag standardization, distance, and closest-match resolution.
Bus messages, the on-the-wire envelope, the forward / reply / response derivations, and the session carrier.
Linting, validating a locale folder, on the CLI or in CI.
API reference, every public name, in brief.

Runnable example scripts are in examples/.

See docs/prerelease-quirks.md for what changed since the last stable release (there has not been one yet, so it covers everything since the first alpha).

Credits

Developed by TigreGótico for OpenVoiceOS.

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

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ovos_spec_tools-1.7.0a3.tar.gz (130.7 kB view details)

Uploaded Aug 14, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

ovos_spec_tools-1.7.0a3-py3-none-any.whl (94.8 kB view details)

Uploaded Aug 14, 2026 Python 3

File details

Details for the file ovos_spec_tools-1.7.0a3.tar.gz.

File metadata

Download URL: ovos_spec_tools-1.7.0a3.tar.gz
Upload date: Aug 14, 2026
Size: 130.7 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for ovos_spec_tools-1.7.0a3.tar.gz
Algorithm	Hash digest
SHA256	`004b8984b3b77934f5e81e941e54a4d38ab47f1fb5cdd9eb3855fb8a86abc9be`
MD5	`d5146c1546d6b55c5b1e53da95bef7c0`
BLAKE2b-256	`b6fb13ae4d44b0824a7e3950917356e96d976ffbfa77e3903e90372edff3c374`

See more details on using hashes here.

File details

Details for the file ovos_spec_tools-1.7.0a3-py3-none-any.whl.

File metadata

Download URL: ovos_spec_tools-1.7.0a3-py3-none-any.whl
Upload date: Aug 14, 2026
Size: 94.8 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for ovos_spec_tools-1.7.0a3-py3-none-any.whl
Algorithm	Hash digest
SHA256	`20376ae51077daaa3427fe1d4e14fc2a5aac5c77ff5fdb35ecddfcf81d863aa7`
MD5	`b7a84a88462a8fa7931d6edd1b1c7832`
BLAKE2b-256	`542debea57302046878d578be923f385f67c906d4d788195d42122bf7f00c5bb`