omniai-anthropic 3.6.0 → 3.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 70d172e3b288451b57742351a6db872672b84a7a9f0b139e2466299b17ef3a2e
-  data.tar.gz: b83fb955581badb868e95b99caee30d1b3e2aa9203a01bcd137b7b0517d14cf3
+  metadata.gz: 1689783da704c9474e0c87a65b63a11589918a1c85d2cdbb3c936bb367903cf9
+  data.tar.gz: 581b32358a1c0464e7f3550fe0d0caac455955703b98dde80f1fb755e4f8d10d
 SHA512:
-  metadata.gz: 26ef3bb07ec0aae3544ec8008a745d754a0a2044645836b26507b1be5c148c341877763281826a8745e5a93df6534032454d38b95d4b062a926875fb32b6e263
-  data.tar.gz: 10efb98acf0f9ee712568d4c1a4cf7087c32bbaae0ec82b28dec5d046937803595483df3a6039dd042c28653a346a8cdfb1866329ef149eb6feec831cfde8c63
+  metadata.gz: a89aa7e9b61dd98d9b893ea147da74f35fec059fdc05a9ebecaf80651496f62aabfbc3d43ede744527bf5e811a26caa9dc928e6c25ec433b1faeef734063fffe
+  data.tar.gz: 81ff3b93a6f55df6848cc86f65984f1083e29fc9c8ddd03661c04126df3ace29df62837238cea61d69011bb1037ad1c1a83bc832750acbf680e98f28ce60aad2

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

@@ -47,6 +47,7 @@ module OmniAI
         CLAUDE_OPUS_4_6 = "claude-opus-4-6"
         CLAUDE_OPUS_4_7 = "claude-opus-4-7"
         CLAUDE_OPUS_5 = "claude-opus-5"
+        CLAUDE_OPUS_5_5 = "claude-opus-5-5"
         CLAUDE_SONNET_4_0 = "claude-sonnet-4-0"
         CLAUDE_SONNET_4_5 = "claude-sonnet-4-5"
         CLAUDE_SONNET_4_6 = "claude-sonnet-4-6"
@@ -54,7 +55,7 @@ module OmniAI
         CLAUDE_FABLE_5 = "claude-fable-5"
 
         CLAUDE_HAIKU = CLAUDE_HAIKU_4_5
-        CLAUDE_OPUS = CLAUDE_OPUS_5
+        CLAUDE_OPUS = CLAUDE_OPUS_5_5
         CLAUDE_SONNET = CLAUDE_SONNET_5
       end
 
@@ -165,19 +166,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 +239,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.8.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.8.0
 platform: ruby
 authors:
 - Kevin Sylvestre