--- name: add-model description: Add a new LLM model to apps/sim/providers/models.ts with specs verified against the provider's live API docs (no hallucination) argument-hint: <provider> <model-id> [docs-url] ---

# Add Model Skill

You add a new model entry to `apps/sim/providers/models.ts`. **Every numeric and capability claim MUST be derived from a live web fetch of the provider's official docs in this session.** Marketing emails, training data, and your prior knowledge are not sources of truth — they routinely hallucinate pricing, context windows, and capability lists.

## Hard rules (do not skip)

1. **Live-fetch or refuse.** Before writing the entry, you must successfully WebFetch the provider's official models/pricing page in this session. If you cannot reach an authoritative source for any field, **mark the field as UNVERIFIED in your report and ask the user before guessing**. Never fill in pricing or capabilities from memory. 2. **Two-source rule for pricing.** Cross-check input/output/cached pricing against at least one secondary source (OpenRouter, Artificial Analysis, CloudPrice, mem0, intuitionlabs). If sources disagree, the provider's own docs win — but flag the disagreement. 3. **Read the code before setting capability flags.** Capability flags are dead unless the provider's implementation under `apps/sim/providers/{provider}/` actually consumes them (see Consumption Matrix below). Setting a flag the provider ignores is a silent bug. 4. **Cite every fact.** Your final report must list the URL each value came from. No URL → not verified.

## Your Task

1. Identify provider and model id from user args 2. Live-fetch official docs + pricing page + capability/parameter pages + at least one secondary source 3. Apply the Consumption Matrix to know which capability flags are real 4. Read 2-3 sibling entries in `models.ts` and match their pattern exactly 5. Check the repo-side touchpoints that are NOT data-driven (hosted-key billing, tests, provider code) 6. Insert the entry, run `bun run lint`, print the verification report

## Step 1: Live source-of-truth lookup

In priority order — fetch all that exist for the provider:

| Provider | Models index | Pricing | Reasoning/parameter caveats | |---|---|---|---| | OpenAI | platform.openai.com/docs/models | openai.com/api/pricing | platform.openai.com/docs/guides/reasoning | | Anthropic | platform.claude.com/docs/en/about-claude/models/overview | claude.com/pricing (API section) | platform.claude.com/docs/en/build-with-claude/extended-thinking | | Google (Gemini) | ai.google.dev/gemini-api/docs/models | ai.google.dev/pricing | ai.google.dev/gemini-api/docs/thinking | | xAI | docs.x.ai/developers/models | docs.x.ai/developers/models (per-model detail page) | docs.x.ai/developers/model-capabilities/text/reasoning | | Mistral | docs.mistral.ai/getting-started/models/models_overview | mistral.ai/pricing | n/a | | DeepSeek | api-docs.deepseek.com/quick_start/pricing | same | api-docs.deepseek.com/guides/reasoning_model | | Groq | console.groq.com/docs/models | groq.com/pricing | n/a | | Cerebras | inference-docs.cerebras.ai/models | cerebras.ai/pricing | n/a |

Secondary verification (use at least one): `openrouter.ai/<provider>/<model>`, `artificialanalysis.ai/models/<model>`, `cloudprice.net/models/<provider>-<model>`.

Use a precise WebFetch prompt: *"Extract for {model_id}: exact model id string, context window in tokens, input price per 1M, cached input price per 1M, output price per 1M, max output tokens, supported reasoning effort levels, accepted parameters (temperature, top_p), release date. Do not fill in fields you cannot find."*

## Step 2: Consumption Matrix (which provider honors which capability)

| Capability | Honored by | Effect if set elsewhere | |---|---|---| | `temperature` | All providers (passed through if set) | Safe but inert on always-reasoning models that reject it | | `toolUsageControl` | All providers (provider-level, not per-model) | n/a — set on `ProviderDefinition`, not models | | `reasoningEffort` | `openai/core.ts`, `azure-openai`, `xai`, `deepseek`, `groq`, `zai`, `meta`, `litellm` (each `index.ts`) | Not read by anthropic/gemini (they use `thinking`) or by mistral, cerebras, openrouter, fireworks, vertex — re-grep before assuming | | `verbosity` | `openai/core.ts`, `azure-openai/index.ts` only | Dead elsewhere | | `thinking` | `anthropic/core.ts`, `gemini/core.ts`; `deepseek`, `groq`, `zai`, `kimi` (each `index.ts`) read the resolved `thinkingLevel` | Dead elsewhere | | `thinking.streamed` | Docs generator + `getThinkingStreamVisibility` (`models.ts`); `anthropic/core.ts` uses `'summary'` to request `display: 'summarized'` on agent-events runs | **Mandatory on Anthropic-family thinking models** (`agent-stream-docs:check` fails without it); other families fall back to provider defaults | | `nativeStructuredOutputs` | `anthropic/core.ts`, `bedrock/index.ts` (via `models.ts` `supportsNativeStructuredOutputs`, which reads the flag) | Dead elsewhere — fireworks/baseten/together/openrouter call their own provider-level `supportsNativeStructuredOutputs` that ignores the model flag (always on, always off, or OpenRouter API metadata) | | `maxOutputTokens` | Read by UI + executor for token estimation | Always meaningful — set if provider documents a cap | | `computerUse` | `providers/utils.ts` (`getComputerUseModels` → `computerUseModels` routing) | Set only on actual computer-use SKUs | | `deepResearch` | UI flag for routing to deep-research SKUs | Set only on actual deep-research model IDs | | `memory: false` | Conversation persistence opt-out | Set only when model genuinely cannot maintain history (e.g., deep-research) |

**Always re-grep before relying on this table** — the codebase moves:

