feature #1759 [Platform] Replace untyped stream chunks with semantic DeltaInterface deltas (fabpot, chr-hertel)

This PR was squashed before being merged into the main branch.

Discussion
----------

[Platform] Replace untyped stream chunks with semantic DeltaInterface deltas

| Q             | A
| ------------- | ---
| Bug fix?      | yes
| New feature?  | yes <!-- please update src/**/CHANGELOG.md files -->
| Docs?         | yes/no <!-- required for new features -->
| Issues        | n/a
| License       | MIT

This PR introduces semantic streaming event objects so that one can react to specific LLM events without parsing the raw JSON. Think of this PR as being a first step towards full streaming support ;)

Commits
-------

232275d [Platform] Replace untyped stream chunks with semantic DeltaInterface deltas

Author: chr-hertel

UPGRADE.md

@@ -27,6 +27,12 @@ Agent
    ```
 
  * The `SimilaritySearch` tool now accepts an optional `$promptTemplate` parameter to customize the result header (default: `'Found documents with the following information:'`)
+ * `Toolbox\StreamListener::onChunk()` has been renamed to `onDelta()`.
+   The listener now checks `$delta instanceof TextDelta` instead of
+   `is_string($chunk)` to accumulate the assistant text buffer.
+ * The `StreamListener` now reacts to `ToolCallComplete` instead of
+   `ToolCallResult`. If you have a custom `StreamListener` or check for
+   `ToolCallResult` in stream consumers, update to `ToolCallComplete`.
 
 Mate
 ----
@@ -42,13 +48,76 @@ AI Bundle
  * The `endpoint` option for `Ollama` is now `null` by default to allow the usage of a `ScopingHttpClient`
 
 Platform
------
+--------
 
  * `ModelCatalog` in `Ollama` has been replaced by `OllamaApiCatalog`
  * `OllamaApiCatalog` in `Ollama` has been replaced to `ModelCatalog`
  * `Ollama` model is now `final`
  * `ModelCatalog` in `ElevenLabs` has been replaced by `ElevenLabsApiCatalog`
  * `ElevenLabsApiCatalog` in `ElevenLabs` has been replaced to `ModelCatalog`
+ * `ChunkEvent` has been replaced by `DeltaEvent`. The `onChunk(ChunkEvent)` method
+   on `ListenerInterface` is now `onDelta(DeltaEvent)`. Update all implementations:
+   - `onChunk(ChunkEvent $event)` → `onDelta(DeltaEvent $event)`
+   - `$event->getChunk()` → `$event->getDelta()`
+   - `$event->setChunk(...)` → `$event->setDelta(...)`
+   - `$event->skipChunk()` → `$event->skipDelta()`
+   - `$event->isChunkSkipped()` → `$event->isDeltaSkipped()`
+ * Stream generators in bridge `ResultConverter` classes now yield typed
+   `DeltaInterface` objects instead of raw strings. Consumers iterating
+   `StreamResult::getContent()` that expect `string` chunks must check for
+   `TextDelta` instead:
+   - `is_string($chunk)` → `$chunk instanceof TextDelta`, then use `$chunk->getText()`
+ * New streaming delta types in `Symfony\AI\Platform\Result\Stream\Delta\`:
+   `TextDelta`, `ThinkingDelta`, `ThinkingSignature`, `ToolCallStart`,
+   `ToolInputDelta`, `BinaryDelta`, `ChoiceDelta`, `ToolCallComplete`,
+   `ThinkingComplete`. These are yielded by bridge converters during streaming.
+ * `Symfony\AI\Platform\Bridge\Ollama\OllamaMessageChunk` has been removed.
+   Ollama streams now yield semantic deltas like the other bridges:
+   - text content → `TextDelta`
+   - thinking content → `ThinkingDelta`
+   - completed tool calls → `ToolCallComplete`
+   - final usage → `TokenUsage`
+
+   ```diff
+   -if ($chunk instanceof OllamaMessageChunk) {
+   -    echo $chunk->getContent();
+   -}
+   +if ($chunk instanceof TextDelta) {
+   +    echo $chunk->getText();
+   +}
+   ```
+ * `Symfony\AI\Platform\Bridge\Perplexity\PerplexitySearchResults`,
+   `Symfony\AI\Platform\Bridge\Perplexity\PerplexityCitations`, and
+   `Symfony\AI\Platform\Bridge\Perplexity\StreamListener` have been
+   removed. Perplexity now emits generic `MetadataDelta` instances internally,
+   which are promoted to result metadata during stream consumption.
+
+   If you relied on those deltas directly, read metadata instead:
+
+   ```diff
+   -if ($delta instanceof PerplexitySearchResults) {
+   -    $results = $delta->getSearchResults();
+   -}
+   -if ($delta instanceof PerplexityCitations) {
+   -    $citations = $delta->getCitations();
+   -}
+   +$results = $result->getMetadata()->get('search_results');
+   +$citations = $result->getMetadata()->get('citations');
+   ```
+ * `BinaryResult`, `ChoiceResult`, `ToolCallResult`, and `ThinkingContent` no
+   longer implement `DeltaInterface`. Stream generators now yield proper delta
+   types instead of result objects:
+   - `ToolCallResult` → `ToolCallComplete`: use `$delta instanceof ToolCallComplete`
+     and `$delta->getToolCalls()`.
+   - `ThinkingContent` → `ThinkingComplete`: use `$delta instanceof ThinkingComplete`
+     and `$delta->getThinking()` / `$delta->getSignature()`.
+   - `BinaryResult` → `BinaryDelta`: use `$delta instanceof BinaryDelta`
+     and `$delta->getData()` / `$delta->getMimeType()`.
+   - `ChoiceResult` → `ChoiceDelta`: use `$delta instanceof ChoiceDelta`
+     and `$delta->getDeltas()`.
+ * `ThinkingContent` has been removed in favor of `ThinkingComplete`.
+ * The `Usage` delta class has been removed. Bridges now yield `TokenUsage`
+   objects directly in streams instead.
 
 Store
 -----

demo/src/Blog/Command/StreamCommand.php

@@ -14,6 +14,7 @@
 use Symfony\AI\Agent\AgentInterface;
 use Symfony\AI\Platform\Message\Message;
 use Symfony\AI\Platform\Message\MessageBag;
+use Symfony\AI\Platform\Result\Stream\Delta\TextDelta;
 use Symfony\AI\Platform\Result\StreamResult;
 use Symfony\Component\Console\Attribute\AsCommand;
 use Symfony\Component\Console\Style\SymfonyStyle;
@@ -45,8 +46,10 @@ public function __invoke(SymfonyStyle $io): int
 
         \assert($result instanceof StreamResult);
 
-        foreach ($result->getContent() as $word) {
-            $io->write($word);
+        foreach ($result->getContent() as $delta) {
+            if ($delta instanceof TextDelta) {
+                $io->write((string) $delta);
+            }
         }
 
         $io->newLine(2);

demo/src/Stream/Chat.php

@@ -16,6 +16,7 @@
 use Symfony\AI\Platform\Message\Message;
 use Symfony\AI\Platform\Message\MessageBag;
 use Symfony\AI\Platform\Message\UserMessage;
+use Symfony\AI\Platform\Result\Stream\Delta\TextDelta;
 use Symfony\Component\DependencyInjection\Attribute\Autowire;
 use Symfony\Component\HttpFoundation\RequestStack;
 
@@ -56,8 +57,10 @@ public function getAssistantResponse(MessageBag $messages): \Generator
         \assert(is_iterable($stream));
 
         $response = '';
-        foreach ($stream as $chunk) {
-            yield $response .= $chunk;
+        foreach ($stream as $delta) {
+            if ($delta instanceof TextDelta) {
+                yield $response .= (string) $delta;
+            }
         }
 
         $assistantMessage = Message::ofAssistant($response);

demo/tests/Blog/Command/StreamCommandTest.php

@@ -17,6 +17,7 @@
 use Symfony\AI\Platform\Metadata\Metadata;
 use Symfony\AI\Platform\Result\RawResultInterface;
 use Symfony\AI\Platform\Result\ResultInterface;
+use Symfony\AI\Platform\Result\Stream\Delta\TextDelta;
 use Symfony\Component\Console\Input\ArrayInput;
 use Symfony\Component\Console\Output\BufferedOutput;
 use Symfony\Component\Console\Style\SymfonyStyle;
@@ -31,10 +32,10 @@ public function testStreamCommandOutputsStreamedContentAndSuccess()
             ->willReturn(new class implements ResultInterface {
                 public function getContent(): iterable
                 {
-                    yield 'Hello';
-                    yield ' ';
-                    yield 'world';
-                    yield '!';
+                    yield new TextDelta('Hello');
+                    yield new TextDelta(' ');
+                    yield new TextDelta('world');
+                    yield new TextDelta('!');
                 }
 
                 public function getMetadata(): Metadata

examples/amazeeai/stream.php

@@ -12,6 +12,7 @@
 use Symfony\AI\Platform\Bridge\AmazeeAi\PlatformFactory;
 use Symfony\AI\Platform\Message\Message;
 use Symfony\AI\Platform\Message\MessageBag;
+use Symfony\AI\Platform\Result\Stream\Delta\TextDelta;
 
 require_once dirname(__DIR__).'/bootstrap.php';
 
@@ -22,7 +23,9 @@
     'stream' => true,
 ]);
 
-foreach ($result->asStream() as $word) {
-    echo $word;
+foreach ($result->asStream() as $delta) {
+    if ($delta instanceof TextDelta) {
+        echo $delta;
+    }
 }
 echo \PHP_EOL;

examples/anthropic/stream.php

@@ -12,6 +12,7 @@
 use Symfony\AI\Platform\Bridge\Anthropic\PlatformFactory;
 use Symfony\AI\Platform\Message\Message;
 use Symfony\AI\Platform\Message\MessageBag;
+use Symfony\AI\Platform\Result\Stream\Delta\TextDelta;
 
 require_once dirname(__DIR__).'/bootstrap.php';
 
@@ -23,7 +24,9 @@
 );
 $result = $platform->invoke('claude-sonnet-4-5-20250929', $messages, ['stream' => true]);
 
-foreach ($result->asStream() as $word) {
-    echo $word;
+foreach ($result->asStream() as $delta) {
+    if ($delta instanceof TextDelta) {
+        echo $delta;
+    }
 }
 echo \PHP_EOL;

examples/anthropic/toolcall-stream.php

@@ -16,6 +16,7 @@
 use Symfony\AI\Platform\Bridge\Anthropic\PlatformFactory;
 use Symfony\AI\Platform\Message\Message;
 use Symfony\AI\Platform\Message\MessageBag;
+use Symfony\AI\Platform\Result\Stream\Delta\TextDelta;
 
 require_once dirname(__DIR__).'/bootstrap.php';
 
@@ -34,8 +35,10 @@
     'stream' => true, // enable streaming of response text
 ]);
 
-foreach ($result->getContent() as $word) {
-    echo $word;
+foreach ($result->getContent() as $delta) {
+    if ($delta instanceof TextDelta) {
+        echo $delta;
+    }
 }
 
 echo \PHP_EOL;

examples/cerebras/stream.php

@@ -12,6 +12,7 @@
 use Symfony\AI\Platform\Bridge\Cerebras\PlatformFactory;
 use Symfony\AI\Platform\Message\Message;
 use Symfony\AI\Platform\Message\MessageBag;
+use Symfony\AI\Platform\Result\Stream\Delta\TextDelta;
 
 require_once dirname(__DIR__).'/bootstrap.php';
 
@@ -26,7 +27,9 @@
     'stream' => true,
 ]);
 
-foreach ($result->asStream() as $word) {
-    echo $word;
+foreach ($result->asStream() as $delta) {
+    if ($delta instanceof TextDelta) {
+        echo $delta;
+    }
 }
 echo \PHP_EOL;

examples/chat/stream-chat.php

@@ -15,6 +15,7 @@
 use Symfony\AI\Platform\Bridge\OpenAi\PlatformFactory;
 use Symfony\AI\Platform\Message\Message;
 use Symfony\AI\Platform\Message\MessageBag;
+use Symfony\AI\Platform\Result\Stream\Delta\TextDelta;
 
 require_once dirname(__DIR__).'/bootstrap.php';
 
@@ -30,7 +31,9 @@
 $chat->initiate($messages);
 $chat->submit(Message::ofUser('My name is Christopher.'));
 
-foreach ($chat->stream(Message::ofUser('Tell me a story about the sun')) as $chunk) {
-    echo $chunk;
+foreach ($chat->stream(Message::ofUser('Tell me a story about the sun')) as $delta) {
+    if ($delta instanceof TextDelta) {
+        echo $delta;
+    }
 }
 echo \PHP_EOL;

examples/claude-code/stream.php

@@ -12,6 +12,7 @@
 use Symfony\AI\Platform\Bridge\ClaudeCode\PlatformFactory;
 use Symfony\AI\Platform\Message\Message;
 use Symfony\AI\Platform\Message\MessageBag;
+use Symfony\AI\Platform\Result\Stream\Delta\TextDelta;
 
 require_once dirname(__DIR__).'/bootstrap.php';
 
@@ -30,7 +31,9 @@
     'max_turns' => 1,
 ]);
 
-foreach ($result->asStream() as $word) {
-    echo $word;
+foreach ($result->asStream() as $delta) {
+    if ($delta instanceof TextDelta) {
+        echo $delta;
+    }
 }
 echo \PHP_EOL;