From 489454bda5dd2b1f69235296b7310e2008c61e81 Mon Sep 17 00:00:00 2001 From: Oskar Stark Date: Tue, 1 Jul 2025 09:07:59 +0200 Subject: [PATCH 01/11] docs: Add comprehensive documentation for Google Gemini server tools - Created detailed documentation explaining URL Context, Google Search, and Code Execution tools - Added usage examples, configuration options, and best practices - Updated README.md to reference the new documentation - Covers implementation from PR #356 --- README.md | 4 + docs/google-server-tools.md | 226 ++++++++++++++++++++++++++++++++++++ 2 files changed, 230 insertions(+) create mode 100644 docs/google-server-tools.md diff --git a/README.md b/README.md index 7a1fb99e..747205de 100644 --- a/README.md +++ b/README.md @@ -172,6 +172,10 @@ $response = $chain->call($messages, [ To integrate LLMs with your application, LLM Chain supports [tool calling](https://platform.openai.com/docs/guides/function-calling) out of the box. Tools are services that can be called by the LLM to provide additional features or process data. +#### Server Tools (Google Gemini) + +Google Gemini provides built-in server-side tools for enhanced capabilities without custom implementations. See the [Server Tools Documentation](docs/google-server-tools.md) for detailed usage instructions. + Tool calling can be enabled by registering the processors in the chain: ```php diff --git a/docs/google-server-tools.md b/docs/google-server-tools.md new file mode 100644 index 00000000..6d2995d2 --- /dev/null +++ b/docs/google-server-tools.md @@ -0,0 +1,226 @@ +# Google Gemini Server Tools + +Server tools are built-in capabilities provided by Google Gemini that allow the model to perform specific actions without requiring custom tool implementations. These tools run on Google's servers and provide access to external data and execution environments. + +## Overview + +Google Gemini provides several server-side tools that can be enabled when calling the model: + +- **URL Context** - Fetches and analyzes content from URLs +- **Google Search** - Performs web searches using Google +- **Code Execution** - Executes code in a sandboxed environment + +## Installation + +Server tools are available through the Google platform bridge: + +```php +composer require php-llm/llm-chain +``` + +## Basic Usage + +To use server tools, specify them in the model options when creating a Gemini instance: + +```php +use PhpLlm\LlmChain\Platform\Bridge\Google\Gemini; +use PhpLlm\LlmChain\Platform\Bridge\Google\PlatformFactory; + +$platform = PlatformFactory::create($_ENV['GOOGLE_API_KEY']); + +// Enable URL Context tool +$llm = new Gemini('gemini-2.5-pro-preview-03-25', [ + 'server_tools' => [ + 'url_context' => true + ], + 'temperature' => 1.0 +]); +``` + +## Available Server Tools + +### URL Context + +The URL Context tool allows Gemini to fetch and analyze content from web pages. This is useful for: + +- Analyzing current web content +- Extracting information from specific pages +- Understanding context from external sources + +```php +$llm = new Gemini('gemini-2.5-pro-preview-03-25', [ + 'server_tools' => [ + 'url_context' => true + ] +]); + +$messages = new MessageBag( + Message::ofUser('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/') +); + +$response = $chain->call($messages); +``` + +### Google Search + +The Google Search tool enables the model to search the web and incorporate search results into its responses: + +```php +$llm = new Gemini('gemini-2.5-pro-preview-03-25', [ + 'server_tools' => [ + 'google_search' => true + ] +]); + +$messages = new MessageBag( + Message::ofUser('What are the latest developments in quantum computing?') +); + +$response = $chain->call($messages); +``` + +### Code Execution + +The Code Execution tool provides a sandboxed environment for running code: + +```php +$llm = new Gemini('gemini-2.5-pro-preview-03-25', [ + 'server_tools' => [ + 'code_execution' => true + ] +]); + +$messages = new MessageBag( + Message::ofUser('Calculate the factorial of 20 and show me the code') +); + +$response = $chain->call($messages); +``` + +## Using Multiple Server Tools + +You can enable multiple server tools simultaneously: + +```php +$llm = new Gemini('gemini-2.5-pro-preview-03-25', [ + 'server_tools' => [ + 'url_context' => true, + 'google_search' => true, + 'code_execution' => true + ] +]); +``` + +## Advanced Configuration + +### Server Tools with Parameters + +For server tools that accept parameters, you can pass an array instead of `true`: + +```php +$llm = new Gemini('gemini-2.5-pro-preview-03-25', [ + 'server_tools' => [ + 'url_context' => [ + // Future parameters can be added here + ] + ] +]); +``` + +### Combining with Custom Tools + +Server tools can be used alongside custom tools from the toolbox: + +```php +use PhpLlm\LlmChain\Chain\Toolbox\Tool\Clock; +use PhpLlm\LlmChain\Chain\Toolbox\Toolbox; + +$toolbox = Toolbox::create(new Clock()); +$processor = new ChainProcessor($toolbox); +$chain = new Chain($platform, $llm); + +$llm = new Gemini('gemini-2.5-pro-preview-03-25', [ + 'server_tools' => [ + 'url_context' => true + ] +]); + +// Both server tools and custom tools will be available +``` + +## Implementation Details + +The server tools implementation works by: + +1. Converting server tool configurations into the format expected by Google's API +2. For boolean `true` values, an empty `ArrayObject` is sent as required by the API +3. Server tools are added to the `tools` array in the API request +4. The `server_tools` option is separate from regular `tools` to prevent toolbox tools from being overwritten + +## Best Practices + +1. **Enable only needed tools** - Each enabled tool increases latency and token usage +2. **Consider rate limits** - Server tools may have usage limits +3. **Combine wisely** - Use server tools for external data and custom tools for application logic +4. **Handle failures gracefully** - Server tools may fail due to network issues or API limits + +## Complete Example + +```php + [ + 'url_context' => true, + 'google_search' => true + ], + 'temperature' => 0.7 +]); + +// Optional: Add custom tools +$toolbox = Toolbox::create(new Clock()); +$processor = new ChainProcessor($toolbox); + +// Create chain +$chain = new Chain($platform, $llm); + +// Use with URL context +$messages = new MessageBag( + Message::ofUser( + 'Compare the current EUR/USD exchange rate from https://www.xe.com with historical rates. + What has been the trend over the past month?' + ) +); + +$response = $chain->call($messages); +echo $response->getContent() . PHP_EOL; +``` + +## Limitations + +- Server tools are only available for Google Gemini models +- API key must have appropriate permissions +- Server tools may have usage quotas +- Response times may vary based on the complexity of server tool operations +- Not all Gemini model versions support all server tools + +## Future Considerations + +As the feature evolves, consider: + +- Additional server tools may become available +- Parameters for existing tools may be expanded +- Integration patterns may be refined based on usage \ No newline at end of file From 89e19bc4608dba7eb3c4f977e355885a71f35bfe Mon Sep 17 00:00:00 2001 From: Oskar Stark Date: Tue, 1 Jul 2025 09:12:05 +0200 Subject: [PATCH 02/11] fix: Add PHP opening tags to all code examples and remove future considerations section --- docs/google-server-tools.md | 24 +++++++++++++++--------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/docs/google-server-tools.md b/docs/google-server-tools.md index 6d2995d2..c9895876 100644 --- a/docs/google-server-tools.md +++ b/docs/google-server-tools.md @@ -23,6 +23,8 @@ composer require php-llm/llm-chain To use server tools, specify them in the model options when creating a Gemini instance: ```php + [ 'url_context' => true @@ -66,6 +70,8 @@ $response = $chain->call($messages); The Google Search tool enables the model to search the web and incorporate search results into its responses: ```php + [ 'google_search' => true @@ -84,6 +90,8 @@ $response = $chain->call($messages); The Code Execution tool provides a sandboxed environment for running code: ```php + [ 'code_execution' => true @@ -102,6 +110,8 @@ $response = $chain->call($messages); You can enable multiple server tools simultaneously: ```php + [ 'url_context' => true, @@ -118,6 +128,8 @@ $llm = new Gemini('gemini-2.5-pro-preview-03-25', [ For server tools that accept parameters, you can pass an array instead of `true`: ```php + [ 'url_context' => [ @@ -132,6 +144,8 @@ $llm = new Gemini('gemini-2.5-pro-preview-03-25', [ Server tools can be used alongside custom tools from the toolbox: ```php +getContent() . PHP_EOL; - API key must have appropriate permissions - Server tools may have usage quotas - Response times may vary based on the complexity of server tool operations -- Not all Gemini model versions support all server tools - -## Future Considerations - -As the feature evolves, consider: - -- Additional server tools may become available -- Parameters for existing tools may be expanded -- Integration patterns may be refined based on usage \ No newline at end of file +- Not all Gemini model versions support all server tools \ No newline at end of file From 07d9a3a11ee1dbd142e53eb2171d452828479e7d Mon Sep 17 00:00:00 2001 From: Oskar Stark Date: Tue, 1 Jul 2025 09:16:04 +0200 Subject: [PATCH 03/11] docs: Update server tools section to list supporting platforms --- README.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 747205de..6390fb82 100644 --- a/README.md +++ b/README.md @@ -172,9 +172,11 @@ $response = $chain->call($messages, [ To integrate LLMs with your application, LLM Chain supports [tool calling](https://platform.openai.com/docs/guides/function-calling) out of the box. Tools are services that can be called by the LLM to provide additional features or process data. -#### Server Tools (Google Gemini) +#### Server Tools -Google Gemini provides built-in server-side tools for enhanced capabilities without custom implementations. See the [Server Tools Documentation](docs/google-server-tools.md) for detailed usage instructions. +Some platforms provide built-in server-side tools for enhanced capabilities without custom implementations: + +1. **Google Gemini** - URL Context, Google Search, Code Execution. See the [Server Tools Documentation](docs/google-server-tools.md) for detailed usage instructions. Tool calling can be enabled by registering the processors in the chain: From 45a1be3c957dbd76160df1c302248c166caeabdd Mon Sep 17 00:00:00 2001 From: Oskar Stark Date: Tue, 1 Jul 2025 09:16:39 +0200 Subject: [PATCH 04/11] refactor: Rename server tools documentation to be platform-specific --- README.md | 2 +- docs/{google-server-tools.md => google-gemini-server-tools.md} | 0 2 files changed, 1 insertion(+), 1 deletion(-) rename docs/{google-server-tools.md => google-gemini-server-tools.md} (100%) diff --git a/README.md b/README.md index 6390fb82..2ad81002 100644 --- a/README.md +++ b/README.md @@ -176,7 +176,7 @@ Tools are services that can be called by the LLM to provide additional features Some platforms provide built-in server-side tools for enhanced capabilities without custom implementations: -1. **Google Gemini** - URL Context, Google Search, Code Execution. See the [Server Tools Documentation](docs/google-server-tools.md) for detailed usage instructions. +1. **Google Gemini** - URL Context, Google Search, Code Execution. See the [Server Tools Documentation](docs/google-gemini-server-tools.md) for detailed usage instructions. Tool calling can be enabled by registering the processors in the chain: diff --git a/docs/google-server-tools.md b/docs/google-gemini-server-tools.md similarity index 100% rename from docs/google-server-tools.md rename to docs/google-gemini-server-tools.md From cc049cb05f4c83bea6263ee9fdff87674127ad75 Mon Sep 17 00:00:00 2001 From: Oskar Stark Date: Tue, 1 Jul 2025 09:17:00 +0200 Subject: [PATCH 05/11] docs: Move documentation link to Google Gemini list entry --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 2ad81002..84fc3911 100644 --- a/README.md +++ b/README.md @@ -176,7 +176,7 @@ Tools are services that can be called by the LLM to provide additional features Some platforms provide built-in server-side tools for enhanced capabilities without custom implementations: -1. **Google Gemini** - URL Context, Google Search, Code Execution. See the [Server Tools Documentation](docs/google-gemini-server-tools.md) for detailed usage instructions. +1. **[Google Gemini](docs/google-gemini-server-tools.md)** - URL Context, Google Search, Code Execution Tool calling can be enabled by registering the processors in the chain: From 5a38152fa73d3647a3bf9c374251d6dff4f4358b Mon Sep 17 00:00:00 2001 From: Oskar Stark Date: Tue, 1 Jul 2025 09:18:44 +0200 Subject: [PATCH 06/11] docs: Remove unnecessary installation section --- docs/google-gemini-server-tools.md | 8 -------- 1 file changed, 8 deletions(-) diff --git a/docs/google-gemini-server-tools.md b/docs/google-gemini-server-tools.md index c9895876..90ae13c5 100644 --- a/docs/google-gemini-server-tools.md +++ b/docs/google-gemini-server-tools.md @@ -10,14 +10,6 @@ Google Gemini provides several server-side tools that can be enabled when callin - **Google Search** - Performs web searches using Google - **Code Execution** - Executes code in a sandboxed environment -## Installation - -Server tools are available through the Google platform bridge: - -```php -composer require php-llm/llm-chain -``` - ## Basic Usage To use server tools, specify them in the model options when creating a Gemini instance: From 578836e753bbaa71db652ca8b8326625bad2da7e Mon Sep 17 00:00:00 2001 From: Oskar Stark Date: Tue, 1 Jul 2025 09:19:08 +0200 Subject: [PATCH 07/11] docs: Remove basic usage section --- docs/google-gemini-server-tools.md | 21 --------------------- 1 file changed, 21 deletions(-) diff --git a/docs/google-gemini-server-tools.md b/docs/google-gemini-server-tools.md index 90ae13c5..3595efb6 100644 --- a/docs/google-gemini-server-tools.md +++ b/docs/google-gemini-server-tools.md @@ -10,27 +10,6 @@ Google Gemini provides several server-side tools that can be enabled when callin - **Google Search** - Performs web searches using Google - **Code Execution** - Executes code in a sandboxed environment -## Basic Usage - -To use server tools, specify them in the model options when creating a Gemini instance: - -```php - [ - 'url_context' => true - ], - 'temperature' => 1.0 -]); -``` - ## Available Server Tools ### URL Context From efecbb519b02f05ae4f99b5c3ee2a5f709ef7cfc Mon Sep 17 00:00:00 2001 From: Oskar Stark Date: Tue, 1 Jul 2025 09:21:03 +0200 Subject: [PATCH 08/11] docs: Remove PHP opening tags from all code examples --- docs/google-gemini-server-tools.md | 14 -------------- 1 file changed, 14 deletions(-) diff --git a/docs/google-gemini-server-tools.md b/docs/google-gemini-server-tools.md index 3595efb6..9fa8476c 100644 --- a/docs/google-gemini-server-tools.md +++ b/docs/google-gemini-server-tools.md @@ -21,8 +21,6 @@ The URL Context tool allows Gemini to fetch and analyze content from web pages. - Understanding context from external sources ```php - [ 'url_context' => true @@ -41,8 +39,6 @@ $response = $chain->call($messages); The Google Search tool enables the model to search the web and incorporate search results into its responses: ```php - [ 'google_search' => true @@ -61,8 +57,6 @@ $response = $chain->call($messages); The Code Execution tool provides a sandboxed environment for running code: ```php - [ 'code_execution' => true @@ -81,8 +75,6 @@ $response = $chain->call($messages); You can enable multiple server tools simultaneously: ```php - [ 'url_context' => true, @@ -99,8 +91,6 @@ $llm = new Gemini('gemini-2.5-pro-preview-03-25', [ For server tools that accept parameters, you can pass an array instead of `true`: ```php - [ 'url_context' => [ @@ -115,8 +105,6 @@ $llm = new Gemini('gemini-2.5-pro-preview-03-25', [ Server tools can be used alongside custom tools from the toolbox: ```php - Date: Tue, 1 Jul 2025 09:27:10 +0200 Subject: [PATCH 09/11] docs: Remove advanced configuration sections --- docs/google-gemini-server-tools.md | 37 ------------------------------ 1 file changed, 37 deletions(-) diff --git a/docs/google-gemini-server-tools.md b/docs/google-gemini-server-tools.md index 9fa8476c..7119744f 100644 --- a/docs/google-gemini-server-tools.md +++ b/docs/google-gemini-server-tools.md @@ -84,43 +84,6 @@ $llm = new Gemini('gemini-2.5-pro-preview-03-25', [ ]); ``` -## Advanced Configuration - -### Server Tools with Parameters - -For server tools that accept parameters, you can pass an array instead of `true`: - -```php -$llm = new Gemini('gemini-2.5-pro-preview-03-25', [ - 'server_tools' => [ - 'url_context' => [ - // Future parameters can be added here - ] - ] -]); -``` - -### Combining with Custom Tools - -Server tools can be used alongside custom tools from the toolbox: - -```php -use PhpLlm\LlmChain\Chain\Toolbox\Tool\Clock; -use PhpLlm\LlmChain\Chain\Toolbox\Toolbox; - -$toolbox = Toolbox::create(new Clock()); -$processor = new ChainProcessor($toolbox); -$chain = new Chain($platform, $llm); - -$llm = new Gemini('gemini-2.5-pro-preview-03-25', [ - 'server_tools' => [ - 'url_context' => true - ] -]); - -// Both server tools and custom tools will be available -``` - ## Implementation Details The server tools implementation works by: From 0f6584d1e65d5a9a06b4332e7d9533b0f6e28553 Mon Sep 17 00:00:00 2001 From: Oskar Stark Date: Tue, 1 Jul 2025 09:28:28 +0200 Subject: [PATCH 10/11] docs: Remove complete example, best practices and implementation details sections --- docs/google-gemini-server-tools.md | 59 +----------------------------- 1 file changed, 2 insertions(+), 57 deletions(-) diff --git a/docs/google-gemini-server-tools.md b/docs/google-gemini-server-tools.md index 7119744f..6912cbfc 100644 --- a/docs/google-gemini-server-tools.md +++ b/docs/google-gemini-server-tools.md @@ -84,64 +84,9 @@ $llm = new Gemini('gemini-2.5-pro-preview-03-25', [ ]); ``` -## Implementation Details +## Example -The server tools implementation works by: - -1. Converting server tool configurations into the format expected by Google's API -2. For boolean `true` values, an empty `ArrayObject` is sent as required by the API -3. Server tools are added to the `tools` array in the API request -4. The `server_tools` option is separate from regular `tools` to prevent toolbox tools from being overwritten - -## Best Practices - -1. **Enable only needed tools** - Each enabled tool increases latency and token usage -2. **Consider rate limits** - Server tools may have usage limits -3. **Combine wisely** - Use server tools for external data and custom tools for application logic -4. **Handle failures gracefully** - Server tools may fail due to network issues or API limits - -## Complete Example - -```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; - -// Initialize platform -$platform = PlatformFactory::create($_ENV['GOOGLE_API_KEY']); - -// Configure model with server tools -$llm = new Gemini('gemini-2.5-pro-preview-03-25', [ - 'server_tools' => [ - 'url_context' => true, - 'google_search' => true - ], - 'temperature' => 0.7 -]); - -// Optional: Add custom tools -$toolbox = Toolbox::create(new Clock()); -$processor = new ChainProcessor($toolbox); - -// Create chain -$chain = new Chain($platform, $llm); - -// Use with URL context -$messages = new MessageBag( - Message::ofUser( - 'Compare the current EUR/USD exchange rate from https://www.xe.com with historical rates. - What has been the trend over the past month?' - ) -); - -$response = $chain->call($messages); -echo $response->getContent() . PHP_EOL; -``` +See [examples/google/server-tools.php](../examples/google/server-tools.php) for a complete working example. ## Limitations From 537e95ddf7b12e4cc72cce0611853027cee9a632 Mon Sep 17 00:00:00 2001 From: Oskar Stark Date: Tue, 1 Jul 2025 09:29:08 +0200 Subject: [PATCH 11/11] docs: Remove redundant limitation about Google Gemini exclusivity --- docs/google-gemini-server-tools.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/google-gemini-server-tools.md b/docs/google-gemini-server-tools.md index 6912cbfc..eef02267 100644 --- a/docs/google-gemini-server-tools.md +++ b/docs/google-gemini-server-tools.md @@ -90,7 +90,6 @@ See [examples/google/server-tools.php](../examples/google/server-tools.php) for ## Limitations -- Server tools are only available for Google Gemini models - API key must have appropriate permissions - Server tools may have usage quotas - Response times may vary based on the complexity of server tool operations