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}