pinecall-runtime 0.1.6__py3-none-any.whl

pinecall/gateway/api/chat.py

@@ -0,0 +1,223 @@
+"""A written call over a WebSocket: a message in, every entry of the call out."""
+
+import asyncio
+
+from fastapi import APIRouter, WebSocket, WebSocketDisconnect
+from pydantic import TypeAdapter, ValidationError
+from starlette.websockets import WebSocketState
+
+from pinecall.domain.call import CallContext, Contact, Route, new_call_id, today_in
+from pinecall.domain.errors import (
+    Conflict,
+    DeclarationRefused,
+    NotAllowed,
+    NotFound,
+    PinecallError,
+    QuotaExhausted,
+)
+from pinecall.domain.names import THE_WIDGET, Json, JsonObject
+from pinecall.domain.scope import Scope
+from pinecall.gateway import _deps
+from pinecall.gateway._call_setup import exhausted
+from pinecall.gateway._gateway import Gateway
+from pinecall.gateway._sockets import NO_AGENT, NO_UNCLAIMED, NOT_THAT_APP, Registration
+from pinecall.gateway._text_calls import open_text, resume_text, tokens_of
+from pinecall.log.logs import Subscription
+from pinecall.session import text
+from pinecall.session.session import Session
+from pinecall.tenancy import admission, keys, personas
+
+router = APIRouter()
+
+
+NOT_TAKEN_UP = "call {call} cannot be taken up: it is over, or not this agent's; open a new one"
+
+NOT_A_STATE = "?state= is the state the call opens in: a JSON object of the class's fields"
+
+STATE_TOO_BIG = "?state= is {size} bytes: the state a call opens in is {at_most} bytes at most"
+
+A_STATE_AT_MOST = 16 * 1024
+
+_A_STATE: TypeAdapter[JsonObject] = TypeAdapter(JsonObject)
+
+OVER = "the call ended: {reason}"
+
+# What uvicorn closes with on a stop; a caller never sends it, so the call is left for the next
+# process to take up.
+SERVICE_RESTART = 1012
+
+
+# The org's key, never a room token (`pinecall chat`, `test`, `simulate`). A refusal accepts the
+# socket first: a close before the handshake is a bare 403 with no reason.
+@router.websocket("/v1/chat")
+async def chat(websocket: WebSocket) -> None:
+    """One text call: {text} frames in, every entry of the call out."""
+    gateway = _deps.gateway_of(websocket)
+    try:
+        found, again = await _chatting(websocket, gateway)
+        session = (
+            await _taken_up(gateway, found, again)
+            if again
+            else await open_text(
+                gateway.serving, found, await _chat_context(websocket, gateway, found)
+            )
+        )
+    except PinecallError as refused:
+        await websocket.accept()
+        await websocket.close(code=_deps.POLICY_VIOLATION, reason=_deps.close_reason(str(refused)))
+        return
+    await websocket.accept()
+    served = gateway.live.calls.get(session.call.context.call)
+    heard = await served.log.followed() if served is not None else None
+    sending = asyncio.create_task(_sent(websocket, heard)) if heard is not None else None
+    # The call can end from the desk or by the model: the socket is closed under the caller.
+    ending = asyncio.create_task(_hung_up(websocket, session))
+    try:
+        if not again:
+            await session.start()
+        await _turns(websocket, gateway, session)
+    finally:
+        ending.cancel()
+        if sending is not None:
+            sending.cancel()
+
+
+async def _hung_up(websocket: WebSocket, session: Session) -> None:
+    await session.over.wait()
+    reason, _ = session.ended or ("error", "platform")
+    if websocket.application_state is WebSocketState.CONNECTED:
+        await websocket.close(reason=_deps.close_reason(OVER.format(reason=reason)))
+
+
+async def _chatting(websocket: WebSocket, gateway: Gateway) -> tuple[Registration, str | None]:
+    data = _deps.bearer_of(websocket.headers)
+    verified = None if data is None else await gateway.keys.verify(data)
+    if verified is None:
+        raise NotAllowed(_deps.TAKES_A_KEY)
+    keys.check_opens(verified, "talk")
+    env = _deps.world_of_request(websocket, verified)
+    scope = keys.scope_of(verified, env)
+    slug = websocket.query_params.get("agent", "")
+    keys.check_agent(verified, slug)
+    app = websocket.query_params.get("app")
+    registration = gateway.sockets.serving(scope, slug, app)
+    if registration is None:
+        raise NotFound(_why_not(gateway, scope, slug, app))
+    return registration, websocket.query_params.get("call")
+
+
+async def _taken_up(gateway: Gateway, registration: Registration, call: str) -> Session:
+    session = await resume_text(
+        gateway.serving, registration, call, gateway.connections.settings.timezone
+    )
+    if session is None:
+        raise Conflict(NOT_TAKEN_UP.format(call=call))
+    return session
+
+
+# A web caller is a visitor id; the org's own key may name who it is (`?contact=`) and which of
+# the agent's synthetic callers plays it (`?persona=`), whose rules are frozen into the call here.
+async def _chat_context(
+    websocket: WebSocket, gateway: Gateway, registration: Registration
+) -> CallContext:
+    scope = registration.scope
+    named = websocket.query_params.get("persona") or None
+    persona = (
+        None
+        if named is None
+        else await personas.persona(gateway.connections.pool, scope.org, registration.slug, named)
+    )
+    contact = websocket.query_params.get("contact")
+    return CallContext(
+        call=new_call_id(),
+        channel=THE_WIDGET,
+        direction="inbound",
+        caller=websocket.query_params.get("caller") or f"web_{new_call_id()[5:17]}",
+        contact=Contact(id=contact) if contact else None,
+        persona=named,
+        accepts_when=None if persona is None else persona.persona.accepts_when or None,
+        declines_when=None if persona is None else persona.persona.declines_when or None,
+        route=Route(org=scope.org, agent=registration.slug, channel=THE_WIDGET, env=scope.env),
+        today=today_in(gateway.connections.settings.timezone),
+        holder=scope.holder or None,
+        state=_opening_state(websocket),
+    )
+
+
+def _opening_state(websocket: WebSocket) -> JsonObject:
+    query = websocket.query_params.get("state")
+    if not query:
+        return {}
+    size = len(query.encode())
+    if size > A_STATE_AT_MOST:
+        raise DeclarationRefused(STATE_TOO_BIG.format(size=size, at_most=A_STATE_AT_MOST))
+    try:
+        return _A_STATE.validate_json(query)
+    except ValidationError:
+        raise DeclarationRefused(NOT_A_STATE) from None
+
+
+# A failed send flips the application state; a receive after it raises RuntimeError, so the
+# state is asked before each receive.
+async def _turns(websocket: WebSocket, gateway: Gateway, session: Session) -> None:
+    scope = session.call.context.route
+    try:
+        while websocket.application_state is WebSocketState.CONNECTED:
+            frame = await websocket.receive_json()
+            if _hangs_up(frame):
+                # Ended before the socket closes, so the caller hears the call is over before
+                # it stops whatever served it.
+                await text.end(session, "caller_hung_up", "caller")
+                over = OVER.format(reason="caller_hung_up")
+                await websocket.close(reason=_deps.close_reason(over))
+                return
+            data = _text_of(frame)
+            if not data:
+                continue
+            try:
+                await admission.admit_turn(
+                    gateway.connections.pool,
+                    Scope(scope.org, scope.env),
+                    turns=session.call.turns,
+                    tokens=tokens_of(session.usage),
+                    at=gateway.logs.store.clock(),
+                )
+            except QuotaExhausted as refused:
+                await exhausted(gateway.logs, scope.org, session.call.config.slug, refused)
+                await text.end(session, "timeout", "platform")
+                await websocket.close(
+                    code=_deps.POLICY_VIOLATION, reason=_deps.close_reason(str(refused))
+                )
+                return
+            await text.hears(session, data)
+    except WebSocketDisconnect as gone:
+        if gone.code != SERVICE_RESTART and not session.closed:
+            await text.end(session, "caller_hung_up", "caller")
+        return
+    # A send that found the caller gone closed the socket under the loop, with no close to hear.
+    if not session.closed:
+        await text.end(session, "caller_hung_up", "caller")
+
+
+async def _sent(websocket: WebSocket, heard: Subscription) -> None:
+    async for entry in heard:
+        await websocket.send_json(entry.written())
+
+
+def _hangs_up(data: Json) -> bool:
+    return isinstance(data, dict) and data.get("hangup") is True
+
+
+def _text_of(data: Json) -> str:
+    if not isinstance(data, dict):
+        return ""
+    text_said = data.get("text")
+    return text_said if isinstance(text_said, str) else ""
+
+
+def _why_not(gateway: Gateway, scope: Scope, slug: str, app: str | None) -> str:
+    if app is not None:
+        return NOT_THAT_APP.format(app=app, slug=slug)
+    if gateway.sockets.of(scope, slug) is not None:
+        return NO_UNCLAIMED.format(slug=slug)
+    return f"{NO_AGENT.format(slug=slug)}: start the app that serves it, then chat again"

