The default model source, reading a bundled models.dev snapshot.
The snapshot (priv/models/models_dev.json) is a verbatim capture of the
models.dev catalog's chat and decision models
(api.json?type=chat,decision). Every Omni release ships a fresh
snapshot, with data-only patch releases for notable catalog changes and at
least one release per month; use live mode (below) when you need fresher
data than the release cadence provides.
The snapshot is transformed into Omni.Model structs at load time. Each
model loads for one capability, by its catalog type:
- text - no type, or
"chat": the model must support tool use and take and produce text - decision -
"decision": the model must take text; tool use doesn't apply
Deprecated models and every other type (image, embedding, speech,
realtime, ...) are left out. Modalities are narrowed to those Omni
supports, and each model's dialect is inferred from models.dev's npm
package metadata: the model's own package if it has one, otherwise its
provider's. Decision models read a separate table, since the same package
names another API for decisions: @ai-sdk/typesafe-ai is System One and
@ai-sdk/openai is OpenAI Decisions. Models that can't be represented
faithfully are skipped with a warning: those whose npm package maps to no
dialect Omni speaks for their capability, and those served from a
different URL than the first model of their dialect.
Provider ids are translated mechanically to models.dev keys:
:fireworks_ai becomes "fireworks-ai". Any catalog id works, including
providers Omni ships no module for (see Omni.Provider). The catalog's
provider record supplies the provider's name, API key environment variable
(when exactly one is listed), and provider-level dialect. Each dialect's
endpoint takes its models' URL: a model's own provider.api when it has
one, otherwise the provider's api. Templated URLs (${VAR}) are kept
for host: to fill.
Options
:live- whentrue, fetch fresh catalog data from models.dev at load time instead of reading the bundled snapshot. Defaults tofalse.:cache_ttl- how long a cached live catalog stays fresh, in milliseconds. Defaults toto_timeout(hour: 24);0means always fetch. Ignored unlesslive: true.:cache_dir- directory for the live catalog cache. Defaults to a per-user directory underSystem.tmp_dir!()(e.g./tmp/omni_alice). Ignored unlesslive: true.
Live mode
config :omni, :models,
source: {Omni.Sources.ModelsDev, live: true}Live mode fetches the same catalog data over HTTPS and caches the response on disk. Each load walks a resilience ladder, logging a warning at every degradation step:
- Cache fresh (younger than
:cache_ttl): use it, no network. - Cache stale or missing: fetch from models.dev; on success, write the cache and use the fetched data.
- Fetch failed: use the stale cache (stale beats empty).
- No usable cache: fall back to the bundled snapshot.
The fetch runs synchronously inside :omni's application start. Live
mode therefore makes a network request at boot, and adds up to about 5
seconds to boot when the cache is cold and models.dev is unreachable. The
request budget is fixed (no retries) and deliberately not configurable:
failure always degrades down the ladder and never crashes the boot.
The cache file is the raw api.json response, replaced atomically and validated before use. Deleting it at any time is safe, and an unreadable cache is treated as missing. A failed cache write never fails a load: the fetched data is used in memory for that boot.