triage-sdk 0.1.0
Triage SDK — security-focused observability for AI agents
Requires Python: >=3.10

# Triage Python SDK

Security-focused observability for AI agents. Automatically captures LLM traces with security context for 37+ providers including OpenAI, Anthropic, Cohere, Bedrock, and more.

## Installation

```bash
pip install triage-sdk
```

## Quick Start

```python
import triage_sdk

triage_sdk.init(api_key="tsk_...")

# That's it — all LLM calls are now automatically traced.
# Optionally, annotate traces with application context:
triage_sdk.set_user(user_id="user_123", role="admin")
triage_sdk.set_tenant(tenant_id="org_456", name="Acme Corp")
```

## Configuration

### `init()` Parameters

```python
triage_sdk.init(
    api_key="tsk_...",            # Required (or set TRIAGE_API_KEY env var)
    app_name="my-agent",          # Identifies your application
    environment="production",     # e.g. development, staging, production
    endpoint="https://...",       # Triage API endpoint (default: https://api.triageai.dev)
    enabled=True,                 # Kill switch to disable tracing
    trace_content=True,           # Capture prompt/completion content
    instruments={...},            # Allowlist specific LLM providers
    block_instruments={...},      # Blocklist specific LLM providers
)
```

All parameters except `api_key` have sensible defaults. Configuration resolves in order: **explicit argument > environment variable > default**.

### Environment Variables

| Variable | Description | Default |
|---|---|---|
| `TRIAGE_API_KEY` | API key for trace ingestion | *required* |
| `TRIAGE_ENDPOINT` | Triage API endpoint URL | `https://api.triageai.dev` |
| `TRIAGE_APP_NAME` | Application name | Inferred from `sys.argv[0]` |
| `TRIAGE_ENVIRONMENT` | Environment tag | `development` |
| `TRIAGE_ENABLED` | Enable/disable SDK (`true`/`false`) | `true` |
| `TRIAGE_TRACE_CONTENT` | Capture prompt/completion content | `true` |

## Context Helpers

Annotate your traces with application-level metadata. Context propagates automatically to all subsequent LLM calls in the current execution context (thread-safe and async-safe).

### `set_user` — User Identity

```python
triage_sdk.set_user(user_id="user_123", role="admin")
```

### `set_tenant` — Organization/Tenant

```python
triage_sdk.set_tenant(tenant_id="org_456", name="Acme Corp")
```

### `set_session` — Conversation Session

```python
triage_sdk.set_session(
    session_id="sess_789",
    turn_number=3,
    history_hash="abc123",
)
```

### `set_input` — User Input

```python
triage_sdk.set_input(
    raw="What's my SSN?",
    sanitized="What's my [REDACTED]?",
)
```

### `set_template` — Prompt Template

```python
triage_sdk.set_template(template_id="summarize-v2", version="1.3")
```

### `set_chunk_acls` — Retrieved Chunk Access Control

```python
triage_sdk.set_chunk_acls([
    {"chunk_id": "c1", "source": "internal-docs", "clearance": "confidential"},
])
```

## Scoped Context

Use `triage_sdk.context()` to set context for a specific block. Previous context is automatically restored on exit, and unset fields inherit from the outer scope:

```python
triage_sdk.set_user(user_id="user_123")

with triage_sdk.context(tenant_id="org_456"):
    # user_id="user_123" is still active here
    call_llm(...)  # traced with both user and tenant

# tenant_id is no longer active here
call_llm(...)  # traced with only user
```

## Shutdown

The SDK registers an `atexit` handler to flush pending spans automatically. You can also shut down manually:

```python
triage_sdk.shutdown()
```

## Requirements

- Python 3.10+

## License

MIT