refactor: introduce tool metadata factory interface

Author: chr-hertel

src/Chain/ToolBox/Exception/ToolConfigurationException.php

@@ -9,6 +9,11 @@
 
 final class ToolConfigurationException extends InvalidArgumentException implements ExceptionInterface
 {
+    public static function noMetadataFactory(string $tool): self
+    {
+        return new self(sprintf('No metadata factory found for tool "%s".', $tool));
+    }
+
     public static function missingAttribute(string $className): self
     {
         return new self(sprintf('The class "%s" is not a tool, please add %s attribute.', $className, AsTool::class));

src/Chain/ToolBox/MetadataFactory.php

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpLlm\LlmChain\Chain\ToolBox;
+
+interface MetadataFactory
+{
+    public function supports(string $tool): bool;
+
+    /**
+     * @return iterable<Metadata>
+     */
+    public function create(string $tool): iterable;
+}

src/Chain/ToolBox/ToolAnalyzer.php renamed to src/Chain/ToolBox/MetadataFactory/ReflectionFactory.php

@@ -2,35 +2,53 @@
 
 declare(strict_types=1);
 
-namespace PhpLlm\LlmChain\Chain\ToolBox;
+namespace PhpLlm\LlmChain\Chain\ToolBox\MetadataFactory;
 
 use PhpLlm\LlmChain\Chain\JsonSchema\Factory;
 use PhpLlm\LlmChain\Chain\ToolBox\Attribute\AsTool;
 use PhpLlm\LlmChain\Chain\ToolBox\Exception\ToolConfigurationException;
+use PhpLlm\LlmChain\Chain\ToolBox\Metadata;
+use PhpLlm\LlmChain\Chain\ToolBox\MetadataFactory;
 
-final readonly class ToolAnalyzer
+/**
+ * Metadata factory that uses reflection in combination with `#[AsTool]` attribute to extract metadata from tools.
+ */
+final readonly class ReflectionFactory implements MetadataFactory
 {
     public function __construct(
         private Factory $factory = new Factory(),
     ) {
     }
 
     /**
-     * @param class-string $className
-     *
+     * @param class-string $tool
+     */
+    public function supports(string $tool): bool
+    {
+        if (!class_exists($tool)) {
+            return false;
+        }
+
+        $reflectionClass = new \ReflectionClass($tool);
+        $attributes = $reflectionClass->getAttributes(AsTool::class);
+
+        return 0 < count($attributes);
+    }
+
+    /**
      * @return iterable<Metadata>
      */
-    public function getMetadata(string $className): iterable
+    public function create(string $tool): iterable
     {
-        $reflectionClass = new \ReflectionClass($className);
+        $reflectionClass = new \ReflectionClass($tool);
         $attributes = $reflectionClass->getAttributes(AsTool::class);
 
         if (0 === count($attributes)) {
-            throw ToolConfigurationException::missingAttribute($className);
+            throw ToolConfigurationException::missingAttribute($tool);
         }
 
         foreach ($attributes as $attribute) {
-            yield $this->convertAttribute($className, $attribute->newInstance());
+            yield $this->convertAttribute($tool, $attribute->newInstance());
         }
     }
 

src/Chain/ToolBox/ToolBox.php

@@ -4,14 +4,21 @@
 
 namespace PhpLlm\LlmChain\Chain\ToolBox;
 
+use PhpLlm\LlmChain\Chain\ToolBox\Exception\ToolConfigurationException;
 use PhpLlm\LlmChain\Chain\ToolBox\Exception\ToolExecutionException;
 use PhpLlm\LlmChain\Chain\ToolBox\Exception\ToolNotFoundException;
+use PhpLlm\LlmChain\Chain\ToolBox\MetadataFactory\ReflectionFactory;
 use PhpLlm\LlmChain\Model\Response\ToolCall;
 use Psr\Log\LoggerInterface;
 use Psr\Log\NullLogger;
 
 final class ToolBox implements ToolBoxInterface
 {
+    /**
+     * @var list<MetadataFactory>
+     */
+    private readonly array $metadataFactories;
+
     /**
      * @var list<object>
      */
@@ -23,19 +30,21 @@ final class ToolBox implements ToolBoxInterface
     private array $map;
 
     /**
-     * @param iterable<object> $tools
+     * @param iterable<MetadataFactory> $metadataFactories
+     * @param iterable<object>          $tools
      */
     public function __construct(
-        private readonly ToolAnalyzer $toolAnalyzer,
+        iterable $metadataFactories,
         iterable $tools,
         private readonly LoggerInterface $logger = new NullLogger(),
     ) {
+        $this->metadataFactories = $metadataFactories instanceof \Traversable ? iterator_to_array($metadataFactories) : $metadataFactories;
         $this->tools = $tools instanceof \Traversable ? iterator_to_array($tools) : $tools;
     }
 
     public static function create(object ...$tools): self
     {
-        return new self(new ToolAnalyzer(), $tools);
+        return new self([new ReflectionFactory()], $tools);
     }
 
     public function getMap(): array
@@ -46,9 +55,7 @@ public function getMap(): array
 
         $map = [];
         foreach ($this->tools as $tool) {
-            foreach ($this->toolAnalyzer->getMetadata($tool::class) as $metadata) {
-                $map[] = $metadata;
-            }
+            $map = array_merge($map, iterator_to_array($this->getMetadata($tool::class)));
         }
 
         return $this->map = $map;
@@ -57,7 +64,7 @@ public function getMap(): array
     public function execute(ToolCall $toolCall): mixed
     {
         foreach ($this->tools as $tool) {
-            foreach ($this->toolAnalyzer->getMetadata($tool::class) as $metadata) {
+            foreach ($this->getMetadata($tool::class) as $metadata) {
                 if ($metadata->name !== $toolCall->name) {
                     continue;
                 }
@@ -76,4 +83,22 @@ public function execute(ToolCall $toolCall): mixed
 
         throw ToolNotFoundException::notFoundForToolCall($toolCall);
     }
+
+    /**
+     * @param class-string $tool
+     *
+     * @return Metadata[]
+     */
+    private function getMetadata(string $tool): iterable
+    {
+        foreach ($this->metadataFactories as $metadataFactory) {
+            if ($metadataFactory->supports($tool)) {
+                yield from $metadataFactory->create($tool);
+
+                return;
+            }
+        }
+
+        throw ToolConfigurationException::noMetadataFactory($tool);
+    }
 }

tests/Chain/ToolBox/ToolAnalyzerTest.php renamed to tests/Chain/ToolBox/MetadataFactory/ReflectionFactoryTest.php

@@ -2,14 +2,14 @@
 
 declare(strict_types=1);
 
-namespace PhpLlm\LlmChain\Tests\Chain\ToolBox;
+namespace PhpLlm\LlmChain\Tests\Chain\ToolBox\MetadataFactory;
 
 use PhpLlm\LlmChain\Chain\JsonSchema\DescriptionParser;
 use PhpLlm\LlmChain\Chain\JsonSchema\Factory;
 use PhpLlm\LlmChain\Chain\ToolBox\Attribute\AsTool;
 use PhpLlm\LlmChain\Chain\ToolBox\Exception\ToolConfigurationException;
 use PhpLlm\LlmChain\Chain\ToolBox\Metadata;
-use PhpLlm\LlmChain\Chain\ToolBox\ToolAnalyzer;
+use PhpLlm\LlmChain\Chain\ToolBox\MetadataFactory\ReflectionFactory;
 use PhpLlm\LlmChain\Tests\Fixture\Tool\ToolMultiple;
 use PhpLlm\LlmChain\Tests\Fixture\Tool\ToolRequiredParams;
 use PhpLlm\LlmChain\Tests\Fixture\Tool\ToolWrong;
@@ -18,33 +18,33 @@
 use PHPUnit\Framework\Attributes\UsesClass;
 use PHPUnit\Framework\TestCase;
 
-#[CoversClass(ToolAnalyzer::class)]
+#[CoversClass(ReflectionFactory::class)]
 #[UsesClass(AsTool::class)]
 #[UsesClass(Metadata::class)]
 #[UsesClass(Factory::class)]
 #[UsesClass(DescriptionParser::class)]
 #[UsesClass(ToolConfigurationException::class)]
-final class ToolAnalyzerTest extends TestCase
+final class ReflectionFactoryTest extends TestCase
 {
-    private ToolAnalyzer $toolAnalyzer;
+    private ReflectionFactory $factory;
 
     protected function setUp(): void
     {
-        $this->toolAnalyzer = new ToolAnalyzer();
+        $this->factory = new ReflectionFactory();
     }
 
     #[Test]
     public function withoutAttribute(): void
     {
         $this->expectException(ToolConfigurationException::class);
-        iterator_to_array($this->toolAnalyzer->getMetadata(ToolWrong::class));
+        iterator_to_array($this->factory->create(ToolWrong::class));
     }
 
     #[Test]
     public function getDefinition(): void
     {
         /** @var Metadata[] $metadatas */
-        $metadatas = iterator_to_array($this->toolAnalyzer->getMetadata(ToolRequiredParams::class));
+        $metadatas = iterator_to_array($this->factory->create(ToolRequiredParams::class));
 
         self::assertToolConfiguration(
             metadata: $metadatas[0],
@@ -73,7 +73,7 @@ className: ToolRequiredParams::class,
     #[Test]
     public function getDefinitionWithMultiple(): void
     {
-        $metadatas = iterator_to_array($this->toolAnalyzer->getMetadata(ToolMultiple::class));
+        $metadatas = iterator_to_array($this->factory->create(ToolMultiple::class));
 
         self::assertCount(2, $metadatas);
 

tests/Chain/ToolBox/ToolBoxTest.php

@@ -11,7 +11,7 @@
 use PhpLlm\LlmChain\Chain\ToolBox\Exception\ToolExecutionException;
 use PhpLlm\LlmChain\Chain\ToolBox\Exception\ToolNotFoundException;
 use PhpLlm\LlmChain\Chain\ToolBox\Metadata;
-use PhpLlm\LlmChain\Chain\ToolBox\ToolAnalyzer;
+use PhpLlm\LlmChain\Chain\ToolBox\MetadataFactory\ReflectionFactory;
 use PhpLlm\LlmChain\Chain\ToolBox\ToolBox;
 use PhpLlm\LlmChain\Model\Response\ToolCall;
 use PhpLlm\LlmChain\Tests\Fixture\Tool\ToolException;
@@ -29,7 +29,7 @@
 #[UsesClass(ToolCall::class)]
 #[UsesClass(AsTool::class)]
 #[UsesClass(Metadata::class)]
-#[UsesClass(ToolAnalyzer::class)]
+#[UsesClass(ReflectionFactory::class)]
 #[UsesClass(Factory::class)]
 #[UsesClass(DescriptionParser::class)]
 #[UsesClass(ToolConfigurationException::class)]
@@ -41,7 +41,7 @@ final class ToolBoxTest extends TestCase
 
     protected function setUp(): void
     {
-        $this->toolBox = new ToolBox(new ToolAnalyzer(), [
+        $this->toolBox = new ToolBox([new ReflectionFactory()], [
             new ToolRequiredParams(),
             new ToolOptionalParam(),
             new ToolNoParams(),
@@ -132,7 +132,7 @@ public function executeWithMisconfiguredTool(): void
         self::expectException(ToolConfigurationException::class);
         self::expectExceptionMessage('Method "foo" not found in tool "PhpLlm\LlmChain\Tests\Fixture\Tool\ToolMisconfigured".');
 
-        $toolBox = new ToolBox(new ToolAnalyzer(), [new ToolMisconfigured()]);
+        $toolBox = new ToolBox([new ReflectionFactory()], [new ToolMisconfigured()]);
 
         $toolBox->execute(new ToolCall('call_1234', 'tool_misconfigured'));
     }