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

License

Apache 2.0 — see LICENSE