Module options 

Portable generation options: provider-neutral knobs a request sets once and every completion wire maps to its own JSON, or refuses. They hold only what CompletionRequest has no field for, so temperature, max_tokens, tool_choice and output_schema stay on the request.

use rig_core::completion::{CacheRetention, CompletionRequest, Effort, GenerationOptions};

let options = GenerationOptions::default()
    .reasoning(Effort::High)
    .cache(CacheRetention::Long);
let request = CompletionRequest::new("Plan the refactor.").options(options);
assert!(!request.options.is_default());

Structs

BaseInput

The base builder’s view of the options and the layers above it. It cannot write them.

FinalBody

The merged request body. Its field is private to this module, so only request_params builds one, and nothing writes to it afterwards. Serialize is for wires that hand their SDK the body as bytes.

GenerationOptions

Provider-neutral generation knobs for one request. An unset field leaves the provider’s default. A field the wire or model cannot honour is reported through Self::unsupported_policy, never silently dropped.

OptionFields

Every option but the policy, borrowed, as a wire’s map_options reads it. Not #[non_exhaustive], so wires in companion crates destructure it whole, which #[non_exhaustive] forbids for GenerationOptions.

OptionMap

One Mapping per option, by field name. Not #[non_exhaustive] and no Default, so a wire writes every field.

UnsupportedOption

An option the wire or model cannot honour. Carried by ProviderError::UnsupportedOption.

Enums

CacheRetention

How long the provider keeps the prompt prefix cached.

Effort

A portable reasoning effort level, lowest first.

Mapping

What a wire does with one option.

OnUnsupported

What happens to an option the wire or model cannot honour.

RawAt

Where the raw layer, additional_params, merges. Data, not code.

Reasoning

How much the model reasons before answering.

Rewrite

The writes request_params makes after the merge, each one a write a wire made after merging additional_params before. Each reads the merged body, raw keys included. A third-party wire uses the stream ones; the provider-specific ones are rig’s own and hidden.

ServiceTier

The processing tier a request asks for.

Verbosity

How long the answer should be.

Functions

check

Report each option target cannot honour for request under its policy: an error under OnUnsupported::Error; under OnUnsupported::Ignore a warning, and the option is cleared on request, so it is reported once. A set option the wire answers Mapping::Nothing is an error. Completion::prepare calls it on the routed target before every completion encode.

param

The value top-level key gets from the mapped options, the provider options and additional_params, merged as request_params merges them, with no base. For a reader that runs before encoding and must agree with the body. Read only, so it cannot rank anything, and it reports nothing: a refused option adds nothing here. The one sanctioned reader of these layers on the completion path outside the merge. A wire’s map_options must not call it, since it calls map_options.

request_params

The body target sends for request. Reports each refused option (after Completion::prepare none is left), then calls base for the wire’s own encoding of the request, merges the mapped options, then the provider options at the top level, then additional_params as raw_at places them, and applies rewrites in order. The only reader of the request’s options, provider options and additional_params on the completion path.