ovos-spec-tools exists for one reason: to be the reference
implementation of the OVOS formal specifications. Every public symbol in
the package implements a specific clause of a specific spec — there is no
"general-purpose" code here. This page is the proof: every name exported
from ovos_spec_tools, mapped to its authoritative spec section.
The specs live in the
OpenVoiceOS/architecture
repository. Section numbers (§N) refer to the spec named in the same row.
Where a symbol is a shared primitive used across several spec clauses, the
"primary" owning clause is cited and the dependents are noted.
The bus domain (message.py, messages.py) is the most heavily
spec-annotated; its module and per-symbol docstrings cite OVOS-MSG-1 inline.
See Bus messages and Bus namespaces for
the prose.
| Symbol | Spec | § |
|---|---|---|
Message |
OVOS-MSG-1 | §2 (envelope) |
Message.msg_type / .data / .context |
OVOS-MSG-1 | §2.1 / §2.2 / §2.3 |
Message.__init__ (type checks) |
OVOS-MSG-1 | §2.1–§2.3, §7 |
Message.forward |
OVOS-MSG-1 | §5.1 |
Message.reply |
OVOS-MSG-1 | §5.2 |
Message.response |
OVOS-MSG-1 | §5.3 |
Message.serialize |
OVOS-MSG-1 | §6 |
Message.deserialize |
OVOS-MSG-1 | §6, §7 |
Message.as_dict |
OVOS-MSG-1 | §2, §6 |
MalformedMessage |
OVOS-MSG-1 | §2, §6, §7 (consumer "MUST reject") |
DEFAULT_SESSION_ID |
OVOS-MSG-1 | §4.1 (reserved "default") |
RoutingValue (type alias) |
OVOS-MSG-1 | §3 / §3.3 (routing key shape) |
The routing keys (context.source / context.destination, §3) and the
session carrier (context.session, §4) are carried by Message but their
inner semantics are owned elsewhere: §3 by MSG-1 itself (opaque), §4's
inner shape by OVOS-SESSION-1.
SpecMessage members each name a topic owned by another spec; the bridge
(MIGRATION_MAP / NamespaceTranslator) is the cross-cutting machinery that
moves the bus onto those topics.
| Symbol | Spec | § |
|---|---|---|
SpecMessage.UTTERANCE |
OVOS-PIPELINE-1 | §9.1 |
SpecMessage.SPEAK |
OVOS-PIPELINE-1 | §9.6 |
SpecMessage.UTTERANCE_HANDLED |
OVOS-PIPELINE-1 | §9.5 |
SpecMessage.UTTERANCE_CANCELLED |
OVOS-TRANSFORM-1 | §8.2 (defined here; PIPELINE-1 §6.4 references it) |
SpecMessage.INTENT_MATCHED |
OVOS-PIPELINE-1 | §9.2 |
SpecMessage.INTENT_UNMATCHED |
OVOS-PIPELINE-1 | §9.3 |
SpecMessage.INTENT_HANDLER_START / _COMPLETE / _ERROR |
OVOS-PIPELINE-1 | §8.1 |
SpecMessage.INTENT_REGISTER_KEYWORD |
OVOS-INTENT-4 | §5 |
SpecMessage.INTENT_REGISTER_TEMPLATE |
OVOS-INTENT-4 | §6 |
SpecMessage.ENTITY_REGISTER |
OVOS-INTENT-4 | §7 |
SpecMessage.INTENT_DEREGISTER |
OVOS-INTENT-4 | §8.2 |
SpecMessage.ENTITY_DEREGISTER |
OVOS-INTENT-4 | §8.3 |
SpecMessage.SKILL_DEREGISTER |
OVOS-INTENT-4 | §8.4 |
SpecMessage.INTENT_ENABLE / INTENT_DISABLE |
OVOS-INTENT-4 | §8.5 |
SpecMessage.INTENT_LIST / _LIST_RESPONSE |
OVOS-INTENT-4 | §10.1 |
SpecMessage.INTENT_DESCRIBE / _DESCRIBE_RESPONSE |
OVOS-INTENT-4 | §10.2 |
SpecMessage.STOP_PING / STOP_PONG |
OVOS-STOP-1 | §4.2 |
SpecMessage.STOP |
OVOS-STOP-1 | §5.3 |
SpecMessage.LISTENER_RECORD_STARTED / _RECORD_ENDED / LISTENER_SLEEP / LISTENER_AWOKEN |
OVOS-AUDIO-IN-1 | §6.1 / §6.2 / §6.3 / §6.4 |
SpecMessage.SPEAK_B64 |
OVOS-AUDIO-1 | §3.4 |
SpecMessage.AUDIO_SPEECH |
OVOS-AUDIO-1 | §4.3 |
SpecMessage.AUDIO_QUEUE / AUDIO_PLAY_SOUND |
OVOS-AUDIO-1 | §4.1 / §4.2 |
SpecMessage.AUDIO_STOP |
OVOS-AUDIO-1 | §6 |
SpecMessage.AUDIO_IS_SPEAKING |
OVOS-AUDIO-1 | §5.3 |
SpecMessage.AUDIO_OUTPUT_STARTED / _OUTPUT_ENDED |
OVOS-AUDIO-1 | §5.1 / §5.2 |
SpecMessage.MIC_LISTEN |
OVOS-AUDIO-1 | §4.4 |
SpecMessage.SESSION_SYNC |
OVOS-SESSION-2 | §2.7 (bus table §7) |
SpecMessage.CONVERSE_ACTIVE_LIST / _ACTIVE_LIST_RESPONSE |
OVOS-CONVERSE-1 | §6.1 |
SpecMessage.PERSONA_QUERY / _ANSWER |
OVOS-PERSONA-1 | §8.5 (§11 bus surface) |
SpecMessage.PERSONA_LIST / _LIST_RESPONSE |
OVOS-PERSONA-1 | §8.7 (§11) |
SpecMessage.PERSONA_REGISTER / _DEREGISTER |
OVOS-PERSONA-1 | §9 (§11) |
SpecMessage.PERSONA_ACTIVATED / _DISMISSED |
OVOS-PERSONA-1 | §11 |
SpecMessage.FALLBACK_REGISTER / _DEREGISTER |
OVOS-FALLBACK-1 | §3.1 / §3.2 (§9 bus surface) |
SpecMessage.COMMON_QUERY_PING / _PONG |
OVOS-COMMON-QUERY-1 | §6.1 / §6.2 (§13 bus surface) |
SpecMessage.TRANSFORMER_{AUDIO,UTTERANCE,METADATA,INTENT,DIALOG,TTS}_LIST / _LIST_RESPONSE |
OVOS-TRANSFORM-1 | §6 (six static query/response pairs) |
SpecMessage.COMMON_PLAY_{PLAY,SEARCH} |
OVOS-OCP-1 | §4.2 |
SpecMessage.COMMON_PLAY_{PAUSE,RESUME,STOP,NEXT,PREVIOUS,SEEK} |
OVOS-OCP-1 | §4.3 |
SpecMessage.COMMON_PLAY_{PLAYER,MEDIA,TRACK}_STATE |
OVOS-OCP-1 | §4.4 |
MIGRATION_MAP |
(bridge) | encodes the renames defined by PIPELINE-1 §8/§9, INTENT-4 §8, STOP-1 §4/§5, AUDIO-IN-1 |
SPEC_TO_LEGACY |
(bridge) | reverse of MIGRATION_MAP |
migration_counterpart |
(bridge) | symmetric counterpart lookup |
NamespaceTranslator |
(bridge) | dual-emit + receive-dedup; mirrors ovos-bus-client / FakeBus |
NamespaceTranslator.counterpart_topics |
(bridge) | send-side dual-emit |
NamespaceTranslator.is_migrated |
(bridge) | participation pre-check |
NamespaceTranslator.new_mirror_guard |
(bridge) | receive-side mirror-window dedup |
The bridge symbols are not owned by one numbered spec clause — they are the
mechanism that carries the bus from the legacy topic names to the ovos.*
topics the specs above define, while honouring OVOS-MSG-1 §6 (payload key
order is not significant, used in the dedup fingerprint). The two topics the
bridge deliberately does not map trace to OVOS-INTENT-4 §5 (N→1
registration consolidation) and OVOS-MSG-1 §2.1.1 (runtime-assembled
placeholder topics); see Bus namespaces.
session.py is the reference implementation of the §4 session carrier's
inner shape (which OVOS-MSG-1 §4 defers to OVOS-SESSION-1), plus the
handler-list helpers that PIPELINE-1 and CONVERSE-1 keep in the session.
| Symbol | Spec | § |
|---|---|---|
Session |
OVOS-SESSION-1 | §3 (registered field set) |
SESSION1_REGISTERED_FIELDS |
OVOS-SESSION-1 | §3 |
SESSION1_OWNED_FIELDS |
OVOS-SESSION-1 | §3 (fields SESSION-1 itself owns) |
DEFAULT_CONVERSE_HANDLERS_CAP |
OVOS-CONVERSE-1 | §2.1 (handler-list cap) |
MalformedSession |
OVOS-SESSION-1 | §3 (malformed wire shape) |
(session.py is owned by an in-flight PR; the citations above describe the
symbols it exports as imported by the package __init__.)
| Symbol | Spec | § |
|---|---|---|
expand |
OVOS-INTENT-1 | §3 (grammar), §3.7 (inline vocab), §4 (sample set) |
inline_keywords |
OVOS-INTENT-1 | §3.7 (<name> inline vocabulary references) |
MalformedTemplate |
OVOS-INTENT-1 | §3.6 (malformed templates) |
| Symbol | Spec | § |
|---|---|---|
LocaleResources |
OVOS-INTENT-2 | §2 (layout / override precedence), §4 (six roles) |
read_resource_file |
OVOS-INTENT-2 | §3 (common reader) |
read_prompt_file |
OVOS-INTENT-2 | §3, §4.4 (.prompt whole-file read) |
iter_locale_dirs |
OVOS-INTENT-2 | §2 (locale layout) + §2.2 distance fallback |
find_lang_dir |
OVOS-INTENT-2 | §2.2 (closest-language directory resolution) |
keyword_form |
OVOS-INTENT-2 | §4.3 (slot-free template grouping) |
normalize_for_match |
OVOS-INTENT-2 | §4.3 (match-comparison normalization) |
utterance_contains |
OVOS-INTENT-2 | §4.3 (vocabulary / keyword match) |
strip_samples |
OVOS-INTENT-2 | §4.3 (keyword removal) |
MalformedResource |
OVOS-INTENT-2 | §3, §4 (malformed file / layout) |
| Symbol | Spec | § |
|---|---|---|
render |
OVOS-INTENT-2 | §4.2 (select + fill a .dialog phrase) |
DialogRenderer |
OVOS-INTENT-2 | §4.2 (stateful, multilingual renderer) |
UnfilledSlot |
OVOS-INTENT-2 | §4.2 (a chosen phrase has an unfilled slot) |
verify_slot_consistency |
OVOS-INTENT-1 | §7 + §5.5 (Dialog renderer MUST verify all phrases declare the same slot set) |
| Symbol | Spec | § |
|---|---|---|
render_prompt |
OVOS-INTENT-2 | §4.4 (conservative {name} substitution) |
PromptRenderer |
OVOS-INTENT-2 | §4.4 (stateful, multilingual prompt renderer) |
language.py is the single implementation of "closest available language",
the smart-fallback logic OVOS-INTENT-2 §2.2 relies on for resource
resolution (and which TTS/STT plugins reuse).
| Symbol | Spec | § |
|---|---|---|
standardize_lang |
OVOS-INTENT-2 | §2.2 (BCP-47 tag normalization) |
lang_distance |
OVOS-INTENT-2 | §2.2 (regional-match distance, <10 usable) |
lang_matches |
OVOS-INTENT-2 | §2.2 (match predicate) |
closest_lang |
OVOS-INTENT-2 | §2.2 (closest-match resolution) |
lint.py validates resource syntax (INTENT-1) and naming/layout
(INTENT-2); the --spec-version switch flags features newer than a target
spec version.
| Symbol | Spec | § |
|---|---|---|
lint_locale |
OVOS-INTENT-1 + OVOS-INTENT-2 | INTENT-1 §3 (syntax) + INTENT-2 §2/§4 (layout/roles) |
Finding |
(tooling) | a single lint result (severity/path/message) |
ovos-spec-lint (CLI) |
(tooling) | command wrapper over lint_locale |
| Symbol | Spec | § |
|---|---|---|
__version__ |
(packaging) | installed package version string |
Every name in ovos_spec_tools.__all__ appears in a table above. The only
rows whose "spec" column is not a numbered OVOS spec clause are:
- the bridge machinery (
MIGRATION_MAP,SPEC_TO_LEGACY,migration_counterpart,NamespaceTranslatorand its methods) — these carry the bus onto spec topics rather than implementing one clause, and each entry/mapping is itself traced to the spec rename it encodes; - tooling/packaging surface (
Finding, theovos-spec-lintcommand,__version__).
Everything else is a direct reference implementation of a cited OVOS-MSG-1, OVOS-SESSION-1, OVOS-SESSION-2, OVOS-INTENT-1, OVOS-INTENT-2, OVOS-INTENT-4, OVOS-PIPELINE-1, OVOS-STOP-1, OVOS-AUDIO-IN-1, OVOS-AUDIO-1, OVOS-CONVERSE-1, OVOS-PERSONA-1, OVOS-FALLBACK-1, OVOS-COMMON-QUERY-1, OVOS-TRANSFORM-1, or OVOS-OCP-1 clause.
SpecMessage is the static ovos.* topic vocabulary: it carries one member
per spec-defined fixed-string topic and deliberately omits runtime-templated
topics (MSG-1 §2.1.1 — the <skill_id>:…, <pipeline_id>…, per-skill ping
placeholders) and topics used by ovos-bus-client that no spec defines
(ovos.session.update_default, ovos.session.start, ovos.context.set).