# Models catalog The models extension supplies model metadata to the harness. Provider extensions can also supply model lists and metadata. Authentication and profile selection are described in [model authentication](auth.md). ## Cache The [models extension](../src/albedo/harness/extensions/models/extension.gleam) stores the catalog as `models.json` in the Albedo home. Its default URL is `https://models.dev/api.json`, and its default refresh interval is 24 hours. A refresh runs in the background when the cache is missing or old. A failed fetch keeps the previous cache. `refreshHours` set to zero disables that automatic fetch. An explicit reload reports fetch errors. The typed [catalog projection](../src/albedo/harness/extensions/models/catalog.gleam) decodes provider and model metadata and trims fetched catalogs to the fields lookup uses. The [catalog cache](../src/albedo/harness/extensions/models/catalog_cache.gleam) owns isolated parsing, the persisted index, and publication of the provider and model maps together. It parses one file revision once. A revision is the file's size and modification time from [`albedo_env/file_revision`](../packages/albedo_env/src/albedo_env/file_revision.gleam). One caller parses a revision while the others wait on the catalog's [`sdk/file`](../src/albedo/harness/sdk/file.gleam) path lock. The maps are shared through [`sdk/pinned`](../src/albedo/harness/sdk/pinned.gleam) without copying them. The index is saved beside the catalog as `models.json.index` in version 4. A version 3 index from an earlier daemon is still read, and the next parse writes version 4. The fetch goes through [`sdk/cached_fetch`](../src/albedo/harness/sdk/cached_fetch.gleam). The [catalogue module](../src/albedo/harness/extensions/models/catalogue.gleam) bounds fetched catalogs at 32 MiB and answers lookups and listings from those maps. Legacy untrimmed files are rewritten on first parse while preserving their modification time. The catalog is external data, not a guarantee of a provider's current offerings. ## Lookup [`catalog.select`](../src/albedo/harness/extensions/models/catalog.gleam) uses the endpoint host to select a provider when possible. `chatgpt.com` selects the OpenAI catalog identity. Without an attributed match, it uses the smallest known context limit, reports an output limit only when known limits agree, and intersects reported modalities and efforts. `select_provider` instead requires the named provider. When a model is missing, the [catalogue lookup](../src/albedo/harness/extensions/models/catalogue.gleam) can infer low, medium, and high reasoning efforts from certain model names. That fallback does not supply catalog limits. A failed lookup otherwise returns no metadata. ## Display names [`ModelInfo`](../src/albedo/harness/sdk/extension.gleam) carries an optional `display_name` separately from the request's model ID. The [model resource](../src/albedo/daemon/http_resources.gleam) returns it as `label`, falling back to the ID for absent or blank names. Names are presentation only; clients send the original ID when selecting or invoking a model. The Codex and Claude catalogs retain upstream `display_name`, and Antigravity retains its discovered name after stripping trailing variant effort suffixes such as `(High)` or `(XHigh)`. The models.dev projection keeps each model's `name` through trimming and index reloads. Unattributed lookup uses a name only when the reported nonempty names agree. Older caches without names still work. ## Reasoning defaults [`ModelInfo`](../src/albedo/harness/sdk/extension.gleam) stores supported reasoning levels and the optional `default_effort` separately, both as `types.Effort`. Each catalog reads its provider's names into that type at its own edge and leaves out a name albedo has no level for; Antigravity's `extra-low` tier is `minimal`. An ordered list of supported levels does not establish a provider default. The [model resource](../src/albedo/daemon/http_resources.gleam) exposes both facts to clients. A null default means that Albedo does not know the level. The [Codex catalog](../src/albedo/harness/extensions/codex/catalog.gleam) retains the backend's `default_reasoning_level` as `default_effort` in its cache. It accepts that default only when it is a supported requestable level. Old caches without the field remain readable. Other catalogs can leave the default unknown rather than guess from the model name or effort order. The [runtime resolver](../src/albedo/harness/runtime.gleam) converts saved reasoning choices before constructing the provider context: - `inherit` follows the profile's explicit effort when configured. Otherwise it follows the model default. - `default` follows the model default even when the profile specifies a level. - A supported level such as `high` is an explicit override. Antigravity requires an Albedo-selected fallback tier; its catalog reports that tier with `default_effort_source` set to `albedo`. Provider-advertised defaults use `provider`. Conflicting Codex account defaults are left unknown. A known model default becomes the request's effort. An unknown default omits the effort control so the provider decides. The reserved choices do not reach provider request encoders. Catalog reads remain local and do not send inference requests. Clients must preserve the choice across model switches rather than replace it with their own preferred level. ## Request effort A request carries a typed effort, [`types.Effort`](../src/albedo/openai_api/types.gleam): `none`, `minimal`, `low`, `medium`, `high`, `xhigh` or `max`, or no effort at all. Saved session and profile choices stay strings, `inherit`, `default` or a level name. Session configuration, child and peer creation, profile settings and the proxy parse a level name with `types.parse_effort` when it arrives and refuse one it does not name; `runtime.resolve_effort` turns the saved choice into the turn's effort. A provider sends the effort a request asks for when the model takes it, and otherwise applies its own rule with what its catalog knows about the model. Nothing outside the provider reads a model's effort list to choose a request's effort. - Claude, Codex, the OpenAI-compatible provider, GitHub Copilot, OpenCode Go and Zen, Mistral, Perplexity and Bedrock Messages use `extension.within_listed_efforts` with their catalog's entry for the model: the highest listed level below the one asked for, else the lowest above it, never stepping down to `none`, and no effort for a model listed without efforts or not listed at all (`types.nearest_effort`). - Bedrock Converse applies the same rule to its verified levels, and sends no reasoning fields for a model without a verified mapping. - The Anthropic gateway applies it to `thinking.supported_efforts`. - Vertex Gemini maps every level onto a budgeted model's budgets, none and minimal turning thinking off where the model allows it, and to the nearest named level for a model that takes levels. A model its table does not know gets no thinking control. - Antigravity picks the nearest of the variant tiers the model lists, and takes the level as asked for a model listing none. A summarizer request of its own (`loop.separate`: lcm leaves and merges, persistent-agent consolidation, rolling and rewind summaries) asks for `medium`. Replayed summaries and the persistent-agent memory request keep the turn's effort, because they read the turn's cached prefix. A generated title asks for `none`, which a provider sends as the lowest level the model takes. The request ledger records the effort a request asked for. New sessions save `inherit` when effort is omitted or null. Existing saved levels remain explicit overrides. Existing null choices retain their legacy omission behavior. Codex's legacy null choice still sends `medium`, matching its earlier encoder. See [session settings](settings.md#session-configuration-and-catalog) for the persistence and validation owners. The clients annotate the actual default level in their reasoning menus. They show a provider-default entry only when its level is unknown. They display the effective level separately from its source: the profile, the model default, or an Albedo fallback. When a profile overrides effort, a separate advanced action switches between that profile and the model default. Normal model and reasoning selections affect only the current session. Saving profile defaults requires a separate explicit action. Do not expose `inherit` and `default` as competing effort levels. See the [terminal controls](tui.md#reasoning-controls) and [web controls](web.md#reasoning-controls). ## Profile effort and replay rules A provider extension can override catalog facts for its own saved profiles through `ProfileModelPlugin`. Core asks the installed extension that the profile names, enabled or not: - [`runtime.profile_effort_override`](../src/albedo/harness/runtime.gleam) uses its `efforts` in place of the catalog's list. The model resource and session effort validation both read it. - [`session_configure`](../src/albedo/daemon/session_configure.gleam) calls its `replay` with the latest projected history before it queues or applies a model switch. The [Bedrock extension](../src/albedo/harness/extensions/bedrock/extension.gleam) is the only contributor. A saved Converse profile answers its verified effort controls, and `Some([])` for an unknown model. A Messages profile keeps the catalog's efforts. Any other or unreadable `api` value answers `Some([])`. A Converse profile refuses a switch when history holds native blocks that only their origin model can replay. See the [contract](plugins.md#provider-account-and-profile-contributions). ## Model lists [`model_lists`](../src/albedo/harness/sdk/model_lists.gleam) exposes `ids`, `refetch`, `saved`, and `ready` for provider-specific lists. `ModelCatalog.list` receives the runtime's key environment as its third argument. A remote listing that discovers an environment key passes it on, and other catalogs ignore it. Its cache stores lists separately from the general catalog, in the `albedo_model_lists` registry table and `$ALBEDO_HOME/model-lists`, and applies success and failure expiry periods. Consumers must handle a missing or unavailable list. The [proxy](proxy.md) uses profile and catalog information when it lists models. The custom `anthropic-api` provider keeps its own model-list namespace, separate from Claude's catalog and credentials. Model metadata still comes from the Anthropic catalog. The custom `anthropic-api` provider lists models from its configured API root's `/models` route. The list contains every sorted, unique ID the route returns, not model limits or thinking capabilities; the Anthropic catalog supplies those facts for Claude models, prefixed aliases included. The selected ID remains the request's model ID. See [custom Anthropic gateways](auth.md#custom-anthropic-gateways) for credentials. OpenAI-compatible lists share [`catalog.ids`](../src/albedo/openai_api/catalog.gleam) for sorted, unique IDs. Providers retain eligibility, credential precedence, headers, timeouts, and HTTP status policy. The generic [OpenAI-compatible extension](../src/albedo/harness/extensions/openai/extension.gleam) also keeps the `architecture.input_modalities` each listed model reports (read by [`catalog.input_modalities`](../src/albedo/openai_api/catalog.gleam)) in `openai-modalities-.json` per endpoint, and its catalog lookup answers with them, completed from models.dev. A model that reports only text input then gets its images projected out instead of sent to a server that would refuse them. A model whose list entry omits the field keeps the old behavior. The extension's picker keeps a model that reports `architecture.output_modalities` (read by `catalog.output_modalities`) when it lists `text`, and hides one that does not; only a listed model without that field is judged by its ID's name. The [ordinary HTTP client](../src/albedo/harness/sdk/http.gleam) preserves response headers for conditional catalog requests. Mixed-credential catalog reads do not establish model-session affinity. The [GitHub Copilot catalog](../src/albedo/harness/extensions/github_copilot/catalog.gleam) keeps the `supported_endpoints` of each model its `/models` fetch lists in `github-copilot-endpoints-.json` per API endpoint. Each session's connection carries them, and the [wire](../src/albedo/harness/extensions/github_copilot/wire.gleam) sends a model to Chat Completions, Responses or Messages by what the list names. A model listed on several endpoints keeps the route its family usually takes when that is among them. Before a list has been fetched, or for a model it does not name, the family decides. Codex reads `codex-models.json` from the correctly encoded home path. If that file is absent, it checks the legacy path that treated UTF-8 bytes as Unicode codepoints and validates the cache before copying its bytes to the canonical path. An unreadable canonical file does not trigger the fallback. The [Codex catalog](../src/albedo/harness/extensions/codex/catalog.gleam) owns this migration. ## Related pages - [All topics](README.md) - [Change guidance](contributing.md) - [Model authentication](auth.md) - [Compaction](compaction.md) - [Image generation](imagegen.md): driver selection and image model settings.