pinecall/gateway/api/dataset.py

@@ -0,0 +1,163 @@
+"""The dataset doors: a call kept as a case or read as a golden, the inbox, a case decided."""
+
+from typing import Annotated
+
+from fastapi import APIRouter, Path, Query
+from pydantic import BaseModel, Field
+
+from pinecall.domain.errors import Conflict, NotFound
+from pinecall.domain.names import Env
+from pinecall.domain.scope import Scope
+from pinecall.evals import calibration, dataset
+from pinecall.evals.calibration import Label, Where
+from pinecall.evals.dataset import Promoted
+from pinecall.gateway import _deps
+from pinecall.gateway._deps import Acting, EvalsKey, GatewayDep, ScopeDep
+from pinecall.gateway._gateway import Gateway
+from pinecall.log import queries
+from pinecall.tenancy.keys import check_agent
+from pinecall.wire.frames import Entry
+from pinecall.wire.rest.evals import (
+    CaseDecision,
+    CaseStatus,
+    EvalCase,
+    EvalCaseList,
+    Expect,
+    Golden,
+    PromoteCaseRequest,
+)
+from pinecall.wire.scores import CallScore
+
+router = APIRouter()
+
+
+STILL_GOING = "call {call} is still going: a case is made of a call that ended"
+
+
+class GoldenQuery(BaseModel):
+    """What a call read as a golden is named, and the seq it is cut at."""
+
+    name: str | None = Field(default=None, min_length=1)
+    from_seq: int = Field(default=0, ge=0)
+
+
+# The case is the org's, played in the sandbox whichever world its call ran in; the key must be
+# one that reads the call, as a replay's does. An expect left empty is the one the call's broken
+# verdicts give.
+@router.post("/v1/evals/cases", response_model_exclude_unset=True)
+async def promote_case(
+    body: PromoteCaseRequest, key: EvalsKey, scope: ScopeDep, gateway: GatewayDep
+) -> EvalCase:
+    """A finished call's caller lines kept as a case of the org's dataset."""
+    entries, agent, env, version = await _finished(gateway, key, scope, body.call)
+    score = _score_in(entries)
+    expect = body.expect
+    if expect == Expect() and score is not None:
+        expect = dataset.expect_of(score.judges, entries)
+    golden = dataset.golden_of(entries, body.name, expect)
+    promoting = Promoted(
+        org=key.org,
+        env=env,
+        name=body.name,
+        author=key.bearer.key.subject or key.bearer.key.key_id,
+        held_out=body.held_out,
+        broke=[] if score is None else dataset.broke_of(score),
+        source_version=version,
+    )
+    return await dataset.promoted(gateway.connections.pool, golden, agent, promoting)
+
+
+# What `pinecall runs promote` writes to test/candidates: the same golden a case would hold,
+# derived here once, kept nowhere.
+@router.get("/v1/calls/{call}/golden", response_model_exclude_unset=True)
+async def golden_of_call(
+    call: Annotated[str, Path()],
+    key: EvalsKey,
+    scope: ScopeDep,
+    gateway: GatewayDep,
+    query: Annotated[GoldenQuery, Query()],
+) -> Golden:
+    """The golden a finished call makes from a seq on, its expect from its broken verdicts."""
+    entries, _, _, _ = await _finished(gateway, key, scope, call)
+    score = _score_in(entries)
+    expect = Expect() if score is None else dataset.expect_of(score.judges, entries)
+    cut = dataset.cut_at(entries, query.from_seq)
+    return dataset.golden_of(cut, query.name or call, expect)
+
+
+@router.get("/v1/evals/cases", response_model_exclude_unset=True)
+async def list_cases(
+    key: EvalsKey,
+    gateway: GatewayDep,
+    agent: Annotated[str | None, Query()] = None,
+    status: Annotated[CaseStatus | None, Query()] = None,
+) -> EvalCaseList:
+    """The org's cases, one agent's or every one, the pending first; how many wait, of how many."""
+    if agent is not None:
+        check_agent(key.bearer, agent)
+    pool = gateway.connections.pool
+    return EvalCaseList(
+        cases=await dataset.listed(pool, key.org, agent, status),
+        pending=await dataset.waiting(pool, key.org, agent),
+        pending_at_most=dataset.PENDING_AT_MOST,
+    )
+
+
+# The judge called wrong is a calibration label in the call's own world, so the key must read the
+# call as the calibration door's does.
+@router.patch("/v1/evals/cases/{id}", response_model_exclude_unset=True)
+async def decide_case(
+    case: Annotated[str, Path(alias="id")],
+    body: CaseDecision,
+    key: EvalsKey,
+    scope: ScopeDep,
+    gateway: GatewayDep,
+) -> EvalCase:
+    """Approve, dismiss, hold out or mark a case as kept in the repository."""
+    pool = gateway.connections.pool
+    kept = await dataset.found(pool, key.org, case)
+    check_agent(key.bearer, kept.agent)
+    dataset.check_decision(kept, body)
+    author = key.bearer.key.subject or key.bearer.key.key_id
+    if body.judge_was_wrong is not None:
+        reader = _deps.Reader(acting=key, scope=scope)
+        await _deps.check_readable(gateway, reader, kept.source_call)
+        where = Where(org=key.org, env=kept.source_env, agent=kept.agent)
+        label = Label(
+            call=kept.source_call,
+            judge=body.judge_was_wrong,
+            held=True,
+            author=author,
+            note=body.note,
+        )
+        await calibration.labelled(pool, where, label)
+    return await dataset.decided(pool, key.org, case, body, author)
+
+
+@router.delete("/v1/evals/cases/{id}", status_code=204)
+async def forget_case(
+    case: Annotated[str, Path(alias="id")], key: EvalsKey, gateway: GatewayDep
+) -> None:
+    """Forget one of the org's cases; another org's, or nobody's, is the same 404."""
+    await dataset.forgotten(gateway.connections.pool, key.org, case)
+
+
+async def _finished(
+    gateway: Gateway, key: Acting, scope: Scope, call: str
+) -> tuple[list[Entry], str, Env, int | None]:
+    """A call the key reads and that ended: its log, its agent, its world, its settings version."""
+    await _deps.check_readable(gateway, _deps.Reader(acting=key, scope=scope), call)
+    kept = await queries.scope_of_call(gateway.connections.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))
+    check_agent(key.bearer, kept.agent)
+    if not any(entry.type == "call.ended" for entry in entries):
+        raise Conflict(STILL_GOING.format(call=call))
+    return list(entries), kept.agent, kept.scope.env, kept.versions.config
+
+
+def _score_in(entries: list[Entry]) -> CallScore | None:
+    """The call's last call.score, the verdict a judge may write again after the seal."""
+    found = [entry for entry in entries if entry.type == "call.score"]
+    return None if not found else CallScore.model_validate(found[-1].data)

