Add Streaming Response

src/Agent.php

@@ -49,6 +49,13 @@ class Agent
      */
     protected bool $complete = false;
 
+    /**
+     * Indicates whether the agent should stream the response
+     *
+     * @var bool
+     */
+    protected bool $streaming = false;
+
     /**
      * The host to be used for self host LLM (e.g., GPT model)
      *
@@ -241,6 +248,18 @@ public function complete(): self
         return $this;
     }
 
+    /**
+     * Enable streaming mode
+     *
+     * @return self
+     */
+    public function withStreaming(): self
+    {
+        $this->streaming = true;
+
+        return $this;
+    }
+
     /**
      * Execute and get response
      *
@@ -258,13 +277,35 @@ public function send(): mixed
      */
     public function execute(): mixed
     {
+        $agent = $this->agentClass::create(
+            key: $this->key,
+            model: $this->model,
+            config: ['host' => $this->host]
+        )->setMessage($this->messages);
+
+        if ($this->streaming) {
+            return $agent->stream($this->params);
+        }
+
+        return $agent->execute($this->params, $this->complete);
+    }
+
+    /**
+     * Stream the agent response
+     *
+     * @return \Generator
+     */
+    public function stream(): \Generator
+    {
+        $this->streaming = true;
+
         return $this->agentClass::create(
             key: $this->key,
             model: $this->model,
             config: ['host' => $this->host]
         )
             ->setMessage($this->messages)
-            ->execute($this->params, $this->complete);
+            ->stream($this->params);
     }
 
     /**

src/AgentFactory/Agent/Claude.php

@@ -80,6 +80,42 @@ public function execute(array $params, bool $complete = false, ?string $textInpu
         return $complete ? $result : $result->asText();
     }
 
+    /**
+     * Streams the model response in real-time.
+     *
+     * This method enables streaming mode and yields text chunks as they arrive
+     * from the LLM, allowing for real-time display of the response.
+     *
+     * @param array<string, mixed> $params Additional parameters (temperature, max_tokens, etc.)
+     * @param ?string $textInput Optional text input to override messages
+     * @return \Generator<int, string, mixed, void> Yields text chunks as strings
+     * @throws \Exception If streaming fails or platform error occurs
+     */
+    public function stream(array $params, ?string $textInput = null): \Generator
+    {
+        $params['stream'] = true;
+
+        try {
+            $result = $this->platform->invoke(
+                $this->model,
+                $textInput ?? $this->messages,
+                $params
+            );
+
+            foreach ($result->asStream() as $chunk) {
+                if (!empty($chunk)) {
+                    yield $chunk;
+                }
+            }
+        } catch (\Throwable $e) {
+            throw new \Exception(
+                "Streaming failed for model {$this->model}: " . $e->getMessage(),
+                $e->getCode(),
+                $e
+            );
+        }
+    }
+
     /**
      * Converts raw message arrays into a MessageBag.
      *

src/AgentFactory/Agent/Gemini.php

@@ -80,6 +80,42 @@ public function execute(array $params, bool $complete = false, ?string $textInpu
         return $complete ? $result : $result->asText();
     }
 
+    /**
+     * Streams the model response in real-time.
+     *
+     * This method enables streaming mode and yields text chunks as they arrive
+     * from the LLM, allowing for real-time display of the response.
+     *
+     * @param array<string, mixed> $params Additional parameters (temperature, max_tokens, etc.)
+     * @param ?string $textInput Optional text input to override messages
+     * @return \Generator<int, string, mixed, void> Yields text chunks as strings
+     * @throws \Exception If streaming fails or platform error occurs
+     */
+    public function stream(array $params, ?string $textInput = null): \Generator
+    {
+        $params['stream'] = true;
+
+        try {
+            $result = $this->platform->invoke(
+                $this->model,
+                $this->messages,
+                $params
+            );
+
+            foreach ($result->asStream() as $chunk) {
+                if (!empty($chunk)) {
+                    yield $chunk;
+                }
+            }
+        } catch (\Throwable $e) {
+            throw new \Exception(
+                "Streaming failed for model {$this->model}: " . $e->getMessage(),
+                $e->getCode(),
+                $e
+            );
+        }
+    }
+
     /**
      * Converts raw message arrays into a MessageBag.
      *

src/AgentFactory/Agent/OpenAI.php

@@ -80,6 +80,42 @@ public function execute(array $params, bool $complete = false, ?string $textInpu
         return $complete ? $result : $result->asText();
     }
 
+    /**
+     * Streams the model response in real-time.
+     *
+     * This method enables streaming mode and yields text chunks as they arrive
+     * from the LLM, allowing for real-time display of the response.
+     *
+     * @param array<string, mixed> $params Additional parameters (temperature, max_tokens, etc.)
+     * @param ?string $textInput Optional text input to override messages
+     * @return \Generator<int, string, mixed, void> Yields text chunks as strings
+     * @throws \Exception If streaming fails or platform error occurs
+     */
+    public function stream(array $params, ?string $textInput = null): \Generator
+    {
+        $params['stream'] = true;
+
+        try {
+            $result = $this->platform->invoke(
+                $this->model,
+                $textInput ?? $this->messages,
+                $params
+            );
+
+            foreach ($result->asStream() as $chunk) {
+                if (!empty($chunk)) {
+                    yield $chunk;
+                }
+            }
+        } catch (\Throwable $e) {
+            throw new \Exception(
+                "Streaming failed for model {$this->model}: " . $e->getMessage(),
+                $e->getCode(),
+                $e
+            );
+        }
+    }
+
     /**
      * Converts raw message arrays into a MessageBag.
      *

src/AgentFactory/Agent/OpenRouter.php

@@ -80,6 +80,42 @@ public function execute(array $params, bool $complete = false, ?string $textInpu
         return $complete ? $result : $result->asText();
     }
 
+    /**
+     * Streams the model response in real-time.
+     *
+     * This method enables streaming mode and yields text chunks as they arrive
+     * from the LLM, allowing for real-time display of the response.
+     *
+     * @param array<string, mixed> $params Additional parameters (temperature, max_tokens, etc.)
+     * @param ?string $textInput Optional text input to override messages
+     * @return \Generator<int, string, mixed, void> Yields text chunks as strings
+     * @throws \Exception If streaming fails or platform error occurs
+     */
+    public function stream(array $params, ?string $textInput = null): \Generator
+    {
+        $params['stream'] = true;
+
+        try {
+            $result = $this->platform->invoke(
+                $this->model,
+                $textInput ?? $this->messages,
+                $params
+            );
+
+            foreach ($result->asStream() as $chunk) {
+                if (!empty($chunk)) {
+                    yield $chunk;
+                }
+            }
+        } catch (\Throwable $e) {
+            throw new \Exception(
+                "Streaming failed for model {$this->model}: " . $e->getMessage(),
+                $e->getCode(),
+                $e
+            );
+        }
+    }
+
     /**
      * Converts raw message arrays into a MessageBag.
      *

src/AgentFactory/Agent/SelfHost.php

@@ -105,6 +105,42 @@ public function execute(array $params, bool $complete = false, ?string $textInpu
         return $complete ? $result : $result->asText();
     }
 
+    /**
+     * Streams the model response in real-time.
+     *
+     * This method enables streaming mode and yields text chunks as they arrive
+     * from the LLM, allowing for real-time display of the response.
+     *
+     * @param array<string, mixed> $params Additional parameters (temperature, max_tokens, etc.)
+     * @param ?string $textInput Optional text input to override messages
+     * @return \Generator<int, string, mixed, void> Yields text chunks as strings
+     * @throws \Exception If streaming fails or platform error occurs
+     */
+    public function stream(array $params, ?string $textInput = null): \Generator
+    {
+        $params['stream'] = true;
+
+        try {
+            $result = $this->platform->invoke(
+                $this->model,
+                $this->messages,
+                $params
+            );
+
+            foreach ($result->asStream() as $chunk) {
+                if (!empty($chunk)) {
+                    yield $chunk;
+                }
+            }
+        } catch (\Throwable $e) {
+            throw new \Exception(
+                "Streaming failed for model {$this->model}: " . $e->getMessage(),
+                $e->getCode(),
+                $e
+            );
+        }
+    }
+
     /**
      * Converts raw message arrays into a MessageBag.
      *

src/AgentFactory/AgentInterface.php

@@ -34,6 +34,15 @@ public function setMessage(array $messages): mixed;
      */
     public function execute(array $params, bool $complete = false, ?string $textInput = null): mixed;
 
+    /**
+     * Streams the agent's response in real-time using provided parameters.
+     *
+     * @param array $params
+     * @param ?string $textInput
+     * @return \Generator
+     */
+    public function stream(array $params, ?string $textInput = null): \Generator;
+
     /**
      * Converts raw message data into a MessageBag instance.
      *