diff --git a/packages/ai/src/providers/compat-schema.ts b/packages/ai/src/providers/compat-schema.ts index 9db22b80f..ca54cc054 100644 --- a/packages/ai/src/providers/compat-schema.ts +++ b/packages/ai/src/providers/compat-schema.ts @@ -600,16 +600,19 @@ function mergeCompatProperties< return { ...merged, ...overrides } as MergedCompatProperties; } -const CompatSchemasByApi = { +/** Compatibility schema for each API whose models accept compat. Mirrors the compat type of Model. */ +export const CompatSchemasByApi = { "openai-completions": OpenAICompletionsCompatSchema, "openai-responses": OpenAIResponsesCompatSchema, + "azure-openai-responses": OpenAIResponsesCompatSchema, + "openai-codex-responses": OpenAIResponsesCompatSchema, "anthropic-messages": AnthropicMessagesCompatSchema, "bedrock-converse-stream": BedrockCompatSchema, "mistral-conversations": MistralConversationsCompatSchema, } as const; const ProviderCompatProperties = mergeCompatProperties( - Object.values(CompatSchemasByApi).map((schema) => schema.properties), + [...new Set(Object.values(CompatSchemasByApi))].map((schema) => schema.properties), ProviderCompatPropertyOverrides, ); diff --git a/packages/ai/src/providers/model-schema.ts b/packages/ai/src/providers/model-schema.ts index 43ce3d204..453ceabc7 100644 --- a/packages/ai/src/providers/model-schema.ts +++ b/packages/ai/src/providers/model-schema.ts @@ -12,13 +12,16 @@ export const ModelInputModalitySchema = Type.Enum(MODEL_INPUT_MODALITIES); export const CacheRetentionSchema = Type.Enum(CACHE_RETENTIONS); const ThinkingLevelMapValueSchema = Type.Union([Type.String(), Type.Null()]); -export const ThinkingLevelMapSchema = Type.Partial(Type.Record(ModelThinkingLevelSchema, ThinkingLevelMapValueSchema)); +export const ThinkingLevelMapSchema = Type.Partial(Type.Record(ModelThinkingLevelSchema, ThinkingLevelMapValueSchema), { + description: + "Provider value sent for each thinking level. null marks a level unsupported. Levels the model does not map use the provider's default value through high; xhigh and max are unsupported.", +}); export const ModelPromptCacheSchema = Type.Partial( Type.Record(Type.Enum(MODEL_PROMPT_CACHE_RETENTIONS), Type.Number({ exclusiveMinimum: 0 })), { description: - "Best-effort prompt cache lifetime in seconds for each retention tier. A missing tier means the lifetime is unknown, so Pi does not warm it.", + "Best-effort prompt cache lifetime in seconds for the short and long retention tiers. Pi warms only tiers with a known lifetime.", }, ); diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md index 2d700d79b..fd7e6c948 100644 --- a/packages/coding-agent/CHANGELOG.md +++ b/packages/coding-agent/CHANGELOG.md @@ -2,6 +2,10 @@ ## [Unreleased] +### Added + +- Added a Models Configuration reference generated from the `models.json` schema, listing all provider, model, model override, and compatibility fields ([#10790](https://github.com/earendil-works/pi/issues/10790)) + ### Changed - `generateSummary()` and `generateSummaryWithUsage()` now ignore their `reserveTokens` parameter. Summary requests use the model's output limit instead. @@ -9,6 +13,7 @@ ### Fixed - Fixed compaction and branch summaries failing with "generation hit the token cap" when reasoning used most of the fixed summary output limit. Summaries now use the model's output limit, and `compaction.reserveTokens` only controls when compaction starts ([#9512](https://github.com/earendil-works/pi/issues/9512), [#9075](https://github.com/earendil-works/pi/issues/9075)). +- Fixed `models.schema.json` missing descriptions for provider and model fields, so editors showed no hints for them ([#10790](https://github.com/earendil-works/pi/issues/10790)) ## [1.3.0] - 2026-10-15 diff --git a/packages/coding-agent/docs/docs.json b/packages/coding-agent/docs/docs.json index c9df247a3..950a05f5d 100644 --- a/packages/coding-agent/docs/docs.json +++ b/packages/coding-agent/docs/docs.json @@ -152,6 +152,10 @@ "title": "Settings", "path": "settings.md" }, + { + "title": "Models Configuration", + "path": "models-configuration.md" + }, { "title": "Environment Variables", "path": "environment-variables.md" diff --git a/packages/coding-agent/docs/models-configuration.md b/packages/coding-agent/docs/models-configuration.md new file mode 100644 index 000000000..04787a77c --- /dev/null +++ b/packages/coding-agent/docs/models-configuration.md @@ -0,0 +1,187 @@ +# Models Configuration + + + +This reference lists the fields of `models.json`. See [Configure a compatible endpoint](models.md#configure-a-compatible-endpoint) for examples and [Configuration](configuration.md#agent-directory) for the file location. + +Add `"$schema": "https://pi.dev/schemas/models.schema.json"` to `models.json` for editor validation and completion. + +## Providers + +Each key under `providers` is a provider ID. A built-in provider ID changes that provider. Any other ID adds a provider, which needs `baseUrl` and an `api` at provider or model level. + +| Field | Type | Default | Description | +|---|---|---|---| +| `name` | string | | Display name. | +| `baseUrl` | string | | API base URL. Also applies to the provider's built-in models. | +| `apiKey` | string | | Literal key, "$NAME" environment interpolation, or "!command" output. | +| `api` | string | | API for the provider's models, such as "openai-completions", "openai-responses", "anthropic-messages", or "google-generative-ai". | +| `oauth` | `"radius"` | | OAuth login flow. Requires baseUrl. | +| `headers` | object | | Request headers. Values resolve like apiKey. | +| `compat` | [object](#compatibility) | | Provider and model compatibility overrides. | +| `authHeader` | boolean | `false` | Whether to send the resolved API key as Authorization: Bearer. | +| `models` | [`object[]`](#models) | | | +| `modelOverrides` | [object](#model-overrides) | | | + +## Models + +Each `models` entry adds a model to the provider. An entry whose `id` matches an existing model replaces it. + +| Field | Type | Default | Description | +|---|---|---|---| +| `id` | string | | Required. Model ID sent to the API. | +| `name` | string | | Display name, also matched by --model patterns. | +| `api` | string | | Overrides the provider api. | +| `baseUrl` | string | | Overrides the provider baseUrl. | +| `reasoning` | boolean | `false` | Whether the model supports thinking. | +| `thinkingLevelMap` | object | | Provider value sent for each thinking level. null marks a level unsupported. Levels the model does not map use the provider's default value through high; xhigh and max are unsupported. | +| `input` | `("text" \| "image")[]` | `["text"]` | | +| `inputLimits` | [object](#input-limits) | | | +| `cost` | object | | | +| `cost.input` | number | | Required. Input cost in USD per million tokens. | +| `cost.output` | number | | Required. Output cost in USD per million tokens. | +| `cost.cacheRead` | number | | Required. Cache-read cost in USD per million tokens. | +| `cost.cacheWrite` | number | | Required. Cache-write cost in USD per million tokens. | +| `cost.tiers` | `object[]` | | Request-wide pricing tiers. The highest matching input threshold applies to the full request. | +| `cost.tiers[].inputTokensAbove` | number | | Required. Use this tier when total request input exceeds this token count. | +| `cost.tiers[].input` | number | | Required. Input cost in USD per million tokens. | +| `cost.tiers[].output` | number | | Required. Output cost in USD per million tokens. | +| `cost.tiers[].cacheRead` | number | | Required. Cache-read cost in USD per million tokens. | +| `cost.tiers[].cacheWrite` | number | | Required. Cache-write cost in USD per million tokens. | +| `promptCache` | object | | Best-effort prompt cache lifetime in seconds for the short and long retention tiers. Pi warms only tiers with a known lifetime. | +| `contextWindow` | number | `128000` | Context window in tokens. | +| `maxTokens` | number | `16384` | Maximum output tokens. | +| `samplingParams` | object | | Fields merged into every request body. Applies only to OpenAI-compatible APIs. | +| `samplingParamsByThinkingLevel` | object | | samplingParams per thinking level, merged over samplingParams. | +| `headers` | object | | Request headers. Values resolve like apiKey. | +| `compat` | [object](#compatibility) | | Provider and model compatibility overrides. | + +## Model overrides + +Each `modelOverrides` key is the ID of a built-in or extension model. Unknown IDs are ignored. Object fields, such as `cost`, merge with the model's value field by field; other fields replace it. + +| Field | Type | Default | Description | +|---|---|---|---| +| `name` | string | | Display name, also matched by --model patterns. | +| `reasoning` | boolean | | Whether the model supports thinking. | +| `thinkingLevelMap` | object | | Provider value sent for each thinking level. null marks a level unsupported. Levels the model does not map use the provider's default value through high; xhigh and max are unsupported. | +| `input` | `("text" \| "image")[]` | | | +| `inputLimits` | [object](#input-limits) | | | +| `cost` | object | | | +| `cost.input` | number | | Input cost in USD per million tokens. | +| `cost.output` | number | | Output cost in USD per million tokens. | +| `cost.cacheRead` | number | | Cache-read cost in USD per million tokens. | +| `cost.cacheWrite` | number | | Cache-write cost in USD per million tokens. | +| `cost.tiers` | `object[]` | | Request-wide pricing tiers. The highest matching input threshold applies to the full request. | +| `cost.tiers[].inputTokensAbove` | number | | Required. Use this tier when total request input exceeds this token count. | +| `cost.tiers[].input` | number | | Required. Input cost in USD per million tokens. | +| `cost.tiers[].output` | number | | Required. Output cost in USD per million tokens. | +| `cost.tiers[].cacheRead` | number | | Required. Cache-read cost in USD per million tokens. | +| `cost.tiers[].cacheWrite` | number | | Required. Cache-write cost in USD per million tokens. | +| `promptCache` | object | | Best-effort prompt cache lifetime in seconds for the short and long retention tiers. Pi warms only tiers with a known lifetime. | +| `contextWindow` | number | | Context window in tokens. | +| `maxTokens` | number | | Maximum output tokens. | +| `samplingParams` | object | | Fields merged into every request body. Applies only to OpenAI-compatible APIs. | +| `samplingParamsByThinkingLevel` | object | | samplingParams per thinking level, merged over samplingParams. | +| `headers` | object | | Request headers. Values resolve like apiKey. | +| `compat` | [object](#compatibility) | | Provider and model compatibility overrides. | + +## Input limits + +See [Describe model input and caching](models.md#describe-model-input-and-caching). + +| Field | Type | Default | Description | +|---|---|---|---| +| `maxRequestBytes` | integer | | Maximum serialized provider request size in bytes. | +| `images` | object | | | +| `images.resize` | object | | Cache-safe resize profile applied before a new image enters conversation history. | +| `images.resize.maxWidth` | integer | | | +| `images.resize.maxHeight` | integer | | | +| `images.resize.maxBytes` | integer | | Maximum base64-encoded payload size in bytes. | +| `images.resize.jpegQuality` | integer | | | +| `images.maxPerMessage` | integer | | Maximum images accepted in one provider message. | +| `images.maxPerRequest` | integer | | Maximum images accepted across one provider request. | + +## Compatibility + +`compat` describes verified differences from an API's standard request and response behavior. Model values override provider values per field. The fields that apply depend on the model's `api`. + +### `openai-completions` + +| Field | Type | Default | Description | +|---|---|---|---| +| `supportsStore` | boolean | | Whether the provider supports the store field. Default: auto-detected from URL. | +| `supportsDeveloperRole` | boolean | | Whether the provider supports the developer role instead of system. Default: auto-detected from URL. | +| `supportsReasoningEffort` | boolean | | Whether the provider supports reasoning_effort. Default: auto-detected from URL. | +| `supportsUsageInStreaming` | boolean | `true` | Whether the provider supports stream_options.include_usage for token usage in streaming responses. | +| `supportsFinishReason` | boolean | `true` | Whether streamed responses include finish_reason. When false, pi infers stop or toolUse when the stream ends. | +| `maxTokensField` | `"max_completion_tokens" \| "max_tokens"` | | Which field to use for max tokens. Default: auto-detected from URL. | +| `requiresToolResultName` | boolean | | Whether tool results require the name field. Default: auto-detected from URL. | +| `requiresAssistantAfterToolResult` | boolean | | Whether a user message after tool results requires an assistant message in between. Default: auto-detected from URL. | +| `requiresThinkingAsText` | boolean | | Whether thinking blocks must be converted to text blocks with <thinking> delimiters. Default: auto-detected from URL. | +| `requiresReasoningContentOnAssistantMessages` | boolean | | Whether all replayed assistant messages must include an empty reasoning_content field when reasoning is enabled. Default: auto-detected from URL. | +| `thinkingFormat` | `"openai" \| "openrouter" \| "deepseek" \| "together" \| "baseten" \| "zai" \| "qwen" \| "chat-template" \| "qwen-chat-template" \| "string-thinking" \| "ant-ling"` | | Format for reasoning or thinking parameters. When omitted, Pi auto-detects the format from the provider URL. "openai" uses reasoning_effort, "openrouter" uses reasoning.effort, "deepseek" uses thinking.type plus reasoning_effort when supported, "together" uses reasoning.enabled plus reasoning_effort when supported, "baseten" uses configurable chat_template_args plus reasoning_effort when supported, "zai" uses thinking.type, "qwen" uses top-level enable_thinking, "qwen-chat-template" uses chat_template_kwargs.enable_thinking and preserve_thinking, "chat-template" uses configurable chat_template_kwargs, "string-thinking" uses top-level thinking, and "ant-ling" uses reasoning.effort only when the mapped effort is non-null. | +| `chatTemplateKwargs` | object | | Kwargs sent as chat_template_kwargs when thinkingFormat is "chat-template". Use $var with "thinking.enabled", "thinking.effort", or "thinking.budget" for pi-controlled values. | +| `chatTemplateArgs` | object | | Arguments sent as chat_template_args when thinkingFormat is "baseten". Use $var with "thinking.enabled", "thinking.effort", or "thinking.budget" for pi-controlled values. | +| `openRouterRouting` | object | | OpenRouter provider routing preferences. Controls which upstream providers OpenRouter routes requests to. Sent as the provider field in the OpenRouter API request body. See https://openrouter.ai/docs/guides/routing/provider-selection. | +| `vercelGatewayRouting` | object | | Vercel AI Gateway routing preferences. Controls which upstream providers the gateway routes requests to. See https://vercel.com/docs/ai-gateway/models-and-providers/provider-options. | +| `zaiToolStream` | boolean | `false` | Whether z.ai supports top-level tool_stream for streaming tool call deltas. | +| `thinkingTokenBudgetField` | `"thinking_token_budget" \| "thinking_budget" \| "thinking_budget_tokens"` | | Top-level request field used to cap reasoning tokens from thinkingBudgets. Reasoning and the answer share max_tokens on these endpoints. "thinking_token_budget" is vLLM, "thinking_budget" is Qwen, DashScope, or SGLang, and "thinking_budget_tokens" is llama.cpp. Off by default and not set on the generated catalog. | +| `supportsThinkingTokenBudget` | boolean | `false` | Alias for thinkingTokenBudgetField: "thinking_token_budget" (vLLM). Prefer thinkingTokenBudgetField. | +| `supportsOpenAIGrammarTools` | boolean | `false` | Whether the provider supports OpenAI custom tools with Lark or regex grammar formats. When false, grammar-constrained tools fall back to normal function tools. The generated catalog enables this for capable models. | +| `supportsMidConvoSystemMessages` | boolean | `false` | Whether the exact model accepts system or developer messages after the conversation has started. When false, later system messages are folded into the leading system message. The generated catalog enables this for verified models. | +| `supportsMidConvoToolAdditions` | boolean | `false` | Whether system messages can introduce additional tools mid-conversation. Requires supportsMidConvoSystemMessages. The generated catalog enables this for capable models. | +| `supportsStrictMode` | boolean | `false` | Whether the provider supports the strict field in tool definitions. Generated capable models enable it explicitly. | +| `cacheControlFormat` | `"anthropic"` | | Cache control convention for prompt caching. Anthropic applies cache_control markers to the system prompt, last tool definition, and last user, assistant, or tool-result text content. | +| `sendSessionAffinityHeaders` | boolean | | Whether to send session-affinity data from options.sessionId. Default: true for OpenRouter endpoints, false otherwise. | +| `sessionAffinityFormat` | `"openai" \| "openai-nosession" \| "openrouter"` | | Session-affinity header format. openai sends session_id, x-client-request-id, and x-session-affinity; openai-nosession sends x-client-request-id and x-session-affinity; openrouter sends x-session-id. Does not affect prompt_cache_key. Default: auto-detected. | +| `supportsLongCacheRetention` | boolean | | Whether the provider supports long prompt cache retention (prompt_cache_retention: "24h" or Anthropic-style cache_control.ttl: "1h", depending on format). Default: auto-detected from provider and URL. | +| `vllmPriority` | number | | vLLM scheduler priority sent as the top-level priority request field. Lower values are handled earlier and the server default is 0. Only meaningful with --scheduling-policy priority. Off by default and not set on the generated catalog. | + +### `openai-responses` + +Also applies to `azure-openai-responses` and `openai-codex-responses`. + +| Field | Type | Default | Description | +|---|---|---|---| +| `supportsDeveloperRole` | boolean | `true` | Whether the provider supports the developer role instead of system. | +| `supportsMidConvoSystemMessages` | boolean | `false` | Whether the exact model accepts developer or system messages after the conversation has started. When false, later system messages are folded into the leading system message. The generated catalog enables this for verified models. | +| `sessionAffinityFormat` | `"openai" \| "openai-nosession" \| "openrouter"` | | Session-affinity header format. openai sends session_id and x-client-request-id; openai-nosession sends x-client-request-id; openrouter sends x-session-id. Does not affect prompt_cache_key. Default: auto-detected. | +| `supportsLongCacheRetention` | boolean | `true` | Whether the provider supports long prompt cache retention. This uses prompt_cache_options.ttl: "30m" on GPT-5.6+ and prompt_cache_retention: "24h" on earlier models. | +| `supportsStrictMode` | boolean | | Whether the provider supports strict JSON-schema function tools. Defaults are API-specific; generated OpenAI models enable it explicitly. | +| `supportsOpenAIGrammarTools` | boolean | `false` | Whether to emit OpenAI custom tools with Lark or regex grammar formats. When false, grammar-constrained tools fall back to normal function tools. The generated catalog enables this for capable models. | +| `supportsAdditionalTools` | boolean | `false` | Whether the model supports message-anchored additional_tools input items. | +| `supportsToolSearch` | boolean | `false` | Whether the model supports client-executed tool search for transcript-anchored additions. | +| `supportsExplicitPromptCacheMode` | boolean | `false` | Whether the model accepts prompt_cache_options. Older OpenAI models reject the parameter. | +| `supportsMidConvoEffort` | boolean | `false` | Whether thinking level changes are sent as configuration_update input items instead of changing reasoning.effort, so a change keeps the prompt cache. Only used by the openai-responses API, and ignored with Sign in with ChatGPT on the openai provider. | +| `supportsMaxOutputTokens` | boolean | `true` | Whether the provider accepts max_output_tokens. Some Codex-protocol gateways reject it. | + +### `anthropic-messages` + +| Field | Type | Default | Description | +|---|---|---|---| +| `supportsEagerToolInputStreaming` | boolean | `true` | Whether the provider accepts per-tool eager_input_streaming. When false, the Anthropic provider omits tools[].eager_input_streaming and sends the legacy fine-grained-tool-streaming-2025-05-14 beta header for tool-enabled requests. | +| `supportsLongCacheRetention` | boolean | `true` | Whether the provider supports Anthropic long cache retention through cache_control.ttl. | +| `sendSessionAffinityHeaders` | boolean | | Whether to send x-session-affinity from options.sessionId when caching is enabled. Required for providers like Fireworks that use session affinity for prompt cache routing; requests to the same replica maximize cache hits. Default: true for OpenRouter endpoints, false otherwise. | +| `sessionAffinityFormat` | `"openrouter"` | | Session-affinity format. openrouter sends x-session-id; when unset, sends x-session-affinity. | +| `supportsCacheControlOnTools` | boolean | `true` | Whether the provider supports Anthropic-style cache_control markers on tool definitions. When false, cache_control is omitted from tool parameters. Some Anthropic-compatible providers, such as Fireworks, do not support this field on tools and may reject or ignore it. | +| `supportsTemperature` | boolean | `true` | Whether the model accepts the Anthropic temperature request field. Claude Opus 4.7+ rejects non-default values. | +| `forceAdaptiveThinking` | boolean | `false` | Whether to force adaptive thinking (thinking.type: adaptive plus output_config.effort) regardless of model ID. Built-in models that require adaptive thinking set this in generated metadata. Custom Anthropic-compatible providers can set this to true for any model whose upstream requires the adaptive format. Set false to opt out on overridden built-in models. | +| `allowEmptySignature` | boolean | `false` | Whether to replay empty thinking signatures instead of converting thinking to text. | +| `supportsStrictTools` | boolean | `false` | Whether the provider supports Anthropic strict tool schemas. Generated Anthropic models enable it explicitly. | +| `supportsMidConvoEffort` | boolean | `false` | Whether the exact model transport supports effort-only system messages and thinking binding controls. | +| `supportsMidConvoSystemMessages` | boolean | `false` | Whether the exact model accepts system-role messages inside the conversation. When false, later system messages are folded into the top-level system prompt. | +| `supportsMidConvoToolChanges` | boolean | `false` | Whether the exact model accepts mid-conversation tool_addition and tool_removal blocks. Requires supportsMidConvoSystemMessages. | +| `allowedFallbackModels` | `object[]` | | Models Anthropic accepts for server-side refusal fallback, with local pricing metadata for returned fallback responses. When absent or empty, callers must omit fallbacks; Anthropic rejects the field for models with no permitted fallback targets. | + +### `bedrock-converse-stream` + +| Field | Type | Default | Description | +|---|---|---|---| +| `supportsStrictMode` | boolean | `false` | Whether the model supports Bedrock strict tool schemas. | + +### `mistral-conversations` + +| Field | Type | Default | Description | +|---|---|---|---| +| `supportsMidConvoSystemMessages` | boolean | `false` | Whether the exact model accepts system messages after the conversation has started. When false, later system messages are folded into the leading system message. | diff --git a/packages/coding-agent/docs/models.md b/packages/coding-agent/docs/models.md index fbb01966e..2014aee50 100644 --- a/packages/coding-agent/docs/models.md +++ b/packages/coding-agent/docs/models.md @@ -62,10 +62,22 @@ Use [`models.json`](configuration.md#agent-directory) when an endpoint speaks an } ``` -The dummy key makes the model available to Pi; Ollama ignores it. For an authenticated endpoint, `apiKey` and header values can use `$NAME` or `${NAME}` environment interpolation, a literal value, or a leading `!command`. Commands in `models.json` run at request time and are not cached by Pi. +The dummy key makes the model available to Pi; Ollama ignores it. For an authenticated endpoint, `apiKey` and header values can use `$NAME` or `${NAME}` environment interpolation, a literal value, or a leading `!command`. `$$` and `$!` produce a literal `$` and `!`. Commands in `models.json` run at request time and are not cached by Pi. Opening `/model` reloads the file. A `models` entry adds or replaces a model with the same ID on that provider. Use `modelOverrides` to change metadata for an existing built-in or extension-provided model without replacing the provider's model list. Unknown override IDs are ignored. +To route a built-in provider through a proxy, set only its `baseUrl`. Its models and authentication stay unchanged: + +```json +{ + "providers": { + "anthropic": { "baseUrl": "https://proxy.example.com/v1" } + } +} +``` + +[Models Configuration](models-configuration.md) lists every field. + ### Describe model input and caching Use `inputLimits.images.resize` to control how Pi encodes new image attachments, `read` results, and tool-result images before storing them in conversation history: diff --git a/packages/coding-agent/package.json b/packages/coding-agent/package.json index a23911cbf..33ac1bcfd 100644 --- a/packages/coding-agent/package.json +++ b/packages/coding-agent/package.json @@ -37,6 +37,7 @@ "copy-binary-assets": "shx cp package.json dist/ && shx cp README.md dist/ && shx cp CHANGELOG.md dist/ && shx mkdir -p dist/theme && shx cp src/modes/interactive/theme/*.json dist/theme/ && shx mkdir -p dist/assets && shx cp src/modes/interactive/assets/*.png dist/assets/ && shx mkdir -p dist/export-html/vendor && shx cp src/core/export-html/template.html dist/export-html/ && shx cp src/core/export-html/vendor/*.js dist/export-html/vendor/ && shx cp -r docs dist/ && shx cp -r examples dist/ && shx cp ../../node_modules/@silvia-odwyer/photon-node/photon_rs_bg.wasm dist/", "test": "vitest --run", "generate:schemas": "node --import ./src/experimental/source-resolver.ts scripts/generate-schemas.ts", + "generate:references": "node --import ./src/experimental/source-resolver.ts scripts/generate-references.ts", "prepublishOnly": "npm run clean && npm run build" }, "dependencies": { diff --git a/packages/coding-agent/schemas/models.schema.json b/packages/coding-agent/schemas/models.schema.json index 3313f85bd..322602d32 100644 --- a/packages/coding-agent/schemas/models.schema.json +++ b/packages/coding-agent/schemas/models.schema.json @@ -18,23 +18,28 @@ "properties": { "name": { "type": "string", - "minLength": 1 + "minLength": 1, + "description": "Display name." }, "baseUrl": { "type": "string", - "minLength": 1 + "minLength": 1, + "description": "API base URL. Also applies to the provider's built-in models." }, "apiKey": { "type": "string", - "minLength": 1 + "minLength": 1, + "description": "Literal key, \"$NAME\" environment interpolation, or \"!command\" output." }, "api": { "type": "string", - "minLength": 1 + "minLength": 1, + "description": "API for the provider's models, such as \"openai-completions\", \"openai-responses\", \"anthropic-messages\", or \"google-generative-ai\"." }, "oauth": { "type": "string", - "const": "radius" + "const": "radius", + "description": "OAuth login flow. Requires baseUrl." }, "headers": { "type": "object", @@ -42,14 +47,17 @@ "^.*$": { "type": "string" } - } + }, + "description": "Request headers. Values resolve like apiKey." }, "compat": { "$ref": "#/$defs/ProviderCompat", "description": "Provider and model compatibility overrides." }, "authHeader": { - "type": "boolean" + "type": "boolean", + "default": false, + "description": "Whether to send the resolved API key as Authorization: Bearer." }, "models": { "type": "array", @@ -61,25 +69,32 @@ "properties": { "id": { "type": "string", - "minLength": 1 + "minLength": 1, + "description": "Model ID sent to the API." }, "name": { "type": "string", - "minLength": 1 + "minLength": 1, + "description": "Display name, also matched by --model patterns." }, "api": { "type": "string", - "minLength": 1 + "minLength": 1, + "description": "Overrides the provider api." }, "baseUrl": { "type": "string", - "minLength": 1 + "minLength": 1, + "description": "Overrides the provider baseUrl." }, "reasoning": { - "type": "boolean" + "type": "boolean", + "default": false, + "description": "Whether the model supports thinking." }, "thinkingLevelMap": { - "$ref": "#/$defs/ThinkingLevelMap" + "$ref": "#/$defs/ThinkingLevelMap", + "description": "Provider value sent for each thinking level. null marks a level unsupported. Levels the model does not map use the provider's default value through high; xhigh and max are unsupported." }, "input": { "type": "array", @@ -88,7 +103,10 @@ "text", "image" ] - } + }, + "default": [ + "text" + ] }, "inputLimits": { "$ref": "#/$defs/ModelInputLimits" @@ -98,21 +116,26 @@ }, "promptCache": { "$ref": "#/$defs/ModelPromptCache", - "description": "Best-effort prompt cache lifetime in seconds for each retention tier. A missing tier means the lifetime is unknown, so Pi does not warm it." + "description": "Best-effort prompt cache lifetime in seconds for the short and long retention tiers. Pi warms only tiers with a known lifetime." }, "contextWindow": { "type": "number", - "exclusiveMinimum": 0 + "exclusiveMinimum": 0, + "default": 128000, + "description": "Context window in tokens." }, "maxTokens": { "type": "number", - "exclusiveMinimum": 0 + "exclusiveMinimum": 0, + "default": 16384, + "description": "Maximum output tokens." }, "samplingParams": { "type": "object", "patternProperties": { "^.*$": {} - } + }, + "description": "Fields merged into every request body. Applies only to OpenAI-compatible APIs." }, "samplingParamsByThinkingLevel": { "type": "object", @@ -159,7 +182,8 @@ "^.*$": {} } } - } + }, + "description": "samplingParams per thinking level, merged over samplingParams." }, "headers": { "type": "object", @@ -167,7 +191,8 @@ "^.*$": { "type": "string" } - } + }, + "description": "Request headers. Values resolve like apiKey." }, "compat": { "$ref": "#/$defs/ProviderCompat", @@ -184,13 +209,16 @@ "properties": { "name": { "type": "string", - "minLength": 1 + "minLength": 1, + "description": "Display name, also matched by --model patterns." }, "reasoning": { - "type": "boolean" + "type": "boolean", + "description": "Whether the model supports thinking." }, "thinkingLevelMap": { - "$ref": "#/$defs/ThinkingLevelMap" + "$ref": "#/$defs/ThinkingLevelMap", + "description": "Provider value sent for each thinking level. null marks a level unsupported. Levels the model does not map use the provider's default value through high; xhigh and max are unsupported." }, "input": { "type": "array", @@ -263,21 +291,24 @@ }, "promptCache": { "$ref": "#/$defs/ModelPromptCache", - "description": "Best-effort prompt cache lifetime in seconds for each retention tier. A missing tier means the lifetime is unknown, so Pi does not warm it." + "description": "Best-effort prompt cache lifetime in seconds for the short and long retention tiers. Pi warms only tiers with a known lifetime." }, "contextWindow": { "type": "number", - "exclusiveMinimum": 0 + "exclusiveMinimum": 0, + "description": "Context window in tokens." }, "maxTokens": { "type": "number", - "exclusiveMinimum": 0 + "exclusiveMinimum": 0, + "description": "Maximum output tokens." }, "samplingParams": { "type": "object", "patternProperties": { "^.*$": {} - } + }, + "description": "Fields merged into every request body. Applies only to OpenAI-compatible APIs." }, "samplingParamsByThinkingLevel": { "type": "object", @@ -324,7 +355,8 @@ "^.*$": {} } } - } + }, + "description": "samplingParams per thinking level, merged over samplingParams." }, "headers": { "type": "object", @@ -332,7 +364,8 @@ "^.*$": { "type": "string" } - } + }, + "description": "Request headers. Values resolve like apiKey." }, "compat": { "$ref": "#/$defs/ProviderCompat", diff --git a/packages/coding-agent/scripts/generate-references.ts b/packages/coding-agent/scripts/generate-references.ts new file mode 100644 index 000000000..3f70af7ce --- /dev/null +++ b/packages/coding-agent/scripts/generate-references.ts @@ -0,0 +1,177 @@ +#!/usr/bin/env node + +import { mkdirSync, writeFileSync } from "node:fs"; +import { dirname, resolve } from "node:path"; +import { fileURLToPath } from "node:url"; +import { CompatSchemasByApi } from "@earendil-works/pi-ai/providers/compat-schema"; +import { ModelInputLimitsSchema } from "@earendil-works/pi-ai/providers/model-schema"; +import type { TSchema } from "typebox"; +import { ModelsJsonSchemas } from "../src/core/model-config.ts"; + +const packageDirectory = fileURLToPath(new URL("..", import.meta.url)); +const generatedComment = + "This file is generated from TypeScript source. Do not edit it manually; run npm run generate:references."; + +/** The subset of JSON Schema that reference pages render. */ +interface ReferenceSchema { + type?: string; + const?: unknown; + enum?: readonly unknown[]; + anyOf?: readonly ReferenceSchema[]; + items?: ReferenceSchema; + properties?: Readonly>; + required?: readonly string[]; + description?: string; + default?: unknown; +} + +interface ReferenceSection { + heading: string; + intro?: string; + /** Object schema whose properties become table rows. */ + schema?: TSchema; + /** Top-level fields whose type links to another section instead of listing nested fields. */ + links?: Readonly>; + /** Top-level fields listed without their nested fields. */ + collapsed?: readonly string[]; +} + +interface ReferenceArtifact { + path: `docs/${string}.md`; + title: string; + intro: string; + sections: readonly ReferenceSection[]; +} + +/** APIs grouped by the compatibility schema they share, in first-seen order. */ +const compatSchemaApis = new Map(); +for (const [api, schema] of Object.entries(CompatSchemasByApi)) { + compatSchemaApis.set(schema, [...(compatSchemaApis.get(schema) ?? []), api]); +} + +const formatList = (items: readonly string[]) => + items.length > 1 ? `${items.slice(0, -1).join(", ")} and ${items.at(-1)}` : (items[0] ?? ""); + +const referenceArtifacts: readonly ReferenceArtifact[] = [ + { + path: "docs/models-configuration.md", + title: "Models Configuration", + intro: [ + "This reference lists the fields of `models.json`. See [Configure a compatible endpoint](models.md#configure-a-compatible-endpoint) for examples and [Configuration](configuration.md#agent-directory) for the file location.", + 'Add `"$schema": "https://pi.dev/schemas/models.schema.json"` to `models.json` for editor validation and completion.', + ].join("\n\n"), + sections: [ + { + heading: "Providers", + intro: "Each key under `providers` is a provider ID. A built-in provider ID changes that provider. Any other ID adds a provider, which needs `baseUrl` and an `api` at provider or model level.", + schema: ModelsJsonSchemas.provider, + links: { models: "#models", modelOverrides: "#model-overrides", compat: "#compatibility" }, + }, + { + heading: "Models", + intro: "Each `models` entry adds a model to the provider. An entry whose `id` matches an existing model replaces it.", + schema: ModelsJsonSchemas.model, + links: { inputLimits: "#input-limits", compat: "#compatibility" }, + }, + { + heading: "Model overrides", + intro: "Each `modelOverrides` key is the ID of a built-in or extension model. Unknown IDs are ignored. Object fields, such as `cost`, merge with the model's value field by field; other fields replace it.", + schema: ModelsJsonSchemas.modelOverride, + links: { inputLimits: "#input-limits", compat: "#compatibility" }, + }, + { + heading: "Input limits", + intro: "See [Describe model input and caching](models.md#describe-model-input-and-caching).", + schema: ModelInputLimitsSchema, + }, + { + heading: "Compatibility", + intro: "`compat` describes verified differences from an API's standard request and response behavior. Model values override provider values per field. The fields that apply depend on the model's `api`.", + }, + ...[...compatSchemaApis].map(([schema, [api, ...aliases]]) => ({ + heading: `### \`${api}\``, + intro: aliases.length > 0 ? `Also applies to ${formatList(aliases.map((alias) => `\`${alias}\``))}.` : undefined, + schema, + collapsed: ["openRouterRouting", "vercelGatewayRouting"], + })), + ], + }, +]; + +function referenceType(schema: ReferenceSchema): string { + if (schema.const !== undefined) return JSON.stringify(schema.const); + if (schema.enum) return schema.enum.map((value) => JSON.stringify(value)).join(" | "); + if (schema.anyOf) return [...new Set(schema.anyOf.map(referenceType))].join(" | "); + if (schema.type === "array") { + const item = schema.items ? referenceType(schema.items) : "unknown"; + return item.includes(" | ") ? `(${item})[]` : `${item}[]`; + } + return schema.type ?? "unknown"; +} + +/** Nested object whose fields get their own rows, if any of them carry documentation. */ +function documentedObject(schema: ReferenceSchema): { suffix: string; schema: ReferenceSchema } | undefined { + if (schema.type === "array") { + const item = schema.items && documentedObject(schema.items); + return item && { suffix: `[]${item.suffix}`, schema: item.schema }; + } + const object = schema.properties ? schema : schema.anyOf?.find((branch) => branch.properties); + const documented = Object.values(object?.properties ?? {}).some( + (field) => field.description !== undefined || field.default !== undefined, + ); + return object && documented ? { suffix: "", schema: object } : undefined; +} + +const escapeTableText = (text: string) => text.replaceAll("|", "\\|").replaceAll("<", "<"); + +function referenceRows(schema: ReferenceSchema, section: ReferenceSection, prefix = ""): string[] { + const rows: string[] = []; + for (const [name, field] of Object.entries(schema.properties ?? {})) { + const path = `${prefix}${name}`; + const link = prefix === "" ? section.links?.[name] : undefined; + const type = escapeTableText(referenceType(field)); + const typeText = /^[a-z]+$/.test(type) ? type : `\`${type}\``; + const defaultText = field.default === undefined ? "" : `\`${escapeTableText(JSON.stringify(field.default))}\``; + const description = [schema.required?.includes(name) ? "Required." : undefined, field.description] + .filter((text) => text !== undefined) + .join(" "); + rows.push( + `| \`${path}\` | ${link ? `[${typeText}](${link})` : typeText} | ${defaultText} | ${escapeTableText(description)} |`, + ); + if (link || (prefix === "" && section.collapsed?.includes(name))) continue; + const nested = documentedObject(field); + if (nested) rows.push(...referenceRows(nested.schema, section, `${path}${nested.suffix}.`)); + } + return rows; +} + +function renderReference(artifact: ReferenceArtifact): string { + const blocks = [`# ${artifact.title}`, ``, artifact.intro]; + for (const section of artifact.sections) { + blocks.push(section.heading.startsWith("#") ? section.heading : `## ${section.heading}`); + if (section.intro) blocks.push(section.intro); + if (section.schema) { + const rows = referenceRows(section.schema as ReferenceSchema, section); + blocks.push(["| Field | Type | Default | Description |", "|---|---|---|---|", ...rows].join("\n")); + } + } + return `${blocks.join("\n\n")}\n`; +} + +export function renderReferences(): ReadonlyMap { + return new Map(referenceArtifacts.map((artifact) => [artifact.path, renderReference(artifact)])); +} + + +function generateReferences(): void { + for (const [relativePath, content] of renderReferences()) { + const path = resolve(packageDirectory, relativePath); + mkdirSync(dirname(path), { recursive: true }); + writeFileSync(path, content, "utf-8"); + console.log(`Generated packages/coding-agent/${relativePath}`); + } +} + +if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) { + generateReferences(); +} diff --git a/packages/coding-agent/src/core/model-config.ts b/packages/coding-agent/src/core/model-config.ts index 1681ea229..553ff35ba 100644 --- a/packages/coding-agent/src/core/model-config.ts +++ b/packages/coding-agent/src/core/model-config.ts @@ -17,62 +17,99 @@ import { normalizePath } from "../utils/paths.ts"; import { stripBom } from "../utils/text.ts"; const SamplingParamsSchema = Type.Record(Type.String(), Type.Unknown()); -const SamplingParamsByThinkingLevelSchema = Type.Object({ - off: Type.Optional(SamplingParamsSchema), - minimal: Type.Optional(SamplingParamsSchema), - low: Type.Optional(SamplingParamsSchema), - medium: Type.Optional(SamplingParamsSchema), - high: Type.Optional(SamplingParamsSchema), - xhigh: Type.Optional(SamplingParamsSchema), - max: Type.Optional(SamplingParamsSchema), +const SamplingParamsByThinkingLevelSchema = Type.Object( + { + off: Type.Optional(SamplingParamsSchema), + minimal: Type.Optional(SamplingParamsSchema), + low: Type.Optional(SamplingParamsSchema), + medium: Type.Optional(SamplingParamsSchema), + high: Type.Optional(SamplingParamsSchema), + xhigh: Type.Optional(SamplingParamsSchema), + max: Type.Optional(SamplingParamsSchema), + }, + { description: "samplingParams per thinking level, merged over samplingParams." }, +); + +const SamplingParamsFieldSchema = Type.Record(Type.String(), Type.Unknown(), { + description: "Fields merged into every request body. Applies only to OpenAI-compatible APIs.", +}); +const HeadersSchema = Type.Record(Type.String(), Type.String(), { + description: "Request headers. Values resolve like apiKey.", }); -const PositiveTokenCountSchema = Type.Number({ exclusiveMinimum: 0 }); +/** Model fields shared by models entries and modelOverrides entries. Defaults apply only to models entries. */ +const ModelFieldDescriptions = { + name: "Display name, also matched by --model patterns.", + reasoning: "Whether the model supports thinking.", + contextWindow: "Context window in tokens.", + maxTokens: "Maximum output tokens.", +} as const; const ModelDefinitionSchema = Type.Object({ - id: Type.String({ minLength: 1 }), - name: Type.Optional(Type.String({ minLength: 1 })), - api: Type.Optional(Type.String({ minLength: 1 })), - baseUrl: Type.Optional(Type.String({ minLength: 1 })), - reasoning: Type.Optional(Type.Boolean()), + id: Type.String({ minLength: 1, description: "Model ID sent to the API." }), + name: Type.Optional(Type.String({ minLength: 1, description: ModelFieldDescriptions.name })), + api: Type.Optional(Type.String({ minLength: 1, description: "Overrides the provider api." })), + baseUrl: Type.Optional(Type.String({ minLength: 1, description: "Overrides the provider baseUrl." })), + reasoning: Type.Optional(Type.Boolean({ default: false, description: ModelFieldDescriptions.reasoning })), thinkingLevelMap: Type.Optional(ThinkingLevelMapSchema), - input: Type.Optional(Type.Array(ModelInputModalitySchema)), + input: Type.Optional(Type.Array(ModelInputModalitySchema, { default: ["text"] })), inputLimits: Type.Optional(ModelInputLimitsSchema), cost: Type.Optional(ModelCostSchema), promptCache: Type.Optional(ModelPromptCacheSchema), - contextWindow: Type.Optional(PositiveTokenCountSchema), - maxTokens: Type.Optional(PositiveTokenCountSchema), - samplingParams: Type.Optional(SamplingParamsSchema), + contextWindow: Type.Optional( + Type.Number({ exclusiveMinimum: 0, default: 128000, description: ModelFieldDescriptions.contextWindow }), + ), + maxTokens: Type.Optional( + Type.Number({ exclusiveMinimum: 0, default: 16384, description: ModelFieldDescriptions.maxTokens }), + ), + samplingParams: Type.Optional(SamplingParamsFieldSchema), samplingParamsByThinkingLevel: Type.Optional(SamplingParamsByThinkingLevelSchema), - headers: Type.Optional(Type.Record(Type.String(), Type.String())), + headers: Type.Optional(HeadersSchema), compat: Type.Optional(ProviderCompatSchema), }); const ModelOverrideSchema = Type.Object({ - name: Type.Optional(Type.String({ minLength: 1 })), - reasoning: Type.Optional(Type.Boolean()), + name: Type.Optional(Type.String({ minLength: 1, description: ModelFieldDescriptions.name })), + reasoning: Type.Optional(Type.Boolean({ description: ModelFieldDescriptions.reasoning })), thinkingLevelMap: Type.Optional(ThinkingLevelMapSchema), input: Type.Optional(Type.Array(ModelInputModalitySchema)), inputLimits: Type.Optional(ModelInputLimitsSchema), cost: Type.Optional(Type.Partial(ModelCostSchema)), promptCache: Type.Optional(ModelPromptCacheSchema), - contextWindow: Type.Optional(PositiveTokenCountSchema), - maxTokens: Type.Optional(PositiveTokenCountSchema), - samplingParams: Type.Optional(SamplingParamsSchema), + contextWindow: Type.Optional( + Type.Number({ exclusiveMinimum: 0, description: ModelFieldDescriptions.contextWindow }), + ), + maxTokens: Type.Optional(Type.Number({ exclusiveMinimum: 0, description: ModelFieldDescriptions.maxTokens })), + samplingParams: Type.Optional(SamplingParamsFieldSchema), samplingParamsByThinkingLevel: Type.Optional(SamplingParamsByThinkingLevelSchema), - headers: Type.Optional(Type.Record(Type.String(), Type.String())), + headers: Type.Optional(HeadersSchema), compat: Type.Optional(ProviderCompatSchema), }); const ProviderConfigSchema = Type.Object({ - name: Type.Optional(Type.String({ minLength: 1 })), - baseUrl: Type.Optional(Type.String({ minLength: 1 })), - apiKey: Type.Optional(Type.String({ minLength: 1 })), - api: Type.Optional(Type.String({ minLength: 1 })), - oauth: Type.Optional(Type.Literal("radius")), - headers: Type.Optional(Type.Record(Type.String(), Type.String())), + name: Type.Optional(Type.String({ minLength: 1, description: "Display name." })), + baseUrl: Type.Optional( + Type.String({ minLength: 1, description: "API base URL. Also applies to the provider's built-in models." }), + ), + apiKey: Type.Optional( + Type.String({ + minLength: 1, + description: 'Literal key, "$NAME" environment interpolation, or "!command" output.', + }), + ), + api: Type.Optional( + Type.String({ + minLength: 1, + description: + 'API for the provider\'s models, such as "openai-completions", "openai-responses", "anthropic-messages", or "google-generative-ai".', + }), + ), + oauth: Type.Optional(Type.Literal("radius", { description: "OAuth login flow. Requires baseUrl." })), + headers: Type.Optional(HeadersSchema), compat: Type.Optional(ProviderCompatSchema), - authHeader: Type.Optional(Type.Boolean()), + authHeader: Type.Optional( + Type.Boolean({ default: false, description: "Whether to send the resolved API key as Authorization: Bearer." }), + ), models: Type.Optional(Type.Array(ModelDefinitionSchema)), modelOverrides: Type.Optional(Type.Record(Type.String(), ModelOverrideSchema)), }); @@ -86,6 +123,13 @@ export const ModelsConfigSchema = Type.Object({ ...ModelsConfigProperties, }); +/** Entry schemas rendered into docs/models-configuration.md. */ +export const ModelsJsonSchemas = { + provider: ProviderConfigSchema, + model: ModelDefinitionSchema, + modelOverride: ModelOverrideSchema, +}; + const validateModelsConfig = Compile(ModelsConfigSchema); export type ModelsJsonModel = Static; diff --git a/packages/coding-agent/test/references.test.ts b/packages/coding-agent/test/references.test.ts new file mode 100644 index 000000000..1ddcd46bd --- /dev/null +++ b/packages/coding-agent/test/references.test.ts @@ -0,0 +1,17 @@ +import { readFileSync } from "node:fs"; +import { describe, expect, it } from "vitest"; +import { renderReferences } from "../scripts/generate-references.ts"; + +describe("generated reference pages", () => { + // Regression for #10790: models.json fields lost their reference documentation. + it("matches the committed pages", () => { + const rendered = renderReferences(); + expect([...rendered.keys()]).toEqual(["docs/models-configuration.md"]); + for (const [relativePath, expected] of rendered) { + expect( + readFileSync(new URL(`../${relativePath}`, import.meta.url), "utf-8"), + `${relativePath} is stale; run npm run generate:references`, + ).toBe(expected); + } + }); +});