Squash Odysseus development history

specs/model-quirks.md

@@ -0,0 +1,90 @@
+# Model Behavior Observations
+
+Last updated: dev@2e2bb52 | 2026-08-16
+
+## Scope
+
+This file records model- or provider+model-specific behavior observed in
+Odysseus code, tests, Issues, PRs, commits, and provider documentation. It is a
+compact evidence map, not a runtime matcher. General canonical rules belong in
+[model-capability-canonical.md](model-capability-canonical.md); provider-wide
+transport belongs in [the provider map](model-providers/_readme.md).
+
+The canonical capability layer intentionally has no
+`src/model_behavior_quirks.py`.
+Adding a registry before runtime call sites carry structured provider, model,
+version, and dialect identity would create another model-name matching layer.
+
+## General Observation Template
+
+Record only the fields supported by the evidence:
+
+- provider and endpoint/dialect scope;
+- exact provider-returned model ID or family;
+- structured model/provider version when available;
+- capability or request/response behavior observed;
+- exact native request field/value and response field when relevant;
+- source, confidence, status, and reproduction date;
+- whether the behavior is already implemented in runtime code.
+
+If exact structured identity is unavailable, keep the observation here and in
+its current tested runtime location. Do not promote it through substring,
+regex, prose, or serialized-prompt parsing in the canonical layer.
+
+## Model-Specific Observation Map
+
+| Observation | Scope | Behavior | Evidence/status |
+| --- | --- | --- | --- |
+| Moonshot Kimi K2.5/K2.6 fixed temperature | official Moonshot, K2.5/K2.6, OpenAI Chat | omit `temperature`; thinking mode owns its fixed value | #3960, `f5d3e509`; implemented in current runtime |
+| Moonshot reasoning tool history | same provider/models/dialect | preserve assistant `reasoning_content` across tool continuation | #3118, `2e6fff22`; implemented |
+| Claude Opus 4.7+ sampling omission | Anthropic Messages, Opus 4.7+ and major-only later IDs such as `claude-opus-5` | omit `temperature`, `top_p`, and `top_k` where the runtime rule applies | #3117, `4f48cfa9`, #5761; implemented through current runtime identity logic |
+| Mistral structured reasoning | reasoning-capable Mistral model through native/compatible response shape | use graded effort where accepted; keep typed thinking separate from text | #4698, `bd9149f7`, provider docs; partly implemented |
+| Ollama native reasoning control | selected reasoning model/deployment | native `think`; reasoning in `message.thinking`/`thinking` | #3031 and provider docs; deployment scoped |
+| Ollama native `gpt-oss` reasoning level | `gpt-oss` served through Ollama native | `think` accepts low/medium/high and does not represent off | provider docs; deployment scoped |
+| Ollama compatibility disable observation | Ollama 0.20.6+, observed Qwen3.5 compatibility path | `reasoning_effort: none` was reported to disable reasoning | #5503; unmerged/low confidence until reproduced |
+
+Issue and commit references are evidence identifiers, not runtime dependencies.
+Open or unmerged observations remain provisional until reproduced or supported
+by current provider documentation.
+
+## Other Model-Level Observations
+
+- Kimi K2.5/K2.6 multimodality differs from older K2 variants (#2522). Promote
+  only from an exact provider card or scoped registry, never the `kimi` token.
+- Google product names suggest media tasks to humans, but its Models resource
+  does not publish complete modalities. Keep those modalities unknown without
+  stronger model-scoped evidence.
+- Ollama `/api/tags` names can omit vision markers (#3743, #4487). Use selected
+  model `/api/show.capabilities`, not its name.
+- Local reasoning controls vary by serving template/config: message/system
+  directives, `chat_template_kwargs.enable_thinking`, native booleans,
+  structured objects, budgets, and effort levels were all observed (#3031).
+  These are endpoint/deployment facts, not universal checkpoint properties.
+- DeepSeek, vLLM/NIM, Mistral, Moonshot, Ollama, and harmony-style servers use
+  different structured reasoning channels. Provider/dialect evidence chooses
+  the channel; generic response-text scanning is not capability discovery.
+- Current runtime recognizes DeepSeek V4 identifiers in its thinking-model patterns; that is request/response handling evidence, not proof that every V4-named endpoint exposes identical capabilities.
+- GPT-OSS deployments can reserve native tool names. Runtime aliases colliding Odysseus tool names at the provider boundary and reverses the alias before local execution; this is dialect compatibility, not extra tool authorization.
+- Cohere native and compatibility transports expose different thinking
+  controls/channels. The Cohere model list does not itself prove reasoning.
+- MiniMax M2.7 exposes different thinking channels through Anthropic and
+  OpenAI-compatible transports. Its current model list is identity-only.
+- Gemma/Phi/Qwen vision behavior has changed across serving engines (#1430,
+  #1704, #1478). Native engine metadata or a verified endpoint probe outranks
+  a model-family name list.
+
+## Promotion Gate
+
+Before an observation becomes canonical runtime behavior, a consumer must
+already have the necessary structured identity and tests must cover both its
+positive scope and a neighboring negative scope. Request control and response
+visibility remain separate: hiding reasoning text is not the same as disabling
+reasoning at the provider (#2905).
+
+## Current Gaps
+
+- Runtime still contains model-name helpers for several implemented behaviors;
+  this spec records them but the canonical catalog does not duplicate them.
+- Hosted aliases and provider behavior can change; there is no durable
+  observation expiry/revalidation layer yet.
+- Detail/probe-only model facts cannot safely be populated from list discovery.