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;