Google Gemini tool support

examples/google/toolcall.php

@@ -0,0 +1,31 @@
+<?php
+
+use PhpLlm\LlmChain\Chain\Chain;
+use PhpLlm\LlmChain\Chain\Toolbox\ChainProcessor;
+use PhpLlm\LlmChain\Chain\Toolbox\Tool\Clock;
+use PhpLlm\LlmChain\Chain\Toolbox\Toolbox;
+use PhpLlm\LlmChain\Platform\Bridge\Google\Gemini;
+use PhpLlm\LlmChain\Platform\Bridge\Google\PlatformFactory;
+use PhpLlm\LlmChain\Platform\Message\Message;
+use PhpLlm\LlmChain\Platform\Message\MessageBag;
+use Symfony\Component\Dotenv\Dotenv;
+
+require_once dirname(__DIR__, 2).'/vendor/autoload.php';
+(new Dotenv())->loadEnv(dirname(__DIR__, 2).'/.env');
+
+if (empty($_ENV['GOOGLE_API_KEY'])) {
+    echo 'Please set the GOOGLE_API_KEY environment variable.'.\PHP_EOL;
+    exit(1);
+}
+
+$platform = PlatformFactory::create($_ENV['GOOGLE_API_KEY']);
+$llm = new Gemini(Gemini::GEMINI_2_FLASH);
+
+$toolbox = Toolbox::create(new Clock());
+$processor = new ChainProcessor($toolbox);
+$chain = new Chain($platform, $llm, [$processor], [$processor]);
+
+$messages = new MessageBag(Message::ofUser('What time is it?'));
+$response = $chain->call($messages);
+
+echo $response->getContent().\PHP_EOL;

src/Platform/Bridge/Google/Contract/AssistantMessageNormalizer.php

@@ -35,8 +35,23 @@ protected function supportsModel(Model $model): bool
      */
     public function normalize(mixed $data, ?string $format = null, array $context = []): array
     {
-        return [
-            ['text' => $data->content],
-        ];
+        $normalized = [];
+
+        if (isset($data->content)) {
+            $normalized['text'] = $data->content;
+        }
+
+        if (isset($data->toolCalls[0])) {
+            $normalized['functionCall'] = [
+                'id' => $data->toolCalls[0]->id,
+                'name' => $data->toolCalls[0]->name,
+            ];
+
+            if ($data->toolCalls[0]->arguments) {
+                $normalized['functionCall']['args'] = $data->toolCalls[0]->arguments;
+            }
+        }
+
+        return [$normalized];
     }
 }

src/Platform/Bridge/Google/Contract/ToolCallMessageNormalizer.php

@@ -0,0 +1,56 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpLlm\LlmChain\Platform\Bridge\Google\Contract;
+
+use PhpLlm\LlmChain\Platform\Bridge\Google\Gemini;
+use PhpLlm\LlmChain\Platform\Contract\Normalizer\ModelContractNormalizer;
+use PhpLlm\LlmChain\Platform\Message\ToolCallMessage;
+use PhpLlm\LlmChain\Platform\Model;
+use Symfony\Component\Serializer\Normalizer\NormalizerAwareInterface;
+use Symfony\Component\Serializer\Normalizer\NormalizerAwareTrait;
+
+/**
+ * @author Valtteri R <[email protected]>
+ */
+final class ToolCallMessageNormalizer extends ModelContractNormalizer implements NormalizerAwareInterface
+{
+    use NormalizerAwareTrait;
+
+    protected function supportedDataClass(): string
+    {
+        return ToolCallMessage::class;
+    }
+
+    protected function supportsModel(Model $model): bool
+    {
+        return $model instanceof Gemini;
+    }
+
+    /**
+     * @param ToolCallMessage $data
+     *
+     * @return array{
+     *      functionResponse: array{
+     *          id: string,
+     *          name: string,
+     *          response: array<int|string, mixed>
+     *      }
+     *  }[]
+     */
+    public function normalize(mixed $data, ?string $format = null, array $context = []): array
+    {
+        $responseContent = json_validate($data->content) ? json_decode($data->content, true) : $data->content;
+
+        return [[
+            'functionResponse' => array_filter([
+                'id' => $data->toolCall->id,
+                'name' => $data->toolCall->name,
+                'response' => \is_array($responseContent) ? $responseContent : [
+                    'rawResponse' => $responseContent, // Gemini expects the response to be an object, but not everyone uses objects as their responses.
+                ],
+            ]),
+        ]];
+    }
+}

src/Platform/Bridge/Google/Contract/ToolNormalizer.php

