Provider Architecture

The gateway should expose one stable public API and keep providers as internal adapters.

Recommended model

• one OpenAI-compatible surface for clients
• one built-in provider catalog for easy adoption
• optional external registry file for custom providers
• provider selection via request field, header, or routing policy
• provider kind to distinguish direct backends from aggregators like OpenRouter
• built-in model catalog exposed at /v1/models

Why this is the simplest option

• users do not need to install a provider package to start
• built-in providers are available immediately
• new providers can be added later without breaking clients
• filtering, audit, and redaction stay centralized
• aggregators are treated as first-class providers, not special cases

Aggregators

Providers like OpenRouter are first-class catalog entries with kind = aggregator. They are not special-cased at the API boundary, which keeps the routing model simple while still letting the router reason about direct providers versus aggregators.

Model catalog

The gateway also ships with free-first model aliases, exposed through /v1/models, so users can start from familiar names and let the router resolve them to upstream providers.

Routing & Quota Resilience

The registry marks free-tier candidates with is_free = true. Detailed fallback chains and quota exhaustion behavior are documented in provider_resilience.feature.

Extensibility model

• add a provider by editing a registry file
• or add a provider in code if it should ship by default
• if needed later, split rare providers into optional crates/features