Add Model Routing

Problem this prompt solves

A single hard-coded model string shared by every feature is how MVPs accidentally run summarisation, tagging, and complex generation at flagship prices. Model routing is a small module with outsized impact: map tasks to models, allow env overrides, fall back when a model errors, and log what actually ran.

When to use it

• You have two or more AI features with different difficulty (e.g. title vs long-form generation).
• You want cost and latency wins without rewriting prompts from scratch.
• You need a safe fallback if a primary model is unavailable or rate-limited.
• You are preparing paid tiers that might unlock a stronger model later.

Implement model routing for this app’s OpenAI (or compatible) calls.

Create a small routing module, e.g. lib/ai/model-router.ts, that:
1) Defines a TaskType union matching real features (e.g. "classify" | "summarise" | "generate" | "extract")
2) Maps each task to a default model and optional fallback model
3) Allows env overrides such as OPENAI_MODEL_GENERATE, OPENAI_MODEL_CLASSIFY, with a global OPENAI_MODEL default
4) Exposes resolveModel(task, options?) → { model, reason }
5) Optionally accepts a user/plan tier override later (stub a PlanTier type if billing exists; do not build Stripe now)

Refactor existing AI call sites to request a task type instead of hard-coding model strings. Persist the resolved model on each ai_runs row.

Failure behaviour:
- On primary model failure (transient 429/5xx), retry once with the fallback model if configured
- Do not infinite-retry
- Surface a stable error to the user if both fail
- Log model, task, fallback_used boolean

Documentation:
- Table of task → model → why
- How to change models via env without deploys that edit code
- Quality note: which tasks must not be silently downgraded without evaluation

Keep the design boring and explicit — no ML-based router, no multi-vendor abstraction unless already present.

Expected result

A task-based model router with env overrides, call sites updated to use tasks, fallbacks on transient failures, and run logs that show which model served each request.

Implementation notes

• Name tasks after product intent, not model names — “generate_brief” ages better than “gpt4_call.”
• Keep the mapping in one file; scattered ternaries become impossible to audit.
• When adding a new feature, force it through the router so shadow hard-codes do not return.
• Evaluate downgrades on a golden set before changing production defaults.
• Fallbacks should be same-vendor compatible unless you already abstract providers.
• Expose reason in logs (“env override”, “default map”, “fallback”) to debug cost regressions.

Testing checklist

• Each AI feature persists the expected default model for its task.
• Setting an env override changes the model without code edits.
• Simulating a primary model failure triggers a single fallback attempt when configured.
• Both primary and fallback failing returns a controlled error and a failed run record.
• No client-facing response includes API keys or upstream model access tokens.
• A mis-typed task fails at compile time or with a loud server error in development.
• Cost/usage summary still groups correctly by model and by task.

Common mistakes

• Routing by raw user input (“if prompt length > 500”) without product semantics — unpredictable bills.
• Silent fallback to a weaker model on every error, including validation errors.
• Different model strings copy-pasted in five files — router never becomes source of truth.
• Forgetting to log the model actually used after override/fallback.
• Building a grandiose multi-provider framework before two tasks exist.
• Letting clients pass arbitrary model names — instant cost abuse.