```bash rg "reasoningEffort|reasoning_effort" apps/sim/providers/<provider>/ rg "verbosity" apps/sim/providers/<provider>/ rg "request\.thinking|thinking:" apps/sim/providers/<provider>/ rg "supportsNativeStructuredOutputs|nativeStructuredOutputs" apps/sim/providers/<provider>/ ```

## Step 3: Match the provider's existing entry pattern

Open `apps/sim/providers/models.ts`, find `PROVIDER_DEFINITIONS[<provider>].models`, read 2-3 sibling entries. Match field order exactly:

```ts { id: '<exact-api-id>', pricing: { input: <number>, cachedInput: <number>, // omit if provider doesn't offer caching output: <number>, updatedAt: '<today YYYY-MM-DD>', }, capabilities: { // only flags the provider actually consumes — see matrix }, contextWindow: <tokens>, releaseDate: '<YYYY-MM-DD>', recommended: true, // only if new flagship; ask user before swapping speedOptimized: true, // only on smallest/fastest tier deprecated: true, // only on retired models } ```

### Reseller providers (azure-openai, azure-anthropic, vertex, bedrock, openrouter)

Model id MUST be prefixed: `azure/`, `azure-anthropic/`, `vertex/`, `bedrock/`, `openrouter/`. Pricing usually mirrors the upstream provider but verify on the reseller's own pricing page.

### Insertion order

Within a family, newest first (as the existing entries are ordered). Across families, biggest/flagship at top of list.

### `recommended` / `speedOptimized`

- At most one or two `recommended: true` per provider — the current flagship(s). - If you're adding a new flagship, ask the user before removing `recommended` from the previous flagship. Never silently flip it. - `speedOptimized: true` only on the smallest/fastest tier (nano, flash-lite, haiku class). - Use today's date for `pricing.updatedAt`; never copy a sibling's. - `cachedInput` is an explicit documented number — never derived from `input` (ratios vary by provider).

## Step 4: Repo-side touchpoints beyond the entry

Adding the `models.ts` entry is most of the job because nearly every consumer is **data-driven** and picks the model up automatically: the ~40 query helpers in `models.ts` / `providers/utils.ts`, the public `/models` catalog (`app/(landing)/models/utils.ts` iterates `PROVIDER_DEFINITIONS`), the agent-block model dropdown, and copilot's `isKnownModelId` / `suggestModelIdsForUnknownModel` validation. The touchpoints below are the exceptions — they are **not** data-driven, so check each one.

### Hosted = auto-billed, by provider

`getHostedModels()` in `apps/sim/providers/models.ts` returns the model IDs served with Sim's rotating hosted key and billed to the workspace via `shouldBillModelUsage()` (`providers/utils.ts`). It builds that list by expanding whole providers (`getProviderModels('openai')`, `'anthropic'`, `'google'`, and others) plus the static Fireworks catalog, so any model added under one of those providers is hosted automatically. Read the function before inserting — the provider set changes. Before you insert:

- **If the model should be BYOK-only / never-billed**, do not add it under a provider that `getHostedModels()` expands — that silently enrolls it in hosted billing. After inserting, verify with `getHostedModels().includes('<new-model-id>')` (a one-line `bun -e` or the assertion in `providers/utils.test.ts`). Confirm hosting/billing intent with the user. (Ollama Cloud is a deliberately separate `isReseller` provider specifically to stay BYOK-only/never-billed.) - **If the model should be hosted**, the deployment must actually have a key for it — the provider's `{PREFIX}_COUNT` / `{PREFIX}_1..N` env vars must be set, or hosted runs fail at execution time. - State the hosted/billing status explicitly in the verification report.

### Tests with hardcoded model IDs

`bun run lint` does **not** run tests. A few tests assert specific model IDs and can break or need updating when you touch a hosted or flagship model:

- `apps/sim/providers/utils.test.ts` — asserts membership of `getHostedModels()` / `shouldBillModelUsage()` - `apps/sim/providers/index.test.ts` and serializer tests — reference concrete model IDs

```bash rg "<new-model-id>|getHostedModels|shouldBillModelUsage" apps/sim/providers/*.test.ts ```

If anything matches, run the affected provider tests and update assertions as needed.

### New API behavior is NOT data-driven

The Consumption Matrix (Step 2) tells you which capability *flags* are honored by existing provider code. But if the new model needs **net-new** request handling that the provider doesn't implement yet — a new beta header, a new thinking/reasoning encoding, a Responses-API quirk — you must edit `apps/sim/providers/<provider>/core.ts` / `index.ts`. Setting a flag whose behavior isn't implemented is a silent no-op. When you do edit provider code, reuse the shared helpers rather than hand-rolling: streaming responses are assembled via `createStreamingExecution` (`@/providers/streaming-execution`) and tool schemas via `adaptOpenAIChatToolSchema` / `adaptAnthropicToolSchema` (`@/providers/tool-schema-adapter`).

### Thinking/reasoning models: `streamed` visibility + generated docs

If the entry has `capabilities.thinking` or `capabilities.reasoningEffort`, it appears in the autogenerated "Streamed thinking and tool calls" table on the Agent block docs page:

- **Anthropic-family (`anthropic`, `azure-anthropic`) thinking models MUST declare `capabilities.thinking.streamed`** (`'full' | 'summary' | 'none'`). Verify against Anthropic's current thinking-display and streaming docs: visible thinking returned by the API is summarized, including when Sim opts models whose default display is `omitted` into `display: 'summarized'` on agent-events runs, so current Claude thinking models use `'summary'`. Use `'full'` only if future official API docs explicitly guarantee raw thinking deltas. `bun run agent-stream-docs:check` (CI) fails if the field is missing. - Other families usually omit the field and inherit the provider default in `getThinkingStreamVisibility` (Gemini/OpenAI → summaries; Bedrock/Meta → none; OpenAI-compatible vendors with documented reasoning fields → full deltas). Set it explicitly only when the mo

