matts-starter-prefactor 0.1.0
Anthropic SDK wrapper with observability and tracing (Python)
License: MIT
Requires Python: >=3.8
Keywords: observability, tracing, anthropic, claude, llm, monitoring

# Prefactor Anthropic SDK (Python)

Python wrapper for the Anthropic SDK with built-in Prefactor observability and tracing.

## Installation

```bash
pip install prefactor-anthropic
```

## Quick Start

```python
from anthropic import Anthropic
from prefactor_anthropic import wrap_anthropic_client, shutdown

# Create your Anthropic client
client = Anthropic(api_key="your-anthropic-api-key")

# Wrap it with Prefactor observability
wrapped_client = wrap_anthropic_client(client, {
    "api_token": "your-prefactor-token",
    "agent_id": "your-agent-id"
})

# Use it like normal - all calls are automatically tracked
response = wrapped_client.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Hello, Claude!"}
    ]
)

print(response.content[0].text)

# Gracefully shutdown and flush telemetry
shutdown()
```

## Configuration

### Simple Configuration

```python
wrapped_client = wrap_anthropic_client(client, {
    "api_url": "https://api.prefactor.ai",  # Optional, defaults to env var
    "api_token": "your-token",               # Required
    "agent_id": "your-agent-id",             # Optional
    "max_input_messages": 10,                # Limit message history in spans
    "max_output_content_length": 1000,       # Truncate long outputs
})
```

### Advanced Configuration

```python
wrapped_client = wrap_anthropic_client(client, {
    "prefactor_config": {
        "transport_type": "http",
        "http_config": {
            "api_url": "https://api.prefactor.ai",
            "api_token": "your-token",
            "agent_id": "your-agent-id",
            "agent_identifier": "my-agent-v1",
            "agent_name": "My Custom Agent",
            "agent_description": "Custom agent for X task"
        }
    }
})
```

### Environment Variables

You can also configure using environment variables:

```bash
export PREFACTOR_API_URL=https://api.prefactor.ai
export PREFACTOR_API_TOKEN=your-token
export PREFACTOR_AGENT_ID=your-agent-id
```

Then:

```python
# Config will be loaded from environment
wrapped_client = wrap_anthropic_client(client)
```

## Features

- ✅ **Automatic tracing** - All Anthropic API calls are tracked
- ✅ **Token usage tracking** - Input/output tokens recorded
- ✅ **Streaming support** - Works with streaming responses
- ✅ **Error tracking** - Captures and reports errors
- ✅ **Configurable limits** - Control message history and output length
- ✅ **Type hints** - Full typing support with TypedDict

## Streaming Example

```python
stream = wrapped_client.messages.stream(
    model="claude-sonnet-4-5-20250929",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Tell me a story"}]
)

for event in stream:
    if hasattr(event, 'delta') and hasattr(event.delta, 'text'):
        print(event.delta.text, end='', flush=True)

shutdown()
```

## API Reference

### `wrap_anthropic_client(client, config=None)`

Wraps an Anthropic client with Prefactor observability.

**Parameters:**
- `client` (Anthropic): The Anthropic client to wrap
- `config` (PrefactorAnthropicConfig, optional): Configuration options

**Returns:**
- `AnthropicWrapper`: Wrapped client with observability

### `shutdown()`

Gracefully shuts down the Prefactor SDK and flushes pending telemetry data.

## Development

```bash
# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest

# Type checking
mypy src/
```

## License

MIT

## Links

- [Prefactor Documentation](https://docs.prefactor.ai)
- [Anthropic SDK](https://github.com/anthropics/anthropic-sdk-python)
- [GitHub Repository](https://github.com/prefactordev/prefactor-anthropic-python)