Models
athena model is the CLI surface over the model registry. Today it covers
discovery (list, get, schema) and readiness — the mechanical
“is a PR needed” check on existing rows, with a brief generator a loop can
consume directly. It also supports source-backed registration, live
verification, source inspection, canaries and promotion. Later
releases add deprecation, retirement and migration, driven by the
same commands.
<ref> — used by readiness, verify --live, sources, migrate,
deprecate and retire — is one of:
- a raw registry UUID
model_registry:<uuid>provider/model(split at the first/; the provider is the part before it, the model is everything after, since some providers’ model ids contain slashes — e.g.fal/fal-ai/flux-pro/v1.1)
CLI input only; the HTTP API accepts bare UUIDs only.
Commands
athena model list
| Flag | Meaning |
|---|---|
--input-type <TYPE> | Filter by input type (text, image, audio, …). Comma-separated values accepted. |
--output-type <TYPE> | Filter by output type. Comma-separated values accepted. |
--search <term> | Case-insensitive substring match on display_name and the provider model path. Empty provider groups are dropped. |
--supports-web-search | Keep only models that can run provider web search (registry web_search capability, a translator dialect, output_type: text). Combines with --search. |
--all | Accepted for symmetry with other list commands; /models always returns the full list. |
-o, --output json | Compatibility flag for scripts that pass -o json / --output json. |
--schema | Dump this leaf’s schema instead of running. |
athena model list --search "recraft v4 pro"{ "data": [ { "provider": "fal", "models": [ { "id": "019f902b-db73-7ea4-8ef2-60a8ff5747cd", "display_name": "Recraft V4 Pro T2I", "model": "fal-ai/recraft/v4/pro/text-to-image" } ] } ]}athena model get <id>
| Flag | Meaning |
|---|---|
<id> | Raw model registry UUID (positional, required unless --schema). |
--schema | Dump this leaf’s schema instead of running. |
athena model get 019f902b-db73-7ea4-8ef2-60a8ff5747cd{ "id": "019f902b-db73-7ea4-8ef2-60a8ff5747cd", "provider": "fal", "model": "fal-ai/recraft/v4/pro/text-to-image", "display_name": "Recraft V4 Pro T2I", "status": "active", "input_schema": { "...": "the full parameter contract" }}athena model schema <id-or-search>
| Flag | Meaning |
|---|---|
<id-or-search> | A raw registry UUID, or a case-insensitive search phrase matched against display_name / model (errors on multiple matches). Required unless --schema. |
--json | Print the raw input_schema only, instead of the readable table. |
--schema | Dump this leaf’s schema instead of running. |
athena model schema "nano banana 2 edit"Default output is a readable table (required params, then each param’s
type / default / enum-or-range). --json prints the schema object
directly:
{ "prompt": { "type": "string", "required": true }, "image_size": { "type": "enum", "values": ["square_hd", "square", "portrait_4_3"], "affects_pricing": true }}athena model verify
| Flag | Meaning |
|---|---|
--from-spec <file|-> | Full agent spec (CreateAgentRequest or a bare workflow) to scan for referenced models. |
--workflow <json|@file|@-> | A workflow object to scan directly: literal JSON, @<path>, or @-. |
--probe-fal | Also probe Fal live for models missing from the registry. |
<ref> | Registry id or a case-insensitive search phrase naming one model. Required with --live; ignored by spec-scanning mode. |
--live | Re-read one registered model from its provider documents and print its diff against the stored row, rather than scan a spec. It re-reads the URL the last resolution recorded. Takes no value, so verify --live <ref> and verify <ref> --live are the same command. |
--live-url <URL> | Read that document instead of the URL the last resolution recorded — the way to verify a row whose provenance was never captured, and the only way to point verification at a moved or renamed provider page. Implies --live for a preview. Handoff and resume require explicit --live. The diff and any --update stay on the row <ref> named. |
--update | With --live, capture a handoff for review; resume writes the reviewed diff and fresh source snapshot. |
--handoff <DIR> | With --live --update, write the review handoff and exit 14 without a registry write. |
--resume <DIR> | Continue the handoff’s retained resolution. Requires --review. |
--review <FILE> | Completed driver review for the resumed resolution. |
--interpret <FILE> | Optional {surface} interpretation submitted with the review on resume. |
--group-id <ID> | Reuse a group holding the provider key for the post-update canary. |
--yes | Register a validated review non-interactively only when the signed gate has no blockers. |
--schema | Dump this leaf’s schema instead of running. |
Exactly one of --from-spec / --workflow is required (neither → exit 2).
athena model verify --from-spec ./agent.json{ "results": [ { "ref": { "registry_id": "019f902b-db73-7ea4-8ef2-60a8ff5747cd" }, "ok": true }, { "ref": { "provider": "fal-ai", "model": "fal-ai/recraft/v4/pro/text-to-image" }, "ok": false } ], "all_ok": false}Exit 0 when all_ok; exit 1 when any referenced model is missing.
With --live, <ref> is required and the command re-resolves the stored
model from its provider documents. It prints the proposed diff. With --update,
it captures a handoff and exits 14; a reviewed resume performs the write.
See Handoff and resume.
A bare --live re-reads whatever URL the last resolution recorded, so a row
that was never resolved through the CLI — an imported or hand-inserted one —
has nothing to re-read. Pass the document yourself in that case:
athena model verify openai/gpt-image-2.5-sunburst --live --live-url https://openai.com/api/pricing/#gpt-image-2-5The source URL rides on its own flag rather than on --live so that the two
can never be confused: --live takes no value, so the ref may be written on
either side of it, and --live-url always names a document.
The supplied URL decides what is read; <ref> still decides what is compared
and, with --update, what is written. A document that resolves to a different
provider or model than the row is refused rather than written, so a URL typed
one row off cannot quietly overwrite the wrong entry. Read-only, the URL form
exits 1 on a non-empty diff so a drift check fails loudly; --live without a
URL keeps its exit-0 report.
athena model register <url>
| Flag | Meaning |
|---|---|
<url> | Provider documentation, API-reference or model-card URL. Required for a fresh handoff; omit on resume. |
--handoff <DIR> | Capture documents and a review template, then exit 14 without registering. |
--resume <DIR> | Continue the handoff’s retained resolution. Requires --review. |
--review <FILE> | Completed review covering all four drivers and the pricing tier. |
--interpret <FILE> | Optional {surface} interpretation for a price the resolver could not machine-read. |
--also | Write candidate URLs to also.json and print a separate handoff command per candidate. Each candidate requires its own review and resume. |
--production | Use the prod profile and require a second confirmation naming the production API URL. |
--price-json <file|-> | Operator-supplied ModelPricingEntry template; - reads stdin. Carries the operator_template blocker and cannot replace a review. |
--group-id <ID> | Reuse a group holding the provider key for the post-registration canary. |
--no-canary | Skip the post-registration canary. |
--yes | Register without prompting when the review is validated and the signed blocker list is empty. |
--schema | Dump this leaf’s schema instead of running. |
Handoff and resume
Every registration and live verification update requires a driver review. The first command captures the provider documents and registers nothing:
athena model register https://provider.example/model --handoff ./model-reviewIt writes three files and exits 14 (ReviewNeeded):
snapshot.json: the retained resolution ID, source URL, and each document’s kind, URL, content hash and text.review.template.json: all four drivers, with resolver-filled values and their statements where available.handoff.md: the skill name, how to read it, and the resume command.
Without --handoff, the CLI writes these files to a temporary directory and prints its path.
It still exits 14. --yes does not bypass the handoff or review.
Read athena-model-register before writing the review. The CLI carries a public copy:
athena model skillathena model skill --jsonText output includes its SHA-256 version. JSON output is {name, version, text}.
Read every captured document. Copy the template to review.json and complete all drivers and the pricing tier.
When the price was not machine-read, write interpret.json as {surface} according to the skill.
Resume the same retained resolution:
athena model register --resume ./model-review --review ./model-review/review.json --group-id <ID># Include this option only when an interpretation was needed:athena model register --resume ./model-review --review ./model-review/review.json --interpret ./model-review/interpret.json --group-id <ID>The CLI prints each driver marked reviewed, registers through the signed gate,
stamps the reviewed pricing tier, then runs the canary. A refused tier stamp is
reported separately; the registration still succeeded. Use --no-canary when execution is deliberately deferred.
An expired resolution exits 2 with resolve again with --handoff; capture and review a fresh handoff.
The live-update flow is the same:
athena model verify <ref> --live --update --handoff ./model-reviewathena model verify <ref> --live --update --resume ./model-review --review ./model-review/review.json --group-id <ID>When the signed gate has blockers, the CLI lists every code and detail, then asks:
Register despite these N blockers? This is recorded against your account.A person must acknowledge on a terminal. The CLI sends exactly the signed blocker codes.
With any blocker, --yes exits 1, prints the codes and sends no acknowledgement.
With a validated review and no blockers, --yes registers, stamps the tier and runs the canary without a prompt.
An agent never acknowledges blockers; it hands the full list to a person.
athena model skill
Print the public athena-model-register skill and its SHA-256 version.
Use --json to print {name, version, text}. The command needs no login.
Follow its handoff, driver review and resume procedure before registering or updating a model.
athena model sources <ref>
| Flag | Meaning |
|---|---|
<ref> | Registry id or a case-insensitive search phrase naming one model. |
--schema | Dump this leaf’s schema instead of running. |
Prints the latest source snapshot recorded by registration or live verification: source documents, capture times, content hashes and extracted pricing.
athena model canary <ref>
| Flag | Meaning |
|---|---|
<ref> | Registry id or a case-insensitive search phrase naming one model. |
--params <json|file|@file|-> | JSON object used for canary execution and cost prediction: a literal, file path, @<file>, or - for stdin. |
--timeout <seconds> | Terminal-result polling limit in seconds. |
--schema | Dump this leaf’s schema instead of running. |
Requires --workspace. It creates a temporary single-model agent, runs it,
checks output modality and recorded cost against the registered prediction,
then deletes the temporary agent and prints the full outcome.
athena model promote <ref> --to <profile>
| Flag | Meaning |
|---|---|
<ref> | Registry id or a case-insensitive search phrase resolved on the current profile. |
--to <profile> | Required target deployment profile. It must resolve to a different API URL with its own token. |
--no-canary | Promote directly without the required target-environment canary. |
--yes | Answer confirmations non-interactively; promotion to prod normally has a second confirmation. Does not by itself resolve a pricing-tier conflict. |
--pricing-tier-conflict <keep|source> | How to resolve a target already audited at a pricing tier that differs from the source’s: keep the target’s audited tier, or replace it with the source tier. |
--schema | Dump this leaf’s schema instead of running. |
Promotion reads the source row and source snapshot, diffs the target’s matching
provider/model row, confirms the target API URL, then writes row and snapshot
together. If both row and provenance already match, it reports a no-op. Unless
--no-canary is supplied, it requires a target workspace and runs the canary
after the write.
pricing_tier, model_owner, and model_family travel with the row. If the
source’s tier is audited and the target does not already hold that same tier
audited, promote re-applies it as an audited edit on the target right after a
successful register. If the target is already audited at a different tier,
that is a conflict: --pricing-tier-conflict resolves it non-interactively,
otherwise promote prompts (defaulting to keeping the target’s tier under
--yes). The JSON report always carries a pricing_tier object describing
both sides and the outcome.
athena model readiness
athena model readiness [<ref>] [--all] [--pr-brief <file>] [--schema]| Flag | Meaning |
|---|---|
<ref> | The model to check (positional). Exactly one of <ref> or --all is required — both or neither is exit 2. |
--all | Check every registry row instead of one. |
--pr-brief <file> | Render the PR brief and write it to <file> (parent directories created; overwrites an existing file). Valid only with <ref> — with --all it’s exit 2. Written whenever the flag is given, whether or not the verdict fails. |
--schema | Dump this leaf’s schema instead of running. |
Single <ref> — stdout gets the full ModelReadinessResponse, exit 0
when readiness.ok, exit 1 otherwise:
athena model readiness higgsfield/higgsfield-ai/soul/2.0The ref splits at the first / (see <ref> above): provider
higgsfield, model higgsfield-ai/soul/2.0.
{ "id": "019f902b-db73-7ea4-8ef2-60a8ff5747cd", "provider": "higgsfield", "model": "higgsfield-ai/soul/2.0", "display_name": "Higgsfield Soul 2.0", "status": "active", "readiness": { "ok": false, "checks": [ { "code": "provider_supported", "ok": false, "reason": "…" }, { "code": "key_present", "ok": true, "reason": "…" }, { "code": "pricing_unit_supported", "ok": true, "reason": "…" }, { "code": "executor_available", "ok": false, "reason": "…" }, { "code": "pricing_param_forwarded", "ok": true, "reason": "…" } ], "unknown_params": ["foo"] }}--all — one JSON object per failing row on stdout, one per line
(NDJSON), rows that pass print nothing, rows in server order:
{"id":"019f902b-db73-7ea4-8ef2-60a8ff5747cd","provider":"higgsfield","model":"higgsfield-ai/soul/2.0","display_name":"Higgsfield Soul 2.0","failing":[{"code":"provider_supported","reason":"…"}],"unknown_params":[]}A summary line goes to stderr:
readiness: 55 of 581 rows need a PR(or readiness: all 581 rows pass). A 2xx response whose data is not an
array — a version skew, an envelope regression — is an error with code
invalid_response and exit 1, never an all-clear on rows the CLI could not
read. Both counts come from the response, never from a fixed catalog size — 581
is simply what the seed catalog (scripts/models/models.json) holds today.
Of the 55 failing rows, 46 fail provider_supported — no client at all (22
higgsfield, 14 stability, 8 ideogram, 2 zhipu) — and 4 fail
executor_available on a provider that otherwise has a client: three
google/imagen-4.0-* ids (not a -image family the Gemini adapter routes)
and google/text-embedding-004 (EmbeddingService takes an OpenAI key only).
The remaining five — cohere/embed-english-v3.0,
cohere/embed-multilingual-v3.0, cohere/embed-v4.0,
openrouter/openai/text-embedding-3-large, and
openrouter/openai/text-embedding-3-small — are declared with
output_type: text but have a zero token-output rate. Their
pricing_unit_supported check fails: only rows declared as embeddings can
omit a completion-token price.
Exit 0 when nothing fails, exit 1 otherwise.
--pr-brief <file> — after printing the verdict, stderr gets
wrote PR brief to <file>. See PR brief below. The command’s
exit code is still driven by the verdict, not by the brief write.
Every command above supports --schema, like the rest of the CLI — see
Reference → Schema dumps.
athena model migrate --from <ref> --to <ref>
| Flag | Meaning |
|---|---|
--from <ref> | Required source model. |
--to <ref> | Required target model. It must have the source model’s output type and must not be retired. |
--scope all|workspace|group | Agent search scope; defaults to all. workspace uses the active workspace. |
--group <id> | Required with --scope group; ignored by other scopes. |
--fix | Apply the plan. Without it, the command only reports the dry-run plan. |
--force | Migrate agents even when wizard-exposed parameters are unsupported by the target, dropping those parameters. Does not resolve a key the target requires a value for — see below. |
--map <key>=<target_key> | Answer an unresolved parameter key by mapping it onto a target property. Repeatable — one per key. |
--set <key>=<json> | Answer an unresolved parameter key with a literal value. The right side is parsed as JSON, falling back to a JSON string when it isn’t valid JSON — --set steps=30 sends 30, --set prompt=hello sends "hello". Only a key the target declares can take a value (a required_unfilled key, not an unmapped one). Repeatable — one per key. |
--drop <key> | Answer an unresolved parameter key by dropping it. Repeatable — one per key. |
--yes | Skip confirmation; required for a fixing run from non-interactive stdin. It answers the migrate/don’t-migrate confirmation only, never an unresolved parameter key. |
--schema | Dump this leaf’s schema instead of running. |
Both references accept a registry id or a case-insensitive search phrase. The command prints the run report. A dry run changes nothing; a fixing run confirms the plan, applies it, then polls the run until it reaches a terminal status.
Unresolved parameter keys
The first dry run can come back with parameter keys the plan could not
resolve on its own — a source parameter with no matching property on the
target, or a target property the plan has no value for. --map, --set and
--drop answer these ahead of time, one flag per key; anything they don’t
cover is asked about on a terminal, one Select question per parameter
name (never per agent), titled with the key, how many agents raised it,
and, for a key the target requires, that fact. The options are each
candidate target property (“Map to <candidate>”) and “Drop it”; a key the
target requires a value for (required_unfilled) also offers “Enter a value”
(a follow-up text prompt, parsed exactly like --set’s right side). A source
key the target has no property for (unmapped) is never offered a value: the
server refuses to set a key the target does not declare, so a value there
could not resolve anything. Skipping a question leaves that key undecided —
the run still proceeds for every agent that is otherwise ready.
Every answer, from flags and from the prompts, is sent on one re-planned dry
run, and that re-planned report — not the first one — is what gets printed
and what --fix applies. When the first plan has no unresolved keys, none of
this happens: one dry run, no extra round trip, no prompt, exactly as before.
athena model migrate --from openai/gpt-image-1 --to openai/gpt-image-2.5 \ --map image=image_urls --set steps=30 --drop seed --fixOff a terminal (a script, a CI job), any key still undecided after flags and
--force is a usage error (exit 2, code decision_required) before anything
else is sent — it lists the undecided keys, their kind, their candidates and
how many agents raised each one, and hints the three flags. --force drops
every key left unmapped, but a key the target requires cannot be satisfied by
dropping it, so those still need --map or --set, interactively or not.
An answer — a flag, or a prompt answer on a terminal — can be well-formed
and still come back unresolved on the re-plan because the target rejected
it: a --set or “Enter a value” of the wrong type, a --set on an
unmapped key. On a terminal or off it, that is a usage error (exit 2, code
decision_required) naming the key the target would not accept — never a
key --fix goes on to skip. Only a question you skipped stays undecided.
athena model deprecate <ref>
| Flag | Meaning |
|---|---|
<ref> | Required model to deprecate. |
--to <ref> | Replacement model. Required to move agents without an interactive replacement prompt. |
--fix | Apply the migration plan when agents still reference the source. |
--force | Drop wizard-exposed parameters unsupported by the replacement instead of skipping the agent. |
--yes | Skip confirmation; required for a fixing run from non-interactive stdin. |
--schema | Dump this leaf’s schema instead of running. |
When no agent references the model, the command confirms and marks it
deprecated. When agents still reference it, it first migrates them to the
replacement; only a completed --fix run marks the source deprecated. A dry
run leaves the status unchanged and reports the plan.
athena model retire <ref>
| Flag | Meaning |
|---|---|
<ref> | Required model to retire. |
--yes | Skip confirmation; required from non-interactive stdin. |
--schema | Dump this leaf’s schema instead of running. |
The command refuses while any agent still references the model and names the references in its error. Migrate those agents first, then confirm retirement.
athena model register does not accept --pr-brief — the brief generator is
a readiness flag; register reads readiness, it does not write briefs.
Plain-language phrases
A driving agent (Claude Code, Codex) maps plain language onto athena model
commands. These are the phrases the loop and the CLI’s own --schema
descriptions agree on:
| Phrase | Command | Availability |
|---|---|---|
| ”is a PR needed” / “is this model ready to run” | athena model readiness <ref> | this release |
| ”which models can’t run” / “check every model” | athena model readiness --all | this release |
| ”write the brief” / “hand it to the loop” | athena model readiness <ref> --pr-brief <file> | this release |
| ”what models are there” / “find the nano banana model” | athena model list --search <term> | shipped |
| ”show its parameters” | athena model schema <ref> | shipped |
| ”does every model in this agent exist” | athena model verify --from-spec <file> | shipped |
| ”register this model” | athena model register <url> | shipped |
| ”check it against the provider” | athena model verify <ref> --live | shipped |
| ”show where the prices came from” | athena model sources <ref> | shipped |
| ”run it once and check the bill” | athena model canary <ref> | shipped |
| ”move it to production” | athena model promote <ref> --to prod | shipped |
| ”swap every agent to the new model” | athena model migrate --from <ref> --to <ref> --fix | later release (03) |
| “deprecate it” / “retire it” | athena model deprecate <ref> --to <ref> / athena model retire <ref> | later release (03) |
Worked example: “move gpt-image-2.5 to production” →
athena model promote openai/gpt-image-2.5-sunburst --to prod.
Exit codes
| Code | Meaning here |
|---|---|
| 0 | Success — readiness passed, or verify found every referenced model |
| 1 | Readiness failed, or verify found a missing model |
| 2 | Usage — neither <ref> nor --all given (or both), --pr-brief combined with --all, or neither --from-spec nor --workflow |
| 3 | Auth — not logged in, or token expired and refresh failed |
| 4 | Not found — provider/model resolved to zero rows, or a raw id doesn’t exist |
| 13 | Forbidden — authenticated but not a super-admin |
| 14 | ReviewNeeded — handoff written; run the skill and resume with a completed review. No registry write occurred. |
See Reference → Exit codes for the full, CLI-wide table.
Provider strategies
The provider column is the stored AiProvider value; aliases in
parentheses.
| Provider | Model types in scope | Identity source | Parameter source | Pricing source | Examples source |
|---|---|---|---|---|---|
fal | text_to_image, image_to_image, text_to_video, image_to_video, video_to_video, text_to_speech, speech_to_text, text_to_music | endpoint id from the path | OpenAPI https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=<id>; <page>/api; <page>/llms.txt | <page> pricing section (matrix or unit price) plus GET /v1/models/pricing?endpoint_id= (fal_platform.rs) when a key is present | <page>/examples |
openai | text_to_text, text_to_image, image_to_image, text_to_speech, speech_to_text, text_to_embedding | model id from the path; existence via GET /v1/models when a key is present | developers.openai.com/api/docs/models/<id> (endpoints, modalities, snapshots); family template row for the parameter schema | the same page’s pricing block; per-image prices when the page has them, else the token rates with a per-image estimate (see pricing rules) | developers.openai.com/api/docs/guides/* linked from the page |
openrouter | text_to_text, text_to_image | <owner>/<name> from the path | GET /api/v1/models/<owner>/<name>/endpoints (supported_parameters, architecture) | the same endpoints response (pricing per endpoint; the cheapest provider is the base, others reported) | openrouter.ai/docs model page |
anthropic | text_to_text | model id from the docs path | docs.anthropic.com models overview and the Messages API reference (llms.txt first) | models overview pricing table (input, output, cache read, cache write) | docs quickstart |
google (gemini) | text_to_text, text_to_image, text_to_video, text_to_speech, text_to_embedding | model id from ai.google.dev/gemini-api/docs/models anchors | the models page and generateContent reference | ai.google.dev/gemini-api/docs/pricing (context tiers recorded as modifiers on declared usage thresholds, see 02b) | cookbook links on the page |
xai (grok) | text_to_text, text_to_image | model id from docs.x.ai/docs/models | the models page and the REST reference | the models page pricing table | docs guides |
deepseek | text_to_text | model id from api-docs.deepseek.com | api-docs.deepseek.com quick start and reasoning pages | api-docs.deepseek.com/quick_start/pricing (standard tier; off-peak discount recorded as a note, not a price) | docs |
moonshot (kimi) | text_to_text | model id from platform.moonshot.ai/docs | the model list page and chat reference | the pricing page incl. cached input | docs |
zai (glm) | text_to_text, text_to_image | model id from docs.z.ai | model page and API reference | model page pricing | docs |
groq | text_to_text, speech_to_text, text_to_speech | model id from console.groq.com/docs/models | the models page and the API reference | groq.com/pricing | docs |
minimax | text_to_text, text_to_speech | model id from platform.minimax.io/docs | the model page | the page when it prices; otherwise benchmarked from OpenRouter and flagged | docs |
| Alibaba Qwen | text_to_text, text_to_image | resolved through OpenRouter (openrouter/qwen/<name>) | OpenRouter endpoints | OpenRouter endpoints | — |
Alibaba’s own DashScope endpoint is not an AiProvider text variant; a
DashScope URL resolves to a PR brief naming the missing text client, and the
CLI offers the OpenRouter route for the same model instead. Qwen media models
are unaffected — media_gen/qwen.rs is a direct DashScope client and passes
provider_supported for image output. Higgsfield stays a brief as well —
higgsfield is not an AiProvider variant either.
Model types and pricing structure
The registry’s model_type column: text_to_text, text_to_image,
image_to_image, text_to_video, image_to_video, video_to_video,
text_to_speech, speech_to_text, speech_to_speech, text_to_music,
text_to_embedding. Each type has one pricing structure the resolver
produces and the billing path reads:
| Model type | Unit | Base | Modifiers evaluated on | Output-dimension pricing |
|---|---|---|---|---|
| text_to_text, text_to_embedding | per 1M tokens | input, output, cached input, reasoning | usage tiers (context thresholds) declared by the page | — |
| text_to_image, image_to_image | per image | the price at the documented default parameters | pricing-affecting job parameters (quality, image_size, background, n, …) | yes: per-cell prices keyed by output width×height when the page prices by size |
| text_to_video, image_to_video, video_to_video | per second, or per video when the page prices whole clips | the price at the documented default resolution and duration | resolution, fps, audio on/off, duration tiers | yes: keyed by output resolution |
| text_to_speech, text_to_music | per 1M characters, per second, or per request as the page states | documented default voice/quality | voice tier, quality, format | — |
| speech_to_text, speech_to_speech | per second (audio in) | documented default | diarisation, timestamps, language options when priced | — |
Readiness checks
readiness.checks is exactly these five pass/fail codes, plus
unknown_params as a sixth, warning-only list. readiness.ok is true iff
every check in checks is ok — unknown_params never fails the verdict.
| Code | Proves | What fixes it |
|---|---|---|
provider_supported | The provider string either parses to an AiProvider variant (aliases included) or is a media-only provider id with its own key spec — google-vertex and qwen are media-only and are not AiProvider variants. | For a text provider, add the variant to AiProvider (crates/athena-intelligence/src/providers/mod.rs) and its key slot (key_resolution.rs); for a media-only provider, add it to media_provider_key_spec (media_gen/provider.rs) alongside its adapter — either way, a PR. |
key_present | A credential is configured for the provider. | Configure the provider credential — an operator task, not a PR. |
pricing_unit_supported | BaseCosts (crates/athena-common/src/types/cost.rs) can hold this row’s pricing unit. | Extend BaseCosts for the unit — a PR. |
executor_available | A runtime path exists for this provider × output type. | Add a runtime path (media: media_gen/provider.rs build_media_provider) — a PR. |
pricing_param_forwarded | Every pricing-affecting parameter is actually forwarded to the provider, so the platform can bill it. | Forward the parameter in the provider client so the pricing modifier can apply — a PR. |
unknown_params (warning) | Lists parameters the provider client does not forward. Never fails the verdict. | Forward the parameter in the provider client, or register/run without it. |
PR brief
athena model readiness <ref> --pr-brief <file> renders the row as a GitHub
issue body and writes it to <file> (parent directories created; an existing
file is overwritten). The body follows the issue spec shape of
.agents/spec/template.md, the shape every agent-ready issue uses. Before the
command exits, the CLI validates that the four required sections are present,
in order — a missing or out-of-order heading is exit 1 with code
brief_invalid, naming the first missing heading.
The brief carries, in this order, and no other section:
- A title line naming the provider and model, and stating the verdict —
needs a PRwhen a check fails,passes — no PR neededwhen none does. ## Objective— what the row does once it runs. It follows the same verdict, so a brief written for a passing row never asks for work nobody needs.## Current baseline— the full registry entry as a fencedjson block; every **failing check** with its reason; `unknown_params` as a warning line; a `Passing:` sub-list; then one bullet per source document (url, capture time, content hash) with its excerpt fenced astext, or a note that no source snapshot was recorded.## Acceptance criteria— numberedAC-1,AC-2, …: one per failing check (athena model readiness <ref>reports that check ok), then a last one requiringathena model readiness <ref>to exit 0.## Out of scope— no data fix of other registry rows, no CLI change, no pricing change beyond the failing checks.## Design—Required scope:, one checkbox item per failing check pointing at the file it needs touched, from the Readiness checks table above. Then the hand-off: the loop invocation naming the file just written, and the GitHub issue route.
To hand the brief to the autopilot, open it as an issue labelled
ready-for-agent:
gh issue create --title "<the brief's title line>" --body-file <file> --label ready-for-agentTo run it yourself, run the delivery loop (.agents/loop/ADD.md) on that
issue’s number, or on the file directly:
/athena-loop deliver the brief at <file>--pr-brief is written whenever the verdict fails or the flag is
given — the command’s own exit code still tracks the verdict, not the
brief write.