pinecall-runtime 0.1.6__py3-none-any.whl

pinecall/wire/rest/usage.py

@@ -0,0 +1,245 @@
+"""The bodies of the org's meters: the usage feed, a window's insights, its drift, the limits."""
+
+from typing import Literal
+
+from pinecall.domain.names import Env
+from pinecall.wire.frames import WireModel
+
+
+class UsageTotals(WireModel):
+    """What was consumed: calls, minutes, turns, tokens, characters, judge calls, the cost."""
+
+    calls: int
+    minutes: float
+    messages: int
+    input_tokens: int
+    output_tokens: int
+    characters: int
+    judge_calls: int
+    cost_usd: float
+
+
+# Flat, as v1 wrote it: a billing layer that reads the feed today reads it unchanged at the cutover.
+class UsageRow(WireModel):
+    """One metered entry: whose it was, which call, what it consumed, and where the feed is."""
+
+    cursor: int
+    org: str
+    agent: str
+    call: str
+    type: str
+    at: float
+    minutes: float
+    messages: int
+    input_tokens: int
+    output_tokens: int
+    characters: int
+    judge_calls: int
+    cost_usd: float
+
+
+class UsagePage(WireModel):
+    """GET /v1/usage: the org's metered rows after the cursor, their totals, the next cursor."""
+
+    rows: list[UsageRow]
+    totals: UsageTotals | None
+    next: int | None
+
+
+class BoxUsagePage(WireModel):
+    """GET /v1/ops/usage: every org's metered rows after the cursor, totals per org, the next."""
+
+    rows: list[UsageRow]
+    totals: dict[str, UsageTotals]
+    next: int | None
+
+
+class InsightsConversations(WireModel):
+    """How many calls started in the window, and in the window of the same length before it."""
+
+    now: int
+    before: int
+
+
+class InsightsChannels(WireModel):
+    """The window's calls by the door they came in by."""
+
+    phone: int
+    web: int
+    whatsapp: int
+
+
+class InsightsSpend(WireModel):
+    """What one agent's window cost by stage, in US dollars, and per minute of its ended calls."""
+
+    llm_usd: float
+    stt_usd: float
+    tts_usd: float
+    phone_usd: float
+    platform_usd: float
+    minutes: float
+    per_minute_usd: float | None
+
+
+class InsightsAgent(WireModel):
+    """One agent's window: its calls, the share of judgments it held, what it cost by stage."""
+
+    slug: str
+    calls: int
+    score: float | None
+    spend: InsightsSpend
+
+
+class InsightsStage(WireModel):
+    """One stage of the window's turns on one vendor and model: how slow, how sure the ears were."""
+
+    stage: Literal["stt", "llm", "tts"]
+    vendor: str | None
+    model: str | None
+    turns: int
+    median_s: float | None
+    p95_s: float | None
+    confidence: float | None
+
+
+class InsightsBudget(WireModel):
+    """What the org may spend in a month and what it has spent so far, both worlds together."""
+
+    limit_usd: int | None
+    spent_usd_month: float
+
+
+class InsightsEnding(WireModel):
+    """One way the window's calls ended, and how many did."""
+
+    reason: str
+    count: int
+
+
+class InsightsDay(WireModel):
+    """One UTC day of the window: its calls by door, what they cost, how their judges answered."""
+
+    day: str
+    phone: int
+    web: int
+    whatsapp: int
+    spend_usd: float
+    judged: int
+    passed: int
+
+
+class Insights(WireModel):
+    """GET /v1/insights: whole UTC days of the key's world and scope, counted off the call index."""
+
+    day: str
+    days: int
+    timezone: str
+    conversations: InsightsConversations
+    resolved_rate: float | None
+    median_e2e_s: float | None
+    spend_usd: float
+    channels: InsightsChannels
+    judged: int
+    passed: int
+    escalated: int
+    mean_length_s: float | None
+    endings: list[InsightsEnding]
+    series: list[InsightsDay]
+    sessions_total: int
+    live: int
+    agents: list[InsightsAgent]
+    stages: list[InsightsStage]
+    budget: InsightsBudget
+
+
+class DriftSide(WireModel):
+    """One side of a drift as asked: a day, a version; and the versions its calls ran."""
+
+    day: str | None
+    version: int | None
+    versions: list[int]
+
+
+class JudgeTally(WireModel):
+    """One judge on one side: its verdicts that held, those settled, and the share that held."""
+
+    held: int
+    judged: int
+    pass_rate: float | None
+
+
+class DriftJudge(WireModel):
+    """One judge on both sides, how far its pass rate moved, and whether its question changed."""
+
+    name: str
+    before: JudgeTally | None
+    after: JudgeTally | None
+    moved: float | None
+    criteria_changed: bool
+
+
+class StageTally(WireModel):
+    """One stage on one side: its turns, median and p95 in seconds, the ears' confidence."""
+
+    turns: int
+    median_s: float | None
+    p95_s: float | None
+    confidence: float | None
+
+
+class DriftStage(WireModel):
+    """One stage on one vendor and model on both sides, and how far its median and p95 moved."""
+
+    stage: Literal["stt", "llm", "tts"]
+    vendor: str | None
+    model: str | None
+    before: StageTally | None
+    after: StageTally | None
+    median_moved_s: float | None
+    p95_moved_s: float | None
+
+
+class DriftVersion(WireModel):
+    """A version of the agent's settings a side ran or that was set between: who, when, why."""
+
+    version: int
+    holder: str
+    author: str
+    note: str | None
+    set_at: float
+    ran_before: bool
+    ran_after: bool
+
+
+class Drift(WireModel):
+    """GET /v1/insights/drift: what moved between two days or versions of an agent, and why."""
+
+    agent: str
+    world: Env
+    before: DriftSide
+    after: DriftSide
+    judges: list[DriftJudge]
+    stages: list[DriftStage]
+    versions: list[DriftVersion]
+
+
+class Limit(WireModel):
+    """One quota: the limit the org was given, and how much of it is used."""
+
+    limit: int | None
+    used: float
+
+
+class Limits(WireModel):
+    """GET /v1/limits: what the key's org may use in the world and has used, and its lends."""
+
+    minutes: Limit
+    messages: Limit
+    llm_tokens: Limit
+    concurrent_calls: Limit
+    agents: Limit
+    seats: Limit
+    numbers: Limit
+    lends: list[str] | None
+    billing_url: str | None
+    world: Env

