Metadata-Version: 2.4
Name: aliquot
Version: 0.0.1
Summary: Audit your Anthropic API logs and find the money wasted on broken prompt caching and tool-definition bloat.
Project-URL: Homepage, https://github.com/maryammeda/aliquot
Project-URL: Repository, https://github.com/maryammeda/aliquot
Author-email: Maryam Meda <mm9134@g.rit.edu>
License: MIT
License-File: LICENSE
Keywords: anthropic,audit,claude,cli,cost,llm,prompt-caching
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.11
Requires-Dist: pydantic>=2.7
Requires-Dist: rich>=13.7
Requires-Dist: tiktoken>=0.7
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: hypothesis>=6.100; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Description-Content-Type: text/markdown

# 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.

```bash
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:

```python
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](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

```bash
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
