pinecall-runtime 0.1.6__py3-none-any.whl

pinecall/domain/agent.py

@@ -0,0 +1,446 @@
+"""What an agent declares (prompt, tools, voice, turns) and what the org sets on top of it."""
+
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from datetime import datetime
+from hashlib import sha256
+from typing import Literal
+
+from pinecall.domain.errors import DeclarationRefused
+from pinecall.domain.names import Json, parse_slug
+
+# public: the caller's browser. tenant: the console (default). pii: the console, masked.
+type Visibility = Literal["public", "tenant", "pii"]
+
+
+# app: the tenant's backend. participant: the caller's browser.
+type EventSource = Literal["app", "participant"]
+
+
+# irreversible tools (payments, cancellations) require the caller's confirmation, asked by the
+# platform rather than the model.
+type SideEffect = Literal["read", "write", "irreversible"]
+
+
+# static: before the history, provider-cached. dynamic: after it, rewritten every turn.
+type PromptRegion = Literal["static", "dynamic"]
+
+
+# retrieved: top chunks are injected every turn. tool: the model gets a search(query) tool.
+type DocsMode = Literal["retrieved", "tool"]
+
+
+# every-call: at every hang-up the org judges. simulations: only a call a persona played.
+type RunsOn = Literal["every-call", "simulations"]
+
+
+# The names the platform gives its verdicts, at hang-up and on a golden; a judge of the org's or an
+# agent's takes another, or a call would carry two verdicts under one name.
+PANEL_JUDGES: tuple[str, ...] = (
+    "consent",
+    "grounded",
+    "promises",
+    "persona",
+    "identified",
+    "disclosed",
+    "honoured_stop",
+    "heard",
+)
+
+
+# A name every model vendor accepts as a function name.
+_A_NAME_A_MODEL_CAN_CALL = re.compile(r"^[A-Za-z][A-Za-z0-9_]*$")
+
+
+# Written by the platform, never the app, so a knowledge file carries the operator's authority.
+KNOWLEDGE = "knowledge"
+
+
+DEFAULT_CHUNKS_PER_TURN = 8
+
+
+# The default ends abandoned lines and machine-to-machine loops; 0 is no limit, else 1 to 60 min.
+LONGEST_VOICE_CALL_S = 600
+
+
+SHORTEST_LIMIT_S = 60
+
+
+LONGEST_LIMIT_S = 3600
+
+
+NO_LIMIT = 0
+
+# How long a tool may run before the model hears it timed out.
+LONGEST_TOOL_S = 300
+
+
+# Unset knobs are None, never "": an empty string reaches the vendor as a value (an empty voice
+# once made every call silent).
+BLANK = (
+    "a blank {field} is not a change: an empty value once silenced a whole line of calls. "
+    "Leave the field out to go back to what the app declared."
+)
+
+
+@dataclass(frozen=True)
+class Voice:
+    """The agent's TTS voice."""
+
+    provider: str
+    model: str | None = None
+    voice_id: str | None = None
+
+
+@dataclass(frozen=True)
+class Model:
+    """An LLM or STT model and its temperature."""
+
+    provider: str
+    model: str
+    temperature: float | None = None
+
+
+@dataclass(frozen=True)
+class Turn:
+    """Turn detection and interruption settings."""
+
+    min_interruption_words: int | None = None
+    endpointing_ms: int | None = None
+    # Deepgram reports its default (0.7) ends up to a fifth of turns early.
+    eot_threshold: float | None = None
+    # The lower bar that starts LiveKit's speculative generation, offsetting a higher eot.
+    eager_eot_threshold: float | None = None
+    # How long the caller must speak over the agent before it stops; None is livekit's 0.5 s.
+    min_interruption_ms: int | None = None
+
+    # Deepgram rejects the connection when eager > eot, leaving the call without STT.
+    def __post_init__(self) -> None:
+        counts = {
+            "min_interruption_ms": self.min_interruption_ms,
+            "endpointing_ms": self.endpointing_ms,
+            "min_interruption_words": self.min_interruption_words,
+        }
+        for name, value in counts.items():
+            if value is not None and value < 0:
+                raise DeclarationRefused(f"{name} is a count, 0 or more")
+        if self.eager_eot_threshold is None or self.eot_threshold is None:
+            return
+        if self.eager_eot_threshold > self.eot_threshold:
+            raise DeclarationRefused(
+                f"eager_eot_threshold {self.eager_eot_threshold} is the bar for GUESSING the turn "
+                f"is over, so it cannot sit above eot_threshold {self.eot_threshold}, which is the "
+                "bar for ending it."
+            )
+
+
+@dataclass(frozen=True)
+class Greeting:
+    """The opening turn: fixed words (`say`) or an instruction for the model (`reply`)."""
+
+    say: str | None = None
+    reply: str | None = None
+    allow_interruptions: bool | None = None
+
+    def __post_init__(self) -> None:
+        if (self.say is None) == (self.reply is None):
+            text = "both were declared" if self.say is not None else "neither was"
+            raise DeclarationRefused(
+                "a greeting is one of two things: `say` the words, or `reply` what the model "
+                f"reads before it finds its own. {text} — pick one."
+            )
+
+
+@dataclass(frozen=True)
+class Hangup:
+    """Lets the model end the call, with instructions on when."""
+
+    when: str = ""
+
+
+@dataclass(frozen=True)
+class ToolSpec:
+    """A tool as the app declares it, validated on construction."""
+
+    name: str
+    description: str
+    parameters: Mapping[str, Json]
+    side_effect: SideEffect = "read"
+    pii: frozenset[str] = frozenset()
+    confirm: str | None = None
+    preview: int | None = None
+    timeout_s: float = 30.0
+
+    def __post_init__(self) -> None:
+        if not _A_NAME_A_MODEL_CAN_CALL.match(self.name):
+            raise DeclarationRefused(f"a tool name is one word a model can call, not {self.name!r}")
+        if not self.description.strip():
+            raise DeclarationRefused(
+                f"tool {self.name}: without a description no model can choose it"
+            )
+        if self.parameters.get("type") != "object":
+            raise DeclarationRefused(
+                f"tool {self.name}: parameters are a JSON Schema of type object"
+            )
+        if self.side_effect == "irreversible" and not self.confirm:
+            raise DeclarationRefused(
+                f"tool {self.name}: an irreversible tool needs a confirm template to read back"
+            )
+        if unknown := self.pii - self.parameter_names:
+            raise DeclarationRefused(
+                f"tool {self.name}: pii names parameters the tool has; unknown: {sorted(unknown)}"
+            )
+        if self.preview is not None and self.preview < 1:
+            raise DeclarationRefused(f"tool {self.name}: a preview shows at least one item")
+        # The caller waits in silence or on the melody while a tool runs: five minutes at most.
+        if not 0 < self.timeout_s <= LONGEST_TOOL_S:
+            raise DeclarationRefused(
+                f"tool {self.name}: timeout_s is seconds above 0, {LONGEST_TOOL_S} at most"
+            )
+
+    @property
+    def parameter_names(self) -> frozenset[str]:
+        """Return the property names of the parameter schema."""
+        properties = self.parameters.get("properties")
+        return frozenset(properties) if isinstance(properties, dict) else frozenset()
+
+
+@dataclass(frozen=True)
+class PromptBlock:
+    """A named prompt block and its region."""
+
+    name: str
+    region: PromptRegion
+
+
+@dataclass(frozen=True)
+class Docs:
+    """A knowledge base the agent uses, and how results reach the model."""
+
+    base: str
+    mode: DocsMode = "retrieved"
+    k: int = DEFAULT_CHUNKS_PER_TURN
+    min_score: float | None = None
+
+    def __post_init__(self) -> None:
+        if not self.base:
+            raise DeclarationRefused("docs name the knowledge base they were pushed to")
+        if self.k < 1:
+            raise DeclarationRefused("docs hand the model at least one chunk")
+        if self.min_score is not None and self.min_score < 0:
+            raise DeclarationRefused("a fused rank score is never negative; min_score cannot be")
+
+
+@dataclass(frozen=True)
+class KnowledgeFile:
+    """One file pushed to a knowledge base."""
+
+    path: str
+    text: str
+
+    def __post_init__(self) -> None:
+        if not self.path:
+            raise DeclarationRefused("a knowledge file is named by its path")
+
+
+# Free-text categories; anything under `forget` is never stored, whatever the model extracts.
+@dataclass(frozen=True)
+class MemoryPolicy:
+    """What memory keeps about a contact across calls, and what it never keeps."""
+
+    remember: tuple[str, ...] = ()
+    forget: tuple[str, ...] = ()
+
+    def __post_init__(self) -> None:
+        if both := set(self.remember) & set(self.forget):
+            raise DeclarationRefused(f"memory cannot both remember and forget {sorted(both)}")
+
+
+@dataclass(frozen=True)
+class Tuning:
+    """One agent's settings; every knob is None until set."""
+
+    voice: str | None = None
+    tts: str | None = None
+    tts_model: str | None = None
+    stt: str | None = None
+    llm: str | None = None
+    # A tag (`en`, `pt-BR`); None leaves each vendor its own default.
+    language: str | None = None
+    greeting: Greeting | None = None
+    hangup: Hangup | None = None
+    turn: Turn | None = None
+    memory: MemoryPolicy | None = None
+    # Tri-state so an explicit False still overrides the layer below.
+    record: bool | None = None
+    # Voice calls only; 0 is no limit, None is the runtime default.
+    max_duration_s: int | None = None
+    # How long a turn waits for the model's first token; None waits as long as livekit retries.
+    llm_timeout_s: float | None = None
+    # Markdown placed whole in the static knowledge block; editable with the `words` scope.
+    knowledge: str | None = None
+    # An empty tuple means "none" and overrides the layer below; None means unset.
+    bases: tuple[Docs, ...] | None = None
+
+    def __post_init__(self) -> None:
+        knobs = (
+            ("voice", self.voice),
+            ("tts", self.tts),
+            ("tts_model", self.tts_model),
+            ("stt", self.stt),
+            ("llm", self.llm),
+            ("language", self.language),
+            ("knowledge", self.knowledge),
+        )
+        for name, value in knobs:
+            if value is not None and not value.strip():
+                raise DeclarationRefused(BLANK.format(field=name))
+        if self.max_duration_s is not None:
+            _check_call_limit(self.max_duration_s)
+        if self.llm_timeout_s is not None and self.llm_timeout_s <= 0:
+            raise DeclarationRefused("llm_timeout_s is a positive number of seconds")
+
+
+@dataclass(frozen=True)
+class Lexicon:
+    """An agent's lexicon: TTS pronunciations and STT keyterms."""
+
+    said: Mapping[str, str] = field(default_factory=dict[str, str])
+    heard: tuple[str, ...] = ()
+
+    def __post_init__(self) -> None:
+        _check_pronunciations(self.said, "the lexicon")
+        if any(not word.strip() for word in self.heard):
+            raise DeclarationRefused("the lexicon: a word the ears must know is not blank")
+
+
+@dataclass(frozen=True)
+class Version[T]:
+    """A stored version of a value, with its holder, number, author and timestamp."""
+
+    holder: str
+    version: int
+    author: str
+    note: str | None
+    set_at: datetime
+    value: T
+
+
+# Stored on the call's head row so the exact configuration can be read back later.
+@dataclass(frozen=True)
+class Versions:
+    """Tuning and lexicon versions a call was built on; None where nothing was set."""
+
+    config: int | None = None
+    lexicon: int | None = None
+
+
+@dataclass(frozen=True)
+class AgentJudge:
+    """A question the org wrote about one agent's job, put to the judge model at hang-up."""
+
+    name: str
+    question: str
+    runs_on: RunsOn = "every-call"
+
+
+DEFAULT_LAYOUT: tuple[PromptBlock, ...] = (
+    PromptBlock("identity", "static"),
+    PromptBlock(KNOWLEDGE, "static"),
+    PromptBlock("tools", "static"),
+    PromptBlock("view", "dynamic"),
+)
+
+
+# Field names match the wire's AgentConfig (tests/domain/test_names.py holds them to it, from
+# TWINS in tests/domain/conftest.py).
+@dataclass(frozen=True)
+class AgentConfig:
+    """An agent's resolved declaration."""
+
+    slug: str
+    name: str | None = None
+    prompt: tuple[PromptBlock, ...] = DEFAULT_LAYOUT
+    greeting: Greeting | None = None
+    language: str | None = None
+    voice: Voice | None = None
+    llm: Model | None = None
+    stt: Model | None = None
+    turn: Turn | None = None
+    says: Mapping[str, str] = field(default_factory=dict[str, str])
+    hears: tuple[str, ...] = ()
+    # From Tuning.knowledge; placed whole in the static knowledge block.
+    knowledge: str | None = None
+    bases: tuple[Docs, ...] = ()
+    # The class calls `this.knowledge.search`; registration fails when no base is attached.
+    uses_knowledge: bool = False
+    memory: MemoryPolicy | None = None
+    hangup: Hangup | None = None
+    record: bool = True
+    max_duration_s: int = LONGEST_VOICE_CALL_S
+    # None: no deadline of ours, so livekit's own retries decide how long a turn waits.
+    llm_timeout_s: float | None = None
+    tools: tuple[ToolSpec, ...] = ()
+    state_fields: Mapping[str, Visibility] = field(default_factory=dict[str, Visibility])
+    # Side-panel title only; the console fetches its contents from the app, so tenant data
+    # never passes through the gateway's config.
+    view: str | None = None
+    events: Mapping[str, frozenset[EventSource]] = field(
+        default_factory=dict[str, frozenset[EventSource]]
+    )
+
+    def __post_init__(self) -> None:
+        parse_slug(self.slug)
+        names = [tool.name for tool in self.tools]
+        if repeated := {name for name in names if names.count(name) > 1}:
+            raise DeclarationRefused(f"agent {self.slug}: tool names repeat: {sorted(repeated)}")
+        blocks = [block.name for block in self.prompt]
+        if repeated := {name for name in blocks if blocks.count(name) > 1}:
+            raise DeclarationRefused(
+                f"agent {self.slug}: prompt block names repeat: {sorted(repeated)}"
+            )
+        _check_pronunciations(self.says, f"agent {self.slug}")
+        _check_call_limit(self.max_duration_s)
+        for event, sources in self.events.items():
+            if not event or not sources:
+                raise DeclarationRefused(
+                    f"agent {self.slug}: event {event!r} names who may send it: app, participant"
+                )
+
+    def visibility_of(self, state_field: str) -> Visibility:
+        """Return a state field's visibility, tenant unless declared."""
+        return self.state_fields.get(state_field, "tenant")
+
+    def accepts(self, event: str, source: EventSource) -> bool:
+        """Return whether the event may be sent by this source."""
+        return source in self.events.get(event, frozenset())
+
+    @property
+    def tools_by_name(self) -> Mapping[str, ToolSpec]:
+        """Return the tools keyed by name."""
+        return {tool.name: tool for tool in self.tools}
+
+
+# The log keeps a block's hash, never its words (prompt.changed); the org's prompts keep the words
+# under the same hash, so a call's prompt is read back whole.
+def block_hash(text: str) -> str:
+    """A block of the prompt as the log names it: the sha256 of its text."""
+    return sha256(text.encode()).hexdigest()
+
+
+def _check_call_limit(seconds: int) -> None:
+    """Raise DeclarationRefused unless seconds is 0 or between 60 and 3600."""
+    if seconds != NO_LIMIT and not SHORTEST_LIMIT_S <= seconds <= LONGEST_LIMIT_S:
+        raise DeclarationRefused(
+            f"max_duration_s {seconds}: 0 for no limit, or {SHORTEST_LIMIT_S} to "
+            f"{LONGEST_LIMIT_S} seconds (1 to 60 minutes)"
+        )
+
+
+def _check_pronunciations(says: Mapping[str, str], owner: str) -> None:
+    """Raise DeclarationRefused when a word or its spoken form is blank."""
+    if blank := {word for word, spoken in says.items() if not word or not spoken}:
+        raise DeclarationRefused(
+            f"{owner}: a pronunciation is a word and how it is said: {sorted(blank)}"
+        )

