cachecanary 0.1.0__py3-none-any.whl

cachecanary/__init__.py

@@ -0,0 +1,3 @@
+"""CacheCanary: know the moment your Claude prompt cache breaks on Amazon Bedrock."""
+
+__version__ = "0.1.0"

cachecanary/cli.py

@@ -0,0 +1,202 @@
+"""cachecanary command line.
+
+  cachecanary lint request.json [--model ID]
+  cachecanary diff previous.json next.json [--model ID]
+  cachecanary probe request.json --model ID [--region R] [--stream]
+  cachecanary logs file.json[.gz] ... [--by model|principal|model+principal] [--min-hit 0.5]
+
+Exit codes: 0 ok, 1 caching problem found (use to gate CI), 2 could not run (bad input, AWS error).
+Add --github (before the command) for GitHub Actions annotations and a job summary.
+"""
+
+import argparse
+import json
+import sys
+from dataclasses import asdict
+from pathlib import Path
+
+from cachecanary import __version__, diff, lint, logs, probe
+from cachecanary import github as gh
+from cachecanary.request import RequestError, normalize
+
+EXIT_OK, EXIT_PROBLEM, EXIT_ERROR = 0, 1, 2
+
+
+class InputError(Exception):
+    pass
+
+
+def _load(path: str):
+    try:
+        return json.loads(Path(path).read_text(encoding="utf-8"))
+    except FileNotFoundError as exc:
+        raise InputError(f"file not found: {path}") from exc
+    except json.JSONDecodeError as exc:
+        raise InputError(f"{path} is not valid JSON: {exc}") from exc
+
+
+def _emit(data, as_json: bool, lines: list[str]) -> None:
+    print(json.dumps(data, indent=2) if as_json else "\n".join(lines))
+
+
+def cmd_lint(args) -> int:
+    findings = lint.lint(normalize(_load(args.request), args.model))
+    lines = [f"[{f.severity}] {f.rule}: {f.message}" + (f" ({f.location})" if f.location else "") for f in findings]
+    _emit([asdict(f) for f in findings], args.json, lines or ["No caching problems found."])
+    if args.github:
+        for f in findings:
+            level = "error" if f.severity == "error" else "warning"
+            where = f" ({f.location})" if f.location else ""
+            print(gh.annotation(level, f"{f.message}{where}", file=args.request, title=f"CacheCanary: {f.rule}"))
+        rows = [[f.severity, f.rule, f.location or "", f.message] for f in findings]
+        gh.append_summary(f"### CacheCanary lint: `{args.request}`\n\n" + (
+            gh.table(["severity", "rule", "location", "message"], rows) if rows else "No caching problems found. ✅"))
+    return EXIT_PROBLEM if any(f.severity == "error" for f in findings) else EXIT_OK
+
+
+def cmd_diff(args) -> int:
+    reasons = diff.explain(normalize(_load(args.previous), args.model), normalize(_load(args.next), args.model))
+    lines = [f"{r.code}: {r.message}" + (f" ({r.location})" if r.location else "") for r in reasons]
+    _emit([asdict(r) for r in reasons], args.json, lines)
+    ok = bool(reasons) and reasons[0].code == "prefix-identical"
+    if args.github:
+        for r in reasons:
+            where = f" ({r.location})" if r.location else ""
+            print(gh.annotation("notice" if ok else "error", f"{r.message}{where}", file=args.next, title=f"CacheCanary: {r.code}"))
+        gh.append_summary(f"### CacheCanary diff: `{args.previous}` → `{args.next}`\n\n" +
+                          gh.table(["reason", "location", "explanation"], [[r.code, r.location or "", r.message] for r in reasons]))
+    return EXIT_OK if ok else EXIT_PROBLEM
+
+
+def _probe_explanation(result: probe.ProbeResult, model: str) -> list[str]:
+    first, second = result.first, result.second
+    if second is None:
+        return ["Could not read token usage from the response, so caching could not be verified."]
+    if result.passed:
+        return []
+    if first and first.cache_write == 0 and first.cache_read == 0:
+        return ["The first call wrote nothing to the cache: no checkpoint was applied (prefix below the "
+                "model minimum, no cache markers, or the library/model ID skipped caching)."]
+    if first and first.cache_write > 0:
+        hint = ["The first call wrote to the cache but the second did not read it."]
+        if model.split(".")[0] in ("us", "eu", "apac", "global", "jp", "au", "ca"):
+            hint.append("Cross-region profiles can route the two calls to different Regions; retry or test with "
+                        "an in-Region model ID to rule this out.")
+        return hint
+    return []
+
+
+def cmd_probe(args) -> int:
+    result = probe.probe(_load(args.request), args.model, region=args.region, stream=args.stream)
+    data = {"passed": result.passed, "first": asdict(result.first) if result.first else None,
+            "second": asdict(result.second) if result.second else None}
+    status = "PASS: second call read from cache." if result.passed else "FAIL: second call did not read from cache."
+    lines = [status, f"first:  {data['first']}", f"second: {data['second']}"]
+    lines += _probe_explanation(result, args.model)
+    if not result.passed:
+        lines.append("Run `cachecanary lint` on the same request to find the likely cause.")
+    _emit(data, args.json, lines)
+    if args.github:
+        if not result.passed:
+            print(gh.annotation("error", " ".join(lines[3:]) or status, file=args.request, title="CacheCanary: cache not read on 2nd call"))
+        rows = [[name, u["uncached_input"], u["cache_read"], u["cache_write"]] if u else [name, "?", "?", "?"]
+                for name, u in (("1st call", data["first"]), ("2nd call", data["second"]))]
+        gh.append_summary(f"### CacheCanary probe: `{args.request}` on `{args.model}` — {'PASS ✅' if result.passed else 'FAIL ❌'}\n\n"
+                          + gh.table(["call", "uncached", "cache read", "cache write"], rows))
+    return EXIT_OK if result.passed else EXIT_PROBLEM
+
+
+def cmd_logs(args) -> int:
+    stats = logs.ReadStats()
+    records = []
+    for p in args.files:
+        path = Path(p)
+        if not path.exists():
+            raise InputError(f"file not found: {p}")
+        try:
+            records.extend(logs.iter_records(path, stats))
+        except (OSError, json.JSONDecodeError) as exc:
+            raise InputError(f"could not read {p}: {exc}") from exc
+    groups = logs.aggregate(records, by=args.by)
+    data, lines, failing = {}, [], False
+    for key, g in sorted(groups.items(), key=lambda kv: -kv[1].usage.total_input):
+        ratio = g.usage.hit_ratio
+        data[key] = {"calls": g.calls, "unparsed": g.unparsed, "hit_ratio": round(ratio, 3), **asdict(g.usage)}
+        flag = ""
+        if args.min_hit is not None and g.calls - g.unparsed > 0 and ratio < args.min_hit:
+            flag, failing = "  <-- below threshold", True
+        lines.append(f"{key}: hit {ratio:.0%} over {g.calls} calls "
+                     f"(read {g.usage.cache_read}, write {g.usage.cache_write}, uncached {g.usage.uncached_input}, "
+                     f"unparsed {g.unparsed}){flag}")
+    if stats.bad_lines:
+        lines.append(f"Skipped {stats.bad_lines} unreadable line(s).")
+    _emit(data, args.json, lines or ["No invocation log records found."])
+    if args.github:
+        rows = []
+        for key, d in data.items():
+            below = args.min_hit is not None and d["calls"] - d["unparsed"] > 0 and d["hit_ratio"] < args.min_hit
+            if below:
+                print(gh.annotation("error", f"{key}: cache hit rate {d['hit_ratio']:.0%} is below {args.min_hit:.0%}",
+                                    title="CacheCanary: low cache hit rate"))
+            rows.append([key, d["calls"], f"{d['hit_ratio']:.0%}", d["cache_read"], d["cache_write"], d["uncached_input"],
+                         d["unparsed"], "❌" if below else ""])
+        gh.append_summary("### CacheCanary logs\n\n" + (gh.table(
+            ["group", "calls", "hit rate", "read", "write", "uncached", "unparsed", "below threshold"], rows)
+            if rows else "No invocation log records found."))
+    return EXIT_PROBLEM if failing else EXIT_OK
+
+
+def _unit(value: str) -> float:
+    f = float(value)
+    if not 0 <= f <= 1:
+        raise argparse.ArgumentTypeError("must be between 0 and 1")
+    return f
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="cachecanary", description="CacheCanary: catch silent prompt-cache breakage for Claude on Amazon Bedrock.")
+    parser.add_argument("--version", action="version", version=f"cachecanary {__version__}")
+    parser.add_argument("--json", action="store_true", help="machine-readable output")
+    parser.add_argument("--github", action="store_true",
+                        help="also emit GitHub Actions annotations and a job summary (used by the GitHub Action)")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p = sub.add_parser("lint", help="static checks on one request")
+    p.add_argument("request")
+    p.add_argument("--model")
+    p.set_defaults(func=cmd_lint)
+
+    p = sub.add_parser("diff", help="explain why the next request missed the previous one's cache")
+    p.add_argument("previous")
+    p.add_argument("next")
+    p.add_argument("--model")
+    p.set_defaults(func=cmd_diff)
+
+    p = sub.add_parser("probe", help="send the request twice and check the second reads from cache")
+    p.add_argument("request")
+    p.add_argument("--model", required=True)
+    p.add_argument("--region")
+    p.add_argument("--stream", action="store_true", help="use ConverseStream / InvokeModelWithResponseStream")
+    p.set_defaults(func=cmd_probe)
+
+    p = sub.add_parser("logs", help="cache hit rates from Bedrock invocation logs")
+    p.add_argument("files", nargs="+")
+    p.add_argument("--by", choices=["model", "principal", "model+principal"], default="model")
+    p.add_argument("--min-hit", type=_unit, help="fail if any group's hit ratio is below this (0-1)")
+    p.set_defaults(func=cmd_logs)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        return args.func(args)
+    except (InputError, RequestError, probe.ProbeError) as exc:
+        print(f"cachecanary: error: {exc}", file=sys.stderr)
+        if getattr(args, "github", False):
+            print(gh.annotation("error", str(exc), title="CacheCanary could not run"))
+        return EXIT_ERROR
+
+
+if __name__ == "__main__":
+    sys.exit(main())

