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;