agent-cost-attribution 0.1.0__py3-none-any.whl

agent_cost_attribution/__init__.py

@@ -0,0 +1,12 @@
+"""agent-cost-attribution — per-stage token attribution for multi-agent workflow runs."""
+from agent_cost_attribution.ledger import (
+    AgentRecord, agents, decompose, load_run, summary, total_tokens, verify_invariant,
+)
+from agent_cost_attribution.health import detect_degradation, is_healthy
+from agent_cost_attribution.pricing import estimate_cost, cost_by_stage, total_cost, blended_rate
+
+__all__ = [
+    "AgentRecord", "agents", "decompose", "load_run", "summary", "total_tokens",
+    "verify_invariant", "detect_degradation", "is_healthy",
+    "estimate_cost", "cost_by_stage", "total_cost", "blended_rate",
+]

agent_cost_attribution/__main__.py

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

agent_cost_attribution/cli.py

@@ -0,0 +1,59 @@
+"""CLI: python -m agent_cost_attribution <run.json | run-dir> ...
+
+Prints a per-stage token waterfall + a silent-degradation health report for each run. Workload-
+agnostic: any wf_*.json (or a directory of them) works — this is the reusable surface.
+"""
+import sys
+from pathlib import Path
+
+from agent_cost_attribution.ledger import load_run, summary
+from agent_cost_attribution.health import detect_degradation
+from agent_cost_attribution.pricing import cost_by_stage, DEFAULT_INPUT_SHARE
+
+
+def _iter_paths(args):
+    for a in args:
+        p = Path(a)
+        if p.is_dir():
+            yield from sorted(p.glob("wf_*.json"))
+        else:
+            yield p
+
+
+def render(run, *, input_share=DEFAULT_INPUT_SHARE):
+    s = summary(run)
+    costs = cost_by_stage(run, input_share=input_share)
+    total_usd = sum(costs.values())
+    head = (f"{s['workflow'] or '?'}  {s['run_id']}  status={s['status']}  "
+            f"total={s['total_tokens']:,} tok  ~${total_usd:,.2f}  invariant_ok={s['invariant_ok']}")
+    lines = [head]
+    for stage, st in sorted(s["stages"].items(), key=lambda kv: -kv[1]["tokens"]):
+        bar = "#" * int(round(st["pct"] / 2))
+        usd = costs.get(stage, 0.0)
+        lines.append(f"  {stage:14s} {st['tokens']:>9,}  {st['pct']:5.1f}%  ~${usd:>7,.2f}  n={st['count']:<3d} {bar}")
+    findings = detect_degradation(run)
+    if findings:
+        lines.append("  ! DEGRADED — cost numbers on this run are NOT publishable:")
+        for f in findings:
+            lines.append(f"      [{f['severity']}] {f['stage']}: {f['kind']} — {f['detail']}")
+    lines.append(f"  ($ = estimate: list prices, {input_share:.0%}-input blend; telemetry has no I/O split)")
+    return "\n".join(lines)
+
+
+def main(argv=None):
+    argv = sys.argv[1:] if argv is None else argv
+    if not argv:
+        print("usage: python -m agent_cost_attribution <run.json | run-dir> ...", file=sys.stderr)
+        return 2
+    paths = list(_iter_paths(argv))
+    if not paths:
+        print("no run files found", file=sys.stderr)
+        return 1
+    for p in paths:
+        run = load_run(p)
+        if not run:
+            print(f"{p}: unreadable/empty", file=sys.stderr)
+            continue
+        print(render(run))
+        print()
+    return 0

agent_cost_attribution/health.py

