ADR 0011 (D-45): the provider catalog — model providers as configuration
Question: Docket's model wire has a clean port (core/llm.py) and one adapter
(edges/adapters/llm.py), but which providers exist lives in seven Python tables with no single
owner, the three direct presets (anthropic, openai, google) cannot be activated through the
CLI, a provider block holds one model and is replaced by the next add, and adding a provider of
record means editing six places. The 2026-09-26 request: make provider selection configurable the
way roles, policies and pipelines already are (a YAML document), with the abstractions that make
the agnosticism structural, robust and easy to extend — without overengineering. What is the shape,
and what earns a card?
Where decided: 2026-09-26, as Phase 29. Activation gate: none on Phases 27/28 (disjoint files); the integrator confirms batching from function-level contention as usual.
Evidence (read at 0764091; every locator is a symbol name, re-locate with rg -n):
| Fact | Locator |
|---|---|
Seven provider tables, seven populations: 2 built-in URLs, 5 credentials, 7 presets, 3 local prefixes, 9 in doctor, 4 key prefixes, 5 in the keys setup wizard |
edges/adapters/llm.py::_HOSTED_GATEWAY_BASE_URLS; core/provider.py::PROVIDER_CREDENTIAL_NAMES; core/models_policy.py::KNOWN_PRESETS, ::PRESET_TABLE, ::LOCAL_PROVIDERS, ::MODEL_PRICING; cli/_doctor.py::_PROVIDER_KEY; cli/_keys.py::_KEY_PREFIXES, ::_keys_setup |
| The direct presets are unreachable through the CLI (deterministic reproduction) | cli/__init__.py::_cmd_models_preset requires get_local_provider(preset); core/provider.py::ping_endpoint GETs <base>/models with no credential and urllib.error.HTTPError is a URLError, so 401 (api.anthropic.com, api.openai.com) and 404 (generativelanguage.googleapis.com /v1beta/openai) register as "unreachable"; no bypass flag exists. Measured 2026-09-26 with curl and ping_endpoint |
The only escapes are hand-editing fleet.json or the process-wide DOCKET_LLM_BASE_URL, which drops registered limits |
edges/adapters/llm.py::resolve_endpoint, precedence 1 |
One model per block; a second add replaces the block |
core/fleet.py::add_local_provider; docs/MODEL-GATEWAYS.md ("multi-model catalog import is not implemented") |
api: "openai-completions" is written and read by nothing |
model-profiles spec "Provider registration display fields" rule 2 |
| The port was designed for a second dialect without a second port | core/llm.py module docstring ("keeping a future second endpoint dialect from leaking wire fields into core/") |
Retry-After is ignored; backoff is linear 2 s × attempt, 2 retries |
core/dispatch.py hop retry loop (ctx.do_sleep(_cfg.DISPATCH_RETRY_BACKOFF_S * attempt)); docs/MODEL-GATEWAYS.md admits it |
| Precedent: a global catalog with credentials and per-entry operator assertions | core/mcp_tools.py::McpServerConfig, ADR 0009 §"MCP" |
| Precedent: YAML in, docket-owned JSON stored, YAML out | core/archetypes.py::parse_yaml_file → docket-roles.json; P27-7 export |
| Precedent: one-shot migration of a fleet field into its registry | model-profiles spec "The default model (single source)" rule 2 |
docket auth is a stub that only reports "gone, use docket keys" |
cli/_keys.py::run_auth; tests/integration/test_provider_agnosticism.py::TestAuthProviderGoneHonestly |
| Vendor facts used for the built-in documents | Anthropic "OpenAI SDK compatibility" (base https://api.anthropic.com/v1, tools supported, "intended to test and compare … not a long-term or production-ready solution", no prompt caching, strict ignored, prompt_tokens_details always empty); Gemini "OpenAI compatibility" (base https://generativelanguage.googleapis.com/v1beta/openai, function calling, beta) — both read 2026-09-26 |
The trigger is an explicit scoped request plus a deterministic regression; no quantitative
threshold is invented. Full audit: internal-docs/llm-provider-audit-2026-09-26.es.md (gitignored).
Decision
A provider catalog of kind: provider documents in two scopes (built-in, global), from which
every table derives; a closed dialect field with one value that selects the adapter; credentials
referenced by name and never by value; and a registration that verifies with the credential instead
of without it. Wiring over the port that exists; no plugin system, no second adapter until a
named trigger fires.
1. The document
The fifth kind of ADR 0010's envelope (YAML, camelCase, kind + name). Until P28-1 ships,
core/provider.py::load_provider_document checks kind itself; P28-1 then adds one case
"provider" that delegates to it.
kind: provider
name: anthropic
dialect: openai-chat # closed enum, one value today; selects the adapter
baseUrl: https://api.anthropic.com/v1
auth:
type: bearer # bearer | header | none
credentials: [ANTHROPIC_API_KEY] # NAMES resolved from env or `docket keys`; first present wins
local: false # true = $0 pricing, no credential expected
marketplace: false # true = per-model prices are not tracked ("n/a (bring your own)")
credentialPrefix: sk-ant- # optional; `docket keys validate` format hint
pricesAsOf: 2026-06-11 # required when any model carries a price
models: # catalog rows; `id` is what goes on the wire
- id: claude-sonnet-4-6
contextWindow: 200000
maxTokens: 64000
price: {input: 3.00, output: 15.00, cacheRead: 0.30, cacheWrite: 3.75} # USD per MTok
presets: # what PRESET_TABLE holds today, attached to its provider
- name: anthropic
ranks: {economy: claude-haiku-4-5, standard: claude-sonnet-4-6, premium: claude-opus-4-6}
note: >
Anthropic's OpenAI-compatibility layer. Anthropic documents it as intended to test and
compare models, not as a production solution: no prompt caching, `strict` ignored,
system messages concatenated. For Claude with caching, a native dialect is a deferred item.
note: ""
A local provider, the way provider add writes it today but readable:
kind: provider
name: local
dialect: openai-chat
baseUrl: http://127.0.0.1:8081/v1
auth: {type: none}
local: true
models:
- {id: /mnt/data/models/qwen.gguf, contextWindow: 16384, maxTokens: 8192}
Format rules. dialect and auth.type are closed enums; an unknown value refuses the load
naming file, field and valid values. auth.type: header requires auth.header. A credential is a
name matching ^[A-Z][A-Z0-9_]*$; a value never appears in a document, so a document can be
committed. headers (static extra request headers, added by P29-4) may not name Authorization,
Content-Type or Accept. models may be empty: any provider/<id> then resolves with None
limits, exactly as an unregistered id does today; an exact row supplies limits and price. A
provider with no presets is not a preset but is selectable with docket models set. local:
true implies $0 (local) pricing and auth.type: none by default. No include, inheritance,
variables or expressions (ADR 0010's cuts apply).
The document grows one field per reader, never ahead of it (ADR 0008 contract property 3).
P29-1 defines name, dialect, baseUrl, auth{type: bearer|none, credentials}, local,
models[]{id, contextWindow, maxTokens}, note. P29-2 adds presets, marketplace,
credentialPrefix, price, pricesAsOf with their consumers. P29-4 adds auth.type: header,
auth.header, headers with the wire that sends them.
2. Scopes, resolution, storage
| Scope | Holds | Lives in | Changed by |
|---|---|---|---|
| Built-in | the providers docket knows: anthropic, openai, google, openrouter, ai-gateway, groq, mistral, deepseek, xai, cerebras, together, ollama, lmstudio, local (the shipped default URL) |
src/docket/templates/providers/*.yaml, in the wheel like templates/policies/ |
a release |
| Global | the operator's: local servers, own gateways, and overrides of a built-in by name (another URL, limits, credential) | ~/.docket/docket-providers.json, docket-owned through edges/store.py |
docket models provider add / remove |
| Pod | — | — | deferred: role policy plus pins already select the model; credentials are global like the MCP catalog |
Resolution is nearest-wins by name, global → built-in: the role-overlay rule one level shorter.
resolve_endpoint(model) becomes: split provider/model → catalog entry → exact model row if any →
credential by name → Endpoint. DOCKET_LLM_BASE_URL / DOCKET_LLM_API_KEY keep overriding
everything (model-profiles "Hosted gateway resolution" rule 4, unchanged). Credential precedence
becomes DOCKET_LLM_API_KEY → env <name> → central store <name>, for each name in
auth.credentials in order; the "non-placeholder key in the provider block" step disappears
because a document never holds a value.
Storage and migration. fleet.json → providers is ported once into
docket-providers.json on first catalog read and the fleet field is cleared — the pattern of
profiles: → roles: and defaults.model → registry default. apiKey: "local" or empty →
auth: {type: none}; a loopback URL or all-zero cost → local: true; a literal non-placeholder
apiKey value is moved into the central store under <NAME>_API_KEY and referenced by name, and
that move is audited (provider.migrate); api, name, reasoning, input are dropped (spec:
display-only). Destination is written before the source is cleared. FleetConfig.providers stays
one release for that read and is then removed (deferred, like ADR 0010's pre-kind format).
One source for seven tables. After P29-2 no module outside core/provider.py holds a
provider-name literal. Base URLs, credential names, presets, rank anchors, local prefixes,
marketplace labels, prices and key prefixes are functions over the loaded catalog (functions, not
import-time constants, because global scope changes at runtime). config.DEFAULT_MODEL remains
the one literal, pinned by a test to equal the built-in anthropic preset's standard rank.
3. The adapter seam: structural agnosticism without a second adapter
client_for(model)dispatches ondialectover a closed dict inedges/adapters/:{"openai-chat": OpenAIChatClient}. A dialect is a file inedges/adapters/and a release — never a plugin, entry point or import by convention. It isload_document's closedmatchapplied to the wire.OpenAIChatClient._headers()readsauth(bearer→Authorization: Bearer;header→<auth.header>: <value>;none→ nothing) and appendsheaders. This covers Azure OpenAI'sapi-keyheader and Anthropic'santhropic-workspace-idwithout vendor code. Azure'sapi-versionquery parameter stays deferred.core/llm.pykeeps its port.Endpointgains typedauth_type,auth_header,headersand losesis_local(no consumer). No new dependency:urllib+pyyaml(already required).- Why not an Anthropic Messages adapter now. It would buy prompt caching (cache read ≈ 10 %
of input price), structured outputs and thinking output. Trigger: a hosted Anthropic fleet whose
measured
usageis mostly repeated prefix, or an operator asking twice. Today: zero hosted use in this system, and D-18 bans per-vendor clients.dialectleaves the slot; that is the whole commitment. D-42's "cut: a second dialect" stands — this ADR adds a closed field with one value.
4. Registration, verification, CLI
docket models provider add verifies with the resolved credential and classifies the result
instead of collapsing it to a boolean; the HTTP probe moves to edges/adapters/llm.py::probe_models
(side effects belong in edges/), the classification stays pure in core/provider.py:
GET {baseUrl}/models with credential |
Action |
|---|---|
| connection refused, DNS, timeout | refuse registration (today's behaviour; the existing fail-closed test stays) |
| 200 | register; ids the response advertises and models[] lacks are printed as a suggestion, never written |
| 401 / 403 | register with a warning naming the missing or rejected credential; docket init still stops at readiness until it exists |
404 on /models |
register with the warning "no /models route; capability not verified" |
| other 4xx / 5xx | register with a warning carrying the status |
No --no-verify: the classification makes it unnecessary.
CLI surface, all under the existing docket models provider:
docket models provider add <file.yaml> # a kind: provider document
docket models provider add <name> <base-url> --model <id> [--ctx N] [--max-tokens N] [--credential NAME]
# today's shortcut; it produces the same document
docket models provider list # name, scope, dialect, baseUrl, credential present
docket models provider show <name> [--json] # resolved entry with its scope
docket models provider remove <name> # global scope only; removing an override restores the built-in
docket models provider export <name> [<file>] # the §1 document
docket models preset <name> lists every preset the catalog carries and no longer demands a
registered block for anthropic/openai/google: the URL is built in, and what is required is the
credential (readiness). docket config explain <agent> gains a provider section (name, scope,
dialect, base URL, credential source override|env|store|none, exact-row limits). docket doctor
reads the catalog for key coverage and reports a malformed global document as it reports a
malformed role overlay.
docket auth (a stub whose every subcommand answers "gone, use docket keys") becomes an entry in
__main__.py::_REMOVED, the mechanism the project uses for workflow, team and eval; docket
keys setup iterates the catalog's built-in credentials instead of its own five-row table.
Retries. The adapter reads Retry-After (seconds or HTTP-date) on a retryable status into
ChatResponse.retry_after_s, threaded through AgentLoopResult and TurnResult; the hop retry
loop sleeps min(max(linear, retryAfter), DISPATCH_RETRY_MAX_WAIT_S) (new constant, default 60 s).
Retry counts and the FailureKind vocabulary do not change. This is a gap in the retry path that
already exists — not a new capability — and it becomes reachable the moment hosted providers do.
It is the one card the integrator may hold back for an observed 429 without affecting the others.
Rules this ADR amends (so no two documents disagree)
| Document, rule | Today | After |
|---|---|---|
| model-profiles "Provider readiness" 2 | "A direct Anthropic, OpenAI, or Google key without an explicitly registered compatible base URL MUST NOT satisfy readiness" | "A selected model is ready when its provider resolves in the catalog (built-in or global) to a base URL and every credential the entry requires is present. A built-in hosted provider needs only its credential." (P29-2) |
| model-profiles "Provider readiness" 3 | "Registration MUST verify <base-url>/models before writing provider state; an unreachable endpoint returns failure" |
"Registration MUST probe <base-url>/models with the resolved credential and classify (§4 table); only a transport failure refuses; every HTTP status registers, with a warning when it is not 200." (P29-3) |
| model-profiles "Hosted gateway resolution" 2 | built-in URLs are openrouter and ai-gateway |
built-in URLs are those of the shipped templates/providers/*.yaml, listed in the spec (P29-2) |
| model-profiles "Hosted gateway resolution" 3 | credential precedence includes "a non-placeholder key in the exact registered provider block" | that step is removed; a document holds names only (P29-1) |
| model-profiles "Provider registration display fields" | api, name, cost, reasoning, input are display-only fields of the block |
section removed; the fields no longer exist after migration (P29-1) |
| model-profiles "Presets" 1 | the built-in presets MUST include the seven names | the built-in presets are those the built-in documents declare, and the seven names stay among them (P29-2) |
| model-profiles "Pricing" 1, 3, 4 | keyed to MODEL_PRICING, LOCAL_PROVIDERS, the marketplace tuple |
keyed to catalog rows, local: true, marketplace: true (P29-2) |
| api-keys "Propagation" 3 | "…require an explicitly registered OpenAI-compatible endpoint until Docket ships a native adapter" | "…are sufficient for a built-in hosted provider; readiness is the catalog's base URL plus the credential" (P29-2) |
api-keys setup |
interactive wizard over a fixed list | wizard over the catalog's built-in credentials (P29-7) |
cli-interface docket models |
provider add <name> <base-url> … only; preset for anthropic, openai, google requires a registered block |
five provider actions; preset requires nothing beyond the catalog (P29-3) |
cli-interface docket auth |
a section with four subcommands | removed; listed with the removed commands (P29-7) |
| pod-dispatch "Retries" | linear backoff only | Retry-After honoured with a ceiling (P29-5) |
| ADR 0010 §1 | "Four kinds" | five, provider delegating to core/provider.py (amended in place) |
Rules that stand and were checked: D-18 (no per-vendor clients — a closed dialect map is one client per open protocol); D-24/D-25 (no streaming, no LiteLLM, no gateway of our own); D-42's cut of a second dialect; ADR 0009's "no second file format, no loader framework" (the document is the same YAML, and the loader is one function); README "Compatible HTTP, not provider SDK parity"; model-profiles "Hosted gateway resolution" 1 and 4; the standing no-fabricated-dollar-figures rule (prices move, they do not change meaning).
Code this ADR retires (no legacy left behind)
| Symbol | Card | Replacement |
|---|---|---|
core/fleet.py::add_local_provider, ::get_local_provider |
P29-1 | core/provider.py::save_provider, ::load_catalog |
core/provider.py::local_provider_config, ::register_local_provider, ::ProviderRegistration, ::ping_endpoint, ::DEFAULT_MODEL_NAME, ::DEFAULT_* provider constants |
P29-3 (ping_endpoint → edges/adapters/llm.py::probe_models) |
register_provider, verify_endpoint, ProviderVerification, the built-in local.yaml |
edges/adapters/llm.py::_HOSTED_GATEWAY_BASE_URLS; core/provider.py::PROVIDER_CREDENTIAL_NAMES |
P29-2 | catalog functions |
core/models_policy.py::KNOWN_PRESETS, ::PRESET_TABLE, ::LOCAL_PROVIDERS, ::UNPRICED_MARKETPLACE_PROVIDERS, ::MODEL_PRICING, ::MODEL_PRICING_AS_OF, ::_RANK_ANCHORS literal |
P29-2 | presets(), is_local_provider(), price_for(), rank_anchors() over the catalog |
cli/_doctor.py::_PROVIDER_KEY; cli/_keys.py::_KEY_PREFIXES; scripts/gen_cli_docs.py::_provider_credential_names literal source |
P29-2 | catalog |
core/llm.py::Endpoint.is_local |
P29-4 | local on the document |
cli/_keys.py::run_auth and helpers, the auth command, ::_keys_setup provider tuple |
P29-7 | __main__._REMOVED["auth"]; the catalog |
FleetConfig.providers |
deferred one release | removed after the migration has had a release to run |
Verdict table
| Item | Verdict | Card | Reason |
|---|---|---|---|
kind: provider document, loader, docket-providers.json, one-shot migration, dialect dispatch |
DO | P29-1 | foundation; byte-identical resolution for today's configs |
| Built-in documents; every table derived; direct presets reachable | DO | P29-2 | one owner; closes the regression on the preset side |
Verification with credential and classification; add <file>, list, show, remove, export; probe in edges/ |
DO | P29-3 | closes the regression on the registration side; fixes the side-effect-in-core smell |
auth.type: header + headers on the wire |
DO | P29-4 | Azure/workspace headers without vendor code |
Retry-After with a ceiling |
DO (removable) | P29-5 | see §4 |
config explain provider section, doctor, docs, spec |
DO | P29-6 | contract property 5 |
Retire docket auth; keys setup over the catalog |
DO | P29-7 | the seventh table, and a command that only says it is gone |
A second dialect (Anthropic Messages, Bedrock converse, Responses API) |
DEFER | — | Trigger: hosted Anthropic usage whose measured input is mostly repeated prefix, or an operator on Bedrock/Vertex, asked twice |
Azure api-version query |
DEFER | — | Trigger: an operator on Azure OpenAI |
Catalog and price discovery from /models |
DEFER | — | P29-3 only suggests ids. Trigger: a built-in pricesAsOf older than six months and one figure shown false |
| Pod-scoped providers, model per step | DEFER (unchanged) | — | ADR 0009's triggers |
Removing FleetConfig.providers |
DEFER | — | one release after Phase 29 ships |
| Automatic fallback to another model or provider | CUT | — | governance: it would change which model ran code without approval; rank anchors stay "not a fallback chain" |
| Streaming, LiteLLM or an own gateway, vendor SDKs | CUT (unchanged) | — | D-18, D-24, D-25 |
Adapter plugins or entry points; include, inheritance, variables in the document |
CUT | — | a dialect is a release; YAML stays data (ADR 0010) |
Test discipline
ADR 0009's rule: one RED behavioural test per card in the module's SUBJECT file; a negative case
only for fail-closed properties (P29-1: an unknown dialect/auth.type refuses the load; P29-3:
a transport failure still refuses registration). The three "same as before" oracles are existing
tests left untouched: TestEndpointResolution, TestPricingHonesty/TestLocalPreset/
TestHostedGatewayPreset, TestHopRetryLoop. P29-2 replaces test_five_known_providers with an
AST test in the same file asserting no provider-name literal outside core/provider.py. P29-3's
round trip (export → add on a fresh home → identical show --json) is the phase's integration
proof. Goldens change only where CLI surface changes (help, completions, models preset
listing) and each card lists the lines.
Waves (proposed; the integrator confirms from function-level contention)
| Wave | Cards | Hot file and function ownership |
|---|---|---|
| 47 | P29-1 | core/provider.py (rewritten: model, loader, catalog, migration, resolve_credential), config.py::PROVIDERS_FILE, core/fleet.py (delete two functions; field comment), edges/adapters/llm.py::resolve_endpoint + ::client_for only, one-line call swaps in cli/__init__.py::_cmd_models_preset and cli/_agents.py |
| 48 | P29-2 ∥ P29-5 ∥ P29-7 | core/provider.py: P29-2 owns the new derivation functions and the P29-2 fields; core/models_policy.py, templates/providers/, cli/_doctor.py::_PROVIDER_KEY users, cli/_keys.py::_validate_key_format, scripts/gen_cli_docs.py → P29-2; core/llm.py::ChatResponse, edges/adapters/llm.py::complete (the HTTPError branch only), core/agent_loop.py::call_backend_and_handle_response + done, core/runtime_driver.py::TurnResult, edges/adapters/docket_runtime.py::run_turn (the TurnResult(...) construction only), core/dispatch.py (the do_sleep line only), config.py → P29-5; cli/_keys.py::_keys_setup + run_auth, cli/__init__.py (the auth command only), __main__.py::_REMOVED → P29-7 |
| 49 | P29-3 ∥ P29-4, then P29-6 | core/provider.py: P29-3 owns verify_endpoint/register_provider/remove_provider/export_provider, P29-4 owns AuthSpec and the headers field; edges/adapters/llm.py: P29-3 owns new probe_models, P29-4 owns _headers + core/llm.py::Endpoint; cli/_provider.py, cli/__init__.py (models provider dispatch + _cmd_models_preset) → P29-3; cli/_config.py, cli/_doctor.py (own check function), docs/ → P29-6 after both merge |
Pre-assigned spec versions (after Phase 28's): model-profiles 2.11.0 (P29-1), 2.12.0 (P29-2),
2.13.0 (P29-3), 2.14.0 (P29-4), 2.15.0 (P29-6); api-keys 1.5.0 (P29-2), 1.6.0 (P29-7);
pod-dispatch 6.18.0 (P29-5); cli-interface 1.40.0 (P29-3), 1.41.0 (P29-6), 1.42.0 (P29-7);
config-format 1.2.0 (P29-1, only if P28-1 has shipped by then; otherwise the integrator adds the
provider arm when merging P28-1). Version numbers stay unique even if Phase 29 lands before 28.
Consequences
- The honest sentence after Phase 29: a provider is a file you can read, commit and export; a hosted provider works with its key alone; a local server works with its URL alone; and adding a compatible provider of record is one YAML file. Before it, the sentence stops at "two gateways work with a key; the rest need a hand-edited JSON".
fleet.jsonholds agents, bindings and flags only; endpoints have their own registry like MCP servers do.- The
dialectfield is a published contract like the harness envelope: its one value is pinned by test; a second value is a release note, never a silent addition. - README limit "Compatible HTTP, not provider SDK parity" stays true and gains "and Anthropic's compatibility layer is documented by Anthropic as for evaluation"; the integrator rewrites that bullet in P29-6's merge (D-37).