Anthropic prompt caching

config/prism.php

@@ -15,6 +15,8 @@
         'anthropic' => [
             'api_key' => env('ANTHROPIC_API_KEY', ''),
             'version' => env('ANTHROPIC_API_VERSION', '2023-06-01'),
+            // Seperate each feature with a comma with no spaces.
+            'beta_features' => ENV('ANTHROPIC_BETA_FEATURES', null),
         ],
         'ollama' => [
             'url' => env('OLLAMA_URL', 'http://localhost:11434/v1'),

src/Concerns/HasProviderMeta.php

@@ -0,0 +1,29 @@
+<?php
+
+namespace EchoLabs\Prism\Concerns;
+
+use EchoLabs\Prism\Enums\Provider;
+
+trait HasProviderMeta
+{
+    /** @var array<string, array<string, mixed>> */
+    protected $providerMeta = [];
+
+    /**
+     * @param  array<string, mixed>  $meta
+     */
+    public function withProviderMeta(Provider $provider, array $meta): self
+    {
+        $this->providerMeta[$provider->value] = $meta;
+
+        return $this;
+    }
+
+    /**
+     * @return array<string, mixed>> $meta
+     */
+    public function providerMeta(Provider $provider): array
+    {
+        return data_get($this->providerMeta, $provider->value, []);
+    }
+}

src/PrismManager.php

@@ -117,6 +117,7 @@ protected function createAnthropicProvider(array $config): Anthropic
         return new Anthropic(
             $config['api_key'],
             $config['version'],
+            $config['beta_features']
         );
     }
 

src/Providers/Anthropic/Anthropic.php

@@ -20,6 +20,7 @@ class Anthropic implements Provider
     public function __construct(
         public readonly string $apiKey,
         public readonly string $apiVersion,
+        public readonly ?string $betaFeatures = null
     ) {}
 
     #[\Override]
