Using reflection API for tools

[eabay]

Hey @ilvalerione,

Thank you for such a well-thought, clean and simple solution. Very much appreciated!

Since the encapsulation is one of the most important aspects of Neuron AI, I think having another abstraction layer would be a good idea to define tools as single classes where the properties are also handled by ReflectionMethod automatically.

Reference implementation:

<?php

namespace AI\Tools;

use NeuronAI\Tools\Tool as BaseTool;
use NeuronAI\Tools\ToolProperty;

abstract class Tool extends BaseTool
{
    public function __construct(string $name, string $description)
    {
        parent::__construct($name, $description);

        $reflection = new \ReflectionMethod($this, '__invoke');
        $docComment = $reflection->getDocComment();
        $paramDescriptions = $this->parseDocCommentParams($docComment);

        foreach ($reflection->getParameters() as $parameter) {
            $description = $paramDescriptions[$parameter->getName()] ?? '';

            $this->addProperty(
                new ToolProperty($parameter->getName(),
                    $parameter->getType()->getName(),
                    $description,
                    ! $parameter->isOptional()
                ),
            );
        }

        $this->setCallable($this);
    }

    protected function parseDocCommentParams($docComment): array
    {
        $params = [];

        if (! $docComment) {
            return $params;
        }

        if (preg_match_all('/@param\s+(\S+)\s+\$(\S+)\s+(.*)$/m', $docComment, $matches, PREG_SET_ORDER)) {
            foreach ($matches as $match) {
                $paramName = $match[2];
                $paramDescription = trim($match[3]);
                $params[$paramName] = $paramDescription;
            }
        }

        return $params;
    }
}

<?php

namespace AI\Tools;

class TranscriptionTool extends Tool
{
    public function __construct()
    {
        parent::__construct(
            'transcribe',
            'Use this tool to transcribe video to text.'
        );
    }

    /**
     * @param  string  $url  The URL of the video file.
     */
    public function __invoke(string $url): string
    {
        //...
        
        return 'Lorem ipsum';
    }
}

<?php

namespace AI\Agents;

use NeuronAI\Agent;
use AI\Tools\TranscriptionTool;

class ExampleAgent extends Agent
{
    protected function tools(): array
    {
        return [
            TranscriptionTool::make(),
        ];
    }
}

Obviously it doesn't cover everything about what you can do with ToolProperty like enums. I would like to get your opinion before moving forward, though.

[ilvalerione]

Hi @eabay thank you for exploring new possibilities. I had to say that I don't see a clear advantage. Consider this tool for example: https://github.com/inspector-apm/neuron-ai/blob/main/src/Tools/Toolkits/Tavily/TavilySearchTool.php

The syntax still clear. I'm looking now for things that can open the door for use cases, while stay lean. I really would integrate all the great PR I'm getting, but I have to be careful because this environment is changing rapidly so I need to keep the framework agile for changes if necessary. Feel free to give me your feedback.

[eabay]

I completely agree about keeping the codebase clean and being selective. In the early stages, requests from a small group of interested users can quickly lead to unnecessary complexity.

TavilySearchTool effectively encapsulates functionality, making it more convenient than defining tools directly within the agent. This approach avoids the need to duplicate tool definitions and callables across different contexts. However, it’s still important to ensure that the tool’s definition and function signature remain synchronized, as highlighted in the documentation:

Notice that the ToolProperty we define should match with the signature of the function you use as a callable. The callable gets the $video_url arguments, and the name of the property is exactly "video_url".

While this might seem like a minor detail, it enhances the developer experience. Keeping related components close together reduces the likelihood of discrepancies and errors, even if it doesn’t eliminate them entirely.

[tacman]

In Symfony, it would be relatively easy to register the tools automatically with attributes and reflection. I'd like to see

#[AsTool('transcribe', 'Use this tool to transcribe video to text.')]
class TranscriptionTool extends Tool
{
    public function __construct(private YoutubeService $youtubeService)
    {
    }

    /**
     * @param  string  $url  The URL of the video file.
     */
    public function __invoke(string $url): string
    {
        //...
       return $this->youtubeService->transcribe($url);
    }
}

Then instead of using TranscriptionTool::make(), you'd inject it. There are a few ways to do that in Symfony

e.g. in a Command

public function __construct(
          private TranscriptionTool $transcriptionTool,
          private Tool $transcriptionTool, /* uses some magic to fetch the right one based on the name */
          #[Target('transcription')] private Tool $tTool
) {}

I'm not familiar enough with the other platforms, but the tool declaration right now seems verbose, having to declare the parameters in the definition and then again in the function itself.