Metadata-Version: 2.4
Name: zolks
Version: 0.3.0
Summary: Cost observability for AI agents
Project-URL: Homepage, https://zolks.vercel.app
Project-URL: Repository, https://github.com/vikramansen/zolks-python
Project-URL: Issues, https://github.com/vikramansen/zolks-python/issues
Author: Vikraman Senthil Kumar
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: httpx>=0.27; 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'
Requires-Dist: starlette>=0.37; extra == 'dev'
Requires-Dist: uvicorn[standard]>=0.29; extra == 'dev'
Provides-Extra: proxy
Requires-Dist: httpx>=0.27; extra == 'proxy'
Requires-Dist: starlette>=0.37; extra == 'proxy'
Requires-Dist: uvicorn[standard]>=0.29; extra == 'proxy'
Description-Content-Type: text/markdown

# Zolks

Local-first cost observability for AI tools. Open source, Python.

Two ways to capture AI API spend.

## Fastest first run

```bash
pip install 'zolks[proxy]'
export ANTHROPIC_API_KEY=sk-ant-...
zolks try
```

## Option 1 — The proxy (for CLI tools: Claude Code, Aider, Cursor, etc.)

```bash
pip install 'zolks[proxy]'
zolks proxy start
```

In another terminal:

```bash
export ANTHROPIC_BASE_URL=http://127.0.0.1:9191
claude-code "refactor this file"
aider
```

Then:

```bash
$ zolks top
agent               runs   tokens    cost     trend
claude-code         14     284K      $2.18    new
aider               3      42K       $0.31    new
python-sdk          21     119K      $0.94    new
```

## Option 2 — The SDK (for Python apps you own)

```bash
pip install zolks
```

```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-opus-4-7", messages=[...])
```

The same `zolks top` command shows SDK and proxy events side by side.

## How it works

The proxy is a local HTTP server that forwards Anthropic API calls and captures tokens,
latency, and cost per request. Tools are identified by User-Agent. All data stays on your
machine in `~/.zolks/events.db`.

The SDK monkey-patches `anthropic.Anthropic` and tags calls with whatever `zolks.tag(...)`
context is active.

## Commands

- `zolks proxy start` — run the local proxy
- `zolks try` — one-command proxy + real Anthropic smoke test
- `zolks top` — top agents/users/features by cost
- `zolks stats` — totals for a time window
- `zolks tail` — live stream of new events

## Status

`0.3.0` — First release with a stable schema. Captures Anthropic API calls through either
the local proxy or the Python SDK. Local SQLite storage with exact-precision cost tracking
(nanodollars). Cloud sync planned for 0.4.

Streaming calls are captured as events without token counts (coming in 0.4). OpenAI support
coming.

Roadmap: OpenAI -> streaming token capture -> anomaly detection -> hosted team dashboard.

## License

MIT