cachecanary/diff.py

@@ -0,0 +1,91 @@
+"""Explain why request B missed the cache that request A should have created.
+
+This rebuilds, for Bedrock, what Anthropic's cache diagnostics reports on the Claude API:
+compare consecutive requests and name the first thing that changed inside the cached prefix.
+"""
+
+from dataclasses import dataclass
+
+from cachecanary.models import LOOKBACK_BLOCKS
+from cachecanary.request import NormalizedRequest
+
+
+@dataclass
+class MissReason:
+    code: str
+    message: str
+    location: str | None = None
+
+
+def explain(a: NormalizedRequest, b: NormalizedRequest) -> list[MissReason]:
+    reasons: list[MissReason] = []
+
+    if a.api != b.api:
+        reasons.append(MissReason(
+            "api-changed",
+            f"Requests switched API ({a.api} -> {b.api}). Converse and InvokeModel build different prompts, "
+            "so the cache entry cannot be reused (common after a gateway/library upgrade).",
+        ))
+        return reasons
+
+    if (a.model_id or "") != (b.model_id or ""):
+        reasons.append(MissReason("model-changed", f"Model changed from {a.model_id} to {b.model_id}. Caches are per model."))
+        return reasons
+
+    a_cps = a.checkpoint_indexes
+    if not a_cps:
+        reasons.append(MissReason("no-checkpoint-in-previous", "The previous request had no checkpoint, so it wrote nothing to read back."))
+        return reasons
+    a_last = a_cps[-1]
+
+    if not b.checkpoint_indexes:
+        reasons.append(MissReason(
+            "no-checkpoint-in-next",
+            "The new request has no cache checkpoint, so it never asks to read the cache "
+            "(a library or code path stopped sending cache markers).",
+        ))
+        return reasons
+
+    for i in range(min(a_last + 1, len(b.blocks))):
+        if a.blocks[i].content != b.blocks[i].content:
+            reasons.append(_classify_change(a, b, i))
+            return reasons
+    if len(b.blocks) <= a_last:
+        reasons.append(MissReason("prefix-truncated", "The new request is shorter than the previous cached prefix (history was trimmed or compacted)."))
+        return reasons
+
+    a_ttls = [a.blocks[i].ttl for i in a_cps]
+    b_ttls = [b.blocks[i].ttl for i in b.checkpoint_indexes]
+    if a_ttls and b_ttls and a_ttls[0] != b_ttls[0]:
+        reasons.append(MissReason("ttl-changed", f"Checkpoint TTL changed ({a_ttls[0]} -> {b_ttls[0]}); entries are keyed by TTL."))
+
+    b_cps = b.checkpoint_indexes
+    if b_cps and b_cps[-1] - a_last > LOOKBACK_BLOCKS and not any(a_last <= i < b_cps[-1] for i in b_cps[:-1]):
+        reasons.append(MissReason(
+            "lookback-exceeded",
+            f"{b_cps[-1] - a_last} blocks were added between the previous checkpoint and the new one. Bedrock only "
+            f"looks back ~{LOOKBACK_BLOCKS} blocks, so it cannot find the earlier cache entry. Add an intermediate "
+            "checkpoint (common after many parallel tool calls).",
+            b.blocks[b_cps[-1]].location,
+        ))
+
+    if not reasons:
+        reasons.append(MissReason(
+            "prefix-identical",
+            "The cached prefix is identical. If B still missed, the entry likely expired (TTL elapsed between calls) "
+            "or cross-region inference routed to a Region without the entry.",
+        ))
+    return reasons
+
+
+def _classify_change(a: NormalizedRequest, b: NormalizedRequest, i: int) -> MissReason:
+    section = a.blocks[i].section
+    if section == "tools":
+        a_tools = sorted(x.content for x in a.blocks if x.section == "tools")
+        b_tools = sorted(x.content for x in b.blocks if x.section == "tools")
+        if a_tools == b_tools:
+            return MissReason("tools-reordered", "Same tools, different order. Sort tools deterministically.", b.blocks[i].location)
+        return MissReason("tools-changed", "A tool definition changed; tools come first, so the whole cache is invalidated.", b.blocks[i].location)
+    if section == "system":
+        return MissReason("system-changed", "The system prompt changed inside the cached prefix (look for dates, IDs or per-user text).", b.blocks[i].location)
+    return MissReason("history-changed", "Earlier conversation history was edited (not just appended).", b.blocks[i].location)

