Skip to main content

rig_core/completion/
options.rs

1//! Portable generation options: provider-neutral knobs a request sets once
2//! and every completion wire maps to its own JSON, or refuses. They hold only
3//! what [`CompletionRequest`](super::CompletionRequest) has no field for, so
4//! `temperature`, `max_tokens`, `tool_choice` and `output_schema` stay on the
5//! request.
6//!
7//! ```
8//! use rig_core::completion::{CacheRetention, CompletionRequest, Effort, GenerationOptions};
9//!
10//! let options = GenerationOptions::default()
11//!     .reasoning(Effort::High)
12//!     .cache(CacheRetention::Long);
13//! let request = CompletionRequest::new("Plan the refactor.").options(options);
14//! assert!(!request.options.is_default());
15//! ```
16
17use std::borrow::Cow;
18
19use serde::{Deserialize, Serialize};
20
21mod mapping;
22mod merge;
23
24pub(crate) use mapping::OptionName;
25pub use mapping::{Mapping, OptionFields, OptionMap};
26pub use merge::{BaseInput, FinalBody, RawAt, Rewrite, check, param, request_params};
27pub(crate) use merge::{BodyRefusal, CatalogRefusal, catalog_refusals, collect_refusals};
28
29/// Provider-neutral generation knobs for one request. An unset field leaves
30/// the provider's default. A field the wire or model cannot honour is
31/// reported through [`Self::unsupported_policy`], never silently dropped.
32///
33/// This is the reusable value: build it once and hand it to an agent
34/// (`AgentBuilder::options`), overlay a run's on an agent's
35/// ([`Self::overlay`]), or store it serialized with a request. For a single
36/// request, `CompletionRequest`, `AgentBuilder` and `AgentRunner` also have
37/// a shortcut per field (`.seed(7)`) that writes that one field into their
38/// options.
39#[non_exhaustive]
40#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
41pub struct GenerationOptions {
42    /// How much the model reasons before answering.
43    #[serde(default)]
44    pub reasoning: Option<Reasoning>,
45    /// How long the provider keeps the prompt prefix cached.
46    #[serde(default)]
47    pub cache: Option<CacheRetention>,
48    /// The processing tier the request asks for.
49    #[serde(default)]
50    pub service_tier: Option<ServiceTier>,
51    /// How long the answer should be.
52    #[serde(default)]
53    pub verbosity: Option<Verbosity>,
54    /// Whether the model may call several tools in one turn.
55    #[serde(default)]
56    pub parallel_tool_calls: Option<bool>,
57    /// Nucleus sampling probability mass.
58    #[serde(default, deserialize_with = "crate::json_utils::floats")]
59    pub top_p: Option<f64>,
60    /// Sampling seed, for providers that offer best-effort determinism.
61    #[serde(default)]
62    pub seed: Option<u64>,
63    /// Sequences that end generation. Empty means none.
64    #[serde(default, skip_serializing_if = "Vec::is_empty")]
65    pub stop: Vec<String>,
66    /// A key the provider routes prompt-cache lookups by, such as a
67    /// conversation's id: requests with the same key reach the server that
68    /// holds their prefix. A hint: providers that route without one send
69    /// nothing for it.
70    #[serde(default, skip_serializing_if = "Option::is_none")]
71    pub cache_key: Option<String>,
72    /// What happens to an option the wire or model cannot honour. `None`
73    /// leaves the policy unset, which acts as [`OnUnsupported::Error`]
74    /// ([`Self::unsupported_policy`]); a set policy counts as setting an
75    /// option.
76    #[serde(default, skip_serializing_if = "Option::is_none")]
77    pub on_unsupported: Option<OnUnsupported>,
78}
79
80impl GenerationOptions {
81    /// No option set and no policy set; the same as [`Self::default`].
82    pub fn new() -> Self {
83        Self::default()
84    }
85
86    /// Whether every field holds its default: no option set, and no
87    /// policy set. A request whose options are default is not checked
88    /// against its model's catalog rules; setting any field, the policy
89    /// included, turns the checks on.
90    pub fn is_default(&self) -> bool {
91        *self == Self::default()
92    }
93
94    /// The policy in effect: the one set, or [`OnUnsupported::Error`].
95    pub fn unsupported_policy(&self) -> OnUnsupported {
96        self.on_unsupported.unwrap_or_default()
97    }
98
99    /// Set the reasoning level or budget.
100    pub fn reasoning(mut self, reasoning: impl Into<Reasoning>) -> Self {
101        self.reasoning = Some(reasoning.into());
102        self
103    }
104
105    /// Set the cache retention.
106    pub fn cache(mut self, cache: CacheRetention) -> Self {
107        self.cache = Some(cache);
108        self
109    }
110
111    /// Set the service tier.
112    pub fn service_tier(mut self, tier: ServiceTier) -> Self {
113        self.service_tier = Some(tier);
114        self
115    }
116
117    /// Set the answer verbosity.
118    pub fn verbosity(mut self, verbosity: Verbosity) -> Self {
119        self.verbosity = Some(verbosity);
120        self
121    }
122
123    /// Allow or forbid several tool calls in one turn.
124    pub fn parallel_tool_calls(mut self, parallel: bool) -> Self {
125        self.parallel_tool_calls = Some(parallel);
126        self
127    }
128
129    /// Set the nucleus sampling probability mass.
130    pub fn top_p(mut self, top_p: f64) -> Self {
131        self.top_p = Some(top_p);
132        self
133    }
134
135    /// Set the sampling seed.
136    pub fn seed(mut self, seed: u64) -> Self {
137        self.seed = Some(seed);
138        self
139    }
140
141    /// Replace the stop sequences.
142    pub fn stop<S: Into<String>>(mut self, stop: impl IntoIterator<Item = S>) -> Self {
143        self.stop = stop.into_iter().map(Into::into).collect();
144        self
145    }
146
147    /// Set the prompt-cache routing key.
148    pub fn cache_key(mut self, key: impl Into<String>) -> Self {
149        self.cache_key = Some(key.into());
150        self
151    }
152
153    /// Set what happens to an option the wire or model cannot honour.
154    pub fn on_unsupported(mut self, policy: OnUnsupported) -> Self {
155        self.on_unsupported = Some(policy);
156        self
157    }
158
159    /// Every option but the policy, borrowed, as a wire maps it.
160    /// Destructures `self` with no `..`, so a new field fails to compile
161    /// here first.
162    pub fn fields(&self) -> OptionFields<'_> {
163        let Self {
164            reasoning,
165            cache,
166            service_tier,
167            verbosity,
168            parallel_tool_calls,
169            top_p,
170            seed,
171            stop,
172            cache_key,
173            on_unsupported: _,
174        } = self;
175        OptionFields {
176            reasoning: reasoning.as_ref(),
177            cache: cache.as_ref(),
178            service_tier: service_tier.as_ref(),
179            verbosity: verbosity.as_ref(),
180            parallel_tool_calls: *parallel_tool_calls,
181            top_p: *top_p,
182            seed: *seed,
183            stop,
184            cache_key: cache_key.as_deref(),
185        }
186    }
187
188    /// `self` with every field `over` sets put on top: a `Some` option, a
189    /// non-empty `stop` list, a set `on_unsupported` (so a run can restore
190    /// `Error` over an agent's `Ignore`). Every other
191    /// field keeps `self`'s value. An agent's options overlaid with a run's
192    /// give the run's where it sets one.
193    pub fn overlay(self, over: &GenerationOptions) -> GenerationOptions {
194        let GenerationOptions {
195            reasoning,
196            cache,
197            service_tier,
198            verbosity,
199            parallel_tool_calls,
200            top_p,
201            seed,
202            stop,
203            cache_key,
204            on_unsupported,
205        } = over;
206        GenerationOptions {
207            reasoning: reasoning.or(self.reasoning),
208            cache: cache.or(self.cache),
209            service_tier: service_tier.or(self.service_tier),
210            verbosity: verbosity.or(self.verbosity),
211            parallel_tool_calls: parallel_tool_calls.or(self.parallel_tool_calls),
212            top_p: top_p.or(self.top_p),
213            seed: seed.or(self.seed),
214            stop: if stop.is_empty() {
215                self.stop
216            } else {
217                stop.clone()
218            },
219            cache_key: cache_key.clone().or(self.cache_key),
220            on_unsupported: on_unsupported.or(self.on_unsupported),
221        }
222    }
223}
224
225/// How much the model reasons before answering.
226#[non_exhaustive]
227#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
228#[serde(rename_all = "lowercase")]
229pub enum Reasoning {
230    /// No reasoning.
231    Off,
232    /// A portable effort level.
233    Effort(Effort),
234    /// An explicit reasoning-token budget.
235    Budget {
236        /// The most tokens the model may spend reasoning.
237        tokens: u32,
238    },
239}
240
241impl From<Effort> for Reasoning {
242    fn from(effort: Effort) -> Self {
243        Self::Effort(effort)
244    }
245}
246
247/// A portable reasoning effort level, lowest first.
248#[non_exhaustive]
249#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
250#[serde(rename_all = "lowercase")]
251pub enum Effort {
252    /// The least reasoning the model offers.
253    Minimal,
254    /// Low effort.
255    Low,
256    /// Medium effort.
257    Medium,
258    /// High effort.
259    High,
260    /// Extra-high effort.
261    XHigh,
262    /// The most reasoning the model offers.
263    Max,
264}
265
266impl Effort {
267    /// The level's lower-case wire word, as its serde name spells it:
268    /// `"minimal"`, `"low"`, `"medium"`, `"high"`, `"xhigh"` or `"max"`.
269    pub fn as_str(&self) -> &'static str {
270        match self {
271            Self::Minimal => "minimal",
272            Self::Low => "low",
273            Self::Medium => "medium",
274            Self::High => "high",
275            Self::XHigh => "xhigh",
276            Self::Max => "max",
277        }
278    }
279
280    /// The level `word` names by its serde name, the inverse of
281    /// [`Self::as_str`].
282    pub(crate) fn named(word: &str) -> Option<Self> {
283        Self::deserialize(serde::de::value::StrDeserializer::<serde::de::value::Error>::new(word))
284            .ok()
285    }
286}
287
288/// How long the provider keeps the prompt prefix cached.
289#[non_exhaustive]
290#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
291#[serde(rename_all = "lowercase")]
292pub enum CacheRetention {
293    /// Do not cache.
294    None,
295    /// The provider's short retention, typically minutes.
296    Short,
297    /// The provider's long retention, typically an hour or more.
298    Long,
299}
300
301/// The processing tier a request asks for.
302#[non_exhaustive]
303#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
304#[serde(rename_all = "lowercase")]
305pub enum ServiceTier {
306    /// The provider chooses.
307    Auto,
308    /// The standard tier.
309    Default,
310    /// Cheaper, slower processing.
311    Flex,
312    /// Faster, dearer processing.
313    Priority,
314}
315
316/// How long the answer should be.
317#[non_exhaustive]
318#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
319#[serde(rename_all = "lowercase")]
320pub enum Verbosity {
321    /// Terse.
322    Low,
323    /// Balanced.
324    Medium,
325    /// Detailed.
326    High,
327}
328
329impl Verbosity {
330    /// The level's lower-case wire word: `"low"`, `"medium"` or `"high"`.
331    pub fn as_str(&self) -> &'static str {
332        match self {
333            Self::Low => "low",
334            Self::Medium => "medium",
335            Self::High => "high",
336        }
337    }
338}
339
340/// What happens to an option the wire or model cannot honour.
341#[non_exhaustive]
342#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash, Serialize, Deserialize)]
343#[serde(rename_all = "lowercase")]
344pub enum OnUnsupported {
345    /// The request fails with [`UnsupportedOption`].
346    #[default]
347    Error,
348    /// The option is skipped with a warning.
349    Ignore,
350}
351
352/// An option the wire or model cannot honour. Carried by
353/// [`ProviderError::UnsupportedOption`](crate::error::ProviderError::UnsupportedOption).
354#[non_exhaustive]
355#[derive(Clone, Debug, PartialEq, Eq, thiserror::Error)]
356#[error("`{option}` is not supported by {provider} model `{model}`: {reason}")]
357pub struct UnsupportedOption {
358    /// The [`GenerationOptions`] field name, such as `"reasoning"`, a
359    /// provider option's `"<provider>.<section>.<field>"`, such as
360    /// `"openrouter.*.provider"`, or the body key a model's catalog entry
361    /// refuses, such as `"temperature"` or `"tools"`.
362    pub option: Cow<'static, str>,
363    /// The provider that refused it.
364    pub provider: String,
365    /// The model the request resolved to.
366    pub model: String,
367    /// Why it cannot be honoured.
368    pub reason: String,
369}
370
371impl UnsupportedOption {
372    /// The refusal of `option` by `provider` for `model`, because of `reason`.
373    pub fn new(
374        option: impl Into<Cow<'static, str>>,
375        provider: impl Into<String>,
376        model: impl Into<String>,
377        reason: impl Into<String>,
378    ) -> Self {
379        Self {
380            option: option.into(),
381            provider: provider.into(),
382            model: model.into(),
383            reason: reason.into(),
384        }
385    }
386}
387
388/// Why a dry run of a completion request failed: what
389/// [`DynModel::check`](crate::DynModel::check) returns.
390#[non_exhaustive]
391#[derive(Debug, thiserror::Error)]
392pub enum CheckError {
393    /// Every option the wire or model cannot honour, in the order the wire
394    /// meets them. The request builds once they are removed.
395    #[error("{}", unsupported_list(.0))]
396    Unsupported(Vec<UnsupportedOption>),
397    /// The request cannot be built for another reason, such as an empty
398    /// history. Refusals met before it are not listed, since the build
399    /// stopped there.
400    #[error(transparent)]
401    Invalid(crate::error::ProviderError),
402}
403
404/// The refusals, one per clause.
405fn unsupported_list(refusals: &[UnsupportedOption]) -> String {
406    refusals
407        .iter()
408        .map(ToString::to_string)
409        .collect::<Vec<_>>()
410        .join("; ")
411}
412
413#[cfg(test)]
414mod tests;