pinecall-runtime 0.1.6__py3-none-any.whl

pinecall/gateway/api/org.py

@@ -0,0 +1,283 @@
+"""The org's own: judging, identity provider, mailbox, policy, erasures, reads and export."""
+
+from collections.abc import AsyncIterator
+from typing import Annotated
+
+from fastapi import APIRouter, Query, Request
+from fastapi.responses import StreamingResponse
+
+from pinecall.domain.errors import Conflict, DeclarationRefused, NotFound, UpstreamFailed
+from pinecall.domain.person import parse_role
+from pinecall.domain.scope import Scope
+from pinecall.gateway._deps import (
+    CallsKey,
+    GatewayDep,
+    TeamKey,
+    UsageKey,
+    asked_by,
+    public_url,
+)
+from pinecall.providers import catalog
+from pinecall.providers.catalog import judge_ceiling
+from pinecall.tenancy import (
+    erasure,
+    export,
+    keys,
+    letters,
+    mail,
+    orgs,
+    policy,
+    reads,
+    sso,
+    sso_domains,
+)
+from pinecall.tenancy.mail import Mailbox, MailboxStatus
+from pinecall.tenancy.sso import Client, OrgSso
+from pinecall.wire.rest.accounts import (
+    OrgMailRequest,
+    OrgMailResponse,
+    OrgPolicy,
+    OrgPolicyRow,
+    OrgSsoRequest,
+    OrgSsoResponse,
+    SendTestLetterRequest,
+    SendTestLetterResponse,
+    SsoDomainProof,
+)
+from pinecall.wire.rest.agents import (
+    JudgingRequest,
+    JudgingSettings,
+)
+from pinecall.wire.rest.calls import ErasureTrail, ReadsResponse
+
+router = APIRouter()
+
+
+# A 404, not a 204: taking away what is not there must not look like it worked.
+NO_SSO = "this org signs in with no identity provider"
+
+
+# Required with no domain proven would lock everybody out: the provider is offered for none.
+NOT_PROVEN_YET = (
+    "no domain of this SSO is verified yet: publish each domain's TXT record and ask "
+    "POST /v1/org/sso/domains/{domain}/verify, then require it"
+)
+
+
+NO_MAIL = "this org sends its letters through the box's own mail"
+
+
+# The issuer is asked before it is kept, so a typo shows here and not at the first sign-in.
+NOT_KEPT = "{said}: nothing was kept"
+
+
+# A 409, not a 503: the request is fine, and there is nothing to test.
+NOTHING_TO_TEST = (
+    "neither this org nor this box has a mail server: set one at PUT /v1/org/mail, or set "
+    "PINECALL_SMTP_URL on the box"
+)
+
+
+# Per org, not per world: judging is billed to the org across both.
+@router.get("/v1/org/judging")
+async def get_judging(key: CallsKey, gateway: GatewayDep) -> JudgingSettings:
+    """Whether hang-up judging is on, and its ceiling per call."""
+    pool = gateway.connections.pool
+    on = await orgs.judged(pool, key.org)
+    return JudgingSettings(on=on, ceiling_usd=judge_ceiling(await catalog.providers(pool)))
+
+
+@router.put("/v1/org/judging")
+async def put_judging(body: JudgingRequest, key: UsageKey, gateway: GatewayDep) -> JudgingSettings:
+    """Hang-up judging on or off, from the next call."""
+    pool = gateway.connections.pool
+    await orgs.set_judging(pool, key.org, on=body.on)
+    return JudgingSettings(on=body.on, ceiling_usd=judge_ceiling(await catalog.providers(pool)))
+
+
+# `team`: the provider decides who the org's people are.
+@router.get("/v1/org/sso")
+async def get_sso(key: TeamKey, request: Request, gateway: GatewayDep) -> OrgSsoResponse:
+    """The org's provider, never its secret, and the redirect URI to register there."""
+    connections = gateway.connections
+    wired = await sso.sso_of(connections.pool, connections.vault, key.org)
+    proofs = await sso_domains.of_org(connections.pool, key.org)
+    return sso_row(wired, f"{public_url(request, gateway)}{sso.CALLBACK}", proofs)
+
+
+# The role the provider seats people with counts as granted by this key: a manager makes no admin.
+@router.put("/v1/org/sso")
+async def put_sso(
+    body: OrgSsoRequest, key: TeamKey, request: Request, gateway: GatewayDep
+) -> OrgSsoResponse:
+    """Replace the org's provider whole, once its issuer answered as one."""
+    connections = gateway.connections
+    role = None if body.role is None else parse_role(body.role)
+    wanted = OrgSso(
+        org=key.org,
+        client=Client(body.issuer.strip(), body.client_id.strip(), body.client_secret),
+        domains=tuple(domain.strip().lower().removeprefix("@") for domain in body.domains),
+        role=role,
+        required=body.required,
+    )
+    keys.check_may_grant(key.bearer, role, production=False)
+    try:
+        await sso.discovered(connections.http, wanted.client.issuer)
+    except UpstreamFailed as unanswered:
+        raise DeclarationRefused(NOT_KEPT.format(said=unanswered)) from unanswered
+    if wanted.required:
+        proven = await sso_domains.verified_domains(connections.pool, key.org)
+        if not proven & frozenset(wanted.domains):
+            raise Conflict(NOT_PROVEN_YET)
+    await sso.put_sso(connections.pool, connections.vault, wanted)
+    proofs = await sso_domains.proofs_for(connections.pool, key.org, wanted.domains)
+    return sso_row(wanted, f"{public_url(request, gateway)}{sso.CALLBACK}", proofs)
+
+
+# The org published the record; the box reads it now, once. A record seen stands.
+@router.post("/v1/org/sso/domains/{domain}/verify")
+async def verify_sso_domain(domain: str, key: TeamKey, gateway: GatewayDep) -> SsoDomainProof:
+    """Look for the domain's TXT record and, found, offer the provider for the domain."""
+    folded = domain.strip().lower().removeprefix("@")
+    proof = await sso_domains.verify(gateway.connections.pool, key.org, folded)
+    return SsoDomainProof(domain=proof.domain, txt=proof.txt, verified=proof.verified)
+
+
+@router.delete("/v1/org/sso", status_code=204)
+async def drop_sso(key: TeamKey, gateway: GatewayDep) -> None:
+    """Forget the org's provider: passwords open it again from the next attempt."""
+    if not await sso.drop_sso(gateway.connections.pool, key.org):
+        raise NotFound(NO_SSO)
+
+
+# `team`: these letters carry invitations and password links.
+@router.get("/v1/org/mail")
+async def get_mail(key: TeamKey, gateway: GatewayDep) -> OrgMailResponse:
+    """The org's own mailbox, never its password, and how its last letter went."""
+    connections = gateway.connections
+    return _mail_row(await mail.mail_of(connections.pool, connections.vault, key.org))
+
+
+# Sends nothing: the test door does, and a person watches it.
+@router.put("/v1/org/mail")
+async def put_mail(body: OrgMailRequest, key: TeamKey, gateway: GatewayDep) -> OrgMailResponse:
+    """Replace the org's own mailbox; its letters go through it from the next one."""
+    connections = gateway.connections
+    await mail.put_mail(connections.pool, connections.vault, key.org, mailbox_of(body))
+    return _mail_row(await mail.mail_of(connections.pool, connections.vault, key.org))
+
+
+@router.delete("/v1/org/mail", status_code=204)
+async def drop_mail(key: TeamKey, gateway: GatewayDep) -> None:
+    """Forget the org's own mailbox: its letters go through the box's again."""
+    if not await mail.drop_mail(gateway.connections.pool, key.org):
+        raise NotFound(NO_MAIL)
+
+
+# The one mail door that waits on SMTP; how it went is kept as a real letter's is.
+@router.post("/v1/org/mail/test")
+async def send_test_letter(
+    body: SendTestLetterRequest, key: TeamKey, gateway: GatewayDep
+) -> SendTestLetterResponse:
+    """One test letter, waited for: whether it went, and what the server said when not."""
+    to = mail.address_of(body.to)
+    if await gateway.outbox.mailbox_for(key.org) is None:
+        raise Conflict(NOTHING_TO_TEST)
+    letter = letters.probe_letter(to, await letters.brand_of(gateway.connections.pool))
+    error = await gateway.outbox.sent(key.org, letter)
+    return SendTestLetterResponse(sent=error is None, error=error)
+
+
+def mailbox_of(body: OrgMailRequest) -> Mailbox:
+    """The mailbox a body describes, its words trimmed; refused in the mailbox's own terms."""
+    return Mailbox(
+        host=body.host.strip(),
+        port=body.port,
+        security=mail.parse_security(body.security),
+        username=body.username.strip(),
+        password=body.password,
+        sender=body.sender.strip(),
+    )
+
+
+def sso_row(
+    wired: OrgSso | None, redirect_uri: str, proofs: list[sso_domains.Proof]
+) -> OrgSsoResponse:
+    """An org's provider as the doors send it: wired or not, never the secret."""
+    return OrgSsoResponse(
+        configured=wired is not None,
+        issuer=None if wired is None else wired.client.issuer,
+        client_id=None if wired is None else wired.client.client_id,
+        domains=[] if wired is None else list(wired.domains),
+        role=None if wired is None else wired.role,
+        required=wired is not None and wired.required,
+        redirect_uri=redirect_uri,
+        proofs=[
+            SsoDomainProof(domain=proof.domain, txt=proof.txt, verified=proof.verified)
+            for proof in proofs
+        ],
+    )
+
+
+@router.get("/v1/org/erasures")
+async def erasures(key: TeamKey, gateway: GatewayDep) -> ErasureTrail:
+    """The org's erasures, newest first: what went, when, and who asked."""
+    rows = await erasure.trail(gateway.connections.pool, key.org)
+    return ErasureTrail(erasures=rows)
+
+
+@router.get("/v1/org/reads")
+async def who_read(
+    key: TeamKey, gateway: GatewayDep, subject: Annotated[str | None, Query()] = None
+) -> ReadsResponse:
+    """Who read the org's calls, recordings, seats, exports and memory; of one subject if named."""
+    rows = await reads.of_org(gateway.connections.pool, key.org, subject=subject)
+    return ReadsResponse(reads=rows)
+
+
+@router.get("/v1/org/policy")
+async def get_policy(key: TeamKey, gateway: GatewayDep) -> OrgPolicyRow:
+    """The org's compliance settings: how many days a sealed call is kept, and who set it."""
+    return await policy.policy_of(gateway.connections.pool, key.org)
+
+
+@router.put("/v1/org/policy")
+async def put_policy(body: OrgPolicy, key: TeamKey, gateway: GatewayDep) -> OrgPolicyRow:
+    """Replace the org's compliance settings whole, from the next nightly run."""
+    pool = gateway.connections.pool
+    await policy.put_policy(pool, key.org, body, by=asked_by(key))
+    return await policy.policy_of(pool, key.org)
+
+
+@router.get("/v1/org/export", response_model=None)
+async def export_org(key: TeamKey, gateway: GatewayDep) -> StreamingResponse:
+    """The org's data in the key's world as JSON Lines: calls, memories, settings, documents."""
+    export_read = reads.Read(key.org, "export", asked_by(key))
+    await reads.record(gateway.connections.pool, Scope(key.org, key.env), export_read)
+    filename = f"pinecall-{key.org}-{key.env}.jsonl"
+    return StreamingResponse(
+        _one_per_line(export.lines(gateway.connections.pool, key.org, key.env)),
+        media_type="application/x-ndjson",
+        headers={"Content-Disposition": f'attachment; filename="{filename}"'},
+    )
+
+
+def _mail_row(kept: MailboxStatus | None) -> OrgMailResponse:
+    # By its wire name: `from` is a keyword.
+    return OrgMailResponse.model_validate(
+        {
+            "configured": kept is not None,
+            "host": None if kept is None else kept.mailbox.host,
+            "port": None if kept is None else kept.mailbox.port,
+            "security": None if kept is None else kept.mailbox.security,
+            "username": None if kept is None else kept.mailbox.username,
+            "from": None if kept is None else kept.mailbox.sender,
+            "verified_at": None if kept is None else kept.verified_at,
+            "last_error": None if kept is None else kept.last_error,
+        }
+    )
+
+
+async def _one_per_line(lines: AsyncIterator[str]) -> AsyncIterator[bytes]:
+    async for line in lines:
+        yield f"{line}\n".encode()

