waterlight 0.2.1

Waterlight AI SDK — OpenAI-compatible client for the Waterlight API

Waterlight Python SDK

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

Install

pip install waterlight

Quick Start

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:

# 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

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

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

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

Models

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

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

Error Handling

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

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