# 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, conversation, decorators)
  client.py                 # Core client + global state
  config.py                 # Config dataclass
  context.py                # contextvars-based span context (session_id, user_id)
  decorators.py             # @agent, @tool, @trace decorators
  annotation.py             # st.annotate() — attach evaluations to traces
  provider.py               # Span, Tracer, TracerProvider
  transport.py              # Background batch HTTP transport
  types.py                  # SpanKind, SpanStatus, metadata keys
  integrations/
    anthropic.py            # Auto-instrumentation for Anthropic SDK
    openai.py               # Auto-instrumentation for OpenAI SDK
    _streaming.py           # Anthropic streaming proxies
    _openai_streaming.py    # OpenAI streaming proxies
test_codebase/              # Standalone integration test agent
  agent.py                  # Multi-provider support agent (Anthropic / OpenAI)
```

## 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]`, `staso[openai]`)
- 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]"
uv run pytest tests/ -v
```

## Running the integration test agent

The test agent in `test_codebase/agent.py` exercises all SDK features against a live backend.
It supports both Anthropic and OpenAI providers via the `PROVIDER` setting.

Config is loaded from `test_codebase/.env` (recommended) or environment variables.

```bash
cd test_codebase

# Install deps
pip install -e "..[anthropic,openai]"
pip install -r requirements.txt

# Create .env file with your config
cat > .env << 'EOF'
PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
STASO_API_KEY=ak_...
STASO_BASE_URL=http://localhost:6999
STASO_ENVIRONMENT=dev
STASO_WORKSPACE_SLUG=staging
EOF

# Run (reads from .env automatically)
python agent.py
```

Switch providers by changing `PROVIDER=openai` in `.env`. Default models: `claude-haiku-4-5` (Anthropic), `gpt-4o-mini` (OpenAI).

## Backend compatibility

Targets the `/v1/traces/ingest` and `/v1/traces/{trace_id}/annotations` endpoints.
Auth via `X-API-Key` header. Spans batched (max 500 per request). Annotations sent directly (not batched).