--- name: add-model description: Add a new LLM model to apps/sim/providers/models.ts with specs verified against the provider's live API docs (no hallucination) argument-hint: <provider> <model-id> [docs-url] ---

# Add Model Skill

You add a new model entry to `apps/sim/providers/models.ts`. **Every numeric and capability claim MUST be derived from a live web fetch of the provider's official docs in this session.** Marketing emails, training data, and your prior knowledge are not sources of truth — they routinely hallucinate pricing, context windows, and capability lists.

## Hard rules (do not skip)

1. **Live-fetch or refuse.** Before writing the entry, you must successfully WebFetch the provider's official models/pricing page in this session. If you cannot reach an authoritative source for any field, **mark the field as UNVERIFIED in your report and ask the user before guessing**. Never fill in pricing or capabilities from memory. 2. **Two-source rule for pricing.** Cross-check input/output/cached pricing against at least one secondary source (OpenRouter, Artificial Analysis, CloudPrice, mem0, intuitionlabs). If sources disagree, the provider's own docs win — but flag the disagreement. 3. **Read the code before setting capability flags.** Capability flags are dead unless the provider's implementation under `apps/sim/providers/{provider}/` actually consumes them (see Consumption Matrix below). Setting a flag the provider ignores is a silent bug. 4. **Cite every fact.** Your final report must list the URL each value came from. No URL → not verified.

## Your Task

1. Identify provider and model id from user args 2. Live-fetch official docs + pricing page + capability/parameter pages + at least one secondary source 3. Apply the Consumption Matrix to know which capability flags are real 4. Read 2-3 sibling entries in `models.ts` and match their pattern exactly 5. Check the repo-side touchpoints that are NOT data-driven (hosted-key billing, tests, provider code) 6. Insert the entry, run `bun run lint`, print the verification report

## Step 1: Live source-of-truth lookup

In priority order — fetch all that exist for the provider:

| Provider | Models index | Pricing | Reasoning/parameter caveats | |---|---|---|---| | OpenAI | platform.openai.com/docs/models | openai.com/api/pricing | platform.openai.com/docs/guides/reasoning | | Anthropic | platform.claude.com/docs/en/about-claude/models/overview | claude.com/pricing (API section) | platform.claude.com/docs/en/build-with-claude/extended-thinking | | Google (Gemini) | ai.google.dev/gemini-api/docs/models | ai.google.dev/pricing | ai.google.dev/gemini-api/docs/thinking | | xAI | docs.x.ai/developers/models | docs.x.ai/developers/models (per-model detail page) | docs.x.ai/developers/model-capabilities/text/reasoning | | Mistral | docs.mistral.ai/getting-started/models/models_overview | mistral.ai/pricing | n/a | | DeepSeek | api-docs.deepseek.com/quick_start/pricing | same | api-docs.deepseek.com/guides/reasoning_model | | Groq | console.groq.com/docs/models | groq.com/pricing | n/a | | Cerebras | inference-docs.cerebras.ai/models | cerebras.ai/pricing | n/a |

Secondary verification (use at least one): `openrouter.ai/<provider>/<model>`, `artificialanalysis.ai/models/<model>`, `cloudprice.net/models/<provider>-<model>`.

Use a precise WebFetch prompt: *"Extract for {model_id}: exact model id string, context window in tokens, input price per 1M, cached input price per 1M, output price per 1M, max output tokens, supported reasoning effort levels, accepted parameters (temperature, top_p), release date. Do not fill in fields you cannot find."*

## Step 2: Consumption Matrix (which provider honors which capability)

| Capability | Honored by | Effect if set elsewhere | |---|---|---| | `temperature` | All providers (passed through if set) | Safe but inert on always-reasoning models that reject it | | `toolUsageControl` | All providers (provider-level, not per-model) | n/a — set on `ProviderDefinition`, not models | | `reasoningEffort` | `openai/core.ts`, `azure-openai`, `xai`, `deepseek`, `groq`, `zai`, `meta`, `litellm` (each `index.ts`) | Not read by anthropic/gemini (they use `thinking`) or by mistral, cerebras, openrouter, fireworks, vertex — re-grep before assuming | | `verbosity` | `openai/core.ts`, `azure-openai/index.ts` only | Dead elsewhere | | `thinking` | `anthropic/core.ts`, `gemini/core.ts`; `deepseek`, `groq`, `zai`, `kimi` (each `index.ts`) read the resolved `thinkingLevel` | Dead elsewhere | | `thinking.streamed` | Docs generator + `getThinkingStreamVisibility` (`models.ts`); `anthropic/core.ts` uses `'summary'` to request `display: 'summarized'` on agent-events runs | **Mandatory on Anthropic-family thinking models** (`agent-stream-docs:check` fails without it); other families fall back to provider defaults | | `nativeStructuredOutputs` | `anthropic/core.ts`, `bedrock/index.ts` (via `models.ts` `supportsNativeStructuredOutputs`, which reads the flag) | Dead elsewhere — fireworks/baseten/together/openrouter call their own provider-level `supportsNativeStructuredOutputs` that ignores the model flag (always on, always off, or OpenRouter API metadata) | | `maxOutputTokens` | Read by UI + executor for token estimation | Always meaningful — set if provider documents a cap | | `computerUse` | `providers/utils.ts` (`getComputerUseModels` → `computerUseModels` routing) | Set only on actual computer-use SKUs | | `deepResearch` | UI flag for routing to deep-research SKUs | Set only on actual deep-research model IDs | | `memory: false` | Conversation persistence opt-out | Set only when model genuinely cannot maintain history (e.g., deep-research) |

**Always re-grep before relying on this table** — the codebase moves:

