# OpenRouter Fallback Model Gateway

## PURPOSE
This project builds a small FastAPI gateway that sits in front of OpenRouter so a single account can drive the 500+ models from 80+ providers the video describes. It solves the exact pain named in the transcript: managing "separate keys, billing, passwords" for OpenAI, Anthropic, and Google. The gateway exposes one `/route` endpoint, applies a cheap-model-first / smart-model-second policy, and falls back to the next model whenever a call errors out, so an automation never dies because one provider hiccuped.

## WHY THIS MATTERS
Nateherk calls OpenRouter the provider that powers "pretty much every automation running in production," and highlights three ideas: model fallback ("if one model errors out, it just tries the next one"), per-automation API keys for cost analytics, and swapping models by "changing one line." This project turns those ideas into working code: a declarative fallback chain, a per-caller tag feeding an analytics table, and a config where changing the model is literally one string.

## HOW TO BUILD
1. `pip install fastapi uvicorn httpx pydantic python-dotenv`.
2. Define a `ChatRequest` (prompt, tier, automation tag) and a `FALLBACK_CHAINS` dict keyed by tier.
3. On `/route`, iterate the chain, POST to the OpenRouter chat-completions endpoint, and return the first success while recording which model answered.
4. Keep a deterministic stub when `OPENROUTER_API_KEY` is unset so it runs offline.

Key snippet:
```python
for model in FALLBACK_CHAINS[req.tier]:
    try:
        return await call_openrouter(model, req.prompt)
    except httpx.HTTPError:
        continue
return {"error": "all models failed", "tried": FALLBACK_CHAINS[req.tier]}
```

## WHEN TO USE IN PRODUCTION
Use it when you run background automations that must stay up, when you want a cheap model to triage and a smarter one to reason, or when finance wants per-automation cost attribution. Do NOT use it for latency-critical one-shot calls where the extra gateway hop hurts, or when you need a provider SDK feature the gateway does not mirror yet.

## HOW IT HELPS STUDENTS
Students practice async HTTP, retry/fallback patterns, config-driven design, and the cost/quality tradeoff between "cheap, fast" and "smart" models — the routing skill production AI teams hire for.

## STARTER CODE
See `starter/main.py` for a runnable FastAPI gateway with a deterministic offline stub and `# TODO` markers for analytics and auth.
