feat!: provider tools (#405)

BREAKING CHANGE: Gemini search grounding must now be enabled using withProviderTools

Author: ChrisB-TL

docs/providers/anthropic.md

@@ -181,6 +181,40 @@ Prism supports [Anthropic's citations feature](https://docs.anthropic.com/en/doc
 
 Please note however that due to Anthropic not supporting "native" structured output, and Prism's workaround for this, the output can be unreliable. You should therefore ensure you implement proper error handling for the scenario where Anthropic does not return a valid decodable schema.
 
+## Code execution
+
+To enable code execution, you will first need to enable the beta feature.
+
+Either in prism/config.php:
+
+```php
+        'anthropic' => [
+            ...
+            'anthropic_beta' => 'code-execution-2025-05-22',
+        ],
+
+```
+
+Or in your env file (assuming config/prism.php reflects the default prism setup):
+
+```
+ANTHROPIC_BETA="code-execution-2025-05-22"
+```
+
+You may then use code execution as follows:
+
+```php
+use Prism\Prism\Prism;
+use Prism\Prism\ValueObjects\ProviderTool;
+
+Prism::text()
+    ->using('anthropic', 'claude-3-5-haiku-latest')
+    ->withPrompt('Solve the equation 3x + 10 = 14.')
+    ->withProviderTools([new ProviderTool(type: 'code_execution_20250522', name: 'code_execution')])
+    ->asText();
+
+```
+
 ### Enabling citations
 
 Anthropic require citations to be enabled on all documents in a request. To enable them, using the `withProviderOptions()` method when building your request:

docs/providers/gemini.md

@@ -10,7 +10,7 @@
 
 ## Search grounding
 
-You may enable Google search grounding on text requests using providerOptions:
+You may enable Google search grounding on text requests using withProviderTools:
 
 ```php
 use Prism\Prism\Prism;
@@ -20,7 +20,7 @@ $response = Prism::text()
     ->using(Provider::Gemini, 'gemini-2.0-flash')
     ->withPrompt('What is the stock price of Google right now?')
     // Enable search grounding
-    ->withProviderOptions(['searchGrounding' => true])
+    ->withProviderTools(['google_search'])
     ->generate();
 ```
 

docs/providers/openai.md

@@ -69,3 +69,18 @@ $response = Prism::structured()
 ### Caching
 
 Automatic caching does not currently work with JsonMode. Please ensure you use StructuredMode if you wish to utilise automatic caching.
+
+### Code interpreter
+
+You can use the OpenAI code interpreter as follows:
+
+```php
+use Prism\Prism\Prism;
+use Prism\Prism\ValueObjects\ProviderTool;
+
+Prism::text()
+    ->using('openai', 'gpt-4.1')
+    ->withPrompt('Solve the equation 3x + 10 = 14.')
+    ->withProviderTools([new ProviderTool(type: 'code_interpreter', options: ['container' => ['type' => 'auto']])])
+    ->asText();
+```

src/Concerns/HasProviderTools.php

@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Prism\Prism\Concerns;
+
+use Prism\Prism\ValueObjects\ProviderTool;
+
+trait HasProviderTools
+{
+    /** @var array<int,ProviderTool> */
+    protected array $providerTools = [];
+
+    /**
+     * @param  array<int,ProviderTool>  $providerTools
+     */
+    public function withProviderTools(array $providerTools): self
+    {
+        $this->providerTools = $providerTools;
+
+        return $this;
+    }
+}

src/Providers/Anthropic/Handlers/Text.php

@@ -21,6 +21,7 @@
 use Prism\Prism\ValueObjects\Messages\AssistantMessage;
 use Prism\Prism\ValueObjects\Messages\ToolResultMessage;
 use Prism\Prism\ValueObjects\Meta;
+use Prism\Prism\ValueObjects\ProviderTool;
 use Prism\Prism\ValueObjects\ToolCall;
 use Prism\Prism\ValueObjects\ToolResult;
 use Prism\Prism\ValueObjects\Usage;
@@ -97,7 +98,7 @@ public static function buildHttpRequestPayload(PrismRequest $request): array
             'max_tokens' => $request->maxTokens(),
             'temperature' => $request->temperature(),
             'top_p' => $request->topP(),
-            'tools' => ToolMap::map($request->tools()),
+            'tools' => static::buildTools($request),
             'tool_choice' => ToolChoiceMap::map($request->toolChoice()),
         ]);
     }
