pinecall-runtime 0.1.6__py3-none-any.whl

pinecall/log/usage.py

@@ -0,0 +1,242 @@
+"""What a scope used: a window of whole days in numbers, and the metered feed past a cursor."""
+
+from dataclasses import asdict, dataclass
+from datetime import UTC, date, datetime
+
+from psycopg import sql
+from psycopg.rows import DictRow
+
+from pinecall.domain.errors import DeclarationRefused
+from pinecall.domain.names import CHANNELS
+from pinecall.domain.scope import Scope
+from pinecall.log.facts import STAGES
+from pinecall.log.reduce import METERED_TYPES, UsageRow, usage_row
+from pinecall.log.store import Store
+from pinecall.postgres.pool import Pool
+
+# Days are cut in UTC: an org has no timezone.
+A_DAY_S = 24 * 60 * 60
+
+
+_IN_THE_WINDOW = sql.SQL("head.started_at >= %(start)s and head.started_at < %(end)s")
+
+
+# A window's rows: the scope's calls, or one agent's when the window names one.
+_THE_WINDOWS_CALLS = sql.SQL("""
+from call_log_head head left join call_facts f on f.call = head.log
+where head.org = %(org)s and head.env = %(env)s and head.holder = %(holder)s
+  and head.call is not null and (%(agent)s::text is null or head.agent = %(agent)s)
+""")
+
+
+@dataclass(frozen=True, slots=True)
+class AgentWindow:
+    """One agent's window: its calls, the share of judgments it held, what it cost by stage."""
+
+    slug: str
+    calls: int
+    score: float | None
+    # Dollars by stage (llm, stt, tts, phone, platform), and the minutes of the calls that ended.
+    spend: dict[str, float]
+    minutes: float
+
+
+@dataclass(frozen=True, slots=True)
+class WindowDay:
+    """One UTC day of a window: its calls by door, what they cost, and how their judges answered."""
+
+    day: date
+    channels: dict[str, int]
+    spent: float
+    judged: int
+    passed: int
+
+
+@dataclass(frozen=True, slots=True)
+class Window:
+    """A scope's window of whole UTC days in numbers, and the window of the same length before."""
+
+    calls: int
+    before: int
+    finished: int
+    unescalated: int
+    judged: int
+    passed: int
+    escalated: int
+    mean_length: float | None
+    median_e2e: float | None
+    spent: float
+    channels: dict[str, int]
+    endings: list[tuple[str, int]]
+    days: list[WindowDay]
+    agents: list[AgentWindow]
+    total: int
+    live: int
+
+
+@dataclass(frozen=True, slots=True)
+class MeteredPage:
+    """One page of the usage feed: the rows kept, and the cursor past everything read."""
+
+    rows: list[UsageRow]
+    next: int | None
+
+
+# "before" is the window of the same length right before it. A call is judged once a judge
+# settled, and passed unless a judge said it did not (CallFacts.score).
+WINDOW = (
+    sql.SQL("""
+select
+    count(*) filter (where {window}) as calls,
+    count(*) filter (where head.started_at >= %(start)s - (%(end)s - %(start)s)
+                       and head.started_at < %(start)s) as before,
+    count(*) filter (where {window} and f.ended_at is not null) as finished,
+    count(*) filter (where {window} and f.ended_at is not null and not f.escalated)
+        as unescalated,
+    count(*) filter (where {window} and f.judged > 0) as judged,
+    count(*) filter (where {window} and f.judged > 0 and f.passed is not false) as passed,
+    count(*) filter (where {window} and f.escalated) as escalated,
+    avg(f.ended_at - head.started_at) filter (where {window} and f.ended_at is not null)
+        as mean_length,
+    coalesce(sum(f.cost_usd) filter (where {window}), 0) as spent,
+    count(*) filter (where {window} and f.channel = 'phone') as phone,
+    count(*) filter (where {window} and f.channel = 'web') as web,
+    count(*) filter (where {window} and f.channel = 'whatsapp') as whatsapp,
+    count(*) as total,
+    count(*) filter (where not head.sealed) as live
+""").format(window=_IN_THE_WINDOW)
+    + _THE_WINDOWS_CALLS
+)
+
+
+WINDOW_MEDIAN_E2E = sql.SQL("""
+select percentile_cont(0.5) within group (order by turn.seconds) as median
+from call_log_head head
+join call_facts f on f.call = head.log
+cross join lateral unnest(f.e2e) as turn(seconds)
+where head.org = %(org)s and head.env = %(env)s and head.holder = %(holder)s
+  and head.call is not null and (%(agent)s::text is null or head.agent = %(agent)s)
+  and {window}
+""").format(window=_IN_THE_WINDOW)
+
+
+WINDOW_BY_AGENT = (
+    sql.SQL("""
+select head.agent as slug, count(*) as calls,
+       avg(f.held::double precision / f.judged) filter (where f.judged > 0) as score,
+       coalesce(sum(f.cost_llm_usd), 0) as llm, coalesce(sum(f.cost_stt_usd), 0) as stt,
+       coalesce(sum(f.cost_tts_usd), 0) as tts, coalesce(sum(f.cost_phone_usd), 0) as phone,
+       coalesce(sum(f.cost_platform_usd), 0) as platform,
+       coalesce(sum(f.ended_at - head.started_at) filter (where f.ended_at is not null), 0) / 60
+           as minutes
+""")
+    + _THE_WINDOWS_CALLS
+    + sql.SQL("""
+  and {window}
+group by head.agent
+order by calls desc, slug
+""").format(window=_IN_THE_WINDOW)
+)
+
+
+WINDOW_ENDINGS = (
+    sql.SQL("select f.end_reason as reason, count(*) as count ")
+    + _THE_WINDOWS_CALLS
+    + sql.SQL("""
+  and {window} and f.end_reason is not null
+group by f.end_reason
+order by count desc, reason
+""").format(window=_IN_THE_WINDOW)
+)
+
+
+# Days are cut in UTC, as everywhere: the day of a call is its start's whole days since the epoch.
+WINDOW_BY_DAY = (
+    sql.SQL("""
+select floor(head.started_at / %(a_day)s)::bigint as epoch_day,
+       count(*) filter (where f.channel = 'phone') as phone,
+       count(*) filter (where f.channel = 'web') as web,
+       count(*) filter (where f.channel = 'whatsapp') as whatsapp,
+       coalesce(sum(f.cost_usd), 0) as spent,
+       count(*) filter (where f.judged > 0) as judged,
+       count(*) filter (where f.judged > 0 and f.passed is not false) as passed
+""")
+    + _THE_WINDOWS_CALLS
+    + sql.SQL("""
+  and {window}
+group by epoch_day
+""").format(window=_IN_THE_WINDOW)
+)
+
+
+# The cursor moves past every row read, kept or not, so a page filtered to one org still moves.
+async def metered_page(store: Store, *, after: int, limit: int, org: str | None) -> MeteredPage:
+    """The metered rows after the cursor, of one org or of every org, folded."""
+    read = [usage_row(item) for item in await store.across(METERED_TYPES, after=after, limit=limit)]
+    kept = [row for row in read if org is None or row.org == org]
+    return MeteredPage(rows=kept, next=read[-1].cursor if read else None)
+
+
+# One agent's window when it names one; the whole scope's when it is None.
+async def counted_window(
+    pool: Pool, scope: Scope, start: float, end: float, agent: str | None
+) -> Window:
+    """Return the scope's window from start to end, both on a UTC midnight, in numbers."""
+    params = {**asdict(scope), "start": start, "end": end, "agent": agent, "a_day": A_DAY_S}
+    # independent: five counts of one window, each its own snapshot
+    async with pool.connection() as connection:
+        counted = await (await connection.execute(WINDOW, params)).fetchone()
+        median = await (await connection.execute(WINDOW_MEDIAN_E2E, params)).fetchone()
+        agents = await (await connection.execute(WINDOW_BY_AGENT, params)).fetchall()
+        endings = await (await connection.execute(WINDOW_ENDINGS, params)).fetchall()
+        by_day = await (await connection.execute(WINDOW_BY_DAY, params)).fetchall()
+    if counted is None:
+        raise DeclarationRefused("a window counts, even an empty one")
+    return Window(
+        calls=int(counted["calls"]),
+        before=int(counted["before"]),
+        finished=int(counted["finished"]),
+        unescalated=int(counted["unescalated"]),
+        judged=int(counted["judged"]),
+        passed=int(counted["passed"]),
+        escalated=int(counted["escalated"]),
+        mean_length=None if counted["mean_length"] is None else float(counted["mean_length"]),
+        median_e2e=None if median is None else median["median"],
+        spent=float(counted["spent"]),
+        channels={door: int(counted[door]) for door in CHANNELS},
+        endings=[(row["reason"], int(row["count"])) for row in endings],
+        days=_every_day(start, end, {int(row["epoch_day"]): row for row in by_day}),
+        agents=[
+            AgentWindow(
+                slug=row["slug"],
+                calls=row["calls"],
+                score=row["score"],
+                spend={stage: float(row[stage]) for stage in STAGES},
+                minutes=float(row["minutes"]),
+            )
+            for row in agents
+        ],
+        total=int(counted["total"]),
+        live=int(counted["live"]),
+    )
+
+
+# Every day of the window has its row, a day nobody called included, so a chart has no holes.
+def _every_day(start: float, end: float, counted: dict[int, DictRow]) -> list[WindowDay]:
+    first, last = int(start // A_DAY_S), int(end // A_DAY_S)
+    return [_day_of(epoch_day, counted.get(epoch_day)) for epoch_day in range(first, last)]
+
+
+def _day_of(epoch_day: int, row: DictRow | None) -> WindowDay:
+    day = datetime.fromtimestamp(epoch_day * A_DAY_S, UTC).date()
+    if row is None:
+        return WindowDay(
+            day=day, channels=dict.fromkeys(CHANNELS, 0), spent=0.0, judged=0, passed=0
+        )
+    return WindowDay(
+        day=day,
+        channels={door: int(row[door]) for door in CHANNELS},
+        spent=float(row["spent"]),
+        judged=int(row["judged"]),
+        passed=int(row["passed"]),
+    )

pinecall/postgres/migrate.py

@@ -0,0 +1,202 @@
+"""The migration runner: the .sql files beside it, applied in order, never edited."""
+
+import asyncio
+import hashlib
+from dataclasses import dataclass
+from pathlib import Path
+
+import psycopg
+from psycopg import sql
+
+from pinecall.domain.errors import MigrationsRefused
+from pinecall.postgres.pool import (
+    DEFAULT_SCHEMA,
+    Connection,
+    Pool,
+    connect,
+    database_named,
+    schemas_of,
+)
+
+# Applied in name order. An applied migration is never edited: add a new one instead.
+MIGRATIONS = Path(__file__).parent / "migrations"
+FIRST = "0001_schema.sql"
+
+# First-line marker that runs a file outside a transaction, required by CREATE INDEX CONCURRENTLY.
+# Such a file holds ONE statement: Postgres runs a multi-statement string as one implicit
+# transaction.
+NO_TRANSACTION = "-- pinecall:no-transaction"
+
+# Fails fast instead of queueing behind a reader and blocking every writer behind it.
+LOCK_TIMEOUT_MS = 1_000
+
+# Serializes concurrent runners; any constant no other code in the database uses.
+ADVISORY_LOCK = 0x9E3_C411
+
+MIGRATIONS_TABLE = """
+create table if not exists schema_migrations (
+    name       text primary key,
+    applied_at timestamptz not null default now(),
+    sha256     text
+)
+"""
+APPLIED = "select name, sha256 from schema_migrations order by name"
+RECORD = "insert into schema_migrations (name, sha256) values (%s, %s)"
+
+EDITED = (
+    "migration {name} changed after it was applied: this database ran a different file.\n"
+    "  applied  sha256 {was}\n"
+    "  on disk  sha256 {now}\n"
+    "An applied migration is never edited: every database that ran it has the OLD one. Put the "
+    "change in a new migration, or restore the file."
+)
+# The rows of every table and the sequences behind them, now and for every table the owner makes
+# later (a day of call_log among them); never a table's shape, never TRUNCATE.
+GRANTS = (
+    "grant usage on schema {schema} to {role}",
+    "grant select, insert, update, delete on all tables in schema {schema} to {role}",
+    "grant usage, select, update on all sequences in schema {schema} to {role}",
+    (
+        "alter default privileges in schema {schema} "
+        "grant select, insert, update, delete on tables to {role}"
+    ),
+    (
+        "alter default privileges in schema {schema} "
+        "grant usage, select, update on sequences to {role}"
+    ),
+)
+
+ROLE_EXISTS = "select 1 from pg_roles where rolname = %s"
+
+# CloudNativePG makes the role from its secret a few seconds after the chart says so: waited for.
+ROLE_WAITED_S = 120.0
+ROLE_ASKED_EVERY_S = 2.0
+
+NO_ROLE = (
+    "role {role} does not exist after {waited:g} s: its secret (charts/postgres, the managed role) "
+    "is not synced yet, or the role is named wrong; nothing was granted"
+)
+
+MISSING = (
+    "migration {name} is recorded as applied and is not in this distribution: "
+    "this checkout is older than the database it is pointed at"
+)
+
+
+@dataclass(frozen=True)
+class Applied:
+    """The result of a migration run: the database, the schema and what was applied."""
+
+    database: str
+    schema: str
+    applied: tuple[str, ...]
+
+
+async def apply_migrations(dsn: str, *, schema: str = DEFAULT_SCHEMA) -> Applied:
+    """Apply every pending migration in name order under an advisory lock."""
+    schemas = schemas_of(schema)
+    async with await connect(dsn) as connection:
+        # Before the lock, which may wait on another runner: nothing here is cut by a timeout the
+        # role or PGOPTIONS set. A file waits on a table's lock LOCK_TIMEOUT_MS at most.
+        await connection.execute("set statement_timeout = 0")
+        # Session-level, released with the connection. Taken before any DDL: concurrent
+        # `create schema if not exists` can still fail on pg_namespace's unique index.
+        await connection.execute("select pg_advisory_lock(%s)", (ADVISORY_LOCK,))
+        if schema != DEFAULT_SCHEMA:
+            await connection.execute(
+                sql.SQL("create schema if not exists {}").format(sql.Identifier(schema))
+            )
+        await connection.execute(
+            sql.SQL("set search_path to {}").format(
+                sql.SQL(", ").join(sql.Identifier(schema) for schema in schemas)
+            )
+        )
+        await connection.execute(MIGRATIONS_TABLE)
+        done = await _applied(connection)
+        ran = [
+            await _apply_one(connection, path)
+            for path in migration_files()
+            if path.name not in done
+        ]
+    return Applied(database=database_named(dsn), schema=schema, applied=tuple(ran))
+
+
+# Granted again every run: a table a migration made is granted the moment it exists, and a grant
+# taken away by hand comes back. Refused, not skipped, when the role never came: a gateway that
+# connects as it would find nothing it may read.
+async def granted(dsn: str, role: str, *, schema: str = DEFAULT_SCHEMA) -> None:
+    """Grant the role every table's rows and nothing else, once it exists."""
+    async with await connect(dsn) as connection:
+        waited = 0.0
+        while await (await connection.execute(ROLE_EXISTS, (role,))).fetchone() is None:
+            if waited >= ROLE_WAITED_S:
+                raise MigrationsRefused(NO_ROLE.format(role=role, waited=ROLE_WAITED_S))
+            await asyncio.sleep(ROLE_ASKED_EVERY_S)
+            waited += ROLE_ASKED_EVERY_S
+        names = {"schema": sql.Identifier(schema), "role": sql.Identifier(role)}
+        async with connection.transaction():
+            for grant in GRANTS:
+                await connection.execute(sql.SQL(grant).format(**names))
+
+
+async def migrations_behind(pool: Pool) -> tuple[str, ...]:
+    """Return the migrations the database has not applied; every one, when it has no table."""
+    async with pool.connection() as connection:
+        try:
+            rows = await (await connection.execute(APPLIED)).fetchall()
+        except psycopg.errors.UndefinedTable:
+            rows = []
+    done = {str(row["name"]) for row in rows}
+    return tuple(path.name for path in migration_files() if path.name not in done)
+
+
+def migration_files() -> list[Path]:
+    """Return every shipped migration, in apply order."""
+    return sorted(MIGRATIONS.glob("*.sql"))
+
+
+def file_hash(path: Path) -> str:
+    """Return the SHA-256 of the file's bytes."""
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def in_a_transaction(statements: bytes) -> bool:
+    """Return False when the file's first line is the no-transaction marker."""
+    first = statements.decode("utf-8").lstrip().split("\n", 1)[0].strip()
+    return first != NO_TRANSACTION
+
+
+async def _applied(connection: Connection) -> set[str]:
+    on_disk = {path.name: path for path in migration_files()}
+    rows = await (await connection.execute(APPLIED)).fetchall()
+    recorded = {str(row["name"]): row["sha256"] for row in rows}
+    # A database the previous runtime migrated: its schema is what the first file holds, so the
+    # first file is recorded as applied and the old bookkeeping goes.
+    if recorded and FIRST not in recorded:
+        await connection.execute("delete from schema_migrations")
+        await connection.execute(RECORD, (FIRST, file_hash(on_disk[FIRST])))
+        return {FIRST}
+    for name, was in recorded.items():
+        path = on_disk.get(name)
+        if path is None:
+            raise MigrationsRefused(MISSING.format(name=name))
+        now = file_hash(path)
+        if str(was) != now:
+            raise MigrationsRefused(EDITED.format(name=name, was=was, now=now))
+    return set(recorded)
+
+
+async def _apply_one(connection: Connection, path: Path) -> str:
+    statements = await asyncio.to_thread(path.read_bytes)
+    recorded = (path.name, hashlib.sha256(statements).hexdigest())
+    if not in_a_transaction(statements):
+        await connection.execute(statements)
+        await connection.execute(RECORD, recorded)
+        return path.name
+    async with connection.transaction():
+        await connection.execute(
+            sql.SQL("set local lock_timeout = {}").format(sql.Literal(LOCK_TIMEOUT_MS))
+        )
+        await connection.execute(statements)
+        await connection.execute(RECORD, recorded)
+    return path.name