Skip to main content

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}