Metadata-Version: 2.4
Name: hyperrouter-ai
Version: 0.2.0
Summary: The official Python SDK for HyperRouter — a unified API gateway for all major AI models.
License-Expression: MIT
Project-URL: Homepage, https://hyperrouter.ai
Project-URL: Documentation, https://hyperrouter.ai/docs
Keywords: ai,llm,openai,hyperrouter,api,models
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: openai>=1.0.0

# HyperRouter

The official Python SDK for HyperRouter — a unified API gateway for all major AI models. One API key, one SDK, any model.

To learn more about how to use the HyperRouter SDK, check out our [API Reference](https://hyperrouter.ai/docs#api-reference) and [Documentation](https://hyperrouter.ai/docs).

## SDK Installation

**Note:** The SDK requires a valid [API key](https://hyperrouter.ai/settings/api-keys).

The SDK can be installed with `pip`, `uv`, or other package managers.

### pip

```bash
pip install hyperrouter-ai
```

### uv

[uv](https://github.com/astral-sh/uv) is a fast Python package installer and resolver, designed as a drop-in replacement for pip and pip-tools.

```bash
uv add hyperrouter-ai
```

### Poetry

```bash
poetry add hyperrouter-ai
```

### Shell and script usage

You can use this SDK in a Python shell with `uv` and the `--with` command-line option:

```bash
# Launch a Python shell
uv run --with hyperrouter-ai python

# Run a script directly
uv run --with hyperrouter-ai python my_script.py
```

## Requirements

This SDK requires Python 3.8 or higher.

## IDE Support

### PyCharm

Generally, the SDK will work well with most IDEs out of the box. However, when using PyCharm, you can enjoy much better integration by installing an additional plugin.

- [PyCharm Pydantic Plugin](https://docs.pydantic.dev/latest/integrations/pycharm/)

## SDK Usage

### Synchronous

```python
from hyperrouter import HyperRouter

client = HyperRouter(api_key="hr-your-key-here")
# Or set HYPERROUTER_API_KEY env var and call HyperRouter()

response = client.chat.completions.create(
    model="anthropic/claude-sonnet-4.6",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What is HyperRouter?"},
    ],
)

print(response.choices[0].message.content)
```

### Async

The SDK client can also be used to make asynchronous requests with `asyncio`:

```python
from hyperrouter import AsyncHyperRouter
import asyncio

client = AsyncHyperRouter()  # Uses HYPERROUTER_API_KEY env var

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

asyncio.run(main())
```

### Streaming

Stream responses token-by-token for real-time output:

```python
from hyperrouter import HyperRouter

client = HyperRouter()

stream = client.chat.completions.create(
    model="deepseek/deepseek-v4-pro",
    messages=[{"role": "user", "content": "Write a haiku about AI."}],
    stream=True,
)

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

### Async Streaming

```python
from hyperrouter import AsyncHyperRouter
import asyncio

client = AsyncHyperRouter()

async def main():
    stream = await client.chat.completions.create(
        model="anthropic/claude-sonnet-4.6",
        messages=[{"role": "user", "content": "Explain quantum computing."}],
        stream=True,
    )

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

asyncio.run(main())
```

## Using Different Models

HyperRouter gives you access to 300+ models from 50+ providers through a single API. Just change the `model` parameter:

```python
from hyperrouter import HyperRouter

client = HyperRouter()

# Anthropic
response = client.chat.completions.create(
    model="anthropic/claude-opus-4.6",
    messages=[{"role": "user", "content": "Hello from Claude!"}],
)

# OpenAI
response = client.chat.completions.create(
    model="openai/gpt-4.1",
    messages=[{"role": "user", "content": "Hello from GPT!"}],
)

# DeepSeek
response = client.chat.completions.create(
    model="deepseek/deepseek-v4-pro",
    messages=[{"role": "user", "content": "Hello from DeepSeek!"}],
)

# Google
response = client.chat.completions.create(
    model="google/gemma-4-31b-it",
    messages=[{"role": "user", "content": "Hello from Gemma!"}],
)

# Meta
response = client.chat.completions.create(
    model="meta-llama/llama-4-scout",
    messages=[{"role": "user", "content": "Hello from Llama!"}],
)

# Auto Router — let HyperRouter pick the best model
response = client.chat.completions.create(
    model="hyperrouter/auto",
    messages=[{"role": "user", "content": "Pick the best model for me!"}],
)
```

Browse all available models at [hyperrouter.ai/models](https://hyperrouter.ai/models).

## OpenAI Compatibility

HyperRouter is fully compatible with the OpenAI SDK. If you already use `openai`, you can switch by changing the base URL:

```python
from openai import OpenAI

client = OpenAI(
    api_key="hr-your-key-here",
    base_url="https://api.hyperrouter.ai/v1",
)

response = client.chat.completions.create(
    model="anthropic/claude-sonnet-4.6",
    messages=[{"role": "user", "content": "Hello!"}],
)
```

## Resource Management

The SDK implements the standard context manager protocol, so you can use it with `with` statements to ensure connections are properly closed:

```python
from hyperrouter import HyperRouter

with HyperRouter() as client:
    response = client.chat.completions.create(
        model="anthropic/claude-sonnet-4.6",
        messages=[{"role": "user", "content": "Hello!"}],
    )
    print(response.choices[0].message.content)
# Connection is automatically closed
```

For async:

```python
from hyperrouter import AsyncHyperRouter
import asyncio

async def main():
    async with AsyncHyperRouter() as client:
        response = await client.chat.completions.create(
            model="openai/gpt-4o",
            messages=[{"role": "user", "content": "Hello!"}],
        )
        print(response.choices[0].message.content)

asyncio.run(main())
```

## Environment Variables

| Variable | Description |
|----------|-------------|
| `HYPERROUTER_API_KEY` | Your HyperRouter API key (`hr-...`). Used when no `api_key` is passed to the client. |

## Debugging

You can turn on debug logging to see raw HTTP requests and responses:

```python
from hyperrouter import HyperRouter
import logging

logging.basicConfig(level=logging.DEBUG)

client = HyperRouter()
```

## Links

- [Documentation](https://hyperrouter.ai/docs)
- [API Reference](https://hyperrouter.ai/docs#api-reference)
- [Models Explorer](https://hyperrouter.ai/models)
- [Dashboard](https://hyperrouter.ai/settings)
- [GitHub](https://github.com/HyperRouterAI)
