# Beaver AI Python SDK v0.2.0

Comprehensive Python SDK for the Beaver AI Gateway. Fully OpenAI-compatible with dot notation access and support for all major endpoints.

## Installation

```bash
pip install beaver-ai
```

## Quick Start (v0.2.0+)

### Initializing the Client

```python
from beaver_ai import Beaver

beaver = Beaver(api_key="your-api-key")
# Defaults to https://api.beaverai.cloud/v1
```

### Chat Completions

Dot notation is now the standard for accessing response data.

#### Non-Streaming

```python
response = beaver.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}],
    stream=False
)

print(response.choices[0].message.content)
print(f"Tokens used: {response.usage.total_tokens}")
```

#### Streaming (Default)

```python
stream = beaver.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Tell me a story."}]
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)
```

### Image Generation

```python
img = beaver.images.generate(
    model="dall-e-3",
    prompt="A futuristic beaver building a dam of fiber optics"
)

print(img.data[0].url)
```

### Embeddings

```python
emb = beaver.embeddings.create(
    model="text-embedding-3-small",
    input="The quick brown fox jumps over the lazy dog"
)

print(f"Dimensions: {len(emb.data[0].embedding)}")
```

### Audio (Text-to-Speech)

```python
audio_bytes = beaver.audio.speech.create(
    model="tts-1",
    voice="alloy",
    input="Hello from the Beaver SDK!"
)

with open("speech.mp3", "wb") as f:
    f.write(audio_bytes)
```

## Advanced Configuration

### Custom Base URL

```python
beaver = Beaver(
    api_key="your-api-key",
    base_url="https://your-private-gateway.com/v1"
)
```

### Parameters

The SDK now standardizes on `max_tokens` for all providers. `max_output_tokens` is supported as a legacy alias but is deprecated.

## Error Handling

The SDK raises `BeaverError` for API failures.

```python
from beaver_ai import Beaver, BeaverError

try:
    beaver.chat.completions.create(...)
except BeaverError as e:
    print(f"Error {e.status}: {e.message} (Code: {e.code})")
```

## License

MIT
