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