ruby_llm-agents 3.14.0 → 3.14.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d974a549e2d99bbcd16c8345547d16c16aff7ae602da503974d9db1f32be8ce6
-  data.tar.gz: 9947da35f39521706e7c7bef349dcf9f6a63f5f732409ff1774ce0607bd6429e
+  metadata.gz: 4734a9b91b3dc228b78661cdbe4e336b9053beb6440601482709f99745c6e918
+  data.tar.gz: de29b3452e781a363c3330137323364edca7e80afd55680f200161c464d3f027
 SHA512:
-  metadata.gz: 8aa785d541d2e00d237a71d5a652643e7e2da83750f8264d754c00fce6c2e33fc7d6d47caa75c1ac94659fd05703a9c488a229064cd1d01157b6845e4ef3970e
-  data.tar.gz: 89bf72286b0a6e70418268457beea87df58bb16514a170730518adeadae84eac6d6ff6553e9726e481b00c2358ad9d909c9f20170bcf41224eb7efdaf3d7f1ac
+  metadata.gz: 180db730cb98f426ce7e774cad42ad146b33cbb09b74340b772a2306cc0249152adbee79da9de71d372eb5f925ebf894db8305ef9df2ca58c60104280fec03e3
+  data.tar.gz: 2b2183165d6e2271ffda0b673ed173abde8cd77d8adc6e85b168de24b9744bc6c51ebe2194fcc45ad7d3e3fb35b82603f7830260927b2fabe763c552b93691cd

data/lib/ruby_llm/agents/base_agent.rb

@@ -934,11 +934,18 @@ module RubyLLM
           context.output_tokens = metadata.output_tokens if metadata.respond_to?(:output_tokens)
           context.model_used = (metadata.respond_to?(:model_id) && metadata.model_id) || model
 
-          # Capture Anthropic prompt caching metrics
+          # Prompt-cache metrics. Every provider that reports them lands here —
+          # not just Anthropic: OpenAI caches automatically with no opt-in, so
+          # these are populated on ordinary calls with a long stable prefix.
+          # Kept on the context's own accessors (and mirrored into metadata for
+          # backward compatibility) because #build_result and #calculate_costs
+          # both read them back.
           if metadata.respond_to?(:cached_tokens) && metadata.cached_tokens&.positive?
+            context.cached_tokens = metadata.cached_tokens
             context[:cached_tokens] = metadata.cached_tokens
           end
           if metadata.respond_to?(:cache_creation_tokens) && metadata.cache_creation_tokens&.positive?
+            context.cache_creation_tokens = metadata.cache_creation_tokens
             context[:cache_creation_tokens] = metadata.cache_creation_tokens
           end
         else
@@ -1001,7 +1008,7 @@ module RubyLLM
         input_price = model_info.pricing&.text_tokens&.input || 0
         output_price = model_info.pricing&.text_tokens&.output || 0
 
-        context.input_cost = (input_tokens / 1_000_000.0) * input_price
+        context.input_cost = input_cost_for(input_tokens, input_price, model_info, context)
 
         # Price cache/reasoning extras first so we know whether reasoning was
         # actually billed at the reasoning rate. Only then exclude those tokens
@@ -1014,6 +1021,75 @@ module RubyLLM
         context.total_cost = (context.input_cost + context.output_cost + extra).round(6)
       end
 
