ovos-pydantic-models

Typed Pydantic v2 models for every message that flows over the OVOS MessageBus.

This package is the authoritative, machine-readable specification of the OVOS MessageBus protocol. Each message type is represented as a Pydantic model with validated fields, making it suitable for type-checking, serialization, documentation generation, and integration testing.

Installation

pip install ovos-pydantic-models

Usage

from ovos_pydantic_models import SpeakMessage, SpeakData

# Create a typed message
msg = SpeakMessage(data=SpeakData(utterance="Hello, world!", lang="en-us"))
print(msg.message_type)   # "speak"
print(msg.model_dump())   # {"message_type": "speak", "data": {...}, "context": {...}}

# Roundtrip from dict (e.g. received over the bus)
raw = {"message_type": "speak", "data": {"utterance": "Hello"}, "context": {}}
restored = SpeakMessage.model_validate(raw)
print(restored.data.utterance)   # "Hello"

from ovos_pydantic_models import RecognizerLoopUtteranceMessage, RecognizerLoopUtteranceData

msg = RecognizerLoopUtteranceMessage(
    data=RecognizerLoopUtteranceData(utterances=["play some jazz"], lang="en-us")
)
print(msg.message_type)   # "recognizer_loop:utterance"

Message Index

Messages are organized by subsystem:

Audio / TTS

Listener / STT

Intent Pipeline

Skill Manager / Core

OCP (Common Play)

Common Query

GUI / Homescreen

Key Types

from ovos_pydantic_models import (
    # Base
    OpenVoiceOSMessage, MessageContext, Session,
    # Enums
    UtteranceState, ListeningState,
    MediaType, PlaybackType, PlayerState, MediaState, MatchConfidence,
    OcpMediaState,  # IntEnum 0-8 (Qt QMediaPlayer states)
    FallbackMode, ConverseMode, CQSMatchLevel,
    # Data models
    MediaEntry, Playlist, PluginStream,
)

Module Structure

ovos_pydantic_models/
  message.py          # OpenVoiceOSMessage base, MessageContext
  session.py          # Session, UtteranceState, IntentContextManager
  audio/
    playback.py       # Speak, AudioService messages
    ocp.py            # OcpMediaState (Qt IntEnum)
    opm.py            # OPM TTS query/response messages
  listener/
    recognizer_loop.py
    opm.py            # OPM STT/WW query messages
  intents/
    core.py           # context, utterance handled, intent get
    converse.py       # converse protocol (canonical)
    fallbacks.py      # fallback protocol (canonical)
    stop.py           # stop messages
  skills/
    ocp.py            # OCP enums, MediaEntry, query messages
    game.py           # game skill messages
    common_query.py   # question:query protocol
    converse.py       # re-exports from intents/converse.py
    fallback.py       # re-exports from intents/fallbacks.py
  core/
    skill_manager.py  # skill lifecycle messages
    skill_settings.py
    skill_installer.py
    session.py        # session sync messages
  gui/
    homescreen.py
  phal/
    connectivity.py
    volume.py

Related Projects

• OpenVoiceOS/ovos-messagebus: the message bus these models validate.
• OpenVoiceOS/ovos-bus-client: the untyped client library this package complements.
• OpenVoiceOS/ovos-audio: the TTS and audio playback service that produces and consumes the audio messages.
• OpenVoiceOS/ovos-dinkum-listener: the wake word and STT service that produces the listener messages.

License

Apache 2.0. See LICENSE.

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.