pinecall-runtime 0.1.6__py3-none-any.whl

pinecall/domain/errors.py

@@ -0,0 +1,151 @@
+"""The one error hierarchy: every error the runtime raises on purpose, with its HTTP status."""
+
+
+class PinecallError(Exception):
+    """Base of every deliberate error; the message is the sentence a person reads."""
+
+    status = 500
+
+
+class DeclarationRefused(PinecallError):
+    """A value broke a contract; the message states the rule."""
+
+    status = 400
+
+
+class NotSignedIn(PinecallError):
+    """No key, a wrong one, or wrong credentials."""
+
+    status = 401
+
+
+class NotAllowed(PinecallError):
+    """A key that opens something, but not this."""
+
+    status = 403
+
+
+class NotFound(PinecallError):
+    """Nothing by that name in the caller's scope."""
+
+    status = 404
+
+
+class Conflict(PinecallError):
+    """A valid request against stored state that contradicts it."""
+
+    status = 409
+
+
+class QuotaExhausted(PinecallError):
+    """A limit of the org is reached: which one, what was used and the limit, when it is one."""
+
+    status = 429
+
+    def __init__(
+        self, sentence: str, *, quota: str | None = None, used: float = 0, limit: int = 0
+    ) -> None:
+        """The refusal, and the numbers the door writes into the agent's log."""
+        super().__init__(sentence)
+        self.quota = quota
+        self.used = used
+        self.limit = limit
+
+
+class TooLarge(PinecallError):
+    """A body over what the door takes."""
+
+    status = 413
+
+
+class TooManyRequests(PinecallError):
+    """The same name knocked too often in the last minute: a password, a code, a sign-up."""
+
+    status = 429
+
+
+class Throttled(TooManyRequests):
+    """An org's family of doors took its minute's requests; the answer says when to come back."""
+
+    def __init__(self, sentence: str, *, retry_after_s: int) -> None:
+        """The refusal, and the whole seconds until the minute turns."""
+        super().__init__(sentence)
+        self.retry_after_s = retry_after_s
+
+
+class UpstreamFailed(PinecallError):
+    """A vendor, a carrier or an identity provider did not answer as it should."""
+
+    status = 502
+
+
+class GatewayRefused(UpstreamFailed):
+    """The worker's gateway did not answer, or answered with a refusal; `answered` is its status."""
+
+    def __init__(self, sentence: str, *, answered: int | None = None) -> None:
+        """The refusal, and the status the gateway answered with, None when it was unreachable."""
+        super().__init__(sentence)
+        self.answered = answered
+
+
+class AppRefused(PinecallError):
+    """A tenant's app refused what a console asked of it; its own status is the answer's."""
+
+    def __init__(self, answered: int, sentence: str) -> None:
+        """The app's status and its sentence, passed on as they came."""
+        super().__init__(sentence)
+        self.status = answered
+
+
+class NotAvailable(PinecallError):
+    """This box lacks what the request needs: a key, the vault, an embedder, a domain."""
+
+    status = 503
+
+
+class EmbedderUnreachable(PinecallError):
+    """The box's embedder did not answer, or answered something that is not its vectors."""
+
+    status = 503
+
+    # The sentence reaches a tenant (a lookup's error on its call's log): it names the vendor and
+    # never where the box asked it, which is the operator's to read in the process's log.
+    def __init__(self, vendor: str, url: str, words: str) -> None:
+        """The embedder, where it was asked, and what it said or why it said nothing."""
+        super().__init__(f"{vendor} did not answer: {words}")
+        self.url = url
+        self.words = words
+
+
+class WrongWidth(PinecallError):
+    """The embedder answered vectors of a width the vector columns do not hold."""
+
+    status = 503
+
+
+# Two models' vectors can share a width and still not be comparable.
+class WrongModel(PinecallError):
+    """A base's vectors were written by another model than the one this box embeds with."""
+
+    status = 503
+
+    def __init__(self, base: str, pushed: str, embeds: str) -> None:
+        """The base, the model that wrote it, and the model the box embeds with now."""
+        super().__init__(
+            f"base {base} was pushed with {pushed}; this box embeds with {embeds}: "
+            "push it again with `pinecall docs push`"
+        )
+
+
+class SettingsRefused(PinecallError):
+    """The process cannot start with the environment it was given."""
+
+
+class StoreUnreachable(PinecallError):
+    """The database cannot be reached or is not usable."""
+
+    status = 503
+
+
+class MigrationsRefused(PinecallError):
+    """The database and the shipped migrations disagree."""

