# `Omni.Sources.ModelsDev`
[🔗](https://github.com/aaronrussell/omni/blob/v2.0.0/lib/omni/sources/models_dev.ex#L1)

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](https://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` - when `true`, fetch fresh catalog data from models.dev at
  load time instead of reading the bundled snapshot. Defaults to `false`.
- `:cache_ttl` - how long a cached live catalog stays fresh, in
  milliseconds. Defaults to `to_timeout(hour: 24)`; `0` means always
  fetch. Ignored unless `live: true`.
- `:cache_dir` - directory for the live catalog cache. Defaults to a
  per-user directory under `System.tmp_dir!()` (e.g. `/tmp/omni_alice`).
  Ignored unless `live: true`.

## Live mode

```elixir
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:

1. Cache fresh (younger than `:cache_ttl`): use it, no network.
2. Cache stale or missing: fetch from models.dev; on success, write the
   cache and use the fetched data.
3. Fetch failed: use the stale cache (stale beats empty).
4. 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.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
