Skip to main content

rig_agent/
handlers.rs

1#![forbid(unsafe_code)]
2
3//! The handler table an agent dispatches its effects through, served inline.
4//!
5//! [`Handlers`] maps keys to [`ErasedHandler`]s. A dispatch looks its handler
6//! up and runs it in the caller's own future or stream, recorded by the
7//! table's [`Recorder`] when one is installed; dropping the future or stream
8//! cancels it. A handler dispatches nested effects through the [`Handlers`]
9//! it is served with ([`Handlers::serving`]), which records them under its
10//! own dispatch.
11//!
12//! ```
13//! use rig_agent::handlers::{Handlers, ModelHandle};
14//! use rig_core::effect::HandlerKey;
15//! let handlers = Handlers::default();
16//! let model: Result<ModelHandle, _> = handlers.handle(&HandlerKey::from("model"));
17//! assert!(model.is_err());
18//! ```
19
20use std::{
21    collections::{BTreeMap, VecDeque},
22    marker::PhantomData,
23    sync::{
24        Arc, PoisonError, RwLock,
25        atomic::{AtomicU64, Ordering},
26    },
27    task::Poll,
28};
29
30use futures::StreamExt;
31use serde::de::DeserializeOwned;
32use tracing::Instrument;
33
34use rig_core::{
35    completion::{CompletionRequest, ModelRef, ProviderCapabilities},
36    effect::{
37        Answered, CustomEffect, EffectFamily, EffectId, EffectKind, Family, FamilyDescriptor,
38        HandlerDescriptor, HandlerKey, Key, RetrieveQuery, RetrievedDocuments, family,
39    },
40    error::{ErrorKind, ErrorReport},
41    serve::{Dispatch, DispatchContext, ErasedHandler, Recorder, Serve, catch_panics},
42    streaming::{CompletionStream, Relayed, StreamEvents},
43    tool::{PublishedContext, ToolContext, ToolResult},
44    vector_store::{
45        VectorSearchIdResult, VectorSearchResult,
46        request::{Filter, VectorSearchRequest},
47    },
48    wasm_compat::WasmCompatSend,
49};
50
51/// A keyed table of effect handlers, dispatched inline. Clones share the
52/// table, its effect ids and its recorder.
53///
54/// A dispatch runs in the caller's future, so the caller decides what runs
55/// at once, and dropping the future cancels the dispatch. A handler that
56/// must bound or serialize its calls does it around its own work, as below.
57/// A dispatch looks its handler up once, as it begins on its first polls,
58/// and runs on that handler to the end: registering a replacement or
59/// deregistering the key changes only dispatches that begin later, and a
60/// displaced handler is dropped once no running dispatch holds it. An
61/// agent's tool calls run on the registration its turn pinned, so a
62/// replacement reaches them from the next turn.
63///
64/// ```
65/// use std::sync::{Arc, atomic::{AtomicUsize, Ordering}};
66/// use rig_agent::handlers::Handlers;
67/// use rig_core::effect::{family, Answered, EffectKind, FamilyDescriptor, HandlerDescriptor};
68/// use rig_core::serve::{Dispatch, Reply, Serve};
69/// use tokio::sync::{Mutex, Semaphore};
70///
71/// fn describe(key: &str) -> HandlerDescriptor {
72///     let family = FamilyDescriptor::Custom { kind: "demo".into() };
73///     HandlerDescriptor { key: key.into(), family, layers: Vec::new() }
74/// }
75///
76/// /// At most two lookups run at once; the others wait for a permit.
77/// struct Lookup { permits: Semaphore, running: AtomicUsize, peak: Arc<AtomicUsize> }
78///
79/// impl Serve for Lookup {
80///     type Family = family::Dynamic;
81///     fn descriptor(&self) -> HandlerDescriptor { describe("lookup") }
82///     async fn serve(&self, _kind: EffectKind, _dispatch: Dispatch) -> Reply {
83///         let _permit = self.permits.acquire().await;
84///         let now = self.running.fetch_add(1, Ordering::SeqCst) + 1;
85///         self.peak.fetch_max(now, Ordering::SeqCst);
86///         tokio::task::yield_now().await;
87///         self.running.fetch_sub(1, Ordering::SeqCst);
88///         Reply::Outcome(Ok(Answered::Custom { payload: serde_json::Value::Null }))
89///     }
90/// }
91///
92/// /// A counter whose read and write must not interleave across calls.
93/// struct Counter { count: Mutex<u64> }
94///
95/// impl Serve for Counter {
96///     type Family = family::Dynamic;
97///     fn descriptor(&self) -> HandlerDescriptor { describe("counter") }
98///     async fn serve(&self, _kind: EffectKind, _dispatch: Dispatch) -> Reply {
99///         let mut count = self.count.lock().await;
100///         let next = *count + 1;
101///         tokio::task::yield_now().await;
102///         *count = next;
103///         Reply::Outcome(Ok(Answered::Custom { payload: next.into() }))
104///     }
105/// }
106///
107/// # #[tokio::main(flavor = "current_thread")]
108/// # async fn main() -> Result<(), rig_core::error::ErrorReport> {
109/// let handlers = Handlers::default();
110/// let peak = Arc::new(AtomicUsize::new(0));
111/// let lookup = Lookup { permits: Semaphore::new(2), running: AtomicUsize::new(0), peak: peak.clone() };
112/// handlers.register("lookup", lookup)?;
113/// handlers.register("counter", Counter { count: Mutex::new(0) })?;
114///
115/// let call = |key| {
116///     let kind = EffectKind::Custom { kind: "demo".into(), payload: serde_json::Value::Null };
117///     handlers.dispatch(key, kind)
118/// };
119/// let (lookup, counter) = ("lookup".into(), "counter".into());
120/// futures::future::try_join_all((0..6).map(|_| call(&lookup))).await?;
121/// assert_eq!(peak.load(Ordering::SeqCst), 2);
122///
123/// let counts = futures::future::try_join_all((0..3).map(|_| call(&counter))).await?;
124/// let counts: Vec<_> = counts.into_iter().map(|answer| match answer {
125///     Answered::Custom { payload } => payload,
126///     _ => serde_json::Value::Null,
127/// }).collect();
128/// assert_eq!(counts, [1, 2, 3]);
129/// # Ok(())
130/// # }
131/// ```
132#[derive(Clone, Default)]
133pub struct Handlers {
134    shared: Arc<Shared>,
135    /// The dispatch every dispatch made through this value descends from:
136    /// `None` for a host's or an agent's own table, the served dispatch for
137    /// the one a handler is served with.
138    parent: Option<EffectId>,
139}
140
141#[derive(Default)]
142struct Shared {
143    table: RwLock<Table>,
144    next_id: AtomicU64,
145}
146
147#[derive(Default)]
148struct Table {
149    handlers: BTreeMap<HandlerKey, (ErasedHandler, HandlerDescriptor)>,
150    recorder: Option<Arc<dyn Recorder + Send + Sync>>,
151}
152
153impl std::fmt::Debug for Handlers {
154    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
155        f.debug_struct("Handlers")
156            .field("keys", &self.keys())
157            .field("parent", &self.parent)
158            .finish_non_exhaustive()
159    }
160}
161
162impl Handlers {
163    fn read(&self) -> std::sync::RwLockReadGuard<'_, Table> {
164        self.shared
165            .table
166            .read()
167            .unwrap_or_else(PoisonError::into_inner)
168    }
169
170    fn write(&self) -> std::sync::RwLockWriteGuard<'_, Table> {
171        self.shared
172            .table
173            .write()
174            .unwrap_or_else(PoisonError::into_inner)
175    }
176
177    /// Register (or replace) the handler serving `key`. A replacement must
178    /// keep the key's family: a family change is refused with
179    /// `HandlerUnavailable` and the table is unchanged.
180    pub fn register(
181        &self,
182        key: impl Into<HandlerKey>,
183        handler: impl Serve + 'static,
184    ) -> Result<(), ErrorReport> {
185        self.register_erased(key, ErasedHandler::new(handler))
186    }
187
188    /// Register an already-erased handler.
189    pub fn register_erased(
190        &self,
191        key: impl Into<HandlerKey>,
192        handler: ErasedHandler,
193    ) -> Result<(), ErrorReport> {
194        let key = key.into();
195        // User code (the descriptor) runs outside the lock.
196        let described = handler.descriptor();
197        let descriptor = HandlerDescriptor {
198            key: key.clone(),
199            family: described.family,
200            layers: described.layers,
201        };
202        let mut table = self.write();
203        if let Some((_, current)) = table.handlers.get(&key) {
204            let (current, family) = (current.family.family(), descriptor.family.family());
205            if current != family {
206                return Err(ErrorReport::new(
207                    ErrorKind::HandlerUnavailable,
208                    format!(
209                        "key `{key}` serves the {current:?} family; a {family:?} handler cannot replace it"
210                    ),
211                )
212                .with_retryable(false));
213            }
214        }
215        if let Some(recorder) = &table.recorder {
216            recorder.handlers(vec![descriptor.clone()]);
217        }
218        let displaced = table.handlers.insert(key, (handler, descriptor));
219        drop(table);
220        // A handler's destructor may reenter the table.
221        drop(displaced);
222        Ok(())
223    }
224
225    /// Remove the handler serving `key`: a later dispatch to it answers
226    /// `HandlerUnavailable`. Returns whether one was registered.
227    pub fn deregister(&self, key: &HandlerKey) -> bool {
228        let removed = self.write().handlers.remove(key);
229        removed.is_some()
230    }
231
232    /// Record every dispatch into `recorder`, in place of any recorder
233    /// installed before: the handlers registered now are handed to it first
234    /// ([`Recorder::handlers`]), in key order, and each one registered later
235    /// as it is registered.
236    ///
237    /// Effect ids are unique within one table and its clones only: two
238    /// tables recording into one recorder issue the same ids, and the
239    /// recorder mixes up their records. Programs that write one log
240    /// dispatch through one table, such as agents built over it with
241    /// [`AgentBuilder::over_handlers`](crate::AgentBuilder::over_handlers).
242    pub fn record_to(&self, recorder: impl Recorder + Send + Sync) {
243        self.record_with(Arc::new(recorder));
244    }
245
246    pub(crate) fn record_with(&self, recorder: Arc<dyn Recorder + Send + Sync>) {
247        let mut table = self.write();
248        recorder.handlers(table.handlers.values().map(|(_, d)| d.clone()).collect());
249        table.recorder = Some(recorder);
250    }
251
252    /// The descriptor of the handler serving `key`, if any.
253    pub fn descriptor(&self, key: &HandlerKey) -> Option<HandlerDescriptor> {
254        self.read().handlers.get(key).map(|(_, d)| d.clone())
255    }
256
257    /// Every registered descriptor, in key order.
258    pub fn descriptors(&self) -> Vec<HandlerDescriptor> {
259        self.read()
260            .handlers
261            .values()
262            .map(|(_, d)| d.clone())
263            .collect()
264    }
265
266    /// Every registered key, in key order.
267    pub fn keys(&self) -> Vec<HandlerKey> {
268        self.read().handlers.keys().cloned().collect()
269    }
270
271    /// The dispatch every dispatch made through this value descends from:
272    /// `Some` for the handlers a handler is served with.
273    pub const fn parent(&self) -> Option<EffectId> {
274        self.parent
275    }
276
277    /// A reference that does not keep the table alive.
278    pub(crate) fn downgrade(&self) -> WeakHandlers {
279        WeakHandlers(Arc::downgrade(&self.shared))
280    }
281
282    /// The handlers `dispatch` is served with: dispatches made through them
283    /// are recorded as its children. `None` for a dispatch made elsewhere.
284    /// Native targets only: a dispatch's scopes are thread-safe, and browser
285    /// handlers are not.
286    #[cfg(not(target_family = "wasm"))]
287    pub fn serving(dispatch: &Dispatch) -> Option<Self> {
288        dispatch.scope::<Self>().map(|handlers| (*handlers).clone())
289    }
290
291    /// Number later dispatches after `last`: a host resuming a recorded run
292    /// passes the last id its restored state had issued (a cassette
293    /// checkpoint's `last`), so its dispatches take the ids the log holds
294    /// for them. Ids never go back: an id this table already issued above
295    /// `last` keeps the count.
296    pub fn resume_ids_after(&self, last: EffectId) {
297        self.shared
298            .next_id
299            .fetch_max(last.as_u64(), Ordering::SeqCst);
300    }
301
302    /// The next effect id of this table.
303    pub(crate) fn mint_id(&self) -> EffectId {
304        EffectId::from_raw(self.shared.next_id.fetch_add(1, Ordering::SeqCst) + 1)
305    }
306
307    /// The handler under `key` and the recorder, read under one lock.
308    fn lookup(
309        &self,
310        key: &HandlerKey,
311    ) -> Result<(ErasedHandler, Option<Arc<dyn Recorder + Send + Sync>>), ErrorReport> {
312        let table = self.read();
313        let (handler, _) = table
314            .handlers
315            .get(key)
316            .ok_or_else(|| handler_unavailable(key))?;
317        Ok((handler.clone(), table.recorder.clone()))
318    }
319
320    /// The dispatch `id` of `kind`, with the scopes it is served with and,
321    /// when the table records, its record begun and the recorder.
322    fn open(&self, id: EffectId, key: &HandlerKey, kind: &EffectKind, beside: Beside) -> Opened {
323        let (handler, recorder) = match &beside.handler {
324            Some(handler) => (handler.clone(), self.read().recorder.clone()),
325            None => self.lookup(key)?,
326        };
327        let mut dispatch = Dispatch::new(id, kind.streams());
328        #[cfg(not(target_family = "wasm"))]
329        {
330            let child = Self {
331                shared: Arc::clone(&self.shared),
332                parent: Some(id),
333            };
334            dispatch = dispatch.with_scope(Arc::new(child));
335        }
336        if let Some(context) = beside.context {
337            dispatch = dispatch.with_scope(Arc::new(context));
338        }
339        if let Some(published) = beside.published {
340            dispatch = dispatch.with_scope(published);
341        }
342        if let Some(recorder) = &recorder {
343            let origin = DispatchContext {
344                parent: self.parent,
345                ..DispatchContext::default()
346            };
347            recorder.begin(id, key.clone(), kind.clone(), origin);
348            dispatch = dispatch.recorded_by(Arc::clone(recorder));
349        }
350        Ok((handler, dispatch, recorder))
351    }
352
353    /// Dispatch a unary effect to the handler under `key`. A streaming
354    /// completion dispatched unary resolves to the completion its stream
355    /// ends with.
356    pub fn dispatch(
357        &self,
358        key: &HandlerKey,
359        kind: EffectKind,
360    ) -> impl Future<Output = Result<Answered, ErrorReport>> + WasmCompatSend + 'static {
361        let beside = Beside::for_kind(&kind);
362        self.serve(self.mint_id(), key.clone(), kind, beside)
363    }
364
365    /// Dispatch a streaming effect to the handler under `key`. A unary kind
366    /// yields one request error without reaching a handler.
367    pub fn dispatch_stream(&self, key: &HandlerKey, kind: EffectKind) -> StreamEvents {
368        self.serve_stream(self.mint_id(), key.clone(), kind, None)
369    }
370
371    /// Serve `kind` as the effect `id`, in the returned future. A panic in
372    /// the handler resolves the effect to an internal error reading
373    /// `panicked: <message>`, where panics unwind.
374    pub(crate) fn serve(
375        &self,
376        id: EffectId,
377        key: HandlerKey,
378        kind: EffectKind,
379        beside: Beside,
380    ) -> impl Future<Output = Result<Answered, ErrorReport>> + WasmCompatSend + 'static {
381        let this = self.clone();
382        async move {
383            yield_once().await;
384            let (handler, dispatch, recorder) = this.open(id, &key, &kind, beside)?;
385            let work = async move { handler.handle(kind, dispatch).await.into_outcome().await };
386            catch_panics(recorder, id, work).await
387        }
388        // The handler runs under the span the dispatch was made in.
389        .instrument(tracing::Span::current())
390    }
391
392    /// Serve the streaming `kind` as the effect `id`, on `handler` when
393    /// given, else on the one under `key`. A stream that ends before its
394    /// response or error ends with `stream_truncated`.
395    pub(crate) fn serve_stream(
396        &self,
397        id: EffectId,
398        key: HandlerKey,
399        kind: EffectKind,
400        handler: Option<ErasedHandler>,
401    ) -> StreamEvents {
402        if !kind.streams() {
403            let report = ErrorReport::new(
404                ErrorKind::Request,
405                format!(
406                    "invalid dispatch: `{}` is a unary effect and cannot be dispatched as a stream",
407                    kind.name()
408                ),
409            );
410            return Box::pin(futures::stream::iter([Err(report)]));
411        }
412        let this = self.clone();
413        let beside = Beside {
414            handler,
415            ..Beside::default()
416        };
417        let events = async_stream::stream! {
418            yield_once().await;
419            let (handler, dispatch, _) = match this.open(id, &key, &kind, beside) {
420                Ok(opened) => opened,
421                Err(report) => {
422                    yield Err(report);
423                    return;
424                }
425            };
426            let mut events = handler.handle(kind, dispatch).await.into_stream();
427            let (mut ahead, mut drained, mut ended) = (VecDeque::new(), false, false);
428            loop {
429                // What the handler has ready is read, and recorded, before
430                // the next item is handed on, up to `READ_AHEAD` items.
431                let next = std::future::poll_fn(|cx| {
432                    while !drained && ahead.len() < READ_AHEAD {
433                        match events.poll_next_unpin(cx) {
434                            Poll::Ready(Some(item)) => ahead.push_back(item),
435                            Poll::Ready(None) => drained = true,
436                            Poll::Pending => break,
437                        }
438                    }
439                    match ahead.pop_front() {
440                        Some(item) => Poll::Ready(Some(item)),
441                        None if drained => Poll::Ready(None),
442                        None => Poll::Pending,
443                    }
444                })
445                .await;
446                let Some(item) = next else { break };
447                ended |= matches!(item, Ok(Relayed::Done(_)) | Err(_));
448                yield item;
449            }
450            if !ended {
451                yield Err(rig_core::serve::stream_truncated());
452            }
453        };
454        Box::pin(tracing_futures::Instrument::instrument(
455            events,
456            tracing::Span::current(),
457        ))
458    }
459
460    /// Bind a typed view to `key`, checking the handler's family against
461    /// `F` now rather than at first dispatch.
462    pub fn handle<F: Family>(&self, key: &HandlerKey) -> Result<Handle<F>, ErrorReport> {
463        let descriptor = self
464            .descriptor(key)
465            .ok_or_else(|| handler_unavailable(key))?;
466        let found = descriptor.family.family();
467        if found != F::FAMILY {
468            return Err(family_mismatch(key, F::FAMILY, found));
469        }
470        Ok(Handle {
471            handlers: self.clone(),
472            descriptor,
473            _family: PhantomData,
474        })
475    }
476
477    /// Bind a typed key, checking that a handler of its family serves it.
478    pub fn bind<F: Family>(&self, key: &Key<F>) -> Result<Handle<F>, ErrorReport> {
479        self.handle(key.raw())
480    }
481
482    /// Bind a typed view to a host's custom effect: the handler under `key`
483    /// must describe itself as [`FamilyDescriptor::Custom`] with `E::KIND`.
484    pub fn custom<E: CustomEffect>(
485        &self,
486        key: &HandlerKey,
487    ) -> Result<Handle<family::Custom<E>>, ErrorReport> {
488        let handle = self.handle::<family::Custom<E>>(key)?;
489        match &handle.descriptor.family {
490            FamilyDescriptor::Custom { kind } if kind == E::KIND => Ok(handle),
491            FamilyDescriptor::Custom { kind } => Err(ErrorReport::new(
492                ErrorKind::HandlerUnavailable,
493                format!(
494                    "handler `{key}` serves the custom kind `{kind}`, not `{}`",
495                    E::KIND
496                ),
497            )),
498            other => Err(family_mismatch(key, EffectFamily::Custom, other.family())),
499        }
500    }
501}
502
503/// A [`Handlers`] that does not keep its table alive.
504pub(crate) struct WeakHandlers(std::sync::Weak<Shared>);
505
506impl WeakHandlers {
507    pub(crate) fn upgrade(&self) -> Option<Handlers> {
508        self.0.upgrade().map(|shared| Handlers {
509            shared,
510            parent: None,
511        })
512    }
513}
514
515type Opened = Result<
516    (
517        ErasedHandler,
518        Dispatch,
519        Option<Arc<dyn Recorder + Send + Sync>>,
520    ),
521    ErrorReport,
522>;
523
524/// How many items of a streamed reply are read ahead of its consumer.
525const READ_AHEAD: usize = 64;
526
527/// Pending once, waking itself: the dispatches a caller makes in one pass
528/// all begin, in the order made, before any of them is answered.
529async fn yield_once() {
530    let mut yielded = false;
531    std::future::poll_fn(|cx| {
532        if std::mem::replace(&mut yielded, true) {
533            return Poll::Ready(());
534        }
535        cx.waker().wake_by_ref();
536        Poll::Pending
537    })
538    .await;
539}
540
541/// What a dispatch is served with beside its effect.
542#[derive(Default)]
543pub(crate) struct Beside {
544    /// The handler to serve it on, in place of the one under its key: a
545    /// tool catalog's pinned registration.
546    pub(crate) handler: Option<ErasedHandler>,
547    /// The context a tool call runs with.
548    pub(crate) context: Option<ToolContext>,
549    /// Where what the tool publishes lands.
550    pub(crate) published: Option<Arc<PublishedContext>>,
551}
552
553impl Beside {
554    /// A tool call always gets a slot for what it publishes, so the record
555    /// keeps it.
556    pub(crate) fn for_kind(kind: &EffectKind) -> Self {
557        Self {
558            published: matches!(kind, EffectKind::ToolCall { .. }).then(PublishedContext::new),
559            ..Self::default()
560        }
561    }
562}
563
564fn handler_unavailable(key: &HandlerKey) -> ErrorReport {
565    ErrorReport::new(
566        ErrorKind::HandlerUnavailable,
567        format!("no handler serves key `{key}`"),
568    )
569    .with_retryable(false)
570}
571
572fn family_mismatch(key: &HandlerKey, wanted: EffectFamily, found: EffectFamily) -> ErrorReport {
573    ErrorReport::new(
574        ErrorKind::HandlerUnavailable,
575        format!("handler `{key}` serves the {found} family, not {wanted}"),
576    )
577}
578
579/// A typed view over a [`Handlers`] key for the family `F`.
580#[derive(Clone)]
581pub struct Handle<F: Family> {
582    handlers: Handlers,
583    descriptor: HandlerDescriptor,
584    _family: PhantomData<fn() -> F>,
585}
586
587/// A completion model: `call`, `stream`, `capabilities`, `label`.
588pub type ModelHandle = Handle<family::Completion>;
589/// A tool: `call`.
590pub type ToolHandle = Handle<family::Tool>;
591/// A vector-store index: `top_n`, `top_n_ids`.
592pub type IndexHandle = Handle<family::Retrieve>;
593
594impl<F: Family> std::fmt::Debug for Handle<F> {
595    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
596        f.debug_struct("Handle")
597            .field("family", &F::FAMILY)
598            .field("key", &self.descriptor.key)
599            .finish_non_exhaustive()
600    }
601}
602
603impl<F: Family> Handle<F> {
604    /// The key this handle dispatches to.
605    pub fn key(&self) -> &HandlerKey {
606        &self.descriptor.key
607    }
608
609    /// The descriptor now: a runtime replacement under the same key is
610    /// visible. Falls back to the bind-time snapshot when nothing serves the
611    /// key any more.
612    pub fn descriptor(&self) -> HandlerDescriptor {
613        self.handlers
614            .descriptor(&self.descriptor.key)
615            .unwrap_or_else(|| self.descriptor.clone())
616    }
617
618    /// Dispatch a typed request of this family. A request with no wire form
619    /// fails without reaching a handler or the recorder.
620    pub fn dispatch(
621        &self,
622        request: F::Request,
623    ) -> impl Future<Output = Result<F::Answer, ErrorReport>> + WasmCompatSend + 'static {
624        self.dispatch_mapped(request, Ok)
625    }
626
627    fn dispatch_mapped<T: 'static>(
628        &self,
629        request: F::Request,
630        map: fn(F::Answer) -> Result<T, ErrorReport>,
631    ) -> impl Future<Output = Result<T, ErrorReport>> + WasmCompatSend + 'static {
632        let id = self.handlers.mint_id();
633        let served = F::wrap(request).map(|kind| {
634            let beside = Beside::for_kind(&kind);
635            self.handlers
636                .serve(id, self.descriptor.key.clone(), kind, beside)
637        });
638        async move { F::unwrap(served?.await?).and_then(map) }
639    }
640}
641
642impl ModelHandle {
643    fn family(&self) -> Option<(ModelRef, ProviderCapabilities)> {
644        match self.descriptor().family {
645            FamilyDescriptor::Completion {
646                model,
647                capabilities,
648            } => Some((model, capabilities)),
649            _ => None,
650        }
651    }
652
653    /// The capability snapshot the handler advertises now.
654    pub fn capabilities(&self) -> ProviderCapabilities {
655        self.family()
656            .map(|(_, capabilities)| capabilities)
657            .unwrap_or_default()
658    }
659
660    /// The model's label as the handler advertises it now.
661    pub fn label(&self) -> ModelRef {
662        self.family()
663            .map_or_else(|| ModelRef::new(self.key().as_str()), |(model, _)| model)
664    }
665
666    /// A unary completion.
667    pub fn call(
668        &self,
669        request: CompletionRequest,
670    ) -> impl Future<Output = Result<<family::Completion as Family>::Answer, ErrorReport>>
671    + WasmCompatSend
672    + 'static {
673        self.dispatch(request)
674    }
675
676    /// A streamed completion, folded by the returned stream.
677    pub fn stream(&self, request: CompletionRequest) -> CompletionStream {
678        let kind = EffectKind::Completion {
679            request: request.into(),
680            stream: true,
681        };
682        let events = self.handlers.serve_stream(
683            self.handlers.mint_id(),
684            self.descriptor.key.clone(),
685            kind,
686            None,
687        );
688        CompletionStream::relay(self.label().to_string(), events)
689    }
690}
691
692/// A tool result and what the tool published into its context.
693#[derive(Debug, Clone)]
694pub struct ToolAnswer {
695    /// The result.
696    pub result: ToolResult,
697    /// The context after the tool ran: the inbound values it ran with and
698    /// the result metadata it published.
699    pub context: ToolContext,
700}
701
702impl ToolHandle {
703    /// Call the tool with raw JSON `args` under `context`: the context
704    /// travels beside the effect to the tool (never on the wire), and the
705    /// answer carries what the tool published.
706    pub fn call(
707        &self,
708        name: impl Into<String>,
709        args: impl Into<String>,
710        context: ToolContext,
711    ) -> impl Future<Output = Result<ToolAnswer, ErrorReport>> + WasmCompatSend + 'static {
712        let kind = EffectKind::ToolCall {
713            name: name.into(),
714            args: args.into(),
715        };
716        // The tool runs on a dispatch snapshot: inbound values, no result
717        // metadata a previous call left on `context`.
718        let mut inbound = context.for_dispatch();
719        let published = PublishedContext::new();
720        let beside = Beside {
721            handler: None,
722            context: Some(inbound.clone()),
723            published: Some(Arc::clone(&published)),
724        };
725        let served = self.handlers.serve(
726            self.handlers.mint_id(),
727            self.descriptor.key.clone(),
728            kind,
729            beside,
730        );
731        async move {
732            let result = family::Tool::unwrap(served.await?)?;
733            let context = published.take().unwrap_or_else(|| {
734                inbound.clear_scope();
735                inbound
736            });
737            Ok(ToolAnswer { result, context })
738        }
739    }
740}
741
742impl IndexHandle {
743    /// Scored documents, deserialized as `T`.
744    pub fn top_n<T: DeserializeOwned + WasmCompatSend + 'static>(
745        &self,
746        req: VectorSearchRequest<Filter<serde_json::Value>>,
747    ) -> impl Future<Output = Result<Vec<VectorSearchResult<T>>, ErrorReport>> + WasmCompatSend + 'static
748    {
749        self.dispatch_mapped(RetrieveQuery::TopN { req }, |documents| match documents {
750            RetrievedDocuments::Scored(results) => results
751                .into_iter()
752                .map(
753                    |(score, id, document)| match rig_core::json_utils::from_value(&document) {
754                        Ok(document) => Ok(VectorSearchResult {
755                            score,
756                            id,
757                            document,
758                        }),
759                        Err(error) => Err(ErrorReport::new(
760                            ErrorKind::Json,
761                            format!("retrieved document `{id}` did not deserialize: {error}"),
762                        )),
763                    },
764                )
765                .collect(),
766            RetrievedDocuments::Ids(_) => Err(wrong_shape("scored documents")),
767        })
768    }
769
770    /// Scored ids.
771    pub fn top_n_ids(
772        &self,
773        req: VectorSearchRequest<Filter<serde_json::Value>>,
774    ) -> impl Future<Output = Result<Vec<VectorSearchIdResult>, ErrorReport>> + WasmCompatSend + 'static
775    {
776        self.dispatch_mapped(
777            RetrieveQuery::TopNIds { req },
778            |documents| match documents {
779                RetrievedDocuments::Ids(results) => Ok(results
780                    .into_iter()
781                    .map(|(score, id)| VectorSearchIdResult { score, id })
782                    .collect()),
783                RetrievedDocuments::Scored(_) => Err(wrong_shape("scored ids")),
784            },
785        )
786    }
787}
788
789fn wrong_shape(expected: &'static str) -> ErrorReport {
790    ErrorReport::new(
791        ErrorKind::Internal,
792        format!("expected {expected}, the retrieve handler answered another shape"),
793    )
794}
795
796#[cfg(test)]
797mod tests;