pinecall/domain/names.py

@@ -0,0 +1,115 @@
+"""The words every part of the runtime speaks: worlds, channels, slugs, numbers, key scopes."""
+
+import re
+from typing import Literal
+
+from pinecall.domain.errors import DeclarationRefused
+
+# The distribution on PyPI; the import stays `pinecall`. PyPI `pinecall` is the Python SDK.
+DISTRIBUTION = "pinecall-runtime"
+
+type Json = str | int | float | bool | list[Json] | dict[str, Json] | None
+
+
+type JsonObject = dict[str, Json]
+
+
+# A lone secret, or the constructor's own keyword arguments (Azure's key and region, Google's
+# service account, LiveKit's key pair).
+type Credentials = str | JsonObject
+
+
+# A key belongs to one environment; its agents, numbers and calls are isolated to it. A shared
+# "staging" is a sandbox agent registered by a machine key (no holder), not a third environment.
+type Env = Literal["production", "sandbox"]
+
+
+# phone: SIP into a LiveKit room; web: the widget over WebRTC; whatsapp: text.
+type Channel = Literal["phone", "web", "whatsapp"]
+
+
+# How the call is had: spoken (a room, a voice) or written (a text session); `web` is either.
+type Medium = Literal["voice", "text"]
+
+
+type Direction = Literal["inbound", "outbound"]
+
+
+# How a number's row was written: bought by the box, imported from an account of the org, hooked
+# by the org from its own carrier, or typed by the box's operator.
+type RouteOrigin = Literal["bought", "imported", "hooked", "typed"]
+
+
+# What one step of a call's way to an agent does now: works, waits on someone, or stops the call.
+type StepState = Literal["ok", "waiting", "broken"]
+
+
+# e.g. clinica-norte: an agent's slug, and an org's.
+A_SLUG = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
+
+
+_E164 = re.compile(r"^\+[1-9]\d{1,14}$")
+
+
+# Checked on every address before a letter is sent: whitespace would allow header injection
+# (RFC 5322 §2.2).
+AN_ADDRESS = re.compile(r"^[^\s@<>,;]+@[^\s@<>,;]+\.[^\s@<>,;]+$")
+
+
+ENVS: tuple[Env, ...] = ("production", "sandbox")
+
+
+PRODUCTION: Env = "production"
+
+
+SANDBOX: Env = "sandbox"
+
+
+CHANNELS: tuple[Channel, ...] = ("phone", "web", "whatsapp")
+
+
+CHANNELS_WITH_A_NUMBER: tuple[Channel, ...] = ("phone", "whatsapp")
+
+
+THE_WIDGET: Channel = "web"
+
+
+def other_world(world: Env) -> Env:
+    """Return the world that is not this one."""
+    return SANDBOX if world == PRODUCTION else PRODUCTION
+
+
+def parse_env(word: str) -> Env:
+    """Return the word as an Env, raising DeclarationRefused when it is neither world."""
+    if word not in ENVS:
+        raise DeclarationRefused(f"a key opens one of {sorted(ENVS)}, not {word!r}")
+    return word
+
+
+def parse_channel(word: str) -> Channel:
+    """Return the word as a Channel, raising DeclarationRefused when it is none."""
+    if word not in CHANNELS:
+        raise DeclarationRefused(f"a call comes through one of {sorted(CHANNELS)}, not {word!r}")
+    return word
+
+
+def parse_slug(word: str) -> str:
+    """Return the slug, raising DeclarationRefused unless it is lowercase words joined by dashes."""
+    if not A_SLUG.match(word):
+        raise DeclarationRefused(f"a slug is lowercase words joined by dashes, not {word!r}")
+    return word
+
+
+def dialable(number: str) -> bool:
+    """Return whether the number is in E.164 form."""
+    return _E164.match(number) is not None
+
+
+def parse_e164(number: str) -> str:
+    """Return the trimmed number, raising DeclarationRefused when it is not E.164."""
+    data = number.strip()
+    if not dialable(data):
+        raise DeclarationRefused(
+            f"a number is written in E.164 form, like +59829001199, not {data!r}"
+        )
+    return data

