# Waterlight Python SDK

OpenAI-compatible Python client for the Waterlight API. Zero external dependencies.

## Install

```bash
pip install waterlight
```

## Quick Start

```python
from waterlight import Waterlight

client = Waterlight(api_key="wl-...")

response = client.chat.completions.create(
    model="mist-1-turbo",
    messages=[{"role": "user", "content": "Hello!"}],
)
print(response.choices[0].message.content)
```

## Drop-in OpenAI Replacement

Change two lines:

```python
# Before
from openai import OpenAI
client = OpenAI(api_key="sk-...")

# After
from waterlight import Waterlight
client = Waterlight(api_key="wl-...")

# Everything else stays the same
response = client.chat.completions.create(
    model="mist-1-turbo",
    messages=[{"role": "user", "content": "Explain quantum computing"}],
)
```

## Streaming

```python
stream = client.chat.completions.create(
    model="mist-1-turbo",
    messages=[{"role": "user", "content": "Tell me a story"}],
    stream=True,
)
for chunk in stream:
    content = chunk.choices[0].delta.content
    if content:
        print(content, end="", flush=True)
```

## Tool Calling

```python
tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Get the weather for a location",
        "parameters": {
            "type": "object",
            "properties": {
                "location": {"type": "string"},
            },
            "required": ["location"],
        },
    },
}]

response = client.chat.completions.create(
    model="mist-1-turbo",
    messages=[{"role": "user", "content": "What's the weather in Tokyo?"}],
    tools=tools,
)
```

## Embeddings

```python
response = client.embeddings.create(input="Hello world")
print(len(response.data[0].embedding))
```

## Models

```python
models = client.models.list()
for model in models.data:
    print(model.id)
```

## Available Models

| Model | Best For |
|-------|----------|
| `mist-1` | Highest quality reasoning and analysis |
| `mist-1-turbo` | Fast, high quality all-rounder |
| `mist-1-flash` | Fastest responses, triage, summarization |
| `mist-1-reason` | Deep reasoning and math |
| `mist-1-code` | Code generation and review |
| `mist-1-vision` | Multimodal / image understanding |

## Billing

```python
billing = client.billing.get()
print(billing)  # plan, spent_usd, balance, limits
```

## Error Handling

```python
from waterlight import (
    AuthenticationError,
    RateLimitError,
    InsufficientCreditsError,
    APIError,
)

try:
    response = client.chat.completions.create(
        model="mist-1-turbo",
        messages=[{"role": "user", "content": "Hello"}],
    )
except AuthenticationError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Rate limited — retry after {e.retry_after}s")
except InsufficientCreditsError:
    print("Add credits at https://waterlight.io")
except APIError as e:
    print(f"API error {e.status_code}: {e.message}")
```

## Configuration

| Parameter | Env Var | Default |
|-----------|---------|---------|
| `api_key` | `WATERLIGHT_API_KEY` | — (required) |
| `base_url` | `WATERLIGHT_BASE_URL` | `https://api.waterlight.io` |
| `timeout` | — | `120.0` |
| `max_retries` | — | `2` |

```python
client = Waterlight(
    api_key="wl-...",           # or set WATERLIGHT_API_KEY env var
    base_url="https://...",     # or set WATERLIGHT_BASE_URL env var
    timeout=120.0,              # request timeout in seconds
    max_retries=2,              # retries on transient errors
)
```

## Requirements

- Python 3.9+
- No external dependencies

## License

MIT
