@bastani/atomic 0.9.19-alpha.6 → 0.9.19-alpha.8

package/docs/custom-provider.md

@@ -1,3 +1,8 @@
+---
+title: "Custom providers"
+description: "Implement a provider API or OAuth flow Atomic does not ship."
+---
+
 # Custom Providers
 
 Extensions can register custom model providers via `pi.registerProvider()`. This enables:
@@ -7,6 +12,18 @@ Extensions can register custom model providers via `pi.registerProvider()`. This
 - **OAuth/SSO** - Add authentication flows for enterprise providers
 - **Custom APIs** - Implement streaming for non-standard LLM APIs
 
+## Where to go next
+
+This page gets you to a first working provider extension. Each part of the job has its own page:
+
+- [Override an existing provider](/custom-provider/override) — change a provider Atomic already ships.
+- [Register a provider](/custom-provider/registration) — register and unregister a provider, and the API types it implements.
+- [Provider OAuth](/custom-provider/oauth) — login callbacks, credential storage, and dynamic catalog refresh.
+- [Provider streaming API](/custom-provider/streaming) — events, content blocks, tool calls, stop reasons, and usage.
+- [Provider API reference](/custom-provider/api-reference) — provider config and model definition contracts.
+
+If you only need to add a model for an API Atomic already speaks, use [Custom models](/models) instead.
+
 ## Example Extensions
 
 See these complete provider examples:
@@ -18,14 +35,14 @@ See these complete provider examples:
 
 - [Example Extensions](#example-extensions)
 - [Quick Reference](#quick-reference)
-- [Override Existing Provider](#override-existing-provider)
-- [Register New Provider](#register-new-provider)
-- [Unregister Provider](#unregister-provider)
-- [OAuth Support](#oauth-support)
-- [Custom Streaming API](#custom-streaming-api)
+- [Override Existing Provider](/custom-provider/override#override-existing-provider)
+- [Register New Provider](/custom-provider/registration#register-new-provider)
+- [Unregister Provider](/custom-provider/registration#unregister-provider)
+- [OAuth Support](/custom-provider/oauth#oauth-support)
+- [Custom Streaming API](/custom-provider/streaming#custom-streaming-api)
 - [Testing Your Implementation](#testing-your-implementation)
-- [Config Reference](#config-reference)
-- [Model Definition Reference](#model-definition-reference)
+- [Config Reference](/custom-provider/api-reference#config-reference)
+- [Model Definition Reference](/custom-provider/api-reference#model-definition-reference)
 
 ## Quick Reference
 
@@ -63,521 +80,71 @@ The extension factory can also be `async`. For dynamic model discovery, fetch an
 
 ## Override Existing Provider
 
-The simplest use case: redirect an existing provider through a proxy.
-
-```typescript
-// All Anthropic requests now go through your proxy
-pi.registerProvider("anthropic", {
-  baseUrl: "https://proxy.example.com"
-});
-
-// Add custom headers to OpenAI requests
-pi.registerProvider("openai", {
-  headers: {
-    "X-Custom-Header": "value"
-  }
-});
-
-// Both baseUrl and headers
-pi.registerProvider("google", {
-  baseUrl: "https://ai-gateway.corp.com/google",
-  headers: {
-    "X-Corp-Auth": "$CORP_AUTH_TOKEN"  // resolves from env; omit $ for a literal
-  }
-});
-```
-
-When only `baseUrl` and/or `headers` are provided (no `models`), all existing models for that provider are preserved with the new endpoint.
+Moved to [Override an existing provider](/custom-provider/override#override-existing-provider).
 
 ## Register New Provider
 
-To add a completely new provider, specify `models` along with the required configuration.
-
-If the model list comes from a remote endpoint, use an async extension factory:
-
-```typescript
-import type { ExtensionAPI } from "@bastani/atomic";
-
-export default async function (pi: ExtensionAPI) {
-  const response = await fetch("http://localhost:1234/v1/models");
-  const payload = (await response.json()) as {
-    data: Array<{
-      id: string;
-      name?: string;
-      context_window?: number;
-      max_tokens?: number;
-    }>;
-  };
-
-  pi.registerProvider("local-openai", {
-    baseUrl: "http://localhost:1234/v1",
-    apiKey: "$LOCAL_OPENAI_API_KEY",
-    api: "openai-completions",
-    models: payload.data.map((model) => ({
-      id: model.id,
-      name: model.name ?? model.id,
-      reasoning: false,
-      input: ["text"],
-      cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-      contextWindow: model.context_window ?? 128000,
-      maxTokens: model.max_tokens ?? 4096,
-    })),
-  });
-}
-```
-
-This registers the fetched models before startup finishes.
-
-```typescript
-pi.registerProvider("my-llm", {
-  baseUrl: "https://api.my-llm.com/v1",
-  apiKey: "$MY_LLM_API_KEY",  // env var reference; omit $ for a literal value
-  api: "openai-completions",  // which streaming API to use
-  models: [
-    {
-      id: "my-llm-large",
-      name: "My LLM Large",
-      reasoning: true,        // supports extended thinking
-      input: ["text", "image"],
-      cost: {
-        input: 3.0,           // $/million tokens
-        output: 15.0,
-        cacheRead: 0.3,
-        cacheWrite: 3.75
-      },
-      contextWindow: 200000,
-      maxTokens: 16384
-    }
-  ]
-});
-```
-
-When `models` is provided, it **replaces** all existing models for that provider.
+Moved to [Register a provider](/custom-provider/registration#register-new-provider).
 
 ## Unregister Provider
 
-Use `pi.unregisterProvider(name)` to remove a provider that was previously registered via `pi.registerProvider(name, ...)`:
-
-```typescript
-// Register
-pi.registerProvider("my-llm", {
-  baseUrl: "https://api.my-llm.com/v1",
-  apiKey: "$MY_LLM_API_KEY",
-  api: "openai-completions",
-  models: [
-    {
-      id: "my-llm-large",
-      name: "My LLM Large",
-      reasoning: true,
-      input: ["text", "image"],
-      cost: { input: 3.0, output: 15.0, cacheRead: 0.3, cacheWrite: 3.75 },
-      contextWindow: 200000,
-      maxTokens: 16384
-    }
-  ]
-});
-
-// Later, remove it
-pi.unregisterProvider("my-llm");
-```
-
-Unregistering removes that provider's dynamic models, API key fallback, OAuth provider registration, and custom stream handler registrations. Any built-in models or provider behavior that were overridden are restored.
-
-Calls made after the initial extension load phase are applied immediately, so no `/reload` is required.
+Moved to [Register a provider](/custom-provider/registration#unregister-provider).
 
 ### API Types
 
-The `api` field determines which streaming implementation is used:
-
-| API | Use for |
-|-----|---------|
-| `anthropic-messages` | Anthropic Claude API and compatibles |
-| `openai-completions` | OpenAI Chat Completions API and compatibles |
-| `openai-responses` | OpenAI Responses API |
-| `azure-openai-responses` | Azure OpenAI Responses API |
-| `openai-codex-responses` | OpenAI Codex Responses API |
-| `mistral-conversations` | Native Mistral Chat Completions streaming |
-| `google-generative-ai` | Google Generative AI API |
-| `google-vertex` | Google Vertex AI API |
-| `bedrock-converse-stream` | Amazon Bedrock Converse API |
-
-Most OpenAI-compatible providers work with `openai-completions`. Use model-level `thinkingLevelMap` for model-specific thinking levels, and `compat` for provider quirks:
-
-```typescript
-models: [{
-  id: "custom-model",
-  // ...
-  reasoning: true,
-  thinkingLevelMap: {              // map Atomic thinking levels to provider values; null hides unsupported levels
-    minimal: null,
-    low: null,
-    medium: null,
-    high: "default",
-    xhigh: null,
-    max: "max"
-  },
-  compat: {
-    supportsDeveloperRole: false,   // use "system" instead of "developer"
-    supportsReasoningEffort: true,
-    maxTokensField: "max_tokens",   // instead of "max_completion_tokens"
-    requiresToolResultName: true,   // tool results need name field
-    thinkingFormat: "qwen",        // top-level enable_thinking: true
-    cacheControlFormat: "anthropic" // Anthropic-style cache_control markers
-  }
-}]
-```
-
-Use `openrouter` for OpenRouter-style `reasoning: { effort }` controls. Use `together` for Together-style `reasoning: { enabled }` controls; with `supportsReasoningEffort`, it also sends `reasoning_effort`. Use `qwen-chat-template` for local Qwen-compatible servers that read `chat_template_kwargs.enable_thinking` and need `preserve_thinking`.
-Use `cacheControlFormat: "anthropic"` for OpenAI-compatible providers that expose Anthropic-style prompt caching via `cache_control` on the system prompt, last tool definition, and last user/assistant text content.
-
-Use `mistral-conversations` for native Mistral models. If you intentionally route a Mistral-compatible or custom endpoint through `openai-completions`, set the required `compat` flags explicitly.
+Moved to [Register a provider](/custom-provider/registration#api-types).
 
 ### Auth Header
 
-If your provider expects `Authorization: Bearer <key>` but doesn't use a standard API, set `authHeader: true`:
-
-```typescript
-pi.registerProvider("custom-api", {
-  baseUrl: "https://api.example.com",
-  apiKey: "$MY_API_KEY",
-  authHeader: true,  // adds Authorization: Bearer header
-  api: "openai-completions",
-  models: [...]
-});
-```
+Moved to [Register a provider](/custom-provider/registration#auth-header).
 
 ## OAuth Support
 
-Add OAuth/SSO authentication that integrates with `/login`:
-
-```typescript
-import type { OAuthCredentials, OAuthLoginCallbacks } from "@bastani/pi-ai";
-
-pi.registerProvider("corporate-ai", {
-  baseUrl: "https://ai.corp.com/v1",
-  api: "openai-responses",
-  models: [...],
-  oauth: {
-    name: "Corporate AI (SSO)",
-
-    async login(callbacks: OAuthLoginCallbacks, signal: AbortSignal): Promise<OAuthCredentials> {
-      // Option 1: Browser-based OAuth
-      callbacks.onAuth({ url: "https://sso.corp.com/authorize?..." });
-
-      // Option 2: Device code flow
-      callbacks.onDeviceCode({
-        userCode: "ABCD-1234",
-        verificationUri: "https://sso.corp.com/device"
-      });
-
-      // Option 3: Prompt for token/code
-      const code = await callbacks.onPrompt({ message: "Enter SSO code:" });
-
-      // Exchange for tokens (your implementation). Forward `signal` so
-      // cancelling /login aborts the in-flight network request.
-      const tokens = await exchangeCodeForTokens(code, { signal });
-
-      return {
-        refresh: tokens.refreshToken,
-        access: tokens.accessToken,
-        expires: Date.now() + tokens.expiresIn * 1000
-      };
-    },
-
-    async refreshToken(
-      credentials: OAuthCredentials,
-      signal: AbortSignal | undefined
-    ): Promise<OAuthCredentials> {
-      const tokens = await refreshAccessToken(credentials.refresh, { signal });
-      return {
-        refresh: tokens.refreshToken ?? credentials.refresh,
-        access: tokens.accessToken,
-        expires: Date.now() + tokens.expiresIn * 1000
-      };
-    },
-
-    getApiKey(credentials: OAuthCredentials): string {
-      return credentials.access;
-    },
-
-    // Optional: modify models based on user's subscription
-    modifyModels(models, credentials) {
-      const region = decodeRegionFromToken(credentials.access);
-      return models.map(m => ({
-        ...m,
-        baseUrl: `https://${region}.ai.corp.com/v1`
-      }));
-    }
-  }
-});
-```
-
-After registration, users can authenticate via `/login corporate-ai`.
-
-Existing extension OAuth definitions keep their `login`, `refreshToken`, `getApiKey`, and optional `modifyModels` methods. OAuth refresh is serialized so concurrent requests do not overwrite each other's credentials.
-
-In isolated interactive mode, extension code and executable OAuth methods remain in the engine process. Atomic transports only the JSON-safe provider description (`id`, `name`, `loginLabel`, and `usesCallbackServer`) to the terminal process; it never serializes provider functions or acquired credentials and does not load the extension a second time in the frontend. `loginLabel` replaces the login dialog title, while `usesCallbackServer: true` exposes a redirect-URL paste field that races the browser callback. The engine executes the provider's login closure and correlates browser URLs, device codes, progress/info messages, prompts, selections, and manual-code callbacks with the originating login.
-
-After acquisition, the engine owns serialized credential persistence and logout. It publishes the authenticated provider against its already-loaded snapshot as soon as persistence succeeds; dynamic catalog and ambient-availability refreshes run separately under the model selector's deadline and never extend the login transaction. Logout similarly publishes stored-credential removal without invoking `refreshModels`; Atomic gives the provider's local remaining-auth probe a short deadline so extension code cannot keep the dialog open. The frontend applies the returned snapshot only after the engine transaction succeeds. Escape or Ctrl+C cancels only the matching login and leaves the prior credential/catalog intact. Built-in OAuth and direct, non-isolated extension OAuth use the same persistence and cancellation semantics; later provider registrations continue to override earlier registrations by ID.
-
-Intentional cancellation is quiet, including native `AbortError`, an aborted signal or its exact reason, nested abort causes, and the legacy exact `Login cancelled` error. Provider denial, timeout, network/protocol errors, malformed responses, token exchange failures, and storage failures remain visible. Catalog-refresh failures are reported by `/model` while cached models remain selectable; they do not turn a persisted login into a failed transaction.
+Moved to [Provider OAuth](/custom-provider/oauth#oauth-support).
 
 ## Dynamic model catalog refresh
 
-Providers whose catalogs change at runtime can add `refreshModels`. Atomic calls it during the model picker's bounded asynchronous refresh, independently of authentication completion:
-
-```typescript
-pi.registerProvider("corporate-ai", {
-  baseUrl: "https://ai.corp.com/v1",
-  api: "openai-responses",
-  apiKey: "$CORPORATE_AI_KEY",
-  models: cachedModels,
-  async refreshModels({ signal, force, credential, store }) {
-    const models = await fetchCorporateModels({ signal, force, credential });
-    await store.write({ models, checkedAt: Date.now() });
-    return models;
-  }
-});
-```
-
-The current catalog stays readable while refresh is pending. Successful provider results are applied independently; a provider that fails, times out, or observes an aborted `signal` retains its previous list. Use the provider-scoped `store` only when the catalog should persist across sessions.
+Moved to [Provider OAuth](/custom-provider/oauth#dynamic-model-catalog-refresh).
 
 ### OAuthLoginCallbacks
 
-The `callbacks` object provides three ways to authenticate:
-
-```typescript
-interface OAuthLoginCallbacks {
-  // Open URL in browser (for OAuth redirects)
-  onAuth(params: { url: string }): void;
-
-  // Show device code (for device authorization flow)
-  onDeviceCode(params: { userCode: string; verificationUri: string }): void;
-
-  // Prompt user for input (for manual token entry)
-  onPrompt(params: { message: string }): Promise<string>;
-}
-```
+Moved to [Provider OAuth](/custom-provider/oauth#oauthlogincallbacks).
 
 ### OAuthCredentials
 
-Credentials are persisted in `~/.atomic/agent/auth.json` (legacy `~/.pi/agent/auth.json` may be read for compatibility):
-
-```typescript
-interface OAuthCredentials {
-  refresh: string;   // Refresh token (for refreshToken())
-  access: string;    // Access token (returned by getApiKey())
-  expires: number;   // Expiration timestamp in milliseconds
-}
-```
+Moved to [Provider OAuth](/custom-provider/oauth#oauthcredentials).
 
 ## Custom Streaming API
 
-For providers with non-standard APIs, implement `streamSimple`. Study the existing API implementations before writing your own:
-
-**Reference implementations:**
-
-Atomic uses provider implementations from its installed `@bastani/pi-ai` dependency. The streaming implementations behind the `api` field live under `node_modules/@bastani/pi-ai/dist/api/`, including:
-- `anthropic-messages.d.ts` / `anthropic-messages.js` - Anthropic Messages API
-- `mistral-conversations.d.ts` / `mistral-conversations.js` - Mistral Conversations/Chat streaming
-- `openai-completions.d.ts` / `openai-completions.js` - OpenAI Chat Completions
-- `openai-responses.d.ts` / `openai-responses.js` - OpenAI Responses API
-- `google-generative-ai.d.ts` / `google-generative-ai.js` - Google Generative AI
-- `bedrock-converse-stream.d.ts` / `bedrock-converse-stream.js` - Amazon Bedrock Converse API
-Per-vendor provider configurations (base URLs, auth, model catalogs) live under `dist/providers/`, for example `anthropic.d.ts` / `anthropic.js` and `mistral.d.ts` / `mistral.js`.
+Moved to [Provider streaming API](/custom-provider/streaming#custom-streaming-api).
 
 ### Stream Pattern
 
-All providers follow the same pattern:
-
-```typescript
-import {
-  type AssistantMessage,
-  type AssistantMessageEventStream,
-  type Context,
-  type Model,
-  type SimpleStreamOptions,
-  calculateCost,
-  createAssistantMessageEventStream,
-} from "@bastani/pi-ai";
-
-function streamMyProvider(
-  model: Model<any>,
-  context: Context,
-  options?: SimpleStreamOptions
-): AssistantMessageEventStream {
-  const stream = createAssistantMessageEventStream();
-
-  (async () => {
-    // Initialize output message
-    const output: AssistantMessage = {
-      role: "assistant",
-      content: [],
-      api: model.api,
-      provider: model.provider,
-      model: model.id,
-      usage: {
-        input: 0,
-        output: 0,
-        cacheRead: 0,
-        cacheWrite: 0,
-        totalTokens: 0,
-        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
-      },
-      stopReason: "pending",
-      timestamp: Date.now(),
-    };
-
-    try {
-      // Push start event
-      stream.push({ type: "start", partial: output });
-
-      // Make API request and process response...
-      // Push content events as they arrive, and set output.stopReason from the
-      // terminal event. A reason your provider sends that you do not map must
-      // become an error, not a silent "stop".
-      if (output.stopReason === "pending") {
-        throw new Error("Provider stream ended without a stop reason");
-      }
-      if (output.stopReason === "error" || output.stopReason === "aborted") {
-        throw new Error(output.errorMessage || "An unknown error occurred");
-      }
-
-      // Push done event
-      stream.push({
-        type: "done",
-        reason: output.stopReason,
-        message: output
-      });
-      stream.end();
-    } catch (error) {
-      output.stopReason = options?.signal?.aborted ? "aborted" : "error";
-      output.errorMessage = error instanceof Error ? error.message : String(error);
-      stream.push({ type: "error", reason: output.stopReason, error: output });
-      stream.end();
-    }
-  })();
-
-  return stream;
-}
-```
+Moved to [Provider streaming API](/custom-provider/streaming#stream-pattern).
 
 ### Event Types
 
-Push events via `stream.push()` in this order:
-
-1. `{ type: "start", partial: output }` - Stream started
-
-2. Content events (repeatable, track `contentIndex` for each block):
-   - `{ type: "text_start", contentIndex, partial }` - Text block started
-   - `{ type: "text_delta", contentIndex, delta, partial }` - Text chunk
-   - `{ type: "text_end", contentIndex, content, partial }` - Text block ended
-   - `{ type: "thinking_start", contentIndex, partial }` - Thinking started
-   - `{ type: "thinking_delta", contentIndex, delta, partial }` - Thinking chunk
-   - `{ type: "thinking_end", contentIndex, content, partial }` - Thinking ended
-   - `{ type: "toolcall_start", contentIndex, partial }` - Tool call started
-   - `{ type: "toolcall_delta", contentIndex, delta, partial }` - Tool call JSON chunk
-   - `{ type: "toolcall_end", contentIndex, toolCall, partial }` - Tool call ended
-
-3. `{ type: "done", reason, message }` or `{ type: "error", reason, error }` - Stream ended
-
-The `partial` field in each event contains the current `AssistantMessage` state. Update `output.content` as you receive data, then include `output` as the `partial`.
+Moved to [Provider streaming API](/custom-provider/streaming#event-types).
 
 ### Stop Reasons
 
-`StopReason` is `"pending" | "stop" | "length" | "toolUse" | "error" | "aborted"`.
-
-Start the partial message at `"pending"`. It is the reason every in-flight message carries, and it says the terminal event has not arrived yet — it is not a default standing in for `"stop"`. Set the real reason when the provider says the turn ended, then push `done` with it.
-
-Two checks belong immediately before `done`:
-
-- a stream that reached the end while still `"pending"` never received a terminal event, so raise rather than report a stop that did not happen;
-- `"error"` and `"aborted"` are failures, so raise them with `output.errorMessage` and let the `catch` push an `error` event.
-
-`done` accepts only `"stop"`, `"length"`, and `"toolUse"`, which is exactly what those two checks leave, so the `as "stop" | "length" | "toolUse"` cast older implementations used is no longer needed.
-
-Map each raw reason your provider can send onto one of the five terminal values, and **raise on one you do not recognise** rather than falling back to `"stop"`. This is what the built-in providers do: an unmapped reason becomes a provider error naming the raw value, so a new truncation or safety signal is visible instead of arriving as a turn that looks like it finished normally. The optional `rawStopReason` field on `AssistantMessage` is where the provider's own string belongs when you want to keep it.
+Moved to [Provider streaming API](/custom-provider/streaming#stop-reasons).
 
 ### Content Blocks
 
-Add content blocks to `output.content` as they arrive:
-
-```typescript
-// Text block
-output.content.push({ type: "text", text: "" });
-stream.push({ type: "text_start", contentIndex: output.content.length - 1, partial: output });
-
-// As text arrives
-const block = output.content[contentIndex];
-if (block.type === "text") {
-  block.text += delta;
-  stream.push({ type: "text_delta", contentIndex, delta, partial: output });
-}
-
-// When block completes
-stream.push({ type: "text_end", contentIndex, content: block.text, partial: output });
-```
+Moved to [Provider streaming API](/custom-provider/streaming#content-blocks).
 
 ### Tool Calls
 
-Tool calls require accumulating JSON and parsing:
-
-```typescript
-// Start tool call
-output.content.push({
-  type: "toolCall",
-  id: toolCallId,
-  name: toolName,
-  arguments: {}
-});
-stream.push({ type: "toolcall_start", contentIndex: output.content.length - 1, partial: output });
-
-// Accumulate JSON
-let partialJson = "";
-partialJson += jsonDelta;
-try {
-  block.arguments = JSON.parse(partialJson);
-} catch {}
-stream.push({ type: "toolcall_delta", contentIndex, delta: jsonDelta, partial: output });
-
-// Complete
-stream.push({
-  type: "toolcall_end",
-  contentIndex,
-  toolCall: { type: "toolCall", id, name, arguments: block.arguments },
-  partial: output
-});
-```
+Moved to [Provider streaming API](/custom-provider/streaming#tool-calls).
 
 ### Usage and Cost
 
-Update usage from API response and calculate cost:
-
-```typescript
-output.usage.input = response.usage.input_tokens;
-output.usage.output = response.usage.output_tokens;
-output.usage.cacheRead = response.usage.cache_read_tokens ?? 0;
-output.usage.cacheWrite = response.usage.cache_write_tokens ?? 0;
-output.usage.totalTokens = output.usage.input + output.usage.output +
-                           output.usage.cacheRead + output.usage.cacheWrite;
-calculateCost(model, output.usage);
-```
-
-`calculateCost()` selects one rate set for the whole request. Aggregate input is `usage.input + usage.cacheRead + usage.cacheWrite`; a tier applies only when that sum is strictly greater than `inputTokensAbove`, and the matching tier with the highest threshold wins. Every tier must provide complete `input`, `output`, `cacheRead`, and `cacheWrite` rates. Extension-registered models preserve these tiers, and matching `models.json` `modelOverrides` use the same replacement rules described in [Custom Models](/models#request-wide-cost-tiers).
+Moved to [Provider streaming API](/custom-provider/streaming#usage-and-cost).
 
 ### Registration
 
-Register your stream function:
-
-```typescript
-pi.registerProvider("my-provider", {
-  baseUrl: "https://api.example.com",
-  apiKey: "$MY_API_KEY",
-  api: "my-custom-api",
-  models: [...],
-  streamSimple: streamMyProvider
-});
-```
+Moved to [Provider streaming API](/custom-provider/streaming#registration).
 
 ## Testing Your Implementation
 
@@ -601,139 +168,8 @@ Run tests with your provider/model pairs to verify compatibility.
 
 ## Config Reference
 
-```typescript
-interface ProviderConfig {
-  /** Display name for the provider in UI such as /login. */
-  name?: string;
-
-  /** API endpoint URL. Required when defining models. */
-  baseUrl?: string;
-
-  /** API key literal or config value (for env vars use "$ENV_VAR" or "${ENV_VAR}"). Required when defining models (unless oauth). */
-  apiKey?: string;
-
-  /** API type for streaming. Required at provider or model level when defining models. */
-  api?: Api;
-
-  /** Custom streaming implementation for non-standard APIs. */
-  streamSimple?: (
-    model: Model<Api>,
-    context: Context,
-    options?: SimpleStreamOptions
-  ) => AssistantMessageEventStream;
-
-  /** Custom headers to include in requests. Values use the same config-value syntax as apiKey. */
-  headers?: Record<string, string>;
-
-  /** If true, adds Authorization: Bearer header with the resolved API key. */
-  authHeader?: boolean;
-
-  /** Models to register. If provided, replaces all existing models for this provider. */
-  models?: ProviderModelConfig[];
-
-  /** OAuth provider for /login support. */
-  oauth?: {
-    name: string;
-    login(callbacks: OAuthLoginCallbacks, signal: AbortSignal): Promise<OAuthCredentials>;
-    refreshToken(credentials: OAuthCredentials, signal: AbortSignal | undefined): Promise<OAuthCredentials>;
-    getApiKey(credentials: OAuthCredentials): string;
-    modifyModels?(models: Model<Api>[], credentials: OAuthCredentials): Model<Api>[];
-  };
-}
-```
+Moved to [Provider API reference](/custom-provider/api-reference#config-reference).
 
 ## Model Definition Reference
 
-```typescript
-interface ProviderModelConfig {
-  /** Model ID (e.g., "claude-sonnet-4-5"). */
-  id: string;
-
-  /** Display name (e.g., "Claude Sonnet 4.5"). */
-  name: string;
-
-  /** API type override for this specific model. */
-  api?: Api;
-
-  /** API endpoint URL override for this specific model. */
-  baseUrl?: string;
-
-  /** Whether the model supports extended thinking. */
-  reasoning: boolean;
-
-  /** Maps Atomic thinking levels to provider/model-specific values; null marks a level unsupported. */
-  thinkingLevelMap?: Partial<Record<"off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max", string | null>>;
-
-  /** Supported input types. */
-  input: ("text" | "image")[];
-
-  /** Base cost per million tokens plus optional request-wide long-context tiers. */
-  cost: {
-    input: number;
-    output: number;
-    cacheRead: number;
-    cacheWrite: number;
-    tiers?: Array<{
-      /** Tier applies only when input + cacheRead + cacheWrite strictly exceeds this value. */
-      inputTokensAbove: number;
-      input: number;
-      output: number;
-      cacheRead: number;
-      cacheWrite: number;
-    }>;
-  };
-
-  /** Default/effective context window size in tokens. */
-  contextWindow: number;
-
-  /** Maximum output tokens. */
-  maxTokens: number;
-  /** Default sampling parameters merged into OpenAI-compatible request bodies. */
-  samplingParams?: Record<string, unknown>;
-
-  /** Custom headers for this specific model. */
-  headers?: Record<string, string>;
-
-  /** API-specific provider compatibility settings. */
-  compat?: {
-    supportsStore?: boolean;
-    supportsDeveloperRole?: boolean;
-    supportsReasoningEffort?: boolean;
-    supportsUsageInStreaming?: boolean;
-    supportsFinishReason?: boolean;
-    supportsThinkingTokenBudget?: boolean;
-    supportsStrictMode?: boolean;
-    supportsOpenAIGrammarTools?: boolean;
-    /** Atomic alias for supportsOpenAIGrammarTools. */
-    supportsGrammarTools?: boolean;
-    maxTokensField?: "max_completion_tokens" | "max_tokens";
-    requiresToolResultName?: boolean;
-    requiresAssistantAfterToolResult?: boolean;
-    requiresThinkingAsText?: boolean;
-    requiresReasoningContentOnAssistantMessages?: boolean;
-    thinkingFormat?: "openai" | "openrouter" | "deepseek" | "together" | "baseten" | "zai" | "qwen" | "chat-template" | "qwen-chat-template" | "string-thinking" | "ant-ling";
-    supportsStrictTools?: boolean;
-    chatTemplateKwargs?: Record<string, string | number | boolean | null | { "$var": "thinking.enabled" | "thinking.effort" | "thinking.budget"; omitWhenOff?: boolean }>;
-    chatTemplateArgs?: Record<string, string | number | boolean | null | { "$var": "thinking.enabled" | "thinking.effort" | "thinking.budget"; omitWhenOff?: boolean }>;
-    thinkingTokenBudgetField?: "thinking_token_budget" | "thinking_budget" | "thinking_budget_tokens";
-    cacheControlFormat?: "anthropic";
-    sendSessionAffinityHeaders?: boolean;
-    sessionAffinityFormat?: "openai" | "openai-nosession" | "openrouter";
-    supportsLongCacheRetention?: boolean;
-    vllmPriority?: number;
-    supportsToolSearch?: boolean;
-    supportsMaxOutputTokens?: boolean;
-  };
-}
-```
-
-The `cost` shape is equivalent to `Model<Api>["cost"]`. Base rates and every tier are complete rate sets. When multiple thresholds match, `calculateCost()` uses the highest threshold and applies that tier to all four cost buckets for the request.
-
-`openrouter` sends `reasoning: { effort }`. `deepseek` sends `thinking: { type: "enabled" | "disabled" }` and `reasoning_effort` when enabled. `together` sends `reasoning: { enabled }` and also `reasoning_effort` when `supportsReasoningEffort` is enabled. `qwen` is for DashScope-style top-level `enable_thinking`. Use `qwen-chat-template` for local Qwen-compatible servers that read `chat_template_kwargs.enable_thinking` and need `preserve_thinking`. Use `chat-template` for configurable `chat_template_kwargs`, for example DeepSeek V3.x behind vLLM with `chatTemplateKwargs: { "thinking": { "$var": "thinking.enabled" } }`. Use `thinkingFormat: "baseten"` with `chatTemplateArgs` when the provider expects toggle values under `chat_template_args` and optionally supports top-level `reasoning_effort`.
-`thinkingTokenBudgetField` sends a clamped per-level thinking budget as a top-level request field (`thinking_token_budget` on vLLM, `thinking_budget` on Qwen/SGLang, `thinking_budget_tokens` on llama.cpp). `supportsThinkingTokenBudget: true` is an alias for the vLLM field name. Do not combine it with `reasoning_effort` on DashScope Qwen models.
-`vllmPriority` sends a top-level `priority` request field for `openai-completions` providers. Lower values are scheduled earlier and the vLLM server default is `0`, so it only takes effect when vLLM runs with `--scheduling-policy priority`. Set it on a background or batch model so its long prefills queue behind interactive sessions. Unset by default and never set on the generated catalog.
-`cacheControlFormat: "anthropic"` applies Anthropic-style `cache_control` markers to the system prompt, last tool definition, and last user, assistant, or tool-result text content.
-
-Capability flags are enforcement claims, not preferences. `supportsStrictMode` controls strict JSON-schema tools for OpenAI-compatible APIs; Anthropic/Bedrock use `supportsStrictTools`; `supportsOpenAIGrammarTools` controls OpenAI Lark/regex custom tools. Atomic also accepts `supportsGrammarTools` as a compatibility alias and synchronizes it to the canonical OpenAI name; when both disagree, the canonical field wins. Leave these fields unset/false unless the endpoint and selected model actually preserve and enforce the corresponding request shape. See [Extensions](/extensions#constrained-sampling) for exact `constrainedSampling` modes.
-
-For `openai-responses` providers, set `compat.sessionAffinityFormat` to `"openai"` for `session_id` plus `x-client-request-id`, `"openai-nosession"` to omit `session_id` while retaining `x-client-request-id`, or `"openrouter"` for `x-session-id`. Responses-compatible providers may also set `supportsToolSearch` when they support deferred tool loading. `supportsMaxOutputTokens` defaults to `true`; set it to `false` for OpenAI Responses-compatible gateways such as Codex-protocol proxies that reject `max_output_tokens` with a 400, and Atomic omits the parameter from those requests.
+Moved to [Provider API reference](/custom-provider/api-reference#model-definition-reference).