pinecall/gateway/api/personas.py

@@ -0,0 +1,157 @@
+"""The persona doors: an agent's synthetic callers, and what each ran."""
+
+import re
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, Query
+from pydantic import BaseModel, Field
+
+from pinecall.domain.errors import DeclarationRefused, NotFound
+from pinecall.gateway import _deps
+from pinecall.gateway._deps import EvalsKey, GatewayDep, ScopeDep
+from pinecall.gateway._gateway import Gateway
+from pinecall.log import lists
+from pinecall.log.lists import PersonaRunFilters
+from pinecall.providers import catalog
+from pinecall.providers.declared import model_of
+from pinecall.tenancy import personas
+from pinecall.tenancy.personas import Persona, PersonaEdit, StoredPersona
+from pinecall.wire.rest.evals import (
+    PersonaList,
+    PersonaRequest,
+    PersonaRow,
+    PersonaRunList,
+    PersonaRunRow,
+)
+
+router = APIRouter()
+
+
+# What `--persona` takes: lower-case words joined by hyphens.
+A_NAME = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
+
+
+NOT_A_NAME = (
+    "{name!r} is not a persona's name: lower-case words joined by hyphens, like price-shopper"
+)
+
+
+A_SCREENFUL = 20
+
+
+class PersonaRunQuery(BaseModel):
+    """Where a persona's runs continue, and how many."""
+
+    limit: int = Field(A_SCREENFUL, ge=1, le=_deps.LONGEST_LIST)
+    before: str | None = None
+
+
+# One list for both worlds: a persona is test data, never heard by a customer.
+@router.get("/v1/agents/{slug}/personas")
+async def list_personas(slug: str, key: EvalsKey, gateway: GatewayDep) -> PersonaList:
+    """The agent's callers, by name."""
+    return await _list_of(gateway, key.org, slug)
+
+
+# A model or a vendor this box lacks is refused when written, not on the call that plays it.
+@router.put("/v1/agents/{slug}/personas/{name}")
+async def put_persona(
+    slug: str, name: str, body: PersonaRequest, key: EvalsKey, gateway: GatewayDep
+) -> PersonaList:
+    """Write one of the agent's callers whole, or rename one from `was`; its list after it."""
+    if not A_NAME.match(name):
+        raise DeclarationRefused(NOT_A_NAME.format(name=name))
+    pool = gateway.connections.pool
+    defaults = (await catalog.providers(pool)).defaults
+    llm, tts = body.llm or None, body.tts or None
+    model_of(llm, "llm", in_use=defaults["llm"].vendor)
+    model_of(tts, "tts", in_use=defaults["tts"].vendor)
+    written = Persona(
+        name=name,
+        goal=body.goal,
+        style=body.style,
+        about=body.about,
+        facts=dict(body.facts),
+        state=dict(body.state),
+        llm=llm,
+        tts=tts,
+        voice=body.voice or None,
+        accepts_when=body.accepts_when or "",
+        declines_when=body.declines_when or "",
+    )
+    bearer = key.bearer.key
+    edit = PersonaEdit(author=bearer.subject or bearer.key_id, was=body.was)
+    await personas.put_persona(pool, key.org, slug, written, edit)
+    return await _list_of(gateway, key.org, slug)
+
+
+@router.delete("/v1/agents/{slug}/personas/{name}")
+async def drop_persona(slug: str, name: str, key: EvalsKey, gateway: GatewayDep) -> PersonaList:
+    """Forget one of the agent's callers; its list after it, 404 for a name nobody wrote."""
+    await personas.drop_persona(gateway.connections.pool, key.org, slug, name)
+    return await _list_of(gateway, key.org, slug)
+
+
+# A name nobody wrote for the agent is a 404, not an empty page. The key is let through by the
+# route's dependency, since the scope already names its org.
+@router.get(
+    "/v1/agents/{slug}/personas/{name}/runs", dependencies=[Depends(_deps.opening("evals"))]
+)
+async def list_persona_runs(
+    slug: str,
+    name: str,
+    scope: ScopeDep,
+    gateway: GatewayDep,
+    query: Annotated[PersonaRunQuery, Query()],
+) -> PersonaRunList:
+    """The calls the persona made to the agent in the key's world and scope, newest first."""
+    pool = gateway.connections.pool
+    if await personas.persona(pool, scope.org, slug, name) is None:
+        raise NotFound(personas.NOBODY.format(name=name, agent=slug))
+    found = await lists.runs_of_persona(
+        pool,
+        scope,
+        PersonaRunFilters(agent=slug, persona=name, before=query.before),
+        limit=query.limit,
+    )
+    rows = [
+        PersonaRunRow.model_validate(
+            {
+                "call": run.facts.call,
+                "agent": run.facts.agent,
+                "started_at": run.started_at,
+                "ended_at": run.facts.ended_at,
+                "turns": run.turns,
+                "end_reason": run.facts.end_reason,
+                "outcome": run.facts.outcome,
+                "cost_usd": run.facts.cost_usd,
+                "score": run.facts.score,
+            }
+        )
+        for run in found.runs
+    ]
+    return PersonaRunList(runs=rows, total=found.total, next=found.next)
+
+
+def _row_of(stored: StoredPersona) -> PersonaRow:
+    persona = stored.persona
+    return PersonaRow(
+        name=persona.name,
+        about=persona.about,
+        goal=persona.goal,
+        style=persona.style,
+        facts=dict(persona.facts),
+        state=dict(persona.state),
+        llm=persona.llm,
+        tts=persona.tts,
+        voice=persona.voice,
+        accepts_when=persona.accepts_when,
+        declines_when=persona.declines_when,
+        author=stored.author,
+        set_at=stored.set_at.timestamp(),
+    )
+
+
+async def _list_of(gateway: Gateway, org: str, agent: str) -> PersonaList:
+    kept = await personas.personas_of(gateway.connections.pool, org, agent)
+    return PersonaList(personas=[_row_of(stored) for stored in kept])

