# Model Selection

## Objective

Let each AI task run on the model that suits its quality, speed, and cost needs.

A per-task model choice, drawn from the models the app already has configured, with capability filtering and safe defaults.

## Before You Begin

This feature is being added to an application that already exists and already
works. Do not scaffold a new project, and do not assume a blank slate.

Inspect the codebase first and establish:

- The existing application structure and where code of this kind already lives.
- The framework and version in use.
- The existing design system — colours, spacing, typography, and component conventions.
- Existing UI components you can reuse instead of writing new ones.
- The existing database structure, if this feature needs to persist anything.
- The existing authentication and authorization system, if this feature is user-scoped.
- Dependencies already installed, so you don't add a library that duplicates one.
- The existing test setup and conventions.

Only start writing code once you understand the above. If the application
already implements part of this feature, extend it rather than replacing it.

## Implementation Instructions

1. Enumerate the models the app already has access to and record what each one can actually do: context capacity, whether it can return the structured output the task requires, whether it supports the tools the task calls, and its relative cost and speed.
2. Offer only the models that satisfy the task's requirements. A task that needs structured output must not list a model that cannot reliably produce it, because the failure appears later as malformed responses rather than as an unavailable option.
3. Store the choice against the specific task, not as one global setting. A single default forces a summarisation task and a classification task onto the same tier when they have opposite needs.
4. Present the choice in plain terms — faster, higher quality, lower cost, and where the data is processed — rather than exposing provider naming and parameter detail to users who did not ask for it. Advanced settings can stay behind a disclosure for the people who need them.
5. Do not let a removed or deprecated model become a silent failure. Fall back to a compatible configured model, record that the substitution happened, and surface it to an administrator.

## UI and UX Requirements

Match the application's existing design system exactly. Reuse its components,
spacing, and typography. This feature should look like it was always there.

## Responsive Requirements

Works on mobile, tablet, and desktop. Touch targets are large enough to hit on a
phone, and nothing overflows horizontally at 320px.

## Accessibility Requirements

- Fully keyboard navigable.
- Correct semantic elements and ARIA roles.
- Visible focus states.
- Meets WCAG AA contrast.
- Dynamic changes are announced to screen readers.
- Respects prefers-reduced-motion.

## Edge Cases

- The list must be filtered by what the task actually needs, so a model that cannot honour the required output shape or call the required tools is never offered for that task.
- Provider-specific parameters and naming should stay hidden from ordinary users behind a plain description of speed, quality, and cost, while remaining reachable for administrators.
- Choices belong to individual tasks. One global default applied everywhere is either too expensive for the cheap work or too weak for the hard work.
- A model that is removed, deprecated, or newly unavailable must resolve to a compatible substitute with a recorded, visible notice, rather than throwing an error at the next run.
- Where models differ materially in cost or in where data is processed, state that at the point of selection. Discovering it on an invoice or in a compliance review is too late.
- Changing the model for a task must not silently change results already produced. Existing outputs keep their original attribution.
- A selection that would exceed a configured spend ceiling must be blocked or flagged at selection time, not at run time.
- If no configured model satisfies the task, say so explicitly rather than defaulting to one that will fail partway through.

## Testing

Exercise the feature end to end in the running application. Cover every edge case
above, then run the existing test suite and confirm nothing regressed.

## Acceptance Criteria

- [ ] Each AI task stores its own model choice rather than inheriting a single global default.
- [ ] Only models capable of the task's output shape and tool requirements are offered for it.
- [ ] Cost and data-processing differences are stated at the point of selection.
- [ ] A deprecated or removed model resolves to a compatible substitute, with the substitution recorded and surfaced.
- [ ] Provider-specific detail is hidden from ordinary users and reachable by administrators.
- [ ] Changing a task's model leaves previously produced outputs and their attribution untouched.
- [ ] The feature matches the existing design system.
- [ ] No existing functionality is broken.

## Adaptation Rules

- Match the existing design system. Do not introduce a new colour palette,
  spacing scale, or component library.
- Reuse existing components and utilities wherever they fit.
- Follow the naming, file layout, and code style already present.
- Do not upgrade, replace, or remove existing dependencies to make this
  feature fit. Adapt the feature to the app, not the app to the feature.
- Do not break existing functionality. If a change is genuinely required in
  existing code, make the smallest one that works and say so.
- If something in these instructions conflicts with how the application is
  built, follow the application and explain the deviation.

## Final Verification

Before you report the work as done:

1. Re-read the acceptance criteria above and check each one against what you
   actually built.
2. Run the application and exercise the feature end to end.
3. Run the existing test suite and confirm you have broken nothing.
4. Check the feature on mobile, tablet, and desktop widths.
5. Check keyboard navigation and focus handling.
6. Summarize what changed: files added, files modified, and anything you
   deliberately did differently because of how this application is built.

If any acceptance criterion is unmet, fix it before reporting completion.