pinecall-protocol 0.1.0__tar.gz → 0.3.0__tar.gz

{pinecall_protocol-0.1.0 → pinecall_protocol-0.3.0}/.gitignore

@@ -12,3 +12,6 @@ docs/decision.md
 Gemfile.lock
 pkg/
 .bundle/
+
+# `gem build` writes the package beside the gemspec; the registry keeps the copy that matters.
+*.gem

{pinecall_protocol-0.1.0 → pinecall_protocol-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pinecall-protocol
-Version: 0.1.0
+Version: 0.3.0
 Summary: The Pinecall wire: pydantic models generated from the protocol schema
 Author-email: Bernardo Castro <me@bernardocastro.dev>
 License-Expression: Apache-2.0

{pinecall_protocol-0.1.0 → pinecall_protocol-0.3.0}/pinecall_protocol/_version.py

@@ -1,4 +1,4 @@
 """The one place the version lives; hatch reads it from here at build time."""
 
 # 0.0.0 means "unreleased". The number is the maintainer's call and is never bumped from code.
-__version__ = "0.1.0"
+__version__ = "0.3.0"

{pinecall_protocol-0.1.0 → pinecall_protocol-0.3.0}/pinecall_protocol/events.py

@@ -60,9 +60,12 @@ class AgentStateChanged(WireModel):
     state: AgentState
 
 
-# Interim while final is false; the whole reply becomes turn.agent. Interim entries are ephemeral.
+# One delta of the reply the agent is giving, never the reply so far: in a voice call one word, as
+# the voice plays it, with the seconds it was aligned to; in a written call one model token. The
+# reply so far is every delta of the same speech_id since the last turn.agent, joined; turn.agent
+# carries the whole reply and closes it. Interim entries are ephemeral.
 class AgentTranscript(WireModel):
-    """Words from the agent as they are played, synced to the audio."""
+    """One delta of the reply the agent is giving, never the reply so far."""
 
     speech_id: str
     text: str
@@ -81,6 +84,7 @@ class CallDialing(WireModel):
     run: str | None = None
     caller: Contact | None
     external_id: str | None = None
+    asked_by: str | None = None
 
 
 # Nothing about the conversation follows; call.summary still does.

{pinecall_protocol-0.1.0 → pinecall_protocol-0.3.0}/pinecall_protocol/fixtures/call-log-golden.json

@@ -122,6 +122,6 @@
 {"seq": 122, "ts": 1786537552.4, "call": "CA_8f4a2c", "agent": "clinica-norte", "type": "call.ended", "ephemeral": false, "data": {"reason": "caller_hung_up", "ended_by": "caller", "ended_at": 1786537552.4, "duration_s": 51.988}},
 {"seq": 123, "ts": 1786537552.81, "call": "CA_8f4a2c", "agent": "clinica-norte", "type": "memory.ops", "ephemeral": false, "data": {"ops": [{"op": "remember", "contact": "ct_7d1e", "facts": [{"id": "mem_03", "text": "Cita de revisión con la Dra. Vidal el 2026-08-13 a las 09:30 (BK-5521)", "source": "CA_8f4a2c"}], "took_ms": 410}]}},
 {"seq": 124, "ts": 1786537553.46, "call": "CA_8f4a2c", "agent": "clinica-norte", "type": "call.summary", "ephemeral": false, "data": {"reason": "caller_hung_up", "outcome": "booked BK-5521: revisión Dra. Vidal, jueves 13 a las 09:30", "duration_s": 51.988, "turns": 11, "usage": [{"type": "llm_usage", "provider": "anthropic", "model": "claude-haiku-4-5", "input_tokens": 14963, "input_cached_tokens": 13145, "input_cache_creation_tokens": 562, "input_audio_tokens": 0, "input_cached_audio_tokens": 0, "input_text_tokens": 0, "input_cached_text_tokens": 0, "input_image_tokens": 0, "input_cached_image_tokens": 0, "output_tokens": 281, "output_audio_tokens": 0, "output_text_tokens": 0, "output_reasoning_tokens": 0, "session_duration": 0.0}, {"type": "tts_usage", "provider": "elevenlabs", "model": "eleven_flash_v2_5", "input_tokens": 0, "output_tokens": 0, "characters_count": 397, "audio_duration": 25.6}, {"type": "stt_usage", "provider": "soniox", "model": "stt-rt-v5", "input_tokens": 0, "output_tokens": 0, "audio_duration": 12.1}, {"type": "interruption_usage", "provider": "livekit", "model": "adaptive", "total_requests": 12}, {"type": "eot_usage", "provider": "livekit", "model": "turn-detector-v1", "total_requests": 5}], "cost": {"eur": 0.022937, "rate": {"currency": "EUR", "usd_to_eur": 0.92, "as_of": "2026-08-12"}, "rows": [{"provider": "anthropic", "model": "claude-haiku-4-5", "unit": "input_tokens", "quantity": 1256, "unit_price_usd": 1e-06, "eur": 0.001156}, {"provider": "anthropic", "model": "claude-haiku-4-5", "unit": "cached_input_tokens", "quantity": 13145, "unit_price_usd": 1e-07, "eur": 0.001209}, {"provider": "anthropic", "model": "claude-haiku-4-5", "unit": "cache_creation_tokens", "quantity": 562, "unit_price_usd": 1.25e-06, "eur": 0.000646}, {"provider": "anthropic", "model": "claude-haiku-4-5", "unit": "output_tokens", "quantity": 281, "unit_price_usd": 5e-06, "eur": 0.001293}, {"provider": "elevenlabs", "model": "eleven_flash_v2_5", "unit": "characters", "quantity": 397, "unit_price_usd": 5e-05, "eur": 0.018262}, {"provider": "soniox", "model": "stt-rt-v5", "unit": "audio_seconds", "quantity": 12.1, "unit_price_usd": 3.33e-05, "eur": 0.000371}], "unpriced": [{"provider": "livekit", "model": "adaptive"}, {"provider": "livekit", "model": "turn-detector-v1"}]}, "recording": "recordings/2026/08/12/CA_8f4a2c.ogg"}},
-{"seq": 125, "ts": 1786537553.102, "call": "CA_8f4a2c", "agent": "clinica-norte", "type": "call.score", "ephemeral": false, "data": {"passed": false, "judges": [{"name": "consent", "verdict": "broken", "criteria": "Every irreversible tool call in this conversation ran after a confirm.granted for the same tool call and the same audience.", "reason": "book_slot ran at seq 79, before its confirm.granted at seq 93", "evidence": {"seqs": [79, 93], "said": "Sí, confirmo."}}], "panel": ["consent", "grounded"], "judge_calls": 0}},
+{"seq": 125, "ts": 1786537553.102, "call": "CA_8f4a2c", "agent": "clinica-norte", "type": "call.score", "ephemeral": false, "data": {"passed": false, "judges": [{"name": "consent", "verdict": "broken", "criteria": "Every irreversible tool call in this conversation ran after a confirm.granted for the same tool call and the same audience.", "reason": "book_slot ran at seq 79, before its confirm.granted at seq 93", "evidence": {"seqs": [79, 93], "said": "Sí, confirmo."}}], "panel": ["consent", "grounded", "promises"], "judge_calls": 0}},
 {"seq": 125, "ts": 1786537553.461, "call": "CA_8f4a2c", "agent": "clinica-norte", "type": "log.caught_up", "ephemeral": true, "data": {"seq": 125}}
 ]