pinecall/gateway/api/desk.py

@@ -0,0 +1,113 @@
+"""The supervisor's desk: listening in, taking a seat, and the verbs sent to a live call."""
+
+from fastapi import APIRouter
+
+from pinecall.domain.errors import (
+    Conflict,
+    NotAllowed,
+    NotFound,
+)
+from pinecall.domain.person import RoomScope
+from pinecall.gateway import _deps
+from pinecall.gateway._deps import Acting, GatewayDep, Reader, ReaderDep
+from pinecall.gateway._gateway import Gateway
+from pinecall.gateway.calls.commands import SUPERVISOR_VERB, commanded
+from pinecall.log import queries
+from pinecall.tenancy import keys, reads, tokens
+from pinecall.tenancy.reads import Read
+from pinecall.wire.commands import SupervisorVerb, Verb
+from pinecall.wire.frames import Command
+from pinecall.wire.parts import Supervisor
+from pinecall.wire.rest.calls import (
+    ReadKind,
+    SeatResponse,
+    VerbResponse,
+)
+
+router = APIRouter()
+
+
+IS_OVER = "call {call} is over: read its log or its recording instead"
+
+READS_ONLY = "this token reads the call and sends no verb: steering it takes a supervise token"
+
+A_KEY = "key:{org}"
+
+
+@router.post("/v1/calls/{call}/listen")
+async def listen(call: str, key: _deps.SuperviseKey, gateway: GatewayDep) -> SeatResponse:
+    """A hidden seat that hears one live call."""
+    return await _seated(gateway, key, call, "observe", "listen")
+
+
+# Not hidden: livekit delivers no track of a hidden seat, and a takeover would be silent.
+@router.post("/v1/calls/{call}/supervise")
+async def supervise(call: str, key: _deps.SuperviseKey, gateway: GatewayDep) -> SeatResponse:
+    """A seat that speaks in one live call; its token also sends the verbs."""
+    return await _seated(gateway, key, call, "supervise", "supervise")
+
+
+# The body never says who sent it: the credential does.
+@router.post("/v1/calls/{call}/verbs", status_code=202)
+async def queue_verb(
+    call: str, verb: Verb, reading: ReaderDep, gateway: GatewayDep
+) -> VerbResponse:
+    """One supervise verb on a live call; the call's log says what it did."""
+    if reading.visit is not None and reading.visit.scope != "supervise":
+        raise NotAllowed(READS_ONLY)
+    if reading.acting is not None:
+        keys.check_opens(reading.acting.bearer, "supervise")
+    await _deps.check_readable(gateway, reading, call)
+    state = await gateway.logs.reading(call).snapshot()
+    if state.seq == 0:
+        raise NotFound(_deps.NO_SUCH_CALL.format(call=call))
+    if await gateway.logs.store.sealed(call):
+        raise Conflict(IS_OVER.format(call=call))
+    wanted = SupervisorVerb(by=_who(reading), verb=verb)
+    served = gateway.live.calls.get(call)
+    if served is not None and served.session is not None:
+        await served.session.supervise(wanted)
+        return VerbResponse(call=call, verb=verb.verb, seq=None)
+    # Whichever gateway runs the call's worker stream or its session takes it.
+    sent = Command(type=SUPERVISOR_VERB, agent=state.agent, call=call, data=wanted.written())
+    if not await commanded(gateway.connections.signal, sent):
+        raise NotFound(_deps.NO_SUCH_CALL.format(call=call))
+    return VerbResponse(call=call, verb=verb.verb, seq=None)
+
+
+# A seat hears the call live: it is recorded as a read of the call, once it is handed out.
+async def _seated(
+    gateway: Gateway, key: Acting, call: str, scope: RoomScope, what: ReadKind
+) -> SeatResponse:
+    kept = await queries.scope_of_call(gateway.connections.pool, call)
+    if kept is None or kept.scope is None or kept.scope.org != key.org:
+        raise NotFound(_deps.NO_SUCH_CALL.format(call=call))
+    keys.check_agent(key.bearer, kept.agent)
+    if await gateway.logs.store.sealed(call):
+        raise Conflict(IS_OVER.format(call=call))
+    seat = tokens.seat(gateway.signer, call, scope, key.bearer)
+    read = Read(call, what, _deps.asked_by(key))
+    await reads.record(gateway.connections.pool, kept.scope, read)
+    return SeatResponse(
+        server_url=gateway.connections.settings.browser_livekit_url(kept.scope.env),
+        participant_token=seat.token,
+        call=call,
+        identity=seat.identity,
+        org=key.org,
+        subject=seat.subject,
+        name=seat.name,
+    )
+
+
+def _who(reading: Reader) -> Supervisor:
+    if reading.visit is not None:
+        if reading.visit.subject is not None:
+            return Supervisor(id=reading.visit.subject, name=reading.visit.name)
+        return Supervisor(id=reading.visit.identity or "")
+    if reading.acting is None:
+        return Supervisor(id="")
+    bearer = reading.acting.bearer
+    if bearer.key.subject is not None:
+        name = bearer.member.name if bearer.member is not None else bearer.key.name
+        return Supervisor(id=bearer.key.subject, name=name)
+    return Supervisor(id=A_KEY.format(org=bearer.key.org))