cachecanary/github.py

@@ -0,0 +1,50 @@
+"""GitHub Actions output: inline annotations (workflow commands) and a job summary.
+
+Annotations appear on the pull request / run page; the summary is Markdown appended to the
+file named by $GITHUB_STEP_SUMMARY. Both are no-ops outside GitHub Actions apart from printing.
+"""
+
+import os
+
+
+def _escape_data(value: str) -> str:
+    # Per GitHub's workflow-command escaping rules.
+    return value.replace("%", "%25").replace("\r", "%0D").replace("\n", "%0A")
+
+
+def _escape_property(value: str) -> str:
+    return _escape_data(value).replace(":", "%3A").replace(",", "%2C")
+
+
+def annotation(level: str, message: str, file: str | None = None, title: str | None = None) -> str:
+    """level: 'error' | 'warning' | 'notice'."""
+    if level not in ("error", "warning", "notice"):
+        raise ValueError(f"unknown annotation level: {level}")
+    props = []
+    if file:
+        props.append(f"file={_escape_property(file)}")
+    if title:
+        props.append(f"title={_escape_property(title)}")
+    head = f"::{level}" + (" " + ",".join(props) if props else "")
+    return f"{head}::{_escape_data(message)}"
+
+
+def append_summary(markdown: str) -> bool:
+    """Append to the job summary. Returns False when not running in GitHub Actions."""
+    path = os.environ.get("GITHUB_STEP_SUMMARY")
+    if not path:
+        return False
+    with open(path, "a", encoding="utf-8") as fh:
+        fh.write(markdown.rstrip() + "\n\n")
+    return True
+
+
+def md_cell(value) -> str:
+    """Make a value safe inside a Markdown table cell."""
+    return str(value).replace("|", "\\|").replace("\n", " ")
+
+
+def table(headers: list[str], rows: list[list]) -> str:
+    out = ["| " + " | ".join(headers) + " |", "|" + "---|" * len(headers)]
+    out += ["| " + " | ".join(md_cell(c) for c in row) + " |" for row in rows]
+    return "\n".join(out)

