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.
Cache #
The models extension
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
decodes provider and model metadata and trims fetched catalogs to the fields
lookup uses. The
catalog cache
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.
One caller parses a revision while the others wait on the catalog's
sdk/file path lock. The maps are
shared through sdk/pinned 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. The
catalogue module
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 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 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 carries an optional
display_name separately from the request's model ID. The
model resource 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 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 exposes both facts
to clients. A null default means that Albedo does not know the level.
The Codex catalog
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 converts saved reasoning choices before constructing the provider context:
inheritfollows the profile's explicit effort when configured. Otherwise it follows the model default.defaultfollows the model default even when the profile specifies a level.- A supported level such as
highis 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: 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_effortswith their catalog's entry for the model: the highest listed level below the one asked for, else the lowest above it, never stepping down tonone, 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 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 and
web 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_overrideuses itseffortsin place of the catalog's list. The model resource and session effort validation both read it.session_configurecalls itsreplaywith the latest projected history before it queues or applies a model switch.
The
Bedrock extension 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.
Model lists #
model_lists 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 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 for credentials.
OpenAI-compatible lists share
catalog.ids for sorted, unique IDs.
Providers retain eligibility, credential precedence, headers, timeouts, and HTTP
status policy.
The generic
OpenAI-compatible extension
also keeps the architecture.input_modalities each listed model reports (read
by catalog.input_modalities) in
openai-modalities-<hash>.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 preserves response
headers for conditional catalog requests. Mixed-credential catalog reads do not
establish model-session affinity.
The
GitHub Copilot catalog
keeps the supported_endpoints of each model its /models fetch lists in
github-copilot-endpoints-<hash>.json per API endpoint. Each session's
connection carries them, and the
wire 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 owns this
migration.
Related pages #
- All topics
- Change guidance
- Model authentication
- Compaction
- Image generation: driver selection and image model settings.