# zappybee

ZappyBee observability SDK for AI agents (Python). Track traces, steps, token usage, and costs.

## Install

```bash
pip install zappybee
```

## Quick Start

```python
import os
from zappybee import ZappyBee

ZappyBee.init(
    api_key=os.getenv("ZAPPYBEE_API_KEY", "tc_live_..."),
    # Optional. Defaults to http://localhost:3001
    base_url=os.getenv("ZAPPYBEE_BASE_URL"),
)
```

## Manual Tracing

```python
from zappybee import ZappyBee

trace = await ZappyBee.start_trace(
    "my-agent",
    user_id="user-123",
    session_id="session-abc",
    input={"prompt": "Hello"},
)

step = await trace.start_step(
    "LLM Call",
    "llm_call",
    model="gpt-4o",
    input={"messages": [{"role": "user", "content": "Hello!"}]},
)

# ... your LLM call here ...

await step.end(
    status="success",
    model="gpt-4o",
    output={"role": "assistant", "content": "Hello!"},
    prompt_tokens=10,
    completion_tokens=20,
)

await trace.end(status="success")
```

## Auto-Instrumentation (OpenAI / Anthropic)

```python
from zappybee import ZappyBee

client = ZappyBee.wrap(openai_client)      # wraps chat.completions.create()
client = ZappyBee.wrap(anthropic_client)   # wraps messages.create()
```

The wrapper supports both non-stream and stream calls (when the client exposes an async iterator).

## Backwards Compatibility

If you previously used `tokencat`, it is still available:

```python
from tokencat import TokenCat

TokenCat.init(api_key="tc_live_...")
```

## License

MIT