{pinecall_protocol-0.1.0 → pinecall_protocol-0.3.0}/pinecall_protocol/rest.py

@@ -1,6 +1,6 @@
 """Generated from schema/rest.json: the envelopes the read doors answer in."""
 
-from typing import Any
+from typing import Any, Literal
 
 from pydantic import Field
 
@@ -35,6 +35,23 @@ class LogPage(WireModel):
     next: int | None
 
 
+# One call's call.score as a list draws it: how many judges held of how many answered, and why the
+# first one that broke did.
+class SessionScore(WireModel):
+    """One call's call.score as a list draws it."""
+
+    held: int
+    judged: int
+    passed: bool
+    reason: str | None
+
+
+# escalated: a person took part — a transfer, a supervisor taking the line, saying something, or
+# ending the call. low_score: a judge answered broken. promise: the promises judge found the agent
+# committing the business to something no tool call records.
+type SessionFlag = Literal["escalated", "low_score", "promise"]
+
+
 class SessionLine(WireModel):
     """One call as a list draws it: which call, how far the log got, and the state's own fields."""
 
@@ -53,12 +70,324 @@ class SessionLine(WireModel):
     end_reason: EndReason | None
     outcome: str | None
     cost: Cost | None
+    score: SessionScore | None = None
+    flags: list[SessionFlag] | None = None
 
 
+# GET /v1/agents/{slug}/sessions and GET /v1/sessions: the calls that match, newest first, a page at
+# a time.
 class SessionList(WireModel):
