1use serde::{Deserialize, Serialize};
26
27use crate::message::AssistantContent;
28
29use super::UnknownPayload;
30
31#[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 pub const fn index(self) -> usize {
48 self.0 as usize
49 }
50}
51
52#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
54#[serde(rename_all = "snake_case")]
55pub enum PartKind {
56 Text,
58 Reasoning,
60 ToolCall,
62 Image,
64}
65
66#[derive(Debug, Clone, PartialEq, Serialize)]
69#[serde(tag = "event", rename_all = "snake_case")]
70pub enum StreamEvent {
71 Start {
73 part: Part,
75 kind: PartKind,
77 },
78 Text {
80 part: Part,
82 text: String,
84 },
85 Reasoning {
87 part: Part,
89 text: String,
91 },
92 Arguments {
94 part: Part,
96 json: String,
98 },
99 End {
101 part: Part,
103 content: AssistantContent,
105 },
106}
107
108impl StreamEvent {
109 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 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#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
136#[serde(tag = "item", content = "value", rename_all = "snake_case")]
137pub enum Item<E> {
138 Event(E),
140 Unknown(UnknownPayload),
142}
143
144#[derive(Debug, Clone, Default)]
149pub struct Transcript {
150 items: Vec<Item<StreamEvent>>,
151 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#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
169pub enum SequenceError {
170 #[error("not a list of stream items: {0}")]
172 Shape(String),
173 #[error("item {0} names a part that has not started")]
176 UnknownPart(usize),
177 #[error("item {0} touches a part that already ended")]
179 EndedTwice(usize),
180 #[error("item {0} does not match its part's kind")]
182 WrongKind(usize),
183 #[error("part {0} never ended")]
185 Unclosed(usize),
186}
187
188#[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 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 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 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 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 pub fn len(&self) -> usize {
319 self.items.len()
320 }
321
322 pub fn is_empty(&self) -> bool {
324 self.items.is_empty()
325 }
326
327 pub fn items(&self) -> &[Item<StreamEvent>] {
329 &self.items
330 }
331
332 pub fn into_items(self) -> Vec<Item<StreamEvent>> {
334 self.items
335 }
336
337 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
359const _: 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;