pw-core 0.27.0__py3-none-any.whl

pw_core/__init__.py

@@ -0,0 +1,27 @@
+"""pw-core: the application framework on top of pw-foundation.
+
+The base install (``pip install pw-core``) brings pw-foundation — structured logging, the
+exception hierarchy, the config base and env resolvers, pure utils, ``Service``, the
+``pw-guards`` gate — and adds pw-core's own dependency-light modules: the ``AppConfig``
+subclass with the framework settings, json recovery, similarity, vocab, parsers, budget.
+Consumers import the foundation as ``pw_foundation.*``; nothing is re-exported here.
+
+Everything else ships as opt-in, orthogonally-composable extras: anti-slop output guards
+(``[validate]``), LLM clients (``[llm]`` ⊇ ``[validate]``), HTTP utils (``[http]``), CLI
+scaffolding (``[cli]``), and the FastAPI + SQLAlchemy app framework (``[db]``, ``[web]``,
+``[jobs]``, ``[tracking]``, ``[eval]``, ``[admin]``). See ``docs/INSTALLATION.md``.
+"""
+
+
+def __getattr__(name: str) -> str:
+    """PEP 562: ``__version__`` reads package metadata on first access, not at import."""
+    if name != "__version__":
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    from importlib.metadata import PackageNotFoundError, version
+
+    try:
+        value = version("pw-core")
+    except PackageNotFoundError:  # running from a source tree with no install
+        value = "0.0.0+unknown"
+    globals()["__version__"] = value
+    return value

pw_core/_env_compat.py

@@ -0,0 +1,27 @@
+"""``PW_*`` env vars with the ``PF_*`` spelling honored until 1.0 (one DeprecationWarning each)."""
+
+from __future__ import annotations
+
+import os
+import warnings
+
+_warned: set[str] = set()
+
+
+def env_name(pw_name: str) -> str:
+    """The name to read: ``pw_name`` if set, else its ``PF_`` spelling if set, else ``pw_name``."""
+    if pw_name in os.environ or not pw_name.startswith("PW_"):
+        return pw_name
+    legacy = "PF_" + pw_name[3:]
+    if legacy in os.environ:
+        if legacy not in _warned:
+            _warned.add(legacy)
+            warnings.warn(
+                f"{legacy} is deprecated; set {pw_name}", DeprecationWarning, stacklevel=3
+            )
+        return legacy
+    return pw_name
+
+
+def getenv(pw_name: str, default: str | None = None) -> str | None:
+    return os.environ.get(env_name(pw_name), default)

pw_core/_extras.py

