# Model settings

Which model an agent uses and how hard it thinks. Models from every vendor are listed; one whose zero-retention terms haven't been attested is shown locked with that reason, never hidden. The fallback must be attested too, and can't be the primary. When the viewer can't change the settings at all, every control is locked and says why.

- Registry name: `model-settings` (`@candor/model-settings`)
- Tier: Pro. Installing it needs a Pro, Premium or Team licence key: the person runs `npx candor-ui key <key>` themselves; never ask for the key in chat or write it to a file.
- Docs: https://candor.themethodic.com/docs/model-settings

## Install

```bash
npx candor-ui add model-settings
```

Run `npx candor-ui@latest init` once first (https://candor.themethodic.com/get-started.md). Without the CLI: `npx shadcn@latest add @candor/model-settings`.
It brings in: know, locale, locked, select, utils.
npm packages: lucide-react@^1.67.0.

## Example

```tsx
"use client"

import * as React from "react"
import { ModelSettings } from "@/components/model-settings"
import type { ModelOption, ModelSettingsValue } from "@/lib/know"

const models: ModelOption[] = [
  { id: "opus", vendor: "Anthropic", name: "Claude Opus 5.5", note: "Design, review and hard builds", cost: 4, zdr: "attested" },
  { id: "sonnet", vendor: "Anthropic", name: "Claude Sonnet 5.5", note: "Most delivery work", cost: 2, zdr: "attested" },
  { id: "gemini", vendor: "Google", name: "Gemini 3.1 Pro", note: "Long documents", cost: 3, zdr: "attested" },
  { id: "gpt", vendor: "OpenAI", name: "GPT-5.5", cost: 3, zdr: "not-attested" },
]

export default function Example() {
  const [value, setValue] = React.useState<ModelSettingsValue>({ model: "sonnet", reasoning: "medium", stepLimit: 30, fallback: "gemini" })
  return <ModelSettings className="max-w-2xl" value={value} onChange={setValue} models={models} />
}
```

## <ModelSettings>

Props:

- `value: ModelSettingsValue`: The settings as they are now.
- `onChange: (value: ModelSettingsValue) => void`: Called with the whole new value on every change.
- `models: ModelOption[]`: Every model the app offers, from any vendor.
- `locked?: string | undefined`: Why the viewer can't change these settings, e.g. "Only admins can change the model." Shown, and every control is locked.
- `className?: string | undefined`

## Strings (`modelSettings`)

The fixed words, English by default. Override any of them under `modelSettings` in `<LocaleProvider strings={{ modelSettings: { … } }}>`; the table is exported as `modelSettingsStrings`.

- `model`: Model
- `notAvailable`: Not available until {vendor}’s zero-retention terms are attested.
- `notAttested`: Zero-retention terms not attested
- `reasoning`: Reasoning
- `reasoningEffort`: Reasoning effort
- `low`: Low
- `lowDetail`: Quick lookups
- `medium`: Medium
- `mediumDetail`: Most work
- `high`: High
- `highDetail`: Design and review
- `max`: Max
- `maxDetail`: Hard problems; slow
- `stepLimit`: Step limit
- `steps`: { one: "{count} step", other: "{count} steps" }
- `stepLimitHelp`: After this many tool calls the agent stops and asks you before going on.
- `fallback`: Fallback
- `fallbackModel`: Fallback model
- `noFallback`: No fallback: wait and retry
- `fallbackHelp`: Used only while the primary is unavailable. Listed models all have attested zero-retention terms.

## Rules for using Candor UI

- Components take plain typed data. Never pass model output as HTML or render it as a link; messages are typed blocks.
- A control that can't be used says why: wrap it in `<Locked reason="…">`, don't just disable it.
- Don't show a value you don't have: leave it out (it renders as —) rather than guess. An estimate is labelled as one.
- Nothing is pre-selected in a decision a person makes, and the agent is named from your app's data, never from model output.
- Your app's words go in `LocaleProvider` (fixed strings) and `TermsProvider` (nouns); entity kinds and agent roles in `EntityKindsProvider` and `AgentRolesProvider`.