pinecall/wire/room.py

@@ -0,0 +1,61 @@
+"""The room's events: the room opened, who joined, left and spoke, what they published, sent."""
+
+from pinecall.domain.names import Channel, JsonObject
+from pinecall.wire.frames import WireModel
+from pinecall.wire.parts import ParticipantKind, TrackKind, TrackSource
+
+
+class RoomOpened(WireModel):
+    """The LiveKit room exists and the call lives in it; a text session never logs this."""
+
+    name: str
+    sid: str
+    channel: Channel
+
+
+# The attributes travel verbatim: the caller's number is a fact of the room, not a field of ours.
+class ParticipantJoined(WireModel):
+    """Somebody joined the room."""
+
+    identity: str
+    kind: ParticipantKind
+    name: str | None = None
+    attributes: JsonObject
+
+
+class ParticipantLeft(WireModel):
+    """Somebody left the room; when it is the caller, call.ended follows."""
+
+    identity: str
+    reason: str
+
+
+class ParticipantSpeaking(WireModel):
+    """The room's own voice activity for one participant flipped; a light for the console."""
+
+    identity: str
+    speaking: bool
+
+
+class TrackPublished(WireModel):
+    """A participant put a track on the room: their microphone, their camera, a screen."""
+
+    identity: str
+    kind: TrackKind
+    source: TrackSource
+
+
+class TrackUnpublished(WireModel):
+    """A participant's track left the room."""
+
+    identity: str
+    kind: TrackKind
+    source: TrackSource
+
+
+class RoomSent(WireModel):
+    """The agent pushed a payload to a browser in the room; the payload stays out of the log."""
+
+    topic: str
+    to: str | None = None
+    bytes: int