```bash rg "reasoningEffort|reasoning_effort" apps/sim/providers/<provider>/ rg "verbosity" apps/sim/providers/<provider>/ rg "request\.thinking|thinking:" apps/sim/providers/<provider>/ rg "supportsNativeStructuredOutputs|nativeStructuredOutputs" apps/sim/providers/<provider>/ ```

## Step 3: Match the provider's existing entry pattern

Open `apps/sim/providers/models.ts`, find `PROVIDER_DEFINITIONS[<provider>].models`, read 2-3 sibling entries. Match field order exactly:

```ts { id: '<exact-api-id>', pricing: { input: <number>, cachedInput: <number>, // omit if provider doesn't offer caching output: <number>, updatedAt: '<today YYYY-MM-DD>', }, capabilities: { // only flags the provider actually consumes — see matrix }, contextWindow: <tokens>, releaseDate: '<YYYY-MM-DD>', recommended: true, // only if new flagship; ask user before swapping speedOptimized: true, // only on smallest/fastest tier deprecated: true, // only on retired models } ```

### Reseller providers (azure-openai, azure-anthropic, vertex, bedrock, openrouter)

Model id MUST be prefixed: `azure/`, `azure-anthropic/`, `vertex/`, `bedrock/`, `openrouter/`. Pricing usually mirrors the upstream provider but verify on the reseller's own pricing page.

### Insertion order

Within a family, newest first (as the existing entries are ordered). Across families, biggest/flagship at top of list.

### `recommended` / `speedOptimized`

- At most one or two `recommended: true` per provider — the current flagship(s). - If you're adding a new flagship, ask the user before removing `recommended` from the previous flagship. Never silently flip it. - `speedOptimized: true` only on the smallest/fastest tier (nano, flash-lite, haiku class). - Use today's date for `pricing.updatedAt`; never copy a sibling's. - `cachedInput` is an explicit documented number — never derived from `input` (ratios vary by provider).

## Step 4: Repo-side touchpoints beyond the entry

Adding the `models.ts` entry is most of the job because nearly every consumer is **data-driven** and picks the model up automatically: the ~40 query helpers in `models.ts` / `providers/utils.ts`, the public `/models` catalog (`app/(landing)/models/utils.ts` iterates `PROVIDER_DEFINITIONS`), the agent-block model dropdown, and copilot's `isKnownModelId` / `suggestModelIdsForUnknownModel` validation. The touchpoints below are the exceptions — they are **not** data-driven, so check each one.

### Hosted = auto-billed, by provider

`getHostedModels()` in `apps/sim/providers/models.ts` returns the model IDs served with Sim's rotating hosted key and billed to the workspace via `shouldBillModelUsage()` (`providers/utils.ts`). It builds that list by expanding whole providers (`getProviderModels('openai')`, `'anthropic'`, `'google'`, and others) plus the static Fireworks catalog, so any model added under one of those providers is hosted automatically. Read the function before inserting — the provider set changes. Before you insert:

- **If the model should be BYOK-only / never-billed**, do not add it under a provider that `getHostedModels()` expands — that silently enrolls it in hosted billing. After inserting, verify with `getHostedModels().includes('<new-model-id>')` (a one-line `bun -e` or the assertion in `providers/utils.test.ts`). Confirm hosting/billing intent with the user. (Ollama Cloud is a deliberately separate `isReseller` provider specifically to stay BYOK-only/never-billed.) - **If the model should be hosted**, the deployment must actually have a key for it — the provider's `{PREFIX}_COUNT` / `{PREFIX}_1..N` env vars must be set, or hosted runs fail at execution time. - State the hosted/billing status explicitly in the verification report.

### Tests with hardcoded model IDs

`bun run lint` does **not** run tests. A few tests assert specific model IDs and can break or need updating when you touch a hosted or flagship model:

- `apps/sim/providers/utils.test.ts` — asserts membership of `getHostedModels()` / `shouldBillModelUsage()` - `apps/sim/providers/index.test.ts` and serializer tests — reference concrete model IDs

```bash rg "<new-model-id>|getHostedModels|shouldBillModelUsage" apps/sim/providers/*.test.ts ```

If anything matches, run the affected provider tests and update assertions as needed.

### New API behavior is NOT data-driven

The Consumption Matrix (Step 2) tells you which capability *flags* are honored by existing provider code. But if the new model needs **net-new** request handling that the provider doesn't implement yet — a new beta header, a new thinking/reasoning encoding, a Responses-API quirk — you must edit `apps/sim/providers/<provider>/core.ts` / `index.ts`. Setting a flag whose behavior isn't implemented is a silent no-op. When you do edit provider code, reuse the shared helpers rather than hand-rolling: streaming responses are assembled via `createStreamingExecution` (`@/providers/streaming-execution`) and tool schemas via `adaptOpenAIChatToolSchema` / `adaptAnthropicToolSchema` (`@/providers/tool-schema-adapter`).

### Thinking/reasoning models: `streamed` visibility + generated docs

If the entry has `capabilities.thinking` or `capabilities.reasoningEffort`, it appears in the autogenerated "Streamed thinking and tool calls" table on the Agent block docs page:

- **Anthropic-family (`anthropic`, `azure-anthropic`) thinking models MUST declare `capabilities.thinking.streamed`** (`'full' | 'summary' | 'none'`). Verify against Anthropic's current thinking-display and streaming docs: visible thinking returned by the API is summarized, including when Sim opts models whose default display is `omitted` into `display: 'summarized'` on agent-events runs, so current Claude thinking models use `'summary'`. Use `'full'` only if future official API docs explicitly guarantee raw thinking deltas. `bun run agent-stream-docs:check` (CI) fails if the field is missing. - Other families usually omit the field and inherit the provider default in `getThinkingStreamVisibility` (Gemini/OpenAI → summaries; Bedrock/Meta → none; OpenAI-compatible vendors with documented reasoning fields → full deltas). Set it explicitly only when the mo

