Metadata-Version: 2.4
Name: auriko
Version: 0.1.0b1
Summary: Auriko API client - Intelligent LLM routing
Author: Auriko
License: Apache-2.0
Project-URL: Homepage, https://docs.auriko.ai
Project-URL: Repository, https://github.com/auriko-ai/auriko-sdk-python
Project-URL: Documentation, https://docs.auriko.ai
Project-URL: Changelog, https://github.com/auriko-ai/auriko-sdk-python/blob/main/CHANGELOG.md
Keywords: auriko,llm,routing,ai,openai-compatible,sdk
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: anyio>=4.0.0
Requires-Dist: httpx>=0.28.1
Requires-Dist: pydantic>=2.11.2
Requires-Dist: typing_extensions>=4.0
Provides-Extra: openai-compat
Requires-Dist: openai<3.0,>=2.8; extra == "openai-compat"
Provides-Extra: langchain
Requires-Dist: langchain-openai<1.2,>=1.1; extra == "langchain"
Provides-Extra: crewai
Requires-Dist: crewai<2.0,>=1.6; python_version >= "3.11" and extra == "crewai"
Requires-Dist: litellm<2.0,>=1.50; python_version >= "3.11" and extra == "crewai"
Provides-Extra: adk
Requires-Dist: google-adk<2.0,>=1.27; extra == "adk"
Requires-Dist: openai<3.0,>=2.20; extra == "adk"
Provides-Extra: llamaindex
Requires-Dist: llama-index-llms-openai<0.8,>=0.7; extra == "llamaindex"
Provides-Extra: all
Requires-Dist: auriko[adk,crewai,langchain,llamaindex]; extra == "all"
Dynamic: license-file

# Auriko Python SDK

Type-safe Python SDK for the [Auriko](https://auriko.ai) intelligent LLM routing API.

[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)

## 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

```bash
pip install auriko
```

## Quick Start with OpenAI SDK

```python
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

```python
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

```python
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:

```python
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

```python
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

```python
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

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

### Provider extensions

```python
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:

```python
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](https://docs.auriko.ai/guides/advanced-routing#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

```python
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

```python
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:

```python
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+
