pinecall-runtime 0.1.6__py3-none-any.whl

pinecall/gateway/api/providers.py

@@ -0,0 +1,240 @@
+"""The providers doors: the catalogue, the org's own vendor keys, a vendor's voices, a sample."""
+
+import dataclasses
+from typing import Annotated
+
+from fastapi import APIRouter, Query, Response
+
+from pinecall.domain.agent import Voice
+from pinecall.domain.errors import DeclarationRefused, NotFound, TooManyRequests
+from pinecall.domain.names import Credentials
+from pinecall.gateway._call_setup import keys_of
+from pinecall.gateway._deps import GatewayDep, PipelineKey, ProvidersKey, ScopeDep
+from pinecall.providers import build, catalog, credentials, voices
+from pinecall.providers.build import Modality, primary
+from pinecall.providers.catalog import Providers
+from pinecall.providers.credentials import Keyring
+from pinecall.providers.declared import model_of
+from pinecall.tenancy import vault
+from pinecall.wire.rest.providers import (
+    Availability,
+    Catalogue,
+    ListedVoice,
+    ProviderKeyRequest,
+    ProviderRow,
+    Standing,
+    VendorsResponse,
+    VoiceSampleRequest,
+    VoicesListed,
+)
+
+router = APIRouter()
+
+
+WAV = "audio/wav"
+
+
+# Samples cost vendor time and write no usage row, so a key gets this many a minute.
+SAMPLES_A_MINUTE = 30
+
+
+# Long enough for a greeting, short enough to keep the vendor's cost to seconds.
+LONGEST_SAMPLE = 400
+
+
+TOO_LONG = "a sample says a sentence: {length} characters, and the ceiling is {ceiling}"
+
+
+TOO_MANY = "this key asked for its {count} samples this minute: the ceiling is {count} a minute"
+
+
+NO_CREDENTIALS = "a key, or the credentials object the vendor's plugin takes, and not both"
+
+
+NO_SUCH_KEY = "this org brought no key for {vendor}"
+
+
+# What a voice says when the picker names no line and the providers row has none in the language.
+A_LINE = "Hello, this is the voice you are listening to."
+
+
+# Availabilities a call can run on.
+READY = frozenset({"yours", "offered"})
+
+
+# v1's word for each, which the console draws: a vendor nobody keyed for this org has "no key".
+STANDING: dict[Availability, Standing] = {
+    "yours": "ready",
+    "offered": "ready",
+    "bring your own": "no key",
+    "broken": "no plugin",
+}
+
+
+# The same for every key of an org: what is installed, and whose key would run each vendor.
+@router.get("/v1/providers")
+async def catalogue(_key: ProvidersKey, scope: ScopeDep, gateway: GatewayDep) -> Catalogue:
+    """Every vendor this build runs and how this org may run it, the defaults, the models named."""
+    pool = gateway.connections.pool
+    configured = await catalog.providers(pool)
+    return catalogue_of(configured, await keys_of(pool, gateway.connections.vault, scope))
+
+
+# Vendor names only, never a key or a prefix of one.
+@router.get("/v1/provider-keys")
+async def own_vendors(key: ProvidersKey, gateway: GatewayDep) -> VendorsResponse:
+    """The vendors the org brought its own credentials for."""
+    return VendorsResponse(vendors=await vault.vendors_of(gateway.connections.pool, key.org))
+
+
+@router.put("/v1/provider-keys/{vendor}", status_code=204)
+async def bring_key(
+    vendor: str, body: ProviderKeyRequest, key: ProvidersKey, gateway: GatewayDep
+) -> None:
+    """Keep the org's own credentials for a vendor; its calls run on them from the next one."""
+    named = installed_vendor(vendor)
+    credentials = credentials_of(body)
+    build.check_credentials(named, credentials)
+    connections = gateway.connections
+    await vault.put_credentials(connections.pool, connections.vault, key.org, named, credentials)
+
+
+@router.delete("/v1/provider-keys/{vendor}", status_code=204)
+async def take_key_back(vendor: str, key: ProvidersKey, gateway: GatewayDep) -> None:
+    """Forget the org's credentials for a vendor; its calls run on the box's from the next one."""
+    named = installed_vendor(vendor)
+    if not await vault.drop_credentials(gateway.connections.pool, key.org, named):
+        raise NotFound(NO_SUCH_KEY.format(vendor=named))
+
+
+# Built as a call builds the stage: the operator's options, on the key a call would use.
+@router.get("/v1/voices")
+async def list_voices(
+    _key: PipelineKey,
+    scope: ScopeDep,
+    gateway: GatewayDep,
+    tts: Annotated[str, Query(min_length=1)],
+    language: Annotated[str | None, Query()] = None,
+) -> VoicesListed:
+    """The voices the providers row lists for a vendor, else its plugin's; neither is a 404."""
+    pool = gateway.connections.pool
+    configured = await catalog.providers(pool)
+    named = installed_vendor(tts)
+    spoken = primary(language)
+    listed = voices.kept(configured, named, spoken)
+    if not listed and not _lists_voices(named, ("tts",)):
+        raise NotFound(voices.NOT_LISTED.format(vendor=named))
+    if not listed:
+        keyring = await keys_of(pool, gateway.connections.vault, scope)
+        stage = credentials.stage("tts", Voice(provider=named), configured, keyring)
+        listed = await voices.voices(dataclasses.replace(stage, language=spoken))
+    return VoicesListed(
+        tts=tts,
+        language=language,
+        voices=[
+            voice
+            for item in listed
+            if (voice := _listed_voice(item)) is not None
+            and (spoken is None or not voice.language or voice.language.startswith(spoken))
+        ],
+    )
+
+
+# The three words are read exactly as the settings door reads them, so what plays is what saves.
+# The answer is the WAV itself, its latencies in Server-Timing, which a browser shows.
+@router.post("/v1/voices/sample")
+async def voice_sample(
+    body: VoiceSampleRequest, key: PipelineKey, scope: ScopeDep, gateway: GatewayDep
+) -> Response:
+    """The line said by that vendor's voice, over the path a call speaks on."""
+    if not await gateway.samples.allowed(key.bearer.key.key_id):
+        raise TooManyRequests(TOO_MANY.format(count=gateway.samples.tries))
+    pool = gateway.connections.pool
+    configured = await catalog.providers(pool)
+    language = primary(body.language)
+    text = body.text or configured.lines.get(language or "", A_LINE)
+    if len(text) > LONGEST_SAMPLE:
+        raise DeclarationRefused(TOO_LONG.format(length=len(text), ceiling=LONGEST_SAMPLE))
+    named = model_of(body.tts, "tts", in_use=configured.defaults["tts"].vendor)
+    voice = Voice(
+        provider=configured.defaults["tts"].vendor if named is None else named.provider,
+        model=body.model or (None if named is None else named.model or None),
+        voice_id=body.voice,
+    )
+    keyring = await keys_of(pool, gateway.connections.vault, scope)
+    stage = credentials.stage("tts", voice, configured, keyring)
+    heard = await voices.sample(
+        dataclasses.replace(stage, voice=voice.voice_id, language=language), text
+    )
+    timing = f"first-audio;dur={heard.first_audio_ms}, total;dur={heard.total_ms}"
+    return Response(content=heard.wav, media_type=WAV, headers={"Server-Timing": timing})
+
+
+def catalogue_of(configured: Providers, keyring: Keyring) -> Catalogue:
+    """Every installed vendor as this org may run it, with the row's defaults and models."""
+    return Catalogue(
+        providers=[
+            ProviderRow(
+                name=vendor.name,
+                does=list(vendor.does),
+                aliases=[],
+                note=vendor.broken or "",
+                standing=STANDING[vendor.availability],
+                ready=vendor.availability in READY,
+                env=None,
+                extra=vendor.name,
+                voices_listed=_lists_voices(vendor.name, vendor.does)
+                or voices.lists_any(configured, vendor.name),
+                availability=vendor.availability,
+                broken=vendor.broken,
+            )
+            for vendor in credentials.readiness(build.installed(), keyring)
+        ],
+        defaults={modality: stage.vendor for modality, stage in configured.defaults.items()},
+        voices=[],
+        models={named: [model] for named, model in configured.models.items()},
+    )
+
+
+def installed_vendor(vendor: str) -> str:
+    """The vendor's name as installed; refused naming the ones this build runs."""
+    named = vendor.strip().lower()
+    if named not in build.installed():
+        known = ", ".join(sorted(build.installed()))
+        raise DeclarationRefused(f"no vendor named {vendor!r}; this build runs: {known}")
+    return named
+
+
+def credentials_of(body: ProviderKeyRequest) -> Credentials:
+    """One key, or the object the plugin takes, out of the body; refused when neither or both."""
+    if (body.key is None) == (body.credentials is None):
+        raise DeclarationRefused(NO_CREDENTIALS)
+    if body.key is not None:
+        if not body.key.strip():
+            raise DeclarationRefused(NO_CREDENTIALS)
+        return body.key.strip()
+    return body.credentials or {}
+
+
+# A plugin lists its voices when its TTS class has a `list_voices`; nothing is built to ask.
+def _lists_voices(vendor: str, does: tuple[Modality, ...]) -> bool:
+    if "tts" not in does:
+        return False
+    try:
+        speech = getattr(build.plugin(vendor), "TTS", None)
+    except DeclarationRefused:
+        return False
+    return callable(getattr(speech, "list_voices", None))
+
+
+def _listed_voice(item: voices.ListedVoice) -> ListedVoice | None:
+    detail = item.detail
+    return ListedVoice(
+        id=item.id,
+        name=item.name,
+        language=str(detail.get("language") or ""),
+        description=str(detail.get("description") or ""),
+        gender=str(detail.get("gender") or ""),
+        country=str(detail.get("country") or ""),
+        accent=str(detail.get("accent") or ""),
+    )

