ovos-spec-tools 0.5.0a1

Reference implementation of the OVOS formal specifications

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
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

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/:

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

Runnable example scripts are in examples/.

Credits

This package was produced as part of a documentation and interoperability effort for OpenVoiceOS, funded by NLnet's NGI0 Commons Fund under grant agreement No 101135429.

License

Apache 2.0