messages

Bus carriers for the UI Worker protocol.

These dataclasses are the on-the-bus shape that UIWorker (see pipecat.workers.ui) and PipelineWorker exchange. They are NOT the on-the-wire format the client sees; that lives in pipecat.processors.frameworks.rtvi.models (UIEventMessage, UICommandMessage, UIJobGroupMessage, …). When RTVI is enabled, PipelineWorker translates between the two: its on_ui_message handler republishes inbound client messages onto the bus, and its on_bus_message handler turns outbound carriers into RTVI frames.

All carriers subclass BusUIDataMessage, which PipelineWorker dispatches on to translate outbound ones into RTVI frames.

  • BusUIEventMessage and BusUICommandMessage carry client events and server commands respectively.

  • BusUIJobGroupStartedMessage, BusUIJobUpdateMessage, BusUIJobCompletedMessage, and BusUIJobGroupCompletedMessage carry the four phases of a user-facing job group’s lifecycle (see UIWorker.ui_job_group).

The carriers live in the bus layer (rather than alongside UIWorker) because both PipelineWorker (in pipecat.pipeline) and UIWorker (in pipecat.workers) reference them, and pipeline must not import from workers.

class pipecat.bus.ui.messages.BusUIDataMessage(*, source: str, target: str | None = None)[source]

Bases: BusDataMessage

Base for all UI Worker protocol bus carriers.

PipelineWorker.on_bus_message dispatches on this type to translate a worker’s outbound UI carriers into RTVI frames, so every UI bus message below subclasses it.

class pipecat.bus.ui.messages.BusUIEventMessage(event_name: str = '', payload: Any = None, *, source: str, target: str | None = None)[source]

Bases: BusUIDataMessage

A UI event sent from the client to a server-side worker.

Emitted by PipelineWorker when the client dispatches an event via PipecatClient.sendUIEvent(event, payload). UIWorker subclasses dispatch these to @ui_event(name) handlers.

Parameters:

  • event_name – App-defined event name.

  • payload – App-defined payload. Schemaless by design.

event_name: str = ''
payload: Any = None
class pipecat.bus.ui.messages.BusUICommandMessage(command_name: str = '', payload: Any = None, *, source: str, target: str | None = None)[source]

Bases: BusUIDataMessage

A UI command sent from a server-side worker to the client.

Published by UIWorker.send_command(name, payload). PipelineWorker (in on_bus_message) translates this to an RTVIUICommandFrame(command=command_name, payload=payload) and pushes it through the pipeline.

Parameters:

  • command_name – App-defined command name.

  • payload – App-defined payload (already a plain dict by the time it lands on the bus).

command_name: str = ''
payload: Any = None
class pipecat.bus.ui.messages.BusUIJobGroupStartedMessage(job_id: str = '', workers: list[str] | None = None, label: str | None = None, cancellable: bool = True, at: int = 0, *, source: str, target: str | None = None)[source]

Bases: BusUIDataMessage

A user-facing job group has been dispatched.

Published by UIWorker.ui_job_group(...) on entry. PipelineWorker forwards it to the client as a ui-job-group envelope with kind = "group_started".

Parameters:

  • job_id – Shared job-group identifier for the group.

  • workers – Names of the workers the work was dispatched to.

  • label – Optional human-readable label for the group.

  • cancellable – Whether the client may request cancellation.

  • at – Epoch milliseconds when the group started.

job_id: str = ''
workers: list[str] | None = None
label: str | None = None
cancellable: bool = True
at: int = 0
class pipecat.bus.ui.messages.BusUIJobUpdateMessage(job_id: str = '', worker_name: str = '', data: Any = None, at: int = 0, *, source: str, target: str | None = None)[source]

Bases: BusUIDataMessage

Per-worker progress for a user-facing job group.

Forwarded by the UIWorker whenever a worker emits a BusJobUpdateMessage whose job_id matches a registered user job group. PipelineWorker forwards to the client as a ui-job-group envelope with kind = "job_update".

Parameters:

  • job_id – The shared job-group identifier.

  • worker_name – The worker that produced the update.

  • data – The worker’s update payload, forwarded verbatim.

  • at – Epoch milliseconds when the update was emitted on the bus.

job_id: str = ''
worker_name: str = ''
data: Any = None
at: int = 0
class pipecat.bus.ui.messages.BusUIJobCompletedMessage(job_id: str = '', worker_name: str = '', status: str = '', response: Any = None, at: int = 0, *, source: str, target: str | None = None)[source]

Bases: BusUIDataMessage

A worker in a user-facing job group has completed.

Forwarded by the UIWorker whenever a worker’s BusJobResponseMessage arrives for a registered user job group. PipelineWorker forwards to the client as a ui-job-group envelope with kind = "job_completed".

Parameters:

  • job_id – The shared job-group identifier.

  • worker_name – The worker that produced the response.

  • status – Completion status as a string (JobStatus value).

  • response – The worker’s response payload.

  • at – Epoch milliseconds when the response was received.

job_id: str = ''
worker_name: str = ''
status: str = ''
response: Any = None
at: int = 0
class pipecat.bus.ui.messages.BusUIJobGroupCompletedMessage(job_id: str = '', at: int = 0, *, source: str, target: str | None = None)[source]

Bases: BusUIDataMessage

A user-facing job group has completed.

Published when UIWorker.ui_job_group(...) exits, after every worker has responded (or the group has been cancelled). PipelineWorker forwards to the client as a ui-job-group envelope with kind = "group_completed".

Parameters:

  • job_id – The shared job-group identifier.

  • at – Epoch milliseconds when the group completed.

job_id: str = ''
at: int = 0