@@ -0,0 +1,50 @@
+"""Silent-degradation detector for multi-agent workflow runs.
+
+The failure that broke the cost baseline (wf_3d01df61): a stage's agents can all ERROR — or run
+anomalously cheap — while the run still reports a status and a plausible totalTokens, so a naive
+per-stage decomposition silently mis-attributes cost (Fetch looked like 66% only because every
+verifier crashed at ~1588 tok). This flags such stages so a cost number is never published on a
+degraded run.
+"""
+import statistics
+
+from agent_cost_attribution.ledger import agents
+
+
+def detect_degradation(run, *, min_agents=5, cheap_ratio=0.25):
+    """Findings (empty == healthy). Each: {stage, kind, severity, detail}.
+
+    kind 'errors' : a stage has agents in state 'error'.
+    kind 'cheap'  : a stage of >= min_agents whose mean tokens/agent is < cheap_ratio of the run-wide
+                    baseline (median of per-stage mean costs) — the signature of a mass-degraded stage.
+    """
+    ags = agents(run)
+    findings = []
+
+    by_stage = {}
+    for a in ags:
+        by_stage.setdefault(a.stage, []).append(a)
+
+    # Run-wide baseline: median of per-stage mean token costs (one data point per stage).
+    # Using per-stage means rather than per-agent tokens prevents a degraded stage's own
+    # cheap agents from dragging the median down and hiding itself.
+    stage_means = [statistics.mean(r.tokens for r in rows)
+                   for rows in by_stage.values() if rows]
+    median = statistics.median(stage_means) if stage_means else 0
+
+    for stage, rows in by_stage.items():
+        errs = [r for r in rows if r.state == "error"]
+        if errs:
+            findings.append({"stage": stage, "kind": "errors", "severity": "high",
+                             "detail": f"{len(errs)}/{len(rows)} agents in state 'error'"})
+        if median and len(rows) >= min_agents:
+            mean_tok = statistics.mean(r.tokens for r in rows)
+            if mean_tok < cheap_ratio * median:
+                findings.append({"stage": stage, "kind": "cheap", "severity": "high",
+                                 "detail": f"mean {mean_tok:.0f} tok/agent over {len(rows)} agents "
+                                           f"< {cheap_ratio:.0%} of run median {median:.0f}"})
+    return findings
+
+
+def is_healthy(run, **kw):
+    return not detect_degradation(run, **kw)

agent_cost_attribution/ledger.py

