Skip to main content

rig_core/driver/
dyn_model.rs

1//! A model erased to its operation: what a consumer stores when it holds
2//! any model of one operation without naming its wire and transport. A
3//! [`DynModel`] runs the same driver as the [`Model`] it was made from.
4
5use std::fmt;
6use std::sync::Arc;
7
8use super::{Model, Sending, Transport};
9use crate::error::ProviderError;
10use crate::streaming::Streamed;
11use crate::wasm_compat::{WasmCompatSend, WasmCompatSync};
12use crate::wire::{Capabilities, Descriptor, Mode, Operation, Wire};
13
14/// Object-safe mirror of the calls a [`Model`] answers, with the wire and
15/// transport fixed. Private: the only way to reach it is through
16/// [`DynModel`], which re-exposes the public surface.
17pub(crate) trait ErasedModel<Op: Operation>: WasmCompatSend + WasmCompatSync {
18    fn describe(&self) -> Descriptor<'_>;
19
20    fn open(
21        &self,
22        request: Op::Request,
23        mode: Mode,
24        sending: Sending,
25    ) -> Result<Streamed<Op>, ProviderError>;
26
27    fn dry_run(&self, request: Op::Request) -> Result<(), ProviderError>;
28}
29
30impl<W, T> ErasedModel<W::Op> for Model<W, T>
31where
32    W: Wire,
33    T: Transport<W>,
34{
35    fn describe(&self) -> Descriptor<'_> {
36        self.wire.describe()
37    }
38
39    fn open(
40        &self,
41        request: <W::Op as Operation>::Request,
42        mode: Mode,
43        sending: Sending,
44    ) -> Result<Streamed<W::Op>, ProviderError> {
45        Model::open(self, request, mode, sending)
46    }
47
48    fn dry_run(&self, request: <W::Op as Operation>::Request) -> Result<(), ProviderError> {
49        Model::dry_run(self, request)
50    }
51}
52
53/// A model of one operation with its wire and transport erased. Clones share
54/// the model. Built with [`Model::erase`] or `From<Model<W, T>>`, so a
55/// consumer takes `impl Into<DynModel<Op>>` and accepts either.
56///
57/// Every call runs the driver the concrete model runs: spans, request ids,
58/// the operation's fold and error enrichment are the same.
59///
60/// A model used by one consumer is passed as is; a model shared by several
61/// is erased once and the handle is cloned. A model a handler table serves
62/// is a `ModelHandle` in the agent runtime instead: its calls are
63/// dispatched, recorded and observed there.
64///
65/// ```no_run
66/// use rig_core::embeddings::EmbeddingsBuilder;
67/// use rig_core::vector_store::in_memory_store::InMemoryVectorStore;
68/// use rig_core::{Model, providers::openai::{self, OpenAIConfig}};
69///
70/// # async fn example(http: rig_core::http_client::DynHttpClient) -> Result<(), Box<dyn std::error::Error>> {
71/// let model = OpenAIConfig::from_env()?.connect(http).embedding(openai::TEXT_EMBEDDING_3_SMALL, None).erase();
72/// let embeddings = EmbeddingsBuilder::new(model.clone())
73///     .documents(["a document".to_owned()])?
74///     .build()
75///     .await?;
76/// let index = InMemoryVectorStore::from_documents(embeddings).index(model);
77/// # let _ = index;
78/// # Ok(())
79/// # }
80/// ```
81pub struct DynModel<Op: Operation> {
82    inner: Arc<dyn ErasedModel<Op>>,
83}
84
85impl<W, T> Model<W, T>
86where
87    W: Wire,
88    T: Transport<W>,
89{
90    /// Erase this model to its operation.
91    pub fn erase(self) -> DynModel<W::Op> {
92        DynModel {
93            inner: Arc::new(self),
94        }
95    }
96}
97
98impl<W, T> From<Model<W, T>> for DynModel<W::Op>
99where
100    W: Wire,
101    T: Transport<W>,
102{
103    fn from(model: Model<W, T>) -> Self {
104        model.erase()
105    }
106}
107
108impl<Op: Operation> Clone for DynModel<Op> {
109    fn clone(&self) -> Self {
110        Self {
111            inner: Arc::clone(&self.inner),
112        }
113    }
114}
115
116impl<Op: Operation> fmt::Debug for DynModel<Op> {
117    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
118        f.debug_struct("DynModel")
119            .field("name", &self.name())
120            .field("id", &self.id())
121            .finish()
122    }
123}
124
125impl<Op: Operation> DynModel<Op> {
126    /// The wire's provider descriptor name (`"anthropic"`).
127    pub fn name(&self) -> &str {
128        self.inner.describe().name
129    }
130
131    /// The model id the wire addresses, when the operation addresses one.
132    pub fn id(&self) -> Option<&str> {
133        self.inner.describe().model
134    }
135
136    /// The catalog facts of the model the wire addresses: the spec it was
137    /// connected to, else the catalog's entry for its id. `None` for an
138    /// operation that addresses no model, or a model the catalog does not
139    /// list.
140    pub fn spec(&self) -> Option<&crate::catalog::ModelSpec> {
141        self.inner.describe().spec()
142    }
143
144    /// What a runtime accounts for about this model.
145    pub fn capabilities(&self) -> Capabilities {
146        self.inner.describe().capabilities
147    }
148
149    /// Send `request` and fold the whole reply into the operation's
150    /// response; [`Model::call`] with the model erased. The call owns what
151    /// it sends, so it can be spawned.
152    pub fn call(
153        &self,
154        request: impl Into<Op::Request>,
155    ) -> impl Future<Output = Result<Op::Response, ProviderError>> + WasmCompatSend + 'static {
156        self.finished(request.into(), Sending::default())
157    }
158
159    /// The call opens when first polled, as [`Model::call`] does.
160    pub(crate) fn finished(
161        &self,
162        request: Op::Request,
163        sending: Sending,
164    ) -> impl Future<Output = Result<Op::Response, ProviderError>> + WasmCompatSend + 'static {
165        let inner = self.inner.clone();
166        async move { inner.open(request, Mode::Unary, sending)?.finish().await }
167    }
168
169    /// Open a streamed reply; [`Model::stream`] with the model erased.
170    pub fn stream(&self, request: impl Into<Op::Request>) -> Result<Streamed<Op>, ProviderError> {
171        self.opened(request.into(), Sending::default())
172    }
173
174    /// Open a streamed reply, sent as `sending` says.
175    pub(crate) fn opened(
176        &self,
177        request: Op::Request,
178        sending: Sending,
179    ) -> Result<Streamed<Op>, ProviderError> {
180        self.inner.open(request, Mode::Streaming, sending)
181    }
182}
183
184impl DynModel<crate::operation::Completion> {
185    /// Every option of `request` this model would refuse, with nothing
186    /// sent; [`Model::check`] with the model erased.
187    ///
188    /// ```no_run
189    /// use rig_core::catalog::Catalog;
190    /// use rig_core::completion::{CheckError, CompletionRequest, Effort};
191    /// use rig_core::providers::registry::ConnectOptions;
192    ///
193    /// let model = Catalog::builtin().connect_with("openai/gpt-6-sol", ConnectOptions::new())?;
194    /// let request = CompletionRequest::new("hi")
195    ///     .temperature(0.2)
196    ///     .reasoning(Effort::High);
197    /// if let Err(CheckError::Unsupported(refused)) = model.check(&request) {
198    ///     for refusal in refused {
199    ///         println!("{refusal}");
200    ///     }
201    /// }
202    /// # Ok::<(), Box<dyn std::error::Error>>(())
203    /// ```
204    ///
205    /// # Errors
206    ///
207    /// As [`Model::check`].
208    pub fn check(
209        &self,
210        request: &crate::completion::CompletionRequest,
211    ) -> Result<(), crate::completion::CheckError> {
212        super::check_with(request, |request| self.inner.dry_run(request))
213    }
214}
215
216#[cfg(test)]
217mod tests;