aimux_core/
stream_part.rs

1//! `StreamPart` — the individual chunk types emitted by `do_stream`.
2//!
3//! Aligned with V4 `LanguageModelV4StreamPart`. v0.1 implements the P0/P1 variants;
4//! P2 variants (reasoning, file, source) are defined but not yet emitted by providers.
5
6use serde::{Deserialize, Serialize};
7use serde_json::Value;
8use ts_rs::TS;
9
10use crate::error::AiMuxError;
11use crate::shared::FileData;
12use crate::types::{FinishReason, ProviderMetadata, Usage, Warning};
13
14/// A single chunk in the stream returned by `do_stream`.
15#[derive(Debug, Clone, Serialize, Deserialize, TS)]
16#[ts(export)]
17pub enum StreamPart {
18    // ── P0: text ──
19    /// Start of a text segment.
20    TextStart {
21        id: String,
22        #[serde(default, skip_serializing_if = "Option::is_none")]
23        provider_metadata: Option<ProviderMetadata>,
24    },
25    /// A delta of generated text.
26    TextDelta {
27        id: String,
28        delta: String,
29        #[serde(default, skip_serializing_if = "Option::is_none")]
30        provider_metadata: Option<ProviderMetadata>,
31    },
32    /// End of a text segment.
33    TextEnd {
34        id: String,
35        #[serde(default, skip_serializing_if = "Option::is_none")]
36        provider_metadata: Option<ProviderMetadata>,
37    },
38
39    // ── P0: stream lifecycle ──
40    /// First chunk — carries warnings from the provider.
41    StreamStart { warnings: Vec<Warning> },
42    /// Final chunk — carries usage, finish reason, and metadata.
43    Finish {
44        finish_reason: FinishReason,
45        usage: Usage,
46        provider_metadata: Option<ProviderMetadata>,
47    },
48    /// An error occurred mid-stream.
49    Error { error: AiMuxError },
50
51    // ── P1: tool calls ──
52    /// Start of a tool call's input streaming.
53    ToolInputStart {
54        id: String,
55        tool_name: String,
56        /// Whether the tool call will be executed by the provider.
57        #[serde(default, skip_serializing_if = "Option::is_none")]
58        provider_executed: Option<bool>,
59        /// Whether the tool is dynamic (defined at runtime, e.g. MCP tools).
60        #[serde(default, skip_serializing_if = "Option::is_none")]
61        dynamic: Option<bool>,
62        /// Optional title for the tool call.
63        #[serde(default, skip_serializing_if = "Option::is_none")]
64        title: Option<String>,
65        #[serde(default, skip_serializing_if = "Option::is_none")]
66        provider_metadata: Option<ProviderMetadata>,
67    },
68    /// A delta of tool call input (partial JSON).
69    ToolInputDelta {
70        id: String,
71        delta: String,
72        #[serde(default, skip_serializing_if = "Option::is_none")]
73        provider_metadata: Option<ProviderMetadata>,
74    },
75    /// End of a tool call's input streaming.
76    ToolInputEnd {
77        id: String,
78        #[serde(default, skip_serializing_if = "Option::is_none")]
79        provider_metadata: Option<ProviderMetadata>,
80    },
81    /// A complete tool call (alternative to the start/delta/end flow).
82    ToolCall {
83        tool_call_id: String,
84        tool_name: String,
85        input: Value,
86        /// Whether the tool call will be executed by the provider.
87        #[serde(default, skip_serializing_if = "Option::is_none")]
88        provider_executed: Option<bool>,
89        /// Whether the tool is dynamic (defined at runtime, e.g. MCP tools).
90        #[serde(default, skip_serializing_if = "Option::is_none")]
91        dynamic: Option<bool>,
92        #[serde(default, skip_serializing_if = "Option::is_none")]
93        provider_metadata: Option<ProviderMetadata>,
94    },
95    /// A tool result (provider-executed tools).
96    ToolResult {
97        tool_call_id: String,
98        tool_name: String,
99        result: Value,
100        /// Whether the result is an error or error message.
101        #[serde(default, skip_serializing_if = "Option::is_none")]
102        is_error: Option<bool>,
103        /// Whether the result is preliminary (replaces prior, e.g. image previews).
104        #[serde(default, skip_serializing_if = "Option::is_none")]
105        preliminary: Option<bool>,
106        /// Whether the tool is dynamic (defined at runtime, e.g. MCP tools).
107        #[serde(default, skip_serializing_if = "Option::is_none")]
108        dynamic: Option<bool>,
109        /// Additional provider-specific metadata for the tool result.
110        #[serde(default, skip_serializing_if = "Option::is_none")]
111        provider_metadata: Option<ProviderMetadata>,
112    },
113
114    // ── P2: file ──
115    /// A file generated by the model (e.g. an image or document).
116    ///
117    /// Mirrors the Vercel AI SDK `file` stream part. `data` is a tagged union
118    /// covering base64 data, URL, or provider reference.
119    File {
120        data: FileData,
121        media_type: String,
122        #[serde(default, skip_serializing_if = "Option::is_none")]
123        provider_metadata: Option<ProviderMetadata>,
124    },
125
126    // ── P2: reasoning ──
127    ReasoningStart {
128        id: String,
129        /// Provider-specific metadata (e.g. xAI `itemId`).
130        #[allow(unused)]
131        provider_metadata: Option<ProviderMetadata>,
132    },
133    ReasoningDelta {
134        id: String,
135        delta: String,
136        /// Provider-specific metadata (e.g. xAI `itemId`).
137        #[allow(unused)]
138        provider_metadata: Option<ProviderMetadata>,
139    },
140    ReasoningEnd {
141        id: String,
142        /// Provider-specific metadata (e.g. xAI `itemId`, `reasoningEncryptedContent`).
143        #[allow(unused)]
144        provider_metadata: Option<ProviderMetadata>,
145    },
146
147    // ── P2: metadata ──
148    /// Response metadata (id, timestamp, model_id).
149    ResponseMetadata {
150        id: Option<String>,
151        timestamp: Option<String>,
152        model_id: Option<String>,
153    },
154
155    /// A source / citation (e.g. URL citation from search-preview models).
156    Source {
157        id: String,
158        source_type: String,
159        url: Option<String>,
160        title: Option<String>,
161        #[serde(default, skip_serializing_if = "Option::is_none")]
162        provider_metadata: Option<ProviderMetadata>,
163    },
164
165    /// A raw chunk from the provider (for debugging, when `include_raw_chunks` is set).
166    Raw { raw_value: Value },
167}
aimux_core/stream_part.rs

aimux_core/
stream_part.rs
