pinecall-runtime 0.1.6__py3-none-any.whl

pinecall/wire/rest/numbers.py

@@ -0,0 +1,280 @@
+"""The number doors' bodies: carriers, numbers, dialling out, a leg's trunk, consent, opt-outs."""
+
+from typing import Literal
+
+from pydantic import Field
+
+from pinecall.domain.call import Route
+from pinecall.domain.names import Channel, Env, RouteOrigin, StepState
+from pinecall.wire.frames import WireModel
+from pinecall.wire.parts import (
+    Projection,
+)
+
+# ── dialling out ──
+
+type ConsentKind = Literal["express", "written", "opt_out"]
+
+
+class DialResponse(WireModel):
+    """POST /v1/agents/{slug}/dial, the answer."""
+
+    call: str
+    agent: str
+    to: str
+    from_: str = Field(alias="from")
+    env: Env
+    log_token: str
+
+
+class DialGuards(WireModel):
+    """GET /v1/carrier/outbound, the guards: what this org may dial and how often."""
+
+    dial_anywhere: bool
+    per_minute: int
+    per_day: int
+    max_duration_s: int
+
+
+class OutboundStatus(WireModel):
+    """GET /v1/carrier/outbound, the answer."""
+
+    ready: bool
+    kind: str | None
+    from_numbers: list[str]
+    steps_missing: list[str]
+    guards: DialGuards
+
+
+class ProvisionOutboundResponse(WireModel):
+    """POST /v1/carrier/outbound, the answer: the plan, and whether it was carried out."""
+
+    steps: list[str]
+    dry_run: bool
+    ready: bool
+    trunk: str | None = None
+    address: str | None = None
+
+
+# ── numbers and the accounts they live in ──
+
+
+class NetworkRow(WireModel):
+    """A network a peer of the org calls from, and whether the box's operator admitted it."""
+
+    network: str
+    state: str
+
+
+class CarrierRow(WireModel):
+    """GET /v1/carrier: one account of the org, named, never its secret."""
+
+    kind: str
+    account: str
+    label: str = ""
+    # A SIP peer's networks, each waiting, approved or refused; none for an account with an API.
+    networks: list[NetworkRow] = Field(default_factory=list[NetworkRow])
+
+
+class CatalogCarrier(WireModel):
+    """A carrier the org may bring numbers through: automatic (its API) or guided (SIP terms)."""
+
+    kind: str
+    name: str
+    how: Literal["automatic", "guided"]
+    networks: list[str]
+
+
+class CarrierCatalog(WireModel):
+    """GET /v1/carriers/catalog: the carriers this box admits, and whether it sells numbers."""
+
+    carriers: list[CatalogCarrier]
+    sells: bool
+
+
+class CarrierList(WireModel):
+    """GET /v1/carriers: every account of the org, oldest first."""
+
+    carriers: list[CarrierRow]
+
+
+class OwnedNumberRow(WireModel):
+    """A number an account owns, and whether this world imported it."""
+
+    number: str
+    name: str
+    imported: bool
+    account: str
+
+
+class AvailableNumbers(WireModel):
+    """GET /v1/numbers/available: what the org's Twilio accounts own; a peer lists none."""
+
+    kind: str
+    numbers: list[OwnedNumberRow]
+
+
+class NumberRow(WireModel):
+    """GET /v1/numbers, one row: a number of the org, the agent it reaches, how it was written."""
+
+    route: Route
+    origin: RouteOrigin
+    # What a call to it does now, read off the tables (GET /v1/numbers/{number}/path says why).
+    rings: StepState = "ok"
+    # When a call to it last reached the box; null when none ever did.
+    last_call_at: float | None = None
+    # The carrier of the box's catalog a hooked number comes through.
+    via: str | None = None
+    # The org's account the number lives in (GET /v1/carriers names it); null for one with none.
+    account: str | None = None
+
+
+class PathStep(WireModel):
+    """One step of a call's way to its agent, what it does now, and what would make it work."""
+
+    step: Literal["carrier", "fence", "world", "agent"]
+    state: StepState
+    says: str
+    fix: str | None = None
+
+
+class NumberPath(WireModel):
+    """GET /v1/numbers/{number}/path: the four steps, the worst of them, and the last call."""
+
+    number: str
+    steps: list[PathStep]
+    rings: StepState
+    last_call_at: float | None
+
+
+class ImportNumberResponse(WireModel):
+    """POST /v1/numbers and /v1/numbers/buy: the route, one sentence a step, whether it ran."""
+
+    route: Route
+    steps: list[str]
+    dry_run: bool
+
+
+class ImportNumberRequest(WireModel):
+    """POST /v1/numbers: a number of one of the org's accounts, or one the org hooks itself."""
+
+    number: str
+    agent: str
+    channel: Channel = "phone"
+    account: str | None = None
+    hooked: bool = False
+    networks: list[str] = Field(default_factory=list[str])
+    # A hooked number's carrier from the box's catalog (GET /v1/carriers/catalog).
+    via: str | None = None
+    move: bool = False
+
+
+class BuyNumberRequest(WireModel):
+    """POST /v1/numbers/buy: a number wanted from the box's own account."""
+
+    # Two letters and digits alone: both ride a URL path the box signs with its own account.
+    country: str = Field(pattern=r"^[A-Za-z]{2}$")
+    area_code: str | None = Field(default=None, pattern=r"^[0-9]{1,6}$")
+    agent: str
+    channel: Channel = "phone"
+
+
+class MoveNumberRequest(WireModel):
+    """PUT /v1/numbers/{number}/env: the world the number answers in from now on."""
+
+    env: Env
+
+
+class Consent(WireModel):
+    """The consent a call runs on: express or written, where it came from, the words, a proof."""
+
+    kind: Literal["express", "written"]
+    source: str = Field(min_length=1, max_length=200)
+    text: str | None = Field(default=None, max_length=2000)
+    evidence: str | None = Field(default=None, max_length=500)
+
+
+class DialRequest(WireModel):
+    """POST /v1/agents/{slug}/dial: the far end, the org's number it is shown, the consent."""
+
+    to: str
+    from_: str | None = Field(None, alias="from")
+    consent: Consent | None = None
+    # What the log token handed back reads the call through.
+    log: Projection = "tenant"
+
+
+class LegTrunk(WireModel):
+    """How the worker dials a leg: the host, its transport, the pair, the number shown."""
+
+    hostname: str
+    transport: Literal["auto", "udp", "tcp", "tls"]
+    username: str
+    password: str
+    shown: str
+
+
+class LegTrunkResponse(WireModel):
+    """GET /v1/agents/{slug}/outbound-trunk: the leg's trunk, inline, after the guards."""
+
+    trunk: LegTrunk
+
+
+class ConsentRow(WireModel):
+    """One fact about a number: a consent or an opt-out, by whom, from what, on which call."""
+
+    kind: ConsentKind
+    source: str
+    text: str | None
+    evidence: str | None
+    given_by: str
+    call: str | None
+    given_at: float
+
+
+class ConsentHistory(WireModel):
+    """GET /v1/org/consents/{number}: what stands for the number, and every row, newest first."""
+
+    number: str
+    standing: Literal["consented", "opted_out", "unknown"]
+    rows: list[ConsentRow]
+
+
+class OptedOut(WireModel):
+    """A number on the org's do-not-call list: since when, from what, and who put it there."""
+
+    number: str
+    since: float
+    source: str
+    given_by: str
+
+
+class DoNotCall(WireModel):
+    """GET /v1/org/dnc: the numbers whose newest row is an opt-out, newest first, a page."""
+
+    numbers: list[OptedOut]
+    next: str | None
+
+
+class DoNotCallImport(WireModel):
+    """POST /v1/org/dnc: numbers the org's own list or a Registry scrub says not to call."""
+
+    numbers: list[str] = Field(min_length=1, max_length=10000)
+    source: str = Field(min_length=1, max_length=200)
+
+
+class DoNotCallImported(WireModel):
+    """POST /v1/org/dnc, the answer: how many numbers joined the list, and the ones refused."""
+
+    added: int
+    refused: list[str]
+
+
+class RecordConsent(WireModel):
+    """POST /v1/org/consents: one fact about a number, a consent given or an opt-out."""
+
+    number: str
+    kind: ConsentKind
+    source: str = Field(min_length=1, max_length=200)
+    text: str | None = Field(default=None, max_length=2000)
+    evidence: str | None = Field(default=None, max_length=500)