@@ -0,0 +1,120 @@
+"""Friendly errors for missing optional-dependency extras.
+
+The foundation install (``pip install pw-core``) is dependency-light: it does
+not ship httpx, pydantic, json-repair, tenacity, or typer. Modules that need
+those live behind opt-in extras ([http], [llm], [cli], [jobs], ...). When such
+a module is imported without its extra installed, the bare third-party
+``ImportError`` ("No module named 'json_repair'") is opaque. This helper turns
+it into a message that names the extra and the exact pip command.
+
+Usage at the top of a gated leaf module::
+
+    try:
+        import httpx
+    except ImportError as e:  # pragma: no cover - exercised by bare-install CI
+        from pw_core._extras import extra_import_error
+
+        raise extra_import_error(
+            "llm", "httpx", feature="pw_core.clients.openrouter"
+        ) from e
+"""
+
+from __future__ import annotations
+
+# Extra name -> the pip target a user should install. Anything not listed
+# falls back to ``pw-core[<extra>]``.
+_INSTALL: dict[str, str] = {
+    "http": "pw-core[http]",
+    "cli": "pw-core[cli]",
+    "validate": "pw-core[validate]",
+    "llm": "pw-core[llm]",
+    "db": "pw-core[db]",
+    "web": "pw-core[web]",
+    "jobs": "pw-core[jobs]",
+    "tracking": "pw-core[tracking]",
+    "eval": "pw-core[eval]",
+    "otel": "pw-core[otel]",
+    "admin": "pw-core[admin]",
+    "articles": "pw-core[articles]",
+    "jsonschema": "pw-core[jsonschema]",
+    "redis": "pw-core[redis]",
+    "ratelimit": "pw-core[ratelimit]",
+}
+
+
+# Module prefix -> the extra needed to import it. Longest prefix wins, so a
+# subpackage may sit above its parent. Unlisted means base install: no extras.
+# Enforced against the source tree by tests/test_extras_tiers.py.
+_MODULE_EXTRA: dict[str, str] = {
+    "pw_core.alembic": "db",
+    "pw_core.budget._aggregate": "tracking",
+    "pw_core.budget._schema": "tracking",
+    "pw_core.budget.audit": "tracking",
+    "pw_core.budget.repo": "tracking",
+    "pw_core.budget.scheduler": "tracking",
+    "pw_core.budget.snapshot_job": "tracking",
+    "pw_core.cli": "cli",
+    "pw_core.cli.export": "otel",
+    "pw_core.cli.jobs": "jobs",
+    "pw_core.clients.anthropic": "anthropic",
+    "pw_core.clients.brave": "llm",
+    "pw_core.clients.openrouter": "llm",
+    "pw_core.db": "db",
+    "pw_core.eval": "eval",
+    # Minimum tier to import, not the extra you'd install for the feature:
+    # jobs modules import under [tracking]; only the CLI needs typer.
+    "pw_core.jobs": "tracking",
+    "pw_core.llm.cache": "tracking",
+    "pw_core.llm.parse": "validate",
+    "pw_core.llm.step": "tracking",
+    "pw_core.llm.tracked": "tracking",
+    "pw_core.llm.tracking": "tracking",
+    "pw_core.llm.tracking.otel": "otel",
+    "pw_core.llm.validate": "validate",
+    # [crawl] = [http,articles]: article_fetch imports utils.urls, which needs httpx.
+    "pw_core.utils.article_fetch": "crawl",
+    "pw_core.utils.phash": "image-phash",
+    "pw_core.utils.url_liveness": "http",
+    "pw_core.utils.urls": "http",
+    "pw_core.web": "web",
+    # Both dashboards need [web] + a DB tier; [admin] supplies both.
+    "pw_core.web.jobs_admin": "admin",
+    "pw_core.web.llm_admin": "admin",
+}
+
+
+def required_extra(module: str) -> str | None:
+    """The extra needed to import *module*, or ``None`` if it is base-install.
+
+    Longest matching prefix wins, so ``pw_core.llm.tracking.repo`` resolves to
+    ``tracking`` rather than to whatever ``pw_core.llm`` would give.
+    """
+    best: str | None = None
+    best_len = -1
+    for prefix, extra in _MODULE_EXTRA.items():
+        if (module == prefix or module.startswith(prefix + ".")) and len(prefix) > best_len:
+            best, best_len = extra, len(prefix)
+    return best
+
+
+def install_target(extra: str) -> str:
+    """Return the ``pip install`` target for an extra (e.g. ``pw-core[llm]``)."""
+    return _INSTALL.get(extra, f"pw-core[{extra}]")
+
+
+def extra_import_error(extra: str, package: str, *, feature: str) -> ImportError:
+    """Build an ``ImportError`` that names the missing extra and pip command.
+
+    Args:
+        extra: The optional-dependency extra that ships ``package`` (e.g. ``"llm"``).
+        package: The third-party import name that failed (e.g. ``"json_repair"``).
+        feature: The pw-core module or capability the caller was importing, used
+            in the message (e.g. ``"pw_core.llm.parse"``).
+
+    Returns:
+        An ``ImportError`` to ``raise ... from`` the original failure.
+    """
+    return ImportError(
+        f"{feature} requires the '{extra}' extra; '{package}' is not installed. "
+        f"Install it with:  pip install {install_target(extra)}"
+    )

pw_core/alembic.py

