crmne · tpaulshippy · Jun 9, 2025 · Jun 9, 2025 · Jun 9, 2025 · Jun 9, 2025
diff --git a/docs/_core_features/chat.md b/docs/_core_features/chat.md
@@ -520,6 +520,42 @@ puts "Total Conversation Tokens: #{total_conversation_tokens}"
 
 Refer to the [Working with Models Guide]({% link _advanced/models.md %}) for details on accessing model-specific pricing.
 
+## Prompt Caching
+
+### Enabling
+For Anthropic models, RubyLLM automatically opts-in to prompt caching which is documented more fully in the [Anthropic API docs](https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching).
+
+Disable prompt caching using configuration:
+
+```ruby
+RubyLLM.configure do |config|
+  config.cache_prompts = false # Disable prompt caching with Anthropic models
+end
+```
+
+Or specify exactly which pieces you want to enable caching for:
+```ruby
+# Enable caching only for specific types of content
+chat = RubyLLM.chat(model: 'claude-3-5-haiku-20241022', cache: :system) # Cache system instructions
+chat = RubyLLM.chat(model: 'claude-3-5-haiku-20241022', cache: :user) # Cache user messages
+chat = RubyLLM.chat(model: 'claude-3-5-haiku-20241022', cache: :tools) # Cache tool definitions
+
+# Or a combination
+chat = RubyLLM.chat(model: 'claude-3-5-haiku-20241022', cache: [:system, :tools]) # Cache system instructions and tool definitions
+
+# Or do the same on the ask method
+chat.ask("What do you think?", cache: :system)
+chat.ask("What do you think?", cache: :user)
+chat.ask("What do you think?", cache: :tools)
+chat.ask("What do you think?", cache: [:system, :tools])
+
+```
+
+### Checking cached token counts
+For Anthropic, OpenAI, and Gemini, you can see the number of tokens read from cache by looking at the `cached_tokens` property on the output messages.
+
+For Anthropic, you can see the tokens written to cache by looking at the `cache_creation_tokens` property.
+
 ## Chat Event Handlers
 
 You can register blocks to be called when certain events occur during the chat lifecycle. This is particularly useful for UI updates, logging, analytics, or building real-time chat interfaces.

diff --git a/gemfiles/rails_7.1.gemfile.lock b/gemfiles/rails_7.1.gemfile.lock
@@ -148,6 +148,7 @@ GEM
       concurrent-ruby (~> 1.1)
       webrick (~> 1.7)
       websocket-driver (~> 0.7)
+    ffi (1.17.2-arm64-darwin)
     ffi (1.17.2-x86_64-linux-gnu)
     fiber-annotation (0.2.0)
     fiber-local (1.1.0)
@@ -180,12 +181,12 @@ GEM
       ruby-vips (>= 2.0.17, < 3)
     iniparse (1.5.0)
     io-console (0.8.1)
-    io-event (1.14.0)
+    io-event (1.11.2)
     irb (1.15.2)
       pp (>= 0.6.0)
       rdoc (>= 4.0.0)
       reline (>= 0.4.2)
-    json (2.14.1)
+    json (2.15.0)
     json-schema (6.0.0)
       addressable (~> 2.8)
       bigdecimal (~> 3.1)
@@ -224,6 +225,8 @@ GEM
     net-smtp (0.5.1)
       net-protocol
     nio4r (2.7.4)
+    nokogiri (1.18.10-arm64-darwin)
+      racc (~> 1.4)
     nokogiri (1.18.10-x86_64-linux-gnu)
       racc (~> 1.4)
     os (1.1.4)
@@ -318,7 +321,7 @@ GEM
       rubocop-ast (>= 1.46.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.47.0)
+    rubocop-ast (1.47.1)
       parser (>= 3.3.7.2)
       prism (~> 1.4)
     rubocop-performance (1.26.0)
@@ -355,6 +358,7 @@ GEM
       simplecov (~> 0.19)
     simplecov-html (0.13.2)
     simplecov_json_formatter (0.1.4)
+    sqlite3 (2.7.4-arm64-darwin)
     sqlite3 (2.7.4-x86_64-linux-gnu)
     stringio (3.1.7)
     thor (1.4.0)
@@ -380,6 +384,7 @@ GEM
     zeitwerk (2.7.3)
 
 PLATFORMS
+  arm64-darwin-22
   x86_64-linux
 
 DEPENDENCIES

diff --git a/gemfiles/rails_7.2.gemfile.lock b/gemfiles/rails_7.2.gemfile.lock
@@ -142,6 +142,7 @@ GEM
       concurrent-ruby (~> 1.1)
       webrick (~> 1.7)
       websocket-driver (~> 0.7)
+    ffi (1.17.2-arm64-darwin)
     ffi (1.17.2-x86_64-linux-gnu)
     fiber-annotation (0.2.0)
     fiber-local (1.1.0)