cachecanary/lint.py

@@ -0,0 +1,163 @@
+"""Static checks on a single Bedrock request for patterns that silently defeat caching."""
+
+import re
+from dataclasses import dataclass
+
+from cachecanary.models import is_profile_arn, lookup
+from cachecanary.request import NormalizedRequest, estimate_tokens
+
+# Values that usually change per request. Matching them inside the cached prefix is
+# the classic "cache never hits" bug (e.g. "Today's date: ..." in the system prompt).
+DYNAMIC_PATTERNS = {
+    "ISO date": re.compile(r"\b20\d{2}-[01]\d-[0-3]\d\b"),
+    "clock time": re.compile(r"\b[0-2]?\d:[0-5]\d(:[0-5]\d)?\b"),
+    "UUID": re.compile(r"\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b", re.I),
+    "unix timestamp": re.compile(r"\b1[6-9]\d{8}(\d{3})?\b"),
+}
+
+# Conversation blocks after the last checkpoint before we suggest caching the history too.
+MIN_UNCACHED_TAIL = 4
+
+# Token estimates are approximate: live Bedrock runs (Oct 2026) counted ~11% MORE tokens than
+# estimate_tokens() for English prompts. Only call a prefix "too short" when it is clearly below
+# the minimum; inside the uncertainty band, warn and point to `probe` for a definitive answer.
+CLEARLY_BELOW = 0.80
+UNCERTAIN_UP_TO = 1.20
+
+
+@dataclass
+class Finding:
+    rule: str
+    severity: str   # "error" = caching cannot work as written; "warn" = likely miss / money left on table
+    message: str
+    location: str | None = None
+
+
+def lint(req: NormalizedRequest) -> list[Finding]:
+    findings: list[Finding] = []
+    cps = req.checkpoint_indexes
+    key, limits = lookup(req.model_id)
+
+    if not req.model_id:
+        findings.append(Finding(
+            "no-model", "warn",
+            "No model ID given (use --model). Model-specific checks such as the minimum prefix size were skipped.",
+        ))
+    elif is_profile_arn(req.model_id):
+        findings.append(Finding(
+            "profile-arn", "warn",
+            "Model is an application inference profile ARN. Many libraries match model names to "
+            "decide whether to send cache checkpoints and silently skip this case. Verify the "
+            "response shows cache reads/writes. Minimum-size checks were skipped (model unknown).",
+        ))
+    elif key is None:
+        findings.append(Finding(
+            "unknown-model", "warn",
+            f"'{req.model_id}' is not in the known Claude caching table. New model IDs are a common "
+            "reason libraries stop adding checkpoints. Verify cache usage in responses.",
+        ))
+
+    for loc in req.orphan_checkpoints:
+        findings.append(Finding(
+            "orphan-checkpoint", "warn", "Cache checkpoint with no content before it; it caches nothing.", loc,
+        ))
+
+    if req.system_is_string and not any(req.blocks[i].section in ("tools", "system") for i in cps):
+        findings.append(Finding(
+            "string-system", "warn",
+            "'system' is a plain string, which cannot carry cache_control. Send it as a list of "
+            "text blocks and put cache_control on the last one to cache the system prompt.",
+            "system",
+        ))
+
+    if not cps:
+        findings.append(Finding(
+            "no-checkpoint", "warn",
+            "No explicit cache checkpoint. Only best-effort implicit caching applies; add a "
+            "checkpoint after the static content (tools/system) for reliable hits.",
+        ))
+        return findings
+
+    max_cp = limits.max_checkpoints if limits else 4
+    if req.checkpoint_markers > max_cp:
+        findings.append(Finding(
+            "too-many-checkpoints", "error",
+            f"{req.checkpoint_markers} cache markers; the maximum is {max_cp}. Bedrock rejects the request or ignores the extras.",
+        ))
+    for loc in req.duplicate_checkpoints:
+        findings.append(Finding(
+            "duplicate-checkpoint", "warn", "Two cache markers in a row; the second adds nothing but counts toward the limit.", loc,
+        ))
+
+    if limits:
+        cumulative = 0
+        clearly_short: list[tuple[int, int]] = []
+        borderline: list[tuple[int, int]] = []
+        cached_any = False
+        for i, block in enumerate(req.blocks[: cps[-1] + 1]):
+            cumulative += estimate_tokens(block.content)
+            if not block.checkpoint:
+                continue
+            if cumulative < limits.min_tokens * CLEARLY_BELOW:
+                clearly_short.append((i, cumulative))
+            elif cumulative < limits.min_tokens * UNCERTAIN_UP_TO:
+                borderline.append((i, cumulative))
+                cached_any = cached_any or cumulative >= limits.min_tokens
+            else:
+                cached_any = True
+        for i, prefix in clearly_short:
+            consequence = (
+                "The request succeeds but nothing is cached."
+                if not cached_any and not borderline
+                else "This checkpoint is ignored; later ones may still cache."
+            )
+            findings.append(Finding(
+                "prefix-too-short", "error" if not cached_any and not borderline else "warn",
+                f"Prefix up to this checkpoint is ~{prefix} tokens; {key} needs at least {limits.min_tokens}. {consequence}",
+                req.blocks[i].location,
+            ))
+        for i, prefix in borderline:
+            findings.append(Finding(
+                "prefix-near-minimum", "warn",
+                f"Prefix up to this checkpoint is ~{prefix} tokens (estimate), close to {key}'s minimum of "
+                f"{limits.min_tokens}. Run `cachecanary probe` to confirm it is actually cached.",
+                req.blocks[i].location,
+            ))
+
+    ttls = [req.blocks[i].ttl for i in cps]
+    unknown_ttls = sorted({t for t in ttls if t not in ("5m", "1h")})
+    if unknown_ttls:
+        findings.append(Finding(
+            "ttl-invalid", "error", f"Unsupported TTL value(s) {unknown_ttls}; only '5m' and '1h' exist.",
+        ))
+    if limits and not limits.supports_1h and "1h" in ttls:
+        findings.append(Finding(
+            "ttl-unsupported", "error", f"{key} only supports the 5-minute TTL; 'ttl: 1h' can raise a ValidationException.",
+        ))
+    if "5m" in ttls and "1h" in ttls and ttls.index("5m") < max(i for i, t in enumerate(ttls) if t == "1h"):
+        findings.append(Finding(
+            "ttl-order", "error", "A 1h checkpoint appears after a 5m checkpoint. Longer TTLs must come first.",
+        ))
+
+    last = cps[-1]
+    for block in req.blocks[: last + 1]:
+        for label, pattern in DYNAMIC_PATTERNS.items():
+            if pattern.search(block.content):
+                findings.append(Finding(
+                    "dynamic-in-prefix", "warn",
+                    f"Found {label} text inside the cached prefix. If it changes per request, every call misses.",
+                    block.location,
+                ))
+                break
+
+    tail = len(req.blocks) - 1 - last
+    # Short tails are normal (one new question); only flag history that is re-billed every turn.
+    if tail >= MIN_UNCACHED_TAIL and req.blocks[last].section != "messages":
+        findings.append(Finding(
+            "no-conversation-checkpoint", "warn",
+            f"The last checkpoint is in {req.blocks[last].section}; {tail} conversation blocks after it are "
+            "re-billed every turn. Add a checkpoint near the end of the conversation history.",
+            req.blocks[last].location,
+        ))
+
+    return findings

