feat: Denormalize tool arguments (#359)

Resolves #352

Author: valtzu

src/Chain/Toolbox/Event/ToolCallArgumentsResolved.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpLlm\LlmChain\Chain\Toolbox\Event;
+
+use PhpLlm\LlmChain\Platform\Tool\Tool;
+
+/**
+ * Dispatched after the arguments are denormalized, just before invoking the tool.
+ *
+ * @author Valtteri R <valtzu@gmail.com>
+ */
+final readonly class ToolCallArgumentsResolved
+{
+    /**
+     * @param array<string, mixed> $arguments
+     */
+    public function __construct(
+        public object $tool,
+        public Tool $metadata,
+        public array $arguments,
+    ) {
+    }
+}

src/Chain/Toolbox/ToolCallArgumentResolver.php

@@ -0,0 +1,36 @@
+<?php
+
+namespace PhpLlm\LlmChain\Chain\Toolbox;
+
+use PhpLlm\LlmChain\Platform\Response\ToolCall;
+use PhpLlm\LlmChain\Platform\Tool\Tool;
+use Symfony\Component\Serializer\Normalizer\DateTimeNormalizer;
+use Symfony\Component\Serializer\Normalizer\DenormalizerInterface;
+use Symfony\Component\Serializer\Normalizer\ObjectNormalizer;
+use Symfony\Component\Serializer\Serializer;
+
+/**
+ * @author Valtteri R <valtzu@gmail.com>
+ */
+final readonly class ToolCallArgumentResolver implements ToolCallArgumentResolverInterface
+{
+    public function __construct(
+        private DenormalizerInterface $denormalizer = new Serializer([new DateTimeNormalizer(), new ObjectNormalizer()]),
+    ) {
+    }
+
+    public function resolveArguments(object $tool, Tool $metadata, ToolCall $toolCall): array
+    {
+        $method = new \ReflectionMethod($metadata->reference->class, $metadata->reference->method);
+
+        /** @var array<string, \ReflectionProperty> $parameters */
+        $parameters = array_column($method->getParameters(), null, 'name');
+        $arguments = [];
+
+        foreach ($toolCall->arguments as $name => $value) {
+            $arguments[$name] = $this->denormalizer->denormalize($value, (string) $parameters[$name]->getType());
+        }
+
+        return $arguments;
+    }
+}

src/Chain/Toolbox/ToolCallArgumentResolverInterface.php

@@ -0,0 +1,17 @@
+<?php
+
+namespace PhpLlm\LlmChain\Chain\Toolbox;
+
+use PhpLlm\LlmChain\Platform\Response\ToolCall;
+use PhpLlm\LlmChain\Platform\Tool\Tool;
+
+/**
+ * @author Valtteri R <valtzu@gmail.com>
+ */
+interface ToolCallArgumentResolverInterface
+{
+    /**
+     * @return array<string, mixed>
+     */
+    public function resolveArguments(object $tool, Tool $metadata, ToolCall $toolCall): array;
+}

src/Chain/Toolbox/Toolbox.php

@@ -4,13 +4,15 @@
 
 namespace PhpLlm\LlmChain\Chain\Toolbox;
 
+use PhpLlm\LlmChain\Chain\Toolbox\Event\ToolCallArgumentsResolved;
 use PhpLlm\LlmChain\Chain\Toolbox\Exception\ToolExecutionException;
 use PhpLlm\LlmChain\Chain\Toolbox\Exception\ToolNotFoundException;
 use PhpLlm\LlmChain\Chain\Toolbox\ToolFactory\ReflectionToolFactory;
 use PhpLlm\LlmChain\Platform\Response\ToolCall;
 use PhpLlm\LlmChain\Platform\Tool\Tool;
 use Psr\Log\LoggerInterface;
 use Psr\Log\NullLogger;
+use Symfony\Contracts\EventDispatcher\EventDispatcherInterface;
 
 /**
  * @author Christopher Hertel <mail@christopher-hertel.de>
@@ -38,6 +40,8 @@ public function __construct(
         private readonly ToolFactoryInterface $toolFactory,
         iterable $tools,
         private readonly LoggerInterface $logger = new NullLogger(),
+        private readonly ToolCallArgumentResolverInterface $argumentResolver = new ToolCallArgumentResolver(),
+        private readonly ?EventDispatcherInterface $eventDispatcher = null,
     ) {
         $this->tools = $tools instanceof \Traversable ? iterator_to_array($tools) : $tools;
     }
@@ -70,7 +74,11 @@ public function execute(ToolCall $toolCall): mixed
 
         try {
             $this->logger->debug(\sprintf('Executing tool "%s".', $toolCall->name), $toolCall->arguments);
-            $result = $tool->{$metadata->reference->method}(...$toolCall->arguments);
+
+            $arguments = $this->argumentResolver->resolveArguments($tool, $metadata, $toolCall);
+            $this->eventDispatcher?->dispatch(new ToolCallArgumentsResolved($tool, $metadata, $arguments));
+
+            $result = $tool->{$metadata->reference->method}(...$arguments);
         } catch (\Throwable $e) {
             $this->logger->warning(\sprintf('Failed to execute tool "%s".', $toolCall->name), ['exception' => $e]);
             throw ToolExecutionException::executionFailed($toolCall, $e);

tests/Chain/Toolbox/ToolCallArgumentResolverTest.php

@@ -0,0 +1,32 @@
+<?php
+
+namespace PhpLlm\LlmChain\Tests\Chain\Toolbox;
+
+use PhpLlm\LlmChain\Chain\Toolbox\ToolCallArgumentResolver;
+use PhpLlm\LlmChain\Platform\Response\ToolCall;
+use PhpLlm\LlmChain\Platform\Tool\ExecutionReference;
+use PhpLlm\LlmChain\Platform\Tool\Tool;
+use PhpLlm\LlmChain\Tests\Fixture\Tool\ToolDate;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\Attributes\UsesClass;
+use PHPUnit\Framework\TestCase;
+
+#[CoversClass(ToolCallArgumentResolver::class)]
+#[UsesClass(Tool::class)]
+#[UsesClass(ExecutionReference::class)]
+#[UsesClass(ToolCall::class)]
+class ToolCallArgumentResolverTest extends TestCase
+{
+    #[Test]
+    public function resolveArguments(): void
+    {
+        $resolver = new ToolCallArgumentResolver();
+
+        $tool = new ToolDate();
+        $metadata = new Tool(new ExecutionReference(ToolDate::class, '__invoke'), 'tool_date', 'test');
+        $toolCall = new ToolCall('invocation', 'tool_date', ['date' => '2025-06-29']);
+
+        self::assertEquals(['date' => new \DateTimeImmutable('2025-06-29')], $resolver->resolveArguments($tool, $metadata, $toolCall));
+    }
+}

tests/Chain/Toolbox/ToolboxTest.php

@@ -17,6 +17,7 @@
 use PhpLlm\LlmChain\Platform\Response\ToolCall;
 use PhpLlm\LlmChain\Platform\Tool\ExecutionReference;
 use PhpLlm\LlmChain\Platform\Tool\Tool;
+use PhpLlm\LlmChain\Tests\Fixture\Tool\ToolDate;
 use PhpLlm\LlmChain\Tests\Fixture\Tool\ToolException;
 use PhpLlm\LlmChain\Tests\Fixture\Tool\ToolMisconfigured;
 use PhpLlm\LlmChain\Tests\Fixture\Tool\ToolNoAttribute1;
@@ -53,6 +54,7 @@ protected function setUp(): void
             new ToolOptionalParam(),
             new ToolNoParams(),
             new ToolException(),
+            new ToolDate(),
         ]);
     }
 
@@ -115,11 +117,30 @@ public function getTools(): void
             'This tool is broken',
         );
 
+        $toolDate = new Tool(
+            new ExecutionReference(ToolDate::class, '__invoke'),
+            'tool_date',
+            'A tool with date parameter',
+            [
+                'type' => 'object',
+                'properties' => [
+                    'date' => [
+                        'type' => 'string',
+                        'format' => 'date-time',
+                        'description' => 'The date',
+                    ],
+                ],
+                'required' => ['date'],
+                'additionalProperties' => false,
+            ],
+        );
+
         $expected = [
             $toolRequiredParams,
             $toolOptionalParam,
             $toolNoParams,
             $toolException,
+            $toolDate,
         ];
 
         self::assertEquals($expected, $actual);
@@ -174,6 +195,12 @@ public static function executeProvider(): iterable
             'tool_required_params',
             ['text' => 'Hello', 'number' => 3],
         ];
+
+        yield 'tool_date' => [
+            'Weekday: Sunday',
+            'tool_date',
+            ['date' => '2025-06-29'],
+        ];
     }
 
     #[Test]

tests/Fixture/Tool/ToolDate.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpLlm\LlmChain\Tests\Fixture\Tool;
+
+use PhpLlm\LlmChain\Chain\Toolbox\Attribute\AsTool;
+
+#[AsTool('tool_date', 'A tool with date parameter')]
+final class ToolDate
+{
+    /**
+     * @param \DateTimeImmutable $date The date
+     */
+    public function __invoke(\DateTimeImmutable $date): string
+    {
+        return \sprintf('Weekday: %s', $date->format('l'));
+    }
+}