auriko 0.1.0b3

Auriko API client - Intelligent LLM routing

Auriko Python SDK

Type-safe Python SDK for the Auriko intelligent LLM routing API.

Overview

Auriko provides a unified API for accessing multiple LLM providers with intelligent routing based on cost, latency, throughput, and availability. The API is fully compatible with OpenAI's Chat Completions API.

Two ways to use Auriko:

1. OpenAI SDK (drop-in) — change base_url and api_key, everything else works as-is
2. Auriko SDK (native) — typed access to Auriko-specific features: multi-model routing, routing metadata, cost tracking, and more

Installation

pip install auriko

Quick Start with OpenAI SDK

import openai

client = openai.OpenAI(
    base_url="https://api.auriko.ai/v1",
    api_key="your-api-key",  # or set AURIKO_API_KEY env var
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "What is inference arbitrage?"}],
)
print(response.choices[0].message.content)

Quick Start with Auriko SDK

from auriko import Client

client = Client(api_key="your-api-key")  # or set AURIKO_API_KEY env var

# Non-streaming
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}],
)
print(response.choices[0].message.content)

# Streaming
stream = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}],
    stream=True,
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

Async

import asyncio
from auriko import AsyncClient

async def main():
    client = AsyncClient(api_key="your-api-key")
    response = await client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": "Hello!"}],
    )
    print(response.choices[0].message.content)

asyncio.run(main())

Authentication

Set AURIKO_API_KEY as an environment variable, or pass it directly:

client = Client(api_key="sk-auriko-...")

The SDK looks for the API key in this order:

1. api_key argument
2. AURIKO_API_KEY environment variable
3. Raises AuthenticationError

Auriko Extensions

Beyond OpenAI compatibility, the Auriko SDK provides:

Multi-model routing

response = client.chat.completions.create(
    messages=[{"role": "user", "content": "Hello!"}],
    gateway={
        "models": ["gpt-4o", "claude-3-5-sonnet", "deepseek-chat"],
        "routing": {"optimize": "cost"},
    },
)

Routing metadata

stream = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}],
    stream=True,
)
for chunk in stream:
    pass  # consume stream

print(stream.routing_metadata)  # provider, model, latency, cost
print(stream.usage)             # token counts

Reasoning effort

response = client.chat.completions.create(
    model="claude-3-5-sonnet",
    messages=[{"role": "user", "content": "Think step by step."}],
    reasoning_effort="high",
)

Provider extensions

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}],
    extensions={"openai": {"logit_bias": {"1234": -100}}},
)

Strict parameter routing

Only route to providers that support the optional parameters you sent:

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}],
    seed=42,
    gateway={"routing": {"require_parameters": True}},
)

See Filter by parameter support for the full list of parameters this applies to.

Available Resources

Resource	Methods	Auth
client.chat.completions	create()	API key
client.models	list_directory(), list_registry(), list_providers()	Public
client.me	get()	API key

Configuration

client = Client(
    api_key="sk-auriko-...",           # default: AURIKO_API_KEY env var
    base_url="https://api.auriko.ai/v1",  # default
    timeout=60.0,                      # seconds, default: 60
    max_retries=2,                     # default: 2
)

Retries

The SDK retries automatically when both conditions hold:

• error.type is rate_limit_error or api_error
• error.code is NOT budget_exhausted, insufficient_quota, or internal_error

Network failures (DNS, connection refused, timeout) retry under a separate rule and surface as APIConnectionError after the last attempt.

Retry uses exponential backoff (0.5s base, 1.5x multiplier, 30s cap) with jitter and respects Retry-After headers.

Error Handling

from auriko import Client
from auriko.errors import (
    AurikoAPIError,
    AuthenticationError,
    BadRequestError,
    RateLimitError,
)

client = Client()
try:
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": "Hello!"}],
    )
except AuthenticationError:
    print("Invalid API key")
except BadRequestError as e:
    print(f"Bad request ({e.code}): {e.message}")
except RateLimitError as e:
    if e.code == "budget_exhausted":
        print("Budget limit reached")
    else:
        print("Rate limited — retries exhausted")
except AurikoAPIError as e:
    print(f"API error {e.status_code} ({e.code}): {e.message}")

Error classes

All errors inherit from AurikoAPIError. Dispatch is HTTP-status-driven; use .code for fine-grained branching.

Error	HTTP status	Description
BadRequestError	400, 413	Invalid request parameters
AuthenticationError	401	Invalid or missing API key
PermissionDeniedError	403	Feature disabled or insufficient permissions
NotFoundError	404	Resource or model not found
ConflictError	409	Idempotency-key conflict
RateLimitError	429	Rate limit, quota, or budget exhausted
InternalServerError	500	Internal gateway error
APIStatusError	502, 503, 504	Upstream/gateway unavailable
APIConnectionError	—	No response received (network/DNS/timeout)

Resource Management

Use the client as a context manager to ensure connections are properly closed:

with Client() as client:
    response = client.chat.completions.create(...)

# Async
async with AsyncClient() as client:
    response = await client.chat.completions.create(...)

Development

Status

This SDK is in beta. There may be breaking changes between minor versions. We recommend pinning to a specific version.

Dependencies

• httpx >=0.28.1 — HTTP client
• pydantic >=2.11.2 — Response models
• anyio >=4.0.0 — Async backoff

Requirements

Python 3.10+