pinecall/wire/scores.py

@@ -0,0 +1,49 @@
+"""What the judges said about a call: call.score, one judgment per judge, and its evidence."""
+
+from pydantic import AliasChoices, Field
+
+from pinecall.wire.frames import WireModel
+from pinecall.wire.parts import ScoreVerdict
+
+
+class JudgmentEvidence(WireModel):
+    """Where in the call's own log a judgment is about."""
+
+    seqs: list[int]
+    said: str | None = None
+
+
+class Judgment(WireModel):
+    """One judge's answer about one call."""
+
+    name: str
+    verdict: ScoreVerdict
+    criteria: str
+    reason: str
+    evidence: JudgmentEvidence
+
+
+class JudgedBy(WireModel):
+    """Who gave a score: the judge model, and one hash of every question the panel asked."""
+
+    # None: the panel was settled by code alone, no model asked.
+    provider: str | None
+    model: str | None
+    criteria: str
+
+
+class CallScore(WireModel):
+    """The last entry of a call: what the judges said about it at hang-up, one row per judge."""
+
+    passed: bool | None = None
+    not_judged: str | None = None
+    judges: list[Judgment]
+    panel: list[str] | None = None
+    judge_calls: int
+    # A score written before money in dollars said it in euros: the same number, read as dollars.
+    judge_cost_usd: float | None = Field(
+        default=None, validation_alias=AliasChoices("judge_cost_usd", "judge_cost_eur")
+    )
+    # Absent on a score written before 10.6, or with nothing judged: drift tells a worse agent from
+    # a changed judge by it.
+    judged_by: JudgedBy | None = None

pinecall/wire/state.py

