pinecall-runtime 0.1.6__py3-none-any.whl

pinecall/providers/catalog.py

@@ -0,0 +1,266 @@
+"""The box's providers configuration: one row in Postgres the operator edits from the console."""
+
+from collections.abc import Iterable
+from typing import Literal
+
+from psycopg.types.json import Jsonb
+from pydantic import BaseModel, ConfigDict, Field
+
+from pinecall.domain.errors import Conflict, DeclarationRefused, NotAvailable
+from pinecall.domain.names import Json, JsonObject
+from pinecall.postgres.pool import Pool
+from pinecall.process import box_settings
+from pinecall.providers.build import MODALITIES, Modality, TurnModel, doing
+
+ROW = "providers"
+
+SEED = """
+INSERT INTO box_settings (name, value) VALUES (%(name)s, %(value)s)
+ON CONFLICT (name) DO NOTHING
+RETURNING name
+"""
+
+# The width of every halfvec column that holds a vector.
+VECTOR_WIDTH = 1024
+
+UNSET = (
+    "this box has no providers configuration yet: the operator writes it from the console, or "
+    "`pinecall-runtime providers seed` writes the one it starts from"
+)
+
+
+NO_JUDGE_FALLBACK = "the judge runs on one model: fallbacks are for the stages of a call"
+
+NESTED = "{modality} fallback {vendor}: a fallback names no fallbacks of its own"
+
+ASKED_OF_A_MODEL = "{key}: `request` is what a model is asked beside the conversation, so only llm"
+
+TURN_ENDED_OTHERWISE = (
+    "stt fallback {vendor}: it {how} and {primary} does the other; the session reads the end "
+    "of the turn one way for the whole call, so every vendor of the stage must end it alike"
+)
+
+
+class Stage(BaseModel):
+    """A vendor and, when not the plugin's own, its model; a default names who takes over."""
+
+    model_config = ConfigDict(frozen=True)
+
+    vendor: str
+    model: str | None = None
+    # A default stage's vendors in the order they take over when the one before fails.
+    fallbacks: tuple["Stage", ...] = ()
+
+
+class Rate(BaseModel):
+    """What a model costs in US dollars: per million tokens, per character, second or minute."""
+
+    model_config = ConfigDict(frozen=True)
+
+    input: float | None = None
+    output: float | None = None
+    # Omitted, a cache read costs what fresh input does.
+    cached_input: float | None = None
+    cache_creation: float | None = None
+    characters: float | None = None
+    audio_seconds: float | None = None
+    # A phone leg's minute, each one begun billed whole.
+    minutes: float | None = None
+    as_of: str = ""
+
+
+class StageOptions(BaseModel):
+    """What one vendor is told for one stage: which class it builds and the kwargs it is given."""
+
+    model_config = ConfigDict(frozen=True)
+
+    # The plugin's class where it is not the one named LLM, STT or TTS (`STTv2`).
+    builds: str | None = None
+    options: JsonObject = Field(default_factory=dict[str, Json])
+    # The ears end the turn themselves, so the session stacks no detector on top.
+    ends_the_turn: bool = False
+    # Where they do not, which local model reads the end of the turn off the audio.
+    turn_model: TurnModel = "v1-mini"
+    # What every request of an llm stage carries beside the conversation, in the vendor's own
+    # field names (`{"thinking": {"type": "disabled"}}`): livekit's extra_kwargs, each request.
+    request: JsonObject = Field(default_factory=dict[str, Json])
+
+
+class KeptVoice(BaseModel):
+    """A voice the row lists for a vendor, as a picker shows it: its id and what to choose by."""
+
+    model_config = ConfigDict(frozen=True)
+
+    id: str
+    name: str
+    gender: str = ""
+    # Where the accent is from: `ES`, `MX`; a language code does not tell them apart.
+    country: str = ""
+    accent: str = ""
+    description: str = ""
+
+
+class Judge(BaseModel):
+    """The model that judges a finished call, on the box's key, and what one call may spend."""
+
+    model_config = ConfigDict(frozen=True)
+
+    llm: Stage
+    ceiling_usd: float
+
+
+class Caller(BaseModel):
+    """What one simulated call's caller may spend, its lines and its voice, before it hangs up."""
+
+    model_config = ConfigDict(frozen=True)
+
+    ceiling_usd: float = Field(gt=0)
+
+
+class Embedding(BaseModel):
+    """The one embedder this box runs, on its own key; every base and fact is in its space."""
+
+    model_config = ConfigDict(frozen=True)
+
+    # The box's `credentials/<vendor>` row holds its key.
+    vendor: str
+    url: str
+    model: str
+    # Two wire formats: `embeddings` takes texts, `contextual` takes documents of chunks.
+    shape: Literal["embeddings", "contextual"]
+    dimensions: int = VECTOR_WIDTH
+
+
+class Providers(BaseModel):
+    """The operator's choices: defaults, what each vendor is told, what a model costs, the judge."""
+
+    model_config = ConfigDict(frozen=True)
+
+    # The stage an agent runs where it names no vendor.
+    defaults: dict[Modality, Stage]
+    # `tts/elevenlabs`: the model a vendor named alone runs, where the plugin's own is not.
+    models: dict[str, str] = Field(default_factory=dict[str, str])
+    # `cartesia/es`: the voice an agent that names none speaks with.
+    voices: dict[str, str] = Field(default_factory=dict[str, str])
+    # `cartesia/es`: the voices a picker offers, where the vendor's plugin lists none of its own.
+    listed: dict[str, tuple[KeptVoice, ...]] = Field(
+        default_factory=dict[str, tuple[KeptVoice, ...]]
+    )
+    # `stt/deepgram`: what that vendor is told for that stage; `llm/anthropic/claude-haiku-5-5`
+    # for the models whose id starts so, the longest such key replacing the vendor's whole.
+    tuning: dict[str, StageOptions] = Field(default_factory=dict[str, StageOptions])
+    # Languages the ears listen for beside the call's own.
+    hints: tuple[str, ...] = ()
+    # A model's price, by the longest prefix of its id: dated snapshots price by family.
+    rates: dict[str, Rate] = Field(default_factory=dict[str, Rate])
+    judge: Judge | None = None
+    # Absent: a simulated caller spends what its turns ask, as before the row named one.
+    caller: Caller | None = None
+    # `es`: the line a voice reads in the picker.
+    lines: dict[str, str] = Field(default_factory=dict[str, str])
+    embedding: Embedding | None = None
+
+
+def tuning_of(
+    configured: Providers, modality: Modality, vendor: str, model: str | None
+) -> StageOptions | None:
+    """What a vendor is told for a stage: the longest key naming the model's id, else its own."""
+    stage = f"{modality}/{vendor}"
+    models = (
+        key.removeprefix(f"{stage}/") for key in configured.tuning if key.startswith(f"{stage}/")
+    )
+    named = None if model is None else longest_prefix(models, model)
+    return configured.tuning.get(stage if named is None else f"{stage}/{named}")
+
+
+def longest_prefix(keys: Iterable[str], name: str) -> str | None:
+    """The longest of the keys the name starts with, so a dated snapshot reads as its family."""
+    listed = [key for key in keys if name.startswith(key)]
+    return max(listed, key=len) if listed else None
+
+
+def judge_ceiling(configured: Providers) -> float | None:
+    """What one call may spend on the box's judge, or None where the row names no judge."""
+    return None if configured.judge is None else configured.judge.ceiling_usd
+
+
+async def providers(pool: Pool) -> Providers:
+    """The box's configuration; NotAvailable until it was written."""
+    async with pool.connection() as connection:
+        value = await box_settings.read(connection, ROW)
+    if value is None:
+        raise NotAvailable(UNSET)
+    return Providers.model_validate(value)
+
+
+async def configure(pool: Pool, edited: Providers) -> None:
+    """Write the configuration whole, as the console's box screen sends it."""
+    checked(edited)
+    async with pool.connection() as connection:
+        await box_settings.write(connection, ROW, edited.model_dump(mode="json"))
+
+
+async def seed(pool: Pool, seeded: Providers) -> None:
+    """Write the configuration a box starts from; Conflict when one is already there."""
+    checked(seeded)
+    async with pool.connection() as connection:
+        written = await connection.execute(
+            SEED, {"name": ROW, "value": Jsonb(seeded.model_dump(mode="json"))}
+        )
+        if await written.fetchone() is None:
+            raise Conflict("this box is configured already: the console edits what is there")
+
+
+# A row that names a vendor nobody installed, or for a stage it does not do, is refused where it
+# is written, not on the first call that reads it.
+def checked(written: Providers) -> Providers:
+    """The configuration: each vendor installed and doing its stage, the embedder at 1024 wide."""
+    for modality, stage in written.defaults.items():
+        doing(stage.vendor, modality)
+        for fallback in stage.fallbacks:
+            _a_fallback(written, modality, stage, fallback)
+    for key in written.models:
+        _a_stage_key(key)
+    for key, options in written.tuning.items():
+        if _a_stage_key(key) != "llm" and options.request:
+            raise DeclarationRefused(ASKED_OF_A_MODEL.format(key=key))
+    for key in (*written.voices, *written.listed):
+        doing(key.partition("/")[0], "tts")
+    if written.judge is not None:
+        doing(written.judge.llm.vendor, "llm")
+        if written.judge.llm.fallbacks:
+            raise DeclarationRefused(NO_JUDGE_FALLBACK)
+    if written.embedding is not None and written.embedding.dimensions != VECTOR_WIDTH:
+        raise DeclarationRefused(
+            f"the embedder answers {written.embedding.dimensions}-wide vectors; every vector "
+            f"column is halfvec({VECTOR_WIDTH}), so it must be asked for {VECTOR_WIDTH}"
+        )
+    return written
+
+
+# `stt/deepgram`, or `llm/anthropic/claude-haiku-5-5` where the key names a model of the vendor.
+def _a_stage_key(key: str) -> Modality:
+    modality, _, vendor = key.partition("/")
+    if modality not in MODALITIES:
+        raise DeclarationRefused(f"{key!r}: a stage is one of {', '.join(MODALITIES)}")
+    doing(vendor.partition("/")[0], modality)
+    return modality
+
+
+# The ears are chosen once for the whole session: a fallback that ends the turn itself where the
+# primary does not (or the reverse) would leave the call with nobody ending the caller's turn.
+def _a_fallback(written: Providers, modality: Modality, primary: Stage, fallback: Stage) -> None:
+    doing(fallback.vendor, modality)
+    if fallback.fallbacks:
+        raise DeclarationRefused(NESTED.format(modality=modality, vendor=fallback.vendor))
+    if modality != "stt" or _ends_the_turn(written, fallback) == _ends_the_turn(written, primary):
+        return
+    how = "ends the turn itself" if _ends_the_turn(written, fallback) else "leaves the turn open"
+    raise DeclarationRefused(
+        TURN_ENDED_OTHERWISE.format(vendor=fallback.vendor, how=how, primary=primary.vendor)
+    )
+
+
+def _ends_the_turn(written: Providers, stage: Stage) -> bool:
+    options = tuning_of(written, "stt", stage.vendor, stage.model)
+    return options is not None and options.ends_the_turn