--- name: add-model description: Add a new LLM model to apps/sim/providers/models.ts with specs verified against the provider's live API docs (no hallucination) argument-hint: <provider> <model-id> [docs-url] ---

# Add Model Skill

You add a new model entry to `apps/sim/providers/models.ts`. **Every numeric and capability claim MUST be derived from a live web fetch of the provider's official docs in this session.** Marketing emails, training data, and your prior knowledge are not sources of truth — they routinely hallucinate pricing, context windows, and capability lists.

## Hard rules (do not skip)

1. **Live-fetch or refuse.** Before writing the entry, you must successfully WebFetch the provider's official models/pricing page in this session. If you cannot reach an authoritative source for any field, **mark the field as UNVERIFIED in your report and ask the user before guessing**. Never fill in pricing or capabilities from memory. 2. **Two-source rule for pricing.** Cross-check input/output/cached pricing against at least one secondary source (OpenRouter, Artificial Analysis, CloudPrice, mem0, intuitionlabs). If sources disagree, the provider's own docs win — but flag the disagreement. 3. **Read the code before setting capability flags.** Capability flags are dead unless the provider's implementation under `apps/sim/providers/{provider}/` actually consumes them (see Consumption Matrix below). Setting a flag the provider ignores is a silent bug. 4. **Cite every fact.** Your final report must list the URL each value came from. No URL → not verified.

## Your Task

1. Identify provider and model id from user args 2. Live-fetch official docs + pricing page + capability/parameter pages + at least one secondary source 3. Apply the Consumption Matrix to know which capability flags are real 4. Read 2-3 sibling entries in `models.ts` and match their pattern exactly 5. Check the repo-side touchpoints that are NOT data-driven (hosted-key billing, tests, provider code) 6. Insert the entry, run `bun run lint`, print the verification report

## Step 1: Live source-of-truth lookup

In priority order — fetch all that exist for the provider:

| Provider | Models index | Pricing | Reasoning/parameter caveats | |---|---|---|---| | OpenAI | platform.openai.com/docs/models | openai.com/api/pricing | platform.openai.com/docs/guides/reasoning | | Anthropic | platform.claude.com/docs/en/about-claude/models/overview | claude.com/pricing (API section) | platform.claude.com/docs/en/build-with-claude/extended-thinking | | Google (Gemini) | ai.google.dev/gemini-api/docs/models | ai.google.dev/pricing | ai.google.dev/gemini-api/docs/thinking | | xAI | docs.x.ai/developers/models | docs.x.ai/developers/models (per-model detail page) | docs.x.ai/developers/model-capabilities/text/reasoning | | Mistral | docs.mistral.ai/getting-started/models/models_overview | mistral.ai/pricing | n/a | | DeepSeek | api-docs.deepseek.com/quick_start/pricing | same | api-docs.deepseek.com/guides/reasoning_model | | Groq | console.groq.com/docs/models | groq.com/pricing | n/a | | Cerebras | inference-docs.cerebras.ai/models | cerebras.ai/pricing | n/a |

Secondary verification (use at least one): `openrouter.ai/<provider>/<model>`, `artificialanalysis.ai/models/<model>`, `cloudprice.net/models/<provider>-<model>`.

Use a precise WebFetch prompt: *"Extract for {model_id}: exact model id string, context window in tokens, input price per 1M, cached input price per 1M, output price per 1M, max output tokens, supported reasoning effort levels, accepted parameters (temperature, top_p), release date. Do not fill in fields you cannot find."*

## Step 2: Consumption Matrix (which provider honors which capability)

| Capability | Honored by | Effect if set elsewhere | |---|---|---| | `temperature` | All providers (passed through if set) | Safe but inert on always-reasoning models that reject it | | `toolUsageControl` | All providers (provider-level, not per-model) | n/a — set on `ProviderDefinition`, not models | | `reasoningEffort` | `openai/core.ts`, `azure-openai`, `xai`, `deepseek`, `groq`, `zai`, `meta`, `litellm` (each `index.ts`) | Not read by anthropic/gemini (they use `thinking`) or by mistral, cerebras, openrouter, fireworks, vertex — re-grep before assuming | | `verbosity` | `openai/core.ts`, `azure-openai/index.ts` only | Dead elsewhere | | `thinking` | `anthropic/core.ts`, `gemini/core.ts`; `deepseek`, `groq`, `zai`, `kimi` (each `index.ts`) read the resolved `thinkingLevel` | Dead elsewhere | | `thinking.streamed` | Docs generator + `getThinkingStreamVisibility` (`models.ts`); `anthropic/core.ts` uses `'summary'` to request `display: 'summarized'` on agent-events runs | **Mandatory on Anthropic-family thinking models** (`agent-stream-docs:check` fails without it); other families fall back to provider defaults | | `nativeStructuredOutputs` | `anthropic/core.ts`, `bedrock/index.ts` (via `models.ts` `supportsNativeStructuredOutputs`, which reads the flag) | Dead elsewhere — fireworks/baseten/together/openrouter call their own provider-level `supportsNativeStructuredOutputs` that ignores the model flag (always on, always off, or OpenRouter API metadata) | | `maxOutputTokens` | Read by UI + executor for token estimation | Always meaningful — set if provider documents a cap | | `computerUse` | `providers/utils.ts` (`getComputerUseModels` → `computerUseModels` routing) | Set only on actual computer-use SKUs | | `deepResearch` | UI flag for routing to deep-research SKUs | Set only on actual deep-research model IDs | | `memory: false` | Conversation persistence opt-out | Set only when model genuinely cannot maintain history (e.g., deep-research) |

**Always re-grep before relying on this table** — the codebase moves:

```bash rg "reasoningEffort|reasoning_effort" apps/sim/providers/<provider>/ rg "verbosity" apps/sim/providers/<provider>/ rg "request\.thinking|thinking:" apps/sim/providers/<provider>/ rg "supportsNativeStructuredOutputs|nativeStructuredOutputs" apps/sim/providers/<provider>/ ```

## Step 3: Match the provider's existing entry pattern

Open `apps/sim/providers/models.ts`, find `PROVIDER_DEFINITIONS[<provider>].models`, read 2-3 sibling entries. Match field order exactly:

```ts { id: '<exact-api-id>', pricing: { input: <number>, cachedInput: <number>, // omit if provider doesn't offer caching output: <number>, updatedAt: '<today YYYY-MM-DD>', }, capabilities: { // only flags the provider actually consumes — see matrix }, contextWindow: <tokens>, releaseDate: '<YYYY-MM-DD>', recommended: true, // only if new flagship; ask user before swapping speedOptimized: true, // only on smallest/fastest tier deprecated: true, // only on retired models } ```

### Reseller providers (azure-openai, azure-anthropic, vertex, bedrock, openrouter)

Model id MUST be prefixed: `azure/`, `azure-anthropic/`, `vertex/`, `bedrock/`, `openrouter/`. Pricing usually mirrors the upstream provider but verify on the reseller's own pricing page.

### Insertion order

Within a family, newest first (as the existing entries are ordered). Across families, biggest/flagship at top of list.

### `recommended` / `speedOptimized`

- At most one or two `recommended: true` per provider — the current flagship(s). - If you're adding a new flagship, ask the user before removing `recommended` from the previous flagship. Never silently flip it. - `speedOptimized: true` only on the smallest/fastest tier (nano, flash-lite, haiku class). - Use today's date for `pricing.updatedAt`; never copy a sibling's. - `cachedInput` is an explicit documented number — never derived from `input` (ratios vary by provider).

## Step 4: Repo-side touchpoints beyond the entry

Adding the `models.ts` entry is most of the job because nearly every consumer is **data-driven** and picks the model up automatically: the ~40 query helpers in `models.ts` / `providers/utils.ts`, the public `/models` catalog (`app/(landing)/models/utils.ts` iterates `PROVIDER_DEFINITIONS`), the agent-block model dropdown, and copilot's `isKnownModelId` / `suggestModelIdsForUnknownModel` validation. The touchpoints below are the exceptions — they are **not** data-driven, so check each one.

### Hosted = auto-billed, by provider

`getHostedModels()` in `apps/sim/providers/models.ts` returns the model IDs served with Sim's rotating hosted key and billed to the workspace via `shouldBillModelUsage()` (`providers/utils.ts`). It builds that list by expanding whole providers (`getProviderModels('openai')`, `'anthropic'`, `'google'`, and others) plus the static Fireworks catalog, so any model added under one of those providers is hosted automatically. Read the function before inserting — the provider set changes. Before you insert:

- **If the model should be BYOK-only / never-billed**, do not add it under a provider that `getHostedModels()` expands — that silently enrolls it in hosted billing. After inserting, verify with `getHostedModels().includes('<new-model-id>')` (a one-line `bun -e` or the assertion in `providers/utils.test.ts`). Confirm hosting/billing intent with the user. (Ollama Cloud is a deliberately separate `isReseller` provider specifically to stay BYOK-only/never-billed.) - **If the model should be hosted**, the deployment must actually have a key for it — the provider's `{PREFIX}_COUNT` / `{PREFIX}_1..N` env vars must be set, or hosted runs fail at execution time. - State the hosted/billing status explicitly in the verification report.

### Tests with hardcoded model IDs

`bun run lint` does **not** run tests. A few tests assert specific model IDs and can break or need updating when you touch a hosted or flagship model:

- `apps/sim/providers/utils.test.ts` — asserts membership of `getHostedModels()` / `shouldBillModelUsage()` - `apps/sim/providers/index.test.ts` and serializer tests — reference concrete model IDs

```bash rg "<new-model-id>|getHostedModels|shouldBillModelUsage" apps/sim/providers/*.test.ts ```

If anything matches, run the affected provider tests and update assertions as needed.

### New API behavior is NOT data-driven

The Consumption Matrix (Step 2) tells you which capability *flags* are honored by existing provider code. But if the new model needs **net-new** request handling that the provider doesn't implement yet — a new beta header, a new thinking/reasoning encoding, a Responses-API quirk — you must edit `apps/sim/providers/<provider>/core.ts` / `index.ts`. Setting a flag whose behavior isn't implemented is a silent no-op. When you do edit provider code, reuse the shared helpers rather than hand-rolling: streaming responses are assembled via `createStreamingExecution` (`@/providers/streaming-execution`) and tool schemas via `adaptOpenAIChatToolSchema` / `adaptAnthropicToolSchema` (`@/providers/tool-schema-adapter`).

### Thinking/reasoning models: `streamed` visibility + generated docs

If the entry has `capabilities.thinking` or `capabilities.reasoningEffort`, it appears in the autogenerated "Streamed thinking and tool calls" table on the Agent block docs page:

- **Anthropic-family (`anthropic`, `azure-anthropic`) thinking models MUST declare `capabilities.thinking.streamed`** (`'full' | 'summary' | 'none'`). Verify against Anthropic's current thinking-display and streaming docs: visible thinking returned by the API is summarized, including when Sim opts models whose default display is `omitted` into `display: 'summarized'` on agent-events runs, so current Claude thinking models use `'summary'`. Use `'full'` only if future official API docs explicitly guarantee raw thinking deltas. `bun run agent-stream-docs:check` (CI) fails if the field is missing. - Other families usually omit the field and inherit the provider default in `getThinkingStreamVisibility` (Gemini/OpenAI → summaries; Bedrock/Meta → none; OpenAI-compatible vendors with documented reasoning fields → full deltas). Set it explicitly only when the mo

