Squash Odysseus development history

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.