@@ -0,0 +1,54 @@
+<?php
+
+namespace PhpLlm\LlmChain\Platform\Bridge\Google\Contract;
+
+use PhpLlm\LlmChain\Platform\Bridge\Google\Gemini;
+use PhpLlm\LlmChain\Platform\Contract\JsonSchema\Factory;
+use PhpLlm\LlmChain\Platform\Contract\Normalizer\ModelContractNormalizer;
+use PhpLlm\LlmChain\Platform\Model;
+use PhpLlm\LlmChain\Platform\Tool\Tool;
+
+/**
+ * @author Valtteri R <[email protected]>
+ *
+ * @phpstan-import-type JsonSchema from Factory
+ */
+final class ToolNormalizer extends ModelContractNormalizer
+{
+    protected function supportedDataClass(): string
+    {
+        return Tool::class;
+    }
+
+    protected function supportsModel(Model $model): bool
+    {
+        return $model instanceof Gemini;
+    }
+
+    /**
+     * @param Tool $data
+     *
+     * @return array{
+     *     functionDeclarations: array{
+     *         name: string,
+     *         description: string,
+     *         parameters: JsonSchema|array{type: 'object'}
+     *     }[]
+     * }
+     */
+    public function normalize(mixed $data, ?string $format = null, array $context = []): array
+    {
+        $parameters = $data->parameters;
+        unset($parameters['additionalProperties']);
+
+        return [
+            'functionDeclarations' => [
+                [
+                    'description' => $data->description,
+                    'name' => $data->name,
+                    'parameters' => $parameters,
+                ],
+            ],
+        ];
+    }
+}

src/Platform/Bridge/Google/Gemini.php

@@ -27,6 +27,7 @@ public function __construct(string $name = self::GEMINI_2_PRO, array $options =
             Capability::INPUT_MESSAGES,
             Capability::INPUT_IMAGE,
             Capability::OUTPUT_STREAMING,
+            Capability::TOOL_CALLING,
         ];
 
         parent::__construct($name, $capabilities, $options);

src/Platform/Bridge/Google/ModelHandler.php

@@ -7,9 +7,13 @@
 use PhpLlm\LlmChain\Platform\Exception\RuntimeException;
 use PhpLlm\LlmChain\Platform\Model;
 use PhpLlm\LlmChain\Platform\ModelClientInterface;
+use PhpLlm\LlmChain\Platform\Response\Choice;
+use PhpLlm\LlmChain\Platform\Response\ChoiceResponse;
 use PhpLlm\LlmChain\Platform\Response\ResponseInterface as LlmResponse;
 use PhpLlm\LlmChain\Platform\Response\StreamResponse;
 use PhpLlm\LlmChain\Platform\Response\TextResponse;
+use PhpLlm\LlmChain\Platform\Response\ToolCall;
+use PhpLlm\LlmChain\Platform\Response\ToolCallResponse;
 use PhpLlm\LlmChain\Platform\ResponseConverterInterface;
 use Symfony\Component\HttpClient\EventSourceHttpClient;
 use Symfony\Contracts\HttpClient\Exception\ClientExceptionInterface;
@@ -52,6 +56,12 @@ public function request(Model $model, array|string $payload, array $options = []
 
         $generationConfig = ['generationConfig' => $options];
         unset($generationConfig['generationConfig']['stream']);
+        unset($generationConfig['generationConfig']['tools']);
+
+        if (isset($options['tools'])) {
+            $generationConfig['tools'] = $options['tools'];
+            unset($options['tools']);
+        }
 
         return $this->httpClient->request('POST', $url, [
             'headers' => [
@@ -76,11 +86,22 @@ public function convert(ResponseInterface $response, array $options = []): LlmRe
 
         $data = $response->toArray();
 
-        if (!isset($data['candidates'][0]['content']['parts'][0]['text'])) {
+        if (!isset($data['candidates'][0]['content']['parts'][0])) {
             throw new RuntimeException('Response does not contain any content');
         }
 
-        return new TextResponse($data['candidates'][0]['content']['parts'][0]['text']);
+        /** @var Choice[] $choices */
+        $choices = array_map($this->convertChoice(...), $data['candidates']);
+
+        if (1 !== \count($choices)) {
+            return new ChoiceResponse(...$choices);
+        }
+
+        if ($choices[0]->hasToolCall()) {
+            return new ToolCallResponse(...$choices[0]->getToolCalls());
+        }
+
+        return new TextResponse($choices[0]->getContent());
     }
 
     private function convertStream(ResponseInterface $response): \Generator
@@ -114,12 +135,68 @@ private function convertStream(ResponseInterface $response): \Generator
                     throw new RuntimeException('Failed to decode JSON response', 0, $e);
                 }
 
-                if (!isset($data['candidates'][0]['content']['parts'][0]['text'])) {
+                /** @var Choice[] $choices */
+                $choices = array_map($this->convertChoice(...), $data['candidates'] ?? []);
+
+                if (!$choices) {
                     continue;
                 }
 
-                yield $data['candidates'][0]['content']['parts'][0]['text'];
+                if (1 !== \count($choices)) {
+                    yield new ChoiceResponse(...$choices);
+                    continue;
+                }
+
+                if ($choices[0]->hasToolCall()) {
+                    yield new ToolCallResponse(...$choices[0]->getToolCalls());
+                }
+
+                if ($choices[0]->hasContent()) {
+                    yield $choices[0]->getContent();
+                }
             }
         }
     }
+
+    /**
+     * @param array{
+     *     finishReason?: string,
+     *     content: array{
+     *         parts: array{
+     *             functionCall?: array{
+     *                 id: string,
+     *                 name: string,
+     *                 args: mixed[]
+     *             },
+     *             text?: string
+     *         }[]
+     *     }
+     * } $choice
+     */
+    private function convertChoice(array $choice): Choice
+    {
+        $contentPart = $choice['content']['parts'][0] ?? [];
+
+        if (isset($contentPart['functionCall'])) {
+            return new Choice(toolCalls: [$this->convertToolCall($contentPart['functionCall'])]);
+        }
+
+        if (isset($contentPart['text'])) {
+            return new Choice($contentPart['text']);
+        }
+
+        throw new RuntimeException(\sprintf('Unsupported finish reason "%s".', $choice['finishReason']));
+    }
+
+    /**
+     * @param array{
+     *     id: string,
+     *     name: string,
+     *     args: mixed[]
+     * } $toolCall
+     */
+    private function convertToolCall(array $toolCall): ToolCall
+    {
+        return new ToolCall($toolCall['id'] ?? '', $toolCall['name'], $toolCall['args']);
+    }
 }

