ClosureTool.php

<?php

declare(strict_types=1);

namespace Cortex\Tools;

use Closure;
use ReflectionFunction;
use Cortex\Attributes\Tool;
use Cortex\LLM\Data\ToolCall;
use Cortex\JsonSchema\SchemaFactory;
use Cortex\JsonSchema\Support\DocParser;
use Cortex\JsonSchema\Types\ObjectSchema;

class ClosureTool extends AbstractTool
{
    protected ReflectionFunction $reflection;

    protected ObjectSchema $schema;

    public function __construct(
        protected Closure $closure,
        protected ?string $name = null,
        protected ?string $description = null,
    ) {
        $this->reflection = new ReflectionFunction($closure);
        $this->schema = SchemaFactory::fromClosure($closure);
    }

    public function name(): string
    {
        return $this->name ?? $this->resolveName();
    }

    public function description(): string
    {
        return $this->description ?? $this->resolveDescription();
    }

    public function schema(): ObjectSchema
    {
        return $this->schema;
    }

    /**
     * @param ToolCall|array<string, mixed> $toolCall
     */
    public function invoke(ToolCall|array $toolCall = []): mixed
    {
        // Get the arguments from the given tool call.
        $arguments = $this->getArguments($toolCall);

        // Ensure arguments are valid as per the tool's schema.
        $this->schema->validate($arguments);

        // Invoke the closure with the arguments.
        return $this->reflection->invokeArgs($arguments);
    }

    /**
     * Attempt to resolve the name of the tool from the Tool attribute,
     * or the name of the closure if no Tool attribute is present.
     */
    protected function resolveName(string $default = 'closure'): string
    {
        $parameters = $this->getToolAttributeParameters();

        return $parameters['name'] ?? $default;
    }

    /**
     * Attempt to resolve the description of the tool from the Tool attribute,
     * or the docblock of the closure if no Tool attribute is present.
     */
    protected function resolveDescription(string $default = ''): string
    {
        $parameters = $this->getToolAttributeParameters();

        if (is_array($parameters)) {
            return $parameters['description'];
        }

        $docblock = $this->reflection->getDocComment();

        if ($docblock === false) {
            return $default;
        }

        $docParser = new DocParser($docblock);

        return $docParser->description() ?? $default;
    }

    /**
     * Get the parameters from the Tool attribute.
     *
     * @return array{name: string, description: string}|null
     */
    protected function getToolAttributeParameters(): ?array
    {
        $attributes = $this->reflection->getAttributes(Tool::class);

        if (isset($attributes[0])) {
            return $attributes[0]->getArguments();
        }

        return null;
    }
}