ai-for-dummies/docs/references/model-routing.md

# Model routing and reasoning controls

Verified against first-party documentation on 2026-09-02. Model catalogs and
aliases change; pin production model IDs and re-check the linked compatibility
tables before rollout.

## Two independent routing knobs

1. **Model tier** chooses the capability, latency, and cost envelope.
2. **Effort / thinking control** changes how much reasoning work a supported
   model performs for one request.

Do not assume that every effort value works with every model or product.
Unsupported values may fail, be ignored, or be mapped to another level depending
on the client.

## OpenAI

The current GPT-5.6 family exposes the **Sol**, **Terra**, and **Luna** model
tiers. Its documented `reasoning.effort` values are `none`, `low`, `medium`,
`high`, `xhigh`, and `max`. Availability remains model-specific, so select from
the levels shown for the chosen model rather than treating the full list as
universal.
[OpenAI: latest model guide](https://developers.openai.com/api/docs/guides/latest-model)

Use a lower-cost tier and low effort for bounded, mechanical work; raise the
model tier or effort for planning, architecture, difficult debugging, and final
review. This is routing guidance, not an API guarantee.

## Anthropic Claude

### Model tier

Claude Code provides the aliases `opus`, `sonnet`, and `haiku`: Opus is intended
for complex reasoning, Sonnet for everyday coding, and Haiku for simple, fast
work. Aliases resolve to provider-dependent recommended versions and can change
over time; use a full model ID when reproducibility matters. Claude Code also
documents `opusplan`, which uses Opus in plan mode and Sonnet for execution.
[Claude Code: model configuration](https://docs.anthropic.com/en/docs/claude-code/model-config)

Copy-ready Claude Code switches:

```text
/model opus
/model sonnet
/model haiku
```

At startup, the equivalent documented form is:

```bash
claude --model opus
```

### Effort

The Claude API parameter is `output_config.effort`. The documented levels are
`low`, `medium`, `high`, `xhigh`, and `max`; `high` is the API default. `xhigh`
and `max` have narrower model support, and Haiku 4.5 does not support effort.
Effort affects the whole response—including thinking and tool calls—and is a
behavioral signal, not a strict token budget.
[Anthropic: effort](https://docs.anthropic.com/en/docs/build-with-claude/effort)

Documented Python example:

```python
import anthropic

client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    output_config={"effort": "medium"},
    messages=[{"role": "user", "content": "Review this implementation plan."}],
)
```

Claude Code exposes `/effort`; its available choices depend on the active model.
Current Claude Code documentation lists `low`, `medium`, `high`, `xhigh`, and
`max` for supported Opus versions, while some Opus/Sonnet versions omit `xhigh`.
When a selected level is unsupported, Claude Code can fall back to the highest
supported level at or below it.
[Claude Code: effort compatibility](https://docs.anthropic.com/en/docs/claude-code/model-config#adjust-effort-level)

## Google Gemini

### Model tier

Gemini uses model families rather than interchangeable aliases: **Pro** targets
the most complex reasoning, **Flash** balances capability and throughput, and
**Flash-Lite** prioritizes latency, volume, and cost. Select an explicit
endpoint such as `gemini-3.7-flash`; Google recommends stable model names for
most production applications because `latest` aliases can be hot-swapped.
[Gemini API: models](https://ai.google.dev/gemini-api/docs/models)

### Thinking level

For Gemini 3 models, the control is `thinkingLevel` in SDKs (`thinking_level` in
Python). Across the family the documented values are `minimal`, `low`, `medium`,
and `high`, but support and defaults vary by model. For example, Gemini 3.7
Flash supports `low`, `medium`, and `high` and defaults to `medium`; Gemini 3.1
Pro supports `low`, `medium`, and `high` and defaults to `high`. `minimal` is
unavailable on several models and does not guarantee that reasoning is
completely off where supported. Gemini 2.5 uses `thinkingBudget`, not
`thinkingLevel`.
[Gemini API: thinking](https://ai.google.dev/gemini-api/docs/thinking)

Documented JavaScript pattern:

```javascript
import { GoogleGenAI, ThinkingLevel } from '@google/genai';

const ai = new GoogleGenAI({});
const response = await ai.models.generateContent({
  model: 'gemini-3.7-flash',
  contents: 'Review this implementation plan.',
  config: {
    thinkingConfig: {
      thinkingLevel: ThinkingLevel.LOW,
    },
  },
});

console.log(response.text);
```

## Practical routing baseline

| Work                                                | Model tier                | Effort / thinking                      |
| --------------------------------------------------- | ------------------------- | -------------------------------------- |
| Formatting, lookup, narrow edit                     | Haiku / Flash-Lite / Luna | Low or minimal where supported         |
| Normal implementation, tests, review                | Sonnet / Flash / Terra    | Medium                                 |
| Architecture, orchestration, hard debugging         | Opus / Pro / Sol          | High                                   |
| Frontier or long-horizon work with measured benefit | Strongest supported tier  | `xhigh` or `max` only where documented |

Treat this table as a starting hypothesis. Evaluate quality, latency, and cost
on representative tasks, then route to the cheapest combination that still
passes the required checks.