Metadata-Version: 2.4
Name: trakr-monitor
Version: 0.1.0
Summary: AI agent cost and failure monitoring — Sentry for AI agents
Project-URL: Homepage, https://trakr.run/docs/python
Project-URL: Documentation, https://trakr.run/docs/python
License: MIT
Requires-Python: >=3.9
Requires-Dist: httpx>=0.24.0
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.25.0; extra == 'anthropic'
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: hatchling>=1.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == 'openai'
Description-Content-Type: text/markdown

# trakr-monitor

Observability SDK for AI agent workflows. Automatically captures Anthropic and OpenAI LLM calls with cost, tokens, latency, and tool use — sent to your [Trakr](https://trakr.run) dashboard.

> **Coming soon on PyPI** — not published yet. Use [`@trakr/monitor`](https://www.npmjs.com/package/@trakr/monitor) on npm for production today.

## Install (when published)

```bash
pip install trakr-monitor

# With Anthropic auto-instrumentation
pip install trakr-monitor[anthropic]

# With OpenAI auto-instrumentation
pip install trakr-monitor[openai]
```

## Quick start

```python
import trakr_monitor as trakr
import anthropic

trakr.init()  # reads TRAKR_API_KEY

client = anthropic.Anthropic()

with trakr.start_run("daily-report") as run:
    client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=256,
        messages=[{"role": "user", "content": "Summarize logs"}],
    )

trakr.flush()  # blocking — call before sys.exit() in scripts
```

## Decorator pattern

```python
import trakr_monitor as trakr

trakr.init()

@trakr.track_agent(name="invoice-extractor")
def extract_invoice(document: str) -> dict:
    return do_extraction(document)
```

Async functions are supported:

```python
@trakr.track_agent(name="async-processor")
async def process_async(data: str) -> str:
    return await call_llm(data)
```

## Configuration

| Option | Default | Description |
|--------|---------|-------------|
| `api_key` | `TRAKR_API_KEY` env | SDK API key (`tk_live_...`) |
| `endpoint` | `https://app.trakr.run/api/ingest` | Ingest URL override |
| `batch_size` | `10` | Events per upload batch |
| `flush_interval_seconds` | `2.0` | Max time between uploads |
| `loop_detection_threshold` | `5` | Consecutive same-tool calls before `loop_detected` |
| `disabled` | `False` | Disable all instrumentation |
| `debug` | `False` | Log SDK activity to stdout |

## Local development

```python
import os
import trakr_monitor as trakr

trakr.init(
    api_key="tk_live_testkey00000000000000000000000000",
    endpoint=os.environ.get("TRAKR_INGEST_URL", "http://localhost:3000/api/ingest"),
)
```

## API

```python
trakr.init(...)
trakr.start_run(workflow_name, ...) -> Run  # context manager
trakr.track_agent(name, metadata=None)    # decorator
trakr.flush()                             # blocking flush
trakr.disable()

run.end(status="success" | "error", error_message=None)
run.set_metadata(key, value)
```

## Tests

```bash
cd libs/sdk/python
pip install -e ".[dev]"
python -m pytest
python -m build
```

## Documentation

- [Getting started](https://trakr.run/docs/getting-started)
- [Python SDK](https://trakr.run/docs/python)
- [Ingest API](https://trakr.run/docs/api)

## Support

Questions or issues: [support@trakr.run](mailto:support@trakr.run)

## License

MIT