cachecanary/logs.py

@@ -0,0 +1,129 @@
+"""Aggregate cache hit rates from Bedrock model-invocation logs.
+
+Invocation log records only carry inputTokenCount/outputTokenCount at the top level; the
+cache counts live in output.outputBodyJson (the model response), which is inline only when
+the body is <= 100 KB. Records whose body was offloaded to S3 are counted as 'unparsed'.
+
+Accepted inputs (optionally .gz):
+- S3 delivery: one JSON record per line, or a JSON array of records
+- CloudWatch Logs export to S3: "<ISO timestamp> <json record>" per line
+- `aws logs filter-log-events` output: {"events": [{"message": "<json record>"}, ...]}
+"""
+
+import gzip
+import json
+from collections import defaultdict
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from cachecanary.models import canonical_model_id
+from cachecanary.usage import Usage, from_response
+
+
+@dataclass
+class Group:
+    calls: int = 0
+    unparsed: int = 0
+    usage: Usage = field(default_factory=Usage)
+
+
+@dataclass
+class ReadStats:
+    bad_lines: int = 0
+
+
+def _iter_concatenated(text: str, stats: ReadStats | None):
+    """Records glued together ('{...}{...}') or one per line; skips unreadable fragments."""
+    decoder = json.JSONDecoder()
+    i, n = 0, len(text)
+    while i < n:
+        while i < n and text[i].isspace():
+            i += 1
+        if i >= n:
+            return
+        if text[i] != "{":
+            # CloudWatch export: "<timestamp> {json}" -> skip to the next object start.
+            nxt = text.find("{", i)
+            if nxt == -1:
+                if stats:
+                    stats.bad_lines += 1
+                return
+            i = nxt
+        try:
+            obj, end = decoder.raw_decode(text, i)
+        except json.JSONDecodeError:
+            if stats:
+                stats.bad_lines += 1
+            nl = text.find("\n", i)
+            if nl == -1:
+                return
+            i = nl + 1
+            continue
+        yield obj
+        i = end
+
+
+def iter_records(path: Path, stats: ReadStats | None = None):
+    opener = gzip.open if path.suffix == ".gz" else open
+    with opener(path, "rt", encoding="utf-8") as fh:
+        text = fh.read().strip()
+    if not text:
+        return
+    if text.startswith("["):
+        yield from json.loads(text)
+        return
+    if text.startswith("{"):
+        try:
+            doc = json.loads(text)
+        except json.JSONDecodeError:
+            doc = None
+        if isinstance(doc, dict):
+            if isinstance(doc.get("events"), list):
+                for event in doc["events"]:
+                    try:
+                        yield json.loads(event.get("message", ""))
+                    except (json.JSONDecodeError, AttributeError, TypeError):
+                        if stats:
+                            stats.bad_lines += 1
+                return
+            yield doc
+            return
+    yield from _iter_concatenated(text, stats)
+
+
+def _body(rec: dict):
+    body = (rec.get("output") or {}).get("outputBodyJson")
+    if isinstance(body, str):
+        try:
+            body = json.loads(body)
+        except json.JSONDecodeError:
+            return None
+    return body
+
+
+def _is_invocation_record(rec) -> bool:
+    """Real log records, not offloaded request/response bodies stored next to them in S3."""
+    if not isinstance(rec, dict):
+        return False
+    if rec.get("schemaType") is not None:
+        return rec.get("schemaType") == "ModelInvocationLog"
+    return "modelId" in rec and ("output" in rec or "operation" in rec)
+
+
+def aggregate(records, by: str = "model") -> dict[str, Group]:
+    """Group by 'model', 'principal' or 'model+principal'."""
+    groups: dict[str, Group] = defaultdict(Group)
+    for rec in records:
+        if not _is_invocation_record(rec):
+            continue
+        model = canonical_model_id(rec.get("modelId")) or "?"
+        principal = (rec.get("identity") or {}).get("arn") or "?"
+        key = {"model": model, "principal": principal}.get(by, f"{model} | {principal}")
+        g = groups[key]
+        g.calls += 1
+        usage = from_response(_body(rec))
+        if usage is None:
+            g.unparsed += 1
+            continue
+        g.usage = g.usage + usage
+    return dict(groups)