Model catalogue snapshots

This page defines how acumen model and catalogue facts are described in documentation and how a snapshot of the catalogue is produced. A snapshot is an observation with a date. It is not a claim about what a model does right now.

Contract

The public model and catalogue contract is read from acumen’s own API. The reference facts are the response shapes and the operator/runbook docs that describe them:

• GET /v1/models lists public model names first (auto, cheap, coding, reason, vision, search with owned_by: acumen), then vendor model ids for eligible seats. Vendor rows may include context_window, max_output, and pricing in USD per 1M tokens (prompt, completion, cache_read, cache_write). Omitted fields mean the gateway did not publish that value.
• GET /v1/router/catalog is the operator JSON form of acumen -catalog. It reports seats, plan/kind/eligibility metadata, credential path names, model counts, and circuit state. It never contains a credential value.
• Public aliases are routing names. A successful completion may answer with a different real model than the alias requested. The real served model is the value observed in the runtime response, not the alias.
• Eligibility in a catalogue response is runtime state at observation time. It can change when credentials, circuits, balances, quotas, or upstream availability change.

For the HTTP contract, see HTTP API and the generated API reference.

Runtime state requires runtime evidence

Documentation states a model’s runtime state only with the evidence checked and the date it was checked.

Runtime evidence is one or more of:

• a GET /v1/models response captured on a dated run;
• a GET /v1/router/catalog response captured on a dated run for operator facts;
• a real completion or health check captured on a dated run, with request and response metadata redacted.

A previous snapshot, a vendor catalogue, a seat definition, or a configured credential is not runtime evidence of live availability.

Snapshot rules

Every snapshot artifact must carry provenance:

Field	Meaning
observed_at	UTC timestamp when the observation was made.
endpoint	The endpoint URL or local path that was observed.
revision	The docs/tool revision that produced the snapshot.
request_identity_class	The class of request identity used: anonymous, bearer, admin-bearer, process-token, or unknown. Never a credential value.
redaction_policy	The redaction policy applied before writing the artifact.
source	How the data was obtained (http, file, or stdin).
label	A short operator label for the run.

The artifact must also state, in text and data, that it is a dated observation.

Redaction and fail-safe behavior

Snapshot tooling redacts secrets and personal data before writing output. It must remove:

• authorization headers, cookies, bearer tokens, process tokens, API keys, session values, and password-like fields;
• email addresses and other obvious personal identifiers when present;
• secret values in DSNs or query strings.

The tool fails closed. It does not write a snapshot when required provenance is missing, when the source cannot be read, when the response is not valid JSON for a JSON endpoint, or when the identity class cannot be determined from the provided inputs.

Tooling

scripts/model-catalogue-snapshot.mjs generates a redacted, dated snapshot artifact.

Examples run in an authorized environment with credentials supplied outside the command line:

ACUMEN_BEARER_TOKEN_FILE=/run/secrets/acumen-catalogue-token \
node scripts/model-catalogue-snapshot.mjs \
  --endpoint https://ai.tcp.systems/v1/models \
  --request-identity-class bearer \
  --label acumen-v1-models \
  --output var/model-catalogue-snapshots/acumen-v1-models.json

node scripts/model-catalogue-snapshot.mjs \
  --input-file /secure/captures/v1-router-catalog.json \
  --endpoint https://ai.tcp.systems/v1/router/catalog \
  --request-identity-class admin-bearer \
  --label acumen-router-catalog \
  --output var/model-catalogue-snapshots/acumen-router-catalog.json

Store credentials in a secret file or another secret manager. Do not pass token values as command arguments, and do not commit snapshot artifacts that contain account-specific catalogue data.