AI Models

AI Models — Research & Update Workflow

When to Use This Skill

• Bumping a text, image, or video model to a newer version
• Adding a new image/video generation model or provider (Vercel gateway, Replicate, fal.ai)
• Updating pricing data (per-token, per-image flat, per-image tiered, per-second)
• Verifying model specs (context window, output limit, cost) against providers
• Grounding a model's first broad public release date and source
• Auditing hosted usage metering against prepaid organization credit

Key Files

Shared authoring and generation

Author catalogue data in repository-root data/ai/. TypeScript packages, the web API and the Rust CLI consume generated projections of those sources. Follow the shared data guide and commit authored and generated changes together.

Use lower_snake_case for authored domain fields. Preserve exact model/provider IDs and standard JSON Schema keywords. The generator explicitly maps text-card and cost fields to existing camelCase TypeScript API fields; preserve schema-1 wire spelling instead of renaming public fields during a data update.

Do not hand-edit generated:* literal blocks or package/crate JSON copies. Types, lookup helpers, validation semantics and provider adapters remain handwritten code. Update an explicit ID union or type outside generated blocks when a new card requires it; a JSON binding alone does not implement a provider.

From the repository root, after editing JSON:

node packages/grida-ai-models/scripts/generate.mjs
pnpm --filter @grida/ai-models build
pnpm --filter @grida/ai build
node packages/grida-ai-models/scripts/generate.mjs --bundle
node packages/grida-ai-models/scripts/generate.mjs --bundle --check

The first pass updates TS literals and package-local input schemas. The bundle pass uses freshly built TS consumers to derive operations, snapshots and service views, and writes the checked-in Rust assets. Cargo builds use these embedded assets without Node or network access. Builds/typechecks reject stale source projections; the CLI contract gate also checks the complete generated bundle.

Tools

Script: .agents/skills/ai-models/scripts/model_info.py (symlink to .tools/model_info.py)

Model lookup

# Text / language models
python .agents/skills/ai-models/scripts/model_info.py <model_id>

# Image models
python .agents/skills/ai-models/scripts/model_info.py --image <model_id>
python .agents/skills/ai-models/scripts/model_info.py --image --all

Discovery source: models.dev/api.json. Accepts exact IDs (anthropic/claude-sonnet-4.6) or substring search (gpt-5.4). Its release_date is a lead to verify, not authoritative provenance to copy into the catalogue.

Note: models.dev has per-token costs but not per-image tier breakdowns. For per-image pricing (OpenAI quality tiers, BFL flat rates), consult provider docs directly.

Provider pricing pages

Providers & model IDs

The same model has different ids — and different availability and pricing — across providers; an id is never portable. Two cataloguing patterns:

• text / audio / image_tools / 3D — one card = one provider or exact endpoint; id is in that provider's format, and the provider field (or namespace) fixes the route.
• image — one intrinsic card carries per-provider bindings, like video. The service view adds a primary provider for older single-provider consumers.
• video — the ecosystem is fragmented, so a card is canonical (vendor/model, e.g. google/veo-3.1) and carries a providers record (keyed by provider) of bindings, each with its own call id + meter. Default-provider choice is deferred (see Video Models). Pick a route with video.binding(card, provider).

