Metadata-Version: 2.4
Name: agentmetrics
Version: 0.1.0
Summary: Observability SDK for Claude Agent SDK - metrics, tracing, and debugging for AI agents
Project-URL: Homepage, https://github.com/yourusername/agentmetrics
Project-URL: Documentation, https://github.com/yourusername/agentmetrics#readme
Project-URL: Repository, https://github.com/yourusername/agentmetrics
Project-URL: Issues, https://github.com/yourusername/agentmetrics/issues
Author-email: Your Name <you@example.com>
License-Expression: MIT
Keywords: agents,ai,anthropic,claude,metrics,observability,tracing
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.10
Provides-Extra: aiohttp
Requires-Dist: aiohttp>=3.8.0; extra == 'aiohttp'
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.0.270; extra == 'dev'
Provides-Extra: full
Requires-Dist: aiohttp>=3.8.0; extra == 'full'
Requires-Dist: claude-agent-sdk>=0.1.3; extra == 'full'
Provides-Extra: httpx
Requires-Dist: httpx>=0.24.0; extra == 'httpx'
Provides-Extra: requests
Requires-Dist: requests>=2.28.0; extra == 'requests'
Provides-Extra: sdk
Requires-Dist: claude-agent-sdk>=0.1.3; extra == 'sdk'
Description-Content-Type: text/markdown

# AgentMetrics

**Observability for AI Agents. Open spec. Self-host or use our platform.**

Drop-in replacement for `claude_agent_sdk.query()` that adds metrics, tracing, and cost tracking.

```python
# Before
from claude_agent_sdk import query

# After (that's it)
from agentmetrics import query
```

---

## Why?

You built an agent. It works locally. Now what?

- **Where do I see what it did?** → AgentMetrics logs every tool call, duration, and token usage
- **How much is this costing me?** → Automatic cost estimation per run
- **Why did it fail?** → Full traces with inputs and outputs
- **Where do I deploy this?** → Start local, self-host when ready, or use our platform

---

## Quick Start

### Install

```bash
pip install agentmetrics

# Also need the Claude Agent SDK
pip install claude-agent-sdk
```

### Use

```python
import asyncio
from agentmetrics import query
from claude_agent_sdk import ClaudeAgentOptions

async def main():
    options = ClaudeAgentOptions(
        allowed_tools=["WebSearch", "Read", "Write"],
        permission_mode="acceptEdits",
    )
    
    async for message in query(
        prompt="Research the latest AI agent frameworks",
        options=options,
        agent_id="my-research-agent",  # Optional: group runs
    ):
        print(message)

asyncio.run(main())
```

That's it. You'll see a summary printed after each run:

```
============================================================
📊 AGENT RUN SUMMARY
============================================================
Run ID:     550e8400-e29b-41d4-a716-446655440000
Agent:      my-research-agent
Status:     completed
Duration:   12340ms
Model:      claude-sonnet-4-5-20250929
Tokens:     15,230 in / 3,200 out
Est. Cost:  $0.0936

📦 Tool Usage:
  • WebSearch: 3x (1200ms) [✓]
  • Read: 2x (50ms) [✓]
  • Write: 1x (30ms) [✓]
============================================================
```

---

## Configuration

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `AGENT_METRICS_URL` | HTTP endpoint to send metrics | None (console mode) |
| `AGENT_METRICS_API_KEY` | API key for authentication | None |
| `AGENT_METRICS_AGENT_ID` | Default agent ID | None |
| `AGENT_METRICS_DISABLED` | Set to "true" to disable | false |
| `AGENT_METRICS_STREAMING` | Real-time event streaming | false |

### Programmatic Configuration

```python
from agentmetrics import configure

configure(
    endpoint_url="https://your-receiver.com",
    api_key="your-api-key",
    agent_id="default-agent-id",
    include_trace=True,
    include_prompt=False,
)
```

---

## Output Modes

### Console (Default)

No config needed. Prints summary to stdout. Great for local development.

### HTTP

Set `AGENT_METRICS_URL` to send data to a receiver:

```bash
export AGENT_METRICS_URL=https://your-receiver.com/v1/runs
export AGENT_METRICS_API_KEY=your-key
```

### Disabled

```bash
export AGENT_METRICS_DISABLED=true
```

---

## Alternative Usage Patterns

### Wrapper Function

Keep using `claude_agent_sdk.query()` directly:

```python
from claude_agent_sdk import query
from agentmetrics import tracked_query

async for message in tracked_query(
    query(prompt="...", options=options),
    agent_id="my-agent"
):
    print(message)
```

### Context Manager

For fine-grained control:

```python
from claude_agent_sdk import query
from agentmetrics import track_run

async with track_run(agent_id="my-agent") as tracker:
    async for message in query(prompt="...", options=options):
        tracker.process_message(message)
        # Custom processing here
```

---

## Self-Hosting

We provide a reference receiver implementation. It's yours to run, modify, or learn from.

### Quick Start

```bash
cd receiver
pip install fastapi uvicorn
python receiver.py
```

The receiver runs at `http://localhost:8080`. Point your SDK at it:

```bash
export AGENT_METRICS_URL=http://localhost:8080
```

### What You Get

- SQLite storage (swap for Postgres, ClickHouse, etc.)
- REST API for querying data
- Ready for Grafana dashboards

### API Spec

See [spec/API.md](spec/API.md) for the full API contract. Build your own receiver if you want.

---

## Data Model

### AgentRun

```json
{
  "run_id": "uuid",
  "agent_id": "my-agent",
  "status": "completed",
  "duration_ms": 12340,
  "tokens": {"input": 15230, "output": 3200},
  "estimated_cost_usd": 0.0936,
  "tool_calls": [
    {"tool": "WebSearch", "count": 3, "total_duration_ms": 1200}
  ],
  "events": [/* full trace */]
}
```

### RunEvent

```json
{
  "event_id": "uuid",
  "type": "tool_call",
  "timestamp": "2025-01-15T10:30:00Z",
  "tool_name": "WebSearch",
  "tool_input": {"query": "AI agents"},
  "tool_duration_ms": 400,
  "tool_success": true
}
```

---

## Roadmap

- [ ] Dashboard UI
- [ ] Alerting (cost thresholds, error rates)
- [ ] Hosted platform
- [ ] Support for other agent frameworks (LangGraph, CrewAI)
- [ ] Replay/debugging tools

---

## Philosophy

1. **Open spec** — The API contract is public. Build your own receiver, use ours, or switch later.
2. **No lock-in** — Remove AgentMetrics and your agent still works. It's just a wrapper.
3. **Start simple** — Console output by default. Add infrastructure as you need it.

---

## License

MIT

---

## Contributing

Issues and PRs welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).