Module models_dev 

models.dev live enrichment (Layer 2.5 of the catalog).

Fetches the community-maintained model catalog from https://models.dev/api.json (MIT, also used by opencode) and enriches the built-in Layer 1 TOML entries with up-to-date pricing, context windows, max output tokens, and reasoning flags.

Layering

Layer 1   built-in TOML (compiled in)           fallback
Layer 2   user overrides (~/.oxicode/catalog/...)    wins
Layer 2.5 models.dev enrichment (this module)   fills gaps / refreshes
Layer 3   /v1/models runtime discovery          local servers

Enrichment runs inside the consumer’s model database (oxicode-ai’s model_db) after Layer 2 overrides are applied. Only fields that are missing or unverifiable in Layer 1 are overwritten — see the precedence rules below.

Precedence (highest wins)

1. Layer 2 user override
2. models.dev enrichment (this module) — only positive prices / known limits; never overwrites a verified Layer 1 value with a worse one
3. Layer 1 built-in TOML

Offline behavior

If the cache is fresh, enrichment is near-instant (file read). If the cache is stale or absent, a live fetch is attempted (10s timeout, 2 retries). On total failure, get returns None and Layer 1 is used unchanged — the application still works, only cost accuracy degrades.

Attribution

Model data © models.dev (MIT). See https://github.com/sst/models.dev.

Structs

MdCatalog

Top-level catalog: provider id → provider.

MdCost

Pricing. All values are USD per million tokens.

MdCostTier

A single pricing tier (used within tiers array).

MdCostTierData

Context-over-200K pricing tier data (Anthropic-specific).

MdLimit

Token limits.

MdModalities

Supported input/output modalities.

MdModel

A single model entry — serialised from models.dev api.json.

MdModelProvider

Per-model provider override — lets a specific model use a different API protocol or endpoint than its parent provider.

MdProvider

A single provider entry.

MdReasoningOption

Reasoning options (effort levels, budget tokens).

MdTierSpec

Functions

get

Get the enriched catalog, if init_models_dev has run with data.

init_models_dev

Initialize the models.dev catalog.

protocol_for

Map a models.dev npm string to oxicode’s API type and authentication method.

refresh

Force-refresh the models.dev cache.