pinecall/providers/credentials.py

@@ -0,0 +1,230 @@
+"""Whose key each stage of a call runs on: the org's own runs anything, the box's what it lends."""
+
+import dataclasses
+import logging
+import re
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass, field
+from typing import Literal
+
+from pinecall.domain.agent import AgentConfig, Model, Voice
+from pinecall.domain.errors import DeclarationRefused, NotAllowed, NotAvailable
+from pinecall.domain.names import Credentials
+from pinecall.providers.build import Modality, Running, Vendor, installed, primary
+from pinecall.providers.catalog import Providers, tuning_of
+from pinecall.providers.declared import SEPARATOR
+
+# yours: the org brought its key. offered: the box holds one and lends it to this org. bring your
+# own: installed, and nobody but the org can key it. broken: its plugin does not import.
+type Availability = Literal["yours", "offered", "bring your own", "broken"]
+
+logger = logging.getLogger(__name__)
+
+
+# What a dated snapshot adds to a model's name: `-20251001`, `-2025-08-07`, `@20240229`.
+A_SNAPSHOT = re.compile(r"[-@](\d{8}|\d{4}-\d{2}-\d{2})")
+
+
+@dataclass(frozen=True)
+class Keyring:
+    """What a call may run on: the org's own credentials, the box's, and what the box lends it."""
+
+    own: Mapping[str, Credentials] = field(default_factory=dict[str, Credentials])
+    box: Mapping[str, Credentials] = field(default_factory=dict[str, Credentials])
+    # quotas.lends: None lends everything the box holds, empty lends nothing.
+    lends: frozenset[str] | None = None
+
+
+@dataclass(frozen=True)
+class Pipeline:
+    """The three stages of a voice call, each on the key it runs on."""
+
+    llm: Running
+    stt: Running
+    tts: Running
+
+    # The gateway keeps these with the call's facts: their usage is the operator's to bill.
+    @property
+    def lent(self) -> list[str]:
+        """The vendors the call may run on the box's key, in stage order, once each."""
+        stages = (self.llm, self.stt, self.tts)
+        each = (item for stage in stages for item in (stage, *stage.fallbacks))
+        return list(dict.fromkeys(item.vendor for item in each if item.lent))
+
+    # The row's order stands but for the vendors `failing` names (over their error line now),
+    # which go last, among themselves in the row's order too.
+    def demoting(self, failing: frozenset[str]) -> "Pipeline":
+        """The same stages, each with the vendors failing now behind the ones that are not."""
+        return Pipeline(
+            llm=_behind(self.llm, failing),
+            stt=_behind(self.stt, failing),
+            tts=_behind(self.tts, failing),
+        )
+
+
+@dataclass(frozen=True)
+class Readiness:
+    """One vendor as `GET /v1/providers` shows it to an org: what it does, and whose key runs it."""
+
+    name: str
+    does: tuple[Modality, ...]
+    availability: Availability
+    broken: str | None = None
+
+
+def readiness(installed: Mapping[str, Vendor], keys: Keyring) -> list[Readiness]:
+    """Every installed vendor, sorted, and how this org may run it."""
+    return [
+        Readiness(
+            name=vendor.name,
+            does=tuple(sorted(vendor.does)),
+            availability=_availability_of(vendor, keys),
+            broken=vendor.broken,
+        )
+        for vendor in sorted(installed.values(), key=lambda one: one.name)
+    ]
+
+
+def pipeline(config: AgentConfig, configured: Providers, keys: Keyring) -> Pipeline:
+    """The stages an agent runs: its vendors or the defaults, each with its key and options."""
+    language = primary(config.language)
+    llm = thinking(config, configured, keys)
+    stt = stage("stt", config.stt, configured, keys)
+    tts = stage("tts", config.voice, configured, keys)
+    heard = dict.fromkeys(item for item in (language, *configured.hints) if item)
+    voice = config.voice.voice_id if config.voice else None
+    ears = (
+        dataclasses.replace(item, language=language, hints=tuple(heard))
+        for item in (stt, *stt.fallbacks)
+    )
+    # The agent's voice is its vendor's; a vendor that takes over speaks the row's for the language.
+    voices = (
+        dataclasses.replace(
+            item,
+            language=language,
+            voice=(voice if item is tts else None)
+            or configured.voices.get(f"{item.vendor}{SEPARATOR}{language}"),
+        )
+        for item in (tts, *tts.fallbacks)
+    )
+    return Pipeline(llm=llm, stt=_over(*ears), tts=_over(*voices))
+
+
+# A written call runs this stage alone: a call with no voice is not refused for want of one.
+def thinking(config: AgentConfig, configured: Providers, keys: Keyring) -> Running:
+    """The model an agent thinks with, on its key, at the temperature it declared."""
+    llm = stage("llm", config.llm, configured, keys)
+    if config.llm is None or config.llm.temperature is None:
+        return llm
+    return dataclasses.replace(llm, options={**llm.options, "temperature": config.llm.temperature})
+
+
+def running(keys: Keyring, vendor: str, model: str | None) -> Running:
+    """The vendor on the org's own key, else on a key the box lends; refused before the call."""
+    own = keys.own.get(vendor)
+    if own is not None:
+        return Running(vendor=vendor, credentials=own, model=model)
+    box = keys.box.get(vendor)
+    if box is None:
+        raise NotAvailable(f"{vendor} has no key: the org brought none and the box holds none")
+    if not lent(keys.lends, vendor, model):
+        raise NotAllowed(refusal(keys.lends or frozenset(), vendor, model))
+    return Running(vendor=vendor, credentials=box, model=model, lent=True)
+
+
+# A model entry lends itself and its dated snapshots (`anthropic/claude-haiku-5-5` lends
+# `claude-haiku-5-5-20261001`), never a sibling that only starts the same (`openai/gpt-5` lends no
+# `gpt-5-pro`); a plugin's own default needs the whole vendor.
+def lent(lends: frozenset[str] | None, vendor: str, model: str | None) -> bool:
+    """Whether the box lends this org its key for this vendor and model."""
+    if lends is None or vendor in lends:
+        return True
+    if model is None:
+        return False
+    prefix = f"{vendor}{SEPARATOR}"
+    named = (entry.removeprefix(prefix) for entry in lends if entry.startswith(prefix))
+    return any(model == entry or _a_snapshot_of(entry, model) for entry in named)
+
+
+def refusal(lends: frozenset[str], vendor: str, model: str | None) -> str:
+    """The sentence a refused org reads: what it asked, what it may run, and the other way."""
+    params = vendor if model is None else f"{vendor}{SEPARATOR}{model}"
+    may = ", ".join(sorted(lends)) if lends else "nothing of the box's"
+    return f"{params} is not lent to this org: it may run on {may}, or on a key of its own"
+
+
+def parse_lending(entries: Iterable[str]) -> frozenset[str]:
+    """The entries an operator lends, each a vendor installed here or `vendor/model`."""
+    parsed: set[str] = set()
+    for entry in entries:
+        named, slash, model = entry.strip().partition(SEPARATOR)
+        vendor = named.lower()
+        if vendor not in installed():
+            raise DeclarationRefused(f"{entry!r} lends no vendor installed here")
+        if slash and not model:
+            raise DeclarationRefused(f"{entry!r} names a vendor and no model after the slash")
+        parsed.add(f"{vendor}{SEPARATOR}{model}" if slash else vendor)
+    return frozenset(parsed)
+
+
+# An agent that names its vendor runs it alone; one on the row's default runs the default's
+# fallbacks behind it, each on its own key, in the row's order. A fallback this org cannot key is
+# left out.
+def stage(
+    modality: Modality, declared: Model | Voice | None, configured: Providers, keys: Keyring
+) -> Running:
+    """One stage on its key: the vendor declared or the default, with the operator's options."""
+    if declared is not None:
+        return _on_its_key(modality, declared.provider, declared.model or None, configured, keys)
+    default = configured.defaults[modality]
+    chosen = _on_its_key(modality, default.vendor, default.model, configured, keys)
+    backups: list[Running] = []
+    for fallback in default.fallbacks:
+        try:
+            backups.append(_on_its_key(modality, fallback.vendor, fallback.model, configured, keys))
+        except (NotAvailable, NotAllowed):
+            logger.info(
+                "%s fallback %s has no key this org may run it on", modality, fallback.vendor
+            )
+    return _over(chosen, *backups)
+
+
+def _a_snapshot_of(entry: str, model: str) -> bool:
+    return model.startswith(entry) and A_SNAPSHOT.fullmatch(model[len(entry) :]) is not None
+
+
+def _on_its_key(
+    modality: Modality, vendor: str, params: str | None, configured: Providers, keys: Keyring
+) -> Running:
+    model = params or configured.models.get(f"{modality}{SEPARATOR}{vendor}")
+    chosen = running(keys, vendor, model)
+    options = tuning_of(configured, modality, vendor, model)
+    if options is None:
+        return chosen
+    return dataclasses.replace(
+        chosen,
+        builds=options.builds,
+        options=dict(options.options),
+        ends_the_turn=options.ends_the_turn,
+        turn_model=options.turn_model,
+        request=dict(options.request),
+    )
+
+
+def _over(primary: Running, *fallbacks: Running) -> Running:
+    return dataclasses.replace(primary, fallbacks=fallbacks)
+
+
+def _behind(chosen: Running, failing: frozenset[str]) -> Running:
+    chain = (dataclasses.replace(chosen, fallbacks=()), *chosen.fallbacks)
+    return _over(*sorted(chain, key=lambda item: item.vendor in failing))
+
+
+def _availability_of(vendor: Vendor, keys: Keyring) -> Availability:
+    if vendor.broken is not None:
+        return "broken"
+    if vendor.name in keys.own:
+        return "yours"
+    if vendor.name in keys.box and lent(keys.lends, vendor.name, None):
+        return "offered"
+    return "bring your own"

