# ADR-0005: Provider interface and the capabilities model

**Status:** Accepted — 2026-06-10

## Context

Each provider — and some individual models — imposes different limits (image
dimensions/bytes/MIME/count, tools, structured output, streaming, context
size). Callers must not need to know them; the library must normalize or
clearly reject.

## Decision

- `Provider` is minimal: `Name()` and `Model(id, opts...) (Model, error)`.
  Model ids pass through verbatim; providers never validate ids against a
  catalog (models churn weekly; catalogs rot).
- `Capabilities` is a plain struct declared **per provider** with
  **per-model overrides** via `WithCapabilities` (a `ModelOption`). Zero
  values mean: `MaxImagesPerReq == 0` → images unsupported;
  `MaxImageBytes/MaxImageDimension/ContextWindow == 0` → no declared limit;
  empty `AllowedImageMIME` → any type.
- Providers construct without error even when credentials are missing; the
  failure surfaces as an auth error at request time (and a chain can fail
  over past it). Construction-time validation would make `New()` fragile.
- Until a provider's implementation phase lands, built-ins register as
  **stubs**: they resolve in Parse (so chains, aliases, and env DSNs are
  fully functional) and return a clear "not implemented yet" error on use.

## Consequences

- The media pipeline (Phase 3, ADR to follow) can normalize against any
  target uniformly.
- Adding a provider is additive: implement two methods + declare
  capabilities.

## Alternatives considered

- Capability methods on Model with provider-specific logic — pushes limits
  knowledge into every caller. Rejected.
- Model catalogs with validation — stale within weeks, breaks pass-through
  targets like foreman. Rejected.