@@ -178,6 +179,28 @@ protected function prepareTempResponse(): void
         );
     }
 
+    /**
+     * @return array<int|string,mixed>
+     */
+    protected static function buildTools(TextRequest $request): array
+    {
+        $tools = ToolMap::map($request->tools());
+
+        if ($request->providerTools() === []) {
+            return $tools;
+        }
+
+        $providerTools = array_map(
+            fn (ProviderTool $tool): array => [
+                'type' => $tool->type,
+                'name' => $tool->name,
+            ],
+            $request->providerTools()
+        );
+
+        return array_merge($providerTools, $tools);
+    }
+
     /**
      * @param  array<string, mixed>  $data
      * @return ToolCall[]

src/Providers/Gemini/Handlers/Text.php

@@ -25,6 +25,7 @@
 use Prism\Prism\ValueObjects\Messages\AssistantMessage;
 use Prism\Prism\ValueObjects\Messages\ToolResultMessage;
 use Prism\Prism\ValueObjects\Meta;
+use Prism\Prism\ValueObjects\ProviderTool;
 use Prism\Prism\ValueObjects\ToolResult;
 use Prism\Prism\ValueObjects\Usage;
 use Throwable;
@@ -89,17 +90,24 @@ protected function sendRequest(Request $request): ClientResponse
                 'thinkingConfig' => $thinkingConfig !== [] ? $thinkingConfig : null,
             ]);
 
-            if ($request->tools() !== [] && ($providerOptions['searchGrounding'] ?? false)) {
-                throw new Exception('Use of search grounding with custom tools is not currently supported by Prism.');
+            if ($request->tools() !== [] && $request->providerTools() != []) {
+                throw new Exception('Use of provider tools with custom tools is not currently supported by Gemini.');
             }
 
-            $tools = $providerOptions['searchGrounding'] ?? false
-                ? [
-                    [
-                        'google_search' => (object) [],
-                    ],
-                ]
-                : ($request->tools() !== [] ? ['function_declarations' => ToolMap::map($request->tools())] : []);
+            $tools = [];
+
+            if ($request->providerTools() !== []) {
+                $tools = [
+                    Arr::mapWithKeys(
+                        $request->providerTools(),
+                        fn (ProviderTool $providerTool): array => [$providerTool->type => (object) []]
+                    ),
+                ];
+            }
+
+            if ($request->tools() !== []) {
+                $tools['function_declarations'] = ToolMap::map($request->tools());
+            }
 
             return $this->client->post(
                 "{$request->model()}:generateContent",

src/Providers/OpenAI/Handlers/Text.php

@@ -24,6 +24,7 @@
 use Prism\Prism\ValueObjects\Messages\AssistantMessage;
 use Prism\Prism\ValueObjects\Messages\ToolResultMessage;
 use Prism\Prism\ValueObjects\Meta;
+use Prism\Prism\ValueObjects\ProviderTool;
 use Prism\Prism\ValueObjects\ToolResult;
 use Prism\Prism\ValueObjects\Usage;
 use Throwable;
@@ -118,7 +119,7 @@ protected function sendRequest(Request $request): ClientResponse
                     'temperature' => $request->temperature(),
                     'top_p' => $request->topP(),
                     'metadata' => $request->providerOptions('metadata'),
-                    'tools' => ToolMap::map($request->tools()),
+                    'tools' => $this->buildTools($request),
                     'tool_choice' => ToolChoiceMap::map($request->toolChoice()),
                     'previous_response_id' => $request->providerOptions('previous_response_id'),
                     'truncation' => $request->providerOptions('truncation'),
@@ -156,4 +157,26 @@ protected function addStep(array $data, Request $request, ClientResponse $client
             systemPrompts: $request->systemPrompts(),
         ));
     }
+
+    /**
+     * @return array<int|string,mixed>
+     */
+    protected function buildTools(Request $request): array
+    {
+        $tools = ToolMap::map($request->tools());
+
+        if ($request->providerTools() === []) {
+            return $tools;
+        }
+
+        $providerTools = array_map(
+            fn (ProviderTool $tool): array => [
+                'type' => $tool->type,
+                ...$tool->options,
+            ],
+            $request->providerTools()
+        );
+
+        return array_merge($providerTools, $tools);
+    }
 }

src/Text/PendingRequest.php

@@ -13,6 +13,7 @@
 use Prism\Prism\Concerns\HasMessages;
 use Prism\Prism\Concerns\HasPrompts;
 use Prism\Prism\Concerns\HasProviderOptions;
