Marcos Paulo
97 lines
5.2 KiB
Markdown
97 lines
5.2 KiB
Markdown
# 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.
|