@@ -0,0 +1,72 @@
+"""
+Alembic migration helper — shared env.py logic for all projects.
+
+Supports SQLite (batch mode), MySQL/MariaDB, and PostgreSQL. Uses pw_core.db
+for engine management so migrations share the same connection config as the app.
+
+Usage in a project's ``alembic/env.py``::
+
+    from pw_core.alembic import run_migrations_online
+
+    run_migrations_online()
+
+With SQLite fallback (e.g., a small app on SQLite)::
+
+    from pw_core.alembic import run_migrations_online
+
+    run_migrations_online(fallback_sqlite="app.db")
+
+With explicit metadata (for autogenerate)::
+
+    from myapp.models import Base
+    from pw_core.alembic import run_migrations_online
+
+    run_migrations_online(target_metadata=Base.metadata)
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from alembic import context
+
+from pw_core.db import db_url, get_engine, is_sqlite
+
+
+def run_migrations_online(
+    *,
+    fallback_sqlite: str = "",
+    target_metadata: Any = None,
+    compare_type: bool = False,
+) -> None:
+    """Run Alembic migrations in online mode.
+
+    Call this from your project's ``alembic/env.py``. Handles:
+    - SQLite batch mode (``render_as_batch=True``)
+    - MySQL/MariaDB and PostgreSQL standard mode
+    - Engine reuse via ``pw_core.db.get_engine()``
+
+    Args:
+        fallback_sqlite: Path to SQLite file if DATABASE_URL is not set.
+        target_metadata: SQLAlchemy MetaData for autogenerate support.
+            Pass ``None`` (default) for raw-SQL migrations.
+        compare_type: Whether Alembic should detect column type changes.
+    """
+    if context.is_offline_mode():
+        raise RuntimeError(
+            "Offline mode is not supported. Set DATABASE_URL and run in online mode."
+        )
+
+    url = db_url(fallback_sqlite=fallback_sqlite)
+    sqlite = is_sqlite(url)
+    engine = get_engine(url)
+
+    with engine.connect() as connection:
+        context.configure(
+            connection=connection,
+            target_metadata=target_metadata,
+            compare_type=compare_type,
+            render_as_batch=sqlite,
+        )
+        with context.begin_transaction():
+            context.run_migrations()

pw_core/budget/__init__.py

@@ -0,0 +1,154 @@
+"""
+Pre-call cost guardrails for LLM spending.
+
+The kernel-safe surface (importable without ``pw-core[db]``) covers the
+budget guard itself and YAML config loading:
+
+    from pw_core.budget import (
+        check_budget, project_cost, CostBudgetExceeded,
+        compute_period_start, compute_period_end, current_spent, current_usage,
+        load_yaml, clear_config_cache,
+    )
+
+The DB-backed surface (requires ``pw-core[db]``) is loaded lazily — the
+import only triggers SQLAlchemy when an attribute is first accessed:
+
+    from pw_core.budget import (
+        BudgetRepo, BudgetSnapshotRepo, CostRateRepo, aggregate_spent,
+        aggregate_usage, sync_budgets_from_yaml,
+        refresh_snapshots, start_budget_refresh_loop,
+        record_blocked_run, record_override,
+        ALL_BUDGET_TABLES, llm_budgets, llm_budget_snapshots, llm_cost_rates,
+    )
+
+In a kernel-only install (no ``[db]`` extra), ``check_budget()`` and
+``project_cost()`` still import and run, but ``project_cost()`` falls back
+to ``0.0`` when no DB-backed cost rates are reachable, and any code path
+that calls into the repos will surface ``ModuleNotFoundError: sqlalchemy``.
+
+See ``docs/cost-budget.md``.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+# Eager imports — kernel-safe modules with no top-level sqlalchemy coupling.
+# These remain importable in a base ``pip install pw-core`` (no extras).
+from pw_core.budget.check import (  # noqa: F401
+    CostBudgetExceeded,
+    check_budget,
+    compute_period_end,
+    compute_period_start,
+    current_spent,
+    current_usage,
+    project_cost,
+)
+from pw_core.budget.config import (  # noqa: F401
+    clear_config_cache,
+    load_yaml,
+)
+
+
+# Lazy imports — these submodules pull SQLAlchemy at module top, so we
+# defer them via PEP 562 ``__getattr__`` to keep the kernel install clean.
+# The first attribute access triggers the import; subsequent accesses are
+# free because we cache into ``globals()``.
+_LAZY: dict[str, str] = {
+    # Repos (DB-required)
+    "BudgetRepo": "pw_core.budget.repo",
+    "BudgetSnapshotRepo": "pw_core.budget.repo",
+    "CostRateRepo": "pw_core.budget.repo",
+    "aggregate_spent": "pw_core.budget._aggregate",
+    "aggregate_usage": "pw_core.budget._aggregate",
+    # Audit logging (DB-required)
+    "record_blocked_run": "pw_core.budget.audit",
+    "record_override": "pw_core.budget.audit",
+    # Snapshot / scheduler jobs (DB-required)
+    "refresh_snapshots": "pw_core.budget.snapshot_job",
+    "start_budget_refresh_loop": "pw_core.budget.scheduler",
+    # YAML→DB sync (DB-required path within the otherwise-kernel config module)
+    "sync_budgets_from_yaml": "pw_core.budget.config",
+    # Schema tables (DB-required — registers on shared MetaData on first access)
+    "ALL_BUDGET_TABLES": "pw_core.budget._schema",
+    "llm_budgets": "pw_core.budget._schema",
+    "llm_budget_snapshots": "pw_core.budget._schema",
+    "llm_cost_rates": "pw_core.budget._schema",
+}
+
+
+def __getattr__(name: str):
+    """Lazy import for DB-required attributes (PEP 562)."""
+    target = _LAZY.get(name)
+    if target is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    import importlib
+
+    mod = importlib.import_module(target)
+    value = getattr(mod, name)
+    globals()[name] = value  # cache so subsequent access skips __getattr__
+    return value
+
+
+def __dir__() -> list[str]:
+    """Expose lazy attributes to ``dir()`` and IDE autocomplete."""
+    return sorted(set(globals()) | set(_LAZY))
+
+
+# Type-checker view of the lazy attributes — keeps ``mypy`` / IDEs happy
+# without paying the import cost at runtime.
+if TYPE_CHECKING:
+    from pw_core.budget._schema import (  # noqa: F401
+        ALL_BUDGET_TABLES,
+        llm_budget_snapshots,
+        llm_budgets,
+        llm_cost_rates,
+    )
+    from pw_core.budget.audit import (  # noqa: F401
+        record_blocked_run,
+        record_override,
+    )
+    from pw_core.budget.config import sync_budgets_from_yaml  # noqa: F401
+    from pw_core.budget.repo import (  # noqa: F401
+        BudgetRepo,
+        BudgetSnapshotRepo,
+        CostRateRepo,
+        aggregate_spent,
+        aggregate_usage,
+    )
+    from pw_core.budget.scheduler import start_budget_refresh_loop  # noqa: F401
+    from pw_core.budget.snapshot_job import refresh_snapshots  # noqa: F401
+
+
+__all__ = [
+    # Guard (eager)
+    "check_budget",
+    "project_cost",
+    "CostBudgetExceeded",
+    "compute_period_start",
+    "compute_period_end",
+    "current_spent",
+    "current_usage",
+    # Config — kernel-safe (eager)
+    "load_yaml",
+    "clear_config_cache",
+    # Config — DB-backed (lazy)
+    "sync_budgets_from_yaml",
+    # Repos (lazy)
+    "BudgetRepo",
+    "BudgetSnapshotRepo",
+    "CostRateRepo",
+    "aggregate_spent",
+    "aggregate_usage",
+    # Snapshot / scheduler jobs (lazy)
+    "refresh_snapshots",
+    "start_budget_refresh_loop",
+    # Audit (lazy)
+    "record_blocked_run",
+    "record_override",
+    # Schema (lazy)
+    "ALL_BUDGET_TABLES",
+    "llm_budgets",
+    "llm_budget_snapshots",
+    "llm_cost_rates",
+]

pw_core/budget/_aggregate.py

@@ -0,0 +1,160 @@
+"""Scope filtering and usage aggregation over ``llm_runs``.
+
+Re-exported from :mod:`pw_core.budget.repo` and ``pw_core.budget``.
+See ``docs/cost-budget.md``.
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+from typing import Any
+
+from sqlalchemy import and_, func, select
+
+from pw_core.db.types import server_now
+from pw_foundation.exceptions import DataError, InvalidInputError
+
+
+# ---------------------------------------------------------------------------
+# Spent aggregation
+# ---------------------------------------------------------------------------
+
+
+def apply_scope_filter(q, budget: dict):
+    """Restrict an ``llm_runs`` query to the runs a budget's scope covers.
+
+    The single definition — snapshot aggregate and live delta must not
+    disagree about what a budget counts.
+
+    Raises:
+        InvalidInputError: unrecognised ``scope_kind``.
+    """
+    from pw_core.llm.tracking.schema import (
+        llm_agent_types,
+        llm_run_tags,
+        llm_runs,
+    )
+
+    scope_kind = budget["scope_kind"]
+    scope_value = budget.get("scope_value")
+
+    if scope_kind == "global":
+        return q
+    if scope_kind == "agent":
+        return q.join(llm_agent_types, llm_runs.c.agent_type_id == llm_agent_types.c.id).where(
+            llm_agent_types.c.slug == scope_value
+        )
+    if scope_kind == "job_kind":
+        from pw_core.jobs._schema import jobs
+
+        return q.join(jobs, llm_runs.c.job_id == jobs.c.id).where(jobs.c.kind == scope_value)
+    if scope_kind == "job_id":
+        if scope_value is None:
+            raise InvalidInputError("budget scope 'job_id' requires a scope_value")
+        return q.where(llm_runs.c.job_id == int(scope_value))
+    if scope_kind == "tag":
+        return q.join(llm_run_tags, llm_runs.c.id == llm_run_tags.c.llm_run_id).where(
+            llm_run_tags.c.tag == scope_value
+        )
+    raise InvalidInputError(f"unknown budget scope_kind: {scope_kind!r}")
+
+
+def db_now(conn=None) -> dt.datetime:
+    """Read the clock ``llm_runs.created_at`` is stamped from.
+
+    Cutoffs compared against server-stamped rows must come from the same
+    clock — a Python-side UTC value skews on MySQL TIMESTAMP columns.
+    """
+    if conn is not None:
+        return _read_now(conn)
+    from pw_core.db.connection import transaction
+
+    with transaction() as c:
+        return _read_now(c)
+
+
+def _read_now(conn: Any) -> dt.datetime:
+    value = conn.execute(select(server_now())).scalar()
+    if value is None:  # pragma: no cover - a scalar clock select always yields a row
+        raise DataError("database clock query returned no row")
+    return value
+
+
+def usage_columns() -> tuple[Any, Any, Any]:
+    """The three usage aggregates in (usd, tokens, calls) order — one definition
+    for the snapshot aggregate and the live delta.
+
+    ``prompt_tokens`` excludes cached input, so the token total adds the cache
+    columns back to count what the call actually consumed.
+    """
+    from pw_core.llm.tracking.schema import llm_runs
+
+    return (
+        func.coalesce(func.sum(llm_runs.c.cost_usd), 0),
+        func.coalesce(
+            func.sum(
+                func.coalesce(llm_runs.c.prompt_tokens, 0)
+                + func.coalesce(llm_runs.c.completion_tokens, 0)
+                + func.coalesce(llm_runs.c.cache_read_tokens, 0)
+                + func.coalesce(llm_runs.c.cache_write_tokens, 0)
+            ),
+            0,
+        ),
+        func.count(llm_runs.c.id),
+    )
+
+
+def aggregate_usage(
+    *,
+    budget: dict,
+    period_start: dt.date,
+    period_end: dt.date,
+    cutoff: dt.datetime | None = None,
+    conn=None,
+) -> dict[str, float | int]:
+    """Aggregate the runs matching a budget's scope in [period_start, period_end).
+
+    Returns ``{"usd": float, "tokens": int, "calls": int}`` — cost sum, token
+    sum over all four token columns (uncached prompt, completion, cache read,
+    cache write), and run count. Excludes rows with
+    ``status IN ('cache_hit', 'budget_blocked')``. ``cutoff`` bounds the
+    aggregate to ``created_at < cutoff``; store it as the snapshot's
+    ``last_updated`` so the live delta resumes exactly there.
+    """
+    from pw_core.llm.tracking.schema import llm_runs
+
+    def _run(c):
+        q = select(*usage_columns()).where(
+            and_(
+                llm_runs.c.created_at >= period_start,
+                llm_runs.c.created_at < period_end,
+                llm_runs.c.status.notin_(["cache_hit", "budget_blocked"]),
+            )
+        )
+        if cutoff is not None:
+            q = q.where(llm_runs.c.created_at < cutoff)
+
+        usd, tokens, n = c.execute(apply_scope_filter(q, budget)).fetchone()
+        return {"usd": float(usd or 0), "tokens": int(tokens or 0), "calls": int(n or 0)}
+
+    if conn is not None:
+        return _run(conn)
+    from pw_core.db.connection import transaction
+
+    with transaction() as c:
+        return _run(c)
+
+
+def aggregate_spent(
+    *,
+    budget: dict,
+    period_start: dt.date,
+    period_end: dt.date,
+    cutoff: dt.datetime | None = None,
+    conn=None,
+) -> tuple[float, int]:
+    """Backward-compatible ``(cost_usd sum, run count)`` view of :func:`aggregate_usage`."""
+    usage = aggregate_usage(
+        budget=budget, period_start=period_start, period_end=period_end, cutoff=cutoff, conn=conn
+    )
+    return (float(usage["usd"]), int(usage["calls"]))

pw_core/budget/_schema.py

@@ -0,0 +1,114 @@
+"""
+SQLAlchemy schema for pw-core cost budgets.
+
+Defines three framework-owned tables that enforce per-agent, per-job, and
+per-tag cost caps on LLM calls:
+
+- ``llm_budgets`` — authoritative budget definitions (one row per scope+period)
+- ``llm_budget_snapshots`` — periodic aggregate cache for fast pre-call checks
+- ``llm_cost_rates`` — per-model price list for projecting call cost
+
+Shares the ``metadata`` object from ``pw_core.llm.tracking.schema`` so a
+single ``metadata.create_all()`` creates tracking, jobs, cache, and budget
+tables in one pass.
+
+See ``docs/cost-budget.md`` for the full reference.
+"""
+
+from __future__ import annotations
+
+from sqlalchemy import (
+    BigInteger,
+    Boolean,
+    Column,
+    Date,
+    ForeignKey,
+    Index,
+    Integer,
+    Numeric,
+    PrimaryKeyConstraint,
+    String,
+    Table,
+    UniqueConstraint,
+)
+
+from pw_core.db.types import FK_SMALL, JSON_, PK_SMALL, TIMESTAMP_US, server_now
+from pw_core.llm.tracking.schema import metadata
+
+# ---------------------------------------------------------------------------
+# Tables
+# ---------------------------------------------------------------------------
+
+llm_budgets = Table(
+    "llm_budgets",
+    metadata,
+    Column("id", PK_SMALL, primary_key=True, autoincrement=True),
+    Column("scope_kind", String(32), nullable=False),
+    Column("scope_value", String(128), nullable=True),
+    Column("period", String(16), nullable=False),
+    Column("limit_usd", Numeric(12, 4), nullable=True),
+    Column("limit_tokens", BigInteger, nullable=True),
+    Column("limit_calls", Integer, nullable=True),
+    Column("soft_thresholds", JSON_, nullable=True),
+    Column("hard_cap", Boolean, nullable=False, server_default="1"),
+    Column("action", String(32), nullable=False, server_default="block"),
+    Column("enabled", Boolean, nullable=False, server_default="1"),
+    Column("created_at", TIMESTAMP_US, nullable=False, server_default=server_now()),
+    Column("updated_at", TIMESTAMP_US, nullable=False, server_default=server_now()),
+    UniqueConstraint("scope_kind", "scope_value", "period", name="uq_llm_budgets_scope_period"),
+    Index("idx_llm_budgets_enabled", "enabled"),
+)
+"""Budget definitions. scope_kind ∈ {global, agent, job_kind, job_id, tag}."""
+
+
+llm_budget_snapshots = Table(
+    "llm_budget_snapshots",
+    metadata,
+    Column(
+        "budget_id",
+        FK_SMALL,
+        ForeignKey("llm_budgets.id", ondelete="CASCADE"),
+        nullable=False,
+    ),
+    Column("period_start", Date, nullable=False),
+    Column("spent_usd", Numeric(12, 4), nullable=False, server_default="0"),
+    Column("spent_tokens", BigInteger, nullable=False, server_default="0"),
+    Column("run_count", Integer, nullable=False, server_default="0"),
+    Column("last_updated", TIMESTAMP_US, nullable=False, server_default=server_now()),
+    PrimaryKeyConstraint("budget_id", "period_start", name="pk_llm_budget_snapshots"),
+    Index("idx_llm_budget_snapshots_period", "period_start"),
+)
+"""Periodic aggregate cache. Not source of truth — rebuilt from llm_runs."""
+
+
+llm_cost_rates = Table(
+    "llm_cost_rates",
+    metadata,
+    Column(
+        "model_id",
+        FK_SMALL,
+        ForeignKey("llm_models.id", ondelete="CASCADE"),
+        nullable=False,
+    ),
+    Column("input_per_1k", Numeric(8, 6), nullable=False),
+    Column("output_per_1k", Numeric(8, 6), nullable=False),
+    Column("cache_read_per_1k", Numeric(8, 6), nullable=True),
+    Column("cache_write_per_1k", Numeric(8, 6), nullable=True),
+    Column("reasoning_per_1k", Numeric(8, 6), nullable=True),
+    Column("effective_from", Date, nullable=False),
+    Column("effective_to", Date, nullable=True),
+    PrimaryKeyConstraint("model_id", "effective_from", name="pk_llm_cost_rates"),
+    Index("idx_llm_cost_rates_model_eff", "model_id", "effective_from"),
+)
+"""Per-model price list. Multiple rows per model allowed (versioned pricing)."""
+
+
+# ---------------------------------------------------------------------------
+# Public table list (in dependency order)
+# ---------------------------------------------------------------------------
+
+ALL_BUDGET_TABLES = (
+    llm_budgets,
+    llm_budget_snapshots,
+    llm_cost_rates,
+)