pinecall/providers/declared.py

@@ -0,0 +1,69 @@
+"""What an agent runs as its org set it: the declaration, its tuning and its lexicon."""
+
+import dataclasses
+from collections.abc import Mapping
+
+from pinecall.domain.agent import AgentConfig, Lexicon, Model, Tuning, Voice
+from pinecall.providers.build import Modality, doing, installed
+from pinecall.providers.catalog import Stage
+
+# Model ids carry slashes of their own (`openai/gpt-5` on LiveKit Inference): the first one ends
+# the vendor.
+SEPARATOR = "/"
+
+
+def apply_tuning(
+    declared: AgentConfig, tuning: Tuning, lexicon: Lexicon, *, defaults: Mapping[Modality, Stage]
+) -> AgentConfig:
+    """The declaration with the org's settings over it: what the world set is what runs."""
+    return dataclasses.replace(
+        declared,
+        greeting=tuning.greeting,
+        # An app on an SDK before 0.9.19 still declares one; the world's wins.
+        language=declared.language if tuning.language is None else tuning.language,
+        voice=_voice(declared, tuning, defaults),
+        stt=model_of(tuning.stt, "stt", in_use=_in_use(declared.stt, defaults["stt"])),
+        llm=model_of(tuning.llm, "llm", in_use=_in_use(declared.llm, defaults["llm"])),
+        hangup=tuning.hangup,
+        turn=tuning.turn,
+        memory=tuning.memory,
+        record=declared.record if tuning.record is None else tuning.record,
+        max_duration_s=(
+            declared.max_duration_s if tuning.max_duration_s is None else tuning.max_duration_s
+        ),
+        llm_timeout_s=tuning.llm_timeout_s,
+        knowledge=tuning.knowledge,
+        bases=tuning.bases or (),
+        says=dict(lexicon.said),
+        hears=lexicon.heard,
+    )
+
+
+def model_of(text: str | None, modality: Modality, *, in_use: str) -> Model | None:
+    """`vendor/model`, a vendor alone, or a model on the vendor in use; None when none is named."""
+    if text is None:
+        return None
+    word = text.strip()
+    vendor, slash, model = word.partition(SEPARATOR)
+    if slash:
+        return Model(provider=doing(vendor.lower(), modality), model=model)
+    if word.lower() in installed():
+        return Model(provider=doing(word.lower(), modality), model="")
+    return Model(provider=doing(in_use, modality), model=word)
+
+
+# `tts_model` names the model of the vendor `tts` names, or of the one in use.
+def _voice(
+    declared: AgentConfig, tuning: Tuning, defaults: Mapping[Modality, Stage]
+) -> Voice | None:
+    if tuning.tts is None and tuning.voice is None and tuning.tts_model is None:
+        return None
+    in_use = _in_use(declared.voice, defaults["tts"])
+    named = model_of(tuning.tts, "tts", in_use=in_use)
+    provider = in_use if named is None else named.provider
+    model = tuning.tts_model or (None if named is None else named.model or None)
+    return Voice(provider=provider, model=model, voice_id=tuning.voice)
+
+
+def _in_use(declared: Model | Voice | None, default: Stage) -> str:
+    return default.vendor if declared is None else declared.provider