feat(anthropic): Add support for automatic caching

docs/providers/anthropic.md

@@ -14,7 +14,35 @@
 
 Anthropic's prompt caching feature allows you to drastically reduce latency and your API bill when repeatedly re-using blocks of content within five minutes or one hour of each other, depending on the Anthropic compatible TTL option you provide.
 
-We support Anthropic prompt caching on:
+There are two ways to enable prompt caching:
+- Automatic caching
+- Explicit cache breakpoints
+
+To enable automatic caching, simply add a single cache_control field at the top level of your request:
+
+```php
+use Prism\Prism\Enums\Provider;
+use Prism\Prism\Facades\Prism;
+use Prism\Prism\Tool;
+use Prism\Prism\ValueObjects\Messages\UserMessage;
+use Prism\Prism\ValueObjects\Messages\SystemMessage;
+
+Prism::text()
+    ->using(Provider::Anthropic, 'claude-3-5-sonnet-20241022')
+    ->withSystemPrompt(
+        (new SystemMessage('I am a long re-usable system message.'))
+    )
+    ->withMessages([
+        (new UserMessage('I am a long re-usable user message.'))
+    ])
+    ->withTools([
+        Tool::as('cache me')
+    ])
+    ->withProviderOptions(['cache_control' => ['type' => 'ephemeral']])
+    ->asText();
+```
+
+We support Anthropic explicit cache breakpoints on:
 
 - System Messages (text only)
 - User Messages (Text, Image and PDF (pdf only))

src/Providers/Anthropic/Handlers/Structured.php

@@ -102,6 +102,7 @@ public static function buildHttpRequestPayload(PrismRequest $request): array
             'temperature' => $request->temperature(),
             'top_p' => $request->topP(),
             'mcp_servers' => $request->providerOptions('mcp_servers'),
+            'cache_control' => $request->providerOptions('cache_control'),
         ]);
 
         return $structuredStrategy->mutatePayload($basePayload);

src/Providers/Anthropic/Handlers/Text.php

@@ -88,6 +88,7 @@ public static function buildHttpRequestPayload(PrismRequest $request): array
             'tools' => static::buildTools($request) ?: null,
             'tool_choice' => ToolChoiceMap::map($request->toolChoice()),
             'mcp_servers' => $request->providerOptions('mcp_servers'),
+            'cache_control' => $request->providerOptions('cache_control'),
         ]);
     }
 

tests/Providers/Anthropic/AnthropicTextTest.php

@@ -639,3 +639,15 @@
 
     })->throws(PrismRequestTooLargeException::class);
 });
+
+it('allows automatic caching enabled via providerOptions', function (): void {
+    Prism::fake();
+
+    $request = Prism::text()
+        ->using(Provider::Anthropic, 'claude-3-5-sonnet-latest')
+        ->withProviderOptions(['cache_control' => ['type' => 'ephemeral']]);
+
+    $payload = Text::buildHttpRequestPayload($request->toRequest());
+
+    expect($payload['cache_control'])->toBe(['type' => 'ephemeral']);
+});

tests/Providers/Anthropic/StructuredTest.php

@@ -386,3 +386,25 @@
         )->toThrow(PrismException::class, 'Citations are not supported with native output_format');
     });
 });
+
+it('allows automatic caching enabled via providerOptions', function (): void {
+    Prism::fake();
+
+    $schema = new ObjectSchema(
+        'output',
+        'the output object',
+        [
+            new StringSchema('weather', 'The weather forecast'),
+        ],
+        ['weather']
+    );
+
+    $request = Prism::structured()
+        ->withSchema($schema)
+        ->using(Provider::Anthropic, 'claude-3-5-sonnet-latest')
+        ->withProviderOptions(['cache_control' => ['type' => 'ephemeral']]);
+
+    $payload = Structured::buildHttpRequestPayload($request->toRequest());
+
+    expect($payload['cache_control'])->toBe(['type' => 'ephemeral']);
+});