Add with_provider_options and use that for opting into caching

Author: tpaulshippy

docs/_core_features/chat.md

@@ -505,21 +505,21 @@ Refer to the [Working with Models Guide]({% link _advanced/models.md %}) for det
 ### Enabling
 For Anthropic models, you can opt-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).
 
-Enable prompt caching using the `cache_prompts` method on your chat instance:
+Enable prompt caching using the `with_provider_options` method on your chat instance:
 
 ```ruby
 chat = RubyLLM.chat(model: 'claude-3-5-haiku-20241022')
 
 # Enable caching for different types of content
-chat.cache_prompts(
-  system: true,  # Cache system instructions
-  user: true,    # Cache user messages
-  tools: true    # Cache tool definitions
+chat.with_provider_options(
+  cache_last_system_prompt: true,  # Cache system instructions
+  cache_last_user_prompt: true,    # Cache user messages
+  cache_tools: true    # Cache tool definitions
 )
 ```
 
 ### 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, 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.
 

lib/ruby_llm/active_record/chat_methods.rb

@@ -135,8 +135,8 @@ def with_schema(...)
         self
       end
 
-      def cache_prompts(...)
-        to_llm.cache_prompts(...)
+      def with_provider_options(...)
+        to_llm.with_provider_options(...)
         self
       end
 

lib/ruby_llm/chat.rb

@@ -98,6 +98,11 @@ def with_schema(schema)
       self
     end
 
+    def with_provider_options(options)
+      @provider.with_options(options)
+      self
+    end
+
     def on_new_message(&block)
       @on[:new_message] = block
       self
@@ -122,18 +127,12 @@ def each(&)
       messages.each(&)
     end
 
-    def cache_prompts(system: false, user: false, tools: false)
-      @cache_prompts = { system: system, user: user, tools: tools }
-      self
-    end
-
     def complete(&) # rubocop:disable Metrics/PerceivedComplexity
       response = @provider.complete(
         messages,
         tools: @tools,
         temperature: @temperature,
         model: @model,
-        cache_prompts: @cache_prompts.dup,
         params: @params,
         headers: @headers,
         schema: @schema,

lib/ruby_llm/provider.rb

@@ -5,12 +5,18 @@ module RubyLLM
   class Provider
     include Streaming
 
-    attr_reader :config, :connection
+    attr_reader :config, :connection, :options
 
     def initialize(config)
       @config = config
       ensure_configured!
       @connection = Connection.new(self, @config)
+      @options = self.class.respond_to?(:options) ? self.class.options.new : nil
+    end
+
+    def with_options(options)
+      @options = options.is_a?(self.class.options) ? options : self.class.options.new(**options)
+      self
     end
 
     def api_base
@@ -37,8 +43,7 @@ def configuration_requirements
       self.class.configuration_requirements
     end
 
-    def complete(messages, tools:, temperature:, model:, params: {}, headers: {}, schema: nil, # rubocop:disable Metrics/ParameterLists
-                 cache_prompts: { system: false, user: false, tools: false }, &)
+    def complete(messages, tools:, temperature:, model:, params: {}, headers: {}, schema: nil, &) # rubocop:disable Metrics/ParameterLists
       normalized_temperature = maybe_normalize_temperature(temperature, model)
 
       payload = Utils.deep_merge(
@@ -47,7 +52,6 @@ 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
         ),

lib/ruby_llm/providers/anthropic.rb

@@ -22,11 +22,26 @@ def headers
         }
       end
 
+      # Options for the Anthropic provider
+      class Options
+        attr_accessor :cache_last_system_prompt, :cache_last_user_prompt, :cache_tools
+
+        def initialize(cache_last_system_prompt: false, cache_last_user_prompt: false, cache_tools: false)
+          @cache_last_system_prompt = cache_last_system_prompt
+          @cache_last_user_prompt = cache_last_user_prompt
+          @cache_tools = cache_tools
+        end
+      end
+
       class << self
         def capabilities
           Anthropic::Capabilities
         end
 
+        def options
+          Anthropic::Options
+        end
+
         def configuration_requirements
           %i[anthropic_api_key]
         end

lib/ruby_llm/providers/anthropic/chat.rb

@@ -11,31 +11,29 @@ def completion_url
           '/v1/messages'
         end
 
-        def render_payload(messages, tools:, temperature:, model:, stream: false, schema: nil, # rubocop:disable Metrics/ParameterLists,Lint/UnusedMethodArgument
-                           cache_prompts: { system: false, user: false, tools: false })
+        def render_payload(messages, tools:, temperature:, model:, stream: false, schema: nil) # rubocop:disable Metrics/ParameterLists,Lint/UnusedMethodArgument
           system_messages, chat_messages = separate_messages(messages)