@@ -174,12 +175,12 @@ GEM
       ruby-vips (>= 2.0.17, < 3)
     iniparse (1.5.0)
     io-console (0.8.1)
-    io-event (1.14.0)
+    io-event (1.11.2)
     irb (1.15.2)
       pp (>= 0.6.0)
       rdoc (>= 4.0.0)
       reline (>= 0.4.2)
-    json (2.14.1)
+    json (2.15.0)
     json-schema (6.0.0)
       addressable (~> 2.8)
       bigdecimal (~> 3.1)
@@ -217,6 +218,8 @@ GEM
     net-smtp (0.5.1)
       net-protocol
     nio4r (2.7.4)
+    nokogiri (1.18.10-arm64-darwin)
+      racc (~> 1.4)
     nokogiri (1.18.10-x86_64-linux-gnu)
       racc (~> 1.4)
     os (1.1.4)
@@ -311,7 +314,7 @@ GEM
       rubocop-ast (>= 1.46.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.47.0)
+    rubocop-ast (1.47.1)
       parser (>= 3.3.7.2)
       prism (~> 1.4)
     rubocop-performance (1.26.0)
@@ -348,6 +351,7 @@ GEM
       simplecov (~> 0.19)
     simplecov-html (0.13.2)
     simplecov_json_formatter (0.1.4)
+    sqlite3 (2.7.4-arm64-darwin)
     sqlite3 (2.7.4-x86_64-linux-gnu)
     stringio (3.1.7)
     thor (1.4.0)
@@ -374,6 +378,7 @@ GEM
     zeitwerk (2.7.3)
 
 PLATFORMS
+  arm64-darwin-22
   x86_64-linux
 
 DEPENDENCIES

diff --git a/gemfiles/rails_8.0.gemfile.lock b/gemfiles/rails_8.0.gemfile.lock
@@ -142,6 +142,7 @@ GEM
       concurrent-ruby (~> 1.1)
       webrick (~> 1.7)
       websocket-driver (~> 0.7)
+    ffi (1.17.2-arm64-darwin)
     ffi (1.17.2-x86_64-linux-gnu)
     fiber-annotation (0.2.0)
     fiber-local (1.1.0)
@@ -174,12 +175,12 @@ GEM
       ruby-vips (>= 2.0.17, < 3)
     iniparse (1.5.0)
     io-console (0.8.1)
-    io-event (1.14.0)
+    io-event (1.11.2)
     irb (1.15.2)
       pp (>= 0.6.0)
       rdoc (>= 4.0.0)
       reline (>= 0.4.2)
-    json (2.14.1)
+    json (2.15.0)
     json-schema (6.0.0)
       addressable (~> 2.8)
       bigdecimal (~> 3.1)
@@ -217,6 +218,8 @@ GEM
     net-smtp (0.5.1)
       net-protocol
     nio4r (2.7.4)
+    nokogiri (1.18.10-arm64-darwin)
+      racc (~> 1.4)
     nokogiri (1.18.10-x86_64-linux-gnu)
       racc (~> 1.4)
     os (1.1.4)
@@ -311,7 +314,7 @@ GEM
       rubocop-ast (>= 1.46.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.47.0)
+    rubocop-ast (1.47.1)
       parser (>= 3.3.7.2)
       prism (~> 1.4)
     rubocop-performance (1.26.0)
@@ -348,6 +351,7 @@ GEM
       simplecov (~> 0.19)
     simplecov-html (0.13.2)
     simplecov_json_formatter (0.1.4)
+    sqlite3 (2.7.4-arm64-darwin)
     sqlite3 (2.7.4-x86_64-linux-gnu)
     stringio (3.1.7)
     thor (1.4.0)
@@ -374,6 +378,7 @@ GEM
     zeitwerk (2.7.3)
 
 PLATFORMS
+  arm64-darwin-22
   x86_64-linux
 
 DEPENDENCIES

diff --git a/lib/ruby_llm/active_record/chat_methods.rb b/lib/ruby_llm/active_record/chat_methods.rb
@@ -179,7 +179,8 @@ def create_user_message(content, with: nil)
         message_record
       end
 
-      def ask(message, with: nil, &)
+      def ask(message, with: nil, cache: nil, &)
+        to_llm.instance_variable_set(:@cache_prompts, cache)
         create_user_message(message, with:)
         complete(&)
       end

diff --git a/lib/ruby_llm/chat.rb b/lib/ruby_llm/chat.rb
@@ -7,7 +7,7 @@ class Chat
 
     attr_reader :model, :messages, :tools, :params, :headers, :schema
 
-    def initialize(model: nil, provider: nil, assume_model_exists: false, context: nil)
+    def initialize(model: nil, provider: nil, assume_model_exists: false, context: nil, cache: nil)
       if assume_model_exists && !provider
         raise ArgumentError, 'Provider must be specified if assume_model_exists is true'
       end
