pinecall-runtime 0.1.6__py3-none-any.whl

pinecall/wire/rest/retrieval.py

@@ -0,0 +1,301 @@
+"""The bodies of the knowledge and memory doors."""
+
+from pydantic import Field
+
+from pinecall.domain.names import Channel
+from pinecall.wire.frames import WireModel
+from pinecall.wire.parts import (
+    KnowledgeFile,
+)
+
+# ── knowledge bases ──
+
+
+# The base is replaced whole, never merged.
+class KnowledgePush(WireModel):
+    """PUT /v1/knowledge/{base}, the body: the tenant's folder as of now."""
+
+    files: list[KnowledgeFile]
+
+
+class KnowledgePushed(WireModel):
+    """PUT /v1/knowledge/{base}, the answer: the base, the chunks it became, how long it took."""
+
+    base: str
+    chunks: int
+    took_ms: float
+
+
+class KnowledgeBase(WireModel):
+    """One base as the list draws it: its size, the model that wrote it, when it was pushed."""
+
+    base: str
+    chunks: int
+    model: str
+    pushed_at: float
+
+
+class KnowledgeList(WireModel):
+    """GET /v1/knowledge: every base the key's scope reads."""
+
+    bases: list[KnowledgeBase]
+
+
+class KnowledgeUse(WireModel):
+    """One base and the agents whose settings attach it."""
+
+    base: str
+    agents: list[str]
+
+
+class KnowledgeUses(WireModel):
+    """GET /v1/knowledge/attached: which agents read each base, off their newest settings."""
+
+    bases: list[KnowledgeUse]
+
+
+class KnowledgeFileRow(WireModel):
+    """One file of a base as the list draws it."""
+
+    path: str
+    chars: int
+    chunks: int
+    pushed_at: float
+
+
+# `kept` is false for a base whose files were never stored, only its chunks.
+class KnowledgeFiles(WireModel):
+    """GET /v1/knowledge/{base}: every file of the base, never its text."""
+
+    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
+
+
+class KnowledgeFilePut(WireModel):
+    """PUT /v1/knowledge/{base}/files/{path}, the body: the file's whole text."""
+
+    text: str
+
+
+class KnowledgeFilePushed(WireModel):
+    """PUT /v1/knowledge/{base}/files/{path}, the answer: the file, its chunks, how long it took."""
+
+    base: str
+    path: str
+    chunks: int
+    took_ms: float
+
+
+# A chunk answers when its file and heading path start with `expects`, never by substring.
+class GoldenQuestion(WireModel):
+    """One question of a base's golden: what somebody asks, and the chunk that should answer."""
+
+    asks: str
+    expects: str
+
+
+class KnowledgeGolden(WireModel):
+    """POST /v1/knowledge/{base}/eval, the body: the questions a base is held to."""
+
+    questions: list[GoldenQuestion]
+    k: int | None = None
+
+
+class GoldenMiss(WireModel):
+    """One question whose chunk was not among the k returned, and what came back instead."""
+
+    asks: str
+    expects: str
+    found: list[str]
+
+
+class KnowledgeScore(WireModel):
+    """POST /v1/knowledge/{base}/eval, the answer: recall@k and nDCG@10, computed with no model."""
+
+    base: str
+    model: str
+    questions: int
+    k: int
+    recall_at_k: float
+    ndcg_at_10: float
+    took_ms: float
+    misses: list[GoldenMiss]
+
+
+# ── memory ──
+
+
+# A fact is never updated, only superseded, so the history keeps every version.
+class ContactFact(WireModel):
+    """One fact of a contact's history, with the two dates that bound it."""
+
+    id: str | None = None
+    text: str
+    category: str | None = None
+    source: str | None = None
+    valid_from: float
+    invalidated_at: float | None
+
+
+class ContactMemory(WireModel):
+    """GET /v1/contacts/{contact}/memory: every fact ever kept of the contact, current first."""
+
+    facts: list[ContactFact]
+
+
+class Forgotten(WireModel):
+    """DELETE /v1/contacts/{contact}/memory and /v1/memory/facts/{id}: how many facts went."""
+
+    forgotten: int
+
+
+class AgentFact(WireModel):
+    """One current fact, among 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 facts the agent's calls taught, newest first, a page."""
+
+    facts: list[AgentFact]
+    next: str | None
+
+
+class OrgFact(WireModel):
+    """One current fact of the org, with the agent whose call taught it."""
+
+    id: str
+    agent: str
+    contact: str
+    text: str
+    category: str | None
+    written_at: float
+
+
+class OrgMemory(WireModel):
+    """GET /v1/memory: the org's current facts from every agent, newest first, a page."""
+
+    facts: list[OrgFact]
+    next: str | None = None
+
+
+# A question brings its own facts: written to a scratch contact, asked, and forgotten.
+class MemoryQuestion(WireModel):
+    """One question of a memory golden: what memory holds, what is asked, what should come back."""
+
+    holds: list[str]
+    asks: str
+    expects: list[str]
+
+
+class MemoryGolden(WireModel):
+    """POST /v1/contacts/memory/eval, the body: the questions memory is held to."""
+
+    questions: list[MemoryQuestion]
+    k: int | None = None
+
+
+class MemoryMiss(WireModel):
+    """One question memory did not answer whole: what it missed, and what came back instead."""
+
+    asks: str
+    missing: list[str]
+    found: list[str]
+
+
+class MemoryScore(WireModel):
+    """POST /v1/contacts/memory/eval, the answer: recall@k and nDCG@10, computed with no model."""
+
+    model: str
+    questions: int
+    k: int
+    recall_at_k: float
+    ndcg_at_10: float
+    took_ms: float
+    misses: list[MemoryMiss]
+
+
+# A category is the agent's own word, a value is a literal the caller said, a supersession an id:
+# nothing is judged by comparing two sentences.
+class ExtractionExpected(WireModel):
+    """What must come of one call's hang-up."""
+
+    writes: list[str] = Field(default_factory=list[str])
+    never: list[str] = Field(default_factory=list[str])
+    never_says: list[str] = Field(default_factory=list[str])
+    invalidates: list[str] = Field(default_factory=list[str])
+
+
+class ExtractionGolden(WireModel):
+    """One call written down, what memory holds before it, and what memory must make of it."""
+
+    name: str
+    said: list[tuple[str, str]]
+    holds: list[str] = Field(default_factory=list[str])
+    plants: list[str] = Field(default_factory=list[str])
+    channel: Channel = "phone"
+    expect: ExtractionExpected = Field(default_factory=ExtractionExpected)
+
+
+class ExtractionCases(WireModel):
+    """POST /v1/agents/{slug}/memory/extraction, the body: one model call per case."""
+
+    # Fifty model calls in one request at most, on keys the box may lend.
+    cases: list[ExtractionGolden] = Field(max_length=50)
+
+
+class ExtractionBroke(WireModel):
+    """One check a case did not hold, and the evidence in a sentence."""
+
+    check: str
+    detail: str
+
+
+class ExtractionJudged(WireModel):
+    """One case run: what memory would have kept, what admission refused, what did not hold."""
+
+    name: str
+    held: bool
+    wrote: list[str] = Field(default_factory=list[str])
+    refused: list[str] = Field(default_factory=list[str])
+    broke: list[ExtractionBroke] = Field(default_factory=list[ExtractionBroke])
+
+
+class ExtractionRun(WireModel):
+    """POST /v1/agents/{slug}/memory/extraction, the answer: the model, how many held, each case."""
+
+    agent: str
+    model: str
+    cases: int
+    held: int
+    took_ms: float
+    results: list[ExtractionJudged]
+
+
+class FoundChunk(WireModel):
+    """One chunk a search found: the file it came from, the heading it sits under, its body."""
+
+    path: str
+    heading: str | None
+    text: str
+
+
+class SearchFound(WireModel):
+    """What search answers a call and an app's `this.knowledge.search`: the best chunks first."""
+
+    chunks: list[FoundChunk]