pinecall/wire/rest/ops.py

@@ -0,0 +1,342 @@
+"""The bodies of the box's own doors: orgs and what they hold, their people and keys, the box."""
+
+from typing import Literal
+
+from pydantic import Field
+
+from pinecall.domain.names import Channel, Env
+from pinecall.domain.org import QuotaName
+from pinecall.wire.frames import Entry, WireModel
+from pinecall.wire.rest.accounts import MemberRow
+from pinecall.wire.rest.fleet import FleetTotals, WorkerStatus
+from pinecall.wire.rest.numbers import DialGuards
+
+# `bought` on the box's account; `twilio`, `sip`, `whatsapp` the org's account it was imported
+# from; `imported` from an account since forgotten; `hooked` pointed at the box by the org itself;
+# `typed` a row the box's operator wrote.
+type NumberCameIn = Literal["bought", "twilio", "sip", "whatsapp", "imported", "hooked", "typed"]
+
+
+class CreateOrgRequest(WireModel):
+    """POST /v1/ops/orgs: the slug, and the name people read; the slug when none."""
+
+    slug: str
+    name: str | None = None
+
+
+class OrgRow(WireModel):
+    """One org: its minted id, its slug and its name."""
+
+    id: str
+    slug: str
+    name: str
+
+
+# The same shape read and written: a limit left out is none, and `lends` null lends everything.
+class OrgQuotas(WireModel):
+    """An org's limits in one world, by name; null is no limit, and `lends` comes back sorted."""
+
+    limits: dict[QuotaName, int | None] = Field(default_factory=dict[QuotaName, int | None])
+    budget_usd: int | None = None
+    lends: list[str] | None = None
+
+
+class PutQuotasRequest(WireModel):
+    """PUT /v1/ops/orgs/{named}/quotas: which world, and the whole set for it."""
+
+    env: Env
+    quotas: OrgQuotas
+
+
+class PutDiallingRequest(WireModel):
+    """PUT /v1/ops/orgs/{named}/dialling: the guards whole; one left out is the default."""
+
+    dial_anywhere: bool | None = None
+    per_minute: int | None = None
+    per_day: int | None = None
+    max_duration_s: int | None = None
+
+
+class OrgHolding(WireModel):
+    """What the org holds right now, across both worlds, against its stock quotas."""
+
+    memory_facts: int
+    knowledge_chunks: int
+    numbers: int
+    seats: int
+
+
+class OrgProfile(WireModel):
+    """GET /v1/ops/orgs/{named}: one org, its quotas per world, its dial guards, its holdings."""
+
+    id: str
+    slug: str
+    name: str
+    quotas: dict[Env, OrgQuotas]
+    dialling: DialGuards
+    holding: OrgHolding
+
+
+class MoveAgentRequest(WireModel):
+    """PUT /v1/ops/orgs/{named}/agents: the agent to move into this org."""
+
+    agent: str
+
+
+class AgentMovedResponse(WireModel):
+    """The move: how many logs came, which numbers came, which stayed where they were."""
+
+    agent: str
+    org: str
+    logs: int
+    numbers: list[str]
+    stayed: list[str]
+
+
+class IssueKeyRequest(WireModel):
+    """POST /v1/ops/orgs/{named}/keys: a key of the org, in a world, with scopes and an owner."""
+
+    env: Env
+    label: str | None = None
+    scopes: list[str] | None = None
+    subject: str | None = None
+    name: str | None = None
+
+
+class OrgMembersResponse(WireModel):
+    """GET /v1/ops/orgs/{named}/members: the org's people, and how many hold a seat."""
+
+    members: list[MemberRow]
+    seated: int
+
+
+class OperatorRequest(WireModel):
+    """PUT /v1/ops/orgs/{named}/members/{id}/operator: whether this member runs the box."""
+
+    operator: bool
+
+
+class SsoRequiredRequest(WireModel):
+    """PUT /v1/ops/orgs/{named}/sso/required: whether a password may still open the org."""
+
+    required: bool
+
+
+class BoxMailResponse(WireModel):
+    """GET and PUT /v1/ops/mail: the box's mailbox and where it came from, never the password."""
+
+    configured: bool
+    source: str | None
+    host: str | None
+    port: int | None
+    security: str | None
+    username: str | None
+    from_: str | None = Field(alias="from")
+    verified_at: str | None
+    last_error: str | None
+
+
+class BoxProvider(WireModel):
+    """One box-wide identity provider: whether it is wired, the client, the URI to register."""
+
+    configured: bool
+    client_id: str | None
+    redirect_uri: str
+
+
+class BoxSignInResponse(WireModel):
+    """GET /v1/ops/signin: every provider the box could offer every org's people."""
+
+    google: BoxProvider
+
+
+class PutSignInRequest(WireModel):
+    """PUT /v1/ops/signin/google: the OAuth client the operator made for this gateway."""
+
+    client_id: str
+    client_secret: str
+
+
+class PutBrandRequest(WireModel):
+    """PUT /v1/ops/brand: a field left out keeps its value; an empty one goes to the default."""
+
+    name: str | None = None
+    logo_url: str | None = None
+    accent: str | None = None
+
+
+class RouteRequest(WireModel):
+    """POST /v1/ops/routes: which org's agent answers a number, on a channel, in a world."""
+
+    org: str
+    number: str
+    agent: str
+    channel: Channel
+    env: Env = "production"
+
+
+class RouteRow(WireModel):
+    """One route as the operator lists it."""
+
+    org: str
+    number: str
+    agent: str
+    channel: Channel
+    env: Env
+    managed: bool
+
+
+class BoxNumber(WireModel):
+    """GET /v1/ops/numbers: a number the box answers at, how it came, and who picks it up."""
+
+    number: str
+    channel: Channel
+    org: str
+    env: Env
+    agent: str
+    came_in: NumberCameIn
+    # A process holds the agent in the org and world now: a call to the number is answered.
+    running: bool
+    # The catalog carrier a number the org hooked comes through, when it named one.
+    via: str | None = None
+    # False for a number the org hooked that waits for the operator: no call to it opens.
+    approved: bool = True
+
+
+class BoxCarrier(WireModel):
+    """A carrier of the box's catalog: its published networks, and whether it is admitted."""
+
+    kind: str
+    name: str
+    # The box drives its API (lists, points, buys numbers); the others are SIP terms alone.
+    control: bool
+    networks: list[str]
+    source: str
+    read_on: str
+    admitted: bool
+    # The platform's own carrier: admitted always, its networks in the cloud firewall.
+    fixed: bool
+    # The numbers of every org that reach the box through it.
+    numbers: int
+
+
+class FenceOpening(WireModel):
+    """A network 5060 opens to beyond Twilio's, and why: a carrier's kind, or an org's ask."""
+
+    network: str
+    reason: str
+
+
+class BoxFence(WireModel):
+    """What the fence opens to beyond Twilio's, and every network the cloud's firewall admits."""
+
+    openings: list[FenceOpening]
+    # Twilio's first, then each opening: Terraform's `sip_sources` (`fence export`).
+    networks: list[str]
+
+
+class BoxCarriers(WireModel):
+    """GET /v1/ops/carriers: the catalog, each carrier admitted or not, and the fence."""
+
+    carriers: list[BoxCarrier]
+    fence: BoxFence
+
+
+class RepointRequest(WireModel):
+    """POST /v1/ops/sip/repoint: the names each world was reached at before, sent on from."""
+
+    former: dict[Env, list[str]] = Field(default_factory=dict[Env, list[str]])
+
+
+class RepointedTrunk(WireModel):
+    """POST /v1/ops/sip/repoint: a trunk of an account sent on from a world's name to its SIP's."""
+
+    account: str
+    trunk: str
+    world: Env
+    was: str
+    now: str
+
+
+class AdmitCarrierRequest(WireModel):
+    """PUT /v1/ops/carriers/{kind}: whether orgs may bring numbers through the carrier."""
+
+    admitted: bool
+
+
+class CarrierNetworkRow(WireModel):
+    """A network an org asked 5060 to open to: who, for what, and the operator's answer."""
+
+    id: int
+    org: str
+    source: str
+    network: str
+    state: str
+    asked_at: float
+    decided_by: str | None
+    decided_at: float | None
+
+
+class FleetListed(WireModel):
+    """GET /v1/ops/fleet: the box's time, every worker heard from, and each fleet summed."""
+
+    now: float
+    stale_after_s: float
+    workers: list[WorkerStatus]
+    totals: list[FleetTotals]
+
+
+class FleetDemand(WireModel):
+    """GET /v1/fleet/wanted: how many scaled workers the fleet wants, for KEDA."""
+
+    fleet: str
+    wanted: int
+    # The fleet's calls and the seats its workers hold now, for whoever reads why.
+    active: int
+    seats: int
+
+
+class BoxEvent(WireModel):
+    """One frame of GET /v1/ops/events: an entry of some org's floor, whose, and in which world."""
+
+    org: str
+    env: Env | None = None
+    entry: Entry
+
+
+class TracebackCall(WireModel):
+    """One phone call with the number: whose, which way, when, how it ended, whether erased."""
+
+    call: str
+    org: str | None
+    env: str | None
+    direction: str | None
+    from_number: str | None
+    to_number: str | None
+    started_at: float | None
+    ended_at: float | None
+    end_reason: str | None
+    # The call's log is gone and only its detail record is left (0016_call_records.sql).
+    erased: bool
+
+
+class TracebackDial(WireModel):
+    """One dial to the number: whose, the call it placed, the number shown, who asked, the guard."""
+
+    org: str
+    env: str
+    agent: str
+    call: str | None
+    shown: str | None
+    asked_by: str
+    refused: str | None
+    at: float
+
+
+class Traceback(WireModel):
+    """GET /v1/ops/traceback: what the box keeps of one number since a day, oldest first."""
+
+    number: str
+    since: float
+    calls: list[TracebackCall]
+    dials: list[TracebackDial]