--- name: add-model description: Add a new LLM model to apps/sim/providers/models.ts with specs verified against the provider's live API docs (no hallucination) argument-hint: <provider> <model-id> [docs-url] ---

# Add Model Skill

You add a new model entry to `apps/sim/providers/models.ts`. **Every numeric and capability claim MUST be derived from a live web fetch of the provider's official docs in this session.** Marketing emails, training data, and your prior knowledge are not sources of truth — they routinely hallucinate pricing, context windows, and capability lists.

## Hard rules (do not skip)

1. **Live-fetch or refuse.** Before writing the entry, you must successfully WebFetch the provider's official models/pricing page in this session. If you cannot reach an authoritative source for any field, **mark the field as UNVERIFIED in your report and ask the user before guessing**. Never fill in pricing or capabilities from memory. 2. **Two-source rule for pricing.** Cross-check input/output/cached pricing against at least one secondary source (OpenRouter, Artificial Analysis, CloudPrice, mem0, intuitionlabs). If sources disagree, the provider's own docs win — but flag the disagreement. 3. **Read the code before setting capability flags.** Capability flags are dead unless the provider's implementation under `apps/sim/providers/{provider}/` actually consumes them (see Consumption Matrix below). Setting a flag the provider ignores is a silent bug. 4. **Cite every fact.** Your final report must list the URL each value came from. No URL → not verified.

## Your Task

1. Identify provider and model id from user args 2. Live-fetch official docs + pricing page + capability/parameter pages + at least one secondary source 3. Apply the Consumption Matrix to know which capability flags are real 4. Read 2-3 sibling entries in `models.ts` and match their pattern exactly 5. Check the repo-side touchpoints that are NOT data-driven (hosted-key billing, tests, provider code) 6. Insert the entry, run `bun run lint`, print the verification report

## Step 1: Live source-of-truth lookup

In priority order — fetch all that exist for the provider:

| Provider | Models index | Pricing | Reasoning/parameter caveats | |---|---|---|---| | OpenAI | platform.openai.com/docs/models | openai.com/api/pricing | platform.openai.com/docs/guides/reasoning | | Anthropic | platform.claude.com/docs/en/about-claude/models/overview | claude.com/pricing (API section) | platform.claude.com/docs/en/build-with-claude/extended-thinking | | Google (Gemini) | ai.google.dev/gemini-api/docs/models | ai.google.dev/pricing | ai.google.dev/gemini-api/docs/thinking | | xAI | docs.x.ai/developers/models | docs.x.ai/developers/models (per-model detail page) | docs.x.ai/developers/model-capabilities/text/reasoning | | Mistral | docs.mistral.ai/getting-started/models/models_overview | mistral.ai/pricing | n/a | | DeepSeek | api-docs.deepseek.com/quick_start/pricing | same | api-docs.deepseek.com/guides/reasoning_model | | Groq | console.groq.com/docs/models | groq.com/pricing | n/a | | Cerebras | inference-docs.cerebras.ai/models | cerebras.ai/pricing | n/a |

Secondary verification (use at least one): `openrouter.ai/<provider>/<model>`, `artificialanalysis.ai/models/<model>`, `cloudprice.net/models/<provider>-<model>`.

Use a precise WebFetch prompt: *"Extract for {model_id}: exact model id string, context window in tokens, input price per 1M, cached input price per 1M, output price per 1M, max output tokens, supported reasoning effort levels, accepted parameters (temperature, top_p), release date. Do not fill in fields you cannot find."*

## Step 2: Consumption Matrix (which provider honors which capability)

| Capability | Honored by | Effect if set elsewhere | |---|---|---| | `temperature` | All providers (passed through if set) | Safe but inert on always-reasoning models that reject it | | `toolUsageControl` | All providers (provider-level, not per-model) | n/a — set on `ProviderDefinition`, not models | | `reasoningEffort` | `openai/core.ts`, `azure-openai`, `xai`, `deepseek`, `groq`, `zai`, `meta`, `litellm` (each `index.ts`) | Not read by anthropic/gemini (they use `thinking`) or by mistral, cerebras, openrouter, fireworks, vertex — re-grep before assuming | | `verbosity` | `openai/core.ts`, `azure-openai/index.ts` only | Dead elsewhere | | `thinking` | `anthropic/core.ts`, `gemini/core.ts`; `deepseek`, `groq`, `zai`, `kimi` (each `index.ts`) read the resolved `thinkingLevel` | Dead elsewhere | | `thinking.streamed` | Docs generator + `getThinkingStreamVisibility` (`models.ts`); `anthropic/core.ts` uses `'summary'` to request `display: 'summarized'` on agent-events runs | **Mandatory on Anthropic-family thinking models** (`agent-stream-docs:check` fails without it); other families fall back to provider defaults | | `nativeStructuredOutputs` | `anthropic/core.ts`, `bedrock/index.ts` (via `models.ts` `supportsNativeStructuredOutputs`, which reads the flag) | Dead elsewhere — fireworks/baseten/together/openrouter call their own provider-level `supportsNativeStructuredOutputs` that ignores the model flag (always on, always off, or OpenRouter API metadata) | | `maxOutputTokens` | Read by UI + executor for token estimation | Always meaningful — set if provider documents a cap | | `computerUse` | `providers/utils.ts` (`getComputerUseModels` → `computerUseModels` routing) | Set only on actual computer-use SKUs | | `deepResearch` | UI flag for routing to deep-research SKUs | Set only on actual deep-research model IDs | | `memory: false` | Conversation persistence opt-out | Set only when model genuinely cannot maintain history (e.g., deep-research) |

**Always re-grep before relying on this table** — the codebase moves:

