haest_core/provider/resolve.rs
1//! Resolving a `provider:model` spec to the provider that serves it.
2
3use std::fmt;
4
5use super::{NO_RESPONSE, ProviderEvent, ProviderRef, ProviderRequest, final_message};
6use crate::{
7 error::BoxError,
8 messages::{AssistantMessage, StopReason},
9};
10
11/// A spec resolved to the provider that serves it and the provider's model id.
12#[derive(Clone)]
13pub struct ResolvedModel {
14 provider: ProviderRef,
15 model: String,
16}
17
18impl ResolvedModel {
19 /// `model` on `provider`: the provider itself, or an `Arc` of one the
20 /// resolver keeps.
21 pub fn new(provider: impl Into<ProviderRef>, model: impl Into<String>) -> Self {
22 Self {
23 provider: provider.into(),
24 model: model.into(),
25 }
26 }
27
28 /// The provider that serves the spec.
29 pub fn provider(&self) -> &ProviderRef {
30 &self.provider
31 }
32
33 /// The id that provider knows the model by (what
34 /// [`ProviderRequest::model`](super::ProviderRequest::model) gets).
35 pub fn model(&self) -> &str {
36 &self.model
37 }
38
39 /// This model's whole answer to `req`, for a call outside the loop (a
40 /// title, a one-shot question). The request goes to this model: its
41 /// `model` is set to [`model`](Self::model).
42 ///
43 /// It never fails: an API or network error is an answer with
44 /// [`StopReason::Error`](crate::StopReason::Error) and the reason in
45 /// `error_message`, as a provider sends it; so is a stream that ends
46 /// without its answer.
47 ///
48 /// ```
49 /// use haest_core::{
50 /// AssistantMessage, AssistantPart, Message, Provider, ProviderRequest, ProviderStream,
51 /// ResolvedModel, answer_stream,
52 /// };
53 ///
54 /// /// Names everything "Tides".
55 /// struct Titler;
56 ///
57 /// impl Provider for Titler {
58 /// fn id(&self) -> &str {
59 /// "titler"
60 /// }
61 /// fn stream(&self, req: ProviderRequest) -> ProviderStream {
62 /// let mut answer = AssistantMessage::start(self.id(), &req.model);
63 /// answer_stream(|_deltas| async move {
64 /// answer.content.push(AssistantPart::Text { text: "Tides".into() });
65 /// answer
66 /// })
67 /// }
68 /// }
69 ///
70 /// # #[tokio::main(flavor = "current_thread")]
71 /// # async fn main() {
72 /// let titles = ResolvedModel::new(Titler, "titles-1");
73 /// let req = ProviderRequest::new(titles.model(), vec![Message::user("A title for this?")]);
74 /// let answer = titles.complete(req).await;
75 /// assert_eq!((answer.text().as_str(), answer.model.as_str()), ("Tides", "titles-1"));
76 /// # }
77 /// ```
78 pub async fn complete(&self, req: ProviderRequest) -> AssistantMessage {
79 self.complete_streaming(req, |_| {}).await
80 }
81
82 /// The same, handing each event before the answer (text, thinking, a
83 /// tool call starting) to `on_delta` as it arrives.
84 pub async fn complete_streaming(
85 &self,
86 mut req: ProviderRequest,
87 on_delta: impl FnMut(ProviderEvent),
88 ) -> AssistantMessage {
89 req.model.clone_from(&self.model);
90 let answer = final_message(self.provider.stream(req), on_delta).await;
91 answer.unwrap_or_else(|| {
92 let mut m = AssistantMessage::start(self.provider.id(), &self.model);
93 m.stop_reason = StopReason::Error;
94 m.error_message = Some(NO_RESPONSE.into());
95 m
96 })
97 }
98}
99
100/// Always this model, whatever the spec: a host with one model resolves
101/// every spec to it (`SharedDeps::new(ResolvedModel::new(provider, "m"), ..)`).
102impl ModelResolver for ResolvedModel {
103 fn resolve(&self, _spec: &str) -> Result<ResolvedModel, ModelError> {
104 Ok(self.clone())
105 }
106}
107
108/// One provider serves every spec: the model is the part after the first
109/// colon ([`parse_model_spec`]), and the provider part is not checked
110/// (`SharedDeps::new(ProviderRef::new(provider), ..)`).
111impl ModelResolver for ProviderRef {
112 fn resolve(&self, spec: &str) -> Result<ResolvedModel, ModelError> {
113 let (_, model) = parse_model_spec(spec)?;
114 Ok(ResolvedModel::new(self.clone(), model))
115 }
116}
117
118impl fmt::Debug for ResolvedModel {
119 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
120 f.debug_struct("ResolvedModel")
121 .field("provider", &self.provider.id())
122 .field("model", &self.model)
123 .finish()
124 }
125}
126
127/// Why a model spec cannot be served: what [`ModelResolver::resolve`] and
128/// [`parse_model_spec`] refuse. The loop shows it to the human with its
129/// causes ([`report`](crate::error::report)).
130///
131/// The variant says what to do: [`BadSpec`](Self::BadSpec) and
132/// [`UnknownProvider`](Self::UnknownProvider), pick another model;
133/// [`MissingKey`](Self::MissingKey), hand in that key;
134/// [`Unavailable`](Self::Unavailable), fix the provider's configuration
135/// (its source says what is wrong).
136#[derive(Debug, thiserror::Error)]
137#[non_exhaustive]
138pub enum ModelError {
139 /// The spec is not `<provider>:<model>`.
140 #[error(
141 "model \"{spec}\" must be \"<provider>:<model>\", e.g. openrouter:anthropic/claude-sonnet-5"
142 )]
143 BadSpec {
144 /// The spec, as written.
145 spec: String,
146 },
147 /// No provider goes by the spec's provider part.
148 #[error("unknown provider \"{provider}\". Known: {}", known.join(", "))]
149 UnknownProvider {
150 /// The provider part, as written.
151 provider: String,
152 /// The providers there are.
153 known: Vec<String>,
154 },
155 /// The provider needs a key the host's [`KeySource`](crate::KeySource)
156 /// does not have.
157 #[error("provider \"{provider}\" needs {key}, and the host has none")]
158 MissingKey {
159 /// The provider.
160 provider: String,
161 /// The name the host was asked for (`OPENROUTER_API_KEY`).
162 key: String,
163 },
164 /// The provider is known but cannot be built: its configuration is bad
165 /// (a providers.json entry, say). Only specs of that provider fail.
166 #[error("provider \"{provider}\" cannot be used")]
167 Unavailable {
168 /// The provider.
169 provider: String,
170 /// What is wrong with it: the resolver's own reason.
171 #[source]
172 source: BoxError,
173 },
174}
175
176/// Turns a `provider:model` spec into a live provider. The loop asks it before
177/// every model call, so a model switch mid-conversation takes effect at once.
178///
179/// Any `Fn(&str) -> Result<ResolvedModel, ModelError>` is one; `haest-providers`'
180/// registry is the full one.
181///
182/// # Examples
183///
184/// ```
185/// use haest_core::{
186/// ModelError, ModelResolver, Provider, ProviderRef, ResolvedModel, provider::parse_model_spec,
187/// };
188/// # use haest_core::{ProviderRequest, ProviderStream};
189/// # struct Echo;
190/// # impl Provider for Echo {
191/// # fn id(&self) -> &str { "echo" }
192/// # fn stream(&self, _: ProviderRequest) -> ProviderStream { unimplemented!() }
193/// # }
194///
195/// # fn main() -> Result<(), ModelError> {
196/// let echo = ProviderRef::new(Echo);
197/// let resolver = move |spec: &str| match parse_model_spec(spec)? {
198/// ("echo", model) => Ok(ResolvedModel::new(echo.clone(), model)),
199/// (other, _) => Err(ModelError::UnknownProvider {
200/// provider: other.into(),
201/// known: vec!["echo".into()],
202/// }),
203/// };
204///
205/// assert_eq!(resolver.resolve("echo:echo-1")?.model(), "echo-1");
206/// assert!(matches!(
207/// resolver.resolve("acme:big"),
208/// Err(ModelError::UnknownProvider { provider, .. }) if provider == "acme"
209/// ));
210/// # Ok(())
211/// # }
212/// ```
213pub trait ModelResolver: Send + Sync {
214 /// The provider and model id for `spec`.
215 ///
216 /// # Errors
217 ///
218 /// [`ModelError`]: a bad spec, an unknown provider, a missing key, a
219 /// provider that cannot be built.
220 fn resolve(&self, spec: &str) -> Result<ResolvedModel, ModelError>;
221}
222
223impl<F> ModelResolver for F
224where
225 F: Fn(&str) -> Result<ResolvedModel, ModelError> + Send + Sync,
226{
227 fn resolve(&self, spec: &str) -> Result<ResolvedModel, ModelError> {
228 self(spec)
229 }
230}
231
232crate::plug_ref! {
233 /// A [`ModelResolver`], shared: what [`SharedDeps::models`](crate::SharedDeps::models)
234 /// holds. Built from the resolver itself (a closure, `haest-providers`'
235 /// registry), or from an `Arc` of one.
236 pub struct ModelResolverRef(dyn ModelResolver);
237}
238
239/// Splits a model spec into provider and model id at the FIRST colon:
240/// `openrouter:anthropic/claude-sonnet-5` -> ("openrouter", "anthropic/claude-sonnet-5"),
241/// `openrouter:x/y:free` -> ("openrouter", "x/y:free").
242///
243/// # Errors
244///
245/// [`ModelError::BadSpec`] when there is no colon or nothing before it.
246pub fn parse_model_spec(spec: &str) -> Result<(&str, &str), ModelError> {
247 match spec.find(':') {
248 Some(i) if i > 0 => Ok((&spec[..i], &spec[i + 1..])),
249 _ => Err(ModelError::BadSpec { spec: spec.into() }),
250 }
251}