Dials: model-neutral generation settings¶
A raw request option names a vendor parameter: temperature, reasoning_effort, a thinking budget. A model that cannot take it rejects the request (D-12), so a preset whose chain spans vendors has to spell out each entry's options. A dial names an intent instead, such as "focused" or "think hard". It travels with the request and is compiled for each attempt against the model that serves it, so a failover re-targets it instead of failing.
- The dials
- What happens when a model cannot honor a dial
- Setting dials
- Changes during a run
- Seeing what was sent
- Declaring dials in the catalog
- Scenarios
- Known limits
Raw options keep their meaning and their strictness. Dials are additive: nothing is deprecated, and a raw option that sets the same parameter as a dial wins.
The dials¶
| Dial | JSON key | Values | Class | Compiles to |
|---|---|---|---|---|
| Creativity | creativity |
deterministic, focused, balanced, creative |
advisory | temperature, top_p, top_k |
| Reasoning | reasoning |
{"mode": "off" \| "adaptive" \| "on", "depth": "minimal" \| "low" \| "medium" \| "high" \| "max"} |
advisory | a toggle, an effort, a budget or a thinking level |
| Max output | max_output |
tokens | clamp | max_output_tokens |
| Tools | tools |
{"mode": "auto" \| "none" \| "required" \| "named", "name": "..."} |
contractual | tool_choice |
| Parallel | parallel |
true, false |
false is contractual, true advisory |
parallel_tools |
| Reproducible | reproducible |
a seed | contractual | seed |
| Cache | cache |
true, false |
advisory | the prompt cache mode the catalog offering declares |
| Modality | modality |
{"default": action, "per": {"audio": ["transcribe", "omit"]}} |
contractual | a conversion plan, not a vendor parameter; see Modality conversion |
A depth without a mode means on. Reasoning merges whole: a layer that sets it replaces mode and depth together. Stop sequences and penalties have no portable meaning and stay raw-only.
The modality dial never reaches an adapter: the conversion decorator spends it on each attempt and removes it from the request options. A service tier is not a dial. An offering declares its tiers (priority, flex, batch) with their rates in the catalog; interactive calls run on the standard tier, and the batch tier prices batch jobs.
Reasoning outranks creativity. When the effective reasoning rules out sampling controls (the offering's sampling.* constraints, or an API that rejects sampling while the model thinks), creativity is dropped and the conflict recorded. Set reasoning.mode to off to let creativity apply.
A seed is not reproducibility on any vendor. To replay a call exactly, use the response cache (agent/provider/cache).
In Go:
focused := types.CreativityFocused
d := types.Dials{
Creativity: &focused,
Reasoning: &types.ReasoningDial{Depth: types.DepthHigh},
}
What happens when a model cannot honor a dial¶
Each dial has a class, and the class sets the default handling:
| Class | Default | Recorded as |
|---|---|---|
| advisory | the nearest declared value, or nothing when there is none | mapped or dropped |
| clamp | lowered to the model's limit, never raised | mapped |
| contractual | the attempt fails with ErrInvalidModelConfig |
rejected |
A types.DialPolicy changes the handling:
Per: map[types.DialName]types.Handling{...}sets one dial toreject,nearestordrop. Naming a contractual dial here is the only way to loosen it, for example{"reproducible": "drop"}. There is no global lenient switch.Strict: true(types.StrictDials) rejects every dial a model cannot honor exactly, and outranksPer. Evals use it to hold settings constant across models.
In a router, a contractual dial a member cannot honor removes that member from the request, and the next eligible member serves. An advisory dial never removes a member. When no member is eligible, the error names each member's reason.
Setting dials¶
Dials resolve field by field, lowest first:
- Global:
provider.Config.Dials, or the catalog's top-leveldials. - The offering's
dials.defaults. - The preset's
dials, unless the entry says"inherit": "none". - The entry's
dials. The entry'sunsetremoves an inherited dial with"dials.<name>". - The agent:
agent.WithDials. - A sub-agent inherits its parent's dials unless its
OptionssetWithDials. A handoff member with its ownHandoffDef.Dialsuses them instead of the entry agent's. - The conversation:
ConfigPart{Dials: ...}, sticky and saved in the tree. Blocks merge field by field in order. - One request:
RequestOptions.Dials.
Layers 1 to 4 are configured on the adapter (WithDials on each adapter package). Layers 5 to 8 travel with the request as RequestOptions.DialLayers and RequestOptions.Dials. A raw option at any layer that sets the same parameter wins over every dial, is recorded as raw_override, and is validated strictly.
agent.WithDialPolicy, provider.Config.DialPolicy and each adapter's WithDialPolicy set the policy. types.ContextWithDialPolicy overrides it for one call tree, which is how an eval holds dials constant.
Dials compile late, on each attempt, against that attempt's model and request: whether it offers tools or a response schema, and which API serves it. The OpenAI adapter reports its API through types.DialSurfaceReporter.
A tool-free call that the agent sends with a native response schema does not carry the agent's dials; see known limits.
Changes during a run¶
ConfigPart{Dials}takes effect at the next safe point (D-25).- While a tool loop with signed reasoning is open, a reasoning mode change waits for the next user turn: providers reject a thinking change in the middle of such a loop. A depth change waits too, unless the offering declares
"depth_change": "per_request". The report records the change asdeferred, with the value that was kept. - When the offering declares
"change_resets_cache": true, a reasoning change against the previous call reportscache_reset_expected. The Anthropic thinking offerings declare it. types.SwitchcarriesDials, so anOutcomePolicycan raise reasoning depth on the same model before it switches models. A switch that changes neither the model nor the dials is ignored (D-26).- A running session keeps its catalog snapshot (D-13). A changed catalog revision applies to new sessions.
Seeing what was sent¶
types.ResolveDials returns a types.DialReport:
| Field | Meaning |
|---|---|
Requested |
the merged dials |
Effective |
the raw options the adapter sends |
EffectiveHash |
a short hash of Effective, equal for equal parameters |
Decisions |
one per dial: applied, mapped, dropped, rejected, raw_override or deferred, with what was sent, why, the scope that set it, and cache_reset_expected |
Policy |
default, strict, or the overrides |
- Each router attempt's
types.RouteDeltacarries the compiledOptionsand theDialsreport. The agent saves the committed attempt's route on the turn astypes.RoutePart, report included. A single adapter reports no route, so for a call with dials the agent compiles them the same way the adapter does and emits the route itself, with the report, whatever the decisions were. saige catalog explain <preset|provider/model> --dials '{"creativity":"focused"}'prints, for every chain entry, each dial decision with its reason and the raw options the entry would send.--toolscompiles for a request with tools,--surface chat|responsespicks the OpenAI API,--strictand--policy name=handlingset the policy, and--format jsonprints the same as JSON.- Traces add
saige.dials.requested,saige.dials.mapped,saige.dials.droppedandsaige.dials.policyto the call span.gen_ai.request.*keeps reporting the effective raw options. agent/eval.AgentRun.Routesrecords each call's effective options and decisions.eval.WithDialPolicyruns subjects under a policy, and a comparison warns when a held dial was sent as different raw parameters on the two arms.
Declaring dials in the catalog¶
Dials are declared on offerings, the model and endpoint pairs of the catalog, and on offering templates. An offering needs no dials object: its mapping is derived from its parameter specification.
- Creativity is derived only when the offering accepts
temperature:deterministicis temperature 0,focused0.3 (withtop_p0.9 when accepted),balanced0.7 andcreative1.0. An offering whosesampling.*constraints forbid sampling while it reasons drops creativity while reasoning is active. - Reasoning depth maps by name onto the
reasoning.effortvalues, then to the nearest declared effort. Areasoning.budgetrange maps by fraction of the range; without a declared maximum the budgets are 1024, 2048, 8192, 16384 and 32768 tokens, and a budget is kept below the output cap. Areasoning.enabledtoggle maps to on and off, and a depth collapses to on. Off maps to effortnone, budget 0 or the toggle where the offering allows it, and otherwise to the lowest depth. - On OpenAI's Chat Completions, an offering with the
openai.chat.toolsconstraint maps reasoning to effortnonewhen tools are offered. The Responses API keeps the effort, andprovider.Buildserves such a model on the Responses API when a configured reasoning dial is not off. - Cache selects markers on Anthropic and automatic caching on OpenAI.
Declare dials to override any part:
"dials": {
"creativity": {
"levels": { "focused": { "temperature": 0.2 } },
"requires_reasoning_off": true
},
"reasoning": {
"off": { "reasoning": { "effort": "none" } },
"depth": { "max": { "reasoning": { "effort": "xhigh" } } },
"depth_change": "per_request",
"change_resets_cache": true,
"with_tools": { "chat": { "reasoning": { "effort": "none" } } }
},
"cache": { "on": { "mode": "markers", "ttl": "5m", "system": true, "tools": true } },
"defaults": { "reasoning": { "depth": "medium" } }
}
Mapped values are options objects. A declared level, depth or surface overrides the derived one of the same key, so an overlay can patch one level and keep the rest. Templates and offerings merge dials field by field. See the catalog guide for presets, validation and hashing.
Scenarios¶
| Scenario | Expressed as | What happens | Recorded | |
|---|---|---|---|---|
| a | Temperature 0.2 everywhere, failover from gpt-6-luna to claude-haiku-5-5 | creativity: focused |
luna defaults to effort medium and takes sampling only with reasoning off, so creativity is dropped. Haiku's adaptive thinking takes no sampling controls, so it is dropped again. Failover proceeds; no member is skipped. | creativity dropped on both attempts |
| a | The same, raw | temperature: 0.2 |
Both members reject it, no member is eligible, and the error names both reasons. A preset that shares a raw temperature across a chain gets a prefer_dial warning. |
ErrInvalidModelConfig |
| b | "Deterministic" on a model with no seed | creativity: deterministic |
Advisory: temperature 0 where the model takes it, dropped where it does not. | applied or dropped |
| b | The same, with a seed | reproducible: 7 |
Contractual: Claude takes no seed, so a Claude member is skipped and a member that takes one serves. | rejected on Claude, applied on the server |
| c | Depth high across vendors | reasoning: {depth: high} |
claude-haiku-5-5: effort high. gpt-6.1-sol: effort high. gemini-3.8-flash: thinking level HIGH. Ollama qwen3: think on. | applied, applied, applied, mapped ("depth collapsed to toggle") |
| c | Depth max, or reasoning off | depth: max, mode: off |
Gemini 3 maps max to its highest level, high. gpt-6.1-sol requires reasoning, so off maps to effort low; Gemini 3 maps off to its lowest level. | mapped |
| d | Tools on gpt-6-luna | depth: high with tools |
Chat Completions maps reasoning to effort none and records the remedy. The Responses API keeps effort high, and creativity is then dropped by the conflict rule. provider.Build picks the Responses API for this model when the reasoning dial is on. A raw effort with tools on Chat Completions stays rejected. |
mapped on chat, applied on responses |
| e | A policy raises depth mid-conversation | ConfigPart{Dials: depth high, Reason: "policy"} |
Resolved at the next safe point. A mode change waits while a signed tool loop is open. The next route shows a new effective hash and cache_reset_expected on offerings that declare it. |
deferred, then applied |
| f | Structured output on a model without native support | an output schema | D-21 applies unchanged: tool or prompt mode is chosen, and an explicit native is rejected. The SDK never falls back to extracting JSON from text. |
not a dial |
| g | An eval that holds settings constant | eval.WithDialPolicy(types.StrictDials) |
Any map or drop fails the attempt. Each call records the effective options and decisions, and a comparison warns when a held dial was sent differently. | rejected |
| h | A user catalog overrides a mapping | an overlay offering patching dials.creativity.levels.focused |
Merged as a JSON merge patch. Every mapped value must pass the offering's validation and be expressible by its adapter, or the catalog fails to load. The configuration hash covers the compiled mapping. A repository layer may not set dials. |
load-time invalid_dial |
Known limits¶
- Native response schemas. A
types.Requestcan carry aSchemaandOptionstogether, and the built-in adapters apply both. The agent loop still sends one or the other: a tool-free call with a native schema (OutputNative, or auto mode on a provider with native structured output and no tools) is sent with the schema and without request options, so the agent's dials are not sent on it, and it logs a warning. Set dials that must cover such calls on the provider:provider.Config.Dials, a preset's or entry'sdials, or an adapter'sWithDials. Those are compiled by the adapter on every request, the schema path included. - Deferral needs a starting value. A signed tool loop holds the reasoning dial that was in force when it opened. If no reasoning dial was set then, the model ran on its default, which no dial value names, so a reasoning change inside that loop is not deferred.
- Cache reset after a reload.
cache_reset_expectedcompares against the options last sent in the same routing session, which is not saved with the tree. The first call after a reload does not report it.