prefixwise 0.3.0__py3-none-any.whl

prefixwise/__init__.py

@@ -0,0 +1,10 @@
+"""Prefixwise: model-agnostic ledger of avoidable agent token spend."""
+
+__version__ = "0.3.0"
+
+from .classifier import MissCause, classify
+from .diagnostics import AgreementScorer
+from .fingerprint import Fingerprinter, fingerprint_blocks
+from .ledger import Ledger
+
+__all__ = ["__version__", "MissCause", "classify", "AgreementScorer", "Fingerprinter", "fingerprint_blocks", "Ledger"]

prefixwise/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

prefixwise/classifier.py

@@ -0,0 +1,283 @@
+"""Miss-cause classifier (v2 taxonomy, 19 causes).
+
+Exactly one cause per request: the first divergence in prefix order.
+``UNKNOWN`` when evidence is absent, never a guess.
+
+Legitimacy is a separate column from cause: a legitimate change still
+costs tokens, but it is not waste. A policy can later mark a catalog
+change avoidable (masking instead of removing) without renaming the cause.
+
+Provider order (verified, not assumed):
+- Anthropic: tools, system, messages.
+- OpenAI: tools are injected before developer instructions, so
+  tools, developer/system, messages. (OpenAI Prompt Caching 201.)
+
+Rules run in v2 order; the first that fires wins, the rest are recorded
+as secondary. Provider native reasons (Anthropic 6, OpenAI 9) map onto
+this taxonomy in diagnostics.py; they are a partial agreement signal,
+not ground truth: providers report the earliest divergence only, in a
+coarse taxonomy, and neither names TTL expiry, routing, or eviction.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+
+from .fingerprint import BlockFingerprint
+
+
+class MissCause(str, Enum):
+    FIRST_WRITE = "first_write"
+    MODEL_SWITCH = "model_switch"
+    VOLATILE_SYSTEM = "volatile_system"
+    SYSTEM_EDIT = "system_edit"
+    TOOL_RESERIALIZE = "tool_reserialize"
+    TOOL_CATALOG_CHANGE = "tool_catalog_change"
+    COMPACTION_REWRITE = "compaction_rewrite"
+    HISTORY_EDIT = "history_edit"
+    TOOL_RESULT_MUTATION = "tool_result_mutation"
+    FORK_BOUNDARY = "fork_boundary"
+    PARAM_RENDERED = "param_rendered"
+    BELOW_MIN_PREFIX = "below_min_prefix"
+    BREAKPOINT_MISPLACED = "breakpoint_misplaced"
+    TTL_EXPIRED = "ttl_expired"
+    EVICTED = "evicted"
+    ROUTING_MISS = "routing_miss"
+    RETRY_REPLAY = "retry_replay"
+    NONE = "none"
+    UNKNOWN = "unknown"
+
+
+# Provider minimum cacheable prefix, tokens. Anthropic is model-dependent:
+# 512-4,096 (512 for Claude Fable/Mythos/Opus/Sonnet/Haiku 5.x, 2,048 for
+# Mythos Preview / Opus 4.7, 4,096 for Opus 4.6/4.5 and Haiku 4.5,
+# 1,024 for Opus 4.8 / Sonnet 5 / Sonnet 4.6). Use the model-specific
+# value when known; the dict below is the per-model table, not a range.
+ANTHROPIC_MIN_PREFIX = {
+    "512": 512, "2048": 2048, "4096": 4096, "1024": 1024,
+}
+OPENAI_MIN_PREFIX = 1024
+# No provider keeps a cache entry for less than ~5 minutes (Anthropic default
+# 5 min; OpenAI in-memory 5-10 min). A cold cache within this gap of the
+# last turn is not explained by expiry.
+MIN_PROVIDER_TTL_SECONDS = 300
+GEMINI_MIN_PREFIX = 4096  # Gemini 3.x; 2,048 on 2.5. ai.google.dev, Nov 2026.
+
+
+@dataclass
+class RequestSnapshot:
+    model: str
+    provider: str = "unknown"
+    blocks: list[BlockFingerprint] = field(default_factory=list)
+    # Prompt-affecting params that change the rendered request without
+    # changing any block: tool_choice, thinking/reasoning, output_format,
+    # context_management, beta headers, temperature is NOT one of these.
+    params: dict = field(default_factory=dict)
+    prompt_tokens: int = 0
+    cached_tokens: int = 0
+    # Seconds since the previous turn in this session; None = unknown.
+    gap_seconds: float | None = None
+    ttl_seconds: float | None = None
+    compaction_event: bool = False
+    fork_parent_session_id: str | None = None
+    session_id: str | None = None
+    # vLLM KV events for this session between the two turns.
+    evicted_block_hashes: list[str] = field(default_factory=list)
+    # Anthropic cache_control present anywhere in the request.
+    has_breakpoint: bool = False
+    breakpoint_after_volatile: bool = False
+    min_prefix_tokens: int | None = None
+
+
+@dataclass
+class Classification:
+    cause: MissCause
+    legit: bool | None  # True = legitimate, False = waste, None = n/a
+    evidence: str
+    secondary: list[MissCause] = field(default_factory=list)
+    native_reason: str | None = None
+    classifier_version: str = "2.0"
+
+
+def _blocks_by_role(blocks: list[BlockFingerprint]) -> dict[str, list[BlockFingerprint]]:
+    out: dict[str, list[BlockFingerprint]] = {}
+    for b in blocks:
+        out.setdefault(b.role, []).append(b)
+    return out
+
+
+def _tool_multiset(blocks: list[BlockFingerprint]) -> list[str]:
+    return sorted(b.canonical for b in blocks if b.role == "tools")
+
+
+def _same(a: BlockFingerprint, b: BlockFingerprint) -> bool:
+    return a.raw == b.raw and a.canonical == b.canonical and a.masked == b.masked
+
+
+# Roles that grow by appending turn over turn. For these, the previous
+# turn's blocks must be an unchanged prefix of the current turn's; new
+# blocks after that prefix are ordinary conversation growth, not a
+# divergence. System and tool blocks must match exactly.
+_APPEND_ROLES = ("messages", "tool_results", "user")
+
+
+def _role_unchanged(role: str, p: list[BlockFingerprint], c: list[BlockFingerprint]) -> bool:
+    if role in _APPEND_ROLES:
+        return len(p) <= len(c) and all(_same(a, b) for a, b in zip(p, c))
+    return len(p) == len(c) and all(_same(a, b) for a, b in zip(p, c))
+
+
+def classify(prev: RequestSnapshot | None, curr: RequestSnapshot,
+             *, native_reason: str | None = None) -> Classification:
+    """Classify one turn against the previous turn in the same session."""
+    if prev is None:
+        if curr.fork_parent_session_id:
+            return Classification(MissCause.FORK_BOUNDARY, True,
+                                  f"first turn of a session forked from {curr.fork_parent_session_id}",
+                                  native_reason=native_reason)
+        return Classification(MissCause.FIRST_WRITE, True, "no prior request in session",
+                              native_reason=native_reason)
+    if prev.model != curr.model:
+        return Classification(MissCause.MODEL_SWITCH, True,
+                              f"model {prev.model} -> {curr.model}", native_reason=native_reason)
+
+    prev_by_role = _blocks_by_role(prev.blocks)
+    curr_by_role = _blocks_by_role(curr.blocks)
+    secondary: list[MissCause] = []
+
+    # First divergence in prefix order: system, tools, messages, tool_results, user.
+    for role in ("system", "system_dynamic", "tools", "messages", "tool_results", "user"):
+        p, c = prev_by_role.get(role, []), curr_by_role.get(role, [])
+        if _role_unchanged(role, p, c):
+            continue
+        if role in ("system", "system_dynamic"):
+            if [b.masked for b in p] == [b.masked for b in c]:
+                return Classification(MissCause.VOLATILE_SYSTEM, False,
+                                      "system raw hash changed, masked hash equal (dates/ids/numbers only)",
+                                      secondary, native_reason)
+            return Classification(MissCause.SYSTEM_EDIT, None,
+                                  "system masked hash changed", secondary, native_reason)
+        if role == "tools":
+            if _tool_multiset(prev.blocks) == _tool_multiset(curr.blocks):
+                return Classification(MissCause.TOOL_RESERIALIZE, False,
+                                      "tool multiset of canonical hashes equal; sequence or raw bytes differ",
+                                      secondary, native_reason)
+            return Classification(MissCause.TOOL_CATALOG_CHANGE, True,
+                                  "tool multiset differs", secondary, native_reason)
+        if role == "messages":
+            cause = MissCause.COMPACTION_REWRITE if curr.compaction_event else MissCause.HISTORY_EDIT
+            legit = True if curr.compaction_event else False
+            ev = "previous message blocks rewritten (not a prefix of this turn) with a compaction event" \
+                if curr.compaction_event else \
+                "previous message blocks rewritten (not a prefix of this turn) without a compaction event"
+            return Classification(cause, legit, ev, secondary, native_reason)
+        if role == "tool_results":
+            if curr.compaction_event:
+                # Context editing that clears old tool results is a compaction.
+                return Classification(MissCause.COMPACTION_REWRITE, True,
+                                      "earlier tool results cleared or rewritten with a compaction event",
+                                      secondary, native_reason)
+            return Classification(MissCause.TOOL_RESULT_MUTATION, False,
+                                  "an earlier tool result changed or was removed without a compaction event",
+                                  secondary, native_reason)
+        # user role divergence with no other cause: fall through to param/TTL checks.
+        secondary.append(MissCause.HISTORY_EDIT)
+
+    # Blocks equal (or only the user turn changed): check params, prefix, TTL, eviction.
+    if prev.params != curr.params:
+        changed = sorted(set(prev.params) ^ set(curr.params) |
+                         {k for k in prev.params.keys() & curr.params.keys() if prev.params[k] != curr.params[k]})
+        return Classification(MissCause.PARAM_RENDERED, None,
+                              f"blocks equal; prompt-affecting params changed: {changed}",
+                              secondary, native_reason)
+
+    min_prefix = curr.min_prefix_tokens
+    if min_prefix is None:
+        min_prefix = {"openai": OPENAI_MIN_PREFIX, "gemini": GEMINI_MIN_PREFIX}.get(curr.provider, None)
+    # 0 prompt tokens means usage was absent, not a short prompt: fall
+    # through to UNKNOWN rather than claim BELOW_MIN_PREFIX.
+    if min_prefix is not None and 0 < curr.prompt_tokens < min_prefix:
+        return Classification(MissCause.BELOW_MIN_PREFIX, None,
+                              f"cacheable prefix {curr.prompt_tokens} below provider minimum {min_prefix}",
+                              secondary, native_reason)
+
+    if curr.provider == "anthropic" and not curr.has_breakpoint:
+        return Classification(MissCause.BREAKPOINT_MISPLACED, False,
+                              "Anthropic: no cache_control anywhere, or breakpoint after a volatile block",
+                              secondary, native_reason)
+    if curr.breakpoint_after_volatile:
+        return Classification(MissCause.BREAKPOINT_MISPLACED, False,
+                              "breakpoint sits after a volatile block", secondary, native_reason)
+
+    # Every rule below reads usage. Usage absent (0 prompt tokens, seen live
+    # on OpenAI 2026-11-06) is no evidence of a hit, a retry or a routing
+    # miss: say UNKNOWN rather than guess from a zero.
+    if curr.prompt_tokens <= 0:
+        return Classification(MissCause.UNKNOWN, None,
+                              "blocks unchanged but the provider returned no usage; cannot tell hit from miss",
+                              secondary, native_reason)
+
+    # Append-only turn: compare cache_read to the reusable prior prefix,
+    # not to this turn's prompt, which includes the newly appended tail.
+    # A real hit wins over every timing rule below: if the cache served
+    # the prefix, it did not expire and was not evicted.
+    reusable = min(prev.prompt_tokens, curr.prompt_tokens) if prev.prompt_tokens else curr.prompt_tokens
+    if curr.prompt_tokens > 0 and curr.cached_tokens >= reusable * 0.5:
+        return Classification(MissCause.NONE, None,
+                              "append-only turn; cache_read at least half of the prior prefix",
+                              secondary, native_reason)
+
+    # From here the prefix was reusable but cache_read was low.
+    # Engine eviction events are direct evidence; they outrank inference.
+    if curr.evicted_block_hashes:
+        return Classification(MissCause.EVICTED, None,
+                              "BlockRemoved events for this session's blocks between the two turns",
+                              secondary, native_reason)
+
+    # Identical replay within a short window is a retry, not a cache miss.
+    if prev.blocks and curr.blocks and \
+       [b.raw for b in prev.blocks] == [b.raw for b in curr.blocks] and \
+       curr.gap_seconds is not None and curr.gap_seconds < 60 and curr.cached_tokens == 0:
+        return Classification(MissCause.RETRY_REPLAY, False,
+                              "identical request within the retry window", secondary, native_reason)
+
+    gap, ttl = curr.gap_seconds, curr.ttl_seconds
+    if ttl is not None and gap is not None and gap > ttl:
+        return Classification(MissCause.TTL_EXPIRED, True,
+                              f"gap {gap:.0f}s since last turn exceeds the cache TTL {ttl:.0f}s",
+                              secondary, native_reason)
+
+    if curr.cached_tokens == 0 and curr.prompt_tokens > 0 and gap is not None and \
+       (gap <= (ttl if ttl is not None else MIN_PROVIDER_TTL_SECONDS)):
+        window = f"TTL {ttl:.0f}s" if ttl is not None else f"shortest provider TTL {MIN_PROVIDER_TTL_SECONDS}s"
+        return Classification(MissCause.ROUTING_MISS, None,
+                              f"blocks and params equal, gap {gap:.0f}s within {window}, "
+                              "no eviction evidence, nothing read from cache",
+                              secondary, native_reason)
+    if curr.prompt_tokens > 0 and gap is not None and ttl is None:
+        return Classification(MissCause.UNKNOWN, None,
+                              f"prefix reusable but cache_read low after a {gap:.0f}s gap with unknown TTL:"
+                              " expiry or routing, not distinguishable",
+                              secondary, native_reason)
+    return Classification(MissCause.UNKNOWN, None,
+                          "prefix reusable but cache_read low; no timing or usage evidence to name a cause",
+                          secondary, native_reason)
+
+
+def classify_first_divergence(changed_role: str | None, *, model_changed: bool = False,
+                              compaction_event: bool = False) -> MissCause:
+    """Backwards-compatible helper from v1 (13-cause API)."""
+    if model_changed:
+        return MissCause.MODEL_SWITCH
+    if changed_role is None:
+        return MissCause.FIRST_WRITE
+    if changed_role in ("system", "system_dynamic"):
+        return MissCause.VOLATILE_SYSTEM
+    if changed_role == "tools":
+        return MissCause.TOOL_RESERIALIZE
+    if changed_role == "messages":
+        return MissCause.COMPACTION_REWRITE if compaction_event else MissCause.HISTORY_EDIT
+    if changed_role == "tool_results":
+        return MissCause.TOOL_RESULT_MUTATION
+    return MissCause.UNKNOWN

prefixwise/cli.py

@@ -0,0 +1,338 @@
+"""The `prefixwise` command line.
+
+    prefixwise serve      run the proxy (ledger on disk by default)
+    prefixwise report     where tokens went: totals, causes, sessions, tasks
+    prefixwise task       record a task outcome (success / failure)
+    prefixwise request    show one request's verdict by request id
+    prefixwise explain    offline: why does the cache miss between requests?
+    prefixwise fixes      which fixes would save the most, from your own ledger
+    prefixwise prices     the dated price table used for dollar costs
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+from . import __version__
+
+DEFAULT_LEDGER = "prefixwise.db"
+
+
+def _ledger_path(args) -> str:
+    return args.ledger or os.environ.get("PREFIXWISE_LEDGER_PATH") or DEFAULT_LEDGER
+
+
+def _open_existing_ledger(args):
+    from .ledger import Ledger
+
+    path = _ledger_path(args)
+    if path != ":memory:" and not Path(path).exists():
+        sys.exit(f"prefixwise: no ledger at {path} (run `prefixwise serve` first, or pass --ledger)")
+    return Ledger(path)
+
+
+def _fmt_int(n) -> str:
+    return "-" if n is None else f"{int(n):,}"
+
+
+def _fmt_usd(x) -> str:
+    if x is None:
+        return "-"
+    return f"${x:,.2f}" if abs(x) >= 1 else f"${x:,.4f}"
+
+
+def _fmt_pct(x) -> str:
+    return "-" if x is None else f"{x:.1%}"
+
+
+def _table(rows: list[list[str]], headers: list[str]) -> str:
+    widths = [max(len(str(c)) for c in col) for col in zip(headers, *rows)]
+    def line(cells):
+        return "  ".join(str(c).ljust(w) if i == 0 else str(c).rjust(w)
+                         for i, (c, w) in enumerate(zip(cells, widths)))
+    return "\n".join([line(headers), line(["-" * w for w in widths])] + [line(r) for r in rows])
+
+
+# -- commands ---------------------------------------------------------------------------
+
+def cmd_serve(args) -> int:
+    from .proxy import serve
+
+    ledger = args.ledger or os.environ.get("PREFIXWISE_LEDGER_PATH") or DEFAULT_LEDGER
+    try:
+        serve(host=args.host, port=args.port, ledger_path=ledger,
+              upstream_url=args.upstream, mock=True if args.mock else None,
+              fixes=args.fix or None, allow_unauthenticated=args.allow_unauthenticated,
+              prices=args.prices)
+    except ValueError as exc:  # unknown --fix name
+        sys.exit(f"prefixwise: {exc}")
+    return 0
+
+
+def cmd_fixes(args) -> int:
+    from .fixes import FIX_ADVICE, FIX_STATUS
+
+    led = _open_existing_ledger(args)
+    summary = led.summary()
+    rows = {r["cause"]: r for r in led.rollup("cause")}
+    with led._lock:
+        fixed_requests = dict(led.conn.execute(
+            "SELECT fixes, COUNT(*) FROM entries WHERE fixes IS NOT NULL GROUP BY fixes").fetchall())
+    recs = []
+    for cause, advice in FIX_ADVICE.items():
+        r = rows.get(cause)
+        if not r or not r["avoidable_tokens"]:
+            continue
+        recs.append({"cause": cause, "requests": r["requests"], "predicted_savings_tokens": r["avoidable_tokens"],
+                     "predicted_savings_usd": r["avoidable_cost"],
+                     "unpriced_requests": r["requests"] - r["priced_requests"],
+                     "share_of_prompt_tokens": (r["avoidable_tokens"] / summary["prompt_tokens"])
+                     if summary["prompt_tokens"] else None,
+                     "fix": advice["fix"], "proxy_toggle": advice["toggle"],
+                     "status": (FIX_STATUS.get(advice["toggle"] or "", {}).get("status")
+                                or "recommended (predicted; prove it with experiments/e4)"),
+                     "evidence": FIX_STATUS.get(advice["toggle"] or "", {}).get("evidence")})
+    recs.sort(key=lambda x: -x["predicted_savings_tokens"])
+    if args.json:
+        print(json.dumps({"recommendations": recs, "requests_rewritten_by_fixes": fixed_requests}, indent=2))
+        return 0
+    if not recs:
+        print("No avoidable waste with a known fix in this ledger.")
+    for i, r in enumerate(recs, 1):
+        toggle = f"   proxy can apply it: prefixwise serve --fix {r['proxy_toggle']}" if r["proxy_toggle"] else ""
+        print(f"{i}. {r['cause']}: {_fmt_int(r['predicted_savings_tokens'])} avoidable tokens "
+              f"({_fmt_pct(r['share_of_prompt_tokens'])} of prompt tokens) over {r['requests']} "
+              f"request{'s' if r['requests'] != 1 else ''}")
+        if r["predicted_savings_usd"] is not None:
+            unpriced = f" ({r['unpriced_requests']} requests unpriced)" if r["unpriced_requests"] else ""
+            print(f"   worth: {_fmt_usd(r['predicted_savings_usd'])}{unpriced}")
+        print(f"   fix: {r['fix']}")
+        if toggle:
+            print(toggle)
+        if r["evidence"]:
+            print(f"   {r['status']}: {r['evidence']}")
+    if fixed_requests:
+        print("\nAlready active: " + ", ".join(f"{k} rewrote {v} requests" for k, v in fixed_requests.items()))
+    return 0
+
+
+def cmd_report(args) -> int:
+    led = _open_existing_ledger(args)
+    summary = led.summary()
+    rows = led.rollup(args.by)[: args.limit]
+    if args.json:
+        print(json.dumps({"summary": summary, "by": args.by, "rows": rows}, indent=2))
+        return 0
+    t = summary["tasks"]
+    print(f"Requests            {_fmt_int(summary['requests'])}")
+    print(f"Prompt tokens       {_fmt_int(summary['prompt_tokens'])}"
+          f"   (cache hit rate {_fmt_pct(summary['cache_hit_rate'])})")
+    print(f"Completion tokens   {_fmt_int(summary['completion_tokens'])}")
+    print(f"Avoidable tokens    {_fmt_int(summary['avoidable_tokens'])}"
+          f"   ({_fmt_pct(summary['avoidable_share'])} of prompt tokens)")
+    tpst = summary["tokens_per_successful_task"]
+    print(f"Tasks               {t['successful']} succeeded / {t['resolved']} resolved")
+    print(f"Tokens per successful task  {_fmt_int(tpst) if tpst is not None else '- (no task outcomes recorded)'}")
+    priced, n = summary["priced_requests"], summary["requests"]
+    if priced:
+        coverage = "" if priced == n else f"   ({priced:,} of {n:,} requests priced; see `prefixwise prices`)"
+        print(f"Cost                {_fmt_usd(summary['cost'])}{coverage}")
+        print(f"Avoidable cost      {_fmt_usd(summary['avoidable_cost'])}")
+        cpst = summary["cost_per_successful_task"]
+        print(f"Cost per successful task  {_fmt_usd(cpst) if cpst is not None else '- (needs task outcomes, all requests priced)'}")
+    elif n:
+        print("Cost                - (no request's model is in the price table; see `prefixwise prices`)")
+    if not rows:
+        return 0
+    print()
+    print(_table([[r[args.by] if r[args.by] is not None else "(none)", _fmt_int(r["requests"]),
+                   _fmt_int(r["prompt_tokens"]), _fmt_pct(r["cached_tokens"] / r["prompt_tokens"])
+                   if r["prompt_tokens"] else "-", _fmt_int(r["avoidable_tokens"]),
+                   _fmt_int(r["waste_requests"]), _fmt_int(r["tokens_per_successful_task"]),
+                   _fmt_usd(r["cost"]) if r["priced_requests"] else "-",
+                   _fmt_usd(r["avoidable_cost"]) if r["priced_requests"] else "-"]
+                  for r in rows],
+                 [args.by, "requests", "prompt", "cached", "avoidable", "waste reqs",
+                  "tokens/success", "cost", "avoidable $"]))
+    return 0
+
+
+def cmd_prices(args) -> int:
+    from .pricing import PriceTable
+
+    try:
+        table = PriceTable.load(args.prices)
+    except (OSError, ValueError) as exc:
+        sys.exit(f"prefixwise: {exc}")
+    if args.json:
+        print(json.dumps({"as_of": table.as_of, "sources": table.sources, "models": table.models}, indent=2))
+        return 0
+    print(f"Price table as of {table.as_of} (USD per 1M tokens), from: {' + '.join(table.sources)}")
+    rows = [[name, r.get("provider", "-"), _rate(r.get("input")), _rate(r.get("cache_read")),
+             _rate(r.get("cache_write_5m", r.get("cache_write"))), _rate(r.get("cache_write_1h")),
+             _rate(r.get("output")), "yes" if r.get("long_prompt") else ""]
+            for name, r in sorted(table.models.items())]
+    print(_table(rows, ["model", "provider", "input", "cache read", "write 5m", "write 1h", "output", "tiered"]))
+    print("\nModels not listed are unpriced: their cost shows as '-', never estimated. Add rates with\n"
+          "PREFIXWISE_PRICES=/path/prices.json (same format as the built-in table; see `--json`).")
+    return 0
+
+
+def _rate(v) -> str:
+    return "-" if v is None else (v if isinstance(v, str) else f"{v:g}")
+
+
+def cmd_task(args) -> int:
+    from .ledger import Ledger
+
+    Ledger(_ledger_path(args)).set_task_outcome(args.task_id, args.outcome == "success")
+    print(f"task {args.task_id}: {args.outcome}")
+    return 0
+
+
+def cmd_request(args) -> int:
+    row = _open_existing_ledger(args).get_request(args.request_id)
+    if row is None:
+        print(f"prefixwise: no request {args.request_id} in the ledger", file=sys.stderr)
+        return 1
+    if args.json:
+        print(json.dumps(row, indent=2))
+    else:
+        for k, v in row.items():
+            print(f"{k:20} {v}")
+    return 0
+
+
+def _print_explanation(label: str, e) -> None:
+    legit = {True: "legitimate", False: "WASTE", None: "undetermined"}[e.legit]
+    if e.cause == "none":
+        legit = "ok, prefix reused"
+    print(f"{label}: {e.cause.upper()}  [{legit}]")
+    if e.divergence:
+        d = e.divergence
+        print(f"  first difference: block {d['index']} ({d['role']}): {d['kind']}")
+    print(f"  why: {e.evidence}")
+    if e.prompt_tokens is not None:
+        print(f"  usage: {_fmt_int(e.cached_tokens)} of {_fmt_int(e.prompt_tokens)} prompt tokens cached")
+
+
+def cmd_explain(args) -> int:
+    from .explain import explain_pair, explain_session, load_turns
+
+    provider = None if args.provider == "auto" else args.provider
+    try:
+        if len(args.files) == 2:
+            prev, curr = (load_turns(f) for f in args.files)
+            if len(prev) != 1 or len(curr) != 1:
+                sys.exit("prefixwise: with two files, each must hold exactly one request")
+            results = [explain_pair(prev[0], curr[0], provider)]
+            labels = [f"{args.files[0]} -> {args.files[1]}"]
+        elif len(args.files) == 1:
+            turns = load_turns(args.files[0])
+            results = explain_session(turns, provider)
+            labels = [f"turn {i + 1} ({t.session_id})" for i, t in enumerate(turns)]
+        else:
+            sys.exit("prefixwise: give one session file (JSON / JSONL) or two request files")
+    except (OSError, ValueError) as exc:
+        sys.exit(f"prefixwise: {exc}")
+    waste = sum(1 for r in results if r.legit is False)
+    fail = 2 if (args.fail_on_waste and waste) else 0
+    if args.json:
+        print(json.dumps([r.to_dict() for r in results], indent=2))
+        return fail
+    if results and results[0].offline:
+        print("(offline: no usage given, so this explains what in the request breaks reuse;"
+              " TTL, eviction and routing need real usage)\n")
+    for label, r in zip(labels, results):
+        _print_explanation(label, r)
+    if len(results) > 1:
+        print(f"\n{len(results)} turns, {waste} wasteful")
+    return fail
+
+
+# -- parser -----------------------------------------------------------------------------
+
+def build_parser() -> argparse.ArgumentParser:
+    ap = argparse.ArgumentParser(prog="prefixwise",
+                                 description="Name why prompt caches miss, and price the miss.")
+    ap.add_argument("--version", action="version", version=f"prefixwise {__version__}")
+    sub = ap.add_subparsers(dest="command", required=True)
+
+    def ledger_opt(p):
+        p.add_argument("--ledger", help=f"SQLite ledger file (default: $PREFIXWISE_LEDGER_PATH or ./{DEFAULT_LEDGER})")
+
+    p = sub.add_parser("serve", help="run the proxy")
+    p.add_argument("--host", default=os.environ.get("PREFIXWISE_HOST", "127.0.0.1"))
+    p.add_argument("--port", type=int, default=int(os.environ.get("PORT", "8080")))
+    p.add_argument("--upstream", help="upstream base URL, e.g. https://api.openai.com "
+                                      "(default: $PREFIXWISE_UPSTREAM_URL; none = mock mode). "
+                                      "API key: $PREFIXWISE_API_KEY, or the client's own auth header.")
+    p.add_argument("--mock", action="store_true", help="synthetic responses, no upstream calls")
+    p.add_argument("--prices", metavar="FILE",
+                   help="extra or overriding rates (JSON, same format as `prefixwise prices --json`); "
+                        "default: $PREFIXWISE_PRICES")
+    p.add_argument("--allow-unauthenticated", action="store_true",
+                   help="listen beyond localhost with PREFIXWISE_API_KEY set but no PREFIXWISE_AUTH_TOKEN "
+                        "(anyone who reaches the port can spend the key)")
+    p.add_argument("--fix", action="append", metavar="NAME",
+                   help="apply a fix to every request before forwarding (repeatable). "
+                        "Available: canonical_tools. Default: $PREFIXWISE_FIXES or none")
+    ledger_opt(p)
+    p.set_defaults(func=cmd_serve)
+
+    p = sub.add_parser("report", help="summarise the ledger")
+    p.add_argument("--by", default="cause", choices=["cause", "session_id", "agent_id", "model",
+                                                     "provider", "task_id"])
+    p.add_argument("--limit", type=int, default=20)
+    p.add_argument("--json", action="store_true")
+    ledger_opt(p)
+    p.set_defaults(func=cmd_report)
+
+    p = sub.add_parser("prices", help="the dated price table used for dollar costs")
+    p.add_argument("--prices", metavar="FILE", help="also load this rates file (default: $PREFIXWISE_PRICES)")
+    p.add_argument("--json", action="store_true")
+    p.set_defaults(func=cmd_prices)
+
+    p = sub.add_parser("fixes", help="fixes ranked by the tokens they would save, from your ledger")
+    p.add_argument("--json", action="store_true")
+    ledger_opt(p)
+    p.set_defaults(func=cmd_fixes)
+
+    p = sub.add_parser("task", help="record a task outcome")
+    p.add_argument("task_id")
+    g = p.add_mutually_exclusive_group(required=True)
+    g.add_argument("--success", dest="outcome", action="store_const", const="success")
+    g.add_argument("--failure", dest="outcome", action="store_const", const="failure")
+    ledger_opt(p)
+    p.set_defaults(func=cmd_task)
+
+    p = sub.add_parser("request", help="show one request's ledger entry")
+    p.add_argument("request_id", help="the X-Prefixwise-Request-Id response header")
+    p.add_argument("--json", action="store_true")
+    ledger_opt(p)
+    p.set_defaults(func=cmd_request)
+
+    p = sub.add_parser("explain", help="offline: why does the cache miss between requests?",
+                       description="Explain cache misses offline. Give two request files (JSON), "
+                                   "or one session file: a JSON array or JSONL of request bodies, "
+                                   'or of {"request": body, "usage": {...}} records.')
+    p.add_argument("files", nargs="+")
+    p.add_argument("--provider", default="auto", choices=["auto", "openai", "anthropic", "vllm"])
+    p.add_argument("--json", action="store_true")
+    p.add_argument("--fail-on-waste", action="store_true",
+                   help="exit 2 if any turn is classified as waste (for CI gates on prompt changes)")
+    p.set_defaults(func=cmd_explain)
+    return ap
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())