feature #274 [Platform][Anthropic] Allow beta feature flags to be passed into platform invocations (TomLisankie)

This PR was squashed before being merged into the main branch.

Discussion
----------

[Platform][Anthropic] Allow beta feature flags to be passed into platform invocations

| Q             | A
| ------------- | ---
| Bug fix?      | No
| New feature?  | Yes
| Docs?         | Yes
| Issues        | See below
| License       | MIT

<!--
Replace this notice by a description of your feature/bugfix.
This will help reviewers and should be a good start for the documentation.

Additionally (see https://symfony.com/releases):
 - Always add tests and ensure they pass.
 - For new features, provide some code snippets to help understand usage.
 - Features and deprecations must be submitted against branch main.
 - Update/add documentation as required (we can help!)
 - Changelog entry should follow https://symfony.com/doc/current/contributing/code/conventions.html#writing-a-changelog-entry
 - Never break backward compatibility (see https://symfony.com/bc).
-->

Anthropic [supports](https://docs.anthropic.com/en/api/beta-headers) passing flags for beta features via beta headers in requests to its API. This PR allows for passing in the desired beta features via the `$options` parameter in the `invoke` function like so:

```php
$platform->invoke($model, $messageBag, [
            'temperature' => 1.0,
            'max_tokens' => 20000,
            // can now include beta features like this:
            'beta_features' => [
                'code-execution-2025-05-22',
                'mcp-client-2025-04-04'
            ]
        ]);
```

If the beta features option is set and contains at least one element, the beta header is constructed inside the model client and then the option is removed from `$options` before the request is built and sent to Anthropic.

If we want to support beta feature flags for other providers in the future, we should perhaps add another parameter to the `invoke` function for platforms and the `request` function for model clients in order to not pollute `$options` (after all, `$options` is meant to hold _model_ options not _platform_ options).

Commits
-------

41faaa6 [Platform][Anthropic] Allow beta feature flags to be passed into platform invocations

Author: chr-hertel

src/platform/CHANGELOG.md

@@ -59,5 +59,6 @@ CHANGELOG
  * Add response promises for async operations
  * Add InMemoryPlatform and InMemoryRawResult for testing Platform without external Providers calls
  * Add tool calling support for Ollama platform
+ * Allow beta feature flags to be passed into Anthropic model options
 
 

src/platform/src/Bridge/Anthropic/ModelClient.php

@@ -39,15 +39,26 @@ public function supports(Model $model): bool
 
     public function request(Model $model, array|string $payload, array $options = []): RawHttpResult
     {
+        $headers = [
+            'x-api-key' => $this->apiKey,
+            'anthropic-version' => $this->version,
+        ];
+
         if (isset($options['tools'])) {
             $options['tool_choice'] = ['type' => 'auto'];
         }
 
+        if (
+            isset($options['beta_features'])
+            && \is_array($options['beta_features'])
+            && !empty($options['beta_features'])
+        ) {
+            $headers['anthropic-beta'] = implode(',', $options['beta_features']);
+            unset($options['beta_features']);
+        }
+
         return new RawHttpResult($this->httpClient->request('POST', 'https://api.anthropic.com/v1/messages', [
-            'headers' => [
-                'x-api-key' => $this->apiKey,
-                'anthropic-version' => $this->version,
-            ],
+            'headers' => $headers,
             'json' => array_merge($options, $payload),
         ]));
     }

src/platform/tests/Bridge/Anthropic/ModelClientTest.php

@@ -0,0 +1,114 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\AI\Platform\Bridge\Anthropic\Tests;
+
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\TestCase;
+use Symfony\AI\Platform\Bridge\Anthropic\Claude;
+use Symfony\AI\Platform\Bridge\Anthropic\ModelClient;
+use Symfony\Component\HttpClient\MockHttpClient;
+use Symfony\Component\HttpClient\Response\JsonMockResponse;
+
+#[CoversClass(ModelClient::class)]
+class ModelClientTest extends TestCase
+{
+    private MockHttpClient $httpClient;
+    private ModelClient $modelClient;
+    private Claude $model;
+
+    protected function setUp(): void
+    {
+        $this->model = new Claude();
+    }
+
+    public function testAnthropicBetaHeaderIsSetWithSingleBetaFeature()
+    {
+        $this->httpClient = new MockHttpClient(function ($method, $url, $options) {
+            $this->assertEquals('POST', $method);
+            $this->assertEquals('https://api.anthropic.com/v1/messages', $url);
+
+            $headers = $this->parseHeaders($options['headers']);
+
+            $this->assertArrayHasKey('anthropic-beta', $headers);
+            $this->assertEquals('feature-1', $headers['anthropic-beta']);
+
+            return new JsonMockResponse('{"success": true}');
+        });
+
+        $this->modelClient = new ModelClient($this->httpClient, 'test-api-key');
+
+        $options = ['beta_features' => ['feature-1']];
+        $this->modelClient->request($this->model, ['message' => 'test'], $options);
+    }
+
+    public function testAnthropicBetaHeaderIsSetWithMultipleBetaFeatures()
+    {
+        $this->httpClient = new MockHttpClient(function ($method, $url, $options) {
+            $headers = $this->parseHeaders($options['headers']);
+
+            $this->assertArrayHasKey('anthropic-beta', $headers);
+            $this->assertEquals('feature-1,feature-2,feature-3', $headers['anthropic-beta']);
+
+            return new JsonMockResponse('{"success": true}');
+        });
+
+        $this->modelClient = new ModelClient($this->httpClient, 'test-api-key', '2023-06-01');
+
+        $options = ['beta_features' => ['feature-1', 'feature-2', 'feature-3']];
+        $this->modelClient->request($this->model, ['message' => 'test'], $options);
+    }
+
+    public function testAnthropicBetaHeaderIsNotSetWhenBetaFeaturesIsEmpty()
+    {
+        $this->httpClient = new MockHttpClient(function ($method, $url, $options) {
+            $headers = $this->parseHeaders($options['headers']);
+
+            $this->assertArrayNotHasKey('anthropic-beta', $headers);
+
+            return new JsonMockResponse('{"success": true}');
+        });
+
+        $this->modelClient = new ModelClient($this->httpClient, 'test-api-key', '2023-06-01');
+
+        $options = ['beta_features' => []];
+        $this->modelClient->request($this->model, ['message' => 'test'], $options);
+    }
+
+    public function testAnthropicBetaHeaderIsNotSetWhenBetaFeaturesIsNotProvided()
+    {
+        $this->httpClient = new MockHttpClient(function ($method, $url, $options) {
+            $headers = $this->parseHeaders($options['headers']);
+
+            $this->assertArrayNotHasKey('anthropic-beta', $headers);
+
+            return new JsonMockResponse('{"success": true}');
+        });
+
+        $this->modelClient = new ModelClient($this->httpClient, 'test-api-key', '2023-06-01');
+
+        $options = ['some_other_option' => 'value'];
+        $this->modelClient->request($this->model, ['message' => 'test'], $options);
+    }
+
+    private function parseHeaders(array $headers): array
+    {
+        $parsed = [];
+        foreach ($headers as $header) {
+            if (str_contains($header, ':')) {
+                [$key, $value] = explode(':', $header, 2);
+                $parsed[trim($key)] = trim($value);
+            }
+        }
+
+        return $parsed;
+    }
+}