omniai-anthropic 3.5.0 → 3.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fcf24d90210fce6c02f7be928c435515a00e75163590946e3222cf36d424c7c9
-  data.tar.gz: 0477ad1fdb3454dec2e84db5bcdf044b97eee780892f013ef85348460ac0fb70
+  metadata.gz: 20cd61e7e110c59273cb86062c34630d07d66b14a5da7be33cfb11f3a3f29514
+  data.tar.gz: 44dfedfa87d0cb07ca36fc155efd5ddb8507eef146202a41e98be1c1bbd0010c
 SHA512:
-  metadata.gz: f91432693771d415d5b7375e00781c817e960711a74c66961808b9a2ebf68cc09a3c7ae455ed631666ef8b15643e9afa79962cef23e1334410eb8a352a233aa7
-  data.tar.gz: b02acec6c970f8e651f465e5fdc07512db9dca9600b787bb42eb2beab866236ec12ea3af626c268ef1734aec67e294892d8b9c2b5048f9c90d516ee7c28633ad
+  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/stream.rb

@@ -81,10 +81,15 @@ module OmniAI
 
           input_tokens = data.dig("usage", "input_tokens")
           output_tokens = data.dig("usage", "output_tokens")
+          # The thinking breakdown arrives only on the final `message_delta`. Carrying it through keeps streamed
+          # responses reporting the same `thinking_tokens` as non-streamed ones; without it the key is dropped and
+          # every streamed response silently reports no reasoning.
+          output_tokens_details = data.dig("usage", "output_tokens_details")
 
           @data["usage"] ||= {}
           @data["usage"]["input_tokens"] = input_tokens if input_tokens
           @data["usage"]["output_tokens"] = output_tokens if output_tokens
+          @data["usage"]["output_tokens_details"] = output_tokens_details if output_tokens_details
         end
 
         # Handler for Type::MESSAGE_STOP

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

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module OmniAI
+  module Anthropic
+    class Chat
+      # Overrides usage deserialize to read Anthropic's reasoning breakdown.
+      module UsageSerializer
+        # Anthropic already counts reasoning inside `output_tokens` and reports the breakdown alongside it at
+        # `output_tokens_details.thinking_tokens`, so the breakdown is read into `thinking_tokens` and the output
+        # count is left exactly as reported. Adding the two together would double count.
+        #
+        # When streaming, the breakdown arrives only on the final `message_delta`.
+        #
+        # @param data [Hash]
+        # @return [OmniAI::Chat::Usage]
+        def self.deserialize(data, *)
+          # Deserialize without a context so the generic flat parse runs rather than recursing into this method.
+          usage = OmniAI::Chat::Usage.deserialize(data)
+
+          # Only overwrite when the vendor container is actually present. A payload produced by `Usage#serialize`
+          # carries base's own `thinking_tokens` key and no `output_tokens_details`, so assigning unconditionally
+          # would clobber a correctly-parsed value with nil and break the round-trip. `unless nil?` rather than
+          # `||=`, so a reported zero from the wire still wins over base's nil.
+          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
+    end
+  end
+end

data/lib/omniai/anthropic/chat.rb

@@ -87,6 +87,8 @@ module OmniAI
 
         context.serializers[:thinking] = ThinkingSerializer.method(:serialize)
         context.deserializers[:thinking] = ThinkingSerializer.method(:deserialize)
+
+        context.deserializers[:usage] = UsageSerializer.method(:deserialize)
       end
 
       # @return [Hash]
@@ -163,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]
@@ -215,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.5.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.5.0
+  version: 3.7.0
 platform: ruby
 authors:
 - Kevin Sylvestre
@@ -29,14 +29,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.7'
+        version: '3.8'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.7'
+        version: '3.8'
 - !ruby/object:Gem::Dependency
   name: openssl
   requirement: !ruby/object:Gem::Requirement
@@ -89,6 +89,7 @@ files:
 - lib/omniai/anthropic/chat/tool_call_serializer.rb
 - lib/omniai/anthropic/chat/tool_serializer.rb
 - lib/omniai/anthropic/chat/url_serializer.rb
+- lib/omniai/anthropic/chat/usage_serializer.rb
 - lib/omniai/anthropic/client.rb
 - lib/omniai/anthropic/computer.rb
 - lib/omniai/anthropic/config.rb