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;