providercatalog

Overview ¶

Package providercatalog is a stdlib-only LEAF DATA adapter exposing a pinned, embed-vendored subset of the models.dev model catalog as a typed, read-only Go API. It carries no behaviour beyond parsing the embedded JSON once and handing out immutable-by-convention value types; nothing here knows about the agent, providers, ports, or the domain.

Source, provenance, and license ¶

The embedded data in models.dev.curated.json is a subset of the community model catalog published at:

https://models.dev/api.json

canonical repository https://github.com/anomalyco/models.dev, distributed under the MIT License ("Copyright (c) 2025 models.dev"). The full MIT license text + attribution is vendored alongside this file in MODELS_DEV_LICENSE, as the MIT license requires when redistributing portions of the work.

The catalog API exposes NO version field (the upstream endpoint has none), so the fetch date IS the pin. Pinned 2026-07-13.

Curation policy (full vendor for in-scope providers) ¶

The full catalog has 145+ providers and thousands of models. We vendor ONLY the three providers in scope for multi-provider Phase 0/1 — but for each of them we vendor ALL models (no hand-pinned allowlist). The DROPPED surface, stated plainly:

• 142+ providers dropped wholesale (out of P0/P1 scope: Chat-Completions providers like Gemini-native / Together are P2 and need their own adapter, so their catalog entries are not useful yet).
• openai: ALL models vendored (P0 native via the Responses adapter).
• anthropic: ALL models vendored (P1 native Messages adapter).
• openrouter: ALL models vendored (the OpenRouter flagship+long-tail set — hundreds of routes across dozens of upstream providers).

The catalog is kept fresh by a weekly CI job (.github/workflows/catalog-refresh.yml) that re-fetches models.dev/api.json, regenerates the curated JSON, and opens a PR if it changed. An unknown provider/model id is an honest (_, false) lookup miss, never a silent substitution. The Go structs deliberately do NOT parse cost / release_date / knowledge etc.; the curated JSON KEEPS those fields (the jq projection copies whole model objects) so a future slice can surface them without re-pinning (encoding/json ignores unmapped fields).

Deterministic regeneration (reproducible re-pin) ¶

The curated file is generated from the full source by ONE deterministic jq filter; -S (sort keys) makes the embedded bytes stable across re-pins so a diff shows only real model changes. To re-pin:

# 1. Re-fetch the pinned source (record the date in the comment above):
curl -s https://models.dev/api.json > .scratch/models.dev.full.json

# 2. Regenerate the curated subset deterministically (ALL models for the 3
#    in-scope providers — no allowlist):
jq -S '{
  openai:     ( .openai     | {id, env, npm, api, name, doc, models} ),
  anthropic:  ( .anthropic  | {id, env, npm, api, name, doc, models} ),
  openrouter: ( .openrouter | {id, env, npm, api, name, doc, models} )
}' .scratch/models.dev.full.json > internal/adapter/providercatalog/models.dev.curated.json

Layering ¶

LEAF adapter: stdlib + embed + encoding/json ONLY. It imports NO domain (session/prompt/tool/governance), NO port, NO internal/app, and NO other adapter. Its Catalog/Provider/Model are package-own value types and must never leak into the domain or port. Only the composition layer (internal/app) reads it.