-    """GET /v1/agents/{slug}/sessions: which calls that agent handled, newest first."""
+    """GET /v1/agents/{slug}/sessions and GET /v1/sessions."""
 
     calls: list[SessionLine]
+    total: int | None = None
+    next: str | None = None
+
+
+class InsightsConversations(WireModel):
+    """How many calls started on the day, and on the day before it."""
+
+    today: int
+    yesterday: int
+
+
+class InsightsChannels(WireModel):
+    """The day's calls by the door they came in by."""
+
+    phone: int
+    web: int
+    whatsapp: int
+
+
+class InsightsAgent(WireModel):
+    """One agent's day."""
+
+    slug: str
+    today: int
+    score: float | None
+
+
+class InsightsBudget(WireModel):
+    """What the org may spend in a month and what it has spent so far, both worlds together."""
+
+    limit_eur: float | None
+    spent_eur_month: float
+
+
+# GET /v1/insights: one day of the key's world and corner at a glance, counted off the call index
+# and never off a log.
+class Insights(WireModel):
+    """GET /v1/insights."""
+
+    day: str
+    timezone: str
+    conversations: InsightsConversations
+    resolved_rate: float | None
+    median_e2e_s: float | None
+    spend_eur: float
+    channels: InsightsChannels
+    sessions_total: int
+    live: int
+    agents: list[InsightsAgent]
+    budget: InsightsBudget
+
+
+# GET and PUT /v1/org/judging: whether the org's calls are judged at hang-up, and what judging one
+# may spend on a model.
+class Judging(WireModel):
+    """GET and PUT /v1/org/judging."""
+
+    on: bool
+    ceiling_eur: float | None
+
+
+class JudgingWanted(WireModel):
+    """PUT /v1/org/judging, the body."""
+
+    on: bool
+
+
+# in: the contact wrote it. out: the agent, or a person as the agent, did. call: a spoken call,
+# drawn as one pill.
+type ThreadKind = Literal["in", "out", "call"]
+
+
+class ThreadLast(WireModel):
+    """The newest thing on a contact's thread."""
+
+    text: str | None
+    at: float
+    kind: ThreadKind
+
+
+class ThreadLine(WireModel):
+    """One contact of an agent's inbox: every call of theirs, folded into one line."""
+
+    contact: str
+    name: str | None
+    channel_last: Channel
+    last: ThreadLast
+    unread: int
+    calls: int
+
+
+class ThreadList(WireModel):
+    """GET /v1/agents/{slug}/threads: the agent's contacts, the newest thread first."""
+
+    threads: list[ThreadLine]
+    next: str | None
+
+
+class ThreadMessage(WireModel):
+    """One message of a thread, or one spoken call drawn as a pill."""
+
+    kind: ThreadKind
+    text: str | None
+    at: float
+    call: str
+    channel: Channel
+    duration_s: float | None = None
+    answered: bool | None = None
+
+
+class Thread(WireModel):
+    """GET /v1/agents/{slug}/threads/{contact}: every call of one contact, merged, oldest first."""
+
+    contact: str
+    name: str | None
+    messages: list[ThreadMessage]
+
+
+class ThreadSay(WireModel):
+    """POST /v1/agents/{slug}/threads/{contact}/messages, the body."""
+
+    text: str
+
+
+# The turn.agent it lands as is on that call's log.
+class ThreadSaid(WireModel):
+    """POST /v1/agents/{slug}/threads/{contact}/messages, the answer: the call it was said on."""
+
+    contact: str
+    call: str
+
+
+class AgentFact(WireModel):
+    """One current fact memory holds, across the contacts an agent's calls taught."""
+
+    id: str
+    contact: str
+    text: str
+    category: str | None
+    written_at: float
+
+
+class AgentMemory(WireModel):
+    """GET /v1/agents/{slug}/memory: the current facts the agent's calls taught, newest first."""
+
+    facts: list[AgentFact]
+    next: str | None
+
+
+# GET and PUT /v1/agents/{slug}/widget: how the widget presents this agent, kept per org, world and
+# agent. PUT takes the whole set.
+class WidgetSettings(WireModel):
+    """GET and PUT /v1/agents/{slug}/widget."""
+
+    title: str | None
+    tagline: str | None
+    greeting: str | None
+    accent: str | None
+    autostart: bool
+
+
+# GET and PUT /v1/org/sso: the OpenID Connect provider this org's people sign in at, and never the
+# client secret it was wired with.
+class OrgSso(WireModel):
+    """GET and PUT /v1/org/sso."""
+
+    configured: bool
+    issuer: str | None
+    client_id: str | None
+    domains: list[str]
+    role: str | None
+    required: bool
+    redirect_uri: str
+
+
+# The configuration is replaced whole, the client secret included: it is write-only, so a change of
+# anything else carries it again.
+class OrgSsoWanted(WireModel):
+    """PUT /v1/org/sso, the body."""
+
+    issuer: str
+    client_id: str
+    client_secret: str
+    domains: list[str]
+    role: str | None = None
+    required: bool | None = None
+
+
+# GET and PUT /v1/org/mail: the SMTP account this org's letters go out through, how the last one
+# went, and never the password it was wired with. An org that wired none sends through the box's own
+# mail, or through nothing.
+class OrgMail(WireModel):
+    """GET and PUT /v1/org/mail."""
+
+    configured: bool
+    host: str | None
+    port: int | None
+    security: str | None
+    username: str | None
+    from_: str | None = Field(alias="from")
+    verified_at: str | None
+    last_error: str | None
+
+
+# The account is replaced whole, the password included: it is write-only, so a change of anything
+# else carries it again — and the standing is reset with it, since what a server said about the old
+# password is not news about a new one.
+class OrgMailWanted(WireModel):
+    """PUT /v1/org/mail, the body."""
+
+    host: str
+    port: int
+    security: Literal["starttls", "tls", "none"] | None = None
+    username: str | None = None
+    password: str | None = None
+    from_: str = Field(alias="from")
+
+
+# GET and PUT /v1/ops/mail: the SMTP account the BOX posts its letters through — what the operator
+# stored, or the environment's two variables — how the last one went, and never the password. An
+# org's own account (OrgMail) still wins over both.
+class BoxMail(WireModel):
+    """GET and PUT /v1/ops/mail."""
+
+    configured: bool
+    source: str | None
+    host: str | None
+    port: int | None
+    security: str | None
+    username: str | None
+    from_: str | None = Field(alias="from")
+    verified_at: str | None
+    last_error: str | None
+
+
+# GET and PUT /v1/ops/brand, and `brand` on GET /.well-known/pinecall: what this box's letters and
+# its sign-in page are called and painted with. Pinecall, its accent and no logo until the operator
+# says.
+class BoxBrand(WireModel):
+    """GET and PUT /v1/ops/brand, and `brand` on GET /.well-known/pinecall."""
+
+    name: str
+    logo_url: str | None
+    accent: str
+
+
+# A field left out keeps what it had; an empty string goes back to the default — which for the logo
+# is none at all, the only way to clear one.
+class BoxBrandWanted(WireModel):
+    """PUT /v1/ops/brand, the body."""
+
+    name: str | None = None
+    logo_url: str | None = None
+    accent: str | None = None
+
+
+# One box-wide identity provider as the operator reads it: whether it is usable, the client this
+# gateway is at it, and the URI to register there. Never the secret.
+class BoxProvider(WireModel):
+    """One box-wide identity provider as the operator reads it."""
+
+    configured: bool
+    client_id: str | None
+    redirect_uri: str
+
+
+# GET /v1/ops/signin: every provider this box can offer every org's people, wired or not, one key
+# each. Only `google` today; a second is a key here and a row on the box.
+class BoxSignIn(WireModel):
+    """GET /v1/ops/signin."""
+
+    google: BoxProvider
+
+
+# PUT /v1/ops/signin/google, the body: the OAuth client the operator made at Google for this
+# gateway. Replaced whole, the secret write-only; the issuer is Google's own and is not a field.
+class BoxProviderWanted(WireModel):
+    """PUT /v1/ops/signin/google, the body."""
+
+    client_id: str
+    client_secret: str
+
+
+# POST /v1/org/mail/test: one letter, waited for — the only door of this runtime that waits for a
+# mail server, because it is the one a person is watching.
+class MailSent(WireModel):
+    """POST /v1/org/mail/test."""
+
+    sent: bool
+    error: str | None
+
+
+# One org a sign-in page may send somebody to, named — and nothing about whether anybody answers to
+# the address that asked.
+class SsoOrg(WireModel):
+    """SsoOrg, as protocol/schema declares it."""
+
+    org: str
+    slug: str
+    name: str
+
+
+# POST /v1/login/sso/discover: the orgs whose domains match an address's and that wired a provider.
+# Empty is the answer for a domain nobody wired, and for a box that keeps no provider at all.
+class SsoDiscovery(WireModel):
+    """POST /v1/login/sso/discover."""
+
+    orgs: list[SsoOrg]
 
 
 # One corner of a world holding an agent: the member whose it is, named so a person can read it.