pinecall/gateway/api/recordings.py

@@ -0,0 +1,89 @@
+"""A call's recording as a player reads it: plain, or sealed and opened a range at a time."""
+
+import asyncio
+from pathlib import Path
+from typing import Annotated
+
+from fastapi import APIRouter, Header
+from fastapi.responses import FileResponse, StreamingResponse
+
+from pinecall.domain.errors import NotFound
+from pinecall.gateway import _deps
+from pinecall.gateway._deps import CallReaderDep, GatewayDep
+from pinecall.gateway._gateway import Gateway
+from pinecall.log import queries
+from pinecall.process.recordings import (
+    SEALED_FILE,
+    Fetched,
+    kept_on_disk,
+    recordings_of,
+    served_sealed,
+)
+from pinecall.process.sealed_audio import on_disk
+from pinecall.tenancy import recording_keys
+
+router = APIRouter()
+
+
+NOT_RECORDED = "call {call} kept no recording"
+
+
+NOT_HERE = "the recording of {call} is at {path} on the box that took the call, not on this one"
+
+
+# From the bucket once the worker moved it there, else the file the recorder wrote on this disk;
+# a sealed one is opened by the call's own key, the range asked for and no more.
+@router.get("/v1/calls/{call}/recording", response_model=None)
+async def recording(
+    call: str,
+    reading: CallReaderDep,
+    gateway: GatewayDep,
+    byte_range: Annotated[str | None, Header(alias="range")] = None,
+) -> FileResponse | StreamingResponse:
+    """The call's audio, with byte ranges so a player can seek."""
+    await _deps.check_readable(gateway, reading, call)
+    await _deps.record_read(gateway, reading, call, "recording")
+    state = await gateway.logs.reading(call).snapshot()
+    summary = next(
+        (
+            item
+            for item in reversed(await gateway.logs.store.whole(call))
+            if item.type == "call.summary"
+        ),
+        None,
+    )
+    pointer = None if summary is None else summary.data.get("recording")
+    if state.seq == 0 or not isinstance(pointer, str) or not pointer:
+        raise NotFound(NOT_RECORDED.format(call=call))
+    root = Path(gateway.connections.settings.recordings_root)
+    path = await asyncio.to_thread(kept_on_disk, root, call, pointer)
+    if path is None:
+        raise NotFound(NOT_RECORDED.format(call=call))
+    kept = await queries.scope_of_call(gateway.connections.pool, call)
+    if kept is not None and kept.scope is not None:
+        fetched = await _fetched(gateway, kept.scope.org, call, path, byte_range)
+        if fetched is not None:
+            headers = {
+                **fetched.headers,
+                "content-disposition": f'attachment; filename="{call}.ogg"',
+            }
+            return StreamingResponse(
+                fetched.body, status_code=fetched.status, headers=headers, media_type="audio/ogg"
+            )
+    if path.name == SEALED_FILE or not await asyncio.to_thread(path.is_file):
+        raise NotFound(NOT_HERE.format(call=call, path=pointer))
+    return FileResponse(path, media_type="audio/ogg", filename=f"{call}.ogg")
+
+
+# A sealed recording is in the bucket, or on this disk where its upload failed; a plain one is
+# the bucket's to answer, and a file on this disk is served as a file.
+async def _fetched(
+    gateway: Gateway, org: str, call: str, path: Path, byte_range: str | None
+) -> Fetched | None:
+    connections = gateway.connections
+    stored = recordings_of(connections.settings, connections.http)
+    if path.name != SEALED_FILE:
+        return await stored.fetch(org, call, byte_range)
+    key = await recording_keys.key_of(connections.pool, connections.vault, call)
+    kept = await stored.sealed(org, call) or await on_disk(call, path)
+    return None if key is None or kept is None else served_sealed(kept, key, byte_range)

