# Staso Python SDK

Python SDK for the Staso platform. Provides decorator-based tracing
and automatic data ingestion for AI agent observability.

## Project structure

```
src/staso/                 # SDK package
  __init__.py               # Public API (init, shutdown, session, decorators)
  client.py                 # Core client + global state
  config.py                 # Config dataclass
  context.py                # contextvars-based span context
  decorators.py             # @agent, @tool, @trace decorators
  transport.py              # Background batch HTTP transport
  types.py                  # TraceEvent, EventType, Status
  integrations/
    anthropic.py            # Auto-instrumentation for Anthropic SDK
test_codebase/              # Standalone test agent
  agent.py                  # Claude-based support agent using the SDK
```

## Key conventions

- Python >= 3.11 required (uses StrEnum, `X | Y` union syntax)
- `httpx` is the only runtime dependency
- Integrations are optional extras (`pip install staso[anthropic]`)
- The SDK must never crash the host application – all emit paths catch exceptions
- Background transport thread is daemon + atexit-registered for clean shutdown

## Development

```bash
pip install -e ".[dev]"
ruff check src/
mypy src/
pytest
```

## Backend compatibility

Targets the `/v1/traces/ingest` endpoint of the Staso backend.
Auth via `X-API-Key` header. Events batched (max 500 per request).
