Skip to main content

rig_core/test_utils/
streaming.rs

1//! Streaming helpers for [`MockCompletionModel`](super::MockCompletionModel):
2//! the script a mock reply is written from, and the decoder that writes it
3//! through the completion writer's part handles, as a wire's decoder does.
4
5use std::collections::HashMap;
6
7use crate::completion::{CompletionResponse, Usage};
8use crate::error::ProviderError;
9use crate::message::ReasoningContent;
10use crate::operation::{
11    CallFragment, Completion, Finish, IfMalformed, ReasoningPart, Seal, TextPart,
12};
13use crate::wire::{Decoder, Flow, Out, WireEvent};
14
15/// Provider descriptor name reported by the test doubles.
16pub const MOCK_PROVIDER: &str = "mock";
17
18/// The end the mock model's reply finishes with, carrying `usage`.
19pub fn mock_final(usage: Usage) -> Finish {
20    Finish {
21        usage,
22        ..Finish::default()
23    }
24}
25
26/// Convert a fixture JSON value into canonical params: `null`/`{}` mean
27/// "none", any other non-object is a scripting mistake surfaced as a stream
28/// error.
29fn fixture_additional_params(
30    value: serde_json::Value,
31) -> Result<Option<crate::message::AdditionalParams>, ProviderError> {
32    crate::message::AdditionalParams::try_from_value(value).map_err(|other| {
33        ProviderError::Provider(format!(
34            "mock stream fixture `additional_params` must be a JSON object, got: {other}"
35        ))
36    })
37}
38
39/// The end of a reply whose usage has only `total_tokens` set.
40pub fn mock_final_with_total_tokens(total_tokens: u64) -> Finish {
41    mock_final(Usage {
42        total_tokens: Some(total_tokens),
43        ..Default::default()
44    })
45}
46
47/// Scripted streaming event yielded by [`MockCompletionModel`](super::MockCompletionModel).
48#[derive(Clone, Debug, PartialEq, serde::Serialize, serde::Deserialize)]
49pub enum MockStreamEvent {
50    /// Text chunk.
51    Text(String),
52    /// Start a new text part with optional provider metadata.
53    TextStart {
54        id: String,
55        additional_params: Option<serde_json::Value>,
56    },
57    /// Provider-specific metadata for the current text part.
58    TextAdditionalParams(serde_json::Value),
59    /// Complete tool call event.
60    ToolCall {
61        id: String,
62        name: String,
63        arguments: serde_json::Value,
64        call_id: Option<String>,
65    },
66    /// A tool call's name, as a wire streams it.
67    ToolCallNameDelta { id: String, name: String },
68    /// A fragment of a tool call's arguments.
69    ToolCallArgumentsDelta { id: String, arguments: String },
70    /// The end of a tool call streamed as fragments: the call closes with
71    /// what they carried, as a wire's step-stop does.
72    ToolCallEnd { id: String },
73    /// Complete reasoning event.
74    Reasoning {
75        id: String,
76        content: ReasoningContent,
77    },
78    /// Reasoning delta event.
79    ReasoningDelta { id: String, reasoning: String },
80    /// Provider-assigned message ID.
81    MessageId(String),
82    /// Provider-native output item that Rig does not model.
83    Unknown(serde_json::Value),
84    /// The transport request id of this turn. The mock transport reports
85    /// it, as a real transport reports a response header; the decoder never
86    /// sees it. Its position in the turn does not matter; when a turn
87    /// scripts more than one, the first wins.
88    RequestId(String),
89    /// The provider's end of the reply.
90    FinalResponse(Finish),
91    /// A failure, which ends the reply.
92    Error(MockError),
93}
94
95use super::completion::MockError;
96
97/// The provider id a fixture spells, when it spells one. Corpus fixtures
98/// are plain data: the renderings `reasoning-0`, `block-3`, `output-1`,
99/// `tool-2` and `text-0` name a part the wire gave no id, and anything else
100/// is the wire's own id.
101fn fixture_provider_id(id: &str) -> Option<&str> {
102    let unnamed = ["reasoning-", "block-", "output-", "tool-", "text-"]
103        .iter()
104        .any(|namespace| {
105            id.strip_prefix(namespace)
106                .is_some_and(|rest| rest.parse::<u64>().is_ok())
107        });
108    (!id.is_empty() && !unnamed).then_some(id)
109}
110
111impl MockStreamEvent {
112    /// Create a text chunk.
113    pub fn text(text: impl Into<String>) -> Self {
114        Self::Text(text.into())
115    }
116
117    /// Start a new text content block identified by `id`.
118    pub fn text_start(id: impl Into<String>, additional_params: Option<serde_json::Value>) -> Self {
119        Self::TextStart {
120            id: id.into(),
121            additional_params,
122        }
123    }
124
125    /// Add provider-specific metadata to the current text content block.
126    pub fn text_additional_params(additional_params: serde_json::Value) -> Self {
127        Self::TextAdditionalParams(additional_params)
128    }
129
130    /// Create a complete tool call event.
131    pub fn tool_call(
132        id: impl Into<String>,
133        name: impl Into<String>,
134        arguments: serde_json::Value,
135    ) -> Self {
136        Self::ToolCall {
137            id: id.into(),
138            name: name.into(),
139            arguments,
140            call_id: None,
141        }
142    }
143
144    /// Attach a provider-specific call ID to a complete tool call event.
145    pub fn with_call_id(mut self, call_id: impl Into<String>) -> Self {
146        if let Self::ToolCall { call_id: id, .. } = &mut self {
147            *id = Some(call_id.into());
148        }
149        self
150    }
151
152    /// Create a tool call name delta.
153    pub fn tool_call_name_delta(id: impl Into<String>, name: impl Into<String>) -> Self {
154        Self::ToolCallNameDelta {
155            id: id.into(),
156            name: name.into(),
157        }
158    }
159
160    /// Create a tool call arguments delta.
161    pub fn tool_call_arguments_delta(id: impl Into<String>, arguments: impl Into<String>) -> Self {
162        Self::ToolCallArgumentsDelta {
163            id: id.into(),
164            arguments: arguments.into(),
165        }
166    }
167
168    /// Create the end of a tool call streamed as deltas.
169    pub fn tool_call_end(id: impl Into<String>) -> Self {
170        Self::ToolCallEnd { id: id.into() }
171    }
172
173    /// Create a complete reasoning event with the default mock id
174    /// (`"reasoning-0"`). Use [`Self::with_reasoning_id`] for tests that
175    /// need distinct reasoning items.
176    pub fn reasoning(reasoning: impl Into<String>) -> Self {
177        Self::Reasoning {
178            id: "reasoning-0".to_string(),
179            content: ReasoningContent::Text {
180                text: reasoning.into(),
181                signature: None,
182            },
183        }
184    }
185
186    /// Attach a provider-specific reasoning ID to a complete reasoning event.
187    pub fn with_reasoning_id(mut self, reasoning_id: impl Into<String>) -> Self {
188        if let Self::Reasoning { id, .. } = &mut self {
189            *id = reasoning_id.into();
190        }
191        self
192    }
193
194    /// Create a reasoning delta event with the default mock id
195    /// (`"reasoning-0"`). Use [`Self::reasoning_delta_with_id`] for tests
196    /// that need distinct reasoning items.
197    pub fn reasoning_delta(reasoning: impl Into<String>) -> Self {
198        Self::reasoning_delta_with_id("reasoning-0", reasoning)
199    }
200
201    /// Create a reasoning delta event with an explicit reasoning item id.
202    pub fn reasoning_delta_with_id(id: impl Into<String>, reasoning: impl Into<String>) -> Self {
203        Self::ReasoningDelta {
204            id: id.into(),
205            reasoning: reasoning.into(),
206        }
207    }
208
209    /// Create a provider-assigned message ID event.
210    pub fn message_id(id: impl Into<String>) -> Self {
211        Self::MessageId(id.into())
212    }
213
214    /// Create an unmodeled provider output item.
215    pub fn unknown(value: serde_json::Value) -> Self {
216        Self::Unknown(value)
217    }
218
219    /// Create the provider's end of the reply, with usage.
220    pub fn final_response(usage: Usage) -> Self {
221        Self::FinalResponse(mock_final(usage))
222    }
223
224    /// Create a final response event whose usage reports no counter.
225    pub fn final_response_with_default_usage() -> Self {
226        Self::FinalResponse(mock_final(Usage::default()))
227    }
228
229    /// Create a final response event whose usage has only `total_tokens` set.
230    pub fn final_response_with_total_tokens(total_tokens: u64) -> Self {
231        Self::FinalResponse(mock_final_with_total_tokens(total_tokens))
232    }
233
234    /// Create a stream error event.
235    pub fn error(message: impl Into<String>) -> Self {
236        Self::Error(MockError::provider(message))
237    }
238}
239
240/// One step of a mock reply: a scripted event, or a whole response.
241#[derive(Clone, Debug)]
242pub enum MockFrame {
243    /// A scripted event.
244    Event(MockStreamEvent),
245    /// A whole response, as a unary turn answers.
246    Response(Box<CompletionResponse>),
247}
248
249/// The decoder of [`MockScript`](super::MockScript): each scripted step is
250/// written through the completion writer's part handles.
251#[derive(Default)]
252pub struct MockDecoder<'id> {
253    /// The text part bare text extends.
254    text: Option<TextPart<'id>>,
255    /// The reasoning part each scripted id streams into, in start order.
256    reasoning: Vec<(String, ReasoningPart<'id>)>,
257    /// The buffer index each scripted call id streams under.
258    calls: HashMap<String, usize>,
259    next_call: usize,
260}
261
262impl<'id> MockDecoder<'id> {
263    fn close_text(&mut self, out: &mut Out<'id, Completion>) {
264        if let Some(part) = self.text.take() {
265            out.close_text(part);
266        }
267    }
268
269    fn call_index(&mut self, id: &str) -> usize {
270        if let Some(index) = self.calls.get(id) {
271            return *index;
272        }
273        let index = self.next_call;
274        self.next_call += 1;
275        if !id.is_empty() {
276            self.calls.insert(id.to_owned(), index);
277        }
278        index
279    }
280
281    fn event(
282        &mut self,
283        event: MockStreamEvent,
284        mut out: Out<'id, Completion>,
285    ) -> Result<Flow, ProviderError> {
286        match event {
287            MockStreamEvent::Text(text) => {
288                let part = self.text.get_or_insert_with(|| out.text());
289                out.push_text(part, &text);
290            }
291            MockStreamEvent::TextStart {
292                id: _,
293                additional_params,
294            } => {
295                self.close_text(&mut out);
296                let part = out.text();
297                if let Some(params) = additional_params
298                    .map(fixture_additional_params)
299                    .transpose()?
300                    .flatten()
301                {
302                    out.text_params(&part, params);
303                }
304                self.text = Some(part);
305            }
306            MockStreamEvent::TextAdditionalParams(additional_params) => {
307                // The real metadata is non-empty by construction; an empty
308                // fixture object is a scripting mistake, not a no-op.
309                let Some(params) = fixture_additional_params(additional_params)? else {
310                    return Err(ProviderError::Provider(
311                        "mock stream fixture `TextAdditionalParams` carries no data — \
312                         drop the event instead"
313                            .to_string(),
314                    ));
315                };
316                let part = self.text.get_or_insert_with(|| out.text());
317                out.text_params(part, params);
318            }
319            MockStreamEvent::ToolCall {
320                id,
321                name,
322                arguments,
323                call_id,
324            } => {
325                self.close_text(&mut out);
326                // An id-less call is a wire that sends none: rig issues the
327                // id. A call id beside the wire id makes the pair a
328                // dual-identifier call. A call scripted as fragments under
329                // this id is the one this restatement closes.
330                let index = match self.calls.remove(&id) {
331                    Some(index) => index,
332                    None => self.call_index(""),
333                };
334                let wire_id = fixture_provider_id(&id);
335                out.call_fragment(
336                    index,
337                    CallFragment {
338                        id: call_id.as_deref().or(wire_id),
339                        item_id: call_id.as_ref().and(wire_id),
340                        name: Some(name.as_str()),
341                        ..CallFragment::default()
342                    },
343                )?;
344                out.announce_pending(index, arguments);
345                out.close_pending(index, IfMalformed::Fail)?;
346            }
347            MockStreamEvent::ToolCallNameDelta { id, name } => {
348                self.close_text(&mut out);
349                let index = self.call_index(&id);
350                out.call_fragment(
351                    index,
352                    CallFragment {
353                        id: fixture_provider_id(&id),
354                        name: Some(name.as_str()),
355                        ..CallFragment::default()
356                    },
357                )?;
358            }
359            MockStreamEvent::ToolCallArgumentsDelta { id, arguments } => {
360                self.close_text(&mut out);
361                let index = self.call_index(&id);
362                out.call_fragment(
363                    index,
364                    CallFragment {
365                        id: fixture_provider_id(&id),
366                        arguments: Some(arguments.as_str()),
367                        ..CallFragment::default()
368                    },
369                )?;
370            }
371            MockStreamEvent::ToolCallEnd { id } => {
372                let index = self.call_index(&id);
373                self.calls.remove(&id);
374                out.close_pending(index, IfMalformed::Fail)?;
375            }
376            MockStreamEvent::Reasoning { id, content } => {
377                self.close_text(&mut out);
378                let reasoning = crate::message::Reasoning {
379                    id: fixture_provider_id(&id).map(str::to_owned),
380                    content: vec![content],
381                };
382                // A whole reasoning restates the part streamed under its id,
383                // and closes it.
384                match self.reasoning.iter().position(|(open, _)| *open == id) {
385                    Some(at) => {
386                        let (_, part) = self.reasoning.remove(at);
387                        out.close_reasoning(
388                            part,
389                            Seal {
390                                id: reasoning.id.clone(),
391                                restated: Some(reasoning),
392                                ..Seal::default()
393                            },
394                        );
395                    }
396                    None => out.reasoning_block(reasoning),
397                }
398            }
399            MockStreamEvent::ReasoningDelta { id, reasoning } => {
400                self.close_text(&mut out);
401                let at = match self.reasoning.iter().position(|(open, _)| *open == id) {
402                    Some(at) => at,
403                    None => {
404                        self.reasoning.push((id, out.reasoning()));
405                        self.reasoning.len() - 1
406                    }
407                };
408                if let Some((_, part)) = self.reasoning.get(at) {
409                    out.push_reasoning(part, &reasoning);
410                }
411            }
412            MockStreamEvent::MessageId(id) => out.message_id(id),
413            MockStreamEvent::Unknown(value) => out.unknown(value.into()),
414            MockStreamEvent::RequestId(_) => {}
415            MockStreamEvent::FinalResponse(finish) => {
416                self.close_text(&mut out);
417                for (id, part) in std::mem::take(&mut self.reasoning) {
418                    out.close_reasoning(
419                        part,
420                        Seal {
421                            id: fixture_provider_id(&id).map(str::to_owned),
422                            ..Seal::default()
423                        },
424                    );
425                }
426                // The mock's document is its scripted end, serialized.
427                out.raw(serde_json::to_value(&finish)?);
428                return Ok(out.end(finish));
429            }
430            MockStreamEvent::Error(error) => return Err(error.into_completion_error()),
431        }
432        Ok(Flow::More)
433    }
434
435    fn response(
436        &mut self,
437        response: CompletionResponse,
438        mut out: Out<'id, Completion>,
439    ) -> Result<Flow, ProviderError> {
440        for content in response.choice.iter().cloned() {
441            out.content(content)?;
442        }
443        if let Some(message_id) = response.message_id.clone() {
444            out.message_id(message_id);
445        }
446        out.raw(response.raw.clone());
447        Ok(out.end(Finish {
448            usage: response.usage,
449            reason: response.finish_reason(),
450            message_id: None,
451            response_id: response.response_id.clone(),
452            model: response.model.clone(),
453        }))
454    }
455}
456
457impl<'id> Decoder<'id, Completion, MockFrame> for MockDecoder<'id> {
458    type Event = MockFrame;
459
460    fn classify(&self, frame: MockFrame) -> WireEvent<MockFrame> {
461        WireEvent::Known(frame)
462    }
463
464    fn decode(
465        &mut self,
466        frame: MockFrame,
467        out: Out<'id, Completion>,
468    ) -> Result<Flow, ProviderError> {
469        match frame {
470            MockFrame::Event(event) => self.event(event, out),
471            MockFrame::Response(response) => self.response(*response, out),
472        }
473    }
474}