Metadata-Version: 2.4
Name: hyperion-ai
Version: 0.1.0
Summary: The official Python SDK for the Hyperion AI Gateway
License-Expression: MIT
Project-URL: Homepage, https://github.com/hyperion-hq/hyperion
Project-URL: Repository, https://github.com/hyperion-hq/hyperion/tree/main/sdk/python
Project-URL: Documentation, https://hyperionhq.co/docs/sdk/python
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: openai>=1.0.0
Requires-Dist: httpx>=0.24.0
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"
Requires-Dist: respx; extra == "dev"

# Hyperion Python SDK

The official Python partner SDK for the Hyperion AI Gateway. This SDK is a drop-in replacement for the standard `openai` Python SDK, enhanced with Hyperion's multi-layer caching, smart routing, and observability.

## Installation

```bash
pip install hyperion-ai
```

## Quick Start

```python
from hyperion import HyperionClient

# HyperionClient extends openai.OpenAI
client = HyperionClient(
    api_key="your-hyperion-key",
    base_url="http://your-gateway:8080/v1"
)

response = client.chat.completions.create(
    model="openai/gpt-5.2",
    messages=[{"role": "user", "content": "How fast is Hyperion?"}],
    # Hyperion-specific controls
    hyperion={
        "bypass_cache": False,
        "tags": ["prod", "onboarding"],
        "route_intent": "high_reasoning"
    }
)

# Access rich metadata
print(f"Cache Status: {response.hyperion.cache_status}")
print(f"Is Hit: {response.hyperion.is_hit}")
```

## Features

- **Zero-Friction Upgrade**: Extends `openai.OpenAI`, inheriting full type parity, streaming support, and tool-call functionality.
- **Smart Caching**: Control bypass, TTL, and semantic similarity thresholds per-request.
- **Observability**: Every response includes a `.hyperion` metadata object with performance and cache metrics.
- **Resilience**: Inherits OpenAI's robust retry and polling logic.
- **Admin Client**: Manage API keys, organizations, and budgets programmatically.

## Admin Client

```python
from hyperion import HyperionAdmin

admin = HyperionAdmin(admin_key="your-admin-secret")

# Create a scoped key
key = admin.keys.create(
    name="Test Key",
    budget_limit_usd=10.0,
    allowed_models=["gpt-5.2-mini"]
)
```

## Global Patching

If you can't easily change your client initialization, use `hyperion.patch()` to redirect all OpenAI traffic:

```python
import openai
import hyperion

hyperion.patch(openai)

# This standard client now routes through Hyperion
client = openai.OpenAI()
```
