Skip to content
Source
Sign inSign up
TanStack/ai
Open History to see the last commit

converter.py

490 lines20.2 KB

1"""
2TanStack AI Stream Chunk Converter
3​
4Converts streaming events from various AI providers (Anthropic, OpenAI)
5into TanStack AI AG-UI StreamChunk format.
6​
7Implements the AG-UI (Agent-User Interaction) Protocol event types:
8- RUN_STARTED, RUN_FINISHED, RUN_ERROR (lifecycle events)
9- TEXT_MESSAGE_START, TEXT_MESSAGE_CONTENT, TEXT_MESSAGE_END (text streaming)
10- TOOL_CALL_START, TOOL_CALL_ARGS, TOOL_CALL_END (tool calling)
11- STEP_STARTED, STEP_FINISHED (thinking/reasoning)
12"""
13import json
14import uuid
15from typing import List, Dict, Any, Optional
16from datetime import datetime
17​
18​
19class StreamChunkConverter:
20 """
21 Converts provider-specific streaming events to TanStack AI AG-UI StreamChunk format.
23 Supports:
24 - Anthropic streaming events
25 - OpenAI streaming events
26 """
28 def __init__(self, model: str, provider: str = "anthropic"):
29 """
30 Initialize converter.
32 Args:
33 model: Model name (e.g., "claude-3-haiku-20240307", "gpt-4o")
34 provider: Provider type ("anthropic" or "openai")
35 """
36 self.model = model
37 self.provider = provider.lower()
38 self.timestamp = int(datetime.now().timestamp() * 1000)
39 self.accumulated_content = ""
40 self.accumulated_thinking = ""
41 self.tool_calls_map: Dict[int, Dict[str, Any]] = {}
42 self.current_tool_index = -1
43 self.run_finished = False
45 # AG-UI lifecycle tracking
46 self.run_id = self.generate_id()
47 self.message_id = self.generate_id()
48 self.step_id: Optional[str] = None
49 self.has_emitted_run_started = False
50 self.has_emitted_text_message_start = False
52 def generate_id(self) -> str:
53 """Generate a unique ID for the chunk"""
54 return f"chatcmpl-{uuid.uuid4().hex[:8]}"
56 def _get_event_type(self, event: Any) -> str:
57 """Get event type from either dict or object"""
58 if isinstance(event, dict):
59 return event.get("type", "")
60 return getattr(event, "type", "")
62 def _get_attr(self, obj: Any, attr: str, default: Any = None) -> Any:
63 """Get attribute from either dict or object"""
64 if isinstance(obj, dict):
65 return obj.get(attr, default)
66 return getattr(obj, attr, default)
68 def _maybe_emit_run_started(self) -> Optional[Dict[str, Any]]:
69 """Create RUN_STARTED event if not already emitted"""
70 if not self.has_emitted_run_started:
71 self.has_emitted_run_started = True
72 return {
73 "type": "RUN_STARTED",
74 "runId": self.run_id,
75 "model": self.model,
76 "timestamp": self.timestamp
77 }
78 return None
80 def _maybe_emit_text_message_start(self) -> Optional[Dict[str, Any]]:
81 """Create TEXT_MESSAGE_START event if not already emitted"""
82 if not self.has_emitted_text_message_start:
83 self.has_emitted_text_message_start = True
84 return {
85 "type": "TEXT_MESSAGE_START",
86 "messageId": self.message_id,
87 "model": self.model,
88 "timestamp": self.timestamp,
89 "role": "assistant"
90 }
91 return None
93 async def convert_anthropic_event(self, event: Any) -> List[Dict[str, Any]]:
94 """Convert Anthropic streaming event to AG-UI StreamChunk format"""
95 chunks = []
96 event_type = self._get_event_type(event)
98 # Emit RUN_STARTED on first event
99 run_started = self._maybe_emit_run_started()
100 if run_started:
101 chunks.append(run_started)
103 if event_type == "content_block_start":
104 content_block = self._get_attr(event, "content_block")
105 if content_block:
106 block_type = self._get_attr(content_block, "type")
108 if block_type == "tool_use":
109 # Tool call is starting
110 self.current_tool_index += 1
111 tool_id = self._get_attr(content_block, "id")
112 tool_name = self._get_attr(content_block, "name")
114 self.tool_calls_map[self.current_tool_index] = {
115 "id": tool_id,
116 "name": tool_name,
117 "input": "",
118 "started": False
119 }
120 elif block_type == "thinking":
121 # Thinking/reasoning block starting
122 self.accumulated_thinking = ""
123 self.step_id = self.generate_id()
124 chunks.append({
125 "type": "STEP_STARTED",
126 "stepId": self.step_id,
127 "model": self.model,
128 "timestamp": self.timestamp,
129 "stepType": "thinking"
130 })
132 elif event_type == "content_block_delta":
133 delta = self._get_attr(event, "delta")
135 if delta and self._get_attr(delta, "type") == "text_delta":
136 # Emit TEXT_MESSAGE_START on first text content
137 text_start = self._maybe_emit_text_message_start()
138 if text_start:
139 chunks.append(text_start)
141 # Text content delta
142 delta_text = self._get_attr(delta, "text", "")
143 self.accumulated_content += delta_text
145 chunks.append({
146 "type": "TEXT_MESSAGE_CONTENT",
147 "messageId": self.message_id,
148 "model": self.model,
149 "timestamp": self.timestamp,
150 "delta": delta_text,
151 "content": self.accumulated_content
152 })
154 elif delta and self._get_attr(delta, "type") == "thinking_delta":
155 # Thinking content delta
156 delta_thinking = self._get_attr(delta, "thinking", "")
157 self.accumulated_thinking += delta_thinking
159 chunks.append({
160 "type": "STEP_FINISHED",
161 "stepId": self.step_id or self.generate_id(),
162 "model": self.model,
163 "timestamp": self.timestamp,
164 "delta": delta_thinking,
165 "content": self.accumulated_thinking
166 })
168 elif delta and self._get_attr(delta, "type") == "input_json_delta":
169 # Tool input is being streamed
170 partial_json = self._get_attr(delta, "partial_json", "")
171 tool_call = self.tool_calls_map.get(self.current_tool_index)
173 if tool_call:
174 # Emit TOOL_CALL_START on first args delta
175 if not tool_call["started"]:
176 tool_call["started"] = True
177 chunks.append({
178 "type": "TOOL_CALL_START",
179 "toolCallId": tool_call["id"],
180 "toolName": tool_call["name"],
181 "model": self.model,
182 "timestamp": self.timestamp,
183 "index": self.current_tool_index
184 })
186 tool_call["input"] += partial_json
188 chunks.append({
189 "type": "TOOL_CALL_ARGS",
190 "toolCallId": tool_call["id"],
191 "model": self.model,
192 "timestamp": self.timestamp,
193 "delta": partial_json,
194 "args": tool_call["input"]
195 })
197 elif event_type == "content_block_stop":
198 # Content block completed
199 tool_call = self.tool_calls_map.get(self.current_tool_index)
200 if tool_call:
201 # If tool call wasn't started yet (no args), start it now
202 if not tool_call["started"]:
203 tool_call["started"] = True
204 chunks.append({
205 "type": "TOOL_CALL_START",
206 "toolCallId": tool_call["id"],
207 "toolName": tool_call["name"],
208 "model": self.model,
209 "timestamp": self.timestamp,
210 "index": self.current_tool_index
211 })
213 # Parse input and emit TOOL_CALL_END
214 parsed_input = {}
215 if tool_call["input"]:
216 try:
217 parsed_input = json.loads(tool_call["input"])
218 except json.JSONDecodeError:
219 parsed_input = {}
221 chunks.append({
222 "type": "TOOL_CALL_END",
223 "toolCallId": tool_call["id"],
224 "toolName": tool_call["name"],
225 "model": self.model,
226 "timestamp": self.timestamp,
227 "input": parsed_input
228 })
230 # Emit TEXT_MESSAGE_END if we had text content
231 if self.has_emitted_text_message_start and self.accumulated_content:
232 chunks.append({
233 "type": "TEXT_MESSAGE_END",
234 "messageId": self.message_id,
235 "model": self.model,
236 "timestamp": self.timestamp
237 })
239 elif event_type == "message_delta":
240 # Message metadata update (includes stop_reason and usage)
241 delta = self._get_attr(event, "delta")
242 usage = self._get_attr(event, "usage")
244 stop_reason = self._get_attr(delta, "stop_reason") if delta else None
245 if stop_reason:
246 usage_dict = None
247 if usage:
248 usage_dict = {
249 "promptTokens": self._get_attr(usage, "input_tokens", 0),
250 "completionTokens": self._get_attr(usage, "output_tokens", 0),
251 "totalTokens": self._get_attr(usage, "input_tokens", 0) + self._get_attr(usage, "output_tokens", 0)
252 }
254 # Handle max_tokens as error
255 if stop_reason == "max_tokens":
256 self.run_finished = True
257 chunks.append({
258 "type": "RUN_ERROR",
259 "runId": self.run_id,
260 "model": self.model,
261 "timestamp": self.timestamp,
262 "error": {
263 "message": "The response was cut off because the maximum token limit was reached.",
264 "code": "max_tokens"
265 }
266 })
267 else:
268 # Map Anthropic stop_reason to TanStack format
269 finish_reason = {
270 "tool_use": "tool_calls",
271 "end_turn": "stop"
272 }.get(stop_reason, stop_reason)
274 self.run_finished = True
275 chunks.append({
276 "type": "RUN_FINISHED",
277 "runId": self.run_id,
278 "model": self.model,
279 "timestamp": self.timestamp,
280 "finishReason": finish_reason,
281 "usage": usage_dict
282 })
284 elif event_type == "message_stop":
285 # Stream completed - this is a fallback if message_delta didn't emit RUN_FINISHED
286 if not self.run_finished:
287 self.run_finished = True
288 chunks.append({
289 "type": "RUN_FINISHED",
290 "runId": self.run_id,
291 "model": self.model,
292 "timestamp": self.timestamp,
293 "finishReason": "stop"
294 })
296 return chunks
298 async def convert_openai_event(self, event: Any) -> List[Dict[str, Any]]:
299 """Convert OpenAI streaming event to AG-UI StreamChunk format"""
300 chunks = []
302 # Emit RUN_STARTED on first event
303 run_started = self._maybe_emit_run_started()
304 if run_started:
305 chunks.append(run_started)
307 # OpenAI events have chunk.choices[0].delta structure
308 choice = self._get_attr(event, "choices", [])
309 if choice and len(choice) > 0:
310 choice = choice[0]
311 else:
312 # Try direct access
313 choice = event
315 delta = self._get_attr(choice, "delta")
317 # Handle content delta
318 if delta:
319 content = self._get_attr(delta, "content")
320 if content:
321 # Emit TEXT_MESSAGE_START on first text content
322 text_start = self._maybe_emit_text_message_start()
323 if text_start:
324 chunks.append(text_start)
326 self.accumulated_content += content
327 chunks.append({
328 "type": "TEXT_MESSAGE_CONTENT",
329 "messageId": self.message_id,
330 "model": self._get_attr(event, "model", self.model),
331 "timestamp": self.timestamp,
332 "delta": content,
333 "content": self.accumulated_content
334 })
336 # Handle tool calls
337 tool_calls = self._get_attr(delta, "tool_calls")
338 if tool_calls:
339 for tool_call in tool_calls:
340 tool_index = self._get_attr(tool_call, "index", len(self.tool_calls_map))
341 tool_id = self._get_attr(tool_call, "id")
342 function = self._get_attr(tool_call, "function", {})
343 tool_name = self._get_attr(function, "name", "")
344 arguments = self._get_attr(function, "arguments", "")
346 # Initialize tool call tracking if new
347 if tool_index not in self.tool_calls_map:
348 self.tool_calls_map[tool_index] = {
349 "id": tool_id or f"call_{self.timestamp}_{tool_index}",
350 "name": tool_name,
351 "input": "",
352 "started": False
353 }
355 tracked = self.tool_calls_map[tool_index]
357 # Update tool ID and name if provided
358 if tool_id:
359 tracked["id"] = tool_id
360 if tool_name:
361 tracked["name"] = tool_name
363 # Emit TOOL_CALL_START on first encounter
364 if not tracked["started"] and (tool_id or tool_name):
365 tracked["started"] = True
366 chunks.append({
367 "type": "TOOL_CALL_START",
368 "toolCallId": tracked["id"],
369 "toolName": tracked["name"],
370 "model": self._get_attr(event, "model", self.model),
371 "timestamp": self.timestamp,
372 "index": tool_index
373 })
375 # Accumulate arguments
376 if arguments:
377 tracked["input"] += arguments
378 chunks.append({
379 "type": "TOOL_CALL_ARGS",
380 "toolCallId": tracked["id"],
381 "model": self._get_attr(event, "model", self.model),
382 "timestamp": self.timestamp,
383 "delta": arguments,
384 "args": tracked["input"]
385 })
387 # Handle completion
388 finish_reason = self._get_attr(choice, "finish_reason")
389 if finish_reason:
390 # Emit TOOL_CALL_END for all pending tool calls
391 for tool_index, tool_call in self.tool_calls_map.items():
392 if tool_call["started"]:
393 parsed_input = {}
394 if tool_call["input"]:
395 try:
396 parsed_input = json.loads(tool_call["input"])
397 except json.JSONDecodeError:
398 parsed_input = {}
400 chunks.append({
401 "type": "TOOL_CALL_END",
402 "toolCallId": tool_call["id"],
403 "toolName": tool_call["name"],
404 "model": self._get_attr(event, "model", self.model),
405 "timestamp": self.timestamp,
406 "input": parsed_input
407 })
409 # Emit TEXT_MESSAGE_END if we had text content
410 if self.has_emitted_text_message_start:
411 chunks.append({
412 "type": "TEXT_MESSAGE_END",
413 "messageId": self.message_id,
414 "model": self._get_attr(event, "model", self.model),
415 "timestamp": self.timestamp
416 })
418 usage = self._get_attr(event, "usage")
419 usage_dict = None
420 if usage:
421 usage_dict = {
422 "promptTokens": self._get_attr(usage, "prompt_tokens", 0),
423 "completionTokens": self._get_attr(usage, "completion_tokens", 0),
424 "totalTokens": self._get_attr(usage, "total_tokens", 0)
425 }
427 # Map OpenAI finish reasons
428 mapped_finish_reason = {
429 "stop": "stop",
430 "length": "length",
431 "tool_calls": "tool_calls",
432 "content_filter": "content_filter"
433 }.get(finish_reason, finish_reason)
435 self.run_finished = True
436 chunks.append({
437 "type": "RUN_FINISHED",
438 "runId": self.run_id,
439 "model": self._get_attr(event, "model", self.model),
440 "timestamp": self.timestamp,
441 "finishReason": mapped_finish_reason,
442 "usage": usage_dict
443 })
445 return chunks
447 async def convert_event(self, event: Any) -> List[Dict[str, Any]]:
448 """
449 Convert provider streaming event to AG-UI StreamChunk format.
450 Automatically detects provider based on event structure.
451 """
452 if self.provider == "anthropic":
453 return await self.convert_anthropic_event(event)
454 elif self.provider == "openai":
455 return await self.convert_openai_event(event)
456 else:
457 # Try to auto-detect based on event structure
458 event_type = self._get_event_type(event)
460 # Anthropic events have types like "content_block_start", "message_delta"
461 # OpenAI events have chunk.choices structure
462 if event_type in ["content_block_start", "content_block_delta", "content_block_stop", "message_delta", "message_stop"]:
463 return await self.convert_anthropic_event(event)
464 elif self._get_attr(event, "choices") is not None:
465 return await self.convert_openai_event(event)
466 else:
467 # Default to Anthropic format
468 return await self.convert_anthropic_event(event)
470 async def convert_error(self, error: Exception) -> List[Dict[str, Any]]:
471 """Convert an error to RUN_ERROR StreamChunk format (AG-UI Protocol)"""
472 # Ensure RUN_STARTED was emitted before error
473 chunks = []
474 run_started = self._maybe_emit_run_started()
475 if run_started:
476 chunks.append(run_started)
478 chunks.append({
479 "type": "RUN_ERROR",
480 "runId": self.run_id,
481 "model": self.model,
482 "timestamp": self.timestamp,
483 "error": {
484 "message": str(error),
485 "code": getattr(error, "code", None) or type(error).__name__
486 }
487 })
489 return chunks
490​