omniai-anthropic 3.6.0 → 3.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 70d172e3b288451b57742351a6db872672b84a7a9f0b139e2466299b17ef3a2e
-  data.tar.gz: b83fb955581badb868e95b99caee30d1b3e2aa9203a01bcd137b7b0517d14cf3
+  metadata.gz: 20cd61e7e110c59273cb86062c34630d07d66b14a5da7be33cfb11f3a3f29514
+  data.tar.gz: 44dfedfa87d0cb07ca36fc155efd5ddb8507eef146202a41e98be1c1bbd0010c
 SHA512:
-  metadata.gz: 26ef3bb07ec0aae3544ec8008a745d754a0a2044645836b26507b1be5c148c341877763281826a8745e5a93df6534032454d38b95d4b062a926875fb32b6e263
-  data.tar.gz: 10efb98acf0f9ee712568d4c1a4cf7087c32bbaae0ec82b28dec5d046937803595483df3a6039dd042c28653a346a8cdfb1866329ef149eb6feec831cfde8c63
+  metadata.gz: 815f8ed94a51cdbe222754218ab865a17227971e6d58d0c39aa6a87425919127af507871bd25263f355d22c5e46c5849c2bc34d6f3a955b6cebc6a06ce944c49
+  data.tar.gz: c4303f54ed395240b18c054f1776ac680323c89ba609c9c0c8dba57f5ad0c641d71eaa34a4713d9d6cc3356fdda59d4f020a186bc7b0d6aca5ec66f9bf2fe34d

data/README.md

@@ -170,3 +170,21 @@ client.chat("What are the prime factors of 1234567?", model: "claude-sonnet-4-20
 The thinking content will stream first, followed by the response.
 
 [Anthropic API Reference `thinking`](https://docs.anthropic.com/en/docs/build-with-claude/thinking)
+
+### Prompt Caching
+
+Prompt caching is opt-in. When enabled, the system prompt (or the last tool, when there is no system prompt) and the last block of the last message are marked with `cache_control`, so each round of a tool-call loop reads the history the previous round wrote.
+
+```ruby
+client.chat(prompt, tools:, cache: true) # 5-minute TTL
+client.chat(prompt, tools:, cache: { ttl: "1h" }) # 1-hour TTL
+```
+
+`usage.input_tokens` reports the whole prompt, including cached tokens. The cache breakdown is on each response's raw usage:
+
+```ruby
+response.response_chain.sum { |r| r.data.dig("usage", "cache_read_input_tokens").to_i }
+response.response_chain.sum { |r| r.data.dig("usage", "cache_creation_input_tokens").to_i }
+```
+
+[Anthropic API Reference `prompt caching`](https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching)

data/lib/omniai/anthropic/chat/usage_serializer.rb

@@ -24,6 +24,11 @@ module OmniAI
           thinking_tokens = data.dig("output_tokens_details", "thinking_tokens")
           usage.thinking_tokens = thinking_tokens unless thinking_tokens.nil?
 
+          # Anthropic's `input_tokens` excludes cache reads and writes; adding them back keeps it the whole prompt, as
+          # for every other provider. A base-serialized payload has neither key and is already whole.
+          cache_tokens = data.values_at("cache_creation_input_tokens", "cache_read_input_tokens").compact
+          usage.input_tokens = (usage.input_tokens || 0) + cache_tokens.sum if cache_tokens.any?
+
           usage
         end
       end

data/lib/omniai/anthropic/chat.rb

@@ -165,19 +165,40 @@ module OmniAI
         end
       end
 
+      # When caching, the last block of the last message is marked so each tool-loop round reads the history the
+      # previous round wrote.
+      #
       # @return [Array<Hash>]
       def messages
-        messages = @prompt.messages.reject(&:system?)
-        messages.map { |message| message.serialize(context:) }
+        messages = @prompt.messages.reject(&:system?).map { |message| message.serialize(context:) }
+        return messages unless cache_control && messages.any?
+
+        *history, last = messages
+        history + [last.merge(content: with_cache_control(last[:content]))]
       end
 
-      # @return [String, nil]
+      # When caching, a single marked text block. Tools render before system, so this breakpoint covers both.
+      #
+      # @return [String, Array<Hash>, nil]
       def system
         parts = @prompt.messages.filter(&:system?).filter(&:text?).map(&:text)
         parts << formatting if formatting?
         return if parts.empty?
 
-        parts.join("\n\n")
+        text = parts.join("\n\n")
+        cache_control ? [{ type: "text", text:, cache_control: }] : text
+      end
+
+      # Translates the opt-in `cache` option to Anthropic's `cache_control`.
+      # Example: `cache: true` becomes `{ type: "ephemeral" }` (5-minute TTL)
+      # Example: `cache: { ttl: "1h" }` becomes `{ type: "ephemeral", ttl: "1h" }`
+      #
+      # @return [Hash, nil]
+      def cache_control
+        case @options[:cache]
+        when true then { type: "ephemeral" }
+        when Hash then { type: "ephemeral" }.merge(@options[:cache])
+        end
       end
 
       # @return [String]
@@ -217,9 +238,25 @@ module OmniAI
         end
       end
 
+      # When caching without a system prompt, the last tool carries the breakpoint instead.
+      #
       # @return [Array<Hash>, nil]
       def tools_payload
-        @tools.map { |tool| tool.serialize(context:) } if @tools&.any?
+        return unless @tools&.any?
+
+        tools = @tools.map { |tool| tool.serialize(context:) }
+        cache_control && system.nil? ? with_cache_control(tools) : tools
+      end
+
+      # Relies on `MessageSerializer` normalizing every content part into a block Hash; a bare String would raise.
+      #
+      # @param blocks [Array<Hash>]
+      # @return [Array<Hash>]
+      def with_cache_control(blocks)
+        return blocks if blocks.empty?
+
+        *head, last = blocks
+        head + [last.merge(cache_control:)]
       end
 
       # @return [Boolean]

data/lib/omniai/anthropic/version.rb

@@ -2,6 +2,6 @@
 
 module OmniAI
   module Anthropic
-    VERSION = "3.6.0"
+    VERSION = "3.7.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: omniai-anthropic
 version: !ruby/object:Gem::Version
-  version: 3.6.0
+  version: 3.7.0
 platform: ruby
 authors:
 - Kevin Sylvestre