zolks 0.1.0

Cost observability for AI agents

zolks

Cost observability for AI agent apps.

pip install zolks anthropic

Quick start

uv run python examples/live_demo.py

Minimal usage

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:

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

zolks top
zolks stats
zolks tail

Tests

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