pinecall/wire/rest/providers.py

@@ -0,0 +1,83 @@
+"""The bodies of the providers doors: the catalogue, the org's own keys, the voices, a sample."""
+
+from typing import Literal
+
+from pinecall.domain.names import JsonObject
+from pinecall.wire.frames import WireModel
+
+type Availability = Literal["yours", "offered", "bring your own", "broken"]
+
+
+type Standing = Literal["ready", "no plugin", "no key", "its own"]
+
+
+# v1's row, which the console reads, and `availability` and `broken` beside it: `standing` is
+# `availability` in v1's words, and the fields v1 read off a table in code are empty here.
+class ProviderRow(WireModel):
+    """One installed vendor: what it does, whose key runs it for this org, and why not."""
+
+    name: str
+    does: list[Literal["llm", "stt", "tts"]]
+    aliases: list[str]
+    note: str
+    standing: Standing
+    ready: bool
+    env: str | None
+    extra: str
+    voices_listed: bool
+    availability: Availability
+    broken: str | None
+
+
+class Catalogue(WireModel):
+    """GET /v1/providers: every vendor installed, the defaults per stage, the models named."""
+
+    providers: list[ProviderRow]
+    defaults: dict[str, str]
+    # The picker reads GET /v1/voices; no names are curated in code.
+    voices: list[str]
+    models: dict[str, list[str]]
+
+
+class VendorsResponse(WireModel):
+    """GET /v1/provider-keys: the vendors the org brought its own credentials for, never one."""
+
+    vendors: list[str]
+
+
+# One key, or the whole object a plugin's constructor takes (`speech_key` and `speech_region`).
+class ProviderKeyRequest(WireModel):
+    """PUT /v1/provider-keys/{vendor}: the org's own credentials for one vendor."""
+
+    key: str | None = None
+    credentials: JsonObject | None = None
+
+
+class ListedVoice(WireModel):
+    """One voice as the picker shows it: the id the `voice` setting takes, and what to choose by."""
+
+    id: str
+    name: str
+    language: str
+    description: str
+    gender: str
+    country: str
+    accent: str
+
+
+class VoicesListed(WireModel):
+    """GET /v1/voices?tts=&language=: a vendor's own voices, in the vendor's order."""
+
+    tts: str
+    language: str | None
+    voices: list[ListedVoice]
+
+
+class VoiceSampleRequest(WireModel):
+    """POST /v1/voices/sample: which vendor, voice, model and words to hear; the answer is WAV."""
+
+    tts: str
+    voice: str
+    model: str | None = None
+    language: str | None = None
+    text: str | None = None