```bash rg "reasoningEffort|reasoning_effort" apps/sim/providers/<provider>/ rg "verbosity" apps/sim/providers/<provider>/ rg "request\.thinking|thinking:" apps/sim/providers/<provider>/ rg "supportsNativeStructuredOutputs|nativeStructuredOutputs" apps/sim/providers/<provider>/ ```

## Step 3: Match the provider's existing entry pattern

Open `apps/sim/providers/models.ts`, find `PROVIDER_DEFINITIONS[<provider>].models`, read 2-3 sibling entries. Match field order exactly:

```ts { id: '<exact-api-id>', pricing: { input: <number>, cachedInput: <number>, // omit if provider doesn't offer caching output: <number>, updatedAt: '<today YYYY-MM-DD>', }, capabilities: { // only flags the provider actually consumes — see matrix }, contextWindow: <tokens>, releaseDate: '<YYYY-MM-DD>', recommended: true, // only if new flagship; ask user before swapping speedOptimized: true, // only on smallest/fastest tier deprecated: true, // only on retired models } ```

### Reseller providers (azure-openai, azure-anthropic, vertex, bedrock, openrouter)

Model id MUST be prefixed: `azure/`, `azure-anthropic/`, `vertex/`, `bedrock/`, `openrouter/`. Pricing usually mirrors the upstream provider but verify on the reseller's own pricing page.

### Insertion order

Within a family, newest first (as the existing entries are ordered). Across families, biggest/flagship at top of list.

### `recommended` / `speedOptimized`

- At most one or two `recommended: true` per provider — the current flagship(s). - If you're adding a new flagship, ask the user before removing `recommended` from the previous flagship. Never silently flip it. - `speedOptimized: true` only on the smallest/fastest tier (nano, flash-lite, haiku class). - Use today's date for `pricing.updatedAt`; never copy a sibling's. - `cachedInput` is an explicit documented number — never derived from `input` (ratios vary by provider).

## Step 4: Repo-side touchpoints beyond the entry

Adding the `models.ts` entry is most of the job because nearly every consumer is **data-driven** and picks the model up automatically: the ~40 query helpers in `models.ts` / `providers/utils.ts`, the public `/models` catalog (`app/(landing)/models/utils.ts` iterates `PROVIDER_DEFINITIONS`), the agent-block model dropdown, and copilot's `isKnownModelId` / `suggestModelIdsForUnknownModel` validation. The touchpoints below are the exceptions — they are **not** data-driven, so check each one.

### Hosted = auto-billed, by provider

`getHostedModels()` in `apps/sim/providers/models.ts` returns the model IDs served with Sim's rotating hosted key and billed to the workspace via `shouldBillModelUsage()` (`providers/utils.ts`). It builds that list by expanding whole providers (`getProviderModels('openai')`, `'anthropic'`, `'google'`, and others) plus the static Fireworks catalog, so any model added under one of those providers is hosted automatically. Read the function before inserting — the provider set changes. Before you insert:

- **If the model should be BYOK-only / never-billed**, do not add it under a provider that `getHostedModels()` expands — that silently enrolls it in hosted billing. After inserting, verify with `getHostedModels().includes('<new-model-id>')` (a one-line `bun -e` or the assertion in `providers/utils.test.ts`). Confirm hosting/billing intent with the user. (Ollama Cloud is a deliberately separate `isReseller` provider specifically to stay BYOK-only/never-billed.) - **If the model should be hosted**, the deployment must actually have a key for it — the provider's `{PREFIX}_COUNT` / `{PREFIX}_1..N` env vars must be set, or hosted runs fail at execution time. - State the hosted/billing status explicitly in the verification report.

### Tests with hardcoded model IDs

`bun run lint` does **not** run tests. A few tests assert specific model IDs and can break or need updating when you touch a hosted or flagship model:

- `apps/sim/providers/utils.test.ts` — asserts membership of `getHostedModels()` / `shouldBillModelUsage()` - `apps/sim/providers/index.test.ts` and serializer tests — reference concrete model IDs

```bash rg "<new-model-id>|getHostedModels|shouldBillModelUsage" apps/sim/providers/*.test.ts ```

If anything matches, run the affected provider tests and update assertions as needed.

### New API behavior is NOT data-driven

The Consumption Matrix (Step 2) tells you which capability *flags* are honored by existing provider code. But if the new model needs **net-new** request handling that the provider doesn't implement yet — a new beta header, a new thinking/reasoning encoding, a Responses-API quirk — you must edit `apps/sim/providers/<provider>/core.ts` / `index.ts`. Setting a flag whose behavior isn't implemented is a silent no-op. When you do edit provider code, reuse the shared helpers rather than hand-rolling: streaming responses are assembled via `createStreamingExecution` (`@/providers/streaming-execution`) and tool schemas via `adaptOpenAIChatToolSchema` / `adaptAnthropicToolSchema` (`@/providers/tool-schema-adapter`).

### Thinking/reasoning models: `streamed` visibility + generated docs

If the entry has `capabilities.thinking` or `capabilities.reasoningEffort`, it appears in the autogenerated "Streamed thinking and tool calls" table on the Agent block docs page:

- **Anthropic-family (`anthropic`, `azure-anthropic`) thinking models MUST declare `capabilities.thinking.streamed`** (`'full' | 'summary' | 'none'`). Verify against Anthropic's current thinking-display and streaming docs: visible thinking returned by the API is summarized, including when Sim opts models whose default display is `omitted` into `display: 'summarized'` on agent-events runs, so current Claude thinking models use `'summary'`. Use `'full'` only if future official API docs explicitly guarantee raw thinking deltas. `bun run agent-stream-docs:check` (CI) fails if the field is missing. - Other families usually omit the field and inherit the provider default in `getThinkingStreamVisibility` (Gemini/OpenAI → summaries; Bedrock/Meta → none; OpenAI-compatible vendors with documented reasoning fields → full deltas). Set it explicitly only when the mo