Skip to main content

rig_core/catalog/
spec.rs

1//! What the catalog knows about one model, and the checks it makes against
2//! [`GenerationOptions`].
3
4use std::ops::RangeInclusive;
5
6use serde::{Deserialize, Serialize};
7
8use crate::completion::options::{CatalogRefusal, OptionName};
9use crate::completion::{
10    CacheRetention, CompletionRequest, Cost, Effort, GenerationOptions, Reasoning,
11    UnsupportedOption, Usage,
12};
13use crate::providers::registry::{Format, ProviderId};
14
15use super::details::ModelDetails;
16
17/// One model's facts: limits, input modalities, the reasoning and caching it
18/// takes, and its prices. [`Catalog`](super::Catalog) builds one per row of
19/// its data; [`ModelSpec::new`] and the `with_*` setters build one in code,
20/// for a model the catalog does not list, and
21/// [`Catalog::insert`](super::Catalog::insert) adds it.
22///
23/// It serializes field by field and reads back the same. For the override
24/// file's row shape, use [`Self::to_row_json`].
25///
26/// ```
27/// use rig_core::catalog::{Catalog, ModelSpec, Pricing};
28/// use rig_core::providers::registry::ProviderId;
29///
30/// let ollama = ProviderId::catalog("ollama").ok_or("a known vendor")?;
31/// let mut catalog = Catalog::builtin().clone();
32/// catalog.insert(
33///     ModelSpec::new(ollama, "qwen3:4b")
34///         .with_context_window(32_768)
35///         .with_tools(true)
36///         .with_pricing(Pricing::new(0.0, 0.0)),
37/// );
38/// let qwen = catalog.get(ollama, "qwen3:4b").ok_or("inserted")?.spec;
39/// assert_eq!(qwen.context_window, Some(32_768));
40/// # Ok::<(), &str>(())
41/// ```
42#[non_exhaustive]
43#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
44pub struct ModelSpec {
45    /// The provider's own model id.
46    pub id: String,
47    /// The provider serving the model under [`Self::id`], in the protocol
48    /// family the model is reached by: its vendor's own
49    /// ([`ProviderId::catalog`]) unless the catalog row names another
50    /// under `rig.format`. [`Self::format`] reads it.
51    pub provider: ProviderId,
52    /// A human-readable name.
53    pub display_name: String,
54    /// The most tokens the model reads and writes in one request, if known.
55    pub context_window: Option<u32>,
56    /// The most tokens the model reads in one request, when the provider
57    /// caps input below [`Self::context_window`]. [`Self::input_limit`]
58    /// reads both.
59    #[serde(default)]
60    pub max_input_tokens: Option<u32>,
61    /// The most tokens the model writes in one reply, if known.
62    pub max_output_tokens: Option<u32>,
63    /// What the model reads.
64    pub input: Modalities,
65    /// The reasoning the model takes.
66    pub reasoning: ReasoningSupport,
67    /// The cache retentions the model honours.
68    pub caching: CacheSupport,
69    /// Whether the model calls tools.
70    pub tools: bool,
71    /// Whether the model constrains its output to a JSON schema.
72    pub structured_output: bool,
73    /// Prices in USD per million tokens, if known.
74    pub pricing: Option<Pricing>,
75    /// Whether the provider has deprecated the model.
76    pub deprecated: bool,
77    /// When the model takes sampling parameters (`temperature`, `top_p`,
78    /// `top_logprobs`, `logprobs`), or `None` when unknown.
79    pub sampling: Option<Sampling>,
80    /// Wire facts the encoders read that no portable field holds.
81    pub compat: Compat,
82    /// What the catalog records about the model that rig does not act on.
83    #[serde(default)]
84    pub details: ModelDetails,
85}
86
87/// What a model reads.
88#[non_exhaustive]
89#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash, Serialize, Deserialize)]
90pub struct Modalities {
91    /// Text.
92    pub text: bool,
93    /// Images.
94    pub image: bool,
95    /// Audio.
96    pub audio: bool,
97    /// Video.
98    pub video: bool,
99    /// PDF documents.
100    pub pdf: bool,
101}
102
103/// The reasoning a model takes, in one of three states: it does not reason,
104/// it reasons but the catalog does not say which controls it takes, or it
105/// reasons and takes exactly the listed controls.
106///
107/// A catalog row that marks a model as reasoning but lists no reasoning
108/// options (most of them gateway rows on HuggingFace, OpenRouter, Venice and
109/// Bedrock) is [`Self::Unknown`], which refuses nothing, as an empty
110/// [`CacheSupport`] does. Only a row whose hand-reviewed `rig` facts say
111/// `"reasoning_control": "none"` (a model whose API rejects every reasoning
112/// control) is [`Self::Listed`] with nothing listed.
113///
114/// ```
115/// use rig_core::catalog::ReasoningSupport;
116/// use rig_core::completion::{Effort, Reasoning};
117///
118/// let unknown = ReasoningSupport::Unknown { default: None };
119/// assert!(unknown.supported() && unknown.levels().is_none());
120/// assert_eq!(unknown.refusal(&Reasoning::Effort(Effort::High)), None);
121///
122/// let listed = ReasoningSupport::Listed {
123///     levels: vec![Effort::Low, Effort::High],
124///     budget: None,
125///     can_disable: false,
126///     default: Some(Effort::High),
127/// };
128/// assert!(listed.refusal(&Reasoning::Off).is_some());
129/// assert_eq!(listed.refusal(&Reasoning::Effort(Effort::Low)), None);
130/// ```
131#[non_exhaustive]
132#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
133#[serde(rename_all = "snake_case")]
134pub enum ReasoningSupport {
135    /// The model does not reason.
136    #[default]
137    None,
138    /// The model reasons; the catalog does not say which controls it takes.
139    /// Nothing is refused.
140    Unknown {
141        /// The effort it uses when a request names none, if documented.
142        default: Option<Effort>,
143    },
144    /// The model reasons and takes exactly these controls.
145    Listed {
146        /// The effort levels it takes, empty when it takes none.
147        levels: Vec<Effort>,
148        /// The reasoning-token budgets it takes, if it takes one.
149        budget: Option<RangeInclusive<u32>>,
150        /// Whether a request can turn its reasoning off.
151        can_disable: bool,
152        /// The effort it uses when a request names none, if documented.
153        default: Option<Effort>,
154    },
155}
156
157/// The cache retentions a model honours.
158#[non_exhaustive]
159#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
160pub struct CacheSupport {
161    /// The [`CacheRetention`] values the model honours. Empty when the
162    /// catalog does not know, in which case nothing is refused.
163    pub retention: Vec<CacheRetention>,
164}
165
166/// Prices in USD per million tokens.
167#[non_exhaustive]
168#[derive(Clone, Copy, Debug, PartialEq, Serialize, Deserialize)]
169pub struct Pricing {
170    /// Uncached input.
171    pub input: f64,
172    /// Output, reasoning included.
173    pub output: f64,
174    /// Input read from the cache, or `None` when unknown.
175    pub cache_read: Option<f64>,
176    /// Input written to the cache, or `None` when unknown.
177    pub cache_write: Option<f64>,
178}
179
180impl Pricing {
181    /// Prices for uncached input and for output, with no cache prices.
182    pub fn new(input: f64, output: f64) -> Self {
183        Self {
184            input,
185            output,
186            cache_read: None,
187            cache_write: None,
188        }
189    }
190
191    /// These prices with `price` for input read from the cache.
192    pub fn with_cache_read(mut self, price: f64) -> Self {
193        self.cache_read = Some(price);
194        self
195    }
196
197    /// These prices with `price` for input written to the cache.
198    pub fn with_cache_write(mut self, price: f64) -> Self {
199        self.cache_write = Some(price);
200        self
201    }
202
203    /// What `usage` costs at these prices, or `None` unless it reports both
204    /// its input and output tokens. Uncached input is the input tokens less
205    /// those read from and written to the cache. A cache part with tokens
206    /// but no listed price is `None`, and the cost is then not
207    /// [complete](Cost::is_complete): its `total` leaves that part out. Every
208    /// cache write here is charged at one price; a decoder whose provider
209    /// splits writes by lifetime prices them itself.
210    /// These are standard-tier API list-price estimates, not subscription
211    /// charges or verified invoices, including for custom endpoints. Service
212    /// tiers, long-context tiers and hosted-tool fees are not included.
213    pub fn cost(&self, usage: &Usage) -> Option<Cost> {
214        let written = usage.cache_creation_input_tokens.unwrap_or(0);
215        let write_cost = match written {
216            0 => Some(0.0),
217            tokens => self
218                .cache_write
219                .map(|rate| tokens as f64 * rate / 1_000_000.0),
220        };
221        self.cost_with_cache_write(usage, write_cost)
222    }
223
224    /// Price the counters with a separately calculated cache-write cost in
225    /// USD. `None` leaves the write part unknown and the total incomplete.
226    pub(crate) fn cost_with_cache_write(
227        &self,
228        usage: &Usage,
229        write_cost: Option<f64>,
230    ) -> Option<Cost> {
231        let input = usage.input_tokens?;
232        let output = usage.output_tokens?;
233        let read = usage.cached_input_tokens.unwrap_or(0);
234        let written = usage.cache_creation_input_tokens.unwrap_or(0);
235        let uncached = input.saturating_sub(read).saturating_sub(written);
236        // Token counts stay far below 2^53, so the conversion is exact.
237        let price = |tokens: u64, per_million: f64| tokens as f64 * per_million / 1_000_000.0;
238        // No tokens cost nothing, whether or not the rate is listed.
239        let cache = |tokens: u64, rate: Option<f64>| match (tokens, rate) {
240            (0, _) => Some(0.0),
241            (tokens, rate) => rate.map(|rate| price(tokens, rate)),
242        };
243        Some(Cost::priced(
244            price(uncached, self.input),
245            price(output, self.output),
246            cache(read, self.cache_read),
247            write_cost,
248        ))
249    }
250}
251
252/// When a model takes sampling parameters.
253#[non_exhaustive]
254#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
255#[serde(rename_all = "snake_case")]
256pub enum Sampling {
257    /// Always.
258    Any,
259    /// Only while its reasoning is off.
260    ReasoningOff,
261    /// Never.
262    Never,
263}
264
265/// When OpenAI Chat Completions takes a model's tools.
266#[non_exhaustive]
267#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
268#[serde(rename_all = "snake_case")]
269pub enum ChatTools {
270    /// Always.
271    Any,
272    /// Only while its reasoning is off.
273    ReasoningOff,
274    /// Never: tool calls need the Responses API.
275    Never,
276}
277
278/// Wire facts the encoders read that no portable field holds. Each defaults
279/// to `false` or `None`, which is what a model the field does not concern
280/// has. An override file sets each one by its field name under a row's
281/// `rig` object, and a spec built in code sets it with the `with_*` setter
282/// of the same name.
283#[non_exhaustive]
284#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
285pub struct Compat {
286    /// The field an OpenAI Chat Completions assistant message must carry
287    /// its reasoning under, such as `reasoning_content`.
288    pub reasoning_field: Option<String>,
289    /// Anthropic: an effort level goes with `thinking: {"type": "adaptive"}`.
290    pub adaptive_thinking: bool,
291    /// Anthropic: the `thinking.type` that turns reasoning off, where it is
292    /// not `disabled`.
293    pub thinking_off: Option<String>,
294    /// Anthropic: the model takes `role: "system"` inside `messages`.
295    pub mid_conversation_system: bool,
296    /// Anthropic: the model answers a forced `tool_choice` with an error.
297    pub rejects_forced_tool_choice: bool,
298    /// Anthropic: the model binds its thinking to the request's tools and
299    /// system prompt.
300    pub binds_context: bool,
301    /// OpenAI: the prompt cache takes `prompt_cache_options`, not
302    /// `prompt_cache_retention`.
303    pub prompt_cache_options: bool,
304    /// OpenAI: when Chat Completions takes the model's tools. `None` is
305    /// [`ChatTools::Any`].
306    pub chat_tools: Option<ChatTools>,
307    /// The model continues a request that ends in an assistant message (a
308    /// prefill) from where that message stops, instead of refusing it, as
309    /// Anthropic's models before Claude 4.6 do while their reasoning is
310    /// off. Unknown is `false`.
311    pub prefill: bool,
312}
313
314impl Compat {
315    /// These facts with `field` as the Chat Completions assistant message's
316    /// reasoning field.
317    pub fn with_reasoning_field(mut self, field: impl Into<String>) -> Self {
318        self.reasoning_field = Some(field.into());
319        self
320    }
321
322    /// These facts with prefill continuation set to `on`.
323    pub fn with_prefill(mut self, on: bool) -> Self {
324        self.prefill = on;
325        self
326    }
327}
328
329impl CacheSupport {
330    /// Support for exactly the retentions in `retention`. An empty list means
331    /// the catalog does not know, and refuses nothing.
332    pub fn new(retention: impl IntoIterator<Item = CacheRetention>) -> Self {
333        Self {
334            retention: retention.into_iter().collect(),
335        }
336    }
337}
338
339impl ModelSpec {
340    /// A spec for `provider`'s model `id` with nothing else known: its id as
341    /// its name, no limits, text input only, no reasoning, unknown caching,
342    /// no tools or structured output, no prices (`None`, never zero), not
343    /// deprecated, unknown sampling, default [`Compat`] and no
344    /// [`ModelDetails`].
345    pub fn new(provider: ProviderId, id: impl Into<String>) -> Self {
346        let id = id.into();
347        Self {
348            display_name: id.clone(),
349            id,
350            provider,
351            context_window: None,
352            max_input_tokens: None,
353            max_output_tokens: None,
354            input: Modalities {
355                text: true,
356                ..Modalities::default()
357            },
358            reasoning: ReasoningSupport::default(),
359            caching: CacheSupport::default(),
360            tools: false,
361            structured_output: false,
362            pricing: None,
363            deprecated: false,
364            sampling: None,
365            compat: Compat::default(),
366            details: ModelDetails::default(),
367        }
368    }
369
370    /// The protocol family a connection to this model speaks unless told
371    /// otherwise, or `None` for a provider the registry cannot configure.
372    /// To reach the model in another family its vendor is registered for,
373    /// build the spec with that [`ProviderId`] or pass the family to
374    /// [`ConnectOptions::format`](crate::providers::registry::ConnectOptions::format).
375    pub fn format(&self) -> Option<Format> {
376        self.provider.format()
377    }
378
379    /// The `vendor/model` reference [`Catalog::resolve`](super::Catalog::resolve)
380    /// reads back to this model.
381    pub fn reference(&self) -> String {
382        format!("{}/{}", self.provider.vendor(), self.id)
383    }
384
385    /// The options of a request to this model with `reasoning` (`None`
386    /// for the provider's default): that reasoning, and the short prompt
387    /// cache when [`Self::caching`] lists it. A model whose caching the
388    /// catalog does not know gets no cache option, which it could refuse.
389    pub fn default_options(&self, reasoning: Option<Reasoning>) -> GenerationOptions {
390        let options = GenerationOptions {
391            reasoning,
392            ..GenerationOptions::default()
393        };
394        if self.caching.retention.contains(&CacheRetention::Short) {
395            options.cache(CacheRetention::Short)
396        } else {
397            options
398        }
399    }
400
401    /// This spec named `name`.
402    pub fn with_display_name(mut self, name: impl Into<String>) -> Self {
403        self.display_name = name.into();
404        self
405    }
406
407    /// This spec with a context window of `tokens`.
408    pub fn with_context_window(mut self, tokens: u32) -> Self {
409        self.context_window = Some(tokens);
410        self
411    }
412
413    /// This spec reading at most `tokens` in one request.
414    pub fn with_max_input_tokens(mut self, tokens: u32) -> Self {
415        self.max_input_tokens = Some(tokens);
416        self
417    }
418
419    /// The most tokens a request to this model may send: its input limit
420    /// when that is below its window, else its window; `None` when neither
421    /// is known.
422    pub fn input_limit(&self) -> Option<u32> {
423        match (self.max_input_tokens, self.context_window) {
424            (Some(input), Some(window)) => Some(input.min(window)),
425            (input, window) => input.or(window),
426        }
427    }
428
429    /// The most tokens a reply from this model may write: its output limit
430    /// held to its window, as a reply never outgrows the window; `None` when
431    /// the output limit is not known.
432    pub fn output_limit(&self) -> Option<u32> {
433        let window = self.context_window.unwrap_or(u32::MAX);
434        self.max_output_tokens.map(|output| output.min(window))
435    }
436
437    /// This spec writing at most `tokens` in one reply.
438    pub fn with_max_output_tokens(mut self, tokens: u32) -> Self {
439        self.max_output_tokens = Some(tokens);
440        self
441    }
442
443    /// This spec taking `reasoning`.
444    pub fn with_reasoning(mut self, reasoning: ReasoningSupport) -> Self {
445        self.reasoning = reasoning;
446        self
447    }
448
449    /// This spec honouring `caching`.
450    pub fn with_caching(mut self, caching: CacheSupport) -> Self {
451        self.caching = caching;
452        self
453    }
454
455    /// This spec with tool calling set to `tools`.
456    pub fn with_tools(mut self, tools: bool) -> Self {
457        self.tools = tools;
458        self
459    }
460
461    /// This spec priced at `pricing`.
462    pub fn with_pricing(mut self, pricing: Pricing) -> Self {
463        self.pricing = Some(pricing);
464        self
465    }
466
467    /// This spec taking sampling parameters as `sampling` says.
468    pub fn with_sampling(mut self, sampling: Sampling) -> Self {
469        self.sampling = Some(sampling);
470        self
471    }
472
473    /// This spec with the wire facts `compat`.
474    pub fn with_compat(mut self, compat: Compat) -> Self {
475        self.compat = compat;
476        self
477    }
478
479    /// This spec with the catalog's other records `details`.
480    pub fn with_details(mut self, details: ModelDetails) -> Self {
481        self.details = details;
482        self
483    }
484
485    /// This spec as one models.dev-shaped row of an override file, with
486    /// rig's facts under `rig`. Read back under its vendor key, the row
487    /// builds this spec again. A fact the spec does not know (a `None`
488    /// limit, price, sampling rule or reasoning default, or empty caching)
489    /// is left out, so laid over another row it keeps that row's value.
490    pub fn to_row_json(&self) -> serde_json::Value {
491        super::row::Row::from_spec(self).to_json()
492    }
493
494    /// Checks `options` against the rules [`Self::refusals`] applies,
495    /// and returns the first refusal. It checks only what `options` holds,
496    /// so it never refuses `temperature`, which a request carries outside
497    /// its options; [`Self::refusals`] checks the whole request.
498    ///
499    /// # Errors
500    ///
501    /// The first option the model cannot take. The error names the option,
502    /// the provider's vendor and this model.
503    pub fn validate(&self, options: &GenerationOptions) -> Result<(), UnsupportedOption> {
504        match self.rules(options, None).into_iter().next() {
505            Some(refusal) => Err(self.unsupported(refusal)),
506            None => Ok(()),
507        }
508    }
509
510    /// Every option of `request` the model cannot take, by the rules every
511    /// completion wire also applies before it encodes, so a request this
512    /// refuses is refused by the model's wire too:
513    ///
514    /// - `reasoning` against [`Self::reasoning`] ([`ReasoningSupport::refusal`]);
515    /// - `cache` against [`Self::caching`] ([`CacheSupport::refusal`]);
516    /// - `top_p` and `temperature` against [`Self::sampling`]:
517    ///   [`Sampling::Never`] refuses both, and [`Sampling::ReasoningOff`]
518    ///   refuses both while the model reasons. A model that cannot turn
519    ///   reasoning off always reasons; one that can reasons unless
520    ///   `reasoning` is `Off`, and with no `reasoning` set, when it names a
521    ///   default effort.
522    ///
523    /// A request whose [`GenerationOptions`] are default is not checked, as
524    /// [`GenerationOptions::is_default`] says, so this is empty for it. A
525    /// wire refuses more than this: what its route or API cannot carry
526    /// (`DynModel::check` reports both).
527    pub fn refusals(&self, request: &CompletionRequest) -> Vec<UnsupportedOption> {
528        self.request_rules(request)
529            .into_iter()
530            .map(|refusal| self.unsupported(refusal))
531            .collect()
532    }
533
534    /// Fits `request` to this model: takes out each option it would refuse
535    /// ([`Self::refusals`]) and leaves everything else as it is, so a request
536    /// built or edited for another model keeps what this one takes. A refused
537    /// reasoning setting becomes the provider default (`None`) first, since
538    /// whether the model reasons decides whether it takes `temperature` and
539    /// `top_p`. Returns what was taken out, in that order; afterwards
540    /// [`Self::refusals`] of the request is empty.
541    ///
542    /// ```
543    /// use rig_core::catalog::{ModelSpec, ReasoningSupport};
544    /// use rig_core::completion::{CompletionRequest, Effort, GenerationOptions, Reasoning};
545    /// use rig_core::providers::registry::ProviderId;
546    ///
547    /// let vendor = ProviderId::catalog("ollama").ok_or("a known vendor")?;
548    /// let plain = ModelSpec::new(vendor, "plain").with_reasoning(ReasoningSupport::None);
549    /// let options = GenerationOptions::default().reasoning(Reasoning::Effort(Effort::High));
550    /// let mut request = CompletionRequest::new("hi").options(options.seed(7));
551    /// let dropped = plain.fit(&mut request);
552    /// assert_eq!(dropped.len(), 1);
553    /// assert_eq!((request.options.reasoning, request.options.seed), (None, Some(7)));
554    /// # Ok::<(), &str>(())
555    /// ```
556    pub fn fit(&self, request: &mut CompletionRequest) -> Vec<UnsupportedOption> {
557        let mut dropped = Vec::new();
558        // Only a set option is refused, and each pass unsets one, so this ends.
559        while let Some(refusal) = self.request_rules(request).into_iter().next() {
560            refusal.option.clear(request);
561            dropped.push(self.unsupported(refusal));
562        }
563        dropped
564    }
565
566    /// [`Self::refusals`] as the options and reasons the wires report under
567    /// their own provider name.
568    pub(crate) fn request_rules(&self, request: &CompletionRequest) -> Vec<CatalogRefusal> {
569        if request.options.is_default() {
570            return Vec::new();
571        }
572        self.rules(&request.options, request.temperature)
573    }
574
575    /// The refusals of `options` and of a request's `temperature`.
576    fn rules(&self, options: &GenerationOptions, temperature: Option<f64>) -> Vec<CatalogRefusal> {
577        let mut refusals = Vec::new();
578        if let Some(reason) = options
579            .reasoning
580            .as_ref()
581            .and_then(|reasoning| self.reasoning.refusal(reasoning))
582        {
583            refusals.push(CatalogRefusal {
584                option: OptionName::Reasoning,
585                reason,
586            });
587        }
588        if let Some(reason) = options
589            .cache
590            .as_ref()
591            .and_then(|cache| self.caching.refusal(cache))
592        {
593            refusals.push(CatalogRefusal {
594                option: OptionName::Cache,
595                reason,
596            });
597        }
598        let reasons = self.reasons_with(options.reasoning.as_ref());
599        let sampled = [
600            (OptionName::Temperature, temperature.is_some()),
601            (OptionName::TopP, options.top_p.is_some()),
602        ];
603        for (option, set) in sampled {
604            let refusal = set.then(|| self.sampling_refusal(option.as_str(), reasons));
605            if let Some(reason) = refusal.flatten() {
606                refusals.push(CatalogRefusal { option, reason });
607            }
608        }
609        refusals
610    }
611
612    /// Why the model takes no `field`, a sampling parameter, when it reasons
613    /// as `reasons` says, by [`Self::sampling`].
614    pub(crate) fn sampling_refusal(&self, field: &str, reasons: bool) -> Option<String> {
615        match self.sampling? {
616            Sampling::Never => Some(format!("the model takes no `{field}`")),
617            Sampling::ReasoningOff if reasons => {
618                Some(match self.reasoning.can_disable() == Some(true) {
619                    true => format!(
620                        "the model rejects `{field}` while it reasons; remove `{field}` or set \
621                         `reasoning` to `Off`"
622                    ),
623                    false => format!("the model rejects `{field}` while it reasons"),
624                })
625            }
626            Sampling::ReasoningOff | Sampling::Any => None,
627        }
628    }
629
630    /// Whether the model reasons when a request asks for `reasoning`: at
631    /// `Off`, only when it cannot turn reasoning off; with nothing asked, as
632    /// [`Self::reasons_by_default`] says.
633    pub(crate) fn reasons_with(&self, reasoning: Option<&Reasoning>) -> bool {
634        match reasoning {
635            Some(Reasoning::Off) => {
636                self.reasoning.supported() && self.reasoning.can_disable() == Some(false)
637            }
638            Some(_) => self.reasoning.supported(),
639            None => self.reasons_by_default(),
640        }
641    }
642
643    /// Whether the model reasons when a request asks for nothing: when it
644    /// names a default effort or cannot turn reasoning off.
645    pub(crate) fn reasons_by_default(&self) -> bool {
646        self.reasoning.supported()
647            && (self.reasoning.default_effort().is_some()
648                || self.reasoning.can_disable() == Some(false))
649    }
650
651    /// `refusal` named for this model.
652    fn unsupported(&self, refusal: CatalogRefusal) -> UnsupportedOption {
653        UnsupportedOption::new(
654            refusal.option.as_str(),
655            self.provider.vendor(),
656            &self.id,
657            refusal.reason,
658        )
659    }
660}
661
662/// A reasoning setting a model takes, by the name a picker shows: the
663/// provider default (`default`, no setting), `off`, an effort level, or a
664/// named budget.
665#[derive(Clone, Copy, Debug, PartialEq, Eq)]
666pub struct ReasoningChoice {
667    /// `default`, `off`, the level's word, or the budget's name.
668    pub name: &'static str,
669    /// The setting a request carries; `None` for the provider default.
670    pub reasoning: Option<Reasoning>,
671}
672
673impl ReasoningChoice {
674    /// The name, with a budget's tokens.
675    pub fn label(&self) -> String {
676        match self.reasoning {
677            Some(Reasoning::Budget { tokens }) => format!("{} ({tokens} tokens)", self.name),
678            _ => self.name.to_owned(),
679        }
680    }
681}
682
683/// A reasoning setting a model does not take, and the ones it does.
684#[derive(Clone, Debug, PartialEq, Eq, thiserror::Error)]
685#[error("the reasoning settings are {}{}, not `{name}`", choices.join(", "), tokens(budget))]
686pub struct UnknownReasoning {
687    /// The text asked for.
688    pub name: String,
689    /// The names of the model's [`ReasoningSupport::choices`].
690    pub choices: Vec<&'static str>,
691    /// The reasoning-token budgets the model takes, if it takes one.
692    pub budget: Option<RangeInclusive<u32>>,
693}
694
695/// `budget` as the last of the settings an [`UnknownReasoning`] lists.
696fn tokens(budget: &Option<RangeInclusive<u32>>) -> String {
697    budget.as_ref().map_or_else(String::new, |range| {
698        format!(", or {} to {} tokens", range.start(), range.end())
699    })
700}
701
702/// Token budgets for the named levels on a model that takes a budget
703/// instead of levels, clamped into its range.
704const NAMED_BUDGETS: [(Effort, u32); 3] = [
705    (Effort::Low, 2048),
706    (Effort::Medium, 8192),
707    (Effort::High, 16384),
708];
709
710impl ReasoningSupport {
711    /// The reasoning settings the model takes: the provider default first,
712    /// then `off` when reasoning can be turned off, then each effort level,
713    /// or `low`, `medium` and `high` budgets on a model that takes a budget
714    /// and no levels. A model whose controls the catalog does not list
715    /// offers only the default.
716    pub fn choices(&self) -> Vec<ReasoningChoice> {
717        let mut choices = vec![ReasoningChoice {
718            name: "default",
719            reasoning: None,
720        }];
721        let Self::Listed {
722            levels,
723            budget,
724            can_disable,
725            ..
726        } = self
727        else {
728            return choices;
729        };
730        if *can_disable {
731            choices.push(ReasoningChoice {
732                name: "off",
733                reasoning: Some(Reasoning::Off),
734            });
735        }
736        choices.extend(levels.iter().map(|level| ReasoningChoice {
737            name: level.as_str(),
738            reasoning: Some(Reasoning::Effort(*level)),
739        }));
740        if levels.is_empty()
741            && let Some(range) = budget
742        {
743            choices.extend(
744                NAMED_BUDGETS
745                    .iter()
746                    .map(|&(effort, tokens)| ReasoningChoice {
747                        name: effort.as_str(),
748                        // Not `clamp`, which panics on an inverted range.
749                        reasoning: Some(Reasoning::Budget {
750                            tokens: tokens.max(*range.start()).min(*range.end()),
751                        }),
752                    }),
753            );
754        }
755        choices
756    }
757
758    /// The choice of [`Self::choices`] named `name`.
759    ///
760    /// # Errors
761    ///
762    /// [`UnknownReasoning`] with the names there are, when none is `name`.
763    pub fn named(&self, name: &str) -> Result<ReasoningChoice, UnknownReasoning> {
764        let choices = self.choices();
765        choices
766            .iter()
767            .find(|choice| choice.name == name)
768            .copied()
769            .ok_or_else(|| self.unknown(name, &choices))
770    }
771
772    /// The setting `text` names for this model, `None` for the provider
773    /// default: a name of [`Self::choices`], so `high` is a budget on a model
774    /// that takes a budget and no levels; or else `off`, a level's word or
775    /// `<n> tokens` that the model takes ([`Self::refusal`]). Surrounding
776    /// spaces are ignored. [`Self::name_of`] prints what this reads back.
777    ///
778    /// # Errors
779    ///
780    /// [`UnknownReasoning`] with the settings there are, when the model
781    /// takes no setting named `text`.
782    pub fn parse(&self, text: &str) -> Result<Option<Reasoning>, UnknownReasoning> {
783        let text = text.trim();
784        let choices = self.choices();
785        if let Some(choice) = choices.iter().find(|choice| choice.name == text) {
786            return Ok(choice.reasoning);
787        }
788        match read(text) {
789            Some(Some(reasoning)) if self.refusal(&reasoning).is_none() => Ok(Some(reasoning)),
790            _ => Err(self.unknown(text, &choices)),
791        }
792    }
793
794    /// The text [`Self::parse`] reads back as `setting` on this model: the
795    /// name of the first of [`Self::choices`] that is `setting`, or else
796    /// `off`, the level's word or `<n> tokens`.
797    pub fn name_of(&self, setting: Option<Reasoning>) -> String {
798        let choices = self.choices();
799        match choices.iter().find(|choice| choice.reasoning == setting) {
800            Some(choice) => choice.name.to_owned(),
801            None => match setting {
802                None => "default".to_owned(),
803                Some(Reasoning::Off) => "off".to_owned(),
804                Some(Reasoning::Effort(level)) => level.as_str().to_owned(),
805                Some(Reasoning::Budget { tokens }) => format!("{tokens} tokens"),
806            },
807        }
808    }
809
810    /// Whether `text` could name a setting on some model: `default`, `off`,
811    /// a level's word or `<n> tokens`. For checking a setting written before
812    /// its model is known; [`Self::parse`] reads it once it is.
813    pub fn reads(text: &str) -> bool {
814        read(text.trim()).is_some()
815    }
816
817    /// `text` refused, with the settings there are.
818    fn unknown(&self, text: &str, choices: &[ReasoningChoice]) -> UnknownReasoning {
819        UnknownReasoning {
820            name: text.to_owned(),
821            choices: choices.iter().map(|choice| choice.name).collect(),
822            budget: self.budget().cloned(),
823        }
824    }
825
826    /// Whether the model reasons at all.
827    pub fn supported(&self) -> bool {
828        !matches!(self, Self::None)
829    }
830
831    /// The effort levels the model takes: empty when it takes none (or does
832    /// not reason), `None` when the catalog does not know, in which case a
833    /// picker shows every level.
834    pub fn levels(&self) -> Option<&[Effort]> {
835        match self {
836            Self::None => Some(&[]),
837            Self::Unknown { .. } => None,
838            Self::Listed { levels, .. } => Some(levels),
839        }
840    }
841
842    /// The reasoning-token budgets the model takes, if the catalog lists
843    /// one. `None` both when it takes no budget and when the catalog does
844    /// not know; [`Self::levels`] tells the two apart.
845    pub fn budget(&self) -> Option<&RangeInclusive<u32>> {
846        match self {
847            Self::Listed { budget, .. } => budget.as_ref(),
848            _ => None,
849        }
850    }
851
852    /// Whether a request can turn the model's reasoning off: `Some(false)`
853    /// for a model that does not reason, `None` when the catalog does not
854    /// know.
855    pub fn can_disable(&self) -> Option<bool> {
856        match self {
857            Self::None => Some(false),
858            Self::Unknown { .. } => None,
859            Self::Listed { can_disable, .. } => Some(*can_disable),
860        }
861    }
862
863    /// The effort the model uses when a request names none, if documented.
864    pub fn default_effort(&self) -> Option<Effort> {
865        match self {
866            Self::None => None,
867            Self::Unknown { default } | Self::Listed { default, .. } => *default,
868        }
869    }
870
871    /// Why the model cannot take `reasoning`, or `None` when it can or the
872    /// catalog does not know ([`Self::Unknown`]).
873    pub fn refusal(&self, reasoning: &Reasoning) -> Option<String> {
874        let (levels, budget, can_disable) = match self {
875            Self::None => {
876                return (!matches!(reasoning, Reasoning::Off))
877                    .then(|| "the model does not reason".to_owned());
878            }
879            Self::Unknown { .. } => return None,
880            Self::Listed {
881                levels,
882                budget,
883                can_disable,
884                ..
885            } => (levels, budget, *can_disable),
886        };
887        match reasoning {
888            Reasoning::Off if can_disable => None,
889            Reasoning::Off => Some("reasoning cannot be turned off on this model".to_owned()),
890            Reasoning::Effort(effort) if levels.contains(effort) => None,
891            Reasoning::Effort(_) if levels.is_empty() && budget.is_some() => {
892                Some("the model takes a reasoning budget, not an effort level".to_owned())
893            }
894            Reasoning::Effort(_) if levels.is_empty() => {
895                Some("the model takes no effort level".to_owned())
896            }
897            Reasoning::Effort(effort) => Some(format!(
898                "the model has no `{}` effort level",
899                effort.as_str()
900            )),
901            Reasoning::Budget { tokens } => match budget {
902                Some(range) if range.contains(tokens) => None,
903                Some(range) => Some(format!(
904                    "the model takes a reasoning budget from {} to {} tokens",
905                    range.start(),
906                    range.end()
907                )),
908                None if levels.is_empty() => Some("the model takes no reasoning budget".to_owned()),
909                None => Some("the model takes an effort level, not a reasoning budget".to_owned()),
910            },
911        }
912    }
913}
914
915/// The setting `text` spells whatever the model: `Some(None)` for
916/// `default`, else `off`, a level's word or `<n> tokens`.
917fn read(text: &str) -> Option<Option<Reasoning>> {
918    let reasoning = match text {
919        "default" => return Some(None),
920        "off" => Reasoning::Off,
921        _ => match text.strip_suffix(" tokens") {
922            Some(tokens) => Reasoning::Budget {
923                tokens: tokens.trim().parse().ok()?,
924            },
925            None => Reasoning::Effort(Effort::named(text)?),
926        },
927    };
928    Some(Some(reasoning))
929}
930
931impl CacheSupport {
932    /// Why the model cannot honour `cache`, or `None` when it can or the
933    /// catalog does not know.
934    pub fn refusal(&self, cache: &CacheRetention) -> Option<String> {
935        (!self.retention.is_empty() && !self.retention.contains(cache)).then(|| {
936            format!(
937                "the model does not honour `{}` cache retention",
938                retention_word(cache)
939            )
940        })
941    }
942}
943
944/// The lower-case word `cache` serializes as.
945pub(super) fn retention_word(cache: &CacheRetention) -> &'static str {
946    match cache {
947        CacheRetention::None => "none",
948        CacheRetention::Short => "short",
949        CacheRetention::Long => "long",
950    }
951}