Skip to main content

rig_core/effect/
mod.rs

1//! Serializable effect requests, handler descriptions, outcomes, and recording data.
2//! [`HandlerKey`] identifies a destination; [`EffectKind`] and [`Answered`] describe
3//! the exchange. Host-defined operations use [`CustomEffect`].
4//!
5//! ```
6//! use rig_core::effect::{EffectFamily, EffectRow, model_key};
7//!
8//! let mut row = EffectRow::new();
9//! row.insert(model_key("primary"), EffectFamily::Completion);
10//! assert_eq!(row.len(), 1);
11//! ```
12
13use std::{borrow::Cow, fmt, sync::Arc};
14
15use serde::{Deserialize, Serialize};
16
17use crate::{
18    completion::{CompletionRequest, CompletionResponse, ModelRef, ProviderCapabilities},
19    embeddings::EmbeddingResponse,
20    error::ErrorReport,
21    operation::RerankRequest,
22    rerank::RerankResponse,
23    streaming::StreamRecord,
24    tool::ToolResult,
25    vector_store::request::{Filter, VectorSearchRequest},
26    wasm_compat::WasmCompatSend,
27};
28
29/// The identity of one dispatch, minted by the dispatcher.
30///
31/// It links an [`EffectRecord`] to a host's own bookkeeping (a host driver
32/// maps it to its own handle). Ids are unique per dispatcher and strictly increasing.
33#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]
34#[serde(transparent)]
35pub struct EffectId(u64);
36
37impl EffectId {
38    /// Build an id from its raw value (a replayer restoring a log does this).
39    pub const fn from_raw(raw: u64) -> Self {
40        Self(raw)
41    }
42
43    /// The raw value.
44    pub const fn as_u64(self) -> u64 {
45        self.0
46    }
47}
48
49impl fmt::Display for EffectId {
50    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
51        write!(f, "effect:{}", self.0)
52    }
53}
54
55/// String identifier for a registered handler, serializable without a live handle.
56#[derive(Clone, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]
57#[serde(transparent)]
58pub struct HandlerKey(Arc<str>);
59
60impl HandlerKey {
61    /// Build a key from any string-like value.
62    pub fn new(key: impl Into<Arc<str>>) -> Self {
63        Self(key.into())
64    }
65
66    /// The key as a string slice.
67    pub fn as_str(&self) -> &str {
68        &self.0
69    }
70
71    /// Parses the key into [`KeyParts`] without failure. Formatting the parts
72    /// reproduces the original key.
73    pub fn parts(&self) -> KeyParts {
74        KeyParts::parse(&self.0)
75    }
76}
77
78/// A key's parts, by the grammar every key the tree mints follows:
79///
80/// ```text
81/// [<owner>/]<name>[#<generation>]     where <name> is [<kind>:]<label>
82/// ```
83///
84/// `golden/tool:add#2` is owner `golden`, kind `tool`, label `add`,
85/// generation `2`; `host/note` is owner `host`, no kind, label `note`;
86/// `model:fast` is no owner, kind `model`, label `fast`. The owner is the
87/// text before the first `/`, the kind the text before the first `:` of
88/// what follows, the generation the digits after the last `#`; a label
89/// holds anything else, so a key whose label contains one of those
90/// separators is read as its grammar says, not as its author meant. The
91/// string is the wire form; this is how a reader takes it apart without
92/// a hand parser of its own.
93#[derive(Debug, Clone, PartialEq, Eq, Hash)]
94pub struct KeyParts {
95    /// The program or host the key belongs to (`golden`, `host`).
96    pub owner: Option<Arc<str>>,
97    /// The family-shaped prefix of the name (`model`, `tool`, `retrieve`).
98    pub kind: Option<Arc<str>>,
99    /// The name proper: a model label, a tool name, `retrieve`, `note`.
100    pub label: Arc<str>,
101    /// The disambiguating generation (`#2`): the same tool registered
102    /// again under a fresh key. Only canonical `u64` decimal suffixes are
103    /// generations; leading zeroes and overflow remain literal label text.
104    pub generation: Option<u64>,
105}
106
107impl KeyParts {
108    /// Read `key` by the grammar.
109    pub fn parse(key: &str) -> Self {
110        let (owner, rest) = match key.split_once('/') {
111            Some((owner, rest)) if !owner.is_empty() && !rest.is_empty() => {
112                (Some(Arc::from(owner)), rest)
113            }
114            _ => (None, key),
115        };
116        let (rest, generation) = match rest.rsplit_once('#') {
117            Some((head, digits))
118                if !digits.is_empty()
119                    && (digits.len() == 1 || !digits.starts_with('0'))
120                    && digits.bytes().all(|b| b.is_ascii_digit()) =>
121            {
122                match digits.parse::<u64>() {
123                    Ok(generation) => (head, Some(generation)),
124                    Err(_) => (rest, None),
125                }
126            }
127            _ => (rest, None),
128        };
129        let (kind, label) = match rest.split_once(':') {
130            Some((kind, label)) if !kind.is_empty() && !label.is_empty() => {
131                (Some(Arc::from(kind)), label)
132            }
133            _ => (None, rest),
134        };
135        Self {
136            owner,
137            kind,
138            label: Arc::from(label),
139            generation,
140        }
141    }
142}
143
144impl fmt::Display for KeyParts {
145    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
146        if let Some(owner) = &self.owner {
147            write!(f, "{owner}/")?;
148        }
149        if let Some(kind) = &self.kind {
150            write!(f, "{kind}:")?;
151        }
152        f.write_str(&self.label)?;
153        if let Some(generation) = self.generation {
154            write!(f, "#{generation}")?;
155        }
156        Ok(())
157    }
158}
159
160impl fmt::Debug for HandlerKey {
161    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
162        write!(f, "HandlerKey({:?})", &*self.0)
163    }
164}
165
166impl fmt::Display for HandlerKey {
167    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
168        f.write_str(&self.0)
169    }
170}
171
172impl From<&str> for HandlerKey {
173    fn from(key: &str) -> Self {
174        Self(Arc::from(key))
175    }
176}
177
178impl From<String> for HandlerKey {
179    fn from(key: String) -> Self {
180        Self(Arc::from(key))
181    }
182}
183
184impl AsRef<str> for HandlerKey {
185    fn as_ref(&self) -> &str {
186        &self.0
187    }
188}
189
190/// Effect classification used by typed binding and recording.
191#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
192#[serde(rename_all = "snake_case")]
193pub enum EffectFamily {
194    /// A completion request to a model.
195    Completion,
196    /// A tool call.
197    Tool,
198    /// A text or image embedding request.
199    Embed,
200    /// A reranking request.
201    Rerank,
202    /// A vector-store retrieval.
203    Retrieve,
204    /// An out-of-tree kind.
205    Custom,
206}
207
208impl EffectFamily {
209    /// The family's stable label.
210    pub const fn name(self) -> &'static str {
211        match self {
212            Self::Completion => "completion",
213            Self::Tool => "tool_call",
214            Self::Embed => "embed",
215            Self::Rerank => "rerank",
216            Self::Retrieve => "retrieve",
217            Self::Custom => "custom",
218        }
219    }
220}
221
222impl fmt::Display for EffectFamily {
223    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
224        f.write_str(self.name())
225    }
226}
227
228/// Sealed mapping between typed requests and answers and the wire's
229/// [`EffectKind`] and [`Answered`]. Hosts extend the protocol through
230/// [`CustomEffect`] and [`family::Custom`], not new family implementations.
231pub trait Family: sealed::Sealed + Clone + Copy + Send + Sync + 'static {
232    /// The family this marker names.
233    const FAMILY: EffectFamily;
234    /// What a typed dispatch of this family takes.
235    type Request: WasmCompatSend + 'static;
236    /// What it resolves to.
237    type Answer: WasmCompatSend + 'static;
238    /// The wire form of a request, or the report for a request that has
239    /// none (a [`CustomEffect`] whose `Serialize` fails). The in-tree
240    /// families always have one; a typed dispatch of a request without one
241    /// is pre-failed and never reaches a handler or a log.
242    fn wrap(request: Self::Request) -> Result<EffectKind, ErrorReport>;
243    /// The typed answer, or the report for an outcome of another family.
244    fn unwrap(outcome: Answered) -> Result<Self::Answer, ErrorReport>;
245    /// The report [`Family::unwrap`] gives for an outcome of another family.
246    fn mismatch(outcome: &Answered) -> ErrorReport {
247        ErrorReport::new(
248            crate::error::ErrorKind::Internal,
249            format!(
250                "expected a {} outcome, the handler answered {}",
251                Self::FAMILY,
252                outcome.family()
253            ),
254        )
255    }
256}
257
258mod sealed {
259    pub trait Sealed {}
260}
261
262/// Sealed handler-family declaration. Typed families expose `Some(F::FAMILY)`;
263/// [`family::Dynamic`] exposes `None` and requires runtime family checks.
264pub trait Served: sealed::Sealed + 'static {
265    /// The family, when the handler has one.
266    const SERVED: Option<EffectFamily>;
267}
268
269// `Served` is sealed; a handler's family is a `Family` marker or `Dynamic`,
270// and an error about it should say so rather than suggest this impl.
271#[diagnostic::do_not_recommend]
272impl<F: Family> Served for F {
273    const SERVED: Option<EffectFamily> = Some(F::FAMILY);
274}
275
276/// A tool call as a typed request: the name and the raw JSON arguments.
277/// The context the tool runs with is not part of the request: it travels
278/// beside the dispatch, attached by the driver to the handler's sink
279/// (`Dispatch::scope::<ToolContext>()`), and what the tool publishes
280/// comes back the same way ([`crate::tool::PublishedContext`]).
281#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
282pub struct ToolCallRequest {
283    /// The tool's name (the name the model calls it by).
284    pub name: String,
285    /// The arguments as a JSON string.
286    pub args: String,
287}
288
289/// A host's own effect, typed the way a [`ToolContext`](crate::tool::ToolContext) value is: a
290/// declared kind label and a declared answer type, both serde. The wire
291/// form is [`EffectKind::Custom`] / [`Answered::Custom`]; the type never
292/// crosses it.
293pub trait CustomEffect: Serialize + serde::de::DeserializeOwned + WasmCompatSend + 'static {
294    /// The kind label this effect dispatches under; a handler's
295    /// [`FamilyDescriptor::Custom`] must name the same label.
296    const KIND: &'static str;
297    /// What the handler answers.
298    type Answer: Serialize + serde::de::DeserializeOwned + WasmCompatSend + 'static;
299}
300
301mod key;
302
303pub use key::Key;
304
305/// A key for a model handler: `model:<label>`.
306pub fn model_key(label: &str) -> HandlerKey {
307    HandlerKey::from(format!("model:{label}"))
308}
309
310/// A key for a tool handler: `tool:<name>`.
311pub fn tool_key(name: &str) -> HandlerKey {
312    HandlerKey::from(format!("tool:{name}"))
313}
314
315/// A key for an embedding handler: `embed:<label>`.
316pub fn embed_key(label: &str) -> HandlerKey {
317    HandlerKey::from(format!("embed:{label}"))
318}
319
320/// A key for a rerank handler: `rerank:<label>`.
321pub fn rerank_key(label: &str) -> HandlerKey {
322    HandlerKey::from(format!("rerank:{label}"))
323}
324
325/// A key for a labelled retrieval handler: `retrieve:<label>`. An agent's
326/// own index is registered under the bare `retrieve` key.
327pub fn retrieve_key(label: &str) -> HandlerKey {
328    HandlerKey::from(format!("retrieve:{label}"))
329}
330
331/// Type-level markers for built-in and host-defined effect families.
332///
333/// ```
334/// use rig_core::effect::{family, Family, EffectFamily};
335/// assert_eq!(family::Completion::FAMILY, EffectFamily::Completion);
336/// ```
337pub mod family {
338    use std::marker::PhantomData;
339
340    use super::{
341        Answered, CustomEffect, EffectFamily, EffectKind, EmbedInputs, EmbedOutputs, Family,
342        RetrieveQuery, RetrievedDocuments, ToolCallRequest, sealed::Sealed,
343    };
344    use crate::{
345        completion::{CompletionRequest, CompletionResponse},
346        error::{ErrorKind, ErrorReport},
347        operation::RerankRequest,
348        rerank::RerankResponse,
349        tool::ToolResult,
350    };
351
352    macro_rules! marker {
353        ($($(#[$doc:meta])* $name:ident => $family:ident, $request:ty, $answer:ty, $wrap:expr, $unwrap:expr;)+) => {$(
354            $(#[$doc])*
355            #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
356            pub struct $name;
357
358            impl Sealed for $name {}
359
360            impl Family for $name {
361                const FAMILY: EffectFamily = EffectFamily::$family;
362                type Request = $request;
363                type Answer = $answer;
364
365                fn wrap(request: Self::Request) -> Result<EffectKind, ErrorReport> {
366                    let wrap: fn(Self::Request) -> EffectKind = $wrap;
367                    Ok(wrap(request))
368                }
369
370                fn unwrap(outcome: Answered) -> Result<Self::Answer, ErrorReport> {
371                    let unwrap: fn(Answered) -> Result<Self::Answer, ErrorReport> = $unwrap;
372                    unwrap(outcome)
373                }
374            }
375        )+};
376    }
377
378    marker! {
379        /// The completion family: a unary completion (a streaming dispatch is
380        /// `ModelHandle::stream`, not a typed request).
381        Completion => Completion, CompletionRequest, CompletionResponse,
382            |request| EffectKind::Completion { request: std::sync::Arc::new(request), stream: false },
383            |outcome| match outcome {
384                Answered::Completion(response) => Ok(std::sync::Arc::unwrap_or_clone(response)),
385                other => Err(Completion::mismatch(&other)),
386            };
387        /// The tool family.
388        Tool => Tool, ToolCallRequest, ToolResult,
389            |request| EffectKind::ToolCall { name: request.name, args: request.args },
390            |outcome| match outcome {
391                Answered::ToolResult { result } => Ok(result),
392                other => Err(Tool::mismatch(&other)),
393            };
394        /// The embedding family.
395        Embed => Embed, EmbedInputs, EmbedOutputs,
396            |inputs| EffectKind::Embed { inputs },
397            |outcome| match outcome {
398                Answered::Embeddings(outputs) => Ok(outputs),
399                other => Err(Embed::mismatch(&other)),
400            };
401        /// The reranking family.
402        Rerank => Rerank, RerankRequest, RerankResponse,
403            |request| EffectKind::Rerank { request },
404            |outcome| match outcome {
405                Answered::Reranked(response) => Ok(response),
406                other => Err(Rerank::mismatch(&other)),
407            };
408        /// The retrieval family.
409        Retrieve => Retrieve, RetrieveQuery, RetrievedDocuments,
410            |query| EffectKind::Retrieve { query },
411            |outcome| match outcome {
412                Answered::Documents(documents) => Ok(documents),
413                other => Err(Retrieve::mismatch(&other)),
414            };
415    }
416
417    /// A handler with no one family: a replayer answering whatever its log
418    /// holds, or an erased handler forwarding to whatever it wraps.
419    #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
420    pub struct Dynamic;
421
422    impl Sealed for Dynamic {}
423
424    impl super::Served for Dynamic {
425        const SERVED: Option<EffectFamily> = None;
426    }
427
428    /// The family of one host-defined effect `E`: dispatches
429    /// [`EffectKind::Custom`] under `E::KIND` and answers `E::Answer`.
430    pub struct Custom<E: CustomEffect>(PhantomData<fn() -> E>);
431
432    // Written by hand: a derive would demand `E: Clone`, and the marker
433    // must be `Copy` for every `E`.
434    impl<E: CustomEffect> Clone for Custom<E> {
435        fn clone(&self) -> Self {
436            *self
437        }
438    }
439    impl<E: CustomEffect> Copy for Custom<E> {}
440
441    impl<E: CustomEffect> Sealed for Custom<E> {}
442
443    impl<E: CustomEffect> Family for Custom<E> {
444        const FAMILY: EffectFamily = EffectFamily::Custom;
445        type Request = E;
446        type Answer = E::Answer;
447
448        fn wrap(request: E) -> Result<EffectKind, ErrorReport> {
449            // Reject unencodable requests before dispatch so no handler or log
450            // receives an effect without a wire representation.
451            serde_json::to_value(&request)
452                .map(|payload| EffectKind::Custom {
453                    kind: std::sync::Arc::from(E::KIND),
454                    payload,
455                })
456                .map_err(|error| {
457                    ErrorReport::new(
458                        ErrorKind::Request,
459                        format!("the `{}` effect did not serialize: {error}", E::KIND),
460                    )
461                })
462        }
463
464        fn unwrap(outcome: Answered) -> Result<E::Answer, ErrorReport> {
465            match outcome {
466                Answered::Custom { payload: value } => crate::json_utils::from_value(&value)
467                    .map_err(|error| {
468                        ErrorReport::new(
469                            ErrorKind::Internal,
470                            format!(
471                                "the answer to the `{}` effect did not deserialize: {error}",
472                                E::KIND
473                            ),
474                        )
475                    }),
476                other => Err(Self::mismatch(&other)),
477            }
478        }
479    }
480}
481
482/// What a registered handler is: its key and its family-specific description.
483#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
484pub struct HandlerDescriptor {
485    /// The key the handler is registered under.
486    pub key: HandlerKey,
487    /// The family and its advertised metadata.
488    pub family: FamilyDescriptor,
489    /// Interceptor names in outermost-first order, used to validate the layer
490    /// stack during replay. Empty for a handler without layers.
491    #[serde(default, skip_serializing_if = "Vec::is_empty")]
492    pub layers: Vec<String>,
493}
494
495impl HandlerDescriptor {
496    /// A tool's handler, under [`tool_key`] of its `name`, with no layers
497    /// and no embedding.
498    pub fn tool(name: &str, description: impl Into<String>, parameters: serde_json::Value) -> Self {
499        Self {
500            key: tool_key(name),
501            family: FamilyDescriptor::Tool {
502                name: name.to_owned(),
503                description: description.into(),
504                parameters,
505                embedding: None,
506            },
507            layers: Vec::new(),
508        }
509    }
510}
511
512/// The family-keyed description of a handler. The variant *is* the family:
513/// binding a typed view compares [`Family::FAMILY`] against
514/// [`FamilyDescriptor::family`].
515#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
516#[serde(tag = "family", rename_all = "snake_case")]
517pub enum FamilyDescriptor {
518    /// A completion model.
519    Completion {
520        /// The model's label.
521        model: ModelRef,
522        /// The capability snapshot a runtime prepares requests against.
523        capabilities: ProviderCapabilities,
524    },
525    /// A tool.
526    Tool {
527        /// The tool's name (the name the model calls it by).
528        name: String,
529        /// The tool's description.
530        description: String,
531        /// The JSON schema of the tool's arguments.
532        parameters: serde_json::Value,
533        /// Present when the tool is retrievable by embedding.
534        #[serde(default, skip_serializing_if = "Option::is_none")]
535        embedding: Option<ToolEmbeddingDescriptor>,
536    },
537    /// An embedding model.
538    Embed {
539        /// The model's label.
540        model: String,
541        /// The vector dimension, when the model declares one.
542        #[serde(default, skip_serializing_if = "Option::is_none")]
543        dims: Option<usize>,
544        /// The largest batch the model accepts.
545        max_documents: usize,
546        /// Whether the model embeds text or images.
547        modality: EmbedModality,
548    },
549    /// A reranking model.
550    Rerank {
551        /// The model's label.
552        model: String,
553        /// The largest batch the model accepts.
554        max_documents: usize,
555    },
556    /// A vector-store index.
557    Retrieve {},
558    /// A handler for an out-of-tree kind: the label it serves.
559    Custom {
560        /// The [`EffectKind::Custom`] kind label this handler answers.
561        kind: String,
562    },
563}
564
565impl FamilyDescriptor {
566    /// The family this descriptor belongs to.
567    pub const fn family(&self) -> EffectFamily {
568        match self {
569            Self::Completion { .. } => EffectFamily::Completion,
570            Self::Tool { .. } => EffectFamily::Tool,
571            Self::Embed { .. } => EffectFamily::Embed,
572            Self::Rerank { .. } => EffectFamily::Rerank,
573            Self::Retrieve {} => EffectFamily::Retrieve,
574            Self::Custom { .. } => EffectFamily::Custom,
575        }
576    }
577}
578
579/// The embedding context of a retrievable tool: what
580/// [`ToolEmbedding`](crate::tool::ToolEmbedding) advertises, as data.
581#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
582pub struct ToolEmbeddingDescriptor {
583    /// The tool's serialized context.
584    pub context: serde_json::Value,
585    /// The documents the tool is retrieved by.
586    pub embedding_docs: Vec<String>,
587}
588
589/// Which modality an embedding handler serves.
590#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
591#[serde(rename_all = "snake_case")]
592pub enum EmbedModality {
593    /// Text documents.
594    Text,
595    /// Image bytes.
596    Image,
597}
598
599/// One effect: what a handler is asked to do.
600#[derive(Debug, Clone, Serialize, Deserialize)]
601#[serde(tag = "effect", rename_all = "snake_case")]
602pub enum EffectKind {
603    /// A completion request.
604    Completion {
605        /// The prepared request, shared with the recorder and the log.
606        request: Arc<CompletionRequest>,
607        /// Whether the response streams (`dispatch_stream`) or is unary.
608        stream: bool,
609    },
610    /// A tool call. The context the tool runs with is not on the wire:
611    /// see [`ToolCallRequest`].
612    ToolCall {
613        /// The tool's name.
614        name: String,
615        /// The raw JSON arguments as the model produced them.
616        args: String,
617    },
618    /// An embedding request.
619    Embed {
620        /// The inputs to embed.
621        inputs: EmbedInputs,
622    },
623    /// A reranking request.
624    Rerank {
625        /// The query and the documents.
626        request: RerankRequest,
627    },
628    /// A retrieval.
629    Retrieve {
630        /// The query.
631        query: RetrieveQuery,
632    },
633    /// An out-of-tree effect.
634    Custom {
635        /// The host-defined kind label.
636        kind: Arc<str>,
637        /// The host-defined payload.
638        payload: serde_json::Value,
639    },
640}
641
642/// The effect a model's tool call is: the tool's name and the call's raw
643/// arguments, as a tool handler is dispatched it.
644///
645/// ```
646/// use rig_core::effect::EffectKind;
647/// use rig_core::message::{ToolCall, ToolFunction, ToolName};
648///
649/// let read = ToolFunction::new(ToolName::new("read")?, serde_json::json!({ "path": "a.rs" }));
650/// let kind = EffectKind::from(&ToolCall::from_wire("call-1", read));
651/// assert!(matches!(kind, EffectKind::ToolCall { ref name, .. } if name == "read"));
652/// # Ok::<(), Box<dyn std::error::Error>>(())
653/// ```
654impl From<&crate::message::ToolCall> for EffectKind {
655    fn from(call: &crate::message::ToolCall) -> Self {
656        Self::ToolCall {
657            name: call.function.name.as_str().to_owned(),
658            args: call.function.raw_arguments(),
659        }
660    }
661}
662
663impl EffectKind {
664    /// The family of this effect.
665    pub const fn family(&self) -> EffectFamily {
666        match self {
667            Self::Completion { .. } => EffectFamily::Completion,
668            Self::ToolCall { .. } => EffectFamily::Tool,
669            Self::Embed { .. } => EffectFamily::Embed,
670            Self::Rerank { .. } => EffectFamily::Rerank,
671            Self::Retrieve { .. } => EffectFamily::Retrieve,
672            Self::Custom { .. } => EffectFamily::Custom,
673        }
674    }
675
676    /// Classification label without payload data. Custom effects return their
677    /// host-defined kind label.
678    pub fn name(&self) -> &str {
679        match self {
680            Self::Custom { kind, .. } => kind,
681            Self::Completion { .. }
682            | Self::ToolCall { .. }
683            | Self::Embed { .. }
684            | Self::Rerank { .. }
685            | Self::Retrieve { .. } => self.family().name(),
686        }
687    }
688
689    /// Whether this effect answers as a stream. Only a streaming completion
690    /// does; every other kind is unary.
691    pub const fn streams(&self) -> bool {
692        match self {
693            Self::Completion { stream, .. } => *stream,
694            Self::ToolCall { .. }
695            | Self::Embed { .. }
696            | Self::Rerank { .. }
697            | Self::Retrieve { .. }
698            | Self::Custom { .. } => false,
699        }
700    }
701}
702
703/// The inputs of an embedding request: the texts or images an embedding
704/// model's call embeds.
705#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
706#[serde(tag = "modality", content = "inputs", rename_all = "snake_case")]
707pub enum EmbedInputs {
708    /// Text documents.
709    Texts(Vec<String>),
710    /// Image bytes.
711    Images(Vec<Vec<u8>>),
712}
713
714/// A retrieval: the transcription of
715/// [`VectorStoreIndex`](crate::vector_store::VectorStoreIndex) over the
716/// dynamic filter. The typed result parameter of `top_n<T>` stays on the
717/// client side.
718#[derive(Debug, Clone, Serialize, Deserialize)]
719#[serde(tag = "query", rename_all = "snake_case")]
720pub enum RetrieveQuery {
721    /// Scored documents.
722    TopN {
723        /// The search.
724        req: VectorSearchRequest<Filter<serde_json::Value>>,
725    },
726    /// Scored ids only.
727    TopNIds {
728        /// The search.
729        req: VectorSearchRequest<Filter<serde_json::Value>>,
730    },
731}
732
733/// What a handler answered, or what a decision gave in its place.
734#[derive(Debug, Clone, Serialize, Deserialize)]
735#[serde(tag = "outcome", rename_all = "snake_case")]
736pub enum Answered {
737    /// A unary completion, shared with the records and layers that read it.
738    Completion(Arc<CompletionResponse>),
739    /// A tool call's result. The values the tool published into its
740    /// context are not on the wire: they come back beside the sink
741    /// ([`crate::tool::PublishedContext`]).
742    ToolResult {
743        /// The result.
744        result: ToolResult,
745    },
746    /// Embeddings.
747    Embeddings(EmbedOutputs),
748    /// A reranking.
749    Reranked(RerankResponse),
750    /// Retrieved documents.
751    Documents(RetrievedDocuments),
752    /// An out-of-tree answer.
753    Custom {
754        /// The answer, nested so every JSON shape is representable.
755        payload: serde_json::Value,
756    },
757}
758
759impl Answered {
760    /// The family this outcome answers.
761    pub const fn family(&self) -> EffectFamily {
762        match self {
763            Self::Completion(_) => EffectFamily::Completion,
764            Self::ToolResult { .. } => EffectFamily::Tool,
765            Self::Embeddings(_) => EffectFamily::Embed,
766            Self::Reranked(_) => EffectFamily::Rerank,
767            Self::Documents(_) => EffectFamily::Retrieve,
768            Self::Custom { .. } => EffectFamily::Custom,
769        }
770    }
771}
772
773/// The answer to an [`EmbedInputs`].
774#[derive(Debug, Clone, Serialize, Deserialize)]
775#[serde(tag = "modality", content = "response", rename_all = "snake_case")]
776pub enum EmbedOutputs {
777    /// Text embeddings.
778    Texts(EmbeddingResponse),
779    /// Image embeddings.
780    Images(EmbeddingResponse),
781}
782
783/// The answer to a [`RetrieveQuery`].
784#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
785#[serde(tag = "retrieved", content = "results", rename_all = "snake_case")]
786pub enum RetrievedDocuments {
787    /// Scored documents: `(score, id, document)`.
788    Scored(
789        #[serde(deserialize_with = "crate::json_utils::floats")]
790        Vec<(f64, String, serde_json::Value)>,
791    ),
792    /// Scored ids: `(score, id)`.
793    Ids(#[serde(deserialize_with = "crate::json_utils::floats")] Vec<(f64, String)>),
794}
795
796/// One recorded exchange: the effect, who served it, and the answer.
797#[derive(Debug, Clone, Serialize, Deserialize)]
798pub struct EffectRecord {
799    /// Explicitly published result metadata, including on errors: a
800    /// tool's, or the facts any layer of the dispatch published
801    /// ([`PublishedContext`](crate::tool::PublishedContext)). Never
802    /// inbound authentication values or runtime scopes. `None` means nothing
803    /// was published before resolving; the wire field is required, and
804    /// `null` records that nothing was published.
805    #[serde(rename = "tool_output", deserialize_with = "Option::deserialize")]
806    pub published: Option<crate::tool::ToolResultContext>,
807    /// The dispatch's id.
808    pub id: EffectId,
809    /// The handler the effect was routed to.
810    pub key: HandlerKey,
811    /// The effect.
812    pub kind: EffectKind,
813    /// The answer.
814    pub outcome: Result<Answered, ErrorReport>,
815    /// A streamed dispatch's items, verbatim, when the recorder was asked
816    /// to keep them (`EffectLogRecorder::keeping_stream_events`); `None`
817    /// otherwise, and the answer is the fold. A replayer re-emits these
818    /// when present, so a replayed consumer sees the original fragment
819    /// boundaries. They read back through [`StreamRecord::parse_prefix`].
820    #[serde(default, skip_serializing_if = "Option::is_none")]
821    pub events: Option<StreamRecord>,
822    /// Who a streamed dispatch's reply was from, as its relay stated it
823    /// before the first item, when the items are kept. A replayer sends it
824    /// first, so a replayed stream cut short knows its origin.
825    #[serde(default, skip_serializing_if = "Option::is_none")]
826    pub stream_origin: Option<crate::message::Origin>,
827    /// Parent dispatch for a nested handler call, or `None` for a root dispatch.
828    #[serde(default, skip_serializing_if = "Option::is_none")]
829    pub parent: Option<EffectId>,
830    /// Stable identifier of the dispatching program or run, not a runtime handle.
831    /// `None` when the dispatcher supplied no scope.
832    #[serde(default, skip_serializing_if = "Option::is_none")]
833    pub scope: Option<std::sync::Arc<str>>,
834    /// What the dispatcher made the effect for, such as `"turn"` or
835    /// `"compaction"`, from its [`DispatchContext`](crate::serve::DispatchContext). `None` when
836    /// it named no purpose.
837    #[serde(default, skip_serializing_if = "Option::is_none")]
838    pub purpose: Option<std::borrow::Cow<'static, str>>,
839    /// The turn of its dispatcher's conversation it was made in, as the
840    /// host numbers turns (the first is `0`). `None` when the host keeps no
841    /// turns or it belongs to none, such as a call made between turns.
842    #[serde(default, skip_serializing_if = "Option::is_none")]
843    pub turn: Option<u64>,
844    /// The reply's call it is, for a tool call a reply asked for.
845    #[serde(default, skip_serializing_if = "Option::is_none")]
846    pub call: Option<crate::conversation::CallRef>,
847    /// When a handler started serving it, in milliseconds since the Unix
848    /// epoch. `None` when no handler started it (it was answered before it
849    /// started), or when the recorder keeps no times.
850    #[serde(default, skip_serializing_if = "Option::is_none")]
851    pub started_ms: Option<u64>,
852    /// When a streamed dispatch's first item came, in milliseconds since
853    /// the Unix epoch: the time to the first token beside
854    /// [`Self::started_ms`]. A part's end counts as an item; the stream's
855    /// own end does not. `None` when no item streamed, or when the
856    /// recorder keeps no times.
857    #[serde(default, skip_serializing_if = "Option::is_none")]
858    pub first_item_ms: Option<u64>,
859    /// When its outcome was known, in milliseconds since the Unix epoch.
860    /// `None` when the recorder keeps no times.
861    #[serde(default, skip_serializing_if = "Option::is_none")]
862    pub finished_ms: Option<u64>,
863    /// The outcome a reviewer put in place of [`Self::outcome`], which stays
864    /// the handler's (or the early answer's) own. `None` when nothing
865    /// replaced it. A replayer answers with [`Self::outcome`] and lets the
866    /// reviewers run again, as it reruns layers.
867    #[serde(default, skip_serializing_if = "Option::is_none")]
868    pub reviewed: Option<Result<Answered, ErrorReport>>,
869    /// How the outcome came about.
870    #[serde(default, skip_serializing_if = "Disposition::is_ran")]
871    pub disposition: Disposition,
872    /// Who decided the answer before it ran, when a decision answered it.
873    /// `None` when its handler or its owner answered it: an effect no gate
874    /// decided ran, and an allow is not a decision.
875    #[serde(default, skip_serializing_if = "Option::is_none")]
876    pub decided_by: Option<Decider>,
877}
878
879/// Who decided an effect's answer before it ran ([`EffectRecord::decided_by`]).
880#[non_exhaustive]
881#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
882#[serde(rename_all = "snake_case")]
883pub enum Decider {
884    /// A person, through a front: an answer to a question, a line they typed.
885    Person,
886    /// A plugin, by its name, such as `print` or `protected-paths`.
887    Plugin(Cow<'static, str>),
888}
889
890impl Decider {
891    /// The plugin called `name`.
892    pub fn plugin(name: impl Into<Cow<'static, str>>) -> Self {
893        Self::Plugin(name.into())
894    }
895}
896
897/// How an [`EffectRecord`]'s outcome came about. A recorder of handler
898/// dispatches records [`Ran`](Self::Ran); a host that answers, replaces or
899/// cancels effects itself records the others.
900#[non_exhaustive]
901#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Hash, Serialize, Deserialize)]
902#[serde(rename_all = "snake_case")]
903pub enum Disposition {
904    /// A handler served it, and the outcome is its answer.
905    #[default]
906    Ran,
907    /// Answered before any handler started it, such as by a policy that
908    /// refused it or a replayer.
909    AnsweredBeforeStart,
910    /// Answered from outside while its handler ran; the handler was
911    /// cancelled.
912    AnsweredWhileRunning,
913    /// Another effect replaced it, and its outcome was never applied.
914    Superseded,
915    /// Cancelled before it had an outcome.
916    Cancelled,
917}
918
919impl EffectRecord {
920    /// The record of effect `id`, `kind`, routed to `key` and answered with
921    /// `outcome`, and nothing else known: no parent, scope, purpose, turn,
922    /// call, times, tool output, kept items, review or decider, and
923    /// [`Disposition::Ran`]. A host that answers or cancels an effect itself
924    /// builds its record from this and sets what it knows.
925    pub fn new(
926        id: EffectId,
927        key: HandlerKey,
928        kind: EffectKind,
929        outcome: Result<Answered, ErrorReport>,
930    ) -> Self {
931        Self {
932            published: None,
933            id,
934            key,
935            kind,
936            outcome,
937            events: None,
938            stream_origin: None,
939            parent: None,
940            scope: None,
941            purpose: None,
942            turn: None,
943            call: None,
944            started_ms: None,
945            first_item_ms: None,
946            finished_ms: None,
947            reviewed: None,
948            disposition: Disposition::Ran,
949            decided_by: None,
950        }
951    }
952}
953
954impl Disposition {
955    /// Whether this is [`Self::Ran`], the default a record leaves out.
956    fn is_ran(&self) -> bool {
957        *self == Self::Ran
958    }
959}
960
961/// Required handler keys and their effect families, ordered by key.
962/// [`Self::is_subset_of`] validates the requirements against handler descriptors.
963#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
964#[serde(transparent)]
965pub struct EffectRow(std::collections::BTreeMap<HandlerKey, EffectFamily>);
966
967/// The first entry of a row a set of handlers does not serve: the key,
968/// the family the row needs, and what serves the key instead, if anything.
969#[derive(Debug, Clone, PartialEq, Eq)]
970pub struct RowGap {
971    /// The key the row names.
972    pub key: HandlerKey,
973    /// The family the row needs it as.
974    pub needed: EffectFamily,
975    /// The family a handler serves it as, or `None` when nothing serves it.
976    pub served: Option<EffectFamily>,
977}
978
979impl std::fmt::Display for RowGap {
980    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
981        match self.served {
982            Some(served) => write!(
983                f,
984                "`{}` is needed as {} but served as {served}",
985                self.key, self.needed
986            ),
987            None => write!(f, "`{}` ({}) is not served", self.key, self.needed),
988        }
989    }
990}
991
992/// One difference between two rows.
993#[derive(Debug, Clone, PartialEq, Eq)]
994pub enum RowDiff {
995    /// The other row lacks this entry.
996    Missing {
997        /// The key this row names.
998        key: HandlerKey,
999        /// The family this row names it as.
1000        family: EffectFamily,
1001    },
1002    /// The other row has an entry this one lacks.
1003    Extra {
1004        /// The key the other row names.
1005        key: HandlerKey,
1006        /// The family the other row names it as.
1007        family: EffectFamily,
1008    },
1009    /// Both rows name the key, as different families.
1010    Family {
1011        /// The key both name.
1012        key: HandlerKey,
1013        /// This row's family for it.
1014        this: EffectFamily,
1015        other: EffectFamily,
1016    },
1017}
1018
1019impl std::fmt::Display for RowDiff {
1020    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1021        match self {
1022            Self::Missing { key, family } => write!(f, "`{key}` ({family}) is missing"),
1023            Self::Extra { key, family } => write!(f, "`{key}` ({family}) is extra"),
1024            Self::Family { key, this, other } => {
1025                write!(f, "`{key}` is {this} here and {other} there")
1026            }
1027        }
1028    }
1029}
1030
1031impl EffectRow {
1032    /// An empty row.
1033    pub fn new() -> Self {
1034        Self::default()
1035    }
1036
1037    /// Name `key` as `family`; a key already named is re-named.
1038    pub fn insert(&mut self, key: HandlerKey, family: EffectFamily) -> Option<EffectFamily> {
1039        self.0.insert(key, family)
1040    }
1041
1042    /// Name `key` as `family` unless the row already names it.
1043    pub fn insert_if_absent(&mut self, key: HandlerKey, family: EffectFamily) {
1044        self.0.entry(key).or_insert(family);
1045    }
1046
1047    /// Remove `key` from the row; the family it named, if it was there.
1048    pub fn remove(&mut self, key: &HandlerKey) -> Option<EffectFamily> {
1049        self.0.remove(key)
1050    }
1051
1052    /// The family the row names `key` as.
1053    pub fn get(&self, key: &HandlerKey) -> Option<&EffectFamily> {
1054        self.0.get(key)
1055    }
1056
1057    /// Whether the row names `key`.
1058    pub fn contains_key(&self, key: &HandlerKey) -> bool {
1059        self.0.contains_key(key)
1060    }
1061
1062    /// The keys, in order.
1063    pub fn keys(&self) -> impl Iterator<Item = &HandlerKey> {
1064        self.0.keys()
1065    }
1066
1067    /// The entries, in key order.
1068    pub fn iter(&self) -> impl Iterator<Item = (&HandlerKey, &EffectFamily)> {
1069        self.0.iter()
1070    }
1071
1072    /// How many keys the row names.
1073    pub fn len(&self) -> usize {
1074        self.0.len()
1075    }
1076
1077    /// Whether the row names no key.
1078    pub fn is_empty(&self) -> bool {
1079        self.0.is_empty()
1080    }
1081
1082    /// Validates that every key is served with the required family, returning
1083    /// the first gap in key order. Uses the first descriptor matching each key.
1084    pub fn is_subset_of(&self, handlers: &[HandlerDescriptor]) -> Result<(), RowGap> {
1085        for (key, needed) in &self.0 {
1086            let served = handlers
1087                .iter()
1088                .find(|descriptor| &descriptor.key == key)
1089                .map(|descriptor| descriptor.family.family());
1090            match served {
1091                Some(served) if served == *needed => {}
1092                served => {
1093                    return Err(RowGap {
1094                        key: key.clone(),
1095                        needed: *needed,
1096                        served,
1097                    });
1098                }
1099            }
1100        }
1101        Ok(())
1102    }
1103
1104    /// Returns missing and mismatched entries in this row's key order, followed
1105    /// by extra entries in the other row's key order.
1106    pub fn diff(&self, other: &EffectRow) -> Vec<RowDiff> {
1107        let mut diffs = Vec::new();
1108        for (key, family) in &self.0 {
1109            match other.0.get(key) {
1110                None => diffs.push(RowDiff::Missing {
1111                    key: key.clone(),
1112                    family: *family,
1113                }),
1114                Some(theirs) if theirs != family => diffs.push(RowDiff::Family {
1115                    key: key.clone(),
1116                    this: *family,
1117                    other: *theirs,
1118                }),
1119                Some(_) => {}
1120            }
1121        }
1122        for (key, family) in &other.0 {
1123            if !self.0.contains_key(key) {
1124                diffs.push(RowDiff::Extra {
1125                    key: key.clone(),
1126                    family: *family,
1127                });
1128            }
1129        }
1130        diffs
1131    }
1132}
1133
1134impl FromIterator<(HandlerKey, EffectFamily)> for EffectRow {
1135    fn from_iter<I: IntoIterator<Item = (HandlerKey, EffectFamily)>>(iter: I) -> Self {
1136        Self(iter.into_iter().collect())
1137    }
1138}
1139
1140impl<'a> IntoIterator for &'a EffectRow {
1141    type Item = (&'a HandlerKey, &'a EffectFamily);
1142    type IntoIter = std::collections::btree_map::Iter<'a, HandlerKey, EffectFamily>;
1143
1144    fn into_iter(self) -> Self::IntoIter {
1145        self.0.iter()
1146    }
1147}
1148
1149impl IntoIterator for EffectRow {
1150    type Item = (HandlerKey, EffectFamily);
1151    type IntoIter = std::collections::btree_map::IntoIter<HandlerKey, EffectFamily>;
1152
1153    fn into_iter(self) -> Self::IntoIter {
1154        self.0.into_iter()
1155    }
1156}
1157
1158// The protocol crosses threads and serializes on every target.
1159const _: fn() = || {
1160    fn assert_wire<T: Clone + Send + Sync + 'static + Serialize + serde::de::DeserializeOwned>() {}
1161    assert_wire::<EffectId>();
1162    assert_wire::<HandlerKey>();
1163    assert_wire::<EffectFamily>();
1164    assert_wire::<HandlerDescriptor>();
1165    assert_wire::<FamilyDescriptor>();
1166    assert_wire::<ToolEmbeddingDescriptor>();
1167    assert_wire::<EmbedModality>();
1168    assert_wire::<EffectKind>();
1169    assert_wire::<EmbedInputs>();
1170    assert_wire::<RerankRequest>();
1171    assert_wire::<RetrieveQuery>();
1172    assert_wire::<Answered>();
1173    assert_wire::<EmbedOutputs>();
1174    assert_wire::<RetrievedDocuments>();
1175    assert_wire::<EffectRecord>();
1176    assert_wire::<Decider>();
1177    assert_wire::<EffectRow>();
1178    assert_wire::<StreamRecord>();
1179};
1180
1181#[cfg(test)]
1182mod tests;