Changeset 0.28.0.1 (#173)

docs/ICD/models.md

@@ -0,0 +1,88 @@
+# Models & Preferences
+
+What models are available to the current user and how they control
+visibility.
+
+### Enabled Models
+
+The primary endpoint for populating model selectors:
+
+```
+GET /models/enabled
+```
+
+Returns `{ "models": [UserModel objects] }`:
+
+```json
+{
+  "id": "composite-id",
+  "model_id": "claude-sonnet-4-20250514",
+  "provider_config_id": "uuid",
+  "provider_config_name": "Anthropic",
+  "provider": "anthropic",
+  "display_name": "Claude Sonnet 4",
+  "model_type": "chat|embedding|image",
+  "context_window": 200000,
+  "max_output_tokens": 8192,
+  "supports_vision": true,
+  "supports_tools": true,
+  "supports_thinking": true,
+  "supports_streaming": true,
+  "input_price_per_m": 3.00,
+  "output_price_per_m": 15.00,
+  "provider_status": "healthy|degraded|down|null",
+  "scope": "global|team|personal",
+  "source": "catalog|heuristic",
+  "is_persona": false,
+  "persona_id": "uuid|null",
+  "persona_scope": "global|team|personal|null",
+  "persona_avatar": "url|null",
+  "persona_team_name": "string|null"
+}
+```
+
+The capabilities on each model are resolved through the three-tier
+chain: catalog DB → heuristic inference → admin overrides (see §10.5).
+
+When `is_persona` is `true`, the capability fields (`context_window`,
+`max_output_tokens`, `supports_*`, pricing, `provider_status`) are
+inherited from the persona's underlying model. The frontend renders
+the same capability pills and badges for a persona as for its raw
+model — the persona adds identity, not capability restrictions.
+
+### User Model Preferences
+
+Users can hide models they don't want to see and set per-model
+defaults. Preferences are keyed on the **composite identity**
+`provider_config_id:model_id` — the same model from different
+providers can have independent visibility.
+
+```
+GET  /models/preferences            → { "preferences": [PreferenceEntry objects] }
+PUT  /models/preferences            ← { "model_id": "...", "provider_config_id": "uuid", "hidden": true }
+POST /models/preferences/bulk       ← { "entries": [{ "model_id": "...", "provider_config_id": "uuid", "hidden": true }] }
+```
+
+PreferenceEntry:
+
+```json
+{
+  "model_id": "grok-4.1-fast",
+  "provider_config_id": "uuid",
+  "hidden": true,
+  "preferred_temperature": 0.7,
+  "preferred_max_tokens": 4096,
+  "sort_order": 0
+}
+```
+
+**Identity rule:** `provider_config_id` is required on write. The same
+bare `model_id` from two different provider configs (e.g. global Venice
+vs personal BYOK Venice) are independent preference entries. The
+frontend composite ID format is `{provider_config_id}:{model_id}`.
+
+**Persona preferences:** Personas are not in this table. A persona's
+visibility is controlled by the grant system (§15.3) and the
+`is_active` flag, not by model preferences.
+
+---