Add support for streaming

cli.php

@@ -10,6 +10,9 @@
  *   OPENAI_API_KEY=123456 php cli.php 'Your prompt here' --providerId=openai
  *   GOOGLE_API_KEY=123456 OPENAI_API_KEY=123456 php cli.php 'Your prompt here'
  *
+ * To stream the response as it arrives, use --outputFormat=stream-text:
+ *   OPENAI_API_KEY=123456 php cli.php 'Your prompt here' --providerId=openai --outputFormat=stream-text
+ *
  * Embedding output formats require both --providerId and --modelId, because embeddings are only
  * comparable to other embeddings from the same model:
  *   OPENAI_API_KEY=123456 php cli.php 'Your text here' --providerId=openai \
@@ -229,6 +232,14 @@ static function ($item) {
 try {
     if ($isEmbedding) {
         $result = $builder->generateEmbeddingResult();
+    } elseif ($outputFormat === 'stream-text') {
+        $stream = $builder->streamGenerateTextResult();
+        foreach ($stream as $chunk) {
+            echo $chunk->getDeltaText();
+            flush();
+        }
+        echo PHP_EOL;
+        $result = $stream->getFinalResult();
     } elseif ($outputFormat === 'image-json' || $outputFormat === 'image-base64') {
         $result = $builder->generateImageResult();
     } else {
@@ -243,7 +254,11 @@ static function ($item) {
 logInfo("Using provider ID: \"{$result->getProviderMetadata()->getId()}\"");
 logInfo("Using model ID: \"{$result->getModelMetadata()->getId()}\"");
 
+$output = null;
 switch ($outputFormat) {
+    case 'stream-text':
+        // The text was already streamed to stdout above.
+        break;
     case 'result-json':
         $output = json_encode($result, JSON_PRETTY_PRINT);
         break;
@@ -267,4 +282,6 @@ static function ($item) {
         $output = $result->toText();
 }
 
-printOutput($output);
+if (is_string($output)) {
+    printOutput($output);
+}

phpcs.xml.dist

@@ -21,6 +21,9 @@
     <!-- Use PSR-12 standard -->
     <rule ref="PSR12"/>
 
+    <!-- Check up to 20 files simultaneously. -->
+    <arg name="parallel" value="20"/>
+
     <!-- Check PHP 7.4 compatibility -->
     <rule ref="PHPCompatibility">
         <!-- Exclude functions that are polyfilled in src/polyfills.php -->

src/AiClient.php

@@ -19,6 +19,7 @@
 use WordPress\AiClient\Results\DTO\Embedding;
 use WordPress\AiClient\Results\DTO\EmbeddingResult;
 use WordPress\AiClient\Results\DTO\GenerativeAiResult;
+use WordPress\AiClient\Results\StreamedGenerativeAiResult;
 
 /**
  * Main AI Client class providing both fluent and traditional APIs for AI operations.
@@ -322,6 +323,33 @@ public static function generateTextResult(
         return self::getConfiguredPromptBuilder($prompt, $modelOrConfig, $registry)->generateTextResult();
     }
 
+    /**
+     * Streams a text result using the traditional API approach.
+     *
+     * Iterate the returned object to consume chunks as they arrive, then call
+     * its getFinalResult() for the complete result.
+     *
+     * @since n.e.x.t
+     *
+     * @param Prompt $prompt The prompt content.
+     * @param ModelInterface|ModelConfig|null $modelOrConfig Optional specific model to use,
+     *                                                        or model configuration for auto-discovery,
+     *                                                        or null for defaults.
+     * @param ProviderRegistry|null $registry Optional custom registry. If null, uses default.
+     * @return StreamedGenerativeAiResult The streamed result.
+     *
+     * @throws \InvalidArgumentException If the prompt format is invalid.
+     * @throws \RuntimeException If no suitable model is found or it does not support streaming.
+     */
+    public static function streamGenerateTextResult(
+        $prompt,
+        $modelOrConfig = null,
+        ?ProviderRegistry $registry = null
+    ): StreamedGenerativeAiResult {
+        self::validateModelOrConfigParameter($modelOrConfig);
+        return self::getConfiguredPromptBuilder($prompt, $modelOrConfig, $registry)->streamGenerateTextResult();
+    }
+
     /**
      * Generates an image using the traditional API approach.
      *

src/Builders/PromptBuilder.php

@@ -10,6 +10,7 @@
 use WordPress\AiClient\Common\Exception\RuntimeException;
 use WordPress\AiClient\Events\AfterGenerateResultEvent;
 use WordPress\AiClient\Events\BeforeGenerateResultEvent;
+use WordPress\AiClient\Events\GenerateResultErrorEvent;
 use WordPress\AiClient\Files\DTO\File;
 use WordPress\AiClient\Files\Enums\FileTypeEnum;
 use WordPress\AiClient\Files\Enums\MediaOrientationEnum;
@@ -25,11 +26,13 @@
 use WordPress\AiClient\Providers\Models\Enums\CapabilityEnum;
 use WordPress\AiClient\Providers\Models\ImageGeneration\Contracts\ImageGenerationModelInterface;
 use WordPress\AiClient\Providers\Models\SpeechGeneration\Contracts\SpeechGenerationModelInterface;
+use WordPress\AiClient\Providers\Models\TextGeneration\Contracts\StreamingTextGenerationModelInterface;
 use WordPress\AiClient\Providers\Models\TextGeneration\Contracts\TextGenerationModelInterface;
 use WordPress\AiClient\Providers\Models\TextToSpeechConversion\Contracts\TextToSpeechConversionModelInterface;
 use WordPress\AiClient\Providers\Models\VideoGeneration\Contracts\VideoGenerationModelInterface;
 use WordPress\AiClient\Providers\ProviderRegistry;
 use WordPress\AiClient\Results\DTO\GenerativeAiResult;
+use WordPress\AiClient\Results\StreamedGenerativeAiResult;
 use WordPress\AiClient\Tools\DTO\FunctionDeclaration;
 use WordPress\AiClient\Tools\DTO\FunctionResponse;
 use WordPress\AiClient\Tools\DTO\WebSearch;
@@ -861,6 +864,65 @@ public function generateTextResult(): GenerativeAiResult
         return $this->generateResult(CapabilityEnum::textGeneration());
     }
 
+    /**
+     * Streams a text result from the prompt.
+     *
+     * @since n.e.x.t
+     *
+     * @return StreamedGenerativeAiResult The streamed result.
+     * @throws InvalidArgumentException If the prompt or model validation fails.
+     * @throws RuntimeException If the model does not support streaming text generation.
+     */
+    public function streamGenerateTextResult(): StreamedGenerativeAiResult
+    {
+        $this->includeOutputModalities(ModalityEnum::text());
+        $this->validateMessages();
+
+        $capability = CapabilityEnum::textGeneration();
+        $model = $this->getConfiguredModel($capability);
+
+        if (!$model instanceof StreamingTextGenerationModelInterface) {
+            throw new RuntimeException(
+                sprintf(
+                    'Model "%s" does not support streaming text generation.',
+                    $model->metadata()->getId()
+                )
+            );
+        }
+
+        $messages = $this->messages;
+
+        return $model->streamGenerateTextResult($messages)
+            ->onStart(function () use ($messages, $model, $capability): void {
+                $this->dispatchEvent(new BeforeGenerateResultEvent($messages, $model, $capability));
+            })
+            ->onComplete(function (GenerativeAiResult $result) use ($messages, $model, $capability): void {
+                $this->dispatchEvent(new AfterGenerateResultEvent($messages, $model, $capability, $result));
+            })
+            ->onError(function (\Throwable $error) use ($messages, $model, $capability): void {
+                $this->dispatchEvent(new GenerateResultErrorEvent($messages, $model, $capability, $error));
+            });
+    }
+
+    /**
+     * Streams generated text from the prompt as it arrives.
+     *
+     * @since n.e.x.t
+     *
+     * @return iterable<string> The text deltas, in order.
+     * @throws InvalidArgumentException If the prompt or model validation fails.
+     * @throws RuntimeException If the model does not support streaming text generation.
+     */
+    public function streamGenerateText(): iterable
+    {
+        foreach ($this->streamGenerateTextResult() as $chunk) {
+            $delta = $chunk->getDeltaText();
+            if ($delta !== '') {
+                yield $delta;
+            }
+        }
+    }
+
     /**
      * Generates an image result from the prompt.
      *

src/Events/GenerateResultErrorEvent.php

@@ -0,0 +1,122 @@
+<?php
+
+declare(strict_types=1);
+
+namespace WordPress\AiClient\Events;
+
+use Throwable;
+use WordPress\AiClient\Messages\DTO\Message;
+use WordPress\AiClient\Providers\Models\Contracts\ModelInterface;
+use WordPress\AiClient\Providers\Models\Enums\CapabilityEnum;
+
+/**
+ * Class GenerateResultErrorEvent.
+ *
+ * @since n.e.x.t
+ */
+class GenerateResultErrorEvent
+{
+    /**
+     * @var list<Message> The messages that were sent to the model.
+     */
+    private array $messages;
+
+    /**
+     * @var ModelInterface The model that processed the prompt.
+     */
+    private ModelInterface $model;
+
+    /**
+     * @var CapabilityEnum|null The capability that was used for generation.
+     */
+    private ?CapabilityEnum $capability;
+
+    /**
+     * @var Throwable The error that occurred during generation.
+     */
+    private Throwable $error;
+
+    /**
+     * Constructor.
+     *
+     * @since n.e.x.t
+     *
+     * @param list<Message> $messages The messages that were sent to the model.
+     * @param ModelInterface $model The model that processed the prompt.
+     * @param CapabilityEnum|null $capability The capability that was used for generation.
+     * @param Throwable $error The error that occurred during generation.
+     */
+    public function __construct(
+        array $messages,
+        ModelInterface $model,
+        ?CapabilityEnum $capability,
+        Throwable $error
+    ) {
+        $this->messages = $messages;
+        $this->model = $model;
+        $this->capability = $capability;
+        $this->error = $error;
+    }
+
+    /**
+     * Gets the messages that were sent to the model.
+     *
+     * @since n.e.x.t
+     *
+     * @return list<Message> The messages.
+     */
+    public function getMessages(): array
+    {
+        return $this->messages;
+    }
+
+    /**
+     * Gets the model that processed the prompt.
+     *
+     * @since n.e.x.t
+     *
+     * @return ModelInterface The model.
+     */
+    public function getModel(): ModelInterface
+    {
+        return $this->model;
+    }
+
+    /**
+     * Gets the capability that was used for generation.
+     *
+     * @since n.e.x.t
+     *
+     * @return CapabilityEnum|null The capability, or null if not specified.
+     */
+    public function getCapability(): ?CapabilityEnum
+    {
+        return $this->capability;
+    }
+
+    /**
+     * Gets the error that occurred during generation.
+     *
+     * @since n.e.x.t
+     *
+     * @return Throwable The error.
+     */
+    public function getError(): Throwable
+    {
+        return $this->error;
+    }
+
+    /**
+     * Performs a deep clone of the event.
+     *
+     * @since n.e.x.t
+     */
+    public function __clone()
+    {
+        $clonedMessages = [];
+        foreach ($this->messages as $message) {
+            $clonedMessages[] = clone $message;
+        }
+        $this->messages = $clonedMessages;
+    }
+}