ovos-pydantic-models

July 31, 2026 · View on GitHub

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

Message type	Class
`speak`	`SpeakMessage`
`mycroft.audio.service.play`	`AudioServicePlayMessage`
`mycroft.audio.service.pause`	`AudioServicePauseMessage`
`mycroft.audio.service.resume`	`AudioServiceResumeMessage`

Message type	Class
`mycroft.audio.service.stop`	`AudioServiceStopMessage`
`mycroft.audio.queue`	`MycroftAudioQueueMessage`
`ovos.languages.tts`	`OvosLanguagesTtsMessage`
`ovos.languages.tts.response`	`OvosLanguagesTtsResponseMessage`

Listener / STT

Message type	Class
`recognizer_loop:utterance`	`RecognizerLoopUtteranceMessage`
`recognizer_loop:wakeword`	`RecognizerLoopWakeWordMessage`
`recognizer_loop:state.set`	`RecognizerLoopStateSetMessage`
`recognizer_loop:state.get`	`RecognizerLoopStateGetMessage`

Message type	Class
`recognizer_loop:state.get.response`	`RecognizerLoopStateResponseMessage`
`mycroft.mic.mute`	`MycroftMicMuteMessage`
`mycroft.mic.listen`	`MycroftMicListenMessage`
`ovos.languages.stt`	`OvosLanguagesSttMessage`

Message type	Class
`ovos.languages.stt.response`	`OvosLanguagesSttResponseMessage`
`opm.ww.query`	`OpmWwQueryMessage`

Intent Pipeline

Message type	Class
`ovos.utterance.handled`	`OvosUtteranceHandledMessage`
`ovos.utterance.cancelled`	`OvosUtteranceCancelledMessage`
`complete_intent_failure`	`CompleteIntentFailureMessage`
`add_context`	`AddContextMessage`

Message type	Class
`remove_context`	`RemoveContextMessage`
`clear_context`	`ClearContextMessage`
`intent.service.skills.activate`	`IntentServiceSkillsActivateMessage`
`intent.service.skills.deactivate`	`IntentServiceSkillsDeactivateMessage`

Message type	Class
`skill.converse.pong`	`SkillConversePongMessage`
`skill.converse.response`	`SkillConverseResponseMessage`
`ovos.skills.fallback.register`	`OvosSkillsFallbackRegisterMessage`
`ovos.skills.fallback.ping`	`OvosSkillsFallbackPingMessage`

Message type	Class
`ovos.skills.fallback.pong`	`OvosSkillsFallbackPongMessage`
`stop:global`	`StopGlobalMessage`
`stop:skill`	`StopSkillMessage`
`mycroft.stop`	`MycroftStopMessage`

Message type	Class
`mycroft.skills.abort_question`	`MycroftSkillsAbortQuestionMessage`
`mycroft.skills.abort_execution`	`MycroftSkillsAbortExecutionMessage`

Skill Manager / Core

Message type	Class
`mycroft.ready`	`MycroftReadyMessage`
`mycroft.skills.ready`	`MycroftSkillsReadyMessage`
`mycroft.skills.is_ready`	`MycroftSkillsIsReadyMessage`
`mycroft.skills.is_ready.response`	`MycroftSkillsIsReadyResponseMessage`

Message type	Class
`mycroft.skills.list`	`MycroftSkillsListMessage`
`skillmanager.list`	`SkillManagerListMessage`
`skillmanager.deactivate`	`SkillManagerDeactivateMessage`
`mycroft.skills.error`	`MycroftSkillsErrorMessage`

Message type	Class
`skill.settings.change`	`SkillSettingsChangeMessage`
`ovos.skills.settings_changed`	`OvosSkillsSettingsChangedMessage`
`ovos.skills.install`	`OvosSkillsInstallMessage`
`ovos.skills.install.failed`	`OvosSkillsInstallFailedMessage`

Message type	Class
`ovos.pip.install`	`OvosPipInstallMessage`
`ovos.session.sync`	`OvosSessionSyncMessage`
`ovos.session.update_default`	`OvosSessionUpdateDefaultMessage`

OCP (Common Play)

Message type	Class
`ovos.common_play.query`	`OvosCommonPlayQueryMessage`
`ovos.common_play.query.response`	`OvosCommonPlayQueryResponseMessage`
`ovos.common_play.announce`	`OvosCommonPlayAnnounceMessage`
`ovos.common_play.player.state`	`OvosCommonPlayPlayerStateMessage`

Message type	Class
`ovos.common_play.skills.detach`	`OvosCommonPlaySkillsDetachMessage`
`ovos.common_play.register_keyword`	`OvosCommonPlayRegisterKeywordMessage`
`ovos.common_play.skill.play`	`OvosCommonPlaySkillPlayMessage`

Common Query

Message type	Class
`question:query`	`QuestionQueryMessage`
`question:query.response`	`QuestionQueryResponseMessage`

GUI / Homescreen

Message type	Class
`homescreen.manager.app`	`HomescreenManagerAppMessage`

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

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.