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

Metadata

Release files for ovos-spec-tools 1.11.0a1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ovos-spec-tools 1.11.0a1
File	Size	Uploaded
ovos_spec_tools-1.11.0a1.tar.gz	152.0 kB	Sep 6, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for ovos-spec-tools 1.11.0a1
File	Interpreter	ABI	Platform	Reset
ovos_spec_tools-1.11.0a1-py3-none-any.whl 105.8 kB Sep 6, 2026	Python 3	none	any	Details

Total release size: 257.8 kB

Release files / ovos_spec_tools-1.11.0a1.tar.gz

Download URL	ovos_spec_tools-1.11.0a1.tar.gz
Size	152.0 kB
Tags	Source
SHA-256 checksum How to use checksums	`32fb787790456ba904929b8f35638bedc1c43bb74cf95dd778ee9fab2bb7d7d7`
BLAKE2b-256 checksum How to use checksums	`cf949b7b2f5eec191adaf7740896a5041ec9b5f0096ec20dd95a10317d4bb575`
Upload date	Sep 6, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Release files / ovos_spec_tools-1.11.0a1-py3-none-any.whl

Download URL	ovos_spec_tools-1.11.0a1-py3-none-any.whl
Size	105.8 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`b1874ebbd30848f34e607d55721905454bed8bc23b8482716b684f934396e5ea`
BLAKE2b-256 checksum How to use checksums	`f503afa737b8267a25107ad578c9f85015ddb31520827138ca943c787db8d24b`
Upload date	Sep 6, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`