Squash Odysseus development history

specs/model-providers/_readme.md

@@ -0,0 +1,100 @@
+# Provider Capability Specs
+
+Last updated: dev@e71f8ce | 2026-08-25
+
+## Scope
+
+This directory maps serving-provider observations and current model-catalog
+normalization into the canonical layer defined by
+[model-capability-canonical.md](../model-capability-canonical.md). It records
+current Odysseus implementation evidence, merged fixes, reproducible user
+observations, and provider documentation without treating any single source as
+global model truth.
+
+## General To Specific Resolution
+
+Read specs in this order:
+
+1. [openai-compatible.md](openai-compatible.md) for the conservative general
+   identity-only reader;
+2. the serving-provider file for native endpoints, headers, request/response
+   observations, and catalog fields;
+3. [model-quirks.md](../model-quirks.md) for model-specific observations.
+
+Provider files document transport; runtime adapters still own it. Model quirks
+record only deviations and are not a second runtime matcher. Shared model facts
+must not be copied into every provider file. An OpenAI-compatible provider is
+not OpenAI: an explicitly supplied vendor string is preserved even when it uses
+the generic reader.
+
+Current reader dispatch does not infer a provider from payload shape. It uses an explicit vendor, then endpoint kind, label-bounded hostname matches, and common local-port hints. The port hints map 11434 to Ollama, 1234 to LM Studio, 8000 to vLLM, and 30000 to SGLang. Those hints are normalization behavior, not endpoint trust.
+
+## Provider Map
+
+### Implemented canonical readers
+
+- [openai.md](openai.md): identity-only Models API plus Chat/Responses dialects.
+- [openai-compatible.md](openai-compatible.md): generic compatible catalog and runtime dialect boundaries.
+- [openrouter.md](openrouter.md): rich architecture, modalities, parameters, and limits.
+- [google.md](google.md): native paginated Gemini Models API and GenerateContent.
+- [ollama.md](ollama.md): `/api/tags`, `/api/show`, native chat, and OpenAI compatibility.
+- [lm-studio.md](lm-studio.md): native v1 catalog/chat, explicit v0 compatibility, and OpenAI compatibility.
+- [llama-cpp.md](llama-cpp.md): `/props`, `/slots`, OpenAI/Responses/Anthropic surfaces.
+
+### Placeholder identities using the generic reader
+
+- [anthropic.md](anthropic.md): identity-only Models API and native Messages runtime adapter.
+- [vllm.md](vllm.md): common-port identity hint; deployment capability remains unknown.
+- [sglang.md](sglang.md): common-port identity hint; parser/config-dependent capability remains unknown.
+- [hugging-face.md](hugging-face.md): Hub observations and download/fit metadata without a canonical reader.
+
+### Provider observations without a dedicated canonical reader
+
+- [mistral.md](mistral.md): rich model cards, reasoning controls, and structured runtime content.
+- [github-copilot.md](github-copilot.md): account model-list observations and required runtime headers.
+- [chatgpt-subscription.md](chatgpt-subscription.md): Codex model identity and Responses event shape.
+- [cohere.md](cohere.md): native endpoint/catalog observations; not currently normalized.
+
+### Other provider identity and general/identity-only observations
+
+- [moonshot-kimi.md](moonshot-kimi.md)
+- [deepseek.md](deepseek.md)
+- [groq.md](groq.md)
+- [nvidia-nim.md](nvidia-nim.md)
+- [cerebras.md](cerebras.md)
+- [together.md](together.md)
+- [fireworks.md](fireworks.md)
+- [xai.md](xai.md)
+- [zai.md](zai.md)
+- [opencode.md](opencode.md)
+- [perplexity.md](perplexity.md)
+- [github-models.md](github-models.md)
+- [venice.md](venice.md)
+- [azure-openai.md](azure-openai.md)
+- [bedrock.md](bedrock.md)
+- [cloudflare-workers-ai.md](cloudflare-workers-ai.md)
+- [atlas-cloud.md](atlas-cloud.md)
+- [siliconflow.md](siliconflow.md)
+- [minimax.md](minimax.md)
+
+### Other local/proxy serving identities
+
+- [local-compatible-engines.md](local-compatible-engines.md): MLX LM, TGI,
+  LMDeploy, LiteLLM, and unknown compatible deployments.
+
+## Provider Spec Template
+
+Each provider file records:
+
+- provider identity and API dialects;
+- latest observed native catalog endpoint/envelope and capability-bearing fields;
+- whether current source has a dedicated reader or only generic fallback;
+- observed request, tool, text, reasoning, and control paths owned by runtime
+  adapters rather than the catalog reader;
+- what remains per-model/unknown;
+- Odysseus evidence and regressions;
+- fallback/safety behavior and current gaps.
+
+Marketing capability lists and curated picker lists may guide research but do
+not automatically become model claims. Provider-returned false values can be
+negative evidence only at the same provider/endpoint/model scope.

specs/model-providers/anthropic.md