pinecall/domain/org.py

@@ -0,0 +1,120 @@
+"""An org and what it may do: its quotas, its admission, what the box lends it."""
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Literal
+
+from pinecall.domain.errors import DeclarationRefused
+from pinecall.domain.names import parse_slug
+
+# Names match the DB columns and the wire. The first four are flows (consumed or open now); the
+# rest are stocks (rows kept), which lets a plan disable a feature with a zero; the budget is
+# dollars a month, both worlds together.
+type QuotaName = Literal[
+    "minutes",
+    "messages",
+    "agents",
+    "concurrent_calls",
+    "memory_facts",
+    "knowledge_chunks",
+    "numbers",
+    "seats",
+    "llm_tokens",
+    "hosted_apps",
+    "budget_usd",
+]
+
+
+# Seeded by the schema; the first key is issued against it and CLI verbs fall back to it.
+DEFAULT_ORG = "default"
+
+
+@dataclass(frozen=True)
+class Org:
+    """An organisation: immutable id, editable slug, and display name."""
+
+    id: str
+    slug: str
+    name: str
+
+    def __post_init__(self) -> None:
+        if not self.id:
+            raise DeclarationRefused("an org has an id")
+        parse_slug(self.slug)
+
+
+# None is no limit (the self-hosted default). Zero is a real limit that refuses everything.
+@dataclass(frozen=True)
+class Quotas:
+    """An org's quota limits, plus its monthly budget and the box keys lent to it."""
+
+    minutes: int | None = None
+    messages: int | None = None
+    agents: int | None = None
+    concurrent_calls: int | None = None
+    memory_facts: int | None = None
+    knowledge_chunks: int | None = None
+    # Only numbers bought on the box's carrier account; imported numbers do not count.
+    numbers: int | None = None
+    # Invited and active members; disabled members hold no seat.
+    seats: int | None = None
+    llm_tokens: int | None = None
+    # Apps the box runs for the org from sources it uploaded.
+    hosted_apps: int | None = None
+    # Whole US dollars a calendar month, both worlds together: a new call is refused past it.
+    budget_usd: int | None = None
+    # Box vendor keys the org may use: None all, empty none, else `vendor` or `vendor/model`.
+    lends: frozenset[str] | None = None
+
+    def __post_init__(self) -> None:
+        for name, limit in self.limits.items():
+            if limit is None or limit >= 0:
+                continue
+            if name == "budget_usd":
+                raise DeclarationRefused(f"a budget is dollars, and cannot be {limit}")
+            raise DeclarationRefused(f"a quota is a count, and {name} cannot be {limit}")
+
+    @property
+    def limits(self) -> Mapping[QuotaName, int | None]:
+        """Return every limit by its name."""
+        return {
+            "minutes": self.minutes,
+            "messages": self.messages,
+            "agents": self.agents,
+            "concurrent_calls": self.concurrent_calls,
+            "memory_facts": self.memory_facts,
+            "knowledge_chunks": self.knowledge_chunks,
+            "numbers": self.numbers,
+            "seats": self.seats,
+            "llm_tokens": self.llm_tokens,
+            "hosted_apps": self.hosted_apps,
+            "budget_usd": self.budget_usd,
+        }
+
+    def reached(self, quota: QuotaName, used: float) -> int | None:
+        """Return the limit when `used` is at or past it, else None."""
+        limit = self.limits[quota]
+        return limit if limit is not None and used >= limit else None
+
+    def exceeded(self, quota: QuotaName, keeping: float) -> int | None:
+        """Return the limit when `keeping` would pass it, else None; for pushes sized up front."""
+        limit = self.limits[quota]
+        return limit if limit is not None and keeping > limit else None
+
+    def switched_off(self, quota: QuotaName) -> bool:
+        """Return whether the quota is zero: the feature is not in the plan."""
+        return self.limits[quota] == 0
+
+
+QUOTAS: tuple[QuotaName, ...] = (
+    "minutes",
+    "messages",
+    "agents",
+    "concurrent_calls",
+    "memory_facts",
+    "knowledge_chunks",
+    "numbers",
+    "seats",
+    "llm_tokens",
+    "hosted_apps",
+)

