pinecall-protocol 0.1.0__py3-none-any.whl

pinecall_protocol/metrics.py

@@ -0,0 +1,303 @@
+"""Generated from schema/metrics.json: every livekit-agents 1.8 metric, verbatim."""
+
+from typing import Annotated, Literal
+
+from pydantic import Field
+
+from pinecall_protocol._base import WireModel
+
+
+# livekit's Metadata, nested exactly as it nests it.
+class Metadata(WireModel):
+    """Which model and provider produced a block."""
+
+    model_name: str | None = None
+    model_provider: str | None = None
+
+
+# Two arrive for one reply when a tool ran in between; they share the speech_id.
+class LLMMetrics(WireModel):
+    """One LLM request, measured by the session's llm node."""
+
+    type: Literal["llm_metrics"] = "llm_metrics"
+    label: str
+    request_id: str
+    timestamp: float
+    duration: float
+    ttft: float
+    cancelled: bool
+    completion_tokens: int
+    prompt_tokens: int
+    prompt_cached_tokens: int
+    cache_creation_tokens: int | None = None
+    reasoning_tokens: int | None = None
+    total_tokens: int
+    tokens_per_second: float
+    speech_id: str | None = None
+    metadata: Metadata | None = None
+
+
+# A streaming STT reports one per connection segment, with duration 0.
+class STTMetrics(WireModel):
+    """One speech-to-text request, measured by the session's stt node."""
+
+    type: Literal["stt_metrics"] = "stt_metrics"
+    label: str
+    request_id: str
+    timestamp: float
+    duration: float
+    audio_duration: float
+    input_tokens: int | None = None
+    output_tokens: int | None = None
+    streamed: bool
+    acquire_time: float | None = None
+    connection_reused: bool | None = None
+    metadata: Metadata | None = None
+
+
+# One reply may produce several, one per sentence segment.
+class TTSMetrics(WireModel):
+    """One text-to-speech request, measured by the session's tts node."""
+
+    type: Literal["tts_metrics"] = "tts_metrics"
+    label: str
+    request_id: str
+    timestamp: float
+    ttfb: float
+    duration: float
+    audio_duration: float
+    cancelled: bool
+    characters_count: int
+    input_tokens: int | None = None
+    output_tokens: int | None = None
+    streamed: bool
+    acquire_time: float | None = None
+    connection_reused: bool | None = None
+    segment_id: str | None = None
+    speech_id: str | None = None
+    metadata: Metadata | None = None
+
+
+# Not a per-turn measure.
+class VADMetrics(WireModel):
+    """The voice activity detector's health, reported about once a second while it runs."""
+
+    type: Literal["vad_metrics"] = "vad_metrics"
+    label: str
+    timestamp: float
+    idle_time: float
+    inference_duration_total: float
+    inference_count: int
+    metadata: Metadata | None = None
+
+
+# One per user turn.
+class EOUMetrics(WireModel):
+    """How long the session took to decide that the caller had finished."""
+
+    type: Literal["eou_metrics"] = "eou_metrics"
+    timestamp: float
+    end_of_utterance_delay: float
+    transcription_delay: float
+    on_user_turn_completed_delay: float
+    speech_id: str | None = None
+    metadata: Metadata | None = None
+
+
+# It listens to the audio and says whether the caller is done.
+class EOTInferenceMetrics(WireModel):
+    """One prediction by the end-of-turn model."""
+
+    type: Literal["eot_inference_metrics"] = "eot_inference_metrics"
+    timestamp: float
+    total_duration: float
+    detection_delay: float
+    prediction_duration: float
+    num_requests: int | None = None
+    metadata: Metadata | None = None
+
+
+# Reported when the detector runs, not per turn.
+class InterruptionMetrics(WireModel):
+    """The interruption detector's latest inference and its running counts."""
+
+    type: Literal["interruption_metrics"] = "interruption_metrics"
+    timestamp: float
+    total_duration: float
+    prediction_duration: float
+    detection_delay: float
+    num_interruptions: int
+    num_backchannels: int
+    num_requests: int
+    metadata: Metadata | None = None
+
+
+class RealtimeCachedTokenDetails(WireModel):
+    """Of a realtime model's cached input, how much was audio, text or image."""
+
+    audio_tokens: int | None = None
+    text_tokens: int | None = None
+    image_tokens: int | None = None
+
+
+class RealtimeInputTokenDetails(WireModel):
+    """What a realtime model read, by kind, with the cached part broken out."""
+
+    audio_tokens: int | None = None
+    text_tokens: int | None = None
+    image_tokens: int | None = None
+    cached_tokens: int | None = None
+    cached_tokens_details: RealtimeCachedTokenDetails | None = None
+
+
+class RealtimeOutputTokenDetails(WireModel):
+    """What a realtime model produced, by kind."""
+
+    text_tokens: int | None = None
+    audio_tokens: int | None = None
+    image_tokens: int | None = None
+
+
+# Pinecall's default pipeline never emits it; a realtime provider would.
+class RealtimeModelMetrics(WireModel):
+    """One response from a speech-to-speech model, which replaces STT, LLM and TTS at once."""
+
+    type: Literal["realtime_model_metrics"] = "realtime_model_metrics"
+    label: str | None = None
+    request_id: str
+    timestamp: float
+    duration: float | None = None
+    session_duration: float | None = None
+    ttft: float | None = None
+    cancelled: bool | None = None
+    input_tokens: int | None = None
+    output_tokens: int | None = None
+    total_tokens: int | None = None
+    tokens_per_second: float | None = None
+    input_token_details: RealtimeInputTokenDetails
+    output_token_details: RealtimeOutputTokenDetails
+    acquire_time: float | None = None
+    connection_reused: bool | None = None
+    metadata: Metadata | None = None
+
+
+# No Pinecall channel has one today; carried because the library measures it.
+class AvatarMetrics(WireModel):
+    """Timing of a video avatar worker, when one is in the chain."""
+
+    type: Literal["avatar_metrics"] = "avatar_metrics"
+    timestamp: float
+    playback_latency: float | None = None
+    session_started_time: float | None = None
+    avatar_joined_time: float | None = None
+    metadata: Metadata | None = None
+
+
+# livekit's MetricsMetadata, as it sits on the ChatMessage.
+class TurnMetadata(WireModel):
+    """Which model handled one leg of a turn."""
+
+    model_name: str | None = None
+    model_provider: str | None = None
+
+
+# livekit stamps it on the user ChatMessage; every field is optional, since a text session has no
+# speech to time.
+class UserTurnMetrics(WireModel):
+    """What the session measured about the caller's turn."""
+
+    started_speaking_at: float | None = None
+    stopped_speaking_at: float | None = None
+    transcription_delay: float | None = None
+    end_of_turn_delay: float | None = None
+    on_user_turn_completed_delay: float | None = None
+    stt_metadata: TurnMetadata | None = None
+
+
+# livekit stamps it on the assistant ChatMessage; every field is optional, since a text session has
+# no audio to time.
+class AgentTurnMetrics(WireModel):
+    """What the session measured about the agent's reply."""
+
+    started_speaking_at: float | None = None
+    stopped_speaking_at: float | None = None
+    llm_node_ttft: float | None = None
+    llm_node_tps: float | None = None
+    llm_node_ttfs: float | None = None
+    tts_node_ttfb: float | None = None
+    playback_latency: float | None = None
+    e2e_latency: float | None = None
+    provider_request_ids: list[str] | None = None
+    llm_metadata: TurnMetadata | None = None
+    tts_metadata: TurnMetadata | None = None
+
+
+# One row per provider and model, as livekit's usage collector sums it.
+class LLMModelUsage(WireModel):
+    """Everything one LLM consumed over the call."""
+
+    type: Literal["llm_usage"] = "llm_usage"
+    provider: str
+    model: str
+    input_tokens: int | None = None
+    input_cached_tokens: int | None = None
+    input_cache_creation_tokens: int | None = None
+    input_audio_tokens: int | None = None
+    input_cached_audio_tokens: int | None = None
+    input_text_tokens: int | None = None
+    input_cached_text_tokens: int | None = None
+    input_image_tokens: int | None = None
+    input_cached_image_tokens: int | None = None
+    output_tokens: int | None = None
+    output_audio_tokens: int | None = None
+    output_text_tokens: int | None = None
+    output_reasoning_tokens: int | None = None
+    session_duration: float | None = None
+
+
+class TTSModelUsage(WireModel):
+    """Everything one TTS consumed over the call."""
+
+    type: Literal["tts_usage"] = "tts_usage"
+    provider: str
+    model: str
+    input_tokens: int | None = None
+    output_tokens: int | None = None
+    characters_count: int | None = None
+    audio_duration: float | None = None
+
+
+class STTModelUsage(WireModel):
+    """Everything one STT consumed over the call."""
+
+    type: Literal["stt_usage"] = "stt_usage"
+    provider: str
+    model: str
+    input_tokens: int | None = None
+    output_tokens: int | None = None
+    audio_duration: float | None = None
+
+
+class InterruptionModelUsage(WireModel):
+    """How often the interruption detector was asked over the call."""
+
+    type: Literal["interruption_usage"] = "interruption_usage"
+    provider: str
+    model: str
+    total_requests: int | None = None
+
+
+class EOTModelUsage(WireModel):
+    """How often the end-of-turn model was asked over the call."""
+
+    type: Literal["eot_usage"] = "eot_usage"
+    provider: str
+    model: str
+    total_requests: int | None = None
+
+
+# One usage row, told apart by its type tag.
+type ModelUsage = Annotated[
+    LLMModelUsage | TTSModelUsage | STTModelUsage | InterruptionModelUsage | EOTModelUsage,
+    Field(discriminator="type"),
+]

