Installation

pip install styrr

Optional extras:

pip install styrr[bedrock]      # AWS Bedrock (boto3)
pip install styrr[huggingface]  # HuggingFace Inference Endpoints
pip install styrr[all]          # Everything

Quick Start

import os
import asyncio
from styrr import StyrRouter

async def main():
    router = StyrRouter(
        models=[
            {"id": "nvidia/nemotron-3-ultra-550b:free"},
            {"id": "openai/gpt-4o-mini"},
        ],
        api_key=os.environ["OPENROUTER_API_KEY"],
    )

    result = await router.prompt("What is FinOps in 2 sentences?")
    print(result)

asyncio.run(main())

Fallback Chain

Models are tried in order. If the first returns 429, 5xx, or times out, the next is tried automatically.

router = StyrRouter(
    models=[
        {"id": "anthropic.claude-sonnet-4"},           # Bedrock primary
        {"id": "openai/gpt-4o-mini"},                   # OpenRouter fallback
        {"id": "nvidia/nemotron-3-super-120b:free"},    # Free fallback
    ],
    api_key=os.environ["OPENROUTER_API_KEY"],
    on_fallback=lambda f, e, n: print(f"Fell back: {f} -> {n}: {e}"),
)

Tool Calling

result = await router.call(
    [
        {"role": "system", "content": "You have access to tools."},
        {"role": "user", "content": "What's the weather in Paris?"},
    ],
    tools=[{
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get current weather for a city",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {"type": "string"}, }}}],
)

if result.tool_calls:
    for tc in result.tool_calls:
        print(f"{tc['name']}({tc['arguments']})")
else:
    print(result.text)

Providers

Provider Auth Install
OpenRouter / OpenAI api_key —
AWS Bedrock AWS credentials styrr[bedrock]
HuggingFace HF token styrr[huggingface]

Streaming

async for event in router.stream([{"role": "user", "content": "Hi"}]):
    if event["type"] == "text_delta":
        print(event["delta"], end="", flush=True)
    elif event["type"] == "done":
        print(f'\nDone — model: {event["model_used"]}')

API Reference

StyrRouter

Method Returns Description
call(messages, tools?, temperature?, max_tokens?) StyrResponse Non-streaming with fallback
stream(messages, tools?, temperature?, max_tokens?) AsyncGenerator Streaming with fallback
prompt(user_message, system_prompt?, **kwargs) str Simple prompt helper

StyrResponse

Field Type Description
text str Response text
model_used str Which model responded
latency_ms int Round-trip latency
fallbacks_tried int Models tried before success
tool_calls list[dict] | None Tool call requests
usage dict | None Token usage
← PreviousStyrr — TypeScript QuickstartNext →Styrr — Hosted API