core/docs/ICD/models.md

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] }:

{
  "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:

{
  "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.

---