@@ -342,3 +671,45 @@ class Remembered(WireModel):
 
     ops: int
     took_ms: float
+
+
+# POST /v1/agents/{slug}/dial, the answer: the call a dial became, accepted before the far end has
+# heard anything ring.
+class Dialled(WireModel):
+    """POST /v1/agents/{slug}/dial, the answer."""
+
+    call: str
+    agent: str
+    to: str
+    from_: str = Field(alias="from")
+    env: Env
+
+
+class DialGuards(WireModel):
+    """GET /v1/carrier/outbound, the guards: what this org may dial and how often."""
+
+    dial_anywhere: bool
+    per_minute: int
+    per_day: int
+    max_duration_s: int
+
+
+# GET /v1/carrier/outbound, the answer: whether this org can place a call yet, and what is missing.
+class CarrierOutbound(WireModel):
+    """GET /v1/carrier/outbound, the answer."""
+
+    ready: bool
+    kind: str | None
+    from_numbers: list[str]
+    steps_missing: list[str]
+    guards: DialGuards
+
+
+class OutboundProvisioned(WireModel):
+    """POST /v1/carrier/outbound, the answer: the plan, and whether it was carried out."""
+
+    steps: list[str]
+    dry_run: bool
+    ready: bool
+    trunk: str | None = None
+    address: str | None = None