examples

Hyperion SDK Examples

This directory contains executable examples for both Python and TypeScript demonstrating the core capabilities of the Hyperion API Gateway.

Structure

• /python: Examples using the hyperion-ai Python package
• /typescript: Examples using the @hyperion-ai/sdk TypeScript package

Features Demonstrated

1. 01_exact_match_caching: Shows how identical requests are served in milliseconds from the L1 Redis cache without hitting upstream. Demonstrates reading latency and token savings from the .hyperion response metadata.
2. 02_semantic_cache: Shows how conceptually similar requests (different phrasing, same meaning) are caught by the L2 vector database, printing the similarity_score.
3. 03_smart_routing: Demonstrates dynamic model selection using the auto model parameter, where simple requests go to fast/cheap models.
4. 04_budget_enforcement: Explains how Hyperion intercepts requests with a 402 error if a key has exceeded its database spending limit.
5. 05_provider_failover: Demonstrates configuring the hyperion.fallbacks array so that if a primary model is down, the request transparently reroutes without throwing a client error.

Running the Examples

1. Make sure your local Hyperion Gateway is running (docker compose up -d).
2. Generate an API Key via the Admin Dashboard (http://localhost:3000).
3. Export your key as an environment variable:

   export HYPERION_API_KEY="your-api-key"

4. Run the scripts using your respective language runner (python3 or ts-node).