Events & Content¶
RoomEvent ¶
Bases: BaseModel
A single event in a room conversation.
EventSource ¶
Bases: BaseModel
Origin information for an event.
verification
class-attribute
instance-attribute
¶
The sender's verification when the event was received (RFC §11.7.3); None where none applies (an unidentified sender, an agent, the framework).
EventContent
module-attribute
¶
EventContent = Annotated[TextContent | RichContent | MediaContent | LocationContent | AudioContent | VideoContent | CompositeContent | SystemContent | TemplateContent | EditContent | DeleteContent | ToolCallContent, Field(discriminator='type')]
Content Types¶
TextContent ¶
Bases: BaseModel
Plain text message content.
RichContent ¶
Bases: BaseModel
Rich formatted content (HTML/Markdown).
MediaContent ¶
Bases: BaseModel
Media attachment content.
url is a link (http, https), a data: URI, or a reference:
<scheme>://… in a scheme the application chooses, naming a media it
holds and resolves for the AI channels (RFC §6.4). A scheme a reader could
fetch or open itself (file, ftp) or run (javascript,
vbscript) is refused, and so is a reference a path reader could follow
(a one-letter scheme, a .. segment, a backslash): some transports read
a URL they are handed as a local path.
AudioContent ¶
Bases: BaseModel
Audio message content.
VideoContent ¶
Bases: BaseModel
Video message content.
LocationContent ¶
Bases: BaseModel
Geographic location content.
CompositeContent ¶
Bases: BaseModel
Multi-part content combining multiple content types.
SystemContent ¶
Bases: BaseModel
System-generated content.
TemplateContent ¶
Bases: BaseModel
Pre-approved template content (WhatsApp Business, etc.).
Framework Events¶
FrameworkEvent ¶
Bases: BaseModel
An event emitted by the framework for observability.
SessionStartedEvent
dataclass
¶
SessionStartedEvent(room_id, channel_id, channel_type, participant_id, session=None, timestamp=_utcnow())
A session has started on any channel type.
For voice channels this fires when the audio path is live and ready
to send/receive (same dual-signal timing as the former
ON_VOICE_SESSION_READY). For text-based transport channels it
fires when the inbound pipeline auto-creates a new room for a first
message.
This is the safe point to send greetings or start telemetry.
ProtocolTrace
dataclass
¶
ProtocolTrace(channel_id, direction, protocol, summary, raw=None, metadata=dict(), timestamp=(lambda: now(UTC))(), session_id=None, room_id=None)
A single protocol-level trace event emitted by a channel.
Captures raw protocol data (SIP, RTP, WebSocket, HTTP, etc.) flowing through a channel. Disabled by default; zero overhead when no observers are registered.
Attributes:
| Name | Type | Description |
|---|---|---|
channel_id |
str
|
Which channel emitted this trace. |
direction |
Literal['inbound', 'outbound']
|
Whether the message was inbound or outbound. |
protocol |
str
|
Protocol identifier (e.g. "sip", "rtp", "ws", "http"). |
summary |
str
|
Human-readable one-liner (e.g. "INVITE sip:+1555@pbx"). |
raw |
bytes | str | None
|
Full payload bytes or string (optional for high-freq traces). |
metadata |
dict[str, Any]
|
Protocol-specific extras (codec info, headers, etc.). |
timestamp |
datetime
|
When the trace was captured. |
session_id |
str | None
|
For session-scoped traces (voice sessions, etc.). |
room_id |
str | None
|
Set by emitter if known at emit time. |
RoomContext ¶
Bases: BaseModel
Contextual information about a room for hook and channel processing.
recent_events is the room's tail in ascending order: its last
element is the most recent event the context knows about. Every consumer
reads it that way — memory providers slice [-N:], the inbound pipeline
appends the freshly committed event at the end, and hooks scanning for
"the latest X" iterate it reversed. A producer building a RoomContext
by hand owes it the same shape.
The room, bindings, participants and events it holds are the store's
snapshots (RFC §14.4): a hook or a channel treats them as frozen, and
changes the room through the kit (update_room_metadata()), never in
place. InMemoryStore shares them, so a change made in place would
reach the store behind the write interface's back.
author_register
class-attribute
instance-attribute
¶
The room's register of authors (RFC §6.4, §10.1 step 12), which the
labels of its turns read their ranks from, as the store keeps it apart
from the room's metadata: its digests name the room's senders to whoever
tries every phone number or name, so it reaches the runtime's readers and
a remote executor here, never a client through room.metadata.
None when the room holds none or the context was built without it.