-          system_content = build_system_content(system_messages, cache: cache_prompts[:system])
+          system_content = build_system_content(system_messages, options)
 
-          build_base_payload(chat_messages, model, stream, cache: cache_prompts[:user]).tap do |payload|
-            add_optional_fields(payload, system_content:, tools:, temperature:,
-                                         cache_tools: cache_prompts[:tools])
+          build_base_payload(chat_messages, model, stream).tap do |payload|
+            add_optional_fields(payload, system_content:, tools:, temperature:, options:)
           end
         end
 
         def separate_messages(messages)
           messages.partition { |msg| msg.role == :system }
         end
 
-        def build_system_content(system_messages, cache: false)
+        def build_system_content(system_messages, options)
           system_messages.flat_map.with_index do |msg, idx|
-            message_cache = cache if idx == system_messages.size - 1
+            message_cache = options.cache_last_system_prompt if idx == system_messages.size - 1
             format_system_message(msg, cache: message_cache)
           end
         end
 
-        def build_base_payload(chat_messages, model, stream, cache: false)
+        def build_base_payload(chat_messages, model, stream)
           messages = chat_messages.map.with_index do |msg, idx|
-            message_cache = cache if idx == chat_messages.size - 1
+            message_cache = options.cache_last_user_prompt if idx == chat_messages.size - 1
             format_message(msg, cache: message_cache)
           end
 
@@ -47,10 +45,10 @@ def build_base_payload(chat_messages, model, stream, cache: false)
           }
         end
 
-        def add_optional_fields(payload, system_content:, tools:, temperature:, cache_tools: false)
+        def add_optional_fields(payload, system_content:, tools:, temperature:, options:)
           if tools.any?
             tool_definitions = tools.values.map { |t| Tools.function_for(t) }
-            tool_definitions[-1][:cache_control] = { type: 'ephemeral' } if cache_tools
+            tool_definitions[-1][:cache_control] = { type: 'ephemeral' } if options.cache_tools
             payload[:tools] = tool_definitions
           end
 

lib/ruby_llm/providers/bedrock.rb

@@ -67,12 +67,15 @@ def build_headers(signature_headers, streaming: false)
           'Accept' => accept_header
         )
       end
-
       class << self
         def capabilities
           Bedrock::Capabilities
         end
 
+        def options
+          Anthropic::Options
+        end
+
         def configuration_requirements
           %i[bedrock_api_key bedrock_secret_key bedrock_region]
         end

lib/ruby_llm/providers/bedrock/chat.rb

@@ -39,20 +39,19 @@ def completion_url
           "model/#{@model_id}/invoke"
         end
 
-        def render_payload(messages, tools:, temperature:, model:, stream: false, schema: nil, # rubocop:disable Lint/UnusedMethodArgument,Metrics/ParameterLists
-                           cache_prompts: { system: false, user: false, tools: false })
+        def render_payload(messages, tools:, temperature:, model:, stream: false, schema: nil) # rubocop:disable Lint/UnusedMethodArgument,Metrics/ParameterLists
           @model_id = model.id
 
           system_messages, chat_messages = Anthropic::Chat.separate_messages(messages)
-          system_content = Anthropic::Chat.build_system_content(system_messages, cache: cache_prompts[:system])
+          system_content = Anthropic::Chat.build_system_content(system_messages, options)
 
-          build_base_payload(chat_messages, model, cache: cache_prompts[:user]).tap do |payload|
+          build_base_payload(chat_messages, model).tap do |payload|
             Anthropic::Chat.add_optional_fields(
               payload,
               system_content:,
               tools:,
               temperature:,
-              cache_tools: cache_prompts[:tools]
+              options:
             )
           end
         end

lib/ruby_llm/providers/gemini/chat.rb

@@ -11,7 +11,7 @@ def completion_url
           "models/#{@model}:generateContent"
         end
 
-        def render_payload(messages, tools:, temperature:, model:, stream: false, schema: nil, cache_prompts: {}) # rubocop:disable Metrics/ParameterLists,Lint/UnusedMethodArgument
+        def render_payload(messages, tools:, temperature:, model:, stream: false, schema: nil) # rubocop:disable Metrics/ParameterLists,Lint/UnusedMethodArgument
           @model = model.id
           payload = {
             contents: format_messages(messages),

lib/ruby_llm/providers/mistral/chat.rb

@@ -12,7 +12,7 @@ def format_role(role)
         end
 
         # rubocop:disable Metrics/ParameterLists
-        def render_payload(messages, tools:, temperature:, model:, stream: false, schema: nil, cache_prompts: {}) # rubocop:disable Metrics/ParameterLists
+        def render_payload(messages, tools:, temperature:, model:, stream: false, schema: nil) # rubocop:disable Metrics/ParameterLists
           payload = super
           payload.delete(:stream_options)
           payload