@@ -0,0 +1,243 @@
+"""What a log reduces to: State and its parts."""
+
+from typing import Annotated, Literal
+
+from pydantic import Field
+
+from pinecall.domain.agent import EventSource
+from pinecall.domain.names import Channel, Direction, Json, JsonObject
+from pinecall.wire.frames import WireModel
+from pinecall.wire.metrics import (
+    AgentTurnMetrics,
+    AvatarMetrics,
+    EOTInferenceMetrics,
+    EOUMetrics,
+    InterruptionMetrics,
+    LLMMetrics,
+    ModelUsage,
+    RealtimeModelMetrics,
+    STTMetrics,
+    TTSMetrics,
+    UserTurnMetrics,
+    VADMetrics,
+)
+from pinecall.wire.parts import (
+    AgentState,
+    CallStatus,
+    Contact,
+    Cost,
+    DocSource,
+    EndReason,
+    MemoryOp,
+    ParticipantKind,
+    Route,
+    Supervisor,
+    TransferMode,
+    UserState,
+)
+
+
+class UserTurn(WireModel):
+    """One finished turn of the caller, with what the session measured about it."""
+
+    role: Literal["user"] = "user"
+    speech_id: str
+    item_id: str | None = None
+    text: str
+    language: str | None = None
+    transcript_confidence: float | None = None
+    metrics: UserTurnMetrics
+
+
+class AgentTurn(WireModel):
+    """One finished reply of the agent, with what the session measured about it."""
+
+    role: Literal["agent"] = "agent"
+    speech_id: str
+    item_id: str | None = None
+    text: str
+    interrupted: bool
+    metrics: AgentTurnMetrics
+
+
+type Turn = Annotated[UserTurn | AgentTurn, Field(discriminator="role")]
+
+
+class CollectedMetrics(WireModel):
+    """Every raw metric block of the call, by kind, in the order it arrived."""
+
+    llm: list[LLMMetrics]
+    stt: list[STTMetrics]
+    tts: list[TTSMetrics]
+    vad: list[VADMetrics]
+    eou: list[EOUMetrics]
+    eot: list[EOTInferenceMetrics]
+    interruption: list[InterruptionMetrics]
+    realtime: list[RealtimeModelMetrics]
+    avatar: list[AvatarMetrics]
+
+
+class ToolRun(WireModel):
+    """One tool call and, once the app answered, its result."""
+
+    call_id: str
+    name: str
+    arguments: JsonObject
+    speech_id: str | None = None
+    status: Literal["running", "done", "failed"]
+    output: Json = None
+    error: str | None = None
+    summary: str | None = None
+    duration_s: float | None = None
+    seq: int
+
+
+class PromptBlockState(WireModel):
+    """What is known about one block of the prompt without storing its text."""
+
+    hash: str
+    chars: int
+    seq: int
+
+
+type PromptState = dict[str, PromptBlockState]
+
+
+class Confirm(WireModel):
+    """One confirmation the platform asked for, and how it went."""
+
+    tool: str
+    call_id: str
+    audience: str
+    phrase: str
+    status: Literal["pending", "granted", "declined"]
+    said: str | None = None
+    reason: str | None = None
+
+
+class Handoff(WireModel):
+    """Whether a supervisor holds the line right now."""
+
+    active: bool
+    by: Supervisor | None
+
+
+class TransferState(WireModel):
+    """The transfer in flight or the one that happened."""
+
+    to: str
+    mode: TransferMode | None = None
+    status: Literal["requested", "done", "failed"]
+    by: Literal["agent", "supervisor"]
+
+
+class AttentionState(WireModel):
+    """The agent's last ask for a person, until attention.answered settles it."""
+
+    reason: str
+    wait_s: float
+    status: Literal["open", "answered", "lapsed"]
+    asked_at: float
+    by: Supervisor | None
+
+
+class LiveTranscript(WireModel):
+    """The words on screen right now: interim transcripts that a finished turn clears."""
+
+    user: str | None
+    agent: str | None
+
+
+class Gap(WireModel):
+    """A stretch of seqs this reader never saw."""
+
+    from_seq: int
+    to_seq: int
+
+
+class LoggedError(WireModel):
+    """An error entry, kept so the console can show what went wrong and when."""
+
+    seq: int
+    code: str
+    message: str
+
+
+class Participant(WireModel):
+    """One participant in the room right now, as the room reported them when they joined."""
+
+    identity: str
+    kind: ParticipantKind
+    name: str | None = None
+    joined_at: float
+    speaking: bool
+    attributes: JsonObject
+
+
+class Room(WireModel):
+    """The LiveKit room the call lives in, and who is in it right now."""
+
+    name: str
+    sid: str
+    participants: list[Participant]
+    caller: str | None
+
+
+class ReceivedEvent(WireModel):
+    """One fact that reached the agent from outside, kept by name and origin; its data is at seq."""
+
+    seq: int
+    name: str
+    source: EventSource
+    identity: str | None = None
+
+
+class CustomNote(WireModel):
+    """A line the app wrote into the log with call.log."""
+
+    seq: int
+    name: str
+    data: JsonObject
+
+
+class State(WireModel):
+    """The whole of what a log says, at the seq it was read to."""
+
+    seq: int
+    agent: str
+    call: str | None
+    status: CallStatus
+    channel: Channel | None
+    direction: Direction | None
+    from_: str | None = Field(alias="from")
+    to: str | None
+    caller: Contact | None
+    room: Room | None
+    started_at: float | None
+    ended_at: float | None
+    end_reason: EndReason | None
+    outcome: str | None
+    user_state: UserState | None
+    agent_state: AgentState | None
+    live: LiveTranscript
+    turns: list[Turn]
+    metrics: CollectedMetrics
+    tools: list[ToolRun]
+    app_state: JsonObject
+    events: list[ReceivedEvent]
+    prompt: PromptState
+    tools_visible: list[str]
+    confirms: list[Confirm]
+    memory: list[MemoryOp]
+    sources: list[DocSource]
+    handoff: Handoff
+    held: bool
+    muted: bool
+    transfer: TransferState | None
+    attention: AttentionState | None = None
+    usage: list[ModelUsage]
+    cost: Cost | None
+    routes: list[Route]
+    gaps: list[Gap]
+    errors: list[LoggedError]
+    custom: list[CustomNote]