+      # Input charge, with cache reads billed at the cached rate rather than the
+      # full one.
+      #
+      # Providers disagree on whether the reported input_tokens ALREADY contains
+      # the cache reads, and the difference decides who has a bug:
+      #
+      #   OpenAI    prompt_tokens       INCLUDES prompt_tokens_details.cached_tokens
+      #   Gemini    promptTokenCount    INCLUDES cachedContentTokenCount
+      #   Anthropic input_tokens        EXCLUDES cache_read_input_tokens
+      #
+      # On Anthropic the cache read is genuinely additive, so charging the full
+      # input_tokens at full rate and letting #extra_token_costs add cache_read
+      # on top is already correct — that path is left untouched.
+      #
+      # On OpenAI and Gemini the cached tokens are sitting inside input_tokens,
+      # so charging them at the full rate overstates spend by 2-3x on exactly
+      # the workload caching exists for (a long stable system prompt replayed
+      # every turn) — and would double-charge outright once the provider also
+      # reports a cache_read cost component. Those get split here instead.
+      #
+      # Falls back to the full input rate whenever the split can't be made
+      # safely (no cache reported, or no cached price in the registry), so an
+      # unknown model is never under-billed.
+      #
+      # @return [Float] The input cost in USD
+      def input_cost_for(input_tokens, input_price, model_info, context)
+        full_rate_charge = (input_tokens / 1_000_000.0) * input_price
+
+        cached_tokens = context.cached_tokens.to_i
+        return full_rate_charge unless cached_tokens.positive?
+        return full_rate_charge unless cached_tokens_included_in_input?(model_info)
+
+        cached_price = cached_input_price(model_info)
+        return full_rate_charge unless cached_price
+
+        # Tells extra_token_costs not to charge these same reads a second time.
+        context[:cache_read_priced] = true
+
+        uncached_tokens = [input_tokens - cached_tokens, 0].max
+        (uncached_tokens / 1_000_000.0) * input_price +
+          (cached_tokens / 1_000_000.0) * cached_price
+      end
+
+      # Per-million price for a cache read, or nil when the model registry
+      # doesn't publish one. Pricing shapes vary by source (and are stubbed with
+      # partial doubles in tests), so an absent field degrades to "unknown" —
+      # callers then charge the full input rate rather than guessing a discount.
+      #
+      # @return [Float, nil]
+      def cached_input_price(model_info)
+        tier = model_info.pricing&.text_tokens
+        return nil unless tier.respond_to?(:cached_input)
+
+        tier.cached_input
+      rescue
+        nil
+      end
+
+      # Whether this provider's reported input_tokens already contains the cache
+      # reads. See #input_cost_for for the per-provider breakdown. Anthropic is
+      # the exception; defaulting the unknown case to "included" matches every
+      # other provider RubyLLM supports.
+      #
+      # @return [Boolean]
+      def cached_tokens_included_in_input?(model_info)
+        provider = model_info.respond_to?(:provider) ? model_info.provider.to_s : ""
+        !provider.include?("anthropic")
+      end
+
       # Number of reasoning (thinking) tokens that were actually charged at the
       # reasoning rate, recorded in the cost breakdown by +extra_token_costs+.
       #
@@ -1050,8 +1126,12 @@ module RubyLLM
         cost = response_cost(response, model_info)
         return 0.0 unless cost
 
+        # Skip cache_read when #input_cost_for already billed the cache at the
+        # cached rate — otherwise the same tokens are charged twice (once inside
+        # input_tokens at full rate, once here). Cache WRITES are always extra:
+        # no provider folds them into input_tokens.
         components = {
-          cache_read: cost.cache_read,
+          cache_read: (cost.cache_read unless context[:cache_read_priced]),
           cache_write: cost.cache_write,
           thinking: cost.thinking
         }.compact.reject { |_, value| value.zero? }
@@ -1156,6 +1236,8 @@ module RubyLLM
           agent_class_name: self.class.name,
           input_tokens: context.input_tokens,
           output_tokens: context.output_tokens,
+          cached_tokens: context.cached_tokens,
+          cache_creation_tokens: context.cache_creation_tokens,
           input_cost: context.input_cost,
           output_cost: context.output_cost,
           total_cost: context.total_cost,

data/lib/ruby_llm/agents/core/version.rb

@@ -4,6 +4,6 @@ module RubyLLM
   module Agents
     # Current version of the RubyLLM::Agents gem
     # @return [String] Semantic version string
-    VERSION = "3.14.0"
+    VERSION = "3.14.1"
   end
 end

data/lib/ruby_llm/agents/pipeline/context.rb

@@ -43,6 +43,11 @@ module RubyLLM
         # Cost tracking
         attr_accessor :input_tokens, :output_tokens, :input_cost, :output_cost, :total_cost
 
+        # Prompt-cache usage. First-class accessors, not metadata keys: these
+        # feed both the persisted execution record and the input-cost split, so
+        # a generic bag entry would be silently droppable (it was).
+        attr_accessor :cached_tokens, :cache_creation_tokens
+
         # Response metadata
         attr_accessor :model_used, :finish_reason, :time_to_first_token_ms
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_llm-agents
 version: !ruby/object:Gem::Version
-  version: 3.14.0
+  version: 3.14.1
 platform: ruby
 authors:
 - adham90