pinecall/domain/call.py

@@ -0,0 +1,152 @@
+"""What a call is: its id, direction, who is calling, the route it came in by, its day."""
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from datetime import UTC, date, datetime
+from typing import Literal
+from uuid import uuid4
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+
+from pinecall.domain.errors import DeclarationRefused
+from pinecall.domain.names import (
+    CHANNELS_WITH_A_NUMBER,
+    PRODUCTION,
+    Channel,
+    Direction,
+    Env,
+    Json,
+    dialable,
+)
+
+# Prefix of call ids minted here (`call_` + 32 hex); phone calls are named by the media plane.
+A_CALL = "call_"
+
+# Who opened a call's log: the fleet's worker, an org's own worker (an app key), or the gateway
+# for a written call. The worker doors of a fleet's call take the fleet's key alone.
+type Opener = Literal["fleet", "app", "gateway"]
+
+
+@dataclass(frozen=True)
+class Contact:
+    """What is known about the caller; a web visitor may be anonymous."""
+
+    id: str | None = None
+    phone: str | None = None
+    name: str | None = None
+    email: str | None = None
+    external_id: str | None = None
+
+
+@dataclass(frozen=True)
+class Route:
+    """Which agent answers on a channel and number, and which org owns it."""
+
+    org: str
+    agent: str
+    channel: Channel
+    number: str | None = None
+    label: str | None = None
+    # A number belongs to one environment; the registry refuses it in the other.
+    env: Env = PRODUCTION
+    # Bought on the box's carrier account, so it counts against the `numbers` quota; numbers
+    # imported from the tenant's own account do not.
+    managed: bool = False
+
+    def __post_init__(self) -> None:
+        if not self.org or not self.agent:
+            raise DeclarationRefused(
+                "a route names the org that owns it and the agent that answers"
+            )
+        if self.channel in CHANNELS_WITH_A_NUMBER:
+            if self.number is None or not dialable(self.number):
+                raise DeclarationRefused(
+                    f"a {self.channel} route answers at a number in E.164 form, not {self.number!r}"
+                )
+        elif self.number is not None:
+            raise DeclarationRefused(f"the {self.channel} widget answers at no number")
+
+    @property
+    def door(self) -> tuple[Channel, str | None]:
+        """Return (channel, number): the registry's key, whatever the org or the label."""
+        return (self.channel, self.number)
+
+
+# Immutable: whatever changes during a call is recorded in the log.
+@dataclass(frozen=True)
+class CallContext:
+    """A call as the worker and the gateway see it when it starts."""
+
+    call: str
+    channel: Channel
+    direction: Direction
+    caller: str
+    route: Route
+    today: date
+    contact: Contact | None = None
+    metadata: Mapping[str, Json] = field(default_factory=dict[str, Json])
+    # Eval run that opened the call; None for a real caller.
+    run: str | None = None
+    # Simulated caller's name, and its rules frozen at call start so judging ignores later edits.
+    persona: str | None = None
+    accepts_when: str | None = None
+    declines_when: str | None = None
+    # Sandbox developer the call belongs to; None for the org itself.
+    holder: str | None = None
+    # The state the call opens in, when a golden, a persona or `?state=` asked for one.
+    state: Mapping[str, Json] = field(default_factory=dict[str, Json])
+
+    def __post_init__(self) -> None:
+        if not self.call:
+            raise DeclarationRefused("a call context names its call")
+        if not self.caller:
+            raise DeclarationRefused("a call has a calling side: a number, or the visitor id")
+        if self.route.channel != self.channel:
+            raise DeclarationRefused(
+                f"a {self.channel} call cannot come through a {self.route.channel} route"
+            )
+
+    @property
+    def env(self) -> Env:
+        """Return the environment of the call's route."""
+        return self.route.env
+
+    # The app's contact id, else the number, so phone and WhatsApp calls share one contact.
+    @property
+    def remembered_as(self) -> str | None:
+        """Return the memory key for the caller, or None when the caller is anonymous."""
+        if self.contact is not None and self.contact.id:
+            return self.contact.id
+        return self.caller if self.channel in CHANNELS_WITH_A_NUMBER else None
+
+
+# A carrier bills each leg on its own, by the number at the end of it: the box's own number when
+# the call came in, the dialled one when it went out.
+@dataclass(frozen=True)
+class PhoneLeg:
+    """One leg of a call on the phone network, and how long it was up."""
+
+    # `twilio`, or `sip` for a trunk the box knows only by its address.
+    carrier: str
+    direction: Direction
+    number: str
+    seconds: float
+
+
+def new_call_id() -> str:
+    """Mint a call id; it is also the LiveKit room name."""
+    return f"{A_CALL}{uuid4().hex}"
+
+
+def parse_zone(zone: str) -> ZoneInfo:
+    """Return the IANA zone, raising DeclarationRefused when there is none by that name."""
+    try:
+        return ZoneInfo(zone)
+    except (ZoneInfoNotFoundError, ValueError) as unknown:
+        raise DeclarationRefused(
+            f"{zone!r} is not an IANA time zone (Europe/Madrid, America/Montevideo, UTC)"
+        ) from unknown
+
+
+def today_in(zone: str) -> date:
+    """Return today's date in the zone: a call is dated where the caller is, not the box."""
+    return datetime.now(UTC).astimezone(parse_zone(zone)).date()