@@ -19,6 +19,7 @@ def initialize(model: nil, provider: nil, assume_model_exists: false, context: n
       @temperature = nil
       @messages = []
       @tools = {}
+      @cache_prompts = cache.nil? ? @config.cache_prompts : cache
       @params = {}
       @headers = {}
       @schema = nil
@@ -30,7 +31,8 @@ def initialize(model: nil, provider: nil, assume_model_exists: false, context: n
       }
     end
 
-    def ask(message = nil, with: nil, &)
+    def ask(message = nil, with: nil, cache: nil, &)
+      @cache_prompts = cache if cache
       add_message role: :user, content: Content.new(message, with)
       complete(&)
     end
@@ -127,6 +129,7 @@ def complete(&) # rubocop:disable Metrics/PerceivedComplexity
         tools: @tools,
         temperature: @temperature,
         model: @model,
+        cache_prompts: @cache_prompts.dup,
         params: @params,
         headers: @headers,
         schema: @schema,

diff --git a/lib/ruby_llm/configuration.rb b/lib/ruby_llm/configuration.rb
@@ -43,7 +43,8 @@ class Configuration
                   :logger,
                   :log_file,
                   :log_level,
-                  :log_stream_debug
+                  :log_stream_debug,
+                  :cache_prompts
 
     def initialize
       @request_timeout = 120
@@ -64,6 +65,7 @@ def initialize
       @log_file = $stdout
       @log_level = ENV['RUBYLLM_DEBUG'] ? Logger::DEBUG : Logger::INFO
       @log_stream_debug = ENV['RUBYLLM_STREAM_DEBUG'] == 'true'
+      @cache_prompts = true
     end
 
     def instance_variables

diff --git a/lib/ruby_llm/message.rb b/lib/ruby_llm/message.rb
@@ -5,7 +5,8 @@ module RubyLLM
   class Message
     ROLES = %i[system user assistant tool].freeze
 
-    attr_reader :role, :tool_calls, :tool_call_id, :input_tokens, :output_tokens, :model_id, :raw
+    attr_reader :role, :tool_calls, :tool_call_id, :input_tokens, :output_tokens, :model_id, :raw,
+                :cached_tokens, :cache_creation_tokens
     attr_writer :content
 
     def initialize(options = {})
@@ -16,6 +17,8 @@ def initialize(options = {})
       @output_tokens = options[:output_tokens]
       @model_id = options[:model_id]
       @tool_call_id = options[:tool_call_id]
+      @cached_tokens = options[:cached_tokens]
+      @cache_creation_tokens = options[:cache_creation_tokens]
       @raw = options[:raw]
 
       ensure_valid_role
@@ -49,7 +52,9 @@ def to_h
         tool_call_id: tool_call_id,
         input_tokens: input_tokens,
         output_tokens: output_tokens,
-        model_id: model_id
+        model_id: model_id,
+        cache_creation_tokens: cache_creation_tokens,
+        cached_tokens: cached_tokens
       }.compact
     end
 

diff --git a/lib/ruby_llm/provider.rb b/lib/ruby_llm/provider.rb
@@ -37,7 +37,8 @@ def configuration_requirements
       self.class.configuration_requirements
     end
 
-    def complete(messages, tools:, temperature:, model:, params: {}, headers: {}, schema: nil, &) # rubocop:disable Metrics/ParameterLists
+    def complete(messages, tools:, temperature:, model:, params: {}, headers: {}, schema: nil, # rubocop:disable Metrics/ParameterLists
+                 cache_prompts: nil, &)
       normalized_temperature = maybe_normalize_temperature(temperature, model)
 
       payload = Utils.deep_merge(
@@ -46,6 +47,7 @@ def complete(messages, tools:, temperature:, model:, params: {}, headers: {}, sc
           tools: tools,
           temperature: normalized_temperature,
           model: model,
+          cache_prompts: cache_prompts,
           stream: block_given?,
           schema: schema
         ),

diff --git a/lib/ruby_llm/providers/anthropic.rb b/lib/ruby_llm/providers/anthropic.rb
@@ -10,6 +10,7 @@ class Anthropic < Provider
       include Anthropic::Models
       include Anthropic::Streaming
       include Anthropic::Tools
+      include Anthropic::Cache
 
       def api_base
         'https://api.anthropic.com'

diff --git a/lib/ruby_llm/providers/anthropic/cache.rb b/lib/ruby_llm/providers/anthropic/cache.rb
@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    class Anthropic
+      # Handles caching of prompts for Anthropic
+      module Cache
+        def should_cache?(type)
+          return false unless cache_prompts
+          return true if cache_prompts == true
+          return true if cache_prompts.is_a?(Array) && cache_prompts.include?(type)
+          return true if cache_prompts.is_a?(Symbol) && cache_prompts == type
+
+          false
+        end
+      end
+    end
+  end
+end