BBramaDocs

Brama integration contracts

models.dev catalog

models.dev is a public metadata boundary Brama reads and does not own. This page carries its contract: what the catalog provides, the data and limits Brama applies to it, and what happens when the catalog cannot be reached or the integration is removed.

Outcome

Provide public provider/model metadata without making the catalog a credential, subscription, or billing authority.

Data and limits

  • default origin: https://models.dev/api.json;
  • a request finishes on the catalog's response or a transport failure, without a Brama elapsed-time cutoff;
  • the in-memory catalog is fetched again only when BRAMA_MODEL_CATALOG_TTL_SECONDS names an age; without it, once per process;
  • default replaceable cache: models-dev-cache.json in Brama's state directory ($BRAMA_STATE_DIR, default $HOME/.brama), beside the journal; nothing is written to /tmp;
  • provider/model identifiers and numeric metadata are validated and normalized;
  • unsupported protocols remain non-executable.

Catalog metadata is untrusted advisory data throughout. A model listed by models.dev is executable only when Brama also has a supported protocol adapter, a trusted endpoint, and the correct capability; the per-entry declarations Brama derives are described on Model providers.

Failure and removal

When models.dev cannot be reached, dynamic discovery reports the catalog as unavailable and Brama answers from its own local cache for as long as that cache is inside its TTL. A catalog outage never unlocks a credential, never manufactures availability for a model Brama cannot execute, and never writes journal state.

A request that needed catalog metadata Brama does not have surfaces to the caller as dependency_unavailable; see Errors and Publication and health for the observable codes.

Removing the integration disables dynamic public metadata. Statically registered, explicitly configured routes remain governed by their own contract: each alias still names exactly one destination route in the registry document, and an alias whose route is not executable reports state no_route rather than borrowing one from the catalog. An existing registry file is brought to the current shape with brama routes migrate.