pinecall/gateway/api/pipeline.py

@@ -0,0 +1,206 @@
+"""An agent's pipeline: what it hears, decides and speaks with, how fast, and its hold melody."""
+
+import asyncio
+from typing import Annotated
+
+from fastapi import APIRouter, Query, Request, Response
+
+from pinecall.domain.agent import AgentConfig, Greeting
+from pinecall.domain.errors import DeclarationRefused, NotFound, PinecallError
+from pinecall.domain.scope import Scope
+from pinecall.gateway._call_setup import keys_of, tuned
+from pinecall.gateway._deps import GatewayDep, PipelineKey, ScopeDep, capped_body
+from pinecall.gateway._gateway import Gateway
+from pinecall.gateway.api.providers import catalogue_of
+from pinecall.log.reduce import medians, reduce
+from pinecall.providers import catalog, credentials
+from pinecall.providers.build import Modality, primary
+from pinecall.providers.credentials import Keyring
+from pinecall.session import hold
+from pinecall.tenancy import agents
+from pinecall.tenancy.agents import Chosen, Clip
+from pinecall.wire.parts import GreetingConfig
+from pinecall.wire.rest.agents import (
+    HoldAudio,
+    Measured,
+    PipelineReport,
+    PipelineStage,
+    PlayedRequest,
+)
+from pinecall.wire.state import Turn
+
+router = APIRouter()
+
+
+# Medians pool the turns of this many calls, so a short call weighs as much as its turns.
+LAST_CALLS = 20
+
+
+# The whole file in one request; a five-minute mp3 is under 10 MB.
+LONGEST_UPLOAD = 20 * 1024 * 1024
+
+
+NO_CLIP = "agent {slug} plays no clip of its own: the box's melody is the worker's, off or default"
+
+
+OGG = "audio/ogg"
+
+
+TOO_BIG = f"a hold melody is {LONGEST_UPLOAD // (1024 * 1024)} MB at most as uploaded"
+
+
+# The stages are the ones the next call would be built with: the declaration under the scope's
+# settings. Nothing is built: a vendor without a key is a reason, not a failure.
+@router.get("/v1/agents/{slug}/pipeline")
+async def pipeline_report(
+    slug: str, _key: PipelineKey, scope: ScopeDep, gateway: GatewayDep
+) -> PipelineReport:
+    """The agent's three stages, the catalogue, and the latencies of its last calls."""
+    pool = gateway.connections.pool
+    registration = gateway.sockets.of(scope, slug)
+    declared = AgentConfig(slug=slug) if registration is None else registration.config
+    configured = await catalog.providers(pool)
+    config, _ = await tuned(pool, declared, scope, configured)
+    keyring = await keys_of(pool, gateway.connections.vault, scope)
+    language = primary(config.language)
+    stages = {
+        "hears": _stage("stt", config, configured, language=language),
+        "decides": _stage("llm", config, configured, language=None),
+        "speaks": _stage("tts", config, configured, language=language),
+    }
+    listed = catalogue_of(configured, keyring)
+    turns = await _recent_turns(gateway, scope.org, slug)
+    return PipelineReport(
+        agent=slug,
+        hears=stages["hears"],
+        decides=stages["decides"],
+        speaks=stages["speaks"],
+        greeting=_greeting(config.greeting),
+        voices=listed.voices,
+        providers=listed.providers,
+        defaults=listed.defaults,
+        models=listed.models,
+        calls=turns[0],
+        medians=[
+            Measured(name=row.name, seconds=row.seconds, turns=row.turns)
+            for row in medians(turns[1])
+        ],
+        unavailable_reasons=_unavailable(stages, keyring),
+    )
+
+
+@router.get("/v1/agents/{slug}/pipeline/hold-audio")
+async def hold_audio(
+    slug: str, _key: PipelineKey, scope: ScopeDep, gateway: GatewayDep
+) -> HoldAudio:
+    """What the agent plays while a tool runs: the box's melody, silence, or a clip of its own."""
+    return _hold_audio_row(await agents.hold_of(gateway.connections.pool, _of(scope), slug))
+
+
+# The body is the file, no multipart; the name rides the query. Converted here, once, so no
+# worker decodes a tenant's upload in the middle of a call.
+@router.put("/v1/agents/{slug}/pipeline/hold-audio")
+async def upload_hold_audio(
+    slug: str,
+    request: Request,
+    _key: PipelineKey,
+    scope: ScopeDep,
+    gateway: GatewayDep,
+    name: Annotated[str | None, Query(max_length=200)] = None,
+) -> HoldAudio:
+    """A file of the org's as the agent's melody, from the next call on."""
+    data = await capped_body(request, LONGEST_UPLOAD)
+    if len(data) > LONGEST_UPLOAD:
+        raise DeclarationRefused(TOO_BIG)
+    melody = await asyncio.to_thread(hold.converted, data)
+    clip = Clip(audio=melody.audio, seconds=melody.seconds, name=(name or "").strip() or "melody")
+    chosen = await agents.keep_hold(gateway.connections.pool, _of(scope), slug, clip)
+    return _hold_audio_row(chosen)
+
+
+@router.get("/v1/agents/{slug}/pipeline/hold-audio/audio")
+async def hold_audio_clip(
+    slug: str, _key: PipelineKey, scope: ScopeDep, gateway: GatewayDep
+) -> Response:
+    """The agent's own clip, Ogg Opus, to hear before a caller does."""
+    audio = await agents.hold_audio(gateway.connections.pool, _of(scope), slug)
+    if audio is None:
+        raise NotFound(NO_CLIP.format(slug=slug))
+    return Response(audio, media_type=OGG)
+
+
+@router.put("/v1/agents/{slug}/pipeline/hold-audio/played")
+async def choose_hold_audio(
+    slug: str, body: PlayedRequest, _key: PipelineKey, scope: ScopeDep, gateway: GatewayDep
+) -> HoldAudio:
+    """The box's melody back, or silence; an uploaded clip is forgotten either way."""
+    pool = gateway.connections.pool
+    if body.played == "default":
+        await agents.forget_hold(pool, _of(scope), slug)
+        return HoldAudio(played="default")
+    await agents.silence_hold(pool, _of(scope), slug)
+    return HoldAudio(played="off")
+
+
+def _hold_audio_row(chosen: Chosen | None) -> HoldAudio:
+    """The stored choice as the doors send it; no row is the box's melody."""
+    if chosen is None:
+        return HoldAudio(played="default")
+    return HoldAudio(
+        played=chosen.played, sha256=chosen.sha256, seconds=chosen.seconds, name=chosen.name
+    )
+
+
+def _stage(
+    modality: Modality, config: AgentConfig, configured: catalog.Providers, *, language: str | None
+) -> PipelineStage:
+    default = configured.defaults[modality]
+    if modality == "tts":
+        voice = config.voice
+        return PipelineStage(
+            vendor=default.vendor if voice is None else voice.provider,
+            model=None if voice is None else voice.model,
+            voice_id=None if voice is None else voice.voice_id,
+            language=language,
+        )
+    declared = config.stt if modality == "stt" else config.llm
+    return PipelineStage(
+        vendor=default.vendor if declared is None else declared.provider,
+        model=None if declared is None else declared.model or None,
+        language=language,
+    )
+
+
+def _greeting(greeting: Greeting | None) -> GreetingConfig | None:
+    if greeting is None:
+        return None
+    return GreetingConfig(
+        say=greeting.say, reply=greeting.reply, allow_interruptions=greeting.allow_interruptions
+    )
+
+
+# A slug is one org's: another org's agent has no calls here, and says nothing of its latencies.
+async def _recent_turns(gateway: Gateway, org: str, slug: str) -> tuple[int, list[list[Turn]]]:
+    store = gateway.logs.store
+    owner = await store.owner(slug)
+    if owner is not None and owner != org:
+        return 0, []
+    calls = await store.newest_calls(LAST_CALLS, agent=slug)
+    turns = [reduce(await store.whole(call)).turns for call in calls]
+    return len(calls), turns
+
+
+# Which stage has no key to run on, and why, before a call fails for want of it.
+def _unavailable(stages: dict[str, PipelineStage], keyring: Keyring) -> dict[str, str]:
+    missing: dict[str, str] = {}
+    for where, stage in stages.items():
+        try:
+            credentials.running(keyring, stage.vendor, stage.model)
+        except PinecallError as refused:
+            missing[where] = str(refused)
+    return missing
+
+
+# The melody and the widget are the agent's in a world, whoever holds it.
+def _of(scope: Scope) -> Scope:
+    return Scope(scope.org, scope.env)

