Skip to main content

haest_core/
catalog.rs

1//! The shapes of a model catalog row: who makes a model and which one it is,
2//! what it takes as input, how it reasons, what it costs and how big its
3//! context is. The rows themselves live
4//! with the providers (`haest-providers`' `Catalog`, bundled from a JSON file);
5//! a host may bring its own rows in the same shape.
6//!
7//! The loop never reads a catalog directly. It asks the host's [`ModelFacts`]
8//! ([`SharedDeps::facts`](crate::SharedDeps::facts)), and the answers come from
9//! these rows: the loop drops input a model cannot take ([`crate::media`]),
10//! fits the reasoning level and caps the turn, and a provider adapter books a
11//! cost from [`ModelPricing`].
12//!
13//! # Examples
14//!
15//! A row as the catalog file writes it (camelCase keys):
16//!
17//! ```
18//! use haest_core::{InputModality, catalog::ModelInfo};
19//!
20//! let row: ModelInfo = serde_json::from_str(r#"{
21//!     "spec": "openrouter:example/model-1",
22//!     "label": "Example Model 1",
23//!     "input": ["text", "image"],
24//!     "contextWindow": 200000,
25//!     "reasoning": { "mandatory": false, "efforts": ["low", "high"] },
26//!     "pricing": { "input": 3.0, "cachedInput": 0.3, "output": 15.0 }
27//! }"#)?;
28//!
29//! assert!(row.input.contains(&InputModality::Image));
30//! assert_eq!(row.pricing.map(|p| p.cache_write), Some(None));
31//! # Ok::<(), serde_json::Error>(())
32//! ```
33
34use std::collections::HashSet;
35
36use serde::{Deserialize, Serialize};
37
38/// PLUG POINT: what the host knows about a model spec
39/// ([`Agent::model_spec`](crate::Agent::model_spec)), set on
40/// [`SharedDeps::facts`](crate::SharedDeps::facts). Asked again before every
41/// model call, so the answers may follow the model. Every method defaults to
42/// "unknown"; [`NoFacts`] knows nothing.
43///
44/// Facts only: what the host hears about (a message, withheld media, a
45/// fitted effort) goes to [`AgentHooks`](crate::AgentHooks), and its caps
46/// per model are a [`TurnCapsSource`](crate::caps::TurnCapsSource).
47pub trait ModelFacts: Send + Sync {
48    /// The spec's whole catalog row; None = unknown. The other methods
49    /// answer from it unless the host answers them itself, so a host with a
50    /// catalog implements this one.
51    fn model_info(&self, _spec: &str) -> Option<ModelInfo> {
52        None
53    }
54
55    /// What the spec takes as input; None = unknown, media sent untouched.
56    /// Media a model does not take is replaced by a note before the call.
57    fn input_modalities(&self, spec: &str) -> Option<HashSet<InputModality>> {
58        self.model_info(spec).map(|m| m.input.into_iter().collect())
59    }
60
61    /// The spec's reasoning row (which efforts it takes); None = unknown,
62    /// effort sent as asked.
63    fn reasoning(&self, spec: &str) -> Option<Reasoning> {
64        self.model_info(spec)?.reasoning
65    }
66}
67
68crate::plug_ref! {
69    /// A [`ModelFacts`], shared: what [`SharedDeps::facts`](crate::SharedDeps::facts) holds.
70    pub struct ModelFactsRef(dyn ModelFacts);
71}
72
73/// Facts about no model: every answer "unknown". [`AgentDeps::new`](crate::AgentDeps::new)'s default.
74#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
75pub struct NoFacts;
76
77impl ModelFacts for NoFacts {}
78
79crate::word_enum! {
80    /// A kind of input a model accepts, in OpenRouter's names (`file` is a PDF).
81    #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
82    #[non_exhaustive]
83    pub enum InputModality ("input modality") {
84        /// Text.
85        Text = "text",
86        /// An image.
87        Image = "image",
88        /// A document: a PDF.
89        File = "file",
90        /// Audio.
91        Audio = "audio",
92        /// Video.
93        Video = "video",
94    }
95}
96
97crate::word_enum! {
98/// A reasoning level in OpenRouter's vocabulary (`reasoning.supported_efforts`).
99///
100/// Wider than haest's own [`Effort`](crate::Effort): `none` and `minimal` have
101/// no haest name; each of haest's levels but `off` has one of the same name.
102#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
103#[non_exhaustive]
104pub enum OpenRouterEffort ("reasoning effort") {
105    /// Reasoning off.
106    None = "none",
107    /// Less than `low`; haest never asks for it.
108    Minimal = "minimal",
109    /// `low`.
110    Low = "low",
111    /// `medium`.
112    Medium = "medium",
113    /// `high`.
114    High = "high",
115    /// `xhigh`.
116    Xhigh = "xhigh",
117    /// `max`.
118    Max = "max",
119}
120}
121
122/// How a model reasons: whether it can stop, and the levels it accepts.
123///
124/// Built with [`new`](Self::new) and [`with_mandatory`](Self::with_mandatory),
125/// so a part it gains later breaks no host; its fields read as they are.
126///
127/// ```
128/// use haest_core::catalog::{OpenRouterEffort, Reasoning};
129///
130/// let r = Reasoning::new([OpenRouterEffort::Low, OpenRouterEffort::High]).with_mandatory(true);
131/// assert!(r.mandatory);
132/// assert_eq!(r.efforts.len(), 2);
133/// ```
134#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
135#[non_exhaustive]
136pub struct Reasoning {
137    /// The model cannot turn reasoning off: `enabled: false` is a 400, not a cheaper turn.
138    pub mandatory: bool,
139    /// The levels the model accepts, in any order.
140    pub efforts: Vec<OpenRouterEffort>,
141}
142
143impl Reasoning {
144    /// A model that accepts `efforts` and may turn reasoning off.
145    pub fn new(efforts: impl IntoIterator<Item = OpenRouterEffort>) -> Self {
146        Self {
147            mandatory: false,
148            efforts: efforts.into_iter().collect(),
149        }
150    }
151
152    /// Whether the model cannot turn reasoning off.
153    #[must_use]
154    pub fn with_mandatory(mut self, mandatory: bool) -> Self {
155        self.mandatory = mandatory;
156        self
157    }
158}
159
160/// A model's price in USD per 1M tokens, for a provider whose API returns no
161/// cost of its own ([`book_priced_cost`](crate::provider::book_priced_cost)).
162///
163/// Built with [`new`](Self::new) and [`with_cache_write`](Self::with_cache_write),
164/// so a price it gains later (for reasoning, for a search) breaks no host; its
165/// fields read as they are.
166///
167/// ```
168/// use haest_core::catalog::ModelPricing;
169///
170/// // $3 in, $0.30 from the cache, $15 out; a cache write costs $3.75.
171/// let price = ModelPricing::new(3.0, 0.3, 15.0).with_cache_write(3.75);
172/// assert_eq!(price.cache_write, Some(3.75));
173/// ```
174#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
175#[serde(rename_all = "camelCase")]
176#[non_exhaustive]
177pub struct ModelPricing {
178    /// Uncached input tokens.
179    pub input: f64,
180    /// Input tokens read from the provider's prompt cache.
181    pub cached_input: f64,
182    /// Output tokens.
183    pub output: f64,
184    /// Input tokens written to the prompt cache; absent = billed as `input`.
185    #[serde(default, skip_serializing_if = "Option::is_none")]
186    pub cache_write: Option<f64>,
187}
188
189impl ModelPricing {
190    /// `input`, `cached_input` and `output` USD per 1M tokens, in that
191    /// order; a cache write is billed as input.
192    pub const fn new(input: f64, cached_input: f64, output: f64) -> Self {
193        Self {
194            input,
195            cached_input,
196            output,
197            cache_write: None,
198        }
199    }
200
201    /// Cache writes at `usd` per 1M tokens, not as input.
202    #[must_use]
203    pub const fn with_cache_write(mut self, usd: f64) -> Self {
204        self.cache_write = Some(usd);
205        self
206    }
207}
208
209/// One model as a catalog lists it: its spec, who makes it and which one it
210/// is, what it takes, and what is known about its reasoning and price.
211///
212/// Built with [`new`](Self::new) and the `with_*` setters, so a part it gains
213/// later breaks no host; its fields read as they are.
214///
215/// `family`, `tier` and `generation` are written in the catalog, never read
216/// out of the spec: model ids follow no shared pattern (`claude-opus-5-5`,
217/// `gpt-6.1-sol-pro`, `qwen3.8-max-0902`).
218///
219/// ```
220/// use haest_core::{
221///     InputModality,
222///     catalog::{ModelInfo, ModelPricing},
223/// };
224///
225/// let row = ModelInfo::new("openrouter:example/model-1-flash", 200_000)
226///     .with_label("Example Model 1 Flash")
227///     .with_family("example")
228///     .with_tier("flash")
229///     .with_generation(1.0)
230///     .with_input([InputModality::Text, InputModality::Image])
231///     .with_pricing(ModelPricing::new(3.0, 0.3, 15.0));
232/// assert_eq!(row.label, "Example Model 1 Flash");
233/// assert_eq!(row.reasoning, None, "unknown: the effort is sent as asked");
234/// ```
235#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
236#[serde(rename_all = "camelCase")]
237#[non_exhaustive]
238pub struct ModelInfo {
239    /// `provider:model`, exactly what a model spec takes.
240    pub spec: String,
241    /// The name a picker shows.
242    pub label: String,
243    /// Who makes the model, as OpenRouter names its author (`anthropic`,
244    /// `openai`, `google`, `x-ai`); absent = unknown.
245    #[serde(default, skip_serializing_if = "Option::is_none")]
246    pub family: Option<String>,
247    /// Which model of its family and generation it is: the words its label
248    /// adds, lowercase and joined by `-` (`opus`, `flash`, `sol-pro`);
249    /// absent = the label adds none, or unknown.
250    #[serde(default, skip_serializing_if = "Option::is_none")]
251    pub tier: Option<String>,
252    /// The version its label carries, as a number (`5.5` for Claude Opus 5.5,
253    /// `4` for Gemini 4 Argon); absent = unknown. It compares within one
254    /// family only, and a float has no `5.10` after `5.9`.
255    #[serde(default, skip_serializing_if = "Option::is_none")]
256    pub generation: Option<f64>,
257    /// What the model accepts as input.
258    pub input: Vec<InputModality>,
259    /// Tokens the model actually serves (the best endpoint's cap, not the advertised one).
260    pub context_window: u64,
261    /// Absent = unknown: haest sends the effort as asked.
262    #[serde(default, skip_serializing_if = "Option::is_none")]
263    pub reasoning: Option<Reasoning>,
264    /// Absent = unpriced: haest books the provider's own cost, or none. Never guessed.
265    #[serde(default, skip_serializing_if = "Option::is_none")]
266    pub pricing: Option<ModelPricing>,
267}
268
269impl ModelInfo {
270    /// The model `spec` serving `context_window` tokens: labelled with its
271    /// spec, taking text only, its family, tier, generation and reasoning
272    /// unknown, and unpriced.
273    pub fn new(spec: impl Into<String>, context_window: u64) -> Self {
274        let spec = spec.into();
275        Self {
276            label: spec.clone(),
277            spec,
278            family: None,
279            tier: None,
280            generation: None,
281            input: vec![InputModality::Text],
282            context_window,
283            reasoning: None,
284            pricing: None,
285        }
286    }
287
288    /// The name a picker shows.
289    #[must_use]
290    pub fn with_label(mut self, label: impl Into<String>) -> Self {
291        self.label = label.into();
292        self
293    }
294
295    /// Who makes the model ([`family`](Self::family)).
296    #[must_use]
297    pub fn with_family(mut self, family: impl Into<String>) -> Self {
298        self.family = Some(family.into());
299        self
300    }
301
302    /// Which model of its family it is ([`tier`](Self::tier)).
303    #[must_use]
304    pub fn with_tier(mut self, tier: impl Into<String>) -> Self {
305        self.tier = Some(tier.into());
306        self
307    }
308
309    /// The version its label carries ([`generation`](Self::generation)).
310    #[must_use]
311    pub fn with_generation(mut self, generation: f64) -> Self {
312        self.generation = Some(generation);
313        self
314    }
315
316    /// What the model accepts as input, in place of text only.
317    #[must_use]
318    pub fn with_input(mut self, input: impl IntoIterator<Item = InputModality>) -> Self {
319        self.input = input.into_iter().collect();
320        self
321    }
322
323    /// How the model reasons.
324    #[must_use]
325    pub fn with_reasoning(mut self, reasoning: Reasoning) -> Self {
326        self.reasoning = Some(reasoning);
327        self
328    }
329
330    /// What the model costs.
331    #[must_use]
332    pub fn with_pricing(mut self, pricing: ModelPricing) -> Self {
333        self.pricing = Some(pricing);
334        self
335    }
336}
337
338/// A labelled group of models, as a picker shows them (by vendor, say).
339///
340/// Built with [`new`](Self::new), so a part it gains later breaks no host.
341#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
342#[non_exhaustive]
343pub struct ModelGroup {
344    /// The group's heading.
345    pub label: String,
346    /// The group's models, in the order a picker lists them.
347    pub models: Vec<ModelInfo>,
348}
349
350impl ModelGroup {
351    /// The group `label` of `models`, in the order a picker lists them.
352    pub fn new(label: impl Into<String>, models: impl IntoIterator<Item = ModelInfo>) -> Self {
353        Self {
354            label: label.into(),
355            models: models.into_iter().collect(),
356        }
357    }
358}
359
360#[cfg(test)]
361mod tests {
362    use super::*;
363
364    /// A host that knows its rows and nothing else.
365    struct Rows;
366    impl ModelFacts for Rows {
367        fn model_info(&self, spec: &str) -> Option<ModelInfo> {
368            (spec == "local:m").then(|| {
369                ModelInfo::new(spec, 8_000)
370                    .with_input([InputModality::Text, InputModality::Image])
371                    .with_reasoning(Reasoning::new([OpenRouterEffort::High]).with_mandatory(true))
372            })
373        }
374    }
375
376    #[test]
377    fn a_host_with_rows_answers_inputs_and_reasoning_from_them() {
378        let inputs = Rows.input_modalities("local:m").unwrap();
379        assert!(inputs.contains(&InputModality::Image));
380        assert!(Rows.reasoning("local:m").unwrap().mandatory);
381        assert_eq!(Rows.input_modalities("local:other"), None);
382        assert_eq!(Rows.reasoning("local:other"), None);
383    }
384}