• Availability + price differ per provider. Veo 3.1 Lite is on OpenRouter/fal.ai but not the Vercel gateway — a canonical card just omits the Vercel binding. Veo 3.1 audio-on is $0.40/s on both Vercel and fal, but fal also meters silent ($0.20/s) and 4K, while OpenRouter exposes only $0/MTok token pricing for video — no usable per-second meter (don't invent one).
• fal.ai is the broadest video/image catalogue (pay-per-use); billing unit is per-model — per-image, per-megapixel, or per-second video — retrievable from its Platform pricing API.
• Image facts are multi-homed across Vercel, fal, and OpenRouter where verified. Service listing is a separate decision; a listed card does not establish that every provider, installed adapter, or request mode can serve it.

What the catalogue is for

Keep one package with two explicit entries: @grida/ai-models for facts and @grida/ai-models/grida for service policy. Service definitions consume facts; the root entry never imports or re-exports Grida policy. Add verified model facts independently of Grida admission. Manage Grida choices in the service definitions, not source declaration order or provider timestamps.

The shared execution SDK (@grida/ai) retains its Grida defaults by explicitly importing the service entry where needed. Its catalog store accepts an optional snapshot or refresh URL; callers need not inject a catalog. Keep provider execution and refresh lifecycle in the SDK and the schema-1 codec in the service entry; do not restore agent-local adapters or duplicate membership.

Preference discipline: an optional default must be listed and nonlegacy. The independent order is partial; unknown and duplicate IDs are errors. Views sort default first, other active models before legacy, then explicit rank, label and ID. Explicit user selections are not replaced by a recommendation. Native subscription and custom-endpoint choices remain with their own runtime owners.

The catalogue states what is true and useful now. Its shape must never be a record of how recently someone got round to updating it — a stale entry is a wrong answer, not a conservative one.

• Price the steady state, not the promotion. When a vendor runs an introductory or time-limited rate, catalogue the price that applies once it ends and record the date and qualification in data/ai/PROVENANCE.md. Otherwise the promotion expiring is a silent cost increase. Recheck when that date passes: a promotion can also be made permanent, which changes the fact, not the rule.
• Deprecate a card that is still a real choice; remove one that is not. Grida legacy: true (projected as deprecated for existing consumers) is for a model someone might still reasonably pick — same price as its successor, or better at something. Delete the entry when the successor is strictly dominant (never worse on any axis, better on at least one): a card nobody should choose is noise in every picker, and keeping it is not caution.

Removing a service member changes admission for consumers of the updated catalogue; it is not merely picker cleanup. It does not require deleting factual identity or imply upstream retirement. TS consumers configured to refresh a published snapshot receive updates through that refresh lifecycle (docs/wg/platform/hosted-ai.md). The Rust CLI embeds its catalogue and does not refresh it at runtime: regenerate its assets and ship a new CLI version for updated discovery data. Do not assume a remote catalogue update revokes an installed binary's bundled knowledge. Hosted authorization remains a separate runtime boundary. Preserve schema-1 membership and legacy fields when publishing; installed snapshot clients ignore additive preferences. The v1 snapshot still has broad GG/BYOK membership and per-family fallback behavior; adapter support and authorization remain independent checks.

Release dates and provenance

Every bundled entry carries a release object:

{
  "date": "2026-07-09",
  "basis": "model",
  "source_url": "https://vendor.example/release-note"
}

Use a YYYY-MM-DD date, or null only when an endpoint day is unknown. basis is model or provider_endpoint.

The date means the earliest day the exact named model or variant became broadly available. A public preview counts; a closed, invitation-only, or limited preview does not. This is intrinsic model metadata, so adding a provider binding does not change a basis: "model" release. Use basis: "provider_endpoint" only when the release fact describes a serving route because no exact upstream model launch can be established. An endpoint-shaped card may still use basis: "model" when its exact underlying model and launch are documented.

Do not substitute any of these:

• snapshot generated_at
• the date Grida added the card
• the date one provider added a binding
• a later GA date when an exact public preview date exists
• an API object's opaque created timestamp

Source priority for release facts:

1. Vendor release note, changelog, announcement, or model card that names the exact variant.
2. Vendor-maintained repository or official provider documentation for the exact endpoint.
3. First-party vendor social announcement when no durable release page exists.
4. Serving-provider history, only for basis: "provider_endpoint" or when the vendor has no usable record.
5. models.dev only to discover candidates; verify its date against one of the sources above.

If no authoritative source establishes the exact day, keep date: null with an HTTPS source showing the endpoint's history. Never infer a day from search-result ordering, repository commit time, or Grida history. Base snapshot types keep the field optional solely for older snapshots and custom models; every bundled card must include it, and tests enforce valid calendar dates, complete provenance, and the narrow null rule.