pinecall-runtime 0.1.6__py3-none-any.whl

pinecall/wire/metrics.py

@@ -0,0 +1,287 @@
+"""Every livekit-agents 1.8 metric and usage row, verbatim."""
+
+from typing import Annotated, Literal
+
+from pydantic import Field
+
+from pinecall.wire.frames import WireModel
+
+
+class Metadata(WireModel):
+    """Which model and provider produced a block."""
+
+    model_name: str | None = None
+    model_provider: str | None = None
+
+
+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
+
+
+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
+
+
+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
+
+
+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
+
+
+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
+
+
+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
+
+
+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
+
+
+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
+
+
+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
+
+
+class TurnMetadata(WireModel):
+    """Which model handled one leg of a turn."""
+
+    model_name: str | None = None
+    model_provider: str | None = None
+
+
+# Every field is optional: 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
+
+
+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
+
+
+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
+
+
+type ModelUsage = Annotated[
+    LLMModelUsage | TTSModelUsage | STTModelUsage | InterruptionModelUsage | EOTModelUsage,
+    Field(discriminator="type"),
+]

pinecall/wire/parts.py

@@ -0,0 +1,320 @@
+"""The parts events, commands and state share: the wire's words and its common shapes."""
+
+from typing import Literal
+
+from pydantic import AliasChoices, Field
+
+from pinecall.domain.agent import EventSource
+from pinecall.domain.names import Channel, Json, JsonObject
+from pinecall.wire.frames import WireModel
+
+# What a console may ask of the process standing in the agent's directory, relayed by the gateway.
+type DevVerb = Literal[
+    "chat.roster",
+    "chat.start",
+    "chat.say",
+    "chat.end",
+    "view.render",
+    "simulate.start",
+    "goldens.roster",
+    "goldens.run",
+    "knowledge.roster",
+    "knowledge.push",
+    "knowledge.eval",
+    "memory.roster",
+    "memory.eval",
+    "memory.extraction",
+    "promote.roster",
+    "promote.write",
+    "drift.read",
+    "reproductions.roster",
+    "reproductions.read",
+]
+
+# drained: the worker went down with the call on it; app_detached: the app closed mid-call.
+type EndReason = Literal[
+    "caller_hung_up",
+    "agent_hung_up",
+    "supervisor_ended",
+    "transferred",
+    "no_answer",
+    "busy",
+    "dial_failed",
+    "timeout",
+    "drained",
+    "app_detached",
+    "error",
+]
+
+# platform covers timeouts, errors and a drained worker.
+type EndedBy = Literal["caller", "agent", "supervisor", "platform"]
+
+# skipped: no model was reachable inside the call's judging budget.
+type ScoreVerdict = Literal["held", "broken", "deferred", "skipped"]
+
+# cold: a REFER on the caller's SIP leg. warm: the number is dialled into the room.
+type TransferMode = Literal["cold", "warm"]
+
+type PromptRegion = Literal["static", "dynamic"]
+type DocsMode = Literal["retrieved", "tool"]
+type PlatformTool = Literal["recall", "search"]
+type UserState = Literal["listening", "speaking", "away"]
+type AgentState = Literal["initializing", "idle", "listening", "thinking", "speaking"]
+type ParticipantKind = Literal["caller", "agent", "supervisor", "listener", "sip"]
+type TrackKind = Literal["audio", "video", "screen"]
+type TrackSource = Literal["microphone", "camera", "screen_share", "screen_share_audio", "unknown"]
+type Visibility = Literal["public", "tenant", "pii"]
+
+# Which projection a sink applies before a state or an entry leaves the platform.
+type Projection = Literal["public", "tenant"]
+
+type CallStatus = Literal["idle", "ringing", "dialing", "active", "ended"]
+type SessionFlag = Literal["escalated", "low_score", "promise"]
+type ThreadKind = Literal["in", "out", "call"]
+type WidgetTheme = Literal["auto", "light", "dark"]
+
+
+# The provider of the box's own rows (its compute): what the platform cost, beside the vendors'.
+PLATFORM = "pinecall"
+
+
+class PromptBlockSpec(WireModel):
+    """One named block of the prompt and the region it lives in."""
+
+    name: str = Field(pattern="^[a-z][a-z0-9_]*$")
+    region: PromptRegion
+
+
+class Contact(WireModel):
+    """Who is on the line, as far as the platform knows; a web visitor may be nobody yet."""
+
+    id: str | None = None
+    phone: str | None = None
+    name: str | None = None
+    email: str | None = None
+    external_id: str | None = None
+
+
+class Route(WireModel):
+    """One door to an agent: a channel and, for phone and WhatsApp, the number that answers."""
+
+    channel: Channel
+    number: str | None
+    label: str | None = None
+
+
+class Supervisor(WireModel):
+    """The human who sent a supervise verb, as the token that let them in names them."""
+
+    id: str
+    name: str | None = None
+
+
+class ToolSpec(WireModel):
+    """What the app declares about one tool."""
+
+    name: str
+    description: str
+    parameters: JsonObject
+    side_effect: Literal["read", "write", "irreversible"] = "read"
+    confirm: str | None = None
+    pii: list[str] | None = None
+    timeout_s: float | None = None
+
+
+class ToolResult(WireModel):
+    """What came back from running a tool in the app's process: an output or an error."""
+
+    call_id: str
+    name: str
+    output: Json = None
+    error: str | None = None
+    summary: str | None = None
+    duration_s: float | None = None
+
+
+class MemoryFact(WireModel):
+    """One thing remembered about a contact."""
+
+    id: str | None = None
+    text: str
+    category: str | None = None
+    score: float | None = None
+    source: str | None = None
+
+
+class MemoryOp(WireModel):
+    """One operation against the contact's memory."""
+
+    op: Literal["recall", "remember", "forget"]
+    contact: str | None = None
+    query: str | None = None
+    facts: list[MemoryFact]
+    took_ms: float
+
+
+class DocSource(WireModel):
+    """One chunk of the knowledge base that retrieval put in front of the model for this turn."""
+
+    id: str
+    base: str | None = None
+    path: str
+    heading: str | None = None
+    score: float
+    excerpt: str | None = None
+
+
+class CostRow(WireModel):
+    """One priced line: a model, what was counted, how much, and what it came to."""
+
+    provider: str
+    model: str
+    unit: Literal[
+        "input_tokens",
+        "cached_input_tokens",
+        "cache_creation_tokens",
+        "output_tokens",
+        "characters",
+        "audio_seconds",
+        "requests",
+        "session_seconds",
+        "minutes",
+    ]
+    quantity: float
+    unit_price_usd: float
+    # A summary written before money in dollars priced its rows in euros: the same number, read as
+    # dollars and never converted, as migration 0007 kept the facts' column.
+    usd: float = Field(validation_alias=AliasChoices("usd", "eur"))
+
+
+class UnpricedRow(WireModel):
+    """A usage row the price table does not know: listed, never priced at zero."""
+
+    provider: str
+    model: str
+
+
+class Cost(WireModel):
+    """What the call cost in provider fees and, priced, the box's own compute; US dollars."""
+
+    usd: float = Field(validation_alias=AliasChoices("usd", "eur"))
+    rows: list[CostRow]
+    unpriced: list[UnpricedRow]
+    # The euro's rate a summary written before money in dollars carried; read, never written.
+    rate: JsonObject | None = Field(default=None, exclude=True)
+
+
+class VoiceConfig(WireModel):
+    """Which voice speaks for the agent."""
+
+    name: str | None = None
+    provider: str | None = None
+    model: str | None = None
+    voice_id: str | None = None
+
+
+class ModelConfig(WireModel):
+    """Which model does a job (the LLM, or the STT), and the one or two knobs worth turning."""
+
+    provider: str
+    model: str
+    temperature: float | None = None
+
+
+class TurnConfig(WireModel):
+    """How the session decides that the caller has finished, and when the caller may interrupt."""
+
+    min_interruption_words: int | None = None
+    endpointing_ms: int | None = None
+    eot_threshold: float | None = None
+    eager_eot_threshold: float | None = None
+    min_interruption_ms: int | None = None
+
+
+class Pronunciation(WireModel):
+    """How the voice says one word it would otherwise get wrong."""
+
+    word: str
+    spoken: str
+
+
+class StateFieldSpec(WireModel):
+    """What the app declares about one field of its state: who may see it."""
+
+    name: str
+    visibility: Visibility
+
+
+class ViewSpec(WireModel):
+    """The panel the agent draws beside a conversation; its contents come by dev verb."""
+
+    name: str
+
+
+class EventSpec(WireModel):
+    """One outside event the agent accepts, and from whom."""
+
+    name: str
+    from_: list[EventSource] = Field(alias="from")
+
+
+class KnowledgeFile(WireModel):
+    """One file of a base, as a push sends it: its path as the tenant keeps it, and its text."""
+
+    path: str
+    text: str
+
+
+class DocsConfig(WireModel):
+    """The knowledge base the agent answers from, and how its chunks reach the model."""
+
+    base: str
+    mode: DocsMode = "retrieved"
+    k: int = 8
+    min_score: float | None = None
+
+
+class GreetingConfig(WireModel):
+    """How the agent opens a call: `say` the words, or `reply` what the model reads first."""
+
+    say: str | None = None
+    reply: str | None = None
+    allow_interruptions: bool | None = None
+
+
+class HangupConfig(WireModel):
+    """Whether the model may end the call itself, and when."""
+
+    when: str = ""
+
+
+class MemoryConfig(WireModel):
+    """What memory keeps about a contact across calls, and what it must never keep."""
+
+    remember: list[str] = Field(default_factory=list[str])
+    forget: list[str] = Field(default_factory=list[str])
+
+
+# Every field is optional so a configure can change one thing.
+class AgentConfig(WireModel):
+    """What an app declares about its agent."""
+
+    prompt: list[PromptBlockSpec] | None = None
+    language: str | None = None
+    greeting: GreetingConfig | None = None
+    voice: VoiceConfig | None = None
+    llm: ModelConfig | None = None
+    stt: ModelConfig | None = None
+    turn: TurnConfig | None = None
+    says: list[Pronunciation] | None = None
+    hears: list[str] | None = None
+    knowledge: KnowledgeFile | None = None
+    docs: DocsConfig | None = None
+    memory: MemoryConfig | None = None
+    hangup: HangupConfig | None = None
+    record: bool = True
+    tools: list[ToolSpec] | None = None
+    uses_knowledge: bool = False
+    state_fields: list[StateFieldSpec] | None = None
+    view: ViewSpec | None = None
+    events: list[EventSpec] | None = None