pinecall/gateway/api/relay.py

@@ -0,0 +1,169 @@
+"""The console's asks relayed to a running app: chat, knowledge, memory, the view, evals."""
+
+import asyncio
+from dataclasses import dataclass
+from typing import Annotated, get_args
+from uuid import uuid4
+
+from fastapi import APIRouter, Depends, Query
+
+from pinecall.domain.errors import (
+    AppRefused,
+    Conflict,
+    NotFound,
+)
+from pinecall.domain.names import JsonObject
+from pinecall.domain.scope import Scope
+from pinecall.gateway import _deps
+from pinecall.gateway._deps import Acting, CallsKey, GatewayDep
+from pinecall.gateway._gateway import Gateway
+from pinecall.gateway._sockets import (
+    NO_AGENT,
+    NO_DEV_ANSWERER,
+    NO_UNCLAIMED,
+    NOT_THAT_APP,
+    Registration,
+)
+from pinecall.tenancy import keys
+from pinecall.wire.events import DevRequest
+from pinecall.wire.parts import DevVerb
+
+router = APIRouter()
+
+
+NO_SUCH_VERB = "no dev verb {verb} in {family}: the verbs are {verbs}"
+
+
+NO_ANSWER = "the app holding agent {slug} did not answer {verb} within {seconds:.0f}s"
+
+
+APP_LEFT = "the app holding agent {slug} disconnected before it answered {verb}"
+
+
+# Longer than any verb takes: a suite waits 20 s on the app's side.
+ANSWERED_WITHIN_S = 120.0
+
+
+NAMED_FAMILIES: dict[str, frozenset[str]] = {
+    "chat": frozenset({"chat.roster", "chat.start", "chat.say", "chat.end"}),
+    "knowledge": frozenset({"knowledge.roster", "knowledge.push", "knowledge.eval"}),
+    "memory": frozenset({"memory.roster", "memory.eval", "memory.extraction"}),
+    "view": frozenset({"view.render"}),
+}
+
+
+EVERY_VERB: frozenset[str] = frozenset(get_args(DevVerb.__value__))
+
+
+# FastAPI builds it: the body, and the socket the query names.
+@dataclass(frozen=True)
+class Ask:
+    """What a console asks an app, and which of the agent's sockets it asks."""
+
+    said: JsonObject
+    app: Annotated[str | None, Query()] = None
+
+
+@dataclass(frozen=True)
+class Relay:
+    """Which family's verb, of which agent."""
+
+    family: str
+    slug: str
+    verb: str
+
+
+# Every verb no other family names is an eval's.
+FAMILIES: dict[str, frozenset[str]] = {
+    **NAMED_FAMILIES,
+    "evals": EVERY_VERB - frozenset().union(*NAMED_FAMILIES.values()),
+}
+
+
+AskDep = Annotated[Ask, Depends(Ask)]
+
+
+@router.post("/v1/agents/{slug}/dev/chat/{verb}")
+async def relay_chat(
+    slug: str, verb: str, ask: AskDep, key: _deps.TalkKey, gateway: GatewayDep
+) -> JsonObject:
+    """A chat verb, answered by the process that answers the console for the agent."""
+    return await _relayed(gateway, key, Relay("chat", slug, verb), ask)
+
+
+@router.post("/v1/agents/{slug}/dev/knowledge/{verb}")
+async def relay_knowledge(
+    slug: str, verb: str, ask: AskDep, key: _deps.KnowledgeKey, gateway: GatewayDep
+) -> JsonObject:
+    """A knowledge verb, answered by the process that answers the console for the agent."""
+    return await _relayed(gateway, key, Relay("knowledge", slug, verb), ask)
+
+
+@router.post("/v1/agents/{slug}/dev/memory/{verb}")
+async def relay_memory(
+    slug: str, verb: str, ask: AskDep, key: _deps.MemoryKey, gateway: GatewayDep
+) -> JsonObject:
+    """A memory verb, answered by the process that answers the console for the agent."""
+    return await _relayed(gateway, key, Relay("memory", slug, verb), ask)
+
+
+@router.post("/v1/agents/{slug}/dev/view/{verb}")
+async def relay_view(
+    slug: str, verb: str, ask: AskDep, key: CallsKey, gateway: GatewayDep
+) -> JsonObject:
+    """The side panel beside a conversation, rendered by the app serving the call."""
+    return await _relayed(gateway, key, Relay("view", slug, verb), ask)
+
+
+@router.post("/v1/agents/{slug}/dev/evals/{verb}")
+async def relay_evals(
+    slug: str, verb: str, ask: AskDep, key: _deps.EvalsKey, gateway: GatewayDep
+) -> JsonObject:
+    """An evals verb, answered by the process that answers the console for the agent."""
+    return await _relayed(gateway, key, Relay("evals", slug, verb), ask)
+
+
+# dev.request goes down the socket unstored; the app's refusal comes back as its own status.
+async def _relayed(gateway: Gateway, key: Acting, relay: Relay, params: Ask) -> JsonObject:
+    if relay.verb not in FAMILIES[relay.family]:
+        verbs = sorted(FAMILIES[relay.family])
+        raise NotFound(NO_SUCH_VERB.format(verb=relay.verb, family=relay.family, verbs=verbs))
+    registration = _answering(gateway, keys.scope_of(key.bearer, key.env), relay, params.app)
+    ask_id = f"dev_{uuid4().hex[:12]}"
+    request = DevRequest.model_validate({"id": ask_id, "verb": relay.verb, "data": params.said})
+    waiting = await gateway.live.ask(ask_id)
+    if not await gateway.live.tell(
+        registration.owner, _deps.ephemeral_entry(relay.slug, request, kind="dev.request")
+    ):
+        gateway.live.pending_answers.pop(ask_id, None)
+        waiting.cancel()
+        raise AppRefused(502, APP_LEFT.format(slug=relay.slug, verb=relay.verb))
+    try:
+        answer = await asyncio.wait_for(waiting, ANSWERED_WITHIN_S)
+    except TimeoutError:
+        gateway.live.pending_answers.pop(ask_id, None)
+        waiting.cancel()
+        said_late = NO_ANSWER.format(slug=relay.slug, verb=relay.verb, seconds=ANSWERED_WITHIN_S)
+        raise AppRefused(504, said_late) from None
+    if answer.refused is not None:
+        raise AppRefused(answer.refused.status, answer.refused.detail)
+    return answer.result or {}
+
+
+# The panel is drawn by the class serving the call; every other verb by the CLI beside it.
+def _answering(gateway: Gateway, where: Scope, relay: Relay, app: str | None) -> Registration:
+    sockets = gateway.sockets
+    if app is not None:
+        named = sockets.serving(where, relay.slug, app)
+        if named is None:
+            raise Conflict(NOT_THAT_APP.format(app=app, slug=relay.slug))
+        return named
+    if relay.family == "view":
+        found, refusal = sockets.serving(where, relay.slug, None), NO_UNCLAIMED
+    else:
+        found, refusal = sockets.answering_dev(where, relay.slug), NO_DEV_ANSWERER
+    if found is not None:
+        return found
+    if sockets.of(where, relay.slug) is not None:
+        raise Conflict(refusal.format(slug=relay.slug))
+    raise NotFound(NO_AGENT.format(slug=relay.slug))