Merge branch 'php-llm:main' into dall-e-image-generation

Author: DZunke

README.md

@@ -97,6 +97,24 @@ echo $response->getContent(); // "I'm fine, thank you. How can I help you today?
 
 The `MessageInterface` and `Content` interface help to customize this process if needed, e.g. additional state handling.
 
+#### Options
+
+The second parameter of the `call` method is an array of options, which can be used to configure the behavior of the
+chain, like `stream`, `output_structure`, or `response_format`. This behavior is a combination of features provided by
+the underlying model and platform, or additional features provided by processors registered to the chain.
+
+Options design for additional features provided by LLM Chain can be found in this documentation. For model and platform
+specific options, please refer to the respective documentation.
+
+```php
+// Chain and MessageBag instantiation
+
+$response = $chain->call($messages, [
+    'temperature' => 0.5, // example option controlling the randomness of the response, e.g. GPT and Claude
+    'n' => 3,             // example option controlling the number of responses generated, e.g. GPT
+]);
+```
+
 #### Code Examples
 
 1. **Anthropic's Claude**: [chat-claude-anthropic.php](examples/chat-claude-anthropic.php)
@@ -208,11 +226,27 @@ See attribute class [ToolParameter](src/Chain/ToolBox/Attribute/ToolParameter.ph
 > [!NOTE]
 > Please be aware, that this is only converted in a JSON Schema for the LLM to respect, but not validated by LLM Chain.
 
+#### Tool Result Interception
+
+To react to the result of a tool, you can implement an EventListener or EventSubscriber, that listens to the
+`ToolCallsExecuted` event. This event is dispatched after the `ToolBox` executed all current tool calls and enables
+you to skip the next LLM call by setting a response yourself:
+
+```php
+$eventDispatcher->addListener(ToolCallsExecuted::class, function (ToolCallsExecuted $event): void {
+    foreach ($event->toolCallResults as $toolCallResult) {
+        if (str_starts_with($toolCallResult->toolCall->name, 'weather_')) {
+            $event->response = new StructuredResponse($toolCallResult->result);
+        }
+    }
+});
+```
+
 #### Code Examples (with built-in tools)
 
 1. **Clock Tool**: [toolbox-clock.php](examples/toolbox-clock.php)
 1. **SerpAPI Tool**: [toolbox-serpapi.php](examples/toolbox-serpapi.php)
-1. **Weather Tool**: [toolbox-weather.php](examples/toolbox-weather.php)
+1. **Weather Tool with Event Listener**: [toolbox-weather-event.php](examples/toolbox-weather-event.php)
 1. **Wikipedia Tool**: [toolbox-wikipedia.php](examples/toolbox-wikipedia.php)
 1. **YouTube Transcriber Tool**: [toolbox-youtube.php](examples/toolbox-youtube.php) (with streaming)
 

composer.json

@@ -37,6 +37,7 @@
         "symfony/css-selector": "^6.4 || ^7.1",
         "symfony/dom-crawler": "^6.4 || ^7.1",
         "symfony/dotenv": "^6.4 || ^7.1",
+        "symfony/event-dispatcher": "^6.4 || ^7.1",
         "symfony/finder": "^6.4 || ^7.1",
         "symfony/process": "^6.4 || ^7.1",
         "symfony/var-dumper": "^6.4 || ^7.1"

examples/toolbox-weather.php renamed to examples/chat-system-prompt.php

@@ -3,14 +3,10 @@
 use PhpLlm\LlmChain\Bridge\OpenAI\GPT;
 use PhpLlm\LlmChain\Bridge\OpenAI\PlatformFactory;
 use PhpLlm\LlmChain\Chain;
-use PhpLlm\LlmChain\Chain\ToolBox\ChainProcessor;
-use PhpLlm\LlmChain\Chain\ToolBox\Tool\OpenMeteo;
-use PhpLlm\LlmChain\Chain\ToolBox\ToolAnalyzer;
-use PhpLlm\LlmChain\Chain\ToolBox\ToolBox;
+use PhpLlm\LlmChain\Chain\InputProcessor\SystemPromptInputProcessor;
 use PhpLlm\LlmChain\Model\Message\Message;
 use PhpLlm\LlmChain\Model\Message\MessageBag;
 use Symfony\Component\Dotenv\Dotenv;
-use Symfony\Component\HttpClient\HttpClient;
 
 require_once dirname(__DIR__).'/vendor/autoload.php';
 (new Dotenv())->loadEnv(dirname(__DIR__).'/.env');
@@ -23,12 +19,10 @@
 $platform = PlatformFactory::create($_ENV['OPENAI_API_KEY']);
 $llm = new GPT(GPT::GPT_4O_MINI);
 
-$wikipedia = new OpenMeteo(HttpClient::create());
-$toolBox = new ToolBox(new ToolAnalyzer(), [$wikipedia]);
-$processor = new ChainProcessor($toolBox);
-$chain = new Chain($platform, $llm, [$processor], [$processor]);
+$processor = new SystemPromptInputProcessor('You are Yoda and write like he speaks. But short.');
 
-$messages = new MessageBag(Message::ofUser('How is the weather currently in Berlin? And how about tomorrow?'));
+$chain = new Chain($platform, $llm, [$processor]);
+$messages = new MessageBag(Message::ofUser('What is the meaning of life?'));
 $response = $chain->call($messages);
 
 echo $response->getContent().PHP_EOL;

examples/toolbox-weather-event.php

@@ -0,0 +1,47 @@
+<?php
+
+use PhpLlm\LlmChain\Bridge\OpenAI\GPT;
+use PhpLlm\LlmChain\Bridge\OpenAI\PlatformFactory;
+use PhpLlm\LlmChain\Chain;
+use PhpLlm\LlmChain\Chain\ToolBox\ChainProcessor;
+use PhpLlm\LlmChain\Chain\ToolBox\Event\ToolCallsExecuted;
+use PhpLlm\LlmChain\Chain\ToolBox\Tool\OpenMeteo;
+use PhpLlm\LlmChain\Chain\ToolBox\ToolAnalyzer;
+use PhpLlm\LlmChain\Chain\ToolBox\ToolBox;
+use PhpLlm\LlmChain\Model\Message\Message;
+use PhpLlm\LlmChain\Model\Message\MessageBag;
+use PhpLlm\LlmChain\Model\Response\StructuredResponse;
+use Symfony\Component\Dotenv\Dotenv;
+use Symfony\Component\EventDispatcher\EventDispatcher;
+use Symfony\Component\HttpClient\HttpClient;
+
+require_once dirname(__DIR__).'/vendor/autoload.php';
+(new Dotenv())->loadEnv(dirname(__DIR__).'/.env');
+
+if (empty($_ENV['OPENAI_API_KEY'])) {
+    echo 'Please set the OPENAI_API_KEY environment variable.'.PHP_EOL;
+    exit(1);
+}
+
+$platform = PlatformFactory::create($_ENV['OPENAI_API_KEY']);
+$llm = new GPT(GPT::GPT_4O_MINI);
+
+$openMeteo = new OpenMeteo(HttpClient::create());
+$toolBox = new ToolBox(new ToolAnalyzer(), [$openMeteo]);
+$eventDispatcher = new EventDispatcher();
+$processor = new ChainProcessor($toolBox, eventDispatcher: $eventDispatcher);
+$chain = new Chain($platform, $llm, [$processor], [$processor]);
+
+// Add tool call result listener to enforce chain exits direct with structured response for weather tools
+$eventDispatcher->addListener(ToolCallsExecuted::class, function (ToolCallsExecuted $event): void {
+    foreach ($event->toolCallResults as $toolCallResult) {
+        if (str_starts_with($toolCallResult->toolCall->name, 'weather_')) {
+            $event->response = new StructuredResponse($toolCallResult->result);
+        }
+    }
+});
+
+$messages = new MessageBag(Message::ofUser('How is the weather currently in Berlin?'));
+$response = $chain->call($messages);
+
+dump($response->getContent());

src/Bridge/OpenAI/GPT/ResponseConverter.php

@@ -59,9 +59,9 @@ private function convertStream(HttpResponse $response): ToolCallResponse|StreamR
 
         if ($this->streamIsToolCall($stream)) {
             return new ToolCallResponse(...$this->convertStreamToToolCalls($stream));
-        } else {
-            return new StreamResponse($this->convertStreamContent($stream));
         }
+
+        return new StreamResponse($this->convertStreamContent($stream));
     }
 
     private function streamResponse(HttpResponse $response): \Generator