pinecall/wire/rest/settings.py

@@ -0,0 +1,184 @@
+"""The bodies of the settings doors: an agent's tuning and lexicon, versioned, and its canary."""
+
+from pydantic import Field
+
+from pinecall.domain.names import Env
+from pinecall.wire.frames import WireModel
+from pinecall.wire.parts import (
+    DocsConfig,
+    GreetingConfig,
+    HangupConfig,
+    MemoryConfig,
+    Pronunciation,
+    TurnConfig,
+)
+
+
+# Every field is optional: one left out is not set, and the runtime's own default stands for it.
+class SettingsBody(WireModel):
+    """An agent's settings as the org set them, per world and per scope."""
+
+    voice: str | None = None
+    tts: str | None = None
+    tts_model: str | None = None
+    stt: str | None = None
+    llm: str | None = None
+    language: str | None = None
+    greeting: GreetingConfig | None = None
+    hangup: HangupConfig | None = None
+    turn: TurnConfig | None = None
+    memory: MemoryConfig | None = None
+    record: bool | None = None
+    max_duration_s: int | None = None
+    llm_timeout_s: float | None = None
+    knowledge: str | None = None
+    bases: list[DocsConfig] | None = None
+
+
+class SettingsRow(WireModel):
+    """One kept version of an agent's settings: whose scope, which version, by whom, what."""
+
+    holder: str
+    version: int
+    author: str
+    note: str | None
+    set_at: float
+    config: SettingsBody
+
+
+class SettingsResponse(WireModel):
+    """GET /v1/agents/{slug}/settings: yours, the team's and production's newest, or null."""
+
+    world: Env
+    yours: SettingsRow | None
+    team: SettingsRow | None
+    production: SettingsRow | None
+
+
+class PutSettingsRequest(WireModel):
+    """PUT /v1/agents/{slug}/settings: the whole set, the version read, why, whose scope."""
+
+    config: SettingsBody
+    if_version: int | None = None
+    note: str | None = None
+    team: bool = False
+
+
+class HistoryQuery(WireModel):
+    """The query string of a history: whose scope, and how many versions at most."""
+
+    team: bool = False
+    limit: int = Field(default=20, ge=1, le=200)
+
+
+class SettingsHistoryResponse(WireModel):
+    """GET /v1/agents/{slug}/settings/history: one scope's versions, newest first."""
+
+    world: Env
+    holder: str
+    rows: list[SettingsRow]
+
+
+class SettingsDiffResponse(WireModel):
+    """GET /v1/agents/{slug}/settings/diff: this scope's newest against another's, by field."""
+
+    ours: SettingsRow | None
+    theirs: SettingsRow | None
+    changed: list[str]
+
+
+class RollbackSettingsRequest(WireModel):
+    """POST /v1/agents/{slug}/settings/rollback: the version to bring back, as a new one."""
+
+    version: int
+    team: bool = False
+
+
+# A share is whole percents: 0 keeps the version off every call without clearing the canary.
+class PutCanaryRequest(WireModel):
+    """PUT /v1/agents/{slug}/settings/canary: the version, its share of the calls, why, whose."""
+
+    version: int = Field(ge=1)
+    share: int = Field(ge=0, le=100)
+    note: str | None = None
+    team: bool = False
+
+
+class CanaryQuery(WireModel):
+    """The query string of a canary's read or clearing: whose scope."""
+
+    team: bool = False
+
+
+class CanaryRow(WireModel):
+    """The canary a scope stands on: which version takes how many calls in a hundred, by whom."""
+
+    holder: str
+    version: int
+    share: int
+    author: str
+    note: str | None
+    set_at: float
+
+
+class CanaryResponse(WireModel):
+    """GET, PUT and DELETE /v1/agents/{slug}/settings/canary: the scope's canary, or null."""
+
+    world: Env
+    holder: str
+    canary: CanaryRow | None
+
+
+class LexiconBody(WireModel):
+    """The agent's lexicon: how the voice says its words, and the words the ears must know."""
+
+    said: list[Pronunciation]
+    heard: list[str]
+
+
+class LexiconRow(WireModel):
+    """One kept version of the agent's lexicon."""
+
+    holder: str
+    version: int
+    author: str
+    note: str | None
+    set_at: float
+    lexicon: LexiconBody
+
+
+class LexiconResponse(WireModel):
+    """GET /v1/agents/{slug}/lexicon: yours, the team's and production's newest, or null."""
+
+    world: Env
+    yours: LexiconRow | None
+    team: LexiconRow | None
+    production: LexiconRow | None
+
+
+class PutLexiconRequest(WireModel):
+    """PUT /v1/agents/{slug}/lexicon: the whole lexicon, the version read, why, whose scope."""
+
+    lexicon: LexiconBody
+    if_version: int | None = None
+    note: str | None = None
+    team: bool = False
+
+
+class LexiconHistoryResponse(WireModel):
+    """GET /v1/agents/{slug}/lexicon/history: one scope's versions, newest first."""
+
+    world: Env
+    holder: str
+    rows: list[LexiconRow]
+
+
+class CallSettingsResponse(WireModel):
+    """GET /v1/calls/{call}/settings: the tuning and lexicon the call was built on."""
+
+    config_version: int | None
+    lexicon_version: int | None
+    config: SettingsRow | None
+    lexicon: LexiconRow | None
+    # The call ran a canary's version, picked for its share of the calls.
+    canary: bool = False