@@ -0,0 +1,39 @@
+# Anthropic Provider Shape
+
+Last updated: dev@e71f8ce | 2026-08-25
+
+## Scope
+
+Canonical placeholder vendor ID `anthropic`; Anthropic Messages runtime
+adapter in `src/llm_core.py`. There is no dedicated Anthropic capability-reader
+module; explicit/auto-detected Anthropic payloads use the generic identity-only
+reader.
+
+## Catalog Shape
+
+`GET /v1/models` returns `data[]` model resources with `id`, `type: model`,
+`display_name`, and `created_at`, plus pagination metadata. These fields prove
+identity/availability only. Do not assume all listed Claude models share
+vision, tools, reasoning, sampling, or context limits.
+
+## Request And Response Shape
+
+Native Messages uses a top-level `system`, alternating `messages`, content
+blocks, `tools[].input_schema`, `tool_use` assistant blocks, and `tool_result`
+user blocks. Text, thinking, signatures, server-tool blocks, and tool calls are
+typed content rather than OpenAI roles/fields. Preserve block IDs/signatures
+needed for continuation.
+
+Sampling and thinking support can be version/model specific. The Opus 4.7+ sampling omission is a model-scoped runtime observation, not an Anthropic-wide rule. Runtime version parsing accepts explicit major/minor IDs and later major-only IDs such as `claude-opus-5`, treats a missing minor as `.0`, caps both components so date stamps cannot be misread as versions, and keeps legacy Claude 3 Opus sampling intact. Anthropic-compatible proxies are Anthropic dialect only when configured or their exact payload/endpoint shape proves it (#3110).
+
+## Fallback And Safety
+
+Runtime and canonical reader detection use label-bounded Anthropic host matching or an explicit endpoint kind. A provider using Anthropic Messages through another host must be explicit. Identity-only model cards remain unknown.
+
+## Current Gaps
+
+- The public model list does not provide per-model canonical capability data.
+- There is no dedicated Anthropic canonical reader; only `id`, `name`, or
+  `model` identity survives generic normalization.
+- Runtime model-version parsing needs structured identity before a later
+  consumer can centralize sampling exceptions without another name matcher.

specs/model-providers/atlas-cloud.md

@@ -0,0 +1,21 @@
+# Atlas Cloud Provider Shape
+
+Last updated: dev@28d27ee | 2026-07-17
+
+## Scope
+
+Canonical provider ID `atlas_cloud`; OpenAI-compatible provider proposed in
+#5566 with live `/v1/models` observations for current Qwen/DeepSeek offerings.
+
+## Shape
+
+Treat the observed list as identity-only. Even capability-looking item fields
+remain raw until an Atlas-specific discriminating shape intentionally maps
+them. The model IDs observed by a PR demonstrate availability at that time,
+not permanent capability or a reason to hardcode family-name behavior.
+
+## Fallback And Current Gaps
+
+Exact Atlas Cloud host or explicit kind preserves identity; otherwise use the
+inventory fallback. The provider work is open/unmerged and has no independently
+versioned rich catalog schema, so evidence remains provisional.

specs/model-providers/azure-openai.md

@@ -0,0 +1,26 @@
+# Azure OpenAI Provider Shape
+
+Last updated: dev@28d27ee | 2026-07-17
+
+## Scope
+
+Canonical provider ID `azure_openai`; Azure deployment-scoped OpenAI dialects;
+custom endpoints use explicit configuration.
+
+## Shape
+
+Azure commonly identifies deployments rather than globally stable model IDs.
+Preserve endpoint, deployment ID, API version, and underlying model/version as
+separate structured identity when returned. A standard OpenAI-compatible model
+list is identity-only until an Azure-specific reader intentionally maps its
+deployment fields.
+
+Request paths and authentication can be deployment/API-version specific; do
+not blindly append public OpenAI paths or copy provider quirks. Capability and
+limits are deployment scoped.
+
+## Fallback And Current Gaps
+
+Known `*.openai.azure.com` hosts select Azure OpenAI; other Azure gateways need
+explicit kind. Odysseus lacks a native Azure deployment catalog reader and
+structured API-version persistence in the canonical record.

specs/model-providers/bedrock.md

@@ -0,0 +1,23 @@
+# AWS Bedrock Provider Shape
+
+Last updated: dev@28d27ee | 2026-07-17
+
+## Scope
+
+Canonical provider ID `bedrock`; UI/provider mapping currently recognizes AWS
+Bedrock, but the canonical layer has no native Bedrock runtime reader.
+
+## Shape
+
+Bedrock is not generally an OpenAI-compatible host: model IDs, inference
+profiles, request/response unions, signing, and per-family payloads differ.
+Only an explicitly configured OpenAI/Anthropic-compatible gateway may use those
+dialects. Native Bedrock capability must come from a versioned Bedrock model
+catalog plus exact foundation-model/inference-profile identity.
+
+## Fallback And Current Gaps
+
+Do not classify all `amazonaws.com` hosts as Bedrock; use explicit kind or a
+future region-aware exact host/path shape. General fallback is safe only behind
+an explicitly compatible gateway. Native signing, catalogs, and family payload
+mappings remain unimplemented.

specs/model-providers/cerebras.md

@@ -0,0 +1,23 @@
+# Cerebras Provider Shape
+
+Last updated: dev@28d27ee | 2026-07-17
+
+## Scope
+
+Canonical provider ID `cerebras`; OpenAI-compatible cloud transport; runtime
+provider detection and cache-affinity safeguards in `src/llm_core.py`.
+
+## Shape And Observations
+
+Model lists use the general identity-only inventory reader. Cerebras rejects
+llama.cpp-only `session_id` and `cache_prompt` fields (#4640), so cloud identity
+must suppress local slot-affinity extensions. Current regressions pin this
+provider boundary.
+
+Tool, reasoning, structured output, and limits remain per model. Do not promote
+them from the fact that the API accepts OpenAI Chat.
+
+## Fallback And Current Gaps
+
+Exact `*.cerebras.ai` selects provider identity. Compatible proxies require
+explicit configuration. No rich per-model Cerebras catalog reader is present.

specs/model-providers/chatgpt-subscription.md

@@ -0,0 +1,47 @@
+# ChatGPT Subscription Provider Shape
+
+Last updated: dev@e57f60b | 2026-07-20
+
+## Scope
+
+Canonical provider ID `chatgpt_subscription`; Codex Responses transport;
+auth and runtime code in `src/chatgpt_subscription.py`,
+`routes/chatgpt_subscription_routes.py`, and `src/llm_core.py`.
+There is no dedicated ChatGPT Subscription canonical reader on current `dev`.
+
+## Catalog Shape
+
+The account-scoped Codex models endpoint returns root `models[]`; `slug` is the
+request identity and `visibility`/`priority` control availability/order. These
+fields do not prove tools, reasoning, vision, or context. Null/malformed model
+lists fail soft rather than crashing discovery (#5280/#5281).
+
+The canonical generic reader does not accept `slug`-only items, so this runtime
+catalog is not currently normalized into `ModelCapabilityRecord` values.
+
+## Request And Response Shape
+
+Transport uses a ChatGPT backend Responses endpoint, `input` items, flattened
+function tools, streamed function-call argument events, exact `call_id`, and
+`function_call_output` continuation. Parallel calls and encrypted reasoning
+continuity require preserving typed output/history rather than coercing all
+roles to text. This shape is supported by the existing adapter and the focused
+tool-calling follow-up evidence in #5490; unmerged observations remain claimed
+until integrated/reproduced.
+
+OAuth/device credentials and refresh are provider-session behavior. Expired
+credentials should return an actionable reconnect error, not generic model
+failure.
+
+## Fallback And Safety
+
+Only the explicit internal base/ChatGPT host selects this provider. Never send
+subscription credentials to a custom OpenAI-compatible URL. Catalog slugs stay
+identity-only unless account-scoped fields or probes supply capability.
+
+## Current Gaps
+
+- Comprehensive Responses tool/reasoning parity is still evolving.
+- Account model slugs are not consumed by the canonical reader package.
+- The account catalog does not currently provide a complete canonical
+  capability card for every slug.

specs/model-providers/cloudflare-workers-ai.md

@@ -0,0 +1,21 @@
+# Cloudflare Workers AI Provider Shape
+
+Last updated: dev@28d27ee | 2026-07-17
+
+## Scope
+
+Canonical provider ID `cloudflare_workers_ai`; OpenAI-compatible Workers AI
+endpoint observations in #5175; explicit provider configuration required.
+
+## Shape
+
+Cloudflare account/path identity is part of the endpoint. Use the general
+OpenAI-compatible inventory reader for returned model cards, preserving full
+model IDs but no capability fields.
+Do not identify the provider from broad `api.cloudflare.com` alone or infer
+capability from Workers AI catalog prose.
+
+## Fallback And Current Gaps
+
+Provider identity must be explicit until a narrow account/AI path matcher is
+implemented. There is no rich normalized capability catalog reader.

specs/model-providers/cohere.md

@@ -0,0 +1,56 @@
+# Cohere Provider Shape
+
+Last updated: dev@e57f60b | 2026-07-20
+
+## Scope
+
+Documented provider identity `cohere`; native Chat v2 plus the OpenAI
+Compatibility API. Current `dev` has no dedicated Cohere capability reader or
+direct Cohere request adapter; compatible endpoints use the general runtime
+path when explicitly configured.
+
+## Catalog Shape
+
+`GET /v1/models` returns a paginated `models[]` envelope. Each model can carry
+`name`, `endpoints`, `default_endpoints`, `context_length`, `features`, and
+`sampling_defaults`; the root can carry `next_page_token`.
+
+These are candidate fields for a future dedicated reader:
+
+- a single canonical family from `endpoints`: `chat`/`generate`, `embed`,
+  `rerank`, or `classify`;
+- `context_length` to the endpoint/model context limit;
+- known sampling-default keys to deterministic controls.
+
+Current canonical normalization does not map them. When the generic reader is
+explicitly selected with vendor `cohere`, it preserves only item identity plus
+the raw item; family, context, features, and sampling controls stay unknown.
+
+## Request And Response Shape
+
+Native `POST /v2/chat` uses `messages`, structured content blocks, tools,
+`response_format`, sampling fields, and an optional structured `thinking`
+object. Text lives in `message.content[type=text].text`; reasoning-capable
+models use `message.content[type=thinking].thinking`. Streaming uses typed
+events rather than one generic text delta.
+
+The OpenAI compatibility base is `/compatibility/v1`. Its current chat subset
+includes tools, structured output, sampling, and `reasoning_effort`, but model
+support remains per-model. In the compatibility dialect only `none` and `high`
+currently map to native thinking off/on; do not assume low/medium support.
+
+## Fallback And Safety
+
+No Cohere host or payload-shape detection exists in the canonical reader
+registry. The caller must supply provider/endpoint configuration. Marketing
+pages and provider-wide endpoint features do not grant every listed model
+tools, vision, or reasoning.
+
+## Evidence And Gaps
+
+- Official List/Get Models resources define the catalog fields.
+- Official Chat v2, Reasoning, and Compatibility API resources define the
+  transport and thinking controls.
+- Odysseus has no direct Cohere request adapter, canonical reader, or sanitized
+  canonical fixtures yet; both normalization and runtime integration remain
+  follow-up work.

specs/model-providers/deepseek.md

@@ -0,0 +1,30 @@
+# DeepSeek Provider Shape
+
+Last updated: dev@2e2bb52 | 2026-08-16
+
+## Scope
+
+Canonical provider ID `deepseek`; official cloud OpenAI-compatible API;
+curation/detection in `routes/model_routes.py` and runtime reasoning handling in
+`src/llm_core.py`.
+
+## Shape And Observations
+
+Use the general model-list inventory shape; capability-looking fields remain
+unknown until a DeepSeek-native reader maps them. Cloud response history can use
+`reasoning_content`; preserve it structurally for reasoning turns and tool
+continuation (#968, #3152). `deepseek-chat`, reasoning models, distilled local
+variants, and future V4 models do not share one capability record.
+
+Cloud endpoint evidence can support tools while a local DeepSeek-R1 deployment
+may not have a working tool parser. Existing tool-support tests intentionally
+separate official host from local engine/model-name heuristics.
+
+Current runtime thinking-pattern detection includes DeepSeek V4 identifiers so their structured reasoning channel is handled like the other supported DeepSeek reasoning families. This name-level compatibility rule is not canonical capability evidence and does not make every V4-labelled local deployment tool-capable.
+
+## Fallback And Current Gaps
+
+Exact `*.deepseek.com` selects provider identity; self-hosted checkpoints use
+Ollama/vLLM/SGLang/llama.cpp identity. Curated model IDs and pricing/context
+tables are compatibility data, not authoritative capability. A rich official
+model-card reader is still absent.

specs/model-providers/fireworks.md

@@ -0,0 +1,22 @@
+# Fireworks AI Provider Shape
+
+Last updated: dev@28d27ee | 2026-07-17
+
+## Scope
+
+Canonical provider ID `fireworks`; OpenAI-compatible cloud transport with path
+prefixes such as `/inference/v1`; curation and URL handling in
+`routes/model_routes.py` and `src/endpoint_resolver.py`.
+
+## Shape
+
+Use the general identity-only inventory reader. Fireworks IDs can contain
+account/model paths; preserve the full request ID and endpoint scope. Item
+modalities, supported parameters, task/type, and limits require a
+Fireworks-native mapped shape before promotion.
+
+## Fallback And Current Gaps
+
+Exact `*.fireworks.ai` preserves provider identity and its configured path
+prefix. Do not normalize account-qualified IDs by taking the last path segment.
+No verified rich Fireworks capability catalog is currently mapped.

specs/model-providers/github-copilot.md

@@ -0,0 +1,46 @@
+# GitHub Copilot Provider Shape
+
+Last updated: dev@e57f60b | 2026-07-20
+
+## Scope
+
+Canonical provider ID `copilot`; OpenAI-compatible chat with Copilot headers
+and OAuth; runtime adapter `src/copilot.py` and routes in
+`routes/copilot_routes.py`. There is no dedicated Copilot canonical reader on
+current `dev`.
+
+## Catalog Shape
+
+The observed Copilot `/models` response uses `data[]` entries with:
+
+- `id`;
+- `model_picker_enabled`;
+- `capabilities.supports.tool_calls` and `.vision`;
+- optional limit/family metadata.
+
+Runtime model discovery uses picker state for availability. The canonical
+reader package does not map the nested support fields; an explicitly supplied
+`copilot` vendor currently uses generic identity-only normalization, and
+`model_picker_enabled` does not become canonical capability.
+
+## Request And Response Shape
+
+Chat is OpenAI-compatible but requires Copilot/GitHub API version, editor/plugin
+identity, intent, integration, and initiator headers; image requests add the
+vision request flag. Header derivation must tolerate malformed message entries.
+OAuth token exchange and access policies are provider authentication, not model
+capability.
+
+## Fallback And Safety
+
+Use exact GitHub Copilot host or explicit kind, including the constrained
+enterprise `copilot-api.*.ghe.com` form. Do not treat arbitrary `ghe.com` hosts
+as Copilot. Official model availability tables are useful registry context but
+do not replace the account-scoped catalog response.
+
+## Current Gaps
+
+- The catalog shape is implementation-observed and needs ongoing fixture
+  comparison with current Copilot clients.
+- Copilot catalog capability fields are not normalized by current `dev`.
+- Account/plan/policy availability must remain endpoint-user scoped.

specs/model-providers/github-models.md

@@ -0,0 +1,21 @@
+# GitHub Models Provider Shape
+
+Last updated: dev@28d27ee | 2026-07-17
+
+## Scope
+
+Canonical provider ID `github_models`; OpenAI-compatible GitHub Models/Azure
+inference endpoint observed in #2995; distinct from GitHub Copilot.
+
+## Shape
+
+Use general identity-only inventory. Deployment IDs and account access
+can differ from upstream model IDs. Do not copy Copilot picker metadata,
+headers, plan rules, or capabilities into GitHub Models; they are separate
+providers despite shared GitHub branding.
+
+## Fallback And Current Gaps
+
+The known `models.inference.ai.azure.com` host selects GitHub Models. Other
+Azure deployment hosts require explicit provider configuration. No rich
+account-scoped capability catalog is currently mapped.

specs/model-providers/google.md

@@ -0,0 +1,54 @@
+# Google Gemini Provider Shape
+
+Last updated: dev@e71f8ce | 2026-08-25
+
+## Scope
+
+Canonical provider ID `google`; native GenerateContent plus optional Google
+OpenAI-compatible chat; readers `google.py` and
+`google_ai_studio_mapping.py`; catalog/probe ownership in
+`routes/model_routes.py`.
+
+## Catalog Shape
+
+Use the native paginated `GET /v1beta/models` endpoint, including
+`nextPageToken`, with `x-goog-api-key` when configured. `models[]` can contain:
+
+- `name`, `baseModelId`, `version`, and `displayName`;
+- `inputTokenLimit` and `outputTokenLimit`;
+- `supportedGenerationMethods`;
+- `thinking`, `temperature`, `maxTemperature`, `topP`, and `topK`.
+
+Embedding-only methods map to embedding. Generation methods prove a native
+method, not chat/image/video/audio modality, so those records remain unknown
+unless stronger structured evidence exists. `thinking: true` and explicit
+sampling fields map to a reasoning claim and controls. Model IDs such as
+Imagen, Veo, or TTS names are not parsed.
+
+## Request And Response Shape
+
+Native generation uses `contents`, `systemInstruction`,
+`generationConfig`, `tools[].functionDeclarations`, and
+`models/{model}:generateContent|streamGenerateContent`. Responses use
+`candidates[].content.parts[]` for `text`, `functionCall`, `functionResponse`,
+`thought`, and `thoughtSignature`; token accounting is in `usageMetadata`.
+Native Google tool/thought continuity must not be flattened through an
+OpenAI-only history shape.
+
+## Fallback And Safety
+
+Prefer native model metadata even when chat is configured through Google's
+OpenAI compatibility URL. Pagination parameters must remain stable between
+pages. The route probe activates only for the exact
+`generativelanguage.googleapis.com` hostname, filters the picker list to
+content-generation methods, returns no curated fallback after probe failure,
+and defaults those endpoints to manual catalog refresh unless explicitly
+overridden. The canonical Google reader is not yet called by that probe.
+Unknown methods and fields stay raw; unrecognized prediction models remain
+unknown.
+
+## Current Gaps
+
+- The Models resource does not expose full modalities for every Google media
+  family.
+- Native Gemini request/response support is not yet the only runtime path.

specs/model-providers/groq.md

@@ -0,0 +1,24 @@
+# Groq Provider Shape
+
+Last updated: dev@28d27ee | 2026-07-17
+
+## Scope
+
+Canonical provider ID `groq`; OpenAI-compatible cloud transport; detection and
+request behavior in `src/llm_core.py`.
+
+## Shape
+
+Model discovery falls back to the general `data[].id` identity shape. Richer
+fields require a Groq-native mapped shape even when the payload happens to
+supply modalities, supported parameters, or limits. Groq transport may accept OpenAI-style tools and streaming extensions,
+but support remains per model and account.
+
+Runtime currently exempts Groq/OpenRouter from some parameter stripping paths;
+that is transport compatibility, not a provider-wide model capability claim.
+
+## Fallback And Current Gaps
+
+Exact `*.groq.com` preserves Groq identity. Do not infer Llama/Gemma model
+capabilities from IDs. There is no canonical rich Groq model-card reader or
+freshness policy yet.

specs/model-providers/hugging-face.md

@@ -0,0 +1,41 @@
+# Hugging Face Provider And Registry Shape
+
+Last updated: dev@e57f60b | 2026-07-20
+
+## Scope
+
+Canonical placeholder vendor ID `huggingface`; download/fit metadata in
+`services/hwfit/`; OpenAI-compatible inference providers/TGI handled as their
+serving dialect. There is no dedicated Hugging Face canonical reader on
+current `dev`.
+
+## Hub Model Shape
+
+Hub model info can provide `modelId`/`id`, `pipeline_tag`, `tags`, `config`, and
+card metadata. Current canonical normalization does not map `pipeline_tag`,
+`config.model_type`, or Hub task/modality fields. An explicitly selected
+Hugging Face vendor uses generic identity-only normalization.
+
+This source is `cookbook_hf`/registry confidence, not live endpoint truth.
+Free-form tags, README/card prose, repository names, and architecture names do
+not automatically claim capability. A serving engine can load a model with
+missing projection, different template, or disabled parser.
+
+## Serving Shape
+
+Hugging Face routed inference and TGI can expose OpenAI-compatible endpoints;
+their model list may be identity-only. Keep Hub identity separate from the
+serving endpoint and merge only when exact revision/model identity is known.
+
+## Fallback And Safety
+
+Hub metadata can fill a scoped registry record after provider payload fields
+and probes, but must not overwrite fresh endpoint-negative evidence. Treat
+remote code, model cards, and repository files as untrusted content.
+
+## Current Gaps
+
+- Revision/digest linkage between downloads, Hub records, and serving
+  endpoints is incomplete.
+- Hub task/family metadata is not consumed by the canonical reader package.
+- Pipeline tags can be missing or overly broad; unknown stays unknown.

specs/model-providers/llama-cpp.md

@@ -0,0 +1,47 @@
+# llama.cpp Provider Shape
+
+Last updated: dev@e57f60b | 2026-07-20
+
+## Scope
+
+Canonical provider ID `llamacpp`; OpenAI Chat/Responses and Anthropic Messages
+compatibility plus native server metadata; reader
+`src/model_capability_readers/llamacpp.py`.
+
+## Metadata Shapes
+
+`/v1/models` provides served identity and can include server model entries;
+native `/props` is authoritative for the running model/server combination:
+
+- `model_alias`/`model_path`;
+- `default_generation_settings.n_ctx` and sampling `params`;
+- `total_slots` and optional `/slots[].n_ctx` fallback;
+- `chat_template_caps` for tools/system role;
+- `modalities.vision|audio`;
+- current server/build state.
+
+Capability depends on weights, projection/model assets, chat template, parser,
+and launch flags. It is endpoint evidence, not a checkpoint-name claim.
+`/props` and `/v1/models` can be merged only for the same served identity.
+
+## Request And Response Shape
+
+llama-server supports several OpenAI-compatible tasks and native extensions.
+Do not infer embeddings/rerank/chat solely from the OpenAI model card; use an
+explicit server model capability field or endpoint configuration. Tool and
+reasoning correctness can depend on selected chat template and parser.
+
+## Fallback And Safety
+
+The registry selects llama.cpp through an explicit vendor or endpoint kind; it
+does not auto-detect `/props` from payload shape. Port 8000 currently maps to
+the vLLM placeholder, while 8080 falls through to generic OpenAI-compatible.
+llama.cpp-only `session_id` and `cache_prompt` affinity fields must remain local
+endpoint behavior and never leak to strict cloud providers (#4640 and current
+affinity tests).
+
+## Current Gaps
+
+- Multi-model routing requires per-served-model `/props` association.
+- Parser/template configuration is not yet fully represented in canonical
+  endpoint metadata.

specs/model-providers/lm-studio.md

@@ -0,0 +1,45 @@
+# LM Studio Provider Shape
+
+Last updated: dev@e57f60b | 2026-07-20
+
+## Scope
+
+Canonical provider ID `lmstudio`; native LM Studio v1 plus OpenAI Chat and
+Responses compatibility; reader `src/model_capability_readers/lmstudio.py`.
+
+## Catalog Shapes
+
+Preferred shape is `GET /api/v1/models` with root `models[]`. Current fields
+include `key`, `type` (`llm` or `embedding`), display/publisher data,
+`architecture`, quantization/format/size, `max_context_length`,
+`loaded_instances[].config.context_length`, and a capability object containing
+`vision`, `trained_for_tool_use`, and reasoning options/defaults.
+
+Compatibility shape `GET /api/v0/models` uses `data[]` with `id`, `type`
+(`llm`, `vlm`, or embeddings), `arch`, `compatibility_type`, state, and
+context metadata. It is an explicit older shape, not a loose fallback.
+OpenAI `/v1/models` is identity-only when native endpoints are unavailable.
+
+Loaded-instance context is the effective runtime context; maximum context is a
+separate limit. Model type maps family, explicit capability booleans map
+vision/tools/reasoning, and architecture is provider-reported model family.
+
+## Request And Response Shape
+
+Native v1 chat is `/api/v1/chat` and can expose stateful/MCP-oriented output;
+LM Studio also supports OpenAI Chat and Responses compatibility. Keep dialect
+selection explicit because tool/MCP features differ between native and
+compatible paths.
+
+## Fallback And Safety
+
+Current reader detection identifies port 1234 as LM Studio. Prefer pathless
+native `/api/v1/models` discovery where configured (#1122, #3615), then v0,
+then general identity. The port mapping is a normalization hint, not endpoint
+trust. An error object from an unsupported native route is not a model list.
+
+## Current Gaps
+
+- Runtime discovery does not yet persist native capability records.
+- LM Studio API capabilities continue to evolve; each new native version needs
+  an explicit shape fixture before promotion.

specs/model-providers/local-compatible-engines.md

@@ -0,0 +1,37 @@
+# Other Local And Proxy Compatible Engines
+
+Last updated: dev@28d27ee | 2026-07-17
+
+## Scope
+
+Canonical explicit identities `mlx_lm`, `text_generation_inference`,
+`lmdeploy`, and `litellm`, plus unknown OpenAI-compatible deployments not
+covered by the native Ollama, LM Studio, llama.cpp, vLLM, or SGLang specs.
+
+## Shape
+
+Use explicit endpoint kind when known; otherwise use only the general model
+list envelopes for inventory identity. Capability-looking structural fields
+remain raw. Local host and port do not distinguish these engines.
+MLX/Cookbook launch recipes, TGI task configuration, LMDeploy
+adapters, and LiteLLM upstream routing can all change capability independently
+of the model ID.
+
+Proxy model aliases are endpoint scoped. A proxy may return richer fields, but
+unknown keys remain raw until a versioned shape is added. Provider-specific
+headers/extensions must not be applied based on a port or upstream model name.
+
+## Fallback And Safety
+
+Discovery can probe cheap native identity endpoints when available, but
+capability probes execute only explicit bounded test contracts. Never read
+broad server/environment dumps as ordinary model metadata. Unknown compatible
+servers should still list identities and make conservative text calls where
+explicitly configured, without appearing on capability-gated surfaces.
+
+## Current Gaps
+
+- These engines need individual safe metadata fixtures before they can graduate
+  from general fallback.
+- Gateway upstream identity and effective downstream model capability are not
+  yet represented as a chain.

specs/model-providers/minimax.md

@@ -0,0 +1,48 @@
+# MiniMax Provider Shape
+
+Last updated: dev@28d27ee | 2026-07-17
+
+## Scope
+
+Canonical provider ID `minimax`; international host `api.minimax.io`, China
+host `api.minimaxi.com`; current OpenAI-compatible and recommended
+Anthropic-compatible text transports. Odysseus contains MiniMax-oriented tool
+output handling and local-serving guidance but no dedicated catalog reader.
+
+## Catalog Shape
+
+Current `GET /v1/models` is an OpenAI-compatible identity list:
+`object: list`, `data[]`, and model cards containing `id`, `object: model`,
+`created`, and `owned_by: minimax`. The `owned_by` discriminator identifies the
+provider shape, but the card exposes no per-model capability or modality
+fields. Keep these records unknown and preserve raw identity metadata.
+
+Do not backfill current model capabilities, token limits, or modalities from
+the platform overview into this list response. Those tables are useful scoped
+registry evidence only after model/version identity and freshness are carried
+explicitly.
+
+## Request And Response Shape
+
+- OpenAI compatibility uses `/v1/chat/completions` and structured
+  `reasoning_content` alongside normal message content.
+- Anthropic compatibility uses `/anthropic/v1/messages`; the current M2.7
+  family supports typed thinking blocks and interleaved thinking, making this
+  the preferred reasoning/tool-continuation transport in provider guidance.
+- Native audio, image, video, music, and file endpoints are separate product
+  shapes. They must not be inferred from presence in the text model list.
+
+## Local Deployments
+
+The current provider guide documents vLLM, SGLang, and MLX deployment. Those
+instances retain serving-engine identity and configuration-derived capability;
+the checkpoint name alone does not turn a vLLM/SGLang card into the hosted
+MiniMax provider shape.
+
+## Fallback And Current Gaps
+
+Exact MiniMax hosts or the discriminating `owned_by: minimax` model-list shape
+select provider identity. Unknown compatible proxies retain the general shape.
+The identity list does not safely distinguish M2 reasoning behavior from
+speech/image/video/music products, so exact model quirks remain documentation
+until structured model-version evidence reaches runtime request builders.

specs/model-providers/mistral.md

@@ -0,0 +1,46 @@
+# Mistral Provider Shape
+
+Last updated: dev@2e2bb52 | 2026-08-16
+
+## Scope
+
+Canonical provider ID `mistral`; OpenAI-compatible chat with Mistral response
+extensions and runtime handling in `src/llm_core.py`. There is no dedicated
+Mistral canonical reader on current `dev`.
+
+## Catalog Shape
+
+`GET /v1/models` returns `data[]` cards with `id`, `root`, aliases,
+`max_context_length`, and `capabilities` booleans including
+`completion_chat`, `completion_fim`, `function_calling`, `vision`,
+`classification`, and lifecycle/fine-tuning fields. These are candidate fields
+for a future dedicated reader:
+
+- chat/FIM or classification family;
+- vision input;
+- function calling;
+- explicitly reported reasoning/structured output when present;
+- context limit and root family.
+
+Fine-tuning availability and archived status are not inference capabilities.
+The current generic reader retains identity/raw data only and does not map any
+of these fields. Different Mistral models retain independent identities.
+
+## Request And Response Shape
+
+Reasoning-capable models accept graded `reasoning_effort`. Mistral can return `content` as typed blocks: a `thinking` block containing text fragments plus a normal `text` block. Runtime normalizes those blocks for async utility calls as well as chat/stream paths, keeping reasoning and visible text separate instead of stringifying the list or scanning text tags (#4698, #5882).
+
+## Fallback And Safety
+
+Runtime `llm_core` detects label-bounded Mistral hosts for request/response
+handling. The canonical registry has no Mistral host or rich-payload detector;
+an explicitly supplied `mistral` vendor falls back to generic identity. A
+Mistral model served through another engine uses that serving engine's dialect.
+
+## Current Gaps
+
+- Catalog reasoning fields vary across model-card generations; absent remains
+  unknown.
+- Mistral catalog capability fields are not normalized by current `dev`.
+- Runtime thinking-family selection still uses names and should migrate to
+  structured root/capability identity.

specs/model-providers/moonshot-kimi.md

@@ -0,0 +1,30 @@
+# Moonshot And Kimi Provider Shape
+
+Last updated: dev@28d27ee | 2026-07-17
+
+## Scope
+
+Provider IDs `moonshot` for official Moonshot API and `kimi_code` for the Kimi
+Code surface; OpenAI-compatible transport with provider-specific headers and
+model-specific behavior in `src/llm_core.py`.
+
+## Shape And Observations
+
+Model lists use the general OpenAI-compatible identity shape unless a richer
+account response is returned. Official Kimi K2.5/K2.6 fixes temperature by
+thinking mode, so Odysseus omits `temperature` rather than sending an invalid
+value (#3960). Thinking tool-call continuation requires preservation of
+assistant `reasoning_content` (#3118). Kimi Code negotiates a small exact
+User-Agent set on 403 and caches the accepted value; this is provider transport,
+not model capability.
+
+Reports distinguish K2.5/K2.6 multimodality from older K2 variants (#2522).
+Promote those claims only through exact structured model IDs/families, not a
+`kimi` name match.
+
+## Fallback And Current Gaps
+
+Keep Moonshot and Kimi Code identities distinct even when both use OpenAI Chat.
+Self-hosted Kimi checkpoints inherit their serving engine shape, not official
+Moonshot sampling rules. The provider catalog does not yet yield a complete
+canonical capability card.

specs/model-providers/nvidia-nim.md

@@ -0,0 +1,28 @@
+# NVIDIA NIM Provider Shape
+
+Last updated: dev@28d27ee | 2026-07-17
+
+## Scope
+
+Canonical provider ID `nvidia`; OpenAI-compatible NVIDIA/NIM endpoints; current
+provider detection, catalog routing, and reasoning stream handling in
+`src/llm_core.py`, `routes/model_routes.py`, and tests.
+
+## Shape And Observations
+
+Model lists use the general identity-only shape; capability-looking fields
+require a provider-native mapped shape.
+NIM/vLLM-style responses have emitted structured `reasoning` while older paths
+used `reasoning_content`; Odysseus routes either to the reasoning channel
+(#602). This response compatibility does not claim that every NIM model
+reasons.
+
+NVIDIA endpoints can host many unrelated model families with different tools,
+vision, context, and parser support. Keep endpoint/model stable identity and
+prefer provider fields or probes.
+
+## Fallback And Current Gaps
+
+Exact NVIDIA host preserves provider identity; private NIM installations need
+explicit endpoint kind because a local port/hostname is not distinctive. No
+safe normalized native NIM capability endpoint is currently consumed.

specs/model-providers/ollama.md

@@ -0,0 +1,52 @@
+# Ollama Provider Shape
+
+Last updated: dev@e71f8ce | 2026-08-25
+
+## Scope
+
+Canonical provider ID `ollama`; native Ollama chat/generate plus OpenAI
+compatibility; reader `src/model_capability_readers/ollama.py`; discovery and
+runtime code in `routes/model_routes.py` and `src/llm_core.py`.
+
+## Catalog And Detail Shapes
+
+Use two native steps:
+
+1. `GET /api/tags` returns `models[]` identity (`name`/`model`, digest,
+   `details.family|families`, format, parameter size, quantization). Tags do not
+   claim capabilities.
+2. `POST /api/show` for a selected model returns explicit `capabilities[]`,
+   `details`, and `model_info`. Map completion/chat, embedding, vision, tools,
+   and thinking/reasoning tokens. Map context from exact `context_length` or
+   native `<architecture>.context_length` fields.
+
+The reader does not parse model names or architecture names. It does parse a
+two-column serialized `parameters` value and can take `num_ctx` from it before
+falling back to exact or suffix `*.context_length` keys in structured mappings.
+The parameters text is used only for that keyed limit lookup, not capability
+inference.
+
+## Request And Response Shape
+
+Native chat uses `/api/chat`, `messages`, optional OpenAI-shaped tool
+definitions, `format`, `options`, and model-dependent `think`. Responses use
+`message.content`, `message.thinking`, and `message.tool_calls`. Generate uses
+top-level `response` and `thinking`. OpenAI compatibility is a separate dialect
+and can change control names independently.
+
+Manual Ollama endpoints registered against the OpenAI-compatible `/v1` surface default to text/prompted tools unless the operator explicitly enables `supports_tools`; model naming alone does not opt that dialect into native function schemas.
+
+Thinking control is model-specific: most documented reasoning families accept
+a native bool, while GPT-OSS accepts low/medium/high and cannot be fully
+disabled. A reported Ollama 0.20.6 Qwen3.5 OpenAI-compat path requires
+`reasoning_effort: none` rather than `think: false` (#5503); keep it versioned
+and low-confidence until corroborated.
+
+## Fallback And Safety
+
+Current reader detection identifies port 11434 as Ollama, in addition to an explicit endpoint kind or an exact/label-bounded `ollama.com` hostname. This is a normalization hint, not endpoint trust or capability evidence. Names that contain `vision`, `embed`, or `qwen` are not capability evidence (#3743, #4487).
+
+## Current Gaps
+
+- List discovery needs an orchestrated `/api/show` detail step per model.
+- Runtime OpenAI-compat thinking suppression still contains name heuristics.

specs/model-providers/openai-compatible.md

@@ -0,0 +1,57 @@
+# General OpenAI-Compatible Inventory Fallback
+
+Last updated: dev@2e2bb52 | 2026-08-16
+
+## Scope
+
+Canonical compatibility identity `generic_openai`; identity-only reader
+`src/model_capability_readers/generic_openai.py`; shared envelope and identity
+helpers in `src/model_capability_readers/base.py`.
+
+This is not a universal OpenAI-compatible capability schema. Transport request
+and response behavior remains in `src.llm_core` and provider adapters.
+
+## Accepted Inventory Shape
+
+- `{"data": [...]}`;
+- `{"models": [...]}`.
+
+Within an item, the reader recovers identity from `id`, `name`, or `model`.
+Bare-list payloads and `key`/`slug`-only items are not supported. It preserves
+the raw item on the in-memory record, while `to_dict()` includes it only when
+the caller explicitly requests `include_raw=True`. Capability remains unknown.
+
+## Disabled Capability Paths
+
+The generic reader does not inspect capability-looking fields, including:
+
+- `type`, `model_type`, `task`, and `pipeline_tag`;
+- top-level or nested modality fields;
+- capability booleans/maps/lists;
+- `supported_parameters`;
+- context, input, output, and model-length fields.
+
+Names, descriptions, ownership, pricing, and serialized text also never
+promote capability through this reader.
+
+## Forward Compatibility
+
+An explicitly configured but unknown provider ID is preserved when the generic
+reader is selected. That allows endpoint-scoped stable IDs to keep working
+while every family, modality, capability, limit, and control remains unknown.
+Non-object entries are skipped; null or malformed roots return no records.
+
+Provider-specific headers, request extensions, and reasoning channels must be
+selected by explicit provider/endpoint adapters. They never leak through this
+fallback.
+
+Compatible tool-call syntax is likewise a runtime concern rather than catalog capability. Current parsers recover selected Hermes/Qwen JSON bodies nested inside `tool_call` wrappers and require the full Qwen bare end delimiter; GPT-OSS compatibility can alias names that collide with its built-in tools and reverse that alias before local dispatch. None of those repairs grants execution authority or proves generic tool support.
+
+## Current Gaps
+
+- Compatible providers differ on path prefixes, null handling, tools,
+  streaming usage, and strict extra-field rejection.
+- Bare-list and `key`/`slug`-only inventories need explicit normalization if a
+  runtime consumer later requires them.
+- Safe request shaping still requires explicit endpoint/provider
+  configuration even when identity normalization succeeds.

specs/model-providers/openai.md

@@ -0,0 +1,34 @@
+# OpenAI Provider Shape
+
+Last updated: dev@e71f8ce | 2026-08-25
+
+## Scope
+
+Canonical provider ID `openai`; API dialects OpenAI Chat Completions and
+Responses; catalog reader `src/model_capability_readers/openai.py`.
+
+## Catalog Shape
+
+`GET /v1/models` returns `object: list` with `data[]` model cards containing
+`id`, `object`, `created`, and `owned_by`. This is identity and availability
+metadata only. It does not claim vision, tools, reasoning, modality, task, or
+context length. The record remains unknown and keeps the raw fields.
+
+## Request And Response Shape
+
+Chat uses `messages`, `tools[].function`, `tool_choice`, and
+`choices[].message|delta`; Responses uses `input`, flattened tools, output
+items, and typed stream events. OpenAI may support a parameter at the platform
+level while individual models differ. A later model registry or probe must
+scope that fact before it becomes canonical model capability.
+
+## Fallback And Safety
+
+An explicit endpoint kind selects this provider. Automatic reader detection accepts exact `openai.com` or a dot-delimited subdomain after normalizing case/trailing dots; it is a normalization hint rather than a trust boundary. Do not parse model IDs or ownership labels. If a proxy returns richer fields while explicitly configured as OpenAI, the reader preserves them as raw evidence but keeps capability unknown.
+
+## Current Gaps
+
+- OpenAI's Models API does not publish the per-model capability shape needed
+  for automatic canonical classification.
+- Runtime model-specific sampling/reasoning behavior still needs a maintained
+  structured registry or endpoint probes.

specs/model-providers/opencode.md

@@ -0,0 +1,21 @@
+# OpenCode Provider Shape
+
+Last updated: dev@2e2bb52 | 2026-08-16
+
+## Scope
+
+Canonical provider identity `opencode` with Zen/Go endpoint variants; OpenAI-compatible transport and webhook presets in `src/llm_core.py` and canonical `routes/webhook/webhook_routes.py`, with the top-level route module retained as a compatibility shim.
+
+## Shape
+
+Keep Zen and Go path identity in endpoint metadata even though the canonical
+provider family is OpenCode. Model discovery uses general identity-only
+fallback. Path/version, account policy, and model selection can differ between
+variants; do not flatten them into OpenAI.
+
+## Fallback And Current Gaps
+
+Exact `*.opencode.ai` plus configured `/zen` or `/zen/go` selects this family.
+No provider-specific rich capability catalog is mapped, and runtime still has
+separate variant labels that should eventually become structured endpoint
+metadata.

specs/model-providers/openrouter.md

@@ -0,0 +1,41 @@
+# OpenRouter Provider Shape
+
+Last updated: dev@e71f8ce | 2026-08-25
+
+## Scope
+
+Canonical provider ID `openrouter`; OpenAI-compatible chat dialect; rich reader
+`src/model_capability_readers/openrouter.py`.
+
+## Catalog Shape
+
+`GET /api/v1/models` returns `data[]`. Canonical fields are:
+
+- `id` (falling back to `name`) and display `name`;
+- `architecture.input_modalities`, `architecture.output_modalities`, and
+  compatibility `architecture.modality`;
+- `context_length` and `top_provider.max_completion_tokens`;
+- `supported_parameters`, `default_parameters`, `supported_voices`, and
+  `per_request_limits`.
+
+Modalities determine family and vision/file/audio/image/video behavior.
+Recognized supported parameters claim tools, JSON/structured output,
+reasoning, and web search. Sampling/default parameters become controls, not
+capabilities. Descriptions, pricing, author slugs, and tokenizer names do not.
+
+## Provider Versus Routed Endpoint
+
+OpenRouter normalizes requests while routing a model to one of several
+underlying providers. The catalog model record is OpenRouter-scoped. Do not
+copy a direct-provider quirk to OpenRouter unless its normalized API and exact
+model/endpoint evidence require it. `top_provider` limits describe the current
+route class, not a permanent global model limit.
+
+## Fallback And Safety
+
+The reader receives OpenRouter through explicit selection or an exact/label-bounded `openrouter.ai` hostname hint. Future fields remain raw. If modalities are absent, it falls back to an identity-only OpenRouter record and does not parse the model slug; supported-parameter controls are not retained on that fallback path.
+
+## Current Gaps
+
+- Per-upstream endpoint differences can still invalidate an aggregate claim.
+- Catalog values change frequently and need freshness/expiry when persisted.

specs/model-providers/perplexity.md

@@ -0,0 +1,20 @@
+# Perplexity Provider Shape
+
+Last updated: dev@28d27ee | 2026-07-17
+
+## Scope
+
+Canonical provider ID `perplexity`; OpenAI-compatible cloud endpoint recognized
+by current UI/provider host maps and agent cloud-host safeguards (#3015).
+
+## Shape
+
+Use general identity-only inventory mapping. Perplexity products may perform
+search, but `web_search` becomes a canonical model capability only when an
+exact model card, maintained registry, or probe reports it. Provider identity
+alone and product descriptions are insufficient.
+
+## Fallback And Current Gaps
+
+Exact `*.perplexity.ai` preserves provider identity. No rich per-model catalog
+or search-control mapping is currently consumed.

specs/model-providers/sglang.md

@@ -0,0 +1,47 @@
+# SGLang Provider Shape
+
+Last updated: dev@e57f60b | 2026-07-20
+
+## Scope
+
+Canonical provider ID `sglang`; OpenAI Chat/Responses plus native generation;
+Cookbook launch behavior in `routes/cookbook_routes.py` and serving UI modules.
+There is no dedicated SGLang canonical reader on current `dev`.
+
+## Metadata Shapes
+
+Preferred native `GET /model_info` (legacy `/get_model_info`) returns:
+
+- `model_path` and `tokenizer_path`;
+- `is_generation`;
+- `has_image_understanding` and `has_audio_understanding`;
+- `model_type`, `architectures`, `weight_version`;
+- `preferred_sampling_params`.
+
+These are provider observations for a future dedicated reader. Current generic
+normalization does not map `is_generation`, modality booleans, sampling keys,
+or `max_model_len`.
+
+`GET /v1/models` returns served IDs with `owned_by: sglang`, `root`, and
+`max_model_len`; it supplies identity/context but not parser capability.
+
+## Runtime Capability
+
+Tools and reasoning depend on explicit `--tool-call-parser` and
+`--reasoning-parser`; multimodality and context can also be launch-configured.
+Cookbook recipes for Qwen, DeepSeek, GLM, Kimi, MiniMax, StepFun, and other
+families are deployment observations, not universal model-name rules. Persist
+the selected parser/config as endpoint evidence before canonical promotion.
+
+## Fallback And Safety
+
+Current reader detection identifies port 30000 as SGLang, or accepts an
+explicit endpoint kind, then dispatches to the generic identity-only reader.
+It does not infer SGLang from `/model_info` payload shape. Avoid normal
+discovery through the broad admin `/server_info` dump.
+
+## Current Gaps
+
+- Endpoint records do not yet store parser/task configuration canonically.
+- Non-generation task classification needs explicit serving metadata.
+- No dedicated reader maps SGLang metadata today.

specs/model-providers/siliconflow.md

@@ -0,0 +1,21 @@
+# SiliconFlow Provider Shape
+
+Last updated: dev@28d27ee | 2026-07-17
+
+## Scope
+
+Canonical provider ID `siliconflow`; global/CN OpenAI-compatible provider
+proposed in #5562.
+
+## Shape
+
+Use the general `/v1/models` identity-only inventory reader for both regional
+surfaces. Region/base URL and API key remain endpoint identity. A regional
+provider-native schema is required before any item fields are promoted; model
+tokens in returned IDs or PR examples are never capability evidence.
+
+## Fallback And Current Gaps
+
+Exact SiliconFlow hosts or explicit kind preserve provider identity. The open
+provider work has no confirmed rich capability card; regional path/host details
+and current payload fixtures need revalidation before runtime integration.

specs/model-providers/together.md

@@ -0,0 +1,27 @@
+# Together AI Provider Shape
+
+Last updated: dev@e57f60b | 2026-07-20
+
+## Scope
+
+Canonical provider ID `together`; OpenAI-compatible cloud transport; curated
+models and discovery compatibility in `routes/model_routes.py`.
+
+## Shape And Observations
+
+Together has returned both standard `data[]` and bare model-card lists. The
+current generic reader accepts the standard envelope when the caller supplies
+the Together vendor, but it does not accept a bare root list. It keeps
+identity/provider scope and promotes no capability fields. Task, modality,
+parameter, and limit data needs a dedicated Together reader before it becomes
+canonical; model names and the curated picker list are not capability evidence.
+
+Together can serve many upstream families. Direct-provider quirks do not
+automatically apply because Together may normalize requests and responses.
+
+## Fallback And Current Gaps
+
+Both `*.together.xyz` and `*.together.ai` identify the provider. Malformed/null
+lists fail soft. A provider-specific rich capability schema has not been
+confirmed, so general fallback remains intentional. Bare-list catalogs require
+route-specific preprocessing or a future reader update.

specs/model-providers/venice.md

@@ -0,0 +1,19 @@
+# Venice Provider Shape
+
+Last updated: dev@28d27ee | 2026-07-17
+
+## Scope
+
+Canonical provider ID `venice`; paid OpenAI-compatible cloud API represented in
+webhook presets and cloud/self-hosted classification tests.
+
+## Shape
+
+Use general identity-only inventory mapping. Treat `api.venice.ai` as a remote API
+for routing/security, while keeping model capability per returned model. Do not
+infer privacy, tools, reasoning, or context from provider marketing or names.
+
+## Fallback And Current Gaps
+
+Exact `*.venice.ai` preserves provider identity. No verified rich model-card
+schema is currently mapped.

specs/model-providers/vllm.md

@@ -0,0 +1,44 @@
+# vLLM Provider Shape
+
+Last updated: dev@e57f60b | 2026-07-20
+
+## Scope
+
+Canonical placeholder provider ID `vllm`; OpenAI Chat and Responses serving;
+generic identity-only inventory normalization. There is no dedicated vLLM
+reader or model-card detector on current `dev`.
+
+## Catalog Shape
+
+Current `GET /v1/models` returns `object: list`, `data[]` model cards with
+`id`, `object`, `owned_by: vllm`, `root`, `parent`, `max_model_len`, and
+`permission[]`. The generic reader retains only identity/raw data and does not
+inspect `owned_by`, `root`, `parent`, `max_model_len`, or `permission`. The card
+does not prove chat template, tools,
+reasoning parser, vision assets, embeddings, transcription, or rerank.
+
+LoRA cards can use a different `id`, root path, and parent. Keep each served ID
+endpoint scoped and do not merge it globally with the base checkpoint.
+
+## Runtime Capability
+
+vLLM's supported API surface is broad, but actual behavior depends on the
+loaded model task, chat template, multimodal assets, tool-call parser,
+reasoning parser, structured-output configuration, and launch flags. Current
+Odysseus reasoning regressions cover structured `reasoning`, legacy
+`reasoning_content`, and compatible fields (#602). These response channels are
+transport evidence, not a claim that every vLLM model reasons.
+
+## Fallback And Safety
+
+Current reader detection identifies port 8000 as vLLM, or accepts an explicit
+endpoint kind, then dispatches to the generic identity-only reader. It does not
+infer vLLM from the model-card payload. Do not consume `/server_info`
+environment/config dumps for normal discovery because they can be large and
+operationally sensitive.
+
+## Current Gaps
+
+- A small safe native capability endpoint is not part of the canonical probe.
+- Deployment parser/template flags are not persisted with endpoint capability.
+- No dedicated reader maps vLLM model-card fields today.

specs/model-providers/xai.md

@@ -0,0 +1,21 @@
+# xAI Provider Shape
+
+Last updated: dev@28d27ee | 2026-07-17
+
+## Scope
+
+Canonical provider ID `xai`; OpenAI-compatible xAI cloud transport; provider
+labels/curation in `src/llm_core.py` and `routes/model_routes.py`.
+
+## Shape
+
+Model discovery uses general identity-only inventory. Reasoning effort, tools,
+image input, or other Grok behavior must be
+scoped per returned model/registry/probe. The provider's broad API feature set
+does not grant every listed model every capability.
+
+## Fallback And Current Gaps
+
+Exact `*.x.ai` selects xAI. Preserve provider identity through OpenAI-compatible
+fallback and reject lookalikes. A current rich model catalog schema and
+structured version registry are not yet mapped.

specs/model-providers/zai.md

@@ -0,0 +1,23 @@
+# Z.AI Provider Shape
+
+Last updated: dev@28d27ee | 2026-07-17
+
+## Scope
+
+Canonical provider ID `zai`; Z.AI/GLM OpenAI-compatible endpoints including
+coding-plan variants; curated discovery in `routes/model_routes.py` and prior
+vision/reasoning fixes such as #664.
+
+## Shape And Observations
+
+Use general identity-only inventory mapping. Some working coding-plan models may be
+absent from `/models`, so pinned/curated IDs are availability compatibility,
+not capability truth. GLM reasoning controls have appeared as structured
+objects or serving-template kwargs depending on direct cloud versus local
+engine (#3031). Keep those scopes separate.
+
+## Fallback And Current Gaps
+
+Exact `*.z.ai` or explicit endpoint kind preserves Z.AI identity. Never infer
+vision/reasoning/tool support from `glm` in a name. A rich official model-card
+reader and direct-versus-coding-plan schema split are still missing.