pinecall_protocol/registry.py

@@ -0,0 +1,341 @@
+"""Generated from schema: every event and command by its wire type."""
+
+from typing import Literal
+
+from pinecall_protocol._base import WireModel
+from pinecall_protocol.commands import (
+    AgentConfigure,
+    AgentRegister,
+    AgentReply,
+    AgentSay,
+    CallDial,
+    CallDtmf,
+    CallEvent,
+    CallHangup,
+    CallHold,
+    CallLog,
+    CallMute,
+    CallTransfer,
+    CallUnhold,
+    CallUnmute,
+    DevAnswer,
+    ParticipantMute,
+    ParticipantRemove,
+    Ping,
+    PromptSet,
+    RoomInvite,
+    RoomSend,
+    SessionConfigure,
+    StateSet,
+    SupervisorVerb,
+    ToolsSet,
+)
+from pinecall_protocol.defs import ToolResult
+from pinecall_protocol.events import (
+    AgentConfigured,
+    AgentDetached,
+    AgentRegistered,
+    AgentStateChanged,
+    AgentTranscript,
+    AgentTurnEnded,
+    CallbackRequested,
+    CallDialing,
+    CallEnded,
+    CallLine,
+    CallRinging,
+    CallScore,
+    CallStarted,
+    CallSummary,
+    CallTransferred,
+    ConfirmDeclined,
+    ConfirmGranted,
+    ConfirmRequest,
+    CreditsExhausted,
+    Custom,
+    DevRequest,
+    DocsSources,
+    ErrorEvent,
+    FleetFull,
+    LogCaughtUp,
+    LogGap,
+    MemoryOps,
+    Pong,
+    PromptChanged,
+    StateChanged,
+    SupervisorEnded,
+    SupervisorReleased,
+    SupervisorSaid,
+    SupervisorTookOver,
+    SupervisorTransferred,
+    SupervisorWhispered,
+    ToolCall,
+    ToolsChanged,
+    UserStateChanged,
+    UserTranscript,
+    UserTurnEnded,
+)
+from pinecall_protocol.metrics import (
+    AvatarMetrics,
+    EOTInferenceMetrics,
+    EOUMetrics,
+    InterruptionMetrics,
+    LLMMetrics,
+    RealtimeModelMetrics,
+    STTMetrics,
+    TTSMetrics,
+    VADMetrics,
+)
+from pinecall_protocol.room import (
+    EventReceived,
+    ParticipantJoined,
+    ParticipantLeft,
+    ParticipantSpeaking,
+    RoomOpened,
+    RoomSent,
+    TrackPublished,
+    TrackUnpublished,
+)
+
+# Every event by its wire type; codec looks the model up here.
+EVENTS: dict[str, type[WireModel]] = {
+    "agent.configured": AgentConfigured,
+    "agent.detached": AgentDetached,
+    "agent.registered": AgentRegistered,
+    "agent.state": AgentStateChanged,
+    "agent.transcript": AgentTranscript,
+    "call.dialing": CallDialing,
+    "call.ended": CallEnded,
+    "call.line": CallLine,
+    "call.ringing": CallRinging,
+    "call.score": CallScore,
+    "call.started": CallStarted,
+    "call.summary": CallSummary,
+    "call.transferred": CallTransferred,
+    "callback.requested": CallbackRequested,
+    "confirm.declined": ConfirmDeclined,
+    "confirm.granted": ConfirmGranted,
+    "confirm.request": ConfirmRequest,
+    "credits.exhausted": CreditsExhausted,
+    "custom": Custom,
+    "dev.request": DevRequest,
+    "docs.sources": DocsSources,
+    "error": ErrorEvent,
+    "event.received": EventReceived,
+    "fleet.full": FleetFull,
+    "log.caught_up": LogCaughtUp,
+    "log.gap": LogGap,
+    "memory.ops": MemoryOps,
+    "metrics.avatar": AvatarMetrics,
+    "metrics.eot": EOTInferenceMetrics,
+    "metrics.eou": EOUMetrics,
+    "metrics.interruption": InterruptionMetrics,
+    "metrics.llm": LLMMetrics,
+    "metrics.realtime": RealtimeModelMetrics,
+    "metrics.stt": STTMetrics,
+    "metrics.tts": TTSMetrics,
+    "metrics.vad": VADMetrics,
+    "participant.joined": ParticipantJoined,
+    "participant.left": ParticipantLeft,
+    "participant.speaking": ParticipantSpeaking,
+    "pong": Pong,
+    "prompt.changed": PromptChanged,
+    "room.opened": RoomOpened,
+    "room.sent": RoomSent,
+    "state.changed": StateChanged,
+    "supervisor.ended": SupervisorEnded,
+    "supervisor.released": SupervisorReleased,
+    "supervisor.said": SupervisorSaid,
+    "supervisor.took_over": SupervisorTookOver,
+    "supervisor.transferred": SupervisorTransferred,
+    "supervisor.whispered": SupervisorWhispered,
+    "tool.call": ToolCall,
+    "tool.result": ToolResult,
+    "tools.changed": ToolsChanged,
+    "track.published": TrackPublished,
+    "track.unpublished": TrackUnpublished,
+    "turn.agent": AgentTurnEnded,
+    "turn.user": UserTurnEnded,
+    "user.state": UserStateChanged,
+    "user.transcript": UserTranscript,
+}
+
+type EventType = Literal[
+    "agent.configured",
+    "agent.detached",
+    "agent.registered",
+    "agent.state",
+    "agent.transcript",
+    "call.dialing",
+    "call.ended",
+    "call.line",
+    "call.ringing",
+    "call.score",
+    "call.started",
+    "call.summary",
+    "call.transferred",
+    "callback.requested",
+    "confirm.declined",
+    "confirm.granted",
+    "confirm.request",
+    "credits.exhausted",
+    "custom",
+    "dev.request",
+    "docs.sources",
+    "error",
+    "event.received",
+    "fleet.full",
+    "log.caught_up",
+    "log.gap",
+    "memory.ops",
+    "metrics.avatar",
+    "metrics.eot",
+    "metrics.eou",
+    "metrics.interruption",
+    "metrics.llm",
+    "metrics.realtime",
+    "metrics.stt",
+    "metrics.tts",
+    "metrics.vad",
+    "participant.joined",
+    "participant.left",
+    "participant.speaking",
+    "pong",
+    "prompt.changed",
+    "room.opened",
+    "room.sent",
+    "state.changed",
+    "supervisor.ended",
+    "supervisor.released",
+    "supervisor.said",
+    "supervisor.took_over",
+    "supervisor.transferred",
+    "supervisor.whispered",
+    "tool.call",
+    "tool.result",
+    "tools.changed",
+    "track.published",
+    "track.unpublished",
+    "turn.agent",
+    "turn.user",
+    "user.state",
+    "user.transcript",
+]
+
+
+# Events a store may drop and a slow reader may miss: the entry's ephemeral flag defaults
+# to this.
+EPHEMERAL_EVENTS: frozenset[str] = frozenset(
+    {
+        "agent.transcript",
+        "dev.request",
+        "log.caught_up",
+        "log.gap",
+        "metrics.vad",
+        "participant.speaking",
+        "pong",
+        "room.sent",
+        "user.transcript",
+    }
+)
+
+
+# The one event that ends a call: after it nothing more is true and the log is sealed.
+TERMINAL_EVENT: str = "call.score"
+
+
+# Every command by its wire type; codec looks the model up here.
+COMMANDS: dict[str, type[WireModel]] = {
+    "agent.configure": AgentConfigure,
+    "agent.register": AgentRegister,
+    "agent.reply": AgentReply,
+    "agent.say": AgentSay,
+    "call.dial": CallDial,
+    "call.dtmf": CallDtmf,
+    "call.event": CallEvent,
+    "call.hangup": CallHangup,
+    "call.hold": CallHold,
+    "call.log": CallLog,
+    "call.mute": CallMute,
+    "call.transfer": CallTransfer,
+    "call.unhold": CallUnhold,
+    "call.unmute": CallUnmute,
+    "dev.answer": DevAnswer,
+    "participant.mute": ParticipantMute,
+    "participant.remove": ParticipantRemove,
+    "ping": Ping,
+    "prompt.set": PromptSet,
+    "room.invite": RoomInvite,
+    "room.send": RoomSend,
+    "session.configure": SessionConfigure,
+    "state.set": StateSet,
+    "supervisor.verb": SupervisorVerb,
+    "tool.result": ToolResult,
+    "tools.set": ToolsSet,
+}
+
+type CommandType = Literal[
+    "agent.configure",
+    "agent.register",
+    "agent.reply",
+    "agent.say",
+    "call.dial",
+    "call.dtmf",
+    "call.event",
+    "call.hangup",
+    "call.hold",
+    "call.log",
+    "call.mute",
+    "call.transfer",
+    "call.unhold",
+    "call.unmute",
+    "dev.answer",
+    "participant.mute",
+    "participant.remove",
+    "ping",
+    "prompt.set",
+    "room.invite",
+    "room.send",
+    "session.configure",
+    "state.set",
+    "supervisor.verb",
+    "tool.result",
+    "tools.set",
+]
+
+
+# Which events a command lands in the log as, so a caller knows what to wait for.
+PRODUCES: dict[str, tuple[str, ...]] = {
+    "agent.configure": ("agent.configured",),
+    "agent.register": ("agent.registered",),
+    "agent.reply": ("turn.agent",),
+    "agent.say": ("turn.agent",),
+    "call.dial": ("call.dialing",),
+    "call.dtmf": (),
+    "call.event": ("event.received",),
+    "call.hangup": ("call.ended",),
+    "call.hold": ("call.line",),
+    "call.log": ("custom",),
+    "call.mute": ("call.line",),
+    "call.transfer": ("call.transferred",),
+    "call.unhold": ("call.line",),
+    "call.unmute": ("call.line",),
+    "dev.answer": (),
+    "participant.mute": ("track.unpublished",),
+    "participant.remove": ("participant.left",),
+    "ping": ("pong",),
+    "prompt.set": ("prompt.changed",),
+    "room.invite": ("participant.joined",),
+    "room.send": ("room.sent",),
+    "session.configure": ("state.changed", "agent.configured"),
+    "state.set": ("state.changed",),
+    "supervisor.verb": (
+        "supervisor.said",
+        "supervisor.whispered",
+        "supervisor.took_over",
+        "supervisor.released",
+        "supervisor.transferred",
+        "supervisor.ended",
+    ),
+    "tool.result": ("tool.result",),
+    "tools.set": ("tools.changed",),
+}