+use Prism\Prism\Concerns\HasProviderTools;
 use Prism\Prism\Concerns\HasTools;
 use Prism\Prism\Exceptions\PrismException;
 use Prism\Prism\ValueObjects\Messages\UserMessage;
@@ -27,6 +28,7 @@ class PendingRequest
     use HasMessages;
     use HasPrompts;
     use HasProviderOptions;
+    use HasProviderTools;
     use HasTools;
 
     /**
@@ -76,6 +78,7 @@ public function toRequest(): Request
             clientRetry: $this->clientRetry,
             toolChoice: $this->toolChoice,
             providerOptions: $this->providerOptions,
+            providerTools: $this->providerTools,
         );
     }
 }

src/Text/Request.php

@@ -12,6 +12,7 @@
 use Prism\Prism\Enums\ToolChoice;
 use Prism\Prism\Tool;
 use Prism\Prism\ValueObjects\Messages\SystemMessage;
+use Prism\Prism\ValueObjects\ProviderTool;
 
 class Request implements PrismRequest
 {
@@ -24,6 +25,7 @@ class Request implements PrismRequest
      * @param  array<string, mixed>  $clientOptions
      * @param  array{0: array<int, int>|int, 1?: Closure|int, 2?: ?callable, 3?: bool}  $clientRetry
      * @param  array<string, mixed>  $providerOptions
+     * @param  array<int, ProviderTool>  $providerTools
      */
     public function __construct(
         protected string $model,
@@ -39,6 +41,7 @@ public function __construct(
         protected array $clientRetry,
         protected string|ToolChoice|null $toolChoice,
         array $providerOptions = [],
+        protected array $providerTools = [],
     ) {
         $this->providerOptions = $providerOptions;
     }
@@ -77,6 +80,14 @@ public function topP(): int|float|null
         return $this->topP;
     }
 