pinecall/domain/person.py

@@ -0,0 +1,208 @@
+"""People and their keys: members, roles, invitations, the scopes a key opens."""
+
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Literal
+
+from pinecall.domain.errors import DeclarationRefused
+from pinecall.domain.names import AN_ADDRESS, PRODUCTION, Env
+
+# Every gateway door belongs to exactly one scope; `fleet` is the box's worker, resolved per call
+# instead of per key org, and only `keys issue --scope fleet` grants it. `runner` is the box's
+# own too: the process that runs every org's hosted apps, handed their tokens and secrets.
+type KeyScope = Literal[
+    "app",
+    "calls",
+    "talk",
+    "supervise",
+    "pipeline",
+    "knowledge",
+    "memory",
+    "evals",
+    "numbers",
+    "keys",
+    "providers",
+    "team",
+    "usage",
+    "words",
+    "fleet",
+    "runner",
+]
+
+
+# A role is only a preset of key scopes. Doors check scopes, never roles, so changing a role
+# affects newly issued keys only.
+type Role = Literal["qa", "supervisor", "manager", "admin", "developer"]
+
+
+# A room token's scope, which LiveKit carries on the seat as its `pinecall.scope` attribute, so
+# the worker reads it without a lookup.
+type RoomScope = Literal["talk", "chat", "observe", "supervise", "participate", "read"]
+
+
+# disabled: cannot log in and keys are revoked; the row is kept because the log references it.
+type MemberStatus = Literal["invited", "active", "disabled"]
+
+
+@dataclass(frozen=True)
+class Member:
+    """A person in one org, with their role, agents and status."""
+
+    id: str
+    org: str
+    email: str
+    name: str
+    role: Role
+    # Empty means all of the org's agents.
+    agents: frozenset[str] = frozenset()
+    status: MemberStatus = "invited"
+    # Box operator: their key also opens /v1/ops/*. Granted only with the ops key.
+    operator: bool = False
+    # Granted by an admin; checked per request, so revoking it takes effect immediately.
+    production: bool = False
+    # Email ownership proven by a mailed link, an IdP, or an operator invitation. Required
+    # before joining another org without a link.
+    verified: bool = False
+
+    def __post_init__(self) -> None:
+        if not self.id or not self.org:
+            raise DeclarationRefused("a member names their id and the org they belong to")
+        if not AN_ADDRESS.match(self.email):
+            raise DeclarationRefused(f"an email has one @ and a domain, not {self.email!r}")
+        if not self.name.strip():
+            raise DeclarationRefused("a member has a name: it is what a seat says when they sit")
+
+    @property
+    def scopes(self) -> frozenset[KeyScope]:
+        """Return the scopes of keys minted for this member."""
+        return ROLE_SCOPES[self.role]
+
+    @property
+    def opens_production(self) -> bool:
+        """Return whether this member may act in production; admins always may."""
+        return self.role == "admin" or self.production
+
+
+EVERY_SCOPE: tuple[KeyScope, ...] = (
+    "app",
+    "calls",
+    "talk",
+    "supervise",
+    "pipeline",
+    "knowledge",
+    "memory",
+    "evals",
+    "numbers",
+    "keys",
+    "providers",
+    "team",
+    "usage",
+    "words",
+    "fleet",
+    "runner",
+)
+
+
+THE_FLEET: KeyScope = "fleet"
+
+
+THE_RUNNER: KeyScope = "runner"
+
+
+HOLDING: KeyScope = "app"
+
+
+THE_TEAM: KeyScope = "team"
+
+
+THE_KEYS: KeyScope = "keys"
+
+
+# Default scopes: every scope except the box's own two.
+KEY_SCOPES: frozenset[KeyScope] = frozenset(EVERY_SCOPE) - {THE_FLEET, THE_RUNNER}
+
+
+# Doors take the org only from this record, never from the request.
+@dataclass(frozen=True)
+class Key:
+    """A verified API key: its org, environment, scopes and holder."""
+
+    key_id: str
+    org: str
+    label: str | None = None
+    env: Env = PRODUCTION
+    scopes: frozenset[KeyScope] = KEY_SCOPES
+    # The person a key was minted for; None on a server's key. A person's one key opens both
+    # worlds, so its env is production's and the request names the world.
+    subject: str | None = None
+    name: str | None = None
+    # None never expires. Keys minted from a personal key never outlive it.
+    expires_at: datetime | None = None
+
+
+ROLES: tuple[Role, ...] = ("qa", "supervisor", "manager", "admin", "developer")
+
+
+STATUSES: tuple[MemberStatus, ...] = ("invited", "active", "disabled")
+
+
+# Serving an agent, its calls, room tokens, knowledge pushes and evals; never the org's people,
+# numbers or money.
+SERVER_SCOPES: frozenset[KeyScope] = frozenset({"app", "calls", "talk", "knowledge", "evals"})
+
+
+ROLE_SCOPES: Mapping[Role, frozenset[KeyScope]] = {
+    "qa": frozenset({"calls", "evals"}),
+    "supervisor": frozenset({"calls", "evals", "supervise", "talk", "memory", "words"}),
+    "manager": frozenset(
+        {
+            "calls",
+            "evals",
+            "supervise",
+            "talk",
+            "memory",
+            "numbers",
+            "keys",
+            "providers",
+            "usage",
+            "team",
+            "words",
+        }
+    ),
+    "admin": KEY_SCOPES,
+    "developer": frozenset(
+        {"app", "calls", "talk", "supervise", "pipeline", "knowledge", "memory", "evals", "words"}
+    ),
+}
+
+
+# The browser's scopes, limited to their own call: the guest log and the widget's channel admit
+# them.
+READS_ITS_OWN_CALL: frozenset[RoomScope] = frozenset({"talk", "chat", "read", "participate"})
+
+
+def key_scopes(words: Iterable[str]) -> frozenset[KeyScope]:
+    """Return the words as scopes, raising DeclarationRefused on the first that is none."""
+    scopes: set[KeyScope] = set()
+    for word in sorted(set(words)):
+        if word not in EVERY_SCOPE:
+            raise DeclarationRefused(
+                f"{word!r} is not a key scope; the scopes are {sorted(EVERY_SCOPE)}"
+            )
+        scopes.add(word)
+    return frozenset(scopes)
+
+
+def parse_role(word: str) -> Role:
+    """Return the word as a Role, raising DeclarationRefused when it is none."""
+    if word not in ROLES:
+        raise DeclarationRefused(f"a role is one of {sorted(ROLES)}, not {word!r}")
+    return word
+
+
+def parse_status(word: str) -> MemberStatus:
+    """Return the word as a member's status, raising DeclarationRefused when it is none."""
+    if word not in STATUSES:
+        raise DeclarationRefused(f"a member's status is one of {sorted(STATUSES)}, not {word!r}")
+    return word

pinecall/domain/scope.py

@@ -0,0 +1,21 @@
+"""A scope: an org, one of its two worlds, and the holder a request acts as."""
+
+from dataclasses import dataclass
+
+from pinecall.domain.names import PRODUCTION, Env
+
+# Holder value for org-owned rows: an empty string, not NULL, because it is part of a primary
+# key and NULL never matches.
+THE_ORGS_OWN = ""
+
+SCOPE_ATTRIBUTE = "pinecall.scope"
+
+
+# What a request may see: an org, one of its two worlds, and in the sandbox one developer's own.
+@dataclass(frozen=True)
+class Scope:
+    """An org's scope: the org, the environment and the holder ("" for the org itself)."""
+
+    org: str
+    env: Env = PRODUCTION
+    holder: str = THE_ORGS_OWN