pinecall/gateway/api/entries.py

@@ -0,0 +1,77 @@
+"""A worker's batches of a call on one socket for its life, each answered with the seqs it got."""
+
+import logging
+import time
+
+from fastapi import APIRouter, WebSocket, WebSocketDisconnect
+
+from pinecall.domain.errors import NotSignedIn, PinecallError
+from pinecall.gateway import _deps
+from pinecall.gateway._deps import Acting
+from pinecall.gateway._gateway import Gateway
+from pinecall.gateway._served import Served
+from pinecall.gateway.api.calls import check_kind, counted, known
+from pinecall.tenancy import keys
+from pinecall.wire.rest.calls import (
+    AppendEntriesRefused,
+    AppendEntriesRequest,
+    AppendEntriesResponse,
+)
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+
+# A request per batch cost the gateway its routing, its headers and its key each time; on the
+# socket a batch is one frame in and one out, and the log's answer to a retry is the same as the
+# batch door's. A refusal is a frame too, and the socket stays: a refused batch never ends a call.
+@router.websocket("/v1/calls/{call}/entries")
+async def entries_socket(websocket: WebSocket, call: str) -> None:
+    """A worker's batches of a call, on one socket for its life, each answered with its seqs."""
+    gateway = _deps.gateway_of(websocket)
+    await websocket.accept()
+    try:
+        served = await _served(websocket, gateway, call)
+    except PinecallError as refused:
+        await _refused(websocket, refused)
+        await websocket.close(code=_deps.POLICY_VIOLATION, reason=_deps.close_reason(str(refused)))
+        return
+    try:
+        while True:
+            raw = await websocket.receive_text()
+            await _answered(websocket, gateway, served, call, raw)
+    except WebSocketDisconnect:
+        logger.debug("call %s: its worker's socket closed", call)
+
+
+async def _served(websocket: WebSocket, gateway: Gateway, call: str) -> Served:
+    data = _deps.bearer_of(websocket.headers)
+    verified = None if data is None else await gateway.keys.verify(data)
+    if verified is None:
+        raise NotSignedIn(_deps.TAKES_A_KEY)
+    keys.check_opens(verified, "app", "fleet")
+    key = Acting(bearer=verified, env=_deps.world_of_request(websocket, verified))
+    return await known(gateway, key, call)
+
+
+async def _answered(
+    websocket: WebSocket, gateway: Gateway, served: Served, call: str, raw: str
+) -> None:
+    try:
+        body = AppendEntriesRequest.read_json(raw, "entries")
+        for item in body.entries:
+            check_kind(item.type)
+        gateway.live.in_use(call, time.monotonic())
+        began = time.perf_counter()
+        entries = await served.log.append_many(body.entries, after=body.after)
+        counted(gateway, time.perf_counter() - began, entries)
+    except PinecallError as refused:
+        await _refused(websocket, refused)
+        return
+    await websocket.send_text(AppendEntriesResponse(entries=entries).written_json())
+
+
+async def _refused(websocket: WebSocket, refused: PinecallError) -> None:
+    frame = AppendEntriesRefused(refused=str(refused), status=refused.status)
+    await websocket.send_json(frame.written())