+    /**
+     * @return array<int,ProviderTool>
+     */
+    public function providerTools(): array
+    {
+        return $this->providerTools;
+    }
+
     public function temperature(): int|float|null
     {
         return $this->temperature;

src/ValueObjects/ProviderTool.php

@@ -0,0 +1,15 @@
+<?php
+
+namespace Prism\Prism\ValueObjects;
+
+class ProviderTool
+{
+    /**
+     * @param  array<string,mixed>  $options
+     */
+    public function __construct(
+        public readonly string $type,
+        public readonly ?string $name = null,
+        public readonly array $options = [],
+    ) {}
+}

tests/Fixtures/anthropic/generate-text-with-provider-tool-1.json

@@ -0,0 +1 @@
+{"id":"msg_01AJ87pcoq6djGGrcYvYGvUy","type":"message","role":"assistant","model":"claude-3-5-haiku-20241022","content":[{"type":"text","text":"I'll solve this equation step by step and then verify the solution using Python.\n\nSolving 3x + 10 = 14 algebraically:\n1. Subtract 10 from both sides of the equation\n   3x + 10 - 10 = 14 - 10\n   3x = 4\n\n2. Divide both sides by 3\n   3x ÷ 3 = 4 ÷ 3\n   x = 4/3\n\nLet me verify this solution using Python:"},{"type":"server_tool_use","id":"srvtoolu_01Co9FxvC6Di5aAfcu8RhUHh","name":"code_execution","input":{"code":"# Solve the equation 3x + 10 = 14\nx = (14 - 10) / 3\nprint(f\"x = {x}\")\n\n# Verify the solution\nleft_side = 3 * x + 10\nright_side = 14\n\nprint(f\"\\nVerification:\")\nprint(f\"Left side (3x + 10): {left_side}\")\nprint(f\"Right side (14):      {right_side}\")\nprint(f\"Equation holds: {left_side == right_side}\")"}},{"type":"code_execution_tool_result","tool_use_id":"srvtoolu_01Co9FxvC6Di5aAfcu8RhUHh","content":{"type":"code_execution_result","stdout":"x = 1.3333333333333333\n\nVerification:\nLeft side (3x + 10): 14.0\nRight side (14):      14\nEquation holds: True\n","stderr":"","return_code":0,"content":[]}},{"type":"text","text":"The solution is x = 4/3 (or approximately 1.333). \n\nLet's break down the verification:\n- x = 4/3\n- Left side: 3 * (4/3) + 10 = 4 + 10 = 14\n- Right side: 14\n\nThe equation is satisfied, confirming that x = 4/3 is the correct solution."}],"container":{"id":"container_011CQ4hgKqeoPBYecAubG4B9","expires_at":"2025-06-12T18:13:51.893719+00:00"},"stop_reason":"end_turn","stop_sequence":null,"usage":{"input_tokens":1779,"cache_creation_input_tokens":0,"cache_read_input_tokens":0,"output_tokens":398,"service_tier":"standard","server_tool_use":{"web_search_requests":0}}}

tests/Fixtures/anthropic/generate-text-with-provider-tool-and-user-tool-1.json

@@ -0,0 +1 @@
+{"id":"msg_01RuwnupYURXYMrhuXTxRqxf","type":"message","role":"assistant","model":"claude-3-5-haiku-20241022","content":[{"type":"text","text":"I'll help you solve this by first checking the current temperature in Detroit and then using that value to solve the equation."},{"type":"tool_use","id":"toolu_013vSsaqxgM8GTUMGDoeCsbS","name":"weather","input":{"city":"Detroit"}}],"stop_reason":"tool_use","stop_sequence":null,"usage":{"input_tokens":854,"cache_creation_input_tokens":0,"cache_read_input_tokens":0,"output_tokens":76,"service_tier":"standard"}}

tests/Fixtures/anthropic/generate-text-with-provider-tool-and-user-tool-2.json

@@ -0,0 +1 @@
+{"id":"msg_014o7Vi8g9F3nW2PFEWMWG9a","type":"message","role":"assistant","model":"claude-3-5-haiku-20241022","content":[{"type":"text","text":"Great! The current temperature in Detroit is 75 degrees. Let's solve the equation 3x + 10 = Y by substituting 75 for x:\n\n3(75) + 10 = Y\n225 + 10 = Y\n235 = Y\n\nSo, when x = 75 (the current temperature in Detroit), Y equals 235 in the equation 3x + 10 = Y."}],"stop_reason":"end_turn","stop_sequence":null,"usage":{"input_tokens":950,"cache_creation_input_tokens":0,"cache_read_input_tokens":0,"output_tokens":99,"service_tier":"standard"}}

tests/Fixtures/openai/generate-text-with-code-interpreter-1.json

@@ -0,0 +1,65 @@
+{
+  "id": "resp_684b06dab43c819c84f623fec58aa55d029bfe449563c425",
+  "object": "response",
+  "created_at": 1749747418,
+  "status": "completed",
+  "background": false,
+  "error": null,
+  "incomplete_details": null,
+  "instructions": null,
+  "max_output_tokens": 2048,
+  "model": "gpt-4.1-2025-04-14",
+  "output": [
+    {
+      "id": "msg_684b06dcce74819c819ffe9b836d7ff8029bfe449563c425",
+      "type": "message",
+      "status": "completed",
+      "content": [
+        {
+          "type": "output_text",
+          "annotations": [],
+          "text": "Let's solve the equation step by step:\n\nGiven equation:\n\\[ 3x + 10 = 14 \\]\n\n**Step 1:** Subtract 10 from both sides to isolate the term with \\( x \\):\n\\[\n3x + 10 - 10 = 14 - 10\n\\]\n\\[\n3x = 4\n\\]\n\n**Step 2:** Divide both sides by 3 to solve for \\( x \\):\n\\[\nx = \\frac{4}{3}\n\\]\n\n**Final Answer:**\n\\[\n\\boxed{x = \\frac{4}{3}}\n\\]"
+        }
+      ],
+      "role": "assistant"
+    }
+  ],
+  "parallel_tool_calls": true,
+  "previous_response_id": null,
+  "reasoning": {
+    "effort": null,
+    "summary": null
+  },
+  "service_tier": "default",
+  "store": true,
+  "temperature": 1.0,
+  "text": {
+    "format": {
+      "type": "text"
+    }
+  },
+  "tool_choice": "auto",
+  "tools": [
+    {
+      "type": "code_interpreter",
+      "container": {
+        "type": "auto"
+      }
+    }
+  ],
+  "top_p": 1.0,
+  "truncation": "disabled",
+  "usage": {
+    "input_tokens": 117,
+    "input_tokens_details": {
+      "cached_tokens": 0
+    },
+    "output_tokens": 126,
+    "output_tokens_details": {
+      "reasoning_tokens": 0
+    },
+    "total_tokens": 243
+  },
+  "user": null,
+  "metadata": {}
+}