src/Chain.php

@@ -11,74 +11,85 @@
 use PhpLlm\LlmChain\Chain\OutputProcessor;
 use PhpLlm\LlmChain\Exception\InvalidArgumentException;
 use PhpLlm\LlmChain\Exception\MissingModelSupport;
+use PhpLlm\LlmChain\Exception\RuntimeException;
 use PhpLlm\LlmChain\Model\LanguageModel;
 use PhpLlm\LlmChain\Model\Message\MessageBagInterface;
 use PhpLlm\LlmChain\Model\Response\AsyncResponse;
 use PhpLlm\LlmChain\Model\Response\ResponseInterface;
+use Psr\Log\LoggerInterface;
+use Psr\Log\NullLogger;
+use Symfony\Contracts\HttpClient\Exception\ClientExceptionInterface;
+use Symfony\Contracts\HttpClient\Exception\HttpExceptionInterface;
 
 final readonly class Chain implements ChainInterface
 {
     /**
      * @var InputProcessor[]
      */
-    private array $inputProcessor;
+    private array $inputProcessors;
 
     /**
      * @var OutputProcessor[]
      */
-    private array $outputProcessor;
+    private array $outputProcessors;
 
     /**
-     * @param InputProcessor[]  $inputProcessor
-     * @param OutputProcessor[] $outputProcessor
+     * @param InputProcessor[]  $inputProcessors
+     * @param OutputProcessor[] $outputProcessors
      */
     public function __construct(
         private PlatformInterface $platform,
         private LanguageModel $llm,
-        iterable $inputProcessor = [],
-        iterable $outputProcessor = [],
+        iterable $inputProcessors = [],
+        iterable $outputProcessors = [],
+        private LoggerInterface $logger = new NullLogger(),
     ) {
-        $this->inputProcessor = $this->initializeProcessors($inputProcessor, InputProcessor::class);
-        $this->outputProcessor = $this->initializeProcessors($outputProcessor, OutputProcessor::class);
+        $this->inputProcessors = $this->initializeProcessors($inputProcessors, InputProcessor::class);
+        $this->outputProcessors = $this->initializeProcessors($outputProcessors, OutputProcessor::class);
     }
 
     /**
      * @param array<string, mixed> $options
      */
     public function call(MessageBagInterface $messages, array $options = []): ResponseInterface
     {
-        $llm = $this->llm;
+        $input = new Input($this->llm, $messages, $options);
+        array_map(fn (InputProcessor $processor) => $processor->processInput($input), $this->inputProcessors);
 
-        if (array_key_exists('llm', $options)) {
-            if (!$options['llm'] instanceof LanguageModel) {
-                throw new InvalidArgumentException(sprintf('Option "llm" must be an instance of %s.', LanguageModel::class));
-            }
-
-            $llm = $options['llm'];
-            unset($options['llm']);
-        }
-
-        $input = new Input($llm, $messages, $options);
-        array_map(fn (InputProcessor $processor) => $processor->processInput($input), $this->inputProcessor);
+        $llm = $input->llm;
+        $messages = $input->messages;
+        $options = $input->getOptions();
 
         if ($messages->containsImage() && !$llm->supportsImageInput()) {
             throw MissingModelSupport::forImageInput($llm::class);
         }
 
-        $response = $this->platform->request($llm, $messages, $options = $input->getOptions());
+        try {
+            $response = $this->platform->request($llm, $messages, $options);
+
+            if ($response instanceof AsyncResponse) {
+                $response = $response->unwrap();
+            }
+        } catch (ClientExceptionInterface $e) {
+            $message = $e->getMessage();
+            $content = $e->getResponse()->toArray(false);
+
+            $this->logger->debug($message, $content);
 
-        if ($response instanceof AsyncResponse) {
-            $response = $response->unwrap();
+            throw new InvalidArgumentException('' === $message ? 'Invalid request to model or platform' : $message, 0, $e);
+        } catch (HttpExceptionInterface $e) {
+            throw new RuntimeException('Failed to request model', 0, $e);
         }
 
         $output = new Output($llm, $response, $messages, $options);
-        array_map(fn (OutputProcessor $processor) => $processor->processOutput($output), $this->outputProcessor);
+        array_map(fn (OutputProcessor $processor) => $processor->processOutput($output), $this->outputProcessors);
 
         return $output->response;
     }
 
     /**
      * @param InputProcessor[]|OutputProcessor[] $processors
+     * @param class-string                       $interface
      *
      * @return InputProcessor[]|OutputProcessor[]
      */

src/Chain/Input.php

@@ -13,8 +13,8 @@ final class Input
      * @param array<string, mixed> $options
      */
     public function __construct(
-        public readonly LanguageModel $llm,
-        public readonly MessageBagInterface $messages,
+        public LanguageModel $llm,
+        public MessageBagInterface $messages,
         private array $options,
     ) {
     }

src/Chain/InputProcessor/LlmOverrideInputProcessor.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpLlm\LlmChain\Chain\InputProcessor;
+
+use PhpLlm\LlmChain\Chain\Input;
+use PhpLlm\LlmChain\Chain\InputProcessor;
+use PhpLlm\LlmChain\Exception\InvalidArgumentException;
+use PhpLlm\LlmChain\Model\LanguageModel;
+
+final class LlmOverrideInputProcessor implements InputProcessor
+{
+    public function processInput(Input $input): void
+    {
+        $options = $input->getOptions();
+
+        if (!array_key_exists('llm', $options)) {
+            return;
+        }
+
+        if (!$options['llm'] instanceof LanguageModel) {
+            throw new InvalidArgumentException(sprintf('Option "llm" must be an instance of %s.', LanguageModel::class));
+        }
+
+        $input->llm = $options['llm'];
+    }
+}

src/Chain/InputProcessor/SystemPromptInputProcessor.php

@@ -0,0 +1,33 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpLlm\LlmChain\Chain\InputProcessor;
+
+use PhpLlm\LlmChain\Chain\Input;
+use PhpLlm\LlmChain\Chain\InputProcessor;
+use PhpLlm\LlmChain\Model\Message\Message;
+use Psr\Log\LoggerInterface;
+use Psr\Log\NullLogger;
+
+final readonly class SystemPromptInputProcessor implements InputProcessor
+{
+    public function __construct(
+        private string $systemPrompt,
+        private LoggerInterface $logger = new NullLogger(),
+    ) {
+    }
+
+    public function processInput(Input $input): void
+    {
+        $messages = $input->messages;
+
+        if (null !== $messages->getSystemMessage()) {
+            $this->logger->debug('Skipping system prompt injection since MessageBag already contains a system message.');
+
+            return;
+        }
+
+        $input->messages = $messages->prepend(Message::forSystem($this->systemPrompt));
+    }
+}

src/Chain/ToolBox/ChainProcessor.php

@@ -10,16 +10,20 @@
 use PhpLlm\LlmChain\Chain\InputProcessor;
 use PhpLlm\LlmChain\Chain\Output;
 use PhpLlm\LlmChain\Chain\OutputProcessor;
+use PhpLlm\LlmChain\Chain\ToolBox\Event\ToolCallsExecuted;
 use PhpLlm\LlmChain\Exception\MissingModelSupport;
 use PhpLlm\LlmChain\Model\Message\Message;
 use PhpLlm\LlmChain\Model\Response\ToolCallResponse;
+use Symfony\Contracts\EventDispatcher\EventDispatcherInterface;
 
 final class ChainProcessor implements InputProcessor, OutputProcessor, ChainAwareProcessor
 {
     use ChainAwareTrait;
 
     public function __construct(
-        private ToolBoxInterface $toolBox,
+        private readonly ToolBoxInterface $toolBox,
+        private ToolResultConverter $resultConverter = new ToolResultConverter(),
+        private readonly ?EventDispatcherInterface $eventDispatcher = null,
     ) {
     }
 
@@ -47,12 +51,17 @@ public function processOutput(Output $output): void
             $toolCalls = $output->response->getContent();
             $messages->add(Message::ofAssistant(toolCalls: $toolCalls));
 
+            $results = [];
             foreach ($toolCalls as $toolCall) {
                 $result = $this->toolBox->execute($toolCall);
-                $messages->add(Message::ofToolCall($toolCall, $result));
+                $results[] = new ToolCallResult($toolCall, $result);
+                $messages->add(Message::ofToolCall($toolCall, $this->resultConverter->convert($result)));
             }
 
-            $output->response = $this->chain->call($messages, $output->options);
+            $event = new ToolCallsExecuted(...$results);
+            $this->eventDispatcher?->dispatch($event);
+
+            $output->response = $event->hasResponse() ? $event->response : $this->chain->call($messages, $output->options);
         }
     }
 }