aliquot 0.0.1

Audit your Anthropic API logs and find the money wasted on broken prompt caching and tool-definition bloat.

Aliquot

Audit your Anthropic API logs and find the money you're wasting on broken prompt caching and tool-definition bloat.

Status: pre-alpha (Phase 0 — setup). Not yet functional.

pip install aliquot          # coming soon
aliquot audit ./logs.jsonl

SCANNED: 12,847 requests over 7 days
TOTAL SPEND: $1,247
ESTIMATED WASTE: up to $782 (likely $620-780)  [63%]

ISSUE 1: Cache miss on system prompt [saves up to $412/mo, likely $340-410]
  ...with the math to back it up.

Aliquot (chemistry): a portion taken from a whole for analysis. Your audit logs are the aliquot of your full AI usage.

What it does

Reads raw Anthropic JSON logs and produces a markdown report showing, with the math:

1. Broken prompt caching — where cache_control breakpoints are missing, misplaced, or silently invalidated, and what relocating them would save.
2. MCP / tool-definition bloat — tools loaded on every request but rarely or never called, and the savings from trimming them.

Read-only. Never modifies your code or sends data anywhere.

Getting your logs

Aliquot reads raw Anthropic request+response records (one JSON object per line). Anthropic doesn't hand you these — the usage cache fields only come back in each API response at call time, so you capture them yourself. The easiest way is to log your calls as you make them:

from examples.capture_logs import logged_create  # 3-line wrapper around messages.create

logged_create(client, model="claude-opus-4-8", max_tokens=512,
              system=SYSTEM, messages=messages)   # appends to anthropic_logs.jsonl

Then aliquot audit ./anthropic_logs.jsonl. See examples/capture_logs.py for the full snippet (model, system, messages, tools, and the response usage). If you already log your Claude calls, point Aliquot at those — it needs the request (system/messages/tools) and the response usage. Logs from wrappers like LangChain aren't supported in v1; you'll get a clear error rather than a wrong answer.

How the cache detector works

(Diagram + write-up coming — Phase 11. Short version: tokenize each request, build a prefix trie across all requests, cluster by structural template shape to find variable slots, classify the cache failure mode, and project savings validated by a replay harness against simulated cache behavior.)

Scope (v1)

• One log format: raw Anthropic JSON.
• One provider: Anthropic. (OpenAI/Gemini are v2 — caching semantics differ.)
• CLI + markdown report. No dashboard, no server, no cloud.

Development

uv pip install -e ".[dev]"
ruff check . && mypy && pytest

All pricing/TTL/cache constants live in src/aliquot/pricing.py with a LAST_VERIFIED date; CI fails if it's more than 60 days old.

License

MIT