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

StreamChunkConverter.php

561 lines21.2 KB

1<?php
2​
3namespace TanStack\AI;
4​
5/**
6 * Converts provider-specific streaming events to TanStack AI AG-UI StreamChunk format.
7 *
8 * Implements the AG-UI (Agent-User Interaction) Protocol event types:
9 * - RUN_STARTED, RUN_FINISHED, RUN_ERROR (lifecycle events)
10 * - TEXT_MESSAGE_START, TEXT_MESSAGE_CONTENT, TEXT_MESSAGE_END (text streaming)
11 * - TOOL_CALL_START, TOOL_CALL_ARGS, TOOL_CALL_END (tool calling)
12 * - STEP_STARTED, STEP_FINISHED (thinking/reasoning)
13 *
14 * Supports:
15 * - Anthropic streaming events
16 * - OpenAI streaming events
17 */
18class StreamChunkConverter
20 private string $model;
21 private string $provider;
22 private int $timestamp;
23 private string $accumulatedContent = '';
24 private string $accumulatedThinking = '';
25 private array $toolCallsMap = [];
26 private int $currentToolIndex = -1;
27 private bool $runFinished = false;
28​
29 // AG-UI lifecycle tracking
30 private string $runId;
31 private string $messageId;
32 private ?string $stepId = null;
33 private bool $hasEmittedRunStarted = false;
34 private bool $hasEmittedTextMessageStart = false;
35​
36 public function __construct(string $model, string $provider = 'anthropic')
37 {
38 $this->model = $model;
39 $this->provider = strtolower($provider);
40 $this->timestamp = (int)(microtime(true) * 1000);
41 $this->runId = $this->generateId();
42 $this->messageId = $this->generateId();
43 }
44​
45 /**
46 * Generate a unique ID for the chunk
47 */
48 public function generateId(): string
49 {
50 return 'chatcmpl-' . bin2hex(random_bytes(4));
51 }
52​
53 /**
54 * Get event type from either array or object
55 */
56 private function getEventType(mixed $event): string
57 {
58 if (is_array($event)) {
59 return $event['type'] ?? '';
60 }
61 return is_object($event) && property_exists($event, 'type') ? $event->type : '';
62 }
63​
64 /**
65 * Get attribute from either array or object
66 */
67 private function getAttr(mixed $obj, string $attr, mixed $default = null): mixed
68 {
69 if (is_array($obj)) {
70 return $obj[$attr] ?? $default;
71 }
72 if (is_object($obj)) {
73 return property_exists($obj, $attr) ? $obj->$attr : $default;
74 }
75 return $default;
76 }
77​
78 /**
79 * Create RUN_STARTED event if not already emitted
80 */
81 private function maybeEmitRunStarted(): ?array
82 {
83 if (!$this->hasEmittedRunStarted) {
84 $this->hasEmittedRunStarted = true;
85 return [
86 'type' => 'RUN_STARTED',
87 'runId' => $this->runId,
88 'model' => $this->model,
89 'timestamp' => $this->timestamp
90 ];
91 }
92 return null;
93 }
94​
95 /**
96 * Create TEXT_MESSAGE_START event if not already emitted
97 */
98 private function maybeEmitTextMessageStart(): ?array
99 {
100 if (!$this->hasEmittedTextMessageStart) {
101 $this->hasEmittedTextMessageStart = true;
102 return [
103 'type' => 'TEXT_MESSAGE_START',
104 'messageId' => $this->messageId,
105 'model' => $this->model,
106 'timestamp' => $this->timestamp,
107 'role' => 'assistant'
108 ];
109 }
110 return null;
111 }
112​
113 /**
114 * Convert Anthropic streaming event to AG-UI StreamChunk format
115 */
116 public function convertAnthropicEvent(mixed $event): array
117 {
118 $chunks = [];
119 $eventType = $this->getEventType($event);
120​
121 // Emit RUN_STARTED on first event
122 $runStarted = $this->maybeEmitRunStarted();
123 if ($runStarted) {
124 $chunks[] = $runStarted;
125 }
126​
127 if ($eventType === 'content_block_start') {
128 $contentBlock = $this->getAttr($event, 'content_block');
129 if ($contentBlock) {
130 $blockType = $this->getAttr($contentBlock, 'type');
132 if ($blockType === 'tool_use') {
133 // Tool call is starting
134 $this->currentToolIndex++;
135 $toolId = $this->getAttr($contentBlock, 'id');
136 $toolName = $this->getAttr($contentBlock, 'name');
138 $this->toolCallsMap[$this->currentToolIndex] = [
139 'id' => $toolId,
140 'name' => $toolName,
141 'input' => '',
142 'started' => false
143 ];
144 } elseif ($blockType === 'thinking') {
145 // Thinking/reasoning block starting
146 $this->accumulatedThinking = '';
147 $this->stepId = $this->generateId();
148 $chunks[] = [
149 'type' => 'STEP_STARTED',
150 'stepId' => $this->stepId,
151 'model' => $this->model,
152 'timestamp' => $this->timestamp,
153 'stepType' => 'thinking'
154 ];
155 }
156 }
157 } elseif ($eventType === 'content_block_delta') {
158 $delta = $this->getAttr($event, 'delta');
159​
160 if ($delta && $this->getAttr($delta, 'type') === 'text_delta') {
161 // Emit TEXT_MESSAGE_START on first text content
162 $textStart = $this->maybeEmitTextMessageStart();
163 if ($textStart) {
164 $chunks[] = $textStart;
165 }
166​
167 // Text content delta
168 $deltaText = $this->getAttr($delta, 'text', '');
169 $this->accumulatedContent .= $deltaText;
170​
171 $chunks[] = [
172 'type' => 'TEXT_MESSAGE_CONTENT',
173 'messageId' => $this->messageId,
174 'model' => $this->model,
175 'timestamp' => $this->timestamp,
176 'delta' => $deltaText,
177 'content' => $this->accumulatedContent
178 ];
179 } elseif ($delta && $this->getAttr($delta, 'type') === 'thinking_delta') {
180 // Thinking content delta
181 $deltaThinking = $this->getAttr($delta, 'thinking', '');
182 $this->accumulatedThinking .= $deltaThinking;
183​
184 $chunks[] = [
185 'type' => 'STEP_FINISHED',
186 'stepId' => $this->stepId ?? $this->generateId(),
187 'model' => $this->model,
188 'timestamp' => $this->timestamp,
189 'delta' => $deltaThinking,
190 'content' => $this->accumulatedThinking
191 ];
192 } elseif ($delta && $this->getAttr($delta, 'type') === 'input_json_delta') {
193 // Tool input is being streamed
194 $partialJson = $this->getAttr($delta, 'partial_json', '');
195 $toolCall = $this->toolCallsMap[$this->currentToolIndex] ?? null;
196​
197 if ($toolCall) {
198 // Emit TOOL_CALL_START on first args delta
199 if (!$toolCall['started']) {
200 $toolCall['started'] = true;
201 $this->toolCallsMap[$this->currentToolIndex] = $toolCall;
203 $chunks[] = [
204 'type' => 'TOOL_CALL_START',
205 'toolCallId' => $toolCall['id'],
206 'toolName' => $toolCall['name'],
207 'model' => $this->model,
208 'timestamp' => $this->timestamp,
209 'index' => $this->currentToolIndex
210 ];
211 }
212​
213 $toolCall['input'] .= $partialJson;
214 $this->toolCallsMap[$this->currentToolIndex] = $toolCall;
215​
216 $chunks[] = [
217 'type' => 'TOOL_CALL_ARGS',
218 'toolCallId' => $toolCall['id'],
219 'model' => $this->model,
220 'timestamp' => $this->timestamp,
221 'delta' => $partialJson,
222 'args' => $toolCall['input']
223 ];
224 }
225 }
226 } elseif ($eventType === 'content_block_stop') {
227 // Content block completed
228 $toolCall = $this->toolCallsMap[$this->currentToolIndex] ?? null;
229 if ($toolCall) {
230 // If tool call wasn't started yet (no args), start it now
231 if (!$toolCall['started']) {
232 $toolCall['started'] = true;
233 $this->toolCallsMap[$this->currentToolIndex] = $toolCall;
235 $chunks[] = [
236 'type' => 'TOOL_CALL_START',
237 'toolCallId' => $toolCall['id'],
238 'toolName' => $toolCall['name'],
239 'model' => $this->model,
240 'timestamp' => $this->timestamp,
241 'index' => $this->currentToolIndex
242 ];
243 }
244​
245 // Parse input and emit TOOL_CALL_END
246 $parsedInput = [];
247 if (!empty($toolCall['input'])) {
248 try {
249 $parsedInput = json_decode($toolCall['input'], true) ?? [];
250 } catch (\Exception $e) {
251 $parsedInput = [];
252 }
253 }
254​
255 $chunks[] = [
256 'type' => 'TOOL_CALL_END',
257 'toolCallId' => $toolCall['id'],
258 'toolName' => $toolCall['name'],
259 'model' => $this->model,
260 'timestamp' => $this->timestamp,
261 'input' => $parsedInput
262 ];
263 }
264​
265 // Emit TEXT_MESSAGE_END if we had text content
266 if ($this->hasEmittedTextMessageStart && !empty($this->accumulatedContent)) {
267 $chunks[] = [
268 'type' => 'TEXT_MESSAGE_END',
269 'messageId' => $this->messageId,
270 'model' => $this->model,
271 'timestamp' => $this->timestamp
272 ];
273 }
274 } elseif ($eventType === 'message_delta') {
275 // Message metadata update (includes stop_reason and usage)
276 $delta = $this->getAttr($event, 'delta');
277 $usage = $this->getAttr($event, 'usage');
278​
279 $stopReason = $delta ? $this->getAttr($delta, 'stop_reason') : null;
280 if ($stopReason) {
281 // Map Anthropic stop_reason to TanStack format
282 $finishReason = match ($stopReason) {
283 'tool_use' => 'tool_calls',
284 'end_turn' => 'stop',
285 'max_tokens' => 'length',
286 default => $stopReason
287 };
288​
289 $usageDict = null;
290 if ($usage) {
291 $usageDict = [
292 'promptTokens' => $this->getAttr($usage, 'input_tokens', 0),
293 'completionTokens' => $this->getAttr($usage, 'output_tokens', 0),
294 'totalTokens' => ($this->getAttr($usage, 'input_tokens', 0) + $this->getAttr($usage, 'output_tokens', 0))
295 ];
296 }
297​
298 // Handle max_tokens as error
299 if ($stopReason === 'max_tokens') {
300 $this->runFinished = true;
301 $chunks[] = [
302 'type' => 'RUN_ERROR',
303 'runId' => $this->runId,
304 'model' => $this->model,
305 'timestamp' => $this->timestamp,
306 'error' => [
307 'message' => 'The response was cut off because the maximum token limit was reached.',
308 'code' => 'max_tokens'
309 ]
310 ];
311 } else {
312 $this->runFinished = true;
313 $chunks[] = [
314 'type' => 'RUN_FINISHED',
315 'runId' => $this->runId,
316 'model' => $this->model,
317 'timestamp' => $this->timestamp,
318 'finishReason' => $finishReason,
319 'usage' => $usageDict
320 ];
321 }
322 }
323 } elseif ($eventType === 'message_stop') {
324 // Stream completed - this is a fallback if message_delta didn't emit RUN_FINISHED
325 if (!$this->runFinished) {
326 $this->runFinished = true;
327 $chunks[] = [
328 'type' => 'RUN_FINISHED',
329 'runId' => $this->runId,
330 'model' => $this->model,
331 'timestamp' => $this->timestamp,
332 'finishReason' => 'stop'
333 ];
334 }
335 }
336​
337 return $chunks;
338 }
339​
340 /**
341 * Convert OpenAI streaming event to AG-UI StreamChunk format
342 */
343 public function convertOpenAIEvent(mixed $event): array
344 {
345 $chunks = [];
346​
347 // Emit RUN_STARTED on first event
348 $runStarted = $this->maybeEmitRunStarted();
349 if ($runStarted) {
350 $chunks[] = $runStarted;
351 }
352​
353 // OpenAI events have chunk.choices[0].delta structure
354 $choices = $this->getAttr($event, 'choices', []);
355 $choice = !empty($choices) ? $choices[0] : $event;
356​
357 $delta = $this->getAttr($choice, 'delta');
358​
359 // Handle content delta
360 if ($delta) {
361 $content = $this->getAttr($delta, 'content');
362 if ($content !== null) {
363 // Emit TEXT_MESSAGE_START on first text content
364 $textStart = $this->maybeEmitTextMessageStart();
365 if ($textStart) {
366 $chunks[] = $textStart;
367 }
368​
369 $this->accumulatedContent .= $content;
370 $chunks[] = [
371 'type' => 'TEXT_MESSAGE_CONTENT',
372 'messageId' => $this->messageId,
373 'model' => $this->getAttr($event, 'model', $this->model),
374 'timestamp' => $this->timestamp,
375 'delta' => $content,
376 'content' => $this->accumulatedContent
377 ];
378 }
379​
380 // Handle tool calls
381 $toolCalls = $this->getAttr($delta, 'tool_calls');
382 if ($toolCalls) {
383 foreach ($toolCalls as $index => $toolCall) {
384 $toolIndex = $this->getAttr($toolCall, 'index', $index);
385 $toolId = $this->getAttr($toolCall, 'id');
386 $function = $this->getAttr($toolCall, 'function', []);
387 $toolName = $this->getAttr($function, 'name', '');
388 $arguments = $this->getAttr($function, 'arguments', '');
389​
390 // Initialize tool call tracking if new
391 if (!isset($this->toolCallsMap[$toolIndex])) {
392 $this->toolCallsMap[$toolIndex] = [
393 'id' => $toolId ?? ('call_' . $this->timestamp . '_' . $toolIndex),
394 'name' => $toolName,
395 'input' => '',
396 'started' => false
397 ];
398 }
399​
400 $tracked = &$this->toolCallsMap[$toolIndex];
402 // Update tool ID and name if provided
403 if ($toolId) {
404 $tracked['id'] = $toolId;
405 }
406 if ($toolName) {
407 $tracked['name'] = $toolName;
408 }
409​
410 // Emit TOOL_CALL_START on first encounter
411 if (!$tracked['started'] && ($toolId || $toolName)) {
412 $tracked['started'] = true;
413 $chunks[] = [
414 'type' => 'TOOL_CALL_START',
415 'toolCallId' => $tracked['id'],
416 'toolName' => $tracked['name'],
417 'model' => $this->getAttr($event, 'model', $this->model),
418 'timestamp' => $this->timestamp,
419 'index' => $toolIndex
420 ];
421 }
422​
423 // Accumulate arguments
424 if ($arguments) {
425 $tracked['input'] .= $arguments;
426 $chunks[] = [
427 'type' => 'TOOL_CALL_ARGS',
428 'toolCallId' => $tracked['id'],
429 'model' => $this->getAttr($event, 'model', $this->model),
430 'timestamp' => $this->timestamp,
431 'delta' => $arguments,
432 'args' => $tracked['input']
433 ];
434 }
435 }
436 }
437 }
438​
439 // Handle completion
440 $finishReason = $this->getAttr($choice, 'finish_reason');
441 if ($finishReason) {
442 // Emit TOOL_CALL_END for all pending tool calls
443 foreach ($this->toolCallsMap as $toolCall) {
444 if ($toolCall['started']) {
445 $parsedInput = [];
446 if (!empty($toolCall['input'])) {
447 try {
448 $parsedInput = json_decode($toolCall['input'], true) ?? [];
449 } catch (\Exception $e) {
450 $parsedInput = [];
451 }
452 }
453​
454 $chunks[] = [
455 'type' => 'TOOL_CALL_END',
456 'toolCallId' => $toolCall['id'],
457 'toolName' => $toolCall['name'],
458 'model' => $this->getAttr($event, 'model', $this->model),
459 'timestamp' => $this->timestamp,
460 'input' => $parsedInput
461 ];
462 }
463 }
464​
465 // Emit TEXT_MESSAGE_END if we had text content
466 if ($this->hasEmittedTextMessageStart) {
467 $chunks[] = [
468 'type' => 'TEXT_MESSAGE_END',
469 'messageId' => $this->messageId,
470 'model' => $this->getAttr($event, 'model', $this->model),
471 'timestamp' => $this->timestamp
472 ];
473 }
474​
475 $usage = $this->getAttr($event, 'usage');
476 $usageDict = null;
477 if ($usage) {
478 $usageDict = [
479 'promptTokens' => $this->getAttr($usage, 'prompt_tokens', 0),
480 'completionTokens' => $this->getAttr($usage, 'completion_tokens', 0),
481 'totalTokens' => $this->getAttr($usage, 'total_tokens', 0)
482 ];
483 }
484​
485 // Map OpenAI finish reasons
486 $mappedFinishReason = match ($finishReason) {
487 'stop' => 'stop',
488 'length' => 'length',
489 'tool_calls' => 'tool_calls',
490 'content_filter' => 'content_filter',
491 default => $finishReason
492 };
493​
494 $this->runFinished = true;
495 $chunks[] = [
496 'type' => 'RUN_FINISHED',
497 'runId' => $this->runId,
498 'model' => $this->getAttr($event, 'model', $this->model),
499 'timestamp' => $this->timestamp,
500 'finishReason' => $mappedFinishReason,
501 'usage' => $usageDict
502 ];
503 }
504​
505 return $chunks;
506 }
507​
508 /**
509 * Convert provider streaming event to AG-UI StreamChunk format.
510 * Automatically detects provider based on event structure.
511 */
512 public function convertEvent(mixed $event): array
513 {
514 if ($this->provider === 'anthropic') {
515 return $this->convertAnthropicEvent($event);
516 } elseif ($this->provider === 'openai') {
517 return $this->convertOpenAIEvent($event);
518 } else {
519 // Try to auto-detect based on event structure
520 $eventType = $this->getEventType($event);
521​
522 // Anthropic events have types like "content_block_start", "message_delta"
523 // OpenAI events have chunk.choices structure
524 if (in_array($eventType, ['content_block_start', 'content_block_delta', 'content_block_stop', 'message_delta', 'message_stop'])) {
525 return $this->convertAnthropicEvent($event);
526 } elseif ($this->getAttr($event, 'choices') !== null) {
527 return $this->convertOpenAIEvent($event);
528 } else {
529 // Default to Anthropic format
530 return $this->convertAnthropicEvent($event);
531 }
532 }
533 }
534​
535 /**
536 * Convert an error to RUN_ERROR StreamChunk format (AG-UI Protocol)
537 */
538 public function convertError(\Throwable $error): array
539 {
540 // Ensure RUN_STARTED was emitted before error
541 $chunks = [];
542 $runStarted = $this->maybeEmitRunStarted();
543 if ($runStarted) {
544 $chunks[] = $runStarted;
545 }
546​
547 $chunks[] = [
548 'type' => 'RUN_ERROR',
549 'runId' => $this->runId,
550 'model' => $this->model,
551 'timestamp' => $this->timestamp,
552 'error' => [
553 'message' => $error->getMessage(),
554 'code' => (string)$error->getCode()
555 ]
556 ];
557​
558 return $chunks;
559 }
561​