| 1 | # Model Configuration Plugin DOX |
| 2 | |
| 3 | ## Purpose |
| 4 | |
| 5 | - Own global LLM preset definitions, scoped preset selection, API-key checks, chat overrides, migration, and model settings UI. |
| 6 | |
| 7 | ## Ownership |
| 8 | |
| 9 | - `helpers/model_config.py` owns config resolution, presets, overrides, and runtime model object construction. |
| 10 | - `api/` owns model config, override, preset, search, and API-key endpoints. |
| 11 | - `webui/` owns model settings, summaries, switcher, and API-key UI. |
| 12 | - `extensions/python/startup_migration/` owns conversion from legacy full configs and project presets, followed by first-launch preset initialization. |
| 13 | - `default_config.yaml`, `mode_presets_fallback.yaml`, `provider_metadata.yaml`, `hooks.py`, and `plugin.yaml` own plugin defaults, offline presets, metadata, hooks, and manifest. |
| 14 | |
| 15 | ## Local Contracts |
| 16 | |
| 17 | - `Default` is the first global preset and cannot be deleted or renamed. It owns the complete main, utility, and embedding baseline; its Vision Model slot is optional. |
| 18 | - Preset definitions are global. Global, project, agent-profile, and project/profile plugin configs persist only `model_preset`; chats may persist a preset reference as their explicit override. |
| 19 | - Preserve scoped plugin resolution order and fall back invalid or missing scope/chat references to `Default`. |
| 20 | - Project Settings `llm` payloads are owned here through the generic `helpers.projects` project extension-data hooks; keep project helper code agnostic to `_model_config` paths, presets, and inheritance rules. |
| 21 | - Keep provider metadata and API-key checks safe around secrets. |
| 22 | - Check API-key readiness only for the effective model configuration; unused global presets must not produce Welcome-screen warnings. |
| 23 | - Coordinate OAuth-backed providers with `_oauth` instead of hardcoding provider-specific auth here. |
| 24 | - `model_config_get` exposes `model_configured` as a derived chat-model readiness flag from provider, model name, and API-key availability. |
| 25 | - Non-default presets may inherit omitted main, utility, or embedding slots and durable tuning from `Default`, but must replace or clear per-slot `kwargs` so provider-specific extra params never leak across model providers. |
| 26 | - The optional `vision` slot is strictly per preset and never inherited from `Default`; an empty slot disables the separate Vision Model for that preset. |
| 27 | - Main native vision wins by default. A configured Vision Model handles `vision_load` when Main lacks vision, or when that preset explicitly enables `override_main`. |
| 28 | - Keep the optional Vision provider/model selector inside the Main Model card and flush with Main's field alignment, without a nested left inset. Show it only while Main vision is disabled or `override_main` is enabled; do not render a standalone Vision Model card. |
| 29 | - Keep Vision timeout and maximum-output-token controls, plus the Agent Editor prompt-customization note, inside the visible Vision sidecar's Advanced Settings only. The Vision call limits belong to the preset/model builder, not to `vision_load` call-site constants. |
| 30 | - Show `Use separate Vision Model` immediately below `Supports Vision` while Main vision is enabled, not inside Advanced Settings; describe the disabled state as using Main's native vision. |
| 31 | - In model overviews, render the effective Vision Model as a text-only `Vision override / Provider / Model` child aligned with Main's provider column, not as an icon-bearing peer row. |
| 32 | - Changing a model provider in the settings UI must clear `api_base` and `kwargs` because both may be provider-specific. |
| 33 | - Repair provider-specific model-config aliases at the model-config read/build boundary; keep provider-specific repairs out of provider-agnostic core wrappers such as `models.py`. |
| 34 | - `modelConfig.createPresetEditor()` owns local preset drafts, row actions, and stable UI-only row keys so deletion or renaming cannot rebind nested model fields. |
| 35 | - The preset editor maps each model provider's API-key field to the shared API-key store; saving the editor persists dirty keys separately and never writes secrets into preset YAML. |
| 36 | - The compact chat selector label combines the effective preset with only the leaf name of its main model; utility and provider text stay out of the closed selector. |
| 37 | - The compact selector strip exposes `model-context-strip-end` after the agent |
| 38 | profile selector so adjacent bundled controls can stay plugin-owned. |
| 39 | - The adjacent agent-profile selector reads the always-enabled Agent Editor list |
| 40 | endpoint directly so the active profile shows its effective title and avatar, |
| 41 | and omits profiles disabled in the chat's current scope plus the exact |
| 42 | `default` utility profile. A chat already using `default` may still show that |
| 43 | current status without adding a selectable or editable row. |
| 44 | - Reload the agent-profile selector catalog when a chat changes project or |
| 45 | active profile so project-only profiles never linger in the visible choices. |
| 46 | - Concurrent agent-profile catalog loads for the same chat share one request; |
| 47 | across chats, only the newest request may replace selector state or finish |
| 48 | its loading lifecycle. |
| 49 | - Preset editor reset actions must remove the user override through the preset API and refresh the open draft from bundled defaults. |
| 50 | - Preset rename, delete, and reset actions must repair scoped config and durable/live chat references; removed definitions fall back to `Default`. |
| 51 | - Migration must preserve existing definitions and distinct scoped model choices, back up replaced user files once, strip inline secrets, and remain idempotent. |
| 52 | - On every startup after migration, short-circuit when `usr/plugins/_model_config/presets.yaml` exists. Only a missing collection may fetch `agent0ai/a0-presets`; parse remote and plugin-local fallback YAML through the same validator, strip secrets before persistence, and persist `mode_presets_fallback.yaml` when download or validation fails. |
| 53 | - Model-name catalogs open below the input from either a field click or the embedded magnifier. |
| 54 | |
| 55 | ## Work Guidance |
| 56 | |
| 57 | - Keep backend model config shape and frontend settings fields synchronized. |
| 58 | |
| 59 | ## Verification |
| 60 | |
| 61 | - Run model-config and onboarding-related tests when model provider, preset, or API-key behavior changes. |
| 62 | |
| 63 | ## Child DOX Index |
| 64 | |
| 65 | No child DOX files. |