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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pinecall-protocol
-Version: 0.3.0
+Version: 0.6.2
 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.3.0 → pinecall_protocol-0.6.2}/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.3.0"
+__version__ = "0.6.2"

{pinecall_protocol-0.3.0 → pinecall_protocol-0.6.2}/pinecall_protocol/commands.py

@@ -23,6 +23,7 @@ class AgentRegister(WireModel):
 
     routes: list[Route]
     sdk: str | None = None
+    host: str | None = None
     takes_unclaimed: bool = True
 
 

{pinecall_protocol-0.3.0 → pinecall_protocol-0.6.2}/pinecall_protocol/defs.py

@@ -25,16 +25,15 @@ type Env = Literal["production", "sandbox"]
 
 
 # What a console may ask of the process standing in the agent's directory, relayed by the gateway: a
-# written call to the class mounted there (chat), a simulated caller from its personas, its goldens
-# and a suite of them, its knowledge folder pushed or its golden asked, its memory goldens, a call
-# promoted to a candidate file, the drift of the last two windows, and the reproductions a broken
-# run left on that disk. Everything else a console needs is a door of the gateway.
+# written call to the class mounted there (chat), a simulated caller put on the class it holds, its
+# goldens and a suite of them, its knowledge folder pushed or its golden asked, its memory goldens,
+# a call promoted to a candidate file, the drift of the last two windows, and the reproductions a
+# broken run left on that disk. Everything else a console needs is a door of the gateway.
 type DevVerb = Literal[
     "chat.roster",
     "chat.start",
     "chat.say",
     "chat.end",
-    "simulate.roster",
     "simulate.start",
     "goldens.roster",
     "goldens.run",
@@ -337,7 +336,7 @@ class EventSpec(WireModel):
 
 
 class KnowledgeFile(WireModel):
-    """One file of knowledge, sent whole: its path as the tenant keeps it, and its text."""
+    """One file of a base, as a push sends it: its path as the tenant keeps it, and its text."""
 
     path: str
     text: str
@@ -384,8 +383,11 @@ class MemoryConfig(WireModel):
     forget: list[str] = Field(default_factory=list[str])
 
 
-# What an app declares about its agent: the voice, the models, the language, the greeting, the
-# tools, and who may see and send what. Every field is optional so a configure can change one thing.
+# What an app declares about its agent: the prompt's layout, the language, the tools, whether it
+# searches its bases itself, and who may see and send what. Every field is optional so a configure
+# can change one thing. The environment — voice, models, greeting, hangup, turn, says, hears,
+# knowledge, docs, memory — is the world's, set in the agent's settings, and no longer read off this
+# declaration.
 class AgentConfig(WireModel):
     """What an app declares about its agent."""
 
@@ -403,5 +405,6 @@ class AgentConfig(WireModel):
     memory: MemoryConfig | None = None
     hangup: HangupConfig | None = None
     tools: list[ToolSpec] | None = None
+    uses_knowledge: bool = False
     state_fields: list[StateFieldSpec] | None = None
     events: list[EventSpec] | None = None

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

@@ -159,6 +159,7 @@ class CallStarted(WireModel):
     from_: str = Field(alias="from")
     to: str
     run: str | None = None
+    persona: str | None = None
     caller: Contact | None
     started_at: float
     env: Env | None = None

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

@@ -10,10 +10,16 @@ from pinecall_protocol.defs import (
     Contact,
     Cost,
     Direction,
+    DocsConfig,
     EndReason,
     Env,
+    GreetingConfig,
+    HangupConfig,
     KnowledgeFile,
+    MemoryConfig,
     PlatformTool,
+    Pronunciation,
+    TurnConfig,
 )
 from pinecall_protocol.envelope import Entry
 from pinecall_protocol.state import CallStatus, State
@@ -412,6 +418,38 @@ class AgentList(WireModel):
     agents: list[HeldAgent]
 
 
+# One app connected to the gateway right now: one process on one machine, holding one or more agents
+# in one world.
+class AppProcess(WireModel):
+    """One app connected to the gateway right now."""
+
+    app: str
+    agents: list[str]
+    env: Env
+    host: str | None
+    address: str | None
+    sdk: str | None
+    holder: LineHolder | None
+    connected_at: float
+
+
+# GET /v1/apps: every app connected in the request's world that this key may see — its own corner's
+# and the org's, every corner's with `team`.
+class AppList(WireModel):
+    """GET /v1/apps."""
+
+    apps: list[AppProcess]
+
+
+# POST /v1/apps/{app}/stop, the answer: the socket was closed with the stop code, and the app exits
+# rather than reconnect.
+class AppStopped(WireModel):
+    """POST /v1/apps/{app}/stop, the answer."""
+
+    app: str
+    stopped: bool
+
+
 # GET /v1/agents/{slug}/line: whose terminal a call that RINGS at this agent's doors lands in. An
 # org shares one sandbox number, so it rings in one place and which one is claimed.
 class TheLine(WireModel):
@@ -643,8 +681,9 @@ class ExtractionRun(WireModel):
 
 
 # POST /v1/calls/{call}/lookup, the body: which platform tool to run for this turn, and what to run
-# it with. Worker-only; the gateway runs it against its own stores and writes memory.ops or
-# docs.sources on the call's log itself.
+# it with. Asked by the worker for the call it serves, and by the app for a call of its own org —
+# `this.knowledge.search` in a tool; the gateway runs it against its own stores and writes
+# memory.ops or docs.sources on the call's log itself.
 class LookupRequest(WireModel):
     """POST /v1/calls/{call}/lookup, the body."""
 
@@ -663,6 +702,22 @@ class LookupResult(WireModel):
     took_ms: float
 
 
+class FoundChunk(WireModel):
+    """One chunk search found: the file it came from, the heading it sits under, and its text."""
+
+    path: str
+    heading: str | None
+    text: str
+
+
+# What search answers in a lookup's output: the best chunks of every base the agent reads, the best
+# first. The app's `this.knowledge.search` hands the chunks to the tool that asked.
+class SearchFound(WireModel):
+    """What search answers in a lookup's output."""
+
+    chunks: list[FoundChunk]
+
+
 # POST /v1/calls/{call}/remember, the answer: what the call taught about the contact, counted.
 # Worker-only; the body is empty, the gateway reads the turns off its own log and writes memory.ops
 # itself.
@@ -713,3 +768,263 @@ class OutboundProvisioned(WireModel):
     ready: bool
     trunk: str | None = None
     address: str | None = None
+
+
+# Every field is optional; one left out is not set, and the runtime's own default stands for it.
+class TuningBody(WireModel):
+    """An agent's settings: what the org set, per world and per corner."""
+
+    voice: str | None = None
+    tts: str | None = None
+    tts_model: str | None = None
+    stt: str | None = None
+    llm: str | None = None
+    greeting: GreetingConfig | None = None
+    hangup: HangupConfig | None = None
+    turn: TurnConfig | None = None
+    memory: MemoryConfig | None = None
+    knowledge: str | None = None
+    bases: list[DocsConfig] | None = None
+
+
+# One kept version of an agent's tuning: whose corner, which version, who set it and when, and what
+# it says.
+class TuningRow(WireModel):
+    """One kept version of an agent's tuning."""
+
+    holder: str
+    version: int
+    author: str
+    note: str | None
+    set_at: float
+    config: TuningBody
+
+
+# GET /v1/agents/{slug}/settings: the agent's tuning as this key sees it — its own corner's, the
+# team's and production's, each corner's own newest row, or null when that corner set nothing.
+class TuningAnswer(WireModel):
+    """GET /v1/agents/{slug}/settings."""
+
+    world: Env
+    yours: TuningRow | None
+    team: TuningRow | None
+    production: TuningRow | None
+
+
+# PUT /v1/agents/{slug}/settings, the body: the whole set, the version it was read at, why, and
+# whose corner.
+class TuningPut(WireModel):
+    """PUT /v1/agents/{slug}/settings, the body."""
+
+    config: TuningBody
+    if_version: int | None = None
+    note: str | None = None
+    team: bool = False
+
+
+class TuningHistory(WireModel):
+    """GET /v1/agents/{slug}/settings/history: one corner's versions, newest first."""
+
+    world: Env
+    holder: str
+    rows: list[TuningRow]
+
+
+# GET /v1/agents/{slug}/settings/diff: what this key's corner reads against another corner's newest,
+# and which fields differ.
+class TuningDiff(WireModel):
+    """GET /v1/agents/{slug}/settings/diff."""
+
+    ours: TuningRow | None
+    theirs: TuningRow | None
+    changed: list[str]
+
+
+# It comes back as a NEW version; nothing is deleted.
+class Rollback(WireModel):
+    """POST /v1/agents/{slug}/settings/rollback, the body: which version to bring back."""
+
+    version: int
+    team: bool = False
+
+
+# The org's lexicon: how the voice says the words it would get wrong, and the words the ears must
+# know. Shared by every agent of the org, laid over each one's own says and hears.
+class LexiconBody(WireModel):
+    """The org's lexicon."""
+
+    said: list[Pronunciation]
+    heard: list[str]
+
+
+class LexiconRow(WireModel):
+    """One kept version of the org's lexicon."""
+
+    holder: str
+    version: int
+    author: str
+    note: str | None
+    set_at: float
+    lexicon: LexiconBody
+
+
+# GET /v1/lexicon: the org's words as this key sees them — its own corner's, the team's and
+# production's, each corner's own newest, or null.
+class LexiconAnswer(WireModel):
+    """GET /v1/lexicon."""
+
+    world: Env
+    yours: LexiconRow | None
+    team: LexiconRow | None
+    production: LexiconRow | None
+
+
+# PUT /v1/lexicon, the body: the whole lexicon, the version it was read at, why, and whose corner.
+class LexiconPut(WireModel):
+    """PUT /v1/lexicon, the body."""
+
+    lexicon: LexiconBody
+    if_version: int | None = None
+    note: str | None = None
+    team: bool = False
+
+
+class LexiconHistory(WireModel):
+    """GET /v1/lexicon/history: one corner's versions, newest first."""
+
+    world: Env
+    holder: str
+    rows: list[LexiconRow]
+
+
+# GET /v1/calls/{call}/settings: the exact tuning and lexicon a call was built on, by the versions
+# its head row recorded.
+class CallTuning(WireModel):
+    """GET /v1/calls/{call}/settings."""
+
+    config_version: int | None
+    lexicon_version: int | None
+    config: TuningRow | None
+    lexicon: LexiconRow | None
+
+
+class KnowledgeFileRow(WireModel):
+    """One file of a base as the list draws it."""
+
+    path: str
+    chars: int
+    chunks: int
+    pushed_at: float
+
+
+# GET /v1/knowledge/{base}: every file of the base, by path, with its size and what it became. Never
+# the text: one file is read at a time.
+class KnowledgeFiles(WireModel):
+    """GET /v1/knowledge/{base}."""
+
+    base: str
+    kept: bool
+    files: list[KnowledgeFileRow]
+
+
+class KnowledgeFileRead(WireModel):
+    """GET /v1/knowledge/{base}/files/{path}: one file, text and all."""
+
+    path: str
+    text: str
+    chunks: int
+    pushed_at: float
+
+
+# New under that path, or replaced in place; the base is begun when there is none.
+class KnowledgeFilePut(WireModel):
+    """PUT /v1/knowledge/{base}/files/{path}, the body: the file's whole text."""
+
+    text: str
+
+
+# PUT /v1/knowledge/{base}/files/{path}, the answer: which file, how many chunks it became, and how
+# long that took.
+class KnowledgeFilePushed(WireModel):
+    """PUT /v1/knowledge/{base}/files/{path}, the answer."""
+
+    base: str
+    path: str
+    chunks: int
+    took_ms: float
+
+
+class KnowledgeUse(WireModel):
+    """One base and the agents whose settings attach it."""
+
+    base: str
+    agents: list[str]
+
+
+# GET /v1/knowledge/attached: which agents read each base, off every agent's newest settings in this
+# world.
+class KnowledgeUses(WireModel):
+    """GET /v1/knowledge/attached."""
+
+    bases: list[KnowledgeUse]
+
+
+# One synthetic caller of an ORG, kept by the gateway: what they want, how they talk, and what they
+# may state about themselves. A model plays them turn by turn — there is no script — for `pinecall
+# simulate` and the console's Simulations. A caller is a person on the phone, so who they are does
+# not depend on which of the org's agents answers: every agent of the org calls with the same list.
+class Persona(WireModel):
+    """One synthetic caller of an ORG, kept by the gateway."""
+
+    name: str
+    about: str
+    goal: str
+    style: str
+    facts: dict[str, str]
+    state: dict[str, Any]
+    author: str
+    set_at: float
+
+
+# The same list for every agent of the org, and the same one in both worlds.
+class PersonaList(WireModel):
+    """GET /v1/personas: every caller the org wrote, by name."""
+
+    personas: list[Persona]
+
+
+# A name that exists is replaced; `was` renames the caller it names.
+class PersonaPut(WireModel):
+    """PUT /v1/personas/{name}, the body: the caller, written whole."""
+
+    about: str | None = None
+    goal: str
+    style: str
+    facts: dict[str, str] | None = None
+    state: dict[str, Any] | None = None
+    was: str | None = None
+
+
+# Read off the call index, never off a log — the same row the sessions list is drawn from.
+class PersonaRun(WireModel):
+    """One simulation this caller has run: the call it was, and what the call came to."""
+
+    call: str
+    agent: str
+    started_at: float
+    ended_at: float | None
+    turns: int
+    end_reason: EndReason | None
+    outcome: str | None
+    cost_eur: float | None
+    score: SessionScore | None
+
+
+# GET /v1/personas/{name}/runs, in the key's own world and corner, paged exactly as the sessions
+# list is.
+class PersonaRunList(WireModel):
+    """Every simulation this caller has run, newest first, a page at a time."""
+
+    runs: list[PersonaRun]
+    total: int
+    next: str | None