Skip to main content

rig_core/streaming/
event.rs

1//! The events of a completion stream. A completion decoder never builds one:
2//! it writes through the reply's part handles
3//! ([`Out`](crate::wire::Out)), and the writer emits each part's start, its
4//! fragments and its end, in that order. A [`Part`] is a part's position in
5//! the response's `choice`. A stream transform that splits or adds parts
6//! (reasoning a model wrote inside its text, tool calls written as text)
7//! numbers its own with [`Part::new`]. An item also reads back from its
8//! serialized form on its own, unchecked, so a client can decode a relayed
9//! stream as it arrives; [`StreamRecord::parse`] is the one place a sequence
10//! is checked.
11//!
12//! ```
13//! use rig_core::streaming::{PartKind, StreamEvent, StreamRecord};
14//!
15//! let transcript = StreamRecord::parse(serde_json::json!([
16//!     {"item": "event", "value": {"event": "start", "part": 0, "kind": "text"}},
17//!     {"item": "event", "value": {"event": "text", "part": 0, "text": "Hello"}},
18//!     {"item": "event", "value": {"event": "end", "part": 0,
19//!         "content": {"type": "text", "text": "Hello"}}},
20//! ]))?;
21//! assert!(matches!(
22//!     transcript.events().next(),
23//!     Some(StreamEvent::Start { kind: PartKind::Text, .. })
24//! ));
25//! # Ok::<(), rig_core::streaming::SequenceError>(())
26//! ```
27
28use std::collections::btree_map::Entry;
29
30use serde::{Deserialize, Serialize};
31
32use crate::message::{AssistantContent, ToolName};
33
34use super::UnknownPayload;
35
36/// A part's position in the response's `choice`. A transform that rewrites
37/// a stream numbers the parts it emits with [`Self::new`], and keeps the
38/// order [`StreamRecord::parse`] checks: each part starts, grows and ends, and
39/// parts are numbered in the order they start.
40///
41/// ```
42/// use rig_core::streaming::Part;
43///
44/// assert_eq!(Part::new(2).index(), 2);
45/// ```
46#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]
47#[serde(transparent)]
48pub struct Part(u32);
49
50impl Part {
51    /// The part at position `index` of the response's `choice`.
52    pub const fn new(index: u32) -> Self {
53        Self(index)
54    }
55
56    /// The part's position in the response's `choice`.
57    pub const fn index(self) -> usize {
58        self.0 as usize
59    }
60}
61
62/// What kind of part a [`StreamEvent::Start`] opened.
63#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
64#[serde(rename_all = "snake_case")]
65pub enum PartKind {
66    /// Answer text.
67    Text,
68    /// Reasoning.
69    Reasoning,
70    /// A tool call.
71    ToolCall,
72    /// An image.
73    Image,
74    /// A provider item with no canonical meaning.
75    Opaque,
76}
77
78/// One event of a completion stream: a part starts, grows, or ends with the
79/// content it finalized. Deserializing one event checks nothing about its
80/// order; read a sequence through [`StreamRecord::parse`] to check it.
81#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
82#[serde(tag = "event", rename_all = "snake_case")]
83pub enum StreamEvent {
84    /// A part opened. A tool call opens once its tool is named, so a call
85    /// streams its arguments under a known tool.
86    Start {
87        /// The part.
88        part: Part,
89        /// What it holds.
90        kind: PartKind,
91        /// The tool a [`PartKind::ToolCall`] names as it opens; `None` for
92        /// every other kind. The call's end states the name it settled on.
93        #[serde(default, skip_serializing_if = "Option::is_none")]
94        name: Option<ToolName>,
95    },
96    /// A text part grew.
97    Text {
98        /// The part.
99        part: Part,
100        /// The fragment.
101        text: String,
102    },
103    /// A reasoning part grew.
104    Reasoning {
105        /// The part.
106        part: Part,
107        /// The fragment.
108        text: String,
109    },
110    /// A tool call's arguments grew. The fragments of one call, joined,
111    /// are the argument JSON the provider sent; read an incomplete prefix
112    /// with [`parse_partial_arguments`](super::parse_partial_arguments).
113    Arguments {
114        /// The part.
115        part: Part,
116        /// The fragment of raw argument JSON.
117        json: String,
118    },
119    /// A part ended with the content it finalized.
120    End {
121        /// The part.
122        part: Part,
123        /// The finalized content.
124        content: AssistantContent,
125    },
126}
127
128impl StreamEvent {
129    /// The part this event is about.
130    pub const fn part(&self) -> Part {
131        match self {
132            Self::Start { part, .. }
133            | Self::Text { part, .. }
134            | Self::Reasoning { part, .. }
135            | Self::Arguments { part, .. }
136            | Self::End { part, .. } => *part,
137        }
138    }
139
140    /// A stable variant name that exposes no payload to logs.
141    pub const fn name(&self) -> &'static str {
142        match self {
143            Self::Start { .. } => "Start",
144            Self::Text { .. } => "Text",
145            Self::Reasoning { .. } => "Reasoning",
146            Self::Arguments { .. } => "Arguments",
147            Self::End { .. } => "End",
148        }
149    }
150
151    /// The events a stream writes for `content` arriving whole as the part
152    /// at `part`: its start, its text, reasoning or argument text as one
153    /// fragment, and its end holding `content`. Empty text writes no
154    /// fragment. A call's fragment is its
155    /// [`raw_arguments`](crate::message::ToolFunction::raw_arguments): the
156    /// text the model sent when it was not an object, else the object.
157    ///
158    /// ```
159    /// use rig_core::message::AssistantContent;
160    /// use rig_core::streaming::{Part, StreamEvent};
161    ///
162    /// let events = StreamEvent::whole(Part::new(0), &AssistantContent::text("Hi"));
163    /// let names: Vec<_> = events.iter().map(StreamEvent::name).collect();
164    /// assert_eq!(names, ["Start", "Text", "End"]);
165    /// ```
166    pub fn whole(part: Part, content: &AssistantContent) -> Vec<Self> {
167        let name = content
168            .as_tool_call()
169            .map(|call| call.function.name.clone());
170        let start = Self::Start {
171            part,
172            kind: PartKind::of(content),
173            name,
174        };
175        let end = Self::End {
176            part,
177            content: content.clone(),
178        };
179        [start]
180            .into_iter()
181            .chain(Self::fragment(part, content))
182            .chain([end])
183            .collect()
184    }
185
186    /// `content`'s whole text, reasoning or argument text as one fragment
187    /// of `part`, or `None` when it is empty or `content` has none.
188    pub(crate) fn fragment(part: Part, content: &AssistantContent) -> Option<Self> {
189        match content {
190            AssistantContent::Text(text) if !text.text.is_empty() => Some(Self::Text {
191                part,
192                text: text.text.clone(),
193            }),
194            AssistantContent::Reasoning(reasoning) if !reasoning.text.is_empty() => {
195                Some(Self::Reasoning {
196                    part,
197                    text: reasoning.text.clone(),
198                })
199            }
200            AssistantContent::ToolCall(call) => {
201                let json = call.function.raw_arguments();
202                (!json.is_empty()).then_some(Self::Arguments { part, json })
203            }
204            _ => None,
205        }
206    }
207}
208
209impl PartKind {
210    /// The kind of part that holds `content`.
211    pub(crate) const fn of(content: &AssistantContent) -> Self {
212        match content {
213            AssistantContent::Text(_) => Self::Text,
214            AssistantContent::Reasoning(_) => Self::Reasoning,
215            AssistantContent::ToolCall(_) => Self::ToolCall,
216            AssistantContent::Image(_) => Self::Image,
217            AssistantContent::Opaque(_) => Self::Opaque,
218        }
219    }
220}
221
222/// One item of a stream: an event of the operation, or a payload the
223/// provider sent that the decoder does not model. An unmodeled payload
224/// always reaches the consumer.
225#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
226#[serde(tag = "item", content = "value", rename_all = "snake_case")]
227pub enum Item<E> {
228    /// An event of the operation.
229    Event(E),
230    /// A payload the decoder does not model.
231    Unknown(UnknownPayload),
232}
233
234/// A completion stream's items read back from their serialized form, in an
235/// order the writer could have produced: each part starts once, at a
236/// position no part took before, grows only while open and with its own
237/// kind of fragment, and ends once. Positions follow the order provider
238/// items opened, so a dropped item leaves a gap. Unmodeled payloads may come
239/// anywhere.
240#[derive(Debug, Clone, Default)]
241pub struct StreamRecord {
242    items: Vec<Item<StreamEvent>>,
243    /// Each started part's kind, and whether it ended.
244    parts: std::collections::BTreeMap<usize, (PartKind, bool)>,
245}
246
247impl PartialEq for StreamRecord {
248    fn eq(&self, other: &Self) -> bool {
249        self.items == other.items
250    }
251}
252
253impl Serialize for StreamRecord {
254    fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
255        self.items.serialize(serializer)
256    }
257}
258
259/// Why a serialized event sequence is not one the writer could produce.
260#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
261pub enum SequenceError {
262    /// The value is not a list of stream items.
263    #[error("not a list of stream items: {0}")]
264    Shape(String),
265    /// An event names a part that has not started, or a start reuses a
266    /// position.
267    #[error("item {0} names a part that has not started, or starts one twice")]
268    UnknownPart(usize),
269    /// A part ended twice, or grew after its end.
270    #[error("item {0} touches a part that already ended")]
271    EndedTwice(usize),
272    /// A fragment or end does not match the part's kind, or a start names a
273    /// tool for a part that is not a call, or none for one that is.
274    #[error("item {0} does not match its part's kind")]
275    WrongKind(usize),
276    /// A part started and never ended.
277    #[error("part {0} never ended")]
278    Unclosed(usize),
279}
280
281impl StreamRecord {
282    /// Read a serialized item sequence, refusing one the writer could not
283    /// have produced. Every part must have ended.
284    pub fn parse(value: serde_json::Value) -> Result<Self, SequenceError> {
285        let transcript = Self::parse_prefix(value)?;
286        transcript.check_closed()?;
287        Ok(transcript)
288    }
289
290    /// [`Self::parse`] for a stream that stopped early (an error or a
291    /// cancellation): parts may still be open at its end.
292    pub fn parse_prefix(value: serde_json::Value) -> Result<Self, SequenceError> {
293        let items: Vec<Item<StreamEvent>> = crate::json_utils::from_value(&value)
294            .map_err(|error| SequenceError::Shape(error.to_string()))?;
295        Self::from_items(items)
296    }
297
298    /// Append the next item a stream yielded, refusing one the writer could
299    /// not have produced after the items so far.
300    pub fn push(&mut self, item: Item<StreamEvent>) -> Result<(), SequenceError> {
301        let position = self.items.len();
302        if let Item::Event(event) = &item {
303            let index = event.part().index();
304            let kind = match event {
305                StreamEvent::Start { kind, name, .. } => {
306                    if (*kind == PartKind::ToolCall) != name.is_some() {
307                        return Err(SequenceError::WrongKind(position));
308                    }
309                    let Entry::Vacant(part) = self.parts.entry(index) else {
310                        return Err(SequenceError::UnknownPart(position));
311                    };
312                    part.insert((*kind, false));
313                    None
314                }
315                StreamEvent::Text { .. } => Some(PartKind::Text),
316                StreamEvent::Reasoning { .. } => Some(PartKind::Reasoning),
317                StreamEvent::Arguments { .. } => Some(PartKind::ToolCall),
318                StreamEvent::End { content, .. } => Some(PartKind::of(content)),
319            };
320            if let Some(kind) = kind {
321                match self.parts.get_mut(&index) {
322                    None => return Err(SequenceError::UnknownPart(position)),
323                    Some((_, true)) => return Err(SequenceError::EndedTwice(position)),
324                    Some((open, false)) if *open != kind => {
325                        return Err(SequenceError::WrongKind(position));
326                    }
327                    Some((_, ended)) => *ended = matches!(event, StreamEvent::End { .. }),
328                }
329            }
330        }
331        self.items.push(item);
332        Ok(())
333    }
334
335    fn check_closed(&self) -> Result<(), SequenceError> {
336        match self.parts.iter().find(|(_, (_, ended))| !ended) {
337            Some((part, _)) => Err(SequenceError::Unclosed(*part)),
338            None => Ok(()),
339        }
340    }
341
342    /// Items a stream yielded, checked as [`Self::push`] checks them: a
343    /// stream that stopped early may leave parts open.
344    pub fn from_items(items: Vec<Item<StreamEvent>>) -> Result<Self, SequenceError> {
345        let mut transcript = Self::default();
346        for item in items {
347            transcript.push(item)?;
348        }
349        Ok(transcript)
350    }
351
352    /// The number of items.
353    pub fn len(&self) -> usize {
354        self.items.len()
355    }
356
357    /// Whether there are no items.
358    pub fn is_empty(&self) -> bool {
359        self.items.is_empty()
360    }
361
362    /// The items, in order.
363    pub fn items(&self) -> &[Item<StreamEvent>] {
364        &self.items
365    }
366
367    /// The items, in order.
368    pub fn into_items(self) -> Vec<Item<StreamEvent>> {
369        self.items
370    }
371
372    /// The events, in order, without the unmodeled payloads.
373    pub fn events(&self) -> impl Iterator<Item = &StreamEvent> {
374        self.items.iter().filter_map(|item| match item {
375            Item::Event(event) => Some(event),
376            Item::Unknown(_) => None,
377        })
378    }
379}
380
381impl From<StreamRecord> for Vec<Item<StreamEvent>> {
382    fn from(transcript: StreamRecord) -> Self {
383        transcript.items
384    }
385}
386
387/// Read as the item list it is, with no `Value` tree between.
388impl<'de> Deserialize<'de> for StreamRecord {
389    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
390        let items = Vec::<Item<StreamEvent>>::deserialize(deserializer)
391            .map_err(|error| serde::de::Error::custom(SequenceError::Shape(error.to_string())))?;
392        Self::from_items(items).map_err(serde::de::Error::custom)
393    }
394}
395
396// The stream vocabulary crosses threads on every target: a handler sends it
397// over a channel, the effect log records it, and a client reads it back.
398const _: fn() = || {
399    fn assert_wire<T: Clone + Send + Sync + 'static + Serialize + serde::de::DeserializeOwned>() {}
400    assert_wire::<StreamEvent>();
401    assert_wire::<StreamRecord>();
402    assert_wire::<Item<StreamEvent>>();
403};
404
405#[cfg(test)]
406mod tests;