feat: Google Gemini server tools (#356)

Add support for Google server-side tools like [Google
search](https://ai.google.dev/gemini-api/docs/google-search), [URL
context](https://ai.google.dev/gemini-api/docs/url-context) & [Code
execution](https://ai.google.dev/gemini-api/docs/code-execution)

---

I thought of using `Tool` classes for this but didn't find any solution
I was happy with, so went the easy way for now.

Ideally no changes would've been required for this approach at all, but
there were 2 issues:
1. Gemini API insist on providing empty object, and IMO it's not
feasible to expect end-user to provide `new \ArrayObject()`
2. If you provide `tools` in `call`'s `$options`, then all toolbox tools
go away – hence the new `server_tools` _(open to better naming –
`remote_tools`?)_

---

If someone has already given this a thought, please share your thoughts
/ if there is some clear better approach

Author: valtzu

examples/google/server-tools.php

@@ -0,0 +1,40 @@
+<?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']);
+
+// Available server-side tools as of 2025-06-28: url_context, google_search, code_execution
+$llm = new Gemini('gemini-2.5-pro-preview-03-25', ['server_tools' => ['url_context' => true], 'temperature' => 1.0]);
+
+$toolbox = Toolbox::create(new Clock());
+$processor = new ChainProcessor($toolbox);
+$chain = new Chain($platform, $llm);
+
+$messages = new MessageBag(
+    Message::ofUser(
+        <<<'PROMPT'
+            What was the 12 month Euribor rate a week ago based on https://www.euribor-rates.eu/en/current-euribor-rates/4/euribor-rate-12-months/
+            PROMPT,
+    ),
+);
+
+$response = $chain->call($messages);
+
+echo $response->getContent().\PHP_EOL;

src/Platform/Bridge/Google/ModelHandler.php

@@ -63,12 +63,21 @@ public function request(Model $model, array|string $payload, array $options = []
         $generationConfig = ['generationConfig' => $options];
         unset($generationConfig['generationConfig']['stream']);
         unset($generationConfig['generationConfig']['tools']);
+        unset($generationConfig['generationConfig']['server_tools']);
 
         if (isset($options['tools'])) {
             $generationConfig['tools'] = $options['tools'];
             unset($options['tools']);
         }
 
+        foreach ($options['server_tools'] ?? [] as $tool => $params) {
+            if (!$params) {
+                continue;
+            }
+
+            $generationConfig['tools'][] = [$tool => true === $params ? new \ArrayObject() : $params];
+        }
+
         return $this->httpClient->request('POST', $url, [
             'headers' => [
                 'x-goog-api-key' => $this->apiKey,

src/Platform/Contract.php

@@ -16,6 +16,7 @@
 use PhpLlm\LlmChain\Platform\Contract\Normalizer\Response\ToolCallNormalizer;
 use PhpLlm\LlmChain\Platform\Contract\Normalizer\ToolNormalizer;
 use PhpLlm\LlmChain\Platform\Tool\Tool;
+use Symfony\Component\Serializer\Normalizer\AbstractObjectNormalizer;
 use Symfony\Component\Serializer\Normalizer\NormalizerInterface;
 use Symfony\Component\Serializer\Serializer;
 
@@ -74,6 +75,6 @@ public function createRequestPayload(Model $model, object|array|string $input):
      */
     public function createToolOption(array $tools, Model $model): array
     {
-        return $this->normalizer->normalize($tools, context: [self::CONTEXT_MODEL => $model]);
+        return $this->normalizer->normalize($tools, context: [self::CONTEXT_MODEL => $model, AbstractObjectNormalizer::PRESERVE_EMPTY_OBJECTS => true]);
     }
 }