@@ -0,0 +1,107 @@
+"""Per-stage token attribution for multi-agent workflow runs.
+
+Reusable + stdlib-only: reads platform workflow telemetry (wf_*.json) and decomposes totalTokens
+across stages (phases). No dependency on any workflow's internals, so it works for ANY workflow run,
+not just deep-research.
+
+Verified schema: a run JSON has top-level `totalTokens` and `workflowProgress`, a list whose entries
+are either type=="workflow_phase" (headers, no tokens) or type=="workflow_agent" (per-agent records
+with `phaseTitle`, `state`, `tokens`, `model`). Invariant: agent tokens sum EXACTLY to totalTokens.
+
+Fail-soft: a missing/corrupt run degrades to {}, never crashes a caller.
+"""
+import json
+from dataclasses import dataclass
+from pathlib import Path
+
+_AGENT = "workflow_agent"
+
+
+def _as_int(value):
+    """Coerce to int, fail-soft to 0 (a corrupt token/count field must never crash a parse)."""
+    try:
+        return int(value or 0)
+    except (ValueError, TypeError):
+        return 0
+
+
+@dataclass(frozen=True)
+class AgentRecord:
+    agent_id: str
+    label: str
+    stage: str
+    model: str
+    state: str
+    tokens: int
+    tool_calls: int
+
+
+def load_run(path):
+    """Load a run JSON; fail-soft to {} on missing/corrupt/non-object."""
+    try:
+        data = json.loads(Path(path).read_text())
+    except (OSError, ValueError, TypeError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def agents(run):
+    """Per-agent records (type==workflow_agent). Phase-header rows are skipped."""
+    out = []
+    for e in (run.get("workflowProgress") or []):
+        if not isinstance(e, dict) or e.get("type") != _AGENT:
+            continue
+        out.append(AgentRecord(
+            agent_id=e.get("agentId", ""),
+            label=e.get("label", ""),
+            stage=e.get("phaseTitle", "?"),
+            model=e.get("model", ""),
+            state=e.get("state", "?"),
+            tokens=_as_int(e.get("tokens")),
+            tool_calls=_as_int(e.get("toolCalls")),
+        ))
+    return out
+
+
+def total_tokens(run):
+    """The run's reported total token count, fail-soft to 0."""
+    return _as_int(run.get("totalTokens"))
+
+
+def decompose(run):
+    """{stage: summed tokens}, preserving first-seen (phase) order."""
+    out = {}
+    for a in agents(run):
+        out[a.stage] = out.get(a.stage, 0) + a.tokens
+    return out
+
+
+def verify_invariant(run):
+    """True iff per-agent tokens sum to the run's totalTokens — the parser's correctness check.
+
+    A run with no agent rows returns False (no data is not a satisfied invariant)."""
+    ags = agents(run)
+    if not ags:
+        return False
+    return sum(a.tokens for a in ags) == total_tokens(run)
+
+
+def summary(run):
+    """Per-stage decomposition with pct/count/state-mix, plus the invariant flag."""
+    tot = total_tokens(run)
+    stages = {}
+    for a in agents(run):
+        s = stages.setdefault(a.stage, {"tokens": 0, "count": 0, "states": {}})
+        s["tokens"] += a.tokens
+        s["count"] += 1
+        s["states"][a.state] = s["states"].get(a.state, 0) + 1
+    for s in stages.values():
+        s["pct"] = round(100 * s["tokens"] / tot, 1) if tot else 0.0
+    return {
+        "run_id": run.get("runId", ""),
+        "workflow": run.get("workflowName", ""),
+        "status": run.get("status", ""),
+        "total_tokens": tot,
+        "invariant_ok": verify_invariant(run),
+        "stages": stages,
+    }

agent_cost_attribution/pricing.py

@@ -0,0 +1,51 @@
+"""Estimated dollar cost for token counts, by model.
+
+CAVEAT (important, surfaced in output): workflow telemetry reports a SINGLE token count per agent with
+NO input/output split. Dollar figures are therefore ESTIMATES — we price the token count at a per-model
+blended rate using a configurable input-share assumption (default 0.85: agentic/tool-heavy runs are
+input-dominated). Prices are public list prices and change over time; update PRICES as needed.
+"""
+
+# $ per 1M tokens (input, output) — public list prices, verified at platform.claude.com 2026-06-09.
+PRICES = {
+    "fable":  (10.0, 50.0),
+    "opus":   (5.0, 25.0),
+    "sonnet": (3.0, 15.0),
+    "haiku":  (1.0, 5.0),
+}
+_UNKNOWN = PRICES["opus"]          # unknown model → priced as opus (sensible default)
+DEFAULT_INPUT_SHARE = 0.85
+
+
+def _tier(model):
+    m = (model or "").lower()
+    for tier in ("fable", "opus", "sonnet", "haiku"):
+        if tier in m:
+            return tier
+    return None
+
+
+def blended_rate(model, *, input_share=DEFAULT_INPUT_SHARE):
+    """Blended $ per single token for `model`, given the input-share assumption."""
+    inp, outp = PRICES.get(_tier(model), _UNKNOWN)
+    per_mtok = input_share * inp + (1.0 - input_share) * outp
+    return per_mtok / 1_000_000.0
+
+
+def estimate_cost(tokens, model, *, input_share=DEFAULT_INPUT_SHARE):
+    """Estimated USD to process `tokens` on `model`. An ESTIMATE — see module caveat."""
+    return (tokens or 0) * blended_rate(model, input_share=input_share)
+
+
+def cost_by_stage(run, *, input_share=DEFAULT_INPUT_SHARE):
+    """{stage: estimated USD}, summed PER AGENT (so per-agent model routing is reflected)."""
+    from agent_cost_attribution.ledger import agents
+    out = {}
+    for a in agents(run):
+        out[a.stage] = out.get(a.stage, 0.0) + estimate_cost(a.tokens, a.model, input_share=input_share)
+    return out
+
+
+def total_cost(run, *, input_share=DEFAULT_INPUT_SHARE):
+    """Estimated USD for the whole run."""
+    return sum(cost_by_stage(run, input_share=input_share).values())

agent_cost_attribution/routing.py

@@ -0,0 +1,122 @@
+"""Route every model call to the cheapest sufficient model — the enforcement half of A1.
+
+The meter (this repo) tells you WHERE tokens go per stage; this module is the policy layer
+that makes the fix stick: a single role table maps each workload to a model + effort, so
+"right-size the model per task" (PLAYBOOK A1) is one table instead of N scattered call
+sites. The case study that produced this pattern is in ROUTING.md.
+
+Design rules (each one earned by a real failure, see ROUTING.md):
+- One table, no hardcoded models at call sites — an unpinned call silently inherits your
+  most expensive default.
+- Unknown role -> KeyError (fail closed): a typo'd role must surface, not silently route.
+- Overrides file -> fail SOFT: a corrupt tuning file must degrade to defaults, never
+  silence a production routine.
+- Per-message escalation is IMPERATIVE-ONLY and tag-overridable: a missed escalation is
+  recoverable (the user types the tag); a false escalation silently burns budget.
+
+Dependency-free, ~120 lines. Pair with `pricing.savings_estimate`-style numbers via
+`savings_estimate()` below — but treat those as planning estimates; the meter measures.
+"""
+import json
+import re
+from pathlib import Path
+
+
+class Router:
+    """Role -> {"model", "effort"} resolution with optional fail-soft file overrides.
+
+    `roles` is your table, e.g. {"chat": {"model": "...", "effort": "medium"}, ...}.
+    `overrides_path` (JSON: {role: {model?, effort?}}) lets you re-route live without a
+    deploy; partial overrides merge over defaults, garbage is ignored per-key.
+    """
+
+    def __init__(self, roles, overrides_path=None):
+        self.roles = dict(roles)
+        # Coerce str -> Path: fail-soft is for CORRUPT files, not for hiding a caller's
+        # type mistake (a str path silently disabling live tuning is the worst outcome).
+        self.overrides_path = (Path(overrides_path) if isinstance(overrides_path, str)
+                               else overrides_path)
+
+    def _overrides(self):
+        if self.overrides_path is None:
+            return {}
+        try:
+            loaded = json.loads(self.overrides_path.read_text())
+        except (OSError, ValueError, TypeError):
+            return {}
+        return loaded if isinstance(loaded, dict) else {}
+
+    def resolve(self, role):
+        """{"model", "effort"} for `role`. Unknown role raises KeyError (fail closed)."""
+        cfg = dict(self.roles[role])
+        ov = self._overrides().get(role)
+        if isinstance(ov, dict):
+            m = ov.get("model")
+            if isinstance(m, str) and m.strip():
+                cfg["model"] = m.strip()
+            if "effort" in ov:
+                e = ov["effort"]
+                cfg["effort"] = e.strip() if isinstance(e, str) and e.strip() else None
+        return cfg
+
+    def model_for(self, role):
+        return self.resolve(role)["model"]
+
+    def effort_for(self, role):
+        return self.resolve(role)["effort"]
+
+
+class MessageRouter:
+    """Per-message routing for a chat-style agent: explicit !tag > escalation regex >
+    cheap default. The tag is stripped from the text before the model sees it.
+
+    `tags` maps tag names to {"model", "effort"} (typed as `!name` anywhere in a message).
+    `deep_pattern` is YOUR escalation regex — keep it imperative-only (see module
+    docstring for why false escalations are the failure mode, not missed ones).
+    """
+
+    def __init__(self, router, *, tags, deep_pattern,
+                 default_role="chat", deep_role="chat_deep"):
+        self.router = router
+        self.tags = {k.lower(): dict(v) for k, v in tags.items()}
+        if self.tags:
+            names = "|".join(re.escape(k) for k in sorted(self.tags))
+            self._tag_re = re.compile(rf"(?:(?<=\s)|^)!({names})\b", re.I)
+        else:
+            self._tag_re = re.compile(r"(?!x)x")     # never matches: no tags configured
+        self._deep_re = re.compile(deep_pattern, re.I)
+        self.default_role = default_role
+        self.deep_role = deep_role
+
+    def route(self, text):
+        """Returns ({"model", "effort"}, cleaned_text)."""
+        text = text if isinstance(text, str) else ""
+        m = self._tag_re.search(text)
+        if m:
+            cleaned = self._tag_re.sub("", text, count=1)
+            cleaned = re.sub(r"[ \t]{2,}", " ", cleaned).strip()
+            return dict(self.tags[m.group(1).lower()]), cleaned
+        if self._deep_re.search(text):
+            return self.router.resolve(self.deep_role), text
+        return self.router.resolve(self.default_role), text
+
+
+def savings_estimate(traffic, roles, *, baseline_model, input_share=None):
+    """PLANNING estimate of routed vs uniform-baseline spend. NOT a measurement.
+
+    `traffic` maps role -> token volume (get real volumes from the meter's per-stage
+    waterfall). Returns {"baseline_usd", "routed_usd", "saved_usd", "saved_pct"}, priced
+    with this repo's `pricing` blended rates (same caveats: list prices, input-share
+    assumption). Publish measured deltas from the meter, not this — this is for deciding
+    whether the routing work is worth doing.
+    """
+    from agent_cost_attribution import pricing
+    share = pricing.DEFAULT_INPUT_SHARE if input_share is None else input_share
+    router = Router(roles)
+    baseline = routed = 0.0
+    for role, tokens in traffic.items():
+        baseline += pricing.estimate_cost(tokens, baseline_model, input_share=share)
+        routed += pricing.estimate_cost(tokens, router.model_for(role), input_share=share)
+    saved = baseline - routed
+    return {"baseline_usd": baseline, "routed_usd": routed, "saved_usd": saved,
+            "saved_pct": (100.0 * saved / baseline) if baseline else 0.0}

agent_cost_attribution-0.1.0.dist-info/METADATA

@@ -0,0 +1,194 @@
+Metadata-Version: 2.4
+Name: agent-cost-attribution
+Version: 0.1.0
+Summary: Per-stage token/cost attribution and silent-degradation detection for multi-agent workflow runs (stdlib-only).
+Author: Jeff Otterson
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Jott2121/agent-cost-attribution
+Project-URL: Repository, https://github.com/Jott2121/agent-cost-attribution
+Project-URL: Issues, https://github.com/Jott2121/agent-cost-attribution/issues
+Keywords: ai,agents,llm,cost,tokens,observability,telemetry
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# agent-cost-attribution
+
+[![CI](https://github.com/Jott2121/agent-cost-attribution/actions/workflows/ci.yml/badge.svg)](https://github.com/Jott2121/agent-cost-attribution/actions/workflows/ci.yml)
+[![CodeQL](https://github.com/Jott2121/agent-cost-attribution/actions/workflows/codeql.yml/badge.svg)](https://github.com/Jott2121/agent-cost-attribution/actions/workflows/codeql.yml)
+[![Coverage](https://raw.githubusercontent.com/Jott2121/agent-cost-attribution/python-coverage-comment-action-data/badge.svg)](https://github.com/Jott2121/agent-cost-attribution/actions/workflows/ci.yml)
+![Python](https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11%20%7C%203.12-blue)
+
+**Get the most capability per token out of agentic coding, and prove it. Headline result, measured by the meter in this repo: routing four mechanical agents to a cheap model cut run cost 67% (~$0.60 → ~$0.20) with identical facts extracted ([receipt](https://github.com/Jott2121/agent-cost-attribution/blob/main/examples/routing-savings.md)).**
+
+Agentic workflows (fan-out subagents, multi-step research, tool-heavy pipelines) burn tokens fast,
+and most of the waste is invisible. You can't fix what you can't see, and the platform's own "success"
+flag is wrong more often than you'd think.
+
+> 🧩 One layer of a five-repo [**cost-governance stack**](https://github.com/Jott2121/bow#the-system-a-cost-governance-stack) for operating AI agents cost-efficiently; [bow](https://github.com/Jott2121/bow) is the flagship that runs every layer in production.
+
+This repo is two things:
+
+1. **`agent_cost_attribution`**: a tiny, dependency-free **meter**. Point it at a workflow run's
+   telemetry and get a per-stage token waterfall, plus a **silent-degradation check** that flags runs
+   that *reported success while quietly breaking*.
+2. **[PLAYBOOK.md](https://github.com/Jott2121/agent-cost-attribution/blob/main/PLAYBOOK.md)**: a playbook of transferable practices for cutting token burn in
+   agentic coding **without losing capability**, each rated by expected savings, axis (tokens vs cost
+   vs latency), capability risk, and effort.
+
+Everything here is **measured, not asserted**. The numbers in this repo were produced by the meter
+included here; point it at your own telemetry to do the same.
+
+## Try it in 30 seconds (zero dependencies, sample included)
+
+```bash
+git clone https://github.com/Jott2121/agent-cost-attribution
+cd agent-cost-attribution
+python3 -m agent_cost_attribution examples/sample-run.json
+```
+
+Output (from the synthetic sample shipped in [`examples/sample-run.json`](https://github.com/Jott2121/agent-cost-attribution/blob/main/examples/sample-run.json)):
+
+```
+sample-research  wf_sample-001  status=completed  total=1,006,200 tok  ~$3.92  invariant_ok=True
+  Verify           720,748   71.6%  ~$   3.46  n=12  ####################################
+  Search           254,248   25.3%  ~$   0.41  n=6   #############
+  Scope             31,204    3.1%  ~$   0.05  n=1   ##
+  ($ = estimate: list prices, 85%-input blend; telemetry has no I/O split)
+```
+
+Then point it at your own runs:
+
+```bash
+python3 -m agent_cost_attribution path/to/run.json
+python3 -m agent_cost_attribution path/to/runs-dir/      # every wf_*.json in a directory
+```
+
+**Where does `run.json` come from?** The meter reads Claude Code workflow telemetry: the `wf_*.json`
+files that Claude Code writes automatically when you run agentic workflows, found under
+`~/.claude/projects/*/tasks/`. If you run Claude Code workflows, you already have these files; no
+instrumentation, SDK, or proxy is required. The shipped sample is synthetic but format-exact, so you
+can see the output before you have telemetry of your own.
+
+You get three things per run: **tokens**, an estimated **dollar cost**, and a **trust check**.
+
+- **`invariant_ok`** means the per-agent token counts sum **exactly** to the run total. The parser is
+  checking itself, so you can believe the breakdown.
+- The **`~$` figures are estimates**: each agent's tokens are priced at its model's list price using a
+  documented input/output blend (the telemetry exposes only a single token count, no I/O split), so read
+  them as a calibrated band, not a billing statement. Because they're priced **per agent**, a
+  model-routing win shows up directly (route a stage to a cheaper model and its `~$` drops).
+- A **`DEGRADED`** banner appears when a stage errored or ran anomalously cheap. Cost numbers on a
+  degraded run aren't trustworthy and shouldn't be published.
+
+## How this differs from Langfuse / Helicone
+
+Langfuse, Helicone, and similar LLM observability platforms are excellent at what they do: they sit
+in your request path (SDK or proxy), capture every call, and give you dashboards over time. This tool
+is deliberately the opposite shape. It is a **post-hoc forensic meter**: a single stdlib-only Python
+package, no server, no account, no instrumentation, that reads telemetry files the platform already
+wrote and answers two narrow questions per run: *which stage of this multi-agent workflow ate the
+tokens*, and *can I trust this run's numbers at all* (the invariant check plus silent-degradation
+detection). If you want fleet-wide dashboards, use those platforms. If you want to audit one run's
+cost attribution in 30 seconds with zero setup, use this.
+
+## The headline finding (why you should trust the method)
+
+I built this meter to support an optimization plan I'd already written. **The meter overturned my own
+plan.** I had assumed the token whale was the page-**Fetch** stage; the telemetry showed it was the
+**Verify** stage (50-74% of healthy runs vs Fetch's ~19-37%). The "expensive" run I'd anchored my
+baseline on turned out to be a **silently broken outlier**: it reported `status=completed` while all
+75 of its verifier agents had errored, which is the *only* reason Fetch looked dominant there.
+
+Along the way the meter also showed the platform's own status flag was unreliable in **both**
+directions: one run said `completed` but was broken; another said `failed` but was perfectly healthy.
+The lesson, and the reason the silent-degradation check exists: **trust per-stage health, not the
+run's self-report.** Full numbers in [`examples/self-correction-deep-research.md`](https://github.com/Jott2121/agent-cost-attribution/blob/main/examples/self-correction-deep-research.md).
+
+Measurement that kills your own hypothesis is the whole point. The rest of this repo is built on it.
+
+## The playbook (TL;DR; full version in [PLAYBOOK.md](https://github.com/Jott2121/agent-cost-attribution/blob/main/PLAYBOOK.md))
+
+- **Right-size the model per task**: mechanical sub-tasks on a cheap model, judgment/synthesis on the
+  strong one. (This repo's own builder/reviewer agents ran on the cheaper tier.)
+- **Fan out only for read-heavy parallel work; keep writes single-threaded.**
+- **Scope context tightly**: read the slice you need, don't re-read, hand a sub-agent only what it needs.
+- **Don't re-gather redundantly · kill junk cheaply before expensive stages · dedup inputs · make your caps actually cap.**
+- **Prompt caching · structured outputs.**
+- **Meter every run · gate on quality · refuse the unsafe shortcut and prove it.**
+
+Each practice is reported on the right axis and **never double-counted** (routing changes cost-per-token,
+not token *count*; caching is a cost-axis win; only genuine token-count reductions go on the headline).
+
+**Measured proof:** [`examples/routing-savings.md`](https://github.com/Jott2121/agent-cost-attribution/blob/main/examples/routing-savings.md), a live before/after
+where routing four mechanical agents to a cheap model cut run cost **67% (~$0.60 to ~$0.20)** with
+identical facts extracted, isolated by the meter to exactly the routed stage. Reproducible from
+[`examples/routing-demo.js`](https://github.com/Jott2121/agent-cost-attribution/blob/main/examples/routing-demo.js).
+
+## Making A1 stick: the routing layer ([ROUTING.md](https://github.com/Jott2121/agent-cost-attribution/blob/main/ROUTING.md))
+
+Right-sizing the model per task fails in practice when the model is a string literal at N call
+sites: one unpinned call silently inherits your most expensive default. [ROUTING.md](https://github.com/Jott2121/agent-cost-attribution/blob/main/ROUTING.md)
+is the case study of retrofitting a live agent fleet (11 call sites, zero routing, all premium-pinned)
+with a central role table, per-message escalation (`!tag` > imperative-only heuristic > cheap
+default), fail-soft live tuning, and an independent cross-model QC pass that caught the policy's own
+over-escalation bug before ship. Audited, built, and live in one day. The reusable module is
+[`agent_cost_attribution/routing.py`](https://github.com/Jott2121/agent-cost-attribution/blob/main/agent_cost_attribution/routing.py) (stdlib-only, like the meter):
+`Router` (fail-closed roles, fail-soft overrides), `MessageRouter` (chat escalation), and
+`savings_estimate()` (planning estimates from the meter's real volumes; labeled estimates, never
+published as measurements).
+
+## What's here
+
+```
+README.md      - this file
+PLAYBOOK.md    - the practices, each with what / why / how / savings / risk
+ROUTING.md     - case study + design rules: retrofitting model routing onto a live fleet in a day
+agent_cost_attribution/   - the meter (stdlib-only): ledger, health, cli, plus routing.py (A1's enforcement layer)
+tests/         - the meter's tests (the sum==total invariant is golden-tested)
+examples/      - measured worked examples + sample-run.json (synthetic quickstart telemetry)
+pyproject.toml - package metadata + pytest config
+.github/       - CI (pytest on Python 3.9-3.12 + a smoke run of the meter on the sample)
+LICENSE        - MIT
+```
+
+## Who it's for
+
+Anyone running agentic workflows who wants maximum capability per token, and a way to *find their own
+waste* instead of guessing. It's also a worked demonstration of rigorous, measured agentic-coding
+practice: measure, attribute, gate on quality, publish what you kept *and* what you killed.
+
+## Reliability & security
+
+A meter people trust has to be measured itself, so the repo is gated:
+
+- **Coverage-gated test matrix** — pytest on Python 3.9–3.12, build fails below the coverage floor (currently 96% covered), plus a smoke-test of the meter on the shipped sample run.
+- **CodeQL** — `security-extended` static analysis on every push, PR, and weekly; findings surface in the Security tab.
+- **Pinned supply chain** — GitHub Actions pinned to commit SHAs, kept current by **Dependabot**.
+- **Branch protection** — `main` requires CI + CodeQL to pass before a merge.
+- **Disclosure policy** — see [SECURITY.md](https://github.com/Jott2121/agent-cost-attribution/blob/main/SECURITY.md); private reporting is enabled.
+
+## About
+
+Built by **Jeff Otterson** ([Jott2121](https://github.com/Jott2121)). Part of the Fleet Mode line:
+[**bow**](https://github.com/Jott2121/bow) (the flagship agent case study) ·
+[**fleet-mode**](https://github.com/Jott2121/fleet-mode) (the orchestration doctrine as a live skill) ·
+[**agent-gate**](https://github.com/Jott2121/agent-gate) · [**rag-guard**](https://github.com/Jott2121/rag-guard) ·
+[**sabot**](https://github.com/Jott2121/sabot) (own-checks fault detection — its silent
+model-downgrade operator grew out of the degraded-run detector in this repo).
+The same discipline throughout: measure it, gate it, keep the receipts.
+
+## License
+
+MIT, see [LICENSE](https://github.com/Jott2121/agent-cost-attribution/blob/main/LICENSE).

agent_cost_attribution-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+agent_cost_attribution/__init__.py,sha256=neLU0N0eFos2K5fNSrKlLL_tqkFN9uDA5FnC4bxZMXw,620
+agent_cost_attribution/__main__.py,sha256=f9i3gFdt-T9IChQkPpTSg-UkywcIJrN4kMK59jRplUM,70
+agent_cost_attribution/cli.py,sha256=d1eLijYOmN_zEZA88kgNQf_vkEvXaBjkHyRN96aY-7M,2254
+agent_cost_attribution/health.py,sha256=Yf7RVSEYlzm8uwqHhrYJWG1jevOuIJSIUdzKcEfpqzI,2334
+agent_cost_attribution/ledger.py,sha256=iw5l-eKWqSnzwtdeyIOV3-oQ1ONeARK67ku5GvrudWA,3396
+agent_cost_attribution/pricing.py,sha256=twGFtOtGbAN247v75OLZ8uKFRZHOcZ12UkBYg04R6a0,2036
+agent_cost_attribution/routing.py,sha256=F5YoDsA2eVi9TzWvKnq0sLJq62M08uLUKuEu63sGZBE,5699
+agent_cost_attribution-0.1.0.dist-info/licenses/LICENSE,sha256=pbwOmZQ2k7MAsOJyV2f9ZOfIXLCpS2Tp232WUv16shI,1070
+agent_cost_attribution-0.1.0.dist-info/METADATA,sha256=xi_plj2O5K9wSF3LPF0GiNIEu7Zfq_1zpTRhH_NDx_w,12639
+agent_cost_attribution-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+agent_cost_attribution-0.1.0.dist-info/top_level.txt,sha256=JxnwI3G67HudA6Few1CZk_9AFGv4maMj9O0cpWc9F94,23
+agent_cost_attribution-0.1.0.dist-info/RECORD,,

agent_cost_attribution-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

agent_cost_attribution-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jeff Otterson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agent_cost_attribution-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+agent_cost_attribution