src/Platform/Bridge/Google/PlatformFactory.php

@@ -6,6 +6,8 @@
 
 use PhpLlm\LlmChain\Platform\Bridge\Google\Contract\AssistantMessageNormalizer;
 use PhpLlm\LlmChain\Platform\Bridge\Google\Contract\MessageBagNormalizer;
+use PhpLlm\LlmChain\Platform\Bridge\Google\Contract\ToolCallMessageNormalizer;
+use PhpLlm\LlmChain\Platform\Bridge\Google\Contract\ToolNormalizer;
 use PhpLlm\LlmChain\Platform\Bridge\Google\Contract\UserMessageNormalizer;
 use PhpLlm\LlmChain\Platform\Contract;
 use PhpLlm\LlmChain\Platform\Platform;
@@ -28,6 +30,8 @@ public static function create(
         return new Platform([$responseHandler], [$responseHandler], Contract::create(
             new AssistantMessageNormalizer(),
             new MessageBagNormalizer(),
+            new ToolNormalizer(),
+            new ToolCallMessageNormalizer(),
             new UserMessageNormalizer(),
         ));
     }

tests/Platform/Bridge/Google/Contract/AssistantMessageNormalizerTest.php

@@ -9,7 +9,9 @@
 use PhpLlm\LlmChain\Platform\Contract;
 use PhpLlm\LlmChain\Platform\Message\AssistantMessage;
 use PhpLlm\LlmChain\Platform\Model;
+use PhpLlm\LlmChain\Platform\Response\ToolCall;
 use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\DataProvider;
 use PHPUnit\Framework\Attributes\Small;
 use PHPUnit\Framework\Attributes\Test;
 use PHPUnit\Framework\Attributes\UsesClass;
@@ -20,6 +22,7 @@
 #[UsesClass(Gemini::class)]
 #[UsesClass(AssistantMessage::class)]
 #[UsesClass(Model::class)]
+#[UsesClass(ToolCall::class)]
 final class AssistantMessageNormalizerTest extends TestCase
 {
     #[Test]
@@ -41,14 +44,33 @@ public function getSupportedTypes(): void
         self::assertSame([AssistantMessage::class => true], $normalizer->getSupportedTypes(null));
     }
 
+    #[DataProvider('normalizeDataProvider')]
     #[Test]
-    public function normalize(): void
+    public function normalize(AssistantMessage $message, array $expectedOutput): void
     {
         $normalizer = new AssistantMessageNormalizer();
-        $message = new AssistantMessage('Great to meet you. What would you like to know?');
 
         $normalized = $normalizer->normalize($message);
 
-        self::assertSame([['text' => 'Great to meet you. What would you like to know?']], $normalized);
+        self::assertSame($expectedOutput, $normalized);
+    }
+
+    /**
+     * @return iterable<string, array{AssistantMessage, array{text?: string, functionCall?: array{id: string, name: string, args?: mixed}}[]}>
+     */
+    public static function normalizeDataProvider(): iterable
+    {
+        yield 'assistant message' => [
+            new AssistantMessage('Great to meet you. What would you like to know?'),
+            [['text' => 'Great to meet you. What would you like to know?']],
+        ];
+        yield 'function call' => [
+            new AssistantMessage(toolCalls: [new ToolCall('id1', 'name1', ['arg1' => '123'])]),
+            [['functionCall' => ['id' => 'id1', 'name' => 'name1', 'args' => ['arg1' => '123']]]],
+        ];
+        yield 'function call without parameters' => [
+            new AssistantMessage(toolCalls: [new ToolCall('id1', 'name1')]),
+            [['functionCall' => ['id' => 'id1', 'name' => 'name1']]],
+        ];
     }
 }