pinecall/domain/country_codes.py

@@ -0,0 +1,32 @@
+"""E.164 country calling codes, the satellite ranges never dialled, the shortest national number."""
+
+# E.164 country calling codes, matched longest first; no longer code starts with 1 or 7.
+CALLING_CODES: frozenset[str] = frozenset(
+    {
+        "1", "7", "20", "27", "30", "31", "32", "33", "34", "36", "39", "40", "41", "43", "44",
+        "45", "46", "47", "48", "49", "51", "52", "53", "54", "55", "56", "57", "58", "60",
+        "61", "62", "63", "64", "65", "66", "81", "82", "84", "86", "90", "91", "92", "93",
+        "94", "95", "98", "211", "212", "213", "216", "218", "220", "221", "222", "223", "224",
+        "225", "226", "227", "228", "229", "230", "231", "232", "233", "234", "235", "236",
+        "237", "238", "239", "240", "241", "242", "243", "244", "245", "246", "247", "248",
+        "249", "250", "251", "252", "253", "254", "255", "256", "257", "258", "260", "261",
+        "262", "263", "264", "265", "266", "267", "268", "269", "290", "291", "297", "298",
+        "299", "350", "351", "352", "353", "354", "355", "356", "357", "358", "359", "370",
+        "371", "372", "373", "374", "375", "376", "377", "378", "379", "380", "381", "382",
+        "383", "385", "386", "387", "389", "420", "421", "423", "500", "501", "502", "503",
+        "504", "505", "506", "507", "508", "509", "590", "591", "592", "593", "594", "595",
+        "596", "597", "598", "599", "670", "672", "673", "674", "675", "676", "677", "678",
+        "679", "680", "681", "682", "683", "685", "686", "687", "688", "689", "690", "691",
+        "692", "800", "808", "850", "852", "853", "855", "856", "870", "878", "880", "881",
+        "882", "883", "886", "888", "960", "961", "962", "963", "964", "965", "966", "967",
+        "968", "970", "971", "972", "973", "974", "975", "976", "977", "979", "992", "993",
+        "994", "995", "996", "998",
+    }
+)  # fmt: skip
+
+# Satellite and global-service ranges: where international revenue-share fraud is dialled, and
+# never a number that called anybody back.
+NEVER_DIALLED = ("870", "878", "881", "882", "883", "888", "979")
+
+# Shorter national numbers are short codes, service numbers or typos.
+SHORTEST_NATIONAL = 5