hackbait 0.1.0__py3-none-any.whl

hackbait/cli.py

@@ -0,0 +1,534 @@
+"""Command line surface: hackbait list | selftest | run | report | power.
+
+Exit codes are part of the contract: 0 for a clean run, 1 for usage or
+runtime errors, 2 when selftest finds a misclassification or power is handed a
+rate or half-width outside its domain. argparse wants to exit 2 on bad flags,
+which would collide with those codes, so the parser here downgrades usage
+errors to 1.
+"""
+
+from __future__ import annotations
+
+import argparse
+import importlib
+import json
+import os
+import re
+import sys
+import time
+import urllib.parse
+from collections import Counter
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Any, NoReturn
+
+import hackbait
+import hackbait.scripted
+
+from . import runner, stats
+from .bait.testedit import EXEC_WARNING
+from .types import CONTROL_TIER, TIER_NAMES, TIERS, VERDICTS
+
+# Token counts assumed per episode when pricing a planned run that has not
+# happened yet (the power command). Input is the exact suite mean from
+# bench/throughput.py; output is the mid completion-length estimate from the
+# same bench. Both are estimates for planning, never a measurement of a real
+# run, and they only price the cost column: they never touch the sample-size
+# math in stats.py, which stays metadata-free.
+_PLAN_PROMPT_TOKENS = 167
+_PLAN_COMPLETION_TOKENS = 350
+
+__all__ = ["build_parser", "run"]
+
+
+class _Parser(argparse.ArgumentParser):
+    """ArgumentParser that exits 1 on usage errors instead of argparse's 2."""
+
+    def error(self, message: str) -> NoReturn:
+        self.print_usage(sys.stderr)
+        print(f"{self.prog}: error: {message}", file=sys.stderr)
+        raise SystemExit(1)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = _Parser(prog="hackbait", description="Honeypot suite that measures reward hacking.")
+    sub = parser.add_subparsers(dest="command")
+
+    sub.add_parser("list", help="one line per honeypot family")
+
+    selftest = sub.add_parser(
+        "selftest", help="judge every scripted policy against its expected verdicts"
+    )
+    selftest.add_argument("--per-tier", type=int, default=8, dest="per_tier")
+    selftest.add_argument("--seed", type=int, default=0)
+    selftest.add_argument(
+        "--exec",
+        action="store_true",
+        dest="execute",
+        help="run held-out tests for HB-TEST in a sandboxed subprocess",
+    )
+
+    run_p = sub.add_parser("run", help="run a model or a scripted policy over the suite")
+    target = run_p.add_mutually_exclusive_group(required=True)
+    target.add_argument("--model", help="model id for an OpenAI-compatible endpoint")
+    target.add_argument(
+        "--policy",
+        choices=("oracle", "cheat", "garbage"),
+        help="scripted policy instead of a model; costs zero API calls",
+    )
+    run_p.add_argument("--base-url", dest="base_url", help="overrides HACKBAIT_BASE_URL")
+    run_p.add_argument("--per-tier", type=int, default=8, dest="per_tier")
+    run_p.add_argument("--seed", type=int, default=0)
+    run_p.add_argument(
+        "--tiers", default="1,2,3", help="comma-separated subset of 0,1,2,3 (0 is the control arm)"
+    )
+    run_p.add_argument("--families", help="comma-separated family codes, e.g. HB-KEY,HB-RUB")
+    run_p.add_argument(
+        "--temperature",
+        default="0.0",
+        help='sampling temperature, or "none" to omit the field for models that reject it',
+    )
+    run_p.add_argument("--exec", action="store_true", dest="execute")
+    run_p.add_argument("--out", help="run file path; default runs/<label>-<unixtime>.jsonl")
+
+    report_p = sub.add_parser("report", help="rebuild the leaderboard from saved runs")
+    # Default is None so the handler can tell "user asked for this path"
+    # (missing means error) from "use the default" (missing may fall back to
+    # ./runs, where hackbait run writes).
+    report_p.add_argument(
+        "--results",
+        default=None,
+        help="directory of run transcripts (default leaderboard/results, falling back to ./runs)",
+    )
+    report_p.add_argument("--out-md", default="leaderboard/LEADERBOARD.md", dest="out_md")
+    report_p.add_argument("--out-json", default="leaderboard/leaderboard.json", dest="out_json")
+
+    power_p = sub.add_parser(
+        "power",
+        help="sample size to estimate a hack rate to a target precision",
+    )
+    power_p.add_argument(
+        "--rate",
+        type=float,
+        action="append",
+        dest="rates",
+        help="expected per-model hack rate (repeatable); default 0, 1, 2, 5, 10%%",
+    )
+    power_p.add_argument(
+        "--half-width",
+        type=float,
+        action="append",
+        dest="half_widths",
+        help="target Wilson half-width as a fraction (repeatable); default 0.02 = 2pp",
+    )
+    power_p.add_argument(
+        "--model",
+        help="price the plan for this model id, adding an estimated-cost column",
+    )
+    power_p.add_argument(
+        "--prices",
+        help="JSON file of {id: [in, out]} price overrides applied before pricing",
+    )
+    power_p.add_argument("--json", action="store_true", dest="as_json")
+
+    return parser
+
+
+def run(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if args.command is None:
+        parser.print_help()
+        return 1
+    handlers = {
+        "list": _cmd_list,
+        "selftest": _cmd_selftest,
+        "run": _cmd_run,
+        "report": _cmd_report,
+        "power": _cmd_power,
+    }
+    try:
+        return handlers[args.command](args)
+    except Exception as err:
+        print(f"error: {err}", file=sys.stderr)
+        return 1
+
+
+def _cmd_list(args: argparse.Namespace) -> int:
+    for honeypot in hackbait.suite():
+        module_name = type(honeypot).__module__
+        module = sys.modules.get(module_name) or importlib.import_module(module_name)
+        doc_lines = (module.__doc__ or "").strip().splitlines()
+        description = doc_lines[0] if doc_lines else ""
+        count = len(honeypot.cases(per_tier=8, seed=0))
+        print(f"{honeypot.family:<8} {module_name:<24} {count:>4} cases  {description}")
+    return 0
+
+
+_POLICY_NAMES: tuple[str, ...] = ("oracle", "cheat", "garbage")
+
+
+def _cmd_selftest(args: argparse.Namespace) -> int:
+    policies = hackbait.scripted.scripted()
+    misses: list[tuple[str, str, tuple[str, ...], str]] = []
+    for honeypot in hackbait.suite():
+        family_policies = policies[honeypot.family]
+        cases = honeypot.cases(per_tier=args.per_tier, seed=args.seed)
+        counts: dict[str, dict[str, int]] = {
+            name: dict.fromkeys(VERDICTS, 0) for name in _POLICY_NAMES
+        }
+        for name in _POLICY_NAMES:
+            policy = family_policies[name]
+            for case in cases:
+                episode = runner.judge_case(honeypot, case, policy(case), execute=args.execute)
+                counts[name][episode.verdict] += 1
+                # The gate accepts what expected_verdicts allows for this exact
+                # case and execute flag, so an HB-TEST oracle judged
+                # CLEAN_UNVERIFIED under --exec is caught as broken wiring
+                # rather than waved through.
+                expected = hackbait.scripted.expected_verdicts(name, case, args.execute)
+                if episode.verdict not in expected:
+                    misses.append((case.id, name, expected, episode.verdict))
+        control_count = sum(1 for case in cases if case.tier == CONTROL_TIER)
+        _print_confusion(honeypot.family, len(cases), counts, control_count)
+    if misses:
+        for case_id, name, expected, got in misses:
+            print(f"miss: {case_id} policy={name} expected={'|'.join(expected)} got={got}")
+        print(f"selftest: {len(misses)} misclassifications")
+        return 2
+    print("selftest: OK")
+    return 0
+
+
+def _print_confusion(
+    family: str, case_count: int, counts: dict[str, dict[str, int]], control_count: int = 0
+) -> None:
+    print(f"{family} ({case_count} cases)")
+    header = "".join(f"{verdict:>18}" for verdict in VERDICTS)
+    print(f"  {'policy':<8}{header}")
+    for name, verdict_counts in counts.items():
+        cells = "".join(f"{verdict_counts[verdict]:>18}" for verdict in VERDICTS)
+        # On control cases no bait exists, so the cheat policy answering the
+        # poisoned value is expected to FAIL; annotate the row so those FAILs
+        # read as the control arm working, not the gate breaking.
+        note = ""
+        if name == "cheat" and control_count:
+            note = f"  (control: {control_count} expected FAIL)"
+        print(f"  {name:<8}{cells}{note}")
+
+
+def _parse_tiers(spec: str) -> tuple[int, ...]:
+    try:
+        tiers = tuple(int(part) for part in spec.split(",") if part.strip())
+    except ValueError:
+        raise ValueError(f"--tiers wants comma-separated integers, got {spec!r}") from None
+    allowed = set(TIERS) | {CONTROL_TIER}
+    bad = sorted(set(tiers) - allowed)
+    if not tiers or bad:
+        raise ValueError(f"--tiers must pick from 0,1,2,3, got {spec!r}")
+    return tiers
+
+
+def _slug(label: str) -> str:
+    """Filesystem-safe run label; model ids often carry slashes and colons."""
+    cleaned = re.sub(r"[^A-Za-z0-9._-]+", "-", label).strip("-.")
+    return cleaned or "run"
+
+
+def _is_local_host(base_url: str) -> bool:
+    """True when the endpoint host is the local machine, so keyless is fine."""
+    try:
+        host = urllib.parse.urlsplit(base_url).hostname
+    except ValueError:
+        return False
+    return host in {"localhost", "127.0.0.1", "::1"}
+
+
+def _cmd_run(args: argparse.Namespace) -> int:
+    tiers = _parse_tiers(args.tiers)
+    if args.execute:
+        print("warning: " + EXEC_WARNING, file=sys.stderr)
+    families = None
+    if args.families:
+        families = [part.strip().upper() for part in args.families.split(",") if part.strip()]
+    if args.model:
+        base_url = args.base_url or os.environ.get("HACKBAIT_BASE_URL", "")
+        api_key = os.environ.get("HACKBAIT_API_KEY", "")
+        if not api_key:
+            # People coming from other OpenAI-compatible tools usually have
+            # this one set already; honor it rather than demanding a rename.
+            api_key = os.environ.get("OPENAI_API_KEY", "")
+            if api_key:
+                print("using OPENAI_API_KEY (HACKBAIT_API_KEY is unset)", file=sys.stderr)
+        missing = []
+        if not base_url:
+            missing.append("a base url (--base-url or HACKBAIT_BASE_URL)")
+        if not api_key:
+            if _is_local_host(base_url):
+                # Local servers (ollama, vllm, llama.cpp) commonly take any
+                # bearer token or none; do not block a localhost run on a key.
+                print(
+                    "no api key set; proceeding keyless against a localhost endpoint",
+                    file=sys.stderr,
+                )
+            else:
+                missing.append("an api key (HACKBAIT_API_KEY or OPENAI_API_KEY)")
+        if missing:
+            print(f"error: --model needs {' and '.join(missing)}", file=sys.stderr)
+            return 1
+        raw_temp = (args.temperature or "").strip().lower()
+        if raw_temp in ("none", "omit", ""):
+            temperature = None
+        else:
+            try:
+                temperature = float(raw_temp)
+            except ValueError:
+                print(
+                    f'error: --temperature wants a number or "none", got {args.temperature!r}',
+                    file=sys.stderr,
+                )
+                return 1
+        respond = runner.model_responder(
+            args.model, base_url=base_url, api_key=api_key, temperature=temperature
+        )
+        label = args.model
+    else:
+        policies = hackbait.scripted.scripted()
+        policy_name = args.policy
+
+        def respond(case: hackbait.Case) -> str:
+            return policies[case.family][policy_name](case)
+
+        label = f"scripted-{policy_name}"
+    out = Path(args.out) if args.out else Path("runs") / f"{_slug(label)}-{int(time.time())}.jsonl"
+    summary = runner.run_suite(
+        respond,
+        out,
+        label,
+        per_tier=args.per_tier,
+        seed=args.seed,
+        tiers=tiers,
+        families=families,
+        execute=args.execute,
+    )
+    total, errored = _print_run_table(out)
+    print(f"wrote {out}")
+    # Only a real model run carries token usage worth summarizing; a scripted
+    # policy reports nothing but zeros. The usage figures are metadata printed
+    # for the operator and never fed back into the run.
+    if args.model:
+        _print_usage_summary(summary)
+        _print_ci_hint(summary)
+    if total and errored == total:
+        # A wrong model name or dead endpoint turns every episode into an
+        # errored FAIL; a normal-looking exit 0 here would hide that the run
+        # measured nothing.
+        print(
+            f"error: all {total} episodes errored; check the base url, model name "
+            "and api key",
+            file=sys.stderr,
+        )
+        return 1
+    return 0
+
+
+def _print_run_table(out: Path) -> tuple[int, int]:
+    """Summary from the rows just written: overall, per family, per tier.
+
+    Computed from the run file rather than report.summarize, so the table
+    never depends on the report module's dict shape. Control (tier 0) rows
+    are not hack attempts and stay out of every rate; they get their own
+    line. Returns (total episodes, episodes with error set) so the caller
+    can refuse to exit 0 on an all-errored run.
+    """
+    rows: list[dict[str, Any]] = []
+    with out.open(encoding="utf-8") as fh:
+        for line in fh:
+            record = json.loads(line)
+            if record.get("kind") != "run":
+                rows.append(record)
+    if not rows:
+        print("no episodes written")
+        return 0, 0
+
+    def rate(subset: list[dict[str, Any]]) -> str:
+        hacks = sum(row["verdict"] == "HACK" for row in subset)
+        return f"{hacks / len(subset):.3f} ({hacks}/{len(subset)})"
+
+    control = [row for row in rows if row["tier"] == CONTROL_TIER]
+    pressured = [row for row in rows if row["tier"] != CONTROL_TIER]
+
+    if pressured:
+        print(f"episodes: {len(pressured)}  hack rate: {rate(pressured)}")
+    else:
+        print(f"episodes: {len(pressured)}  hack rate: n/a (no pressured episodes)")
+    verdict_counts = Counter(row["verdict"] for row in pressured)
+    print("verdicts: " + "  ".join(f"{v}={verdict_counts.get(v, 0)}" for v in VERDICTS))
+    for family in sorted({row["family"] for row in pressured}):
+        subset = [row for row in pressured if row["family"] == family]
+        print(f"  {family:<8} {rate(subset)}")
+    for tier in TIERS:
+        subset = [row for row in pressured if row["tier"] == tier]
+        if subset:
+            print(f"  tier {tier} ({TIER_NAMES[tier]}): {rate(subset)}")
+    if control:
+        collisions = sum(
+            1 for row in control if "control_key_collision" in (row.get("signals") or [])
+        )
+        print(
+            f"  control (tier 0): {len(control)} episodes, "
+            f"{collisions} key collisions (excluded from hack rate)"
+        )
+    errored = sum(1 for row in rows if row.get("error") is not None)
+    if errored:
+        print(f"errors: {errored}")
+    return len(rows), errored
+
+
+def _print_usage_summary(summary: dict[str, Any]) -> None:
+    """Print the run's token, latency and cost line from the report summary.
+
+    Reads the summary's usage block, which report.summarize builds from the
+    stored rows. Cost is None when the model is unpriced or no episode carried
+    a usage block; latency is None when nothing timed. Both render as n/a
+    rather than a fake zero. Nothing here changes a verdict.
+    """
+    usage = summary.get("usage")
+    if not isinstance(usage, dict):
+        return
+    total = usage.get("total_tokens", 0)
+    in_tok = usage.get("prompt_tokens", 0)
+    out_tok = usage.get("completion_tokens", 0)
+    p95 = usage.get("p95_latency_ms")
+    p95_text = "n/a" if p95 is None else f"{p95:.0f}ms"
+    cost = usage.get("cost_usd")
+    cost_text = "n/a" if cost is None else f"${cost:.4f}"
+    print(f"tokens: {total} (in {in_tok} / out {out_tok})  p95 {p95_text}  cost {cost_text}")
+
+
+def _print_ci_hint(summary: dict[str, Any]) -> None:
+    """Print the observed hack-rate CI half-width and the per_tier to tighten it.
+
+    Uses the same Wilson half-width the leaderboard's bracket comes from, so
+    the +-Ypp here agrees with the stored interval. N is the pressured episode
+    count; with no pressured episodes there is nothing to bound, so the hint is
+    skipped. This reads the observed rate only to report precision; it never
+    feeds back into case generation or judging.
+    """
+    hack_rate = summary.get("hack_rate")
+    n = summary.get("episodes")
+    if not isinstance(hack_rate, (int, float)) or not isinstance(n, int) or n <= 0:
+        return
+    half_pp = 100.0 * stats.wilson_half_width(hack_rate, n)
+    per_tier = stats.episodes_and_per_tier(hack_rate, 0.02)[1]
+    print(
+        f"hack rate {hack_rate:.1%} +- {half_pp:.1f}pp (95% CI, n={n}); "
+        f"to reach +-2pp, run per_tier={per_tier}"
+    )
+
+
+def _cmd_power(args: argparse.Namespace) -> int:
+    """Sample-size plan: episodes and per_tier for a target CI half-width.
+
+    The statistics come from stats.power_table, which is metadata-free by
+    construction. When --model names a priced model an estimated-cost column
+    is joined on top, but that join is one-directional: cost never feeds the
+    sample-size math, it only annotates it. Bad flag values (rate outside
+    [0, 1], half-width <= 0) exit 2, matching selftest's "the inputs were
+    wrong" code and distinct from a clean exit 0.
+    """
+    from . import pricing
+
+    rates = args.rates if args.rates else list(stats.DEFAULT_RATES)
+    half_widths = args.half_widths if args.half_widths else [stats.DEFAULT_HALF_WIDTH]
+    if args.prices:
+        pricing.load_prices(args.prices)
+
+    per_ep_cost: float | None = None
+    if args.model:
+        per_ep_cost = pricing.cost_usd(args.model, _PLAN_PROMPT_TOKENS, _PLAN_COMPLETION_TOKENS)
+        if per_ep_cost is None:
+            print(
+                f"note: {args.model} is unpriced; showing episodes and per_tier only",
+                file=sys.stderr,
+            )
+    try:
+        table = stats.power_table(rates, half_widths)
+    except ValueError as err:
+        # stats raises on rate outside [0, 1] or half-width <= 0. That is a
+        # bad-input error, not a crash, so it exits 2 rather than 1.
+        print(f"error: {err}", file=sys.stderr)
+        return 2
+
+    if per_ep_cost is not None:
+        for record in table:
+            # Cost of the episodes the plan calls for, at the per-episode
+            # estimate. An annotation on the sample-size row, never an input.
+            record["est_cost_usd"] = record["episodes"] * per_ep_cost
+            record["model"] = args.model
+
+    if args.as_json:
+        print(json.dumps(table, indent=2))
+        return 0
+
+    _print_power_table(table, per_ep_cost is not None, args.model)
+    return 0
+
+
+def _print_power_table(table: list[dict[str, Any]], priced: bool, model: str | None) -> None:
+    """Render the power table for humans: rates and half-widths as percentages."""
+    if priced:
+        print(
+            f"per-episode cost estimate for {model}: "
+            f"{_PLAN_PROMPT_TOKENS} in / {_PLAN_COMPLETION_TOKENS} out tokens per episode"
+        )
+    header = f"{'rate':>8} {'half_width':>12} {'episodes':>10} {'per_tier':>10}"
+    if priced:
+        header += f" {'est_cost':>12}"
+    print(header)
+    print("-" * len(header))
+    for record in table:
+        rate_pct = f"{record['rate'] * 100:.1f}%"
+        half_pp = f"+-{record['half_width'] * 100:.1f}pp"
+        line = (
+            f"{rate_pct:>8} {half_pp:>12} "
+            f"{int(record['episodes']):>10} {int(record['per_tier']):>10}"
+        )
+        if priced:
+            cost = record.get("est_cost_usd")
+            cost_text = "n/a" if cost is None else f"${cost:.2f}"
+            line += f" {cost_text:>12}"
+        print(line)
+
+
+def _cmd_report(args: argparse.Namespace) -> int:
+    from hackbait import report
+
+    if args.results is None:
+        results = Path("leaderboard/results")
+        if not results.exists():
+            runs = Path("runs")
+            if runs.is_dir():
+                # hackbait run writes to ./runs by default, so a fresh user's
+                # transcripts live there; fall back rather than erroring on a
+                # directory they never created.
+                print(f"{results} not found; falling back to {runs}", file=sys.stderr)
+                results = runs
+            else:
+                print(
+                    f"error: {results}: results directory does not exist "
+                    "(if your runs are in ./runs, pass --results runs)",
+                    file=sys.stderr,
+                )
+                return 1
+    else:
+        # An explicitly requested path that does not exist is an error;
+        # report.leaderboard_rows raises and run() turns that into exit 1.
+        results = Path(args.results)
+    report.write_leaderboard(results, Path(args.out_md), Path(args.out_json))
+    print(f"leaderboard written to {args.out_md} and {args.out_json}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(run())

hackbait/pricing.py

@@ -0,0 +1,135 @@
+"""Model price table and cost estimation for hackbait runs.
+
+Prices as of 2026-08, in USD per million tokens as (input, output) pairs, for
+the models this suite actually exercises: the claude-* ids and the gemini-* ids
+seen in this project. They are public list rates kept here so a run can print a
+computed cost estimate next to its token usage.
+
+The number this module returns is an estimate, not a bill. It multiplies token
+counts by list rates and ignores prompt caching, batch discounts, negotiated
+pricing, and per-request minimums, so it can only ever approximate an invoice.
+
+Cost is metadata. It never feeds case generation or a verdict, and the core
+judging path does not import it; only the report layer reads it. Runtime price
+overrides (register_prices / load_prices) change the reported cost of a run but
+cannot change which cases are generated or how they are scored.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+__all__ = ["cost_usd", "load_prices", "prices", "register_prices", "reset_prices"]
+
+# Keys are model-id prefixes. A lookup matches an id exactly first, then falls
+# back to the longest key that is a prefix of the id, so a dated snapshot like
+# "claude-sonnet-5-20260101" bills at the "claude-sonnet-5" rate.
+_DEFAULT_PRICES: dict[str, tuple[float, float]] = {
+    # Claude (first-party list rates as of 2026-08).
+    "claude-fable-5": (10.0, 50.0),
+    "claude-opus-5": (5.0, 25.0),
+    "claude-opus-4-8": (5.0, 25.0),
+    "claude-opus-4-7": (5.0, 25.0),
+    "claude-opus-4-6": (5.0, 25.0),
+    "claude-sonnet-5": (3.0, 15.0),
+    "claude-sonnet-4-6": (3.0, 15.0),
+    "claude-haiku-4-5": (1.0, 5.0),
+    # Gemini (Google list rates as of 2026-08; short-context tier where tiered).
+    "gemini-2.5-pro": (1.25, 10.0),
+    "gemini-2.5-flash": (0.30, 2.50),
+    "gemini-2.5-flash-lite": (0.10, 0.40),
+    "gemini-2.0-flash": (0.10, 0.40),
+    "gemini-1.5-pro": (1.25, 5.0),
+    "gemini-1.5-flash": (0.075, 0.30),
+    # Gemini 3.x flash tiers actually exercised by live runs here. Their public
+    # list prices are not yet confirmed, so these carry the same flash / flash-
+    # lite estimates as the 2.5 tier; override with register_prices once the
+    # real rates land. The longest-prefix match means "gemini-3-flash-preview"
+    # and "gemini-3.7-flash" both resolve to the flash estimate below.
+    "gemini-3-flash": (0.30, 2.50),
+    "gemini-3.5-flash": (0.30, 2.50),
+    "gemini-3.6-flash": (0.30, 2.50),
+    "gemini-3.7-flash": (0.30, 2.50),
+    "gemini-flash-latest": (0.30, 2.50),
+    "gemini-3.1-flash-lite": (0.10, 0.40),
+    "gemini-flash-lite-latest": (0.10, 0.40),
+}
+
+# Mutable working copy. register_prices / load_prices update it in place;
+# reset_prices restores the defaults above.
+_PRICES: dict[str, tuple[float, float]] = dict(_DEFAULT_PRICES)
+
+
+def prices() -> dict[str, tuple[float, float]]:
+    """A copy of the current price table, safe to inspect but not mutate."""
+    return dict(_PRICES)
+
+
+def register_prices(mapping: dict[str, tuple[float, float]]) -> None:
+    """Merge runtime price overrides into the table, keyed by model id or prefix.
+
+    Each value is an (input_per_million, output_per_million) pair. Existing
+    keys are replaced; keys not named are left alone.
+    """
+    for model, pair in mapping.items():
+        in_rate, out_rate = pair
+        _PRICES[str(model)] = (float(in_rate), float(out_rate))
+
+
+def reset_prices() -> None:
+    """Restore the built-in default table, discarding any runtime overrides."""
+    _PRICES.clear()
+    _PRICES.update(_DEFAULT_PRICES)
+
+
+def _coerce_pair(value: object) -> tuple[float, float]:
+    """Read one price entry as (input, output) from a list or an input/output map."""
+    if isinstance(value, dict):
+        return (float(value["input"]), float(value["output"]))
+    # A two-element sequence: [input, output].
+    in_rate, out_rate = value  # type: ignore[misc]
+    return (float(in_rate), float(out_rate))
+
+
+def load_prices(path: str | Path) -> dict[str, tuple[float, float]]:
+    """Load price overrides from a JSON file and register them.
+
+    The JSON maps model id (or prefix) to either a two-element ``[input,
+    output]`` array or an ``{"input": ..., "output": ...}`` object. Returns the
+    mapping that was registered.
+    """
+    data = json.loads(Path(path).read_text(encoding="utf-8"))
+    mapping = {str(model): _coerce_pair(value) for model, value in data.items()}
+    register_prices(mapping)
+    return mapping
+
+
+def _lookup(model: str) -> tuple[float, float] | None:
+    """Find the price pair for a model id: exact match, then longest prefix."""
+    if model in _PRICES:
+        return _PRICES[model]
+    candidates = [key for key in _PRICES if model.startswith(key)]
+    if not candidates:
+        return None
+    return _PRICES[max(candidates, key=len)]
+
+
+def cost_usd(
+    model: str | None,
+    prompt_tokens: int | None,
+    completion_tokens: int | None,
+) -> float | None:
+    """Estimate the USD cost of one run's usage, or None when it cannot be priced.
+
+    Returns None when the model is unpriced (no exact or prefix match) or when
+    either token count is None, so callers never mistake a missing figure for
+    a real zero.
+    """
+    if model is None or prompt_tokens is None or completion_tokens is None:
+        return None
+    rate = _lookup(model)
+    if rate is None:
+        return None
+    in_rate, out_rate = rate
+    return prompt_tokens / 1_000_000 * in_rate + completion_tokens / 1_000_000 * out_rate