@@ -56,10 +57,11 @@ public function embeddings(EmbeddingRequest $request): EmbeddingResponse
      */
     protected function client(array $options = [], array $retry = []): PendingRequest
     {
-        return Http::withHeaders([
+        return Http::withHeaders(array_filter([
             'x-api-key' => $this->apiKey,
             'anthropic-version' => $this->apiVersion,
-        ])
+            'anthropic-beta' => $this->betaFeatures,
+        ]))
             ->withOptions($options)
             ->retry(...$retry)
             ->baseUrl('https://api.anthropic.com/v1');

src/Providers/Anthropic/Enums/AnthropicCacheType.php

@@ -0,0 +1,8 @@
+<?php
+
+namespace EchoLabs\Prism\Providers\Anthropic\Enums;
+
+enum AnthropicCacheType
+{
+    case ephemeral;
+}

src/Providers/Anthropic/Handlers/Structured.php

@@ -47,8 +47,10 @@ public function handle(Request $request): ProviderResponse
             text: $this->extractText($data),
             toolCalls: $this->extractToolCalls($data),
             usage: new Usage(
-                data_get($data, 'usage.input_tokens'),
-                data_get($data, 'usage.output_tokens'),
+                promptTokens: data_get($data, 'usage.input_tokens'),
+                completionTokens: data_get($data, 'usage.output_tokens'),
+                cacheWriteInputTokens: data_get($data, 'usage.cache_creation_input_tokens', null),
+                cacheReadInputTokens: data_get($data, 'usage.cache_read_input_tokens', null)
             ),
             finishReason: FinishReasonMap::map(data_get($data, 'stop_reason', '')),
             response: [

src/Providers/Anthropic/Handlers/Text.php

@@ -45,8 +45,10 @@ public function handle(Request $request): ProviderResponse
             text: $this->extractText($data),
             toolCalls: $this->extractToolCalls($data),
             usage: new Usage(
-                data_get($data, 'usage.input_tokens'),
-                data_get($data, 'usage.output_tokens'),
+                promptTokens: data_get($data, 'usage.input_tokens'),
+                completionTokens: data_get($data, 'usage.output_tokens'),
+                cacheWriteInputTokens: data_get($data, 'usage.cache_creation_input_tokens'),
+                cacheReadInputTokens: data_get($data, 'usage.cache_read_input_tokens')
             ),
             finishReason: FinishReasonMap::map(data_get($data, 'stop_reason', '')),
             response: [

src/Providers/Anthropic/Maps/MessageMap.php

@@ -5,6 +5,7 @@
 namespace EchoLabs\Prism\Providers\Anthropic\Maps;
 
 use EchoLabs\Prism\Contracts\Message;
+use EchoLabs\Prism\Enums\Provider;
 use EchoLabs\Prism\ValueObjects\Messages\AssistantMessage;
 use EchoLabs\Prism\ValueObjects\Messages\Support\Image;
 use EchoLabs\Prism\ValueObjects\Messages\SystemMessage;
@@ -14,6 +15,7 @@
 use EchoLabs\Prism\ValueObjects\ToolResult;
 use Exception;
 use InvalidArgumentException;
+use UnitEnum;
 
 class MessageMap
 {
@@ -45,10 +47,13 @@ protected static function mapMessage(Message $message): array
      */
     protected static function mapSystemMessage(SystemMessage $systemMessage): array
     {
-        return [
+        $cacheType = data_get($systemMessage->providerMeta(Provider::Anthropic), 'cacheType', null);
+
+        return array_filter([
             'role' => 'user',
             'content' => $systemMessage->content,
-        ];
+            'cache_control' => $cacheType ? ['type' => $cacheType instanceof UnitEnum ? $cacheType->name : $cacheType] : null,
+        ]);
     }
 
     /**
@@ -86,10 +91,16 @@ protected static function mapUserMessage(UserMessage $message): array
             ];
         }, $message->images());
 
+        $cacheType = data_get($message->providerMeta(Provider::Anthropic), 'cacheType', null);
+
         return [
             'role' => 'user',
             'content' => [
-                ['type' => 'text', 'text' => $message->text()],
+                array_filter([
+                    'type' => 'text',
+                    'text' => $message->text(),
+                    'cache_control' => $cacheType ? ['type' => $cacheType instanceof UnitEnum ? $cacheType->name : $cacheType] : null,
+                ]),
                 ...$imageParts,
             ],
 
@@ -101,32 +112,30 @@ protected static function mapUserMessage(UserMessage $message): array
      */
     protected static function mapAssistantMessage(AssistantMessage $message): array
     {
-        if ($message->toolCalls) {
-            $content = [];
+        $content = [];
 
-            if ($message->content !== '' && $message->content !== '0') {
-                $content[] = [
-                    'type' => 'text',
-                    'text' => $message->content,
-                ];
-            }
+        if ($message->content !== '' && $message->content !== '0') {
+            $cacheType = data_get($message->providerMeta(Provider::Anthropic), 'cacheType', null);
 
-            $toolCalls = array_map(fn (ToolCall $toolCall): array => [
+            $content[] = array_filter([
+                'type' => 'text',
+                'text' => $message->content,
+                'cache_control' => $cacheType ? ['type' => $cacheType instanceof UnitEnum ? $cacheType->name : $cacheType] : null,
+            ]);
+        }
+
+        $toolCalls = $message->toolCalls
+            ? array_map(fn (ToolCall $toolCall): array => [
                 'type' => 'tool_use',
                 'id' => $toolCall->id,
                 'name' => $toolCall->name,
                 'input' => $toolCall->arguments(),
-            ], $message->toolCalls);
-
-            return [
-                'role' => 'assistant',
-                'content' => array_merge($content, $toolCalls),
-            ];
-        }
+            ], $message->toolCalls)
+            : [];
 
         return [
             'role' => 'assistant',
-            'content' => $message->content,
+            'content' => array_merge($content, $toolCalls),
         ];
     }
 }

src/Providers/Anthropic/Maps/ToolMap.php

@@ -4,7 +4,9 @@
 
 namespace EchoLabs\Prism\Providers\Anthropic\Maps;
 
+use EchoLabs\Prism\Enums\Provider;
 use EchoLabs\Prism\Tool as PrismTool;
+use UnitEnum;
 
 class ToolMap
 {
@@ -14,14 +16,19 @@ class ToolMap
      */
     public static function map(array $tools): array
     {
-        return array_map(fn (PrismTool $tool): array => [
-            'name' => $tool->name(),
-            'description' => $tool->description(),
-            'input_schema' => [
-                'type' => 'object',
-                'properties' => $tool->parameters(),
-                'required' => $tool->requiredParameters(),
-            ],
-        ], $tools);
+        return array_map(function (PrismTool $tool): array {
+            $cacheType = data_get($tool->providerMeta(Provider::Anthropic), 'cacheType', null);
+
+            return array_filter([
+                'name' => $tool->name(),
+                'description' => $tool->description(),
+                'input_schema' => [
+                    'type' => 'object',
+                    'properties' => $tool->parameters(),
+                    'required' => $tool->requiredParameters(),
+                ],
+                'cache_control' => $cacheType ? ['type' => $cacheType instanceof UnitEnum ? $cacheType->name : $cacheType] : null,
+            ]);
+        }, $tools);
     }
 }

src/Structured/ResponseBuilder.php

@@ -73,12 +73,18 @@ protected function decodeObject(string $responseText): ?array
     protected function calculateTotalUsage(): Usage
     {
         return new Usage(
-            $this
+            promptTokens: $this
                 ->steps
                 ->sum(fn (Step $result): int => $result->usage->promptTokens),
-            $this
+            completionTokens: $this
                 ->steps
-                ->sum(fn (Step $result): int => $result->usage->completionTokens)
+                ->sum(fn (Step $result): int => $result->usage->completionTokens),
+            cacheWriteInputTokens: $this->steps->contains(fn (Step $result): bool => $result->usage->cacheWriteInputTokens !== null)
+                ? $this->steps->sum(fn (Step $result): int => $result->usage->cacheWriteInputTokens ?? 0)
+                : null,
+            cacheReadInputTokens: $this->steps->contains(fn (Step $result): bool => $result->usage->cacheReadInputTokens !== null)
+                ? $this->steps->sum(fn (Step $result): int => $result->usage->cacheReadInputTokens ?? 0)
+                : null,
         );
     }
 }

src/Text/ResponseBuilder.php

@@ -56,12 +56,18 @@ public function toResponse(): Response
     protected function calculateTotalUsage(): Usage
     {
         return new Usage(
-            $this
+            promptTokens: $this
                 ->steps
                 ->sum(fn (Step $result): int => $result->usage->promptTokens),
-            $this
+            completionTokens: $this
                 ->steps
-                ->sum(fn (Step $result): int => $result->usage->completionTokens)
+                ->sum(fn (Step $result): int => $result->usage->completionTokens),
+            cacheWriteInputTokens: $this->steps->contains(fn (Step $result): bool => $result->usage->cacheWriteInputTokens !== null)
+                ? $this->steps->sum(fn (Step $result): int => $result->usage->cacheWriteInputTokens ?? 0)
+                : null,
+            cacheReadInputTokens: $this->steps->contains(fn (Step $result): bool => $result->usage->cacheReadInputTokens !== null)
+                ? $this->steps->sum(fn (Step $result): int => $result->usage->cacheReadInputTokens ?? 0)
+                : null,
         );
     }
 }

src/Tool.php

@@ -6,8 +6,8 @@
 
 use ArgumentCountError;
 use Closure;
+use EchoLabs\Prism\Concerns\HasProviderMeta;
 use EchoLabs\Prism\Contracts\Schema;
-use EchoLabs\Prism\Enums\Provider;
 use EchoLabs\Prism\Exceptions\PrismException;
 use EchoLabs\Prism\Schema\ArraySchema;
 use EchoLabs\Prism\Schema\BooleanSchema;
@@ -21,6 +21,8 @@
 
 class Tool
 {
+    use HasProviderMeta;
+
     protected string $name = '';
 
     protected string $description;
@@ -34,9 +36,6 @@ class Tool
     /** @var Closure():string|callable():string */
     protected $fn;
 
-    /** @var array<string, array<string, mixed>> */
-    protected $providerMeta = [];
-
     public function as(string $name): self
     {
         $this->name = $name;
@@ -139,24 +138,6 @@ public function withEnumParameter(
         return $this;
     }
 
-    /**
-     * @param  array<string, mixed>  $meta
-     */
-    public function withProviderMeta(Provider $provider, array $meta): self
-    {
-        $this->providerMeta[$provider->value] = $meta;
-
-        return $this;
-    }
-
-    /**
-     * @return array<string, mixed>> $meta
-     */
-    public function providerMeta(Provider $provider): array
-    {
-        return data_get($this->providerMeta, $provider->value, []);
-    }
-
     /** @return array<int, string> */
     public function requiredParameters(): array
     {

src/ValueObjects/Messages/AssistantMessage.php

@@ -4,11 +4,14 @@
 
 namespace EchoLabs\Prism\ValueObjects\Messages;
 
+use EchoLabs\Prism\Concerns\HasProviderMeta;
 use EchoLabs\Prism\Contracts\Message;
 use EchoLabs\Prism\ValueObjects\ToolCall;
 
 class AssistantMessage implements Message
 {
+    use HasProviderMeta;
+
     /**
      * @param  ToolCall[]  $toolCalls
      */

src/ValueObjects/Messages/SystemMessage.php

@@ -4,11 +4,14 @@
 
 namespace EchoLabs\Prism\ValueObjects\Messages;
 
+use EchoLabs\Prism\Concerns\HasProviderMeta;
 use EchoLabs\Prism\Contracts\Message;
 
 class SystemMessage implements Message
 {
+    use HasProviderMeta;
+
     public function __construct(
-        public readonly string $content,
+        public readonly string $content
     ) {}
 }

src/ValueObjects/Messages/UserMessage.php

@@ -4,12 +4,15 @@
 
 namespace EchoLabs\Prism\ValueObjects\Messages;
 
+use EchoLabs\Prism\Concerns\HasProviderMeta;
 use EchoLabs\Prism\Contracts\Message;
 use EchoLabs\Prism\ValueObjects\Messages\Support\Image;
 use EchoLabs\Prism\ValueObjects\Messages\Support\Text;
 
 class UserMessage implements Message
 {
+    use HasProviderMeta;
+
     /**
      * @param  array<int, Text|Image>  $additionalContent
      */

src/ValueObjects/Usage.php

@@ -8,6 +8,8 @@ class Usage
 {
     public function __construct(
         public readonly int $promptTokens,
-        public readonly int $completionTokens
+        public readonly int $completionTokens,
+        public readonly ?int $cacheWriteInputTokens = null,
+        public readonly ?int $cacheReadInputTokens = null
     ) {}
 }

tests/Fixtures/anthropic/calculate-cache-usage-1.json

@@ -0,0 +1 @@
+{"id":"msg_01X2Qk7LtNEh4HB9xpYU57XU","type":"message","role":"assistant","model":"claude-3-5-sonnet-20240620","content":[{"type":"text","text":"I am an AI assistant created by Anthropic to be helpful, harmless, and honest. I don't have a physical form or avatar - I'm a language model trained to engage in conversation and help with tasks. How can I assist you today?"}],"stop_reason":"end_turn","stop_sequence":null,"usage":{"input_tokens":11,"output_tokens":55, "cache_creation_input_tokens" : 200, "cache_read_input_tokens": 100}}