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

pip install hyperion-ai

Quick Start

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

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:

import openai
import hyperion

hyperion.patch(openai)

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