Metadata-Version: 2.4
Name: zolks
Version: 0.1.0
Summary: Cost observability for AI agents
Author: Vikraman Selvaraj
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: click>=8.1
Requires-Dist: rich>=13.7
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.30; extra == 'anthropic'
Provides-Extra: dev
Requires-Dist: anthropic==0.51.0; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# zolks

Cost observability for AI agent apps.

```bash
pip install zolks anthropic
```

## Quick start

```bash
uv run python examples/live_demo.py
```

## Minimal usage

```python
import zolks
zolks.init()

from anthropic import Anthropic
client = Anthropic()

with zolks.tag(agent="refund-bot", user_id="user_123"):
    client.messages.create(
        model="claude-haiku-4-5",
        max_tokens=20,
        messages=[{"role": "user", "content": "hi"}],
    )
```

Then:

```bash
zolks top --group-by agent
```

If you see `untagged`, your calls are not tagged yet.

## What it does

Zolks monkey-patches Anthropic `messages.create()` calls, captures tokens/latency/cost,
and writes events to `~/.zolks/events.db` (SQLite, local-first). Use `tag(...)` or
`track(...)` to attribute spend to agents/users/features.

## Commands

```bash
zolks top
zolks stats
zolks tail
```

## Tests

```bash
./scripts/test.sh
```

## Status

`0.1.0` — Anthropic only, SQLite only, no cloud yet.
Roadmap in `ROADMAP.md`.
Known limitations are tracked in `KNOWN_LIMITATIONS.md`.

## License

MIT