pinecall/gateway/api/prompts.py

@@ -0,0 +1,50 @@
+"""A call's prompt read back: each block its log names by hash, with the words the org kept."""
+
+from fastapi import APIRouter
+
+from pinecall.domain.errors import NotFound
+from pinecall.gateway import _deps
+from pinecall.gateway._deps import CallsKey, GatewayDep, ScopeDep, asked_by
+from pinecall.log import queries
+from pinecall.tenancy import prompts, reads
+from pinecall.tenancy.reads import Read
+from pinecall.wire.events import PromptChanged
+from pinecall.wire.rest.calls import CallPromptResponse, PromptBlockRow
+
+router = APIRouter()
+
+
+# A key's read alone, never a page's token: the prompt is the operator's and the app's words.
+# It is a read of the call, and on the record as one.
+@router.get("/v1/calls/{call}/prompt")
+async def call_prompt(
+    call: str, key: CallsKey, scope: ScopeDep, gateway: GatewayDep
+) -> CallPromptResponse:
+    """Every block of prompt the call was told, in order, each with its words when kept."""
+    reader = _deps.Reader(acting=key, scope=scope)
+    await _deps.check_readable(gateway, reader, call)
+    pool = gateway.connections.pool
+    kept = await queries.scope_of_call(pool, call)
+    entries = await gateway.logs.store.whole(call)
+    if kept is None or kept.scope is None or not entries:
+        raise NotFound(_deps.NO_SUCH_CALL.format(call=call))
+    await reads.record(pool, scope, Read(call, "log", asked_by(key)))
+    changes = [
+        (entry.seq, PromptChanged.model_validate(entry.data))
+        for entry in entries
+        if entry.type == "prompt.changed"
+    ]
+    texts = await prompts.texts_of(pool, kept.scope.org, {block.hash for _, block in changes})
+    return CallPromptResponse(
+        call=call,
+        blocks=[
+            PromptBlockRow(
+                seq=seq,
+                name=block.name,
+                hash=block.hash,
+                chars=block.chars,
+                text="" if block.chars == 0 else texts.get(block.hash),
+            )
+            for seq, block in changes
+        ],
+    )