ruby_llm 2.1.0 → 2.2.0

data/lib/ruby_llm/protocol/unsupported_operations.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  class Protocol
+    # Turns the NotImplementedError of a missing seam into an Error naming the
+    # provider and the operation. It wraps only Protocol's own methods, so a
+    # subclass that replaces an operation answers for its own errors.
+    module UnsupportedOperations # :nodoc:
+      OPERATIONS = {
+        tool_approval_response: 'remote tool approvals',
+        render: 'chat',
+        count_tokens: 'token counting',
+        tokenize: 'text tokenization',
+        compact: 'manual compaction',
+        list_models: 'model listing',
+        embed: 'embeddings',
+        moderate: 'moderation',
+        paint: 'image generation',
+        animate_later: 'video generation',
+        find_video_job: 'video generation',
+        refresh_video_job: 'video generation',
+        speak: 'speech generation',
+        transcribe: 'transcription',
+        ocr: 'OCR',
+        rerank: 'reranking',
+        judge: 'judgments',
+        cache_content: 'explicit content caching',
+        find_cache: 'explicit content caching',
+        delete_cache: 'explicit content caching',
+        extend_cache: 'explicit content caching'
+      }.freeze
+
+      OPERATIONS.each do |operation, label|
+        define_method(operation) do |*args, **options, &block|
+          super(*args, **options, &block)
+        rescue NotImplementedError
+          raise Error, "#{@provider.name} doesn't support #{label}"
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/protocol.rb

@@ -38,6 +38,9 @@ module RubyLLM
     include Streaming
     include BinaryStreaming
     include RequestShapes
+    include NativeContent
+    prepend UnsupportedOperations
+    prepend ToolNamespaces
 
     # The Provider this protocol talks through.
     attr_reader :provider
@@ -91,18 +94,37 @@ module RubyLLM
       @model = model
     end
 
-    def tool_approval_response(tool_call, approved:)
-      Message.new(role: :tool, content: approved ? 'Approved' : 'Denied', tool_call_id: tool_call.id,
-                  raw_content: render_tool_approval_response(tool_call, approved:))
-    rescue NotImplementedError
-      raise Error, "#{@provider.name} doesn't support remote tool approvals"
+    # Returns the options of +operation+ (+:upload+, +:paint+, +:transcribe+,
+    # or +:embed+) this wire format has no way to carry, as an Array of
+    # Symbols. RubyLLM raises ArgumentError when a caller gives one, rather
+    # than dropping it. The default is none.
+    #
+    #   def rejected_options(operation)
+    #     operation == :paint ? %i[count] : super
+    #   end
+    #
+    def rejected_options(_operation)
+      []
+    end
+
+    def reject_options(operation, **options) # :nodoc:
+      rejected = rejected_options(operation) & options.compact.keys
+      return if rejected.empty?
+
+      raise ArgumentError, "#{@provider.name} #{operation} does not accept #{rejected.join(', ')}"
+    end
+
+    def tool_approval_response(tool_call, approved:, note: nil)
+      Message.new(role: :tool, content: approved ? 'Approved' : note || 'Denied', tool_call_id: tool_call.id,
+                  provider_call_id: tool_call.provider_call_id,
+                  raw_content: render_tool_approval_response(tool_call, approved:, note:))
     end
 
     def complete(messages, tools:, temperature:, provider_options: {}, headers: {}, schema: nil, thinking: nil,
                  max_output_tokens: nil, citations: false, caching: nil, tool_prefs: nil, before_request: [],
-                 usage_recorder: nil, provider_tools: [], compaction: nil, end_user: nil, &)
+                 usage_recorder: nil, progress_recorder: nil, provider_tools: [], compaction: nil, end_user: nil, &)
       resolution = resolve_provider_tools_for_request(provider_tools)
-      headers = resolution.headers.merge(headers) if resolution
+      headers = merge_tool_headers(resolution.headers, headers) if resolution
       headers = apply_compaction_headers(headers, compaction) if compaction
       payload = render(
         messages, tools:, tool_prefs:, temperature:, max_output_tokens:, provider_options:, schema:, thinking:,
@@ -110,6 +132,10 @@ module RubyLLM
                   stream: block_given?
       )
 
+      complete_request(payload, headers, usage_recorder:, progress_recorder:, &)
+    end
+
+    def complete_request(payload, headers, usage_recorder: nil, **) # :nodoc:
       # The caller's block can raise the error of another operation it ran.
       yielding = false
       track_usage(:chat, on_finish: usage_recorder) do
@@ -124,11 +150,23 @@ module RubyLLM
           sync_response payload, headers
         end
       end
+    rescue Error => e
+      raise e if yielding
+
+      e = unsupported_parameter_error(e)
+      claim_error(e, payload)
+      raise e
     rescue NotImplementedError
+      raise if yielding
+
       raise Error, "#{@provider.name} doesn't support chat"
-    rescue Error => e
-      claim_error(e, payload) unless yielding
-      raise
+    end
+
+    # Returns the parameter a rejected request named as one the model does
+    # not take, as UnsupportedParameterError#parameter describes, or +nil+.
+    # Protocols whose errors say so in structured fields override it.
+    def parse_unsupported_parameter(_response)
+      nil
     end
 
     def render(messages, tools:, temperature:, provider_options: {}, schema: nil, thinking: nil,
@@ -153,8 +191,35 @@ module RubyLLM
       payload = apply_provider_tools(payload, provider_tools)
       payload = apply_tool_search(payload)
       apply_before_request_hooks(payload, before_request)
-    rescue NotImplementedError
-      raise Error, "#{@provider.name} doesn't support chat"
+    end
+
+    # Returns whether the API searches deferred tools itself. Chat gives a
+    # model on any other API a +tool_search+ tool of its own instead.
+    def tool_search?
+      false
+    end
+
+    # Returns +caching+ for a fallback attempt, without the options this
+    # wire format cannot express, so a hint meant for the model the caller
+    # chose does not stop another provider from answering. An explicit
+    # cache +id+ names content the prompt relies on and stays.
+    def fallback_caching(caching) # :nodoc:
+      names = cache_option_names
+      return caching unless names
+
+      dropped = caching.keys - names - [:id]
+      return caching if dropped.empty?
+
+      RubyLLM.logger.debug do
+        "RubyLLM left out #{dropped.map { |name| ":#{name}" }.join(', ')} from caching on a fallback to " \
+          "#{@provider.name}, which has no use for it"
+      end
+      caching.except(*dropped)
+    end
+
+    # Returns whether this wire format takes a cache key.
+    def cache_key? # :nodoc:
+      cache_option_names&.include?(:key) || false
     end
 
     # Writes the chat's safety identifier into the request payload and
@@ -218,8 +283,6 @@ module RubyLLM
         caching: caching
       )
       parse_count_tokens_response post_count_tokens(payload)
-    rescue NotImplementedError
-      raise Error, "#{@provider.name} doesn't support token counting"
     rescue Error => e
       claim_error(e, payload)
       raise
@@ -234,8 +297,6 @@ module RubyLLM
       payload = render_tokenization_payload(text, model:)
       response = @connection.post tokenization_url, payload
       parse_tokenization_response(response, model:)
-    rescue NotImplementedError
-      raise Error, "#{@provider.name} doesn't support text tokenization"
     end
 
     def compact(messages, headers: {}, before_request: [], usage_recorder: nil)
@@ -246,8 +307,6 @@ module RubyLLM
         end
         parse_compaction_response(response)
       end
-    rescue NotImplementedError
-      raise Error, "#{@provider.name} doesn't support manual compaction"
     rescue Error => e
       claim_error(e, payload)
       raise
@@ -255,7 +314,7 @@ module RubyLLM
 
     def embed(text, model:, dimensions:, task_type: nil, title: nil, with: nil, provider_options: {})
       attachments = Attachment.wrap(with, config: @config)
-      raise UnsupportedAttachmentError, attachments.first.mime_type if attachments.any? && !supports_embedding_media?
+      raise UnsupportedAttachmentError, attachments.first.mime_type if attachments.any? && !embedding_media?
 
       track_usage(:embedding) do
         payload = if attachments.any?
@@ -265,10 +324,8 @@ module RubyLLM
                     render_embedding_payload(text, model:, dimensions:, task_type:, title:, provider_options:)
                   end
         response = @connection.post(embedding_url(model:), payload, usage: @usage_tracker)
-        parse_embedding_response(response, model:, text:)
+        ensure_embedding_per_text(parse_embedding_response(response, model:, text:), text, attachments, response)
       end
-    rescue NotImplementedError
-      raise Error, "#{@provider.name} doesn't support embeddings"
     end
 
     def render_embedding(text, model:, dimensions: nil, task_type: nil, title: nil, provider_options: {}) # :nodoc:
@@ -282,8 +339,6 @@ module RubyLLM
         response = @connection.post moderation_url, payload, usage: @usage_tracker
         parse_moderation_response(response, model:)
       end
-    rescue NotImplementedError
-      raise Error, "#{@provider.name} doesn't support moderation"
     end
 
     def paint(prompt, model:, size:, count: nil, with: nil, mask: nil, provider_options: {})
@@ -295,8 +350,6 @@ module RubyLLM
         images.each { |image| image.config = @config }
         images.size <= 1 ? images.first : images
       end
-    rescue NotImplementedError
-      raise Error, "#{@provider.name} doesn't support image generation"
     end
 
     def post_image(payload, with:, mask:)
@@ -329,8 +382,6 @@ module RubyLLM
       end
       response = post_video(url, payload)
       parse_video_job(response, model:, **parse_video_request(payload))
-    rescue NotImplementedError
-      raise Error, "#{@provider.name} doesn't support video generation"
     end
 
     # Returns the duration in seconds and the resolution a rendered video
@@ -387,6 +438,10 @@ module RubyLLM
       parse_video_job_status @connection.get(video_job_url(job)), job: job
     end
 
+    def find_video_job(id, model:)
+      VideoJob.new(id:, protocol: self, model:).refresh
+    end
+
     def speak(input, model:, voice:, format:, provider_options: {}, &block)
       track_usage(:speech) do
         payload = render_speech_payload(input, model:, voice:, format:, provider_options:)
@@ -395,8 +450,6 @@ module RubyLLM
         response = @connection.post speech_url(model:), payload, usage: @usage_tracker
         parse_speech_response(response, model:, voice:, format:)
       end
-    rescue NotImplementedError
-      raise Error, "#{@provider.name} doesn't support speech generation"
     end
 
     def stream_speech(*, **, &)
@@ -431,8 +484,6 @@ module RubyLLM
         response = @connection.post transcription_url, payload, usage: @usage_tracker
         parse_transcription_response(response, model:)
       end
-    rescue NotImplementedError
-      raise Error, "#{@provider.name} doesn't support transcription"
     end
 
     # Streams a transcription, yielding TranscriptionChunk objects and
@@ -449,7 +500,7 @@ module RubyLLM
     # Whether the protocol can embed media attachments alongside text.
     # Protocols that support multimodal embeddings override this and accept
     # a +with:+ array of Attachments in render_embedding_payload.
-    def supports_embedding_media?
+    def embedding_media?
       false
     end
 
@@ -459,8 +510,6 @@ module RubyLLM
         response = @connection.post ocr_url, payload, usage: @usage_tracker
         parse_ocr_response(response, model:)
       end
-    rescue NotImplementedError
-      raise Error, "#{@provider.name} doesn't support OCR"
     end
 
     def rerank(query, documents, model:, top_n: nil, provider_options: {})
@@ -469,8 +518,6 @@ module RubyLLM
         response = @connection.post rerank_url, payload, usage: @usage_tracker
         parse_rerank_response(response, model:, documents:)
       end
-    rescue NotImplementedError
-      raise Error, "#{@provider.name} doesn't support reranking"
     end
 
     def cache_content(content, model:, ttl: nil, instructions: nil, with: nil)
@@ -478,8 +525,6 @@ module RubyLLM
                                               attachments: Attachment.wrap(with, config: @config))
       response = @connection.post caches_url, payload, idempotent: false
       parse_cache_response(response.body)
-    rescue NotImplementedError
-      raise Error, "#{@provider.name} doesn't support explicit content caching"
     end
 
     def judge(input, questions:, model:, with: [], provider_options: {}) # :nodoc:
@@ -488,35 +533,35 @@ module RubyLLM
         response = @connection.post judgment_url, payload, usage: @usage_tracker
         parse_judgment_response(response, questions:)
       end
-    rescue NotImplementedError
-      raise Error, "#{@provider.name} doesn't support judgments"
     end
 
     def find_cache(name)
       response = @connection.get cache_url(name)
       parse_cache_response(response.body)
-    rescue NotImplementedError
-      raise Error, "#{@provider.name} doesn't support explicit content caching"
     end
 
     def delete_cache(name)
       @connection.delete cache_url(name)
       true
-    rescue NotImplementedError
-      raise Error, "#{@provider.name} doesn't support explicit content caching"
     end
 
     def extend_cache(name, ttl:)
       response = @connection.patch cache_url(name), render_cache_update_payload(ttl:)
       parse_cache_response(response.body)
-    rescue NotImplementedError
-      raise Error, "#{@provider.name} doesn't support explicit content caching"
     end
 
     def parse_error(response)
       @provider.parse_error(response)
     end
 
+    def slug # :nodoc:
+      @provider.slug
+    end
+
+    def parse_error_code(response) # :nodoc:
+      @provider.parse_error_code(response)
+    end
+
     # Returns a RequestShape describing +payload+, a conversation request
     # this protocol rendered, as JSON parsed back with String keys.
     # Error#request_shape asks for it when the request fails. The default
@@ -577,68 +622,29 @@ module RubyLLM
 
     private
 
-    # An error raised before the request went out answers no request.
-    def claim_error(error, payload)
-      return if error.request_protocol || error.response.nil? || payload.nil?
-
-      error.request_protocol = self
-      error.request_payload = payload
-    end
-
-    # A thinking signature or a provider-shaped content block belongs to the
-    # model that produced it, and one provider can serve models that do not
-    # read each other's, so a message another model produced replays
-    # without them. A message with no known producer replays as it is.
-    def foreign_native_content?(message)
-      return false unless message.role == :assistant && carries_native_content?(message)
-
-      producer = producing_entry(message)
-      !producer.nil? && (producer.provider != @provider.slug || !current_model?(producer.model))
-    end
-
-    # Usage records the id a chat resolved its model to, and a message built
-    # by hand may name the model by an alias of it.
-    def current_model?(model_id)
-      return true if @model.nil? || model_id == @model.id
-
-      RubyLLM.models.find(model_id, provider: @provider.slug, config: @config).id == @model.id
-    rescue ModelNotFoundError
-      false
-    end
-
-    # Another model of this provider gets the raw content any of its models
-    # reads, such as a tool search, and none of the producing model's own.
-    def without_foreign_native_content(message)
-      portable = portable_raw_content(message) if producer_slug(message) == @provider.slug
-      message.without_native_content(raw_content: portable)
-    end
-
-    def portable_raw_content(_message)
+    # The with_caching options this wire format can express, or +nil+ when
+    # it ignores the ones it has no use for.
+    def cache_option_names
       nil
     end
 
-    def carries_native_content?(message)
-      return true if message.thinking || message.raw_reasoning || message.raw_content
+    def unsupported_parameter_error(error)
+      return error unless error.instance_of?(BadRequestError) && error.response
 
-      message.tool_call? && message.tool_calls.each_value.any?(&:thought_signature)
-    end
+      parameter = parse_unsupported_parameter(error.response)
+      return error unless parameter
 
-    # Only a usage entry names the producer: a model id alone can belong
-    # to several providers.
-    def producer_slug(message)
-      producing_entry(message)&.provider
+      UnsupportedParameterError.new(nil, parameter:, response: error.response, provider: error.provider,
+                                         provider_message: error.provider_message, error_code: error.error_code,
+                                         redact: @provider.config&.redact_error_messages)
     end
 
-    def producing_entry(message)
-      message.ruby_llm_usage_entries.reverse.find(&:succeeded?)
-    end
+    # An error raised before the request went out answers no request.
+    def claim_error(error, payload)
+      return if error.request_protocol || error.response.nil? || payload.nil?
 
-    # A thinking signature can be another provider's opaque blob, and a
-    # message restored without its usage could come from anyone, so a
-    # protocol that verifies signatures gets back only its own.
-    def own_signature(message)
-      signature = message.thinking&.signature
-      signature if signature && producer_slug(message) == @provider.slug
+      error.request_protocol = self
+      error.request_payload = payload
     end
 
     def resolve_provider_tools_for_request(entries)
@@ -654,6 +660,10 @@ module RubyLLM
       RubyLLM::Tools::ProviderTools.resolve(entries, aliases: aliases, owner: @provider.name)
     end
 
+    def merge_tool_headers(tool_headers, headers)
+      tool_headers.merge(headers)
+    end
+
     def apply_provider_tools(payload, entries)
       resolution = resolve_provider_tools_for_request(entries)
       return payload unless resolution
@@ -673,6 +683,13 @@ module RubyLLM
       payload
     end
 
+    def ensure_embedding_per_text(embedding, text, attachments, response)
+      count = Array(embedding.vectors).size
+      return embedding if attachments.any? || !text.is_a?(Array) || count == text.size
+
+      raise Error.new("Expected #{text.size} embeddings, got #{count}", response:)
+    end
+
     def track_usage(operation, on_finish: nil, model_id: nil)
       @usage_tracker = Accounting::Usage::Tracker.new(
         operation:,
@@ -689,19 +706,22 @@ module RubyLLM
       @usage_tracker.fail_pending(e)
       raise
     ensure
+      @usage_tracker.cancel_pending
       @usage_tracker = nil
     end
 
     def apply_before_request_hooks(payload, hooks)
-      Array(hooks).each { |hook| hook.call(payload) }
-      payload
+      hooks = Array(hooks)
+      return payload if hooks.empty?
+
+      Support::Utils.deep_dup(payload).tap { |copy| hooks.each { |hook| hook.call(copy) } }
     end
 
     def auto_upload_large_files?
-      @config.auto_upload_large_files && @provider.files? && supports_provider_file_references?
+      @config.auto_upload_large_files && @provider.files? && provider_file_references?
     end
 
-    def supports_provider_file_references?
+    def provider_file_references?
       false
     end
 
@@ -709,7 +729,8 @@ module RubyLLM
       return attachment if attachment.provider_file?
       return attachment unless upload_large_attachment?(attachment)
 
-      Attachment.new(provider_upload(attachment), resolution: attachment.resolution, config: @config)
+      Attachment.new(provider_upload(attachment), resolution: attachment.resolution,
+                                                  processing: attachment.processing, config: @config)
     end
 
     def supported_message_attachment?(_message, attachment)
@@ -753,12 +774,16 @@ module RubyLLM
     end
 
     def missing_uploads(messages, error, scope)
-      uploads = messages.flat_map(&:attachments).filter_map do |attachment|
+      uploads = attachment_uploads(messages, scope)
+      named = uploads.select { |_, upload| names_file?(error, upload.id) }
+      named.empty? && error.response&.status == 404 ? uploads : named
+    end
+
+    def attachment_uploads(messages, scope)
+      messages.flat_map(&:attachments).uniq(&:object_id).filter_map do |attachment|
         upload = attachment.provider_uploads[scope]
         [attachment, upload] if upload
       end
-      named = uploads.select { |_, upload| names_file?(error, upload.id) }
-      named.empty? && error.response&.status == 404 ? uploads : named
     end
 
     def names_file?(error, id)

data/lib/ruby_llm/protocols/anthropic/batches.rb

@@ -9,8 +9,11 @@ module RubyLLM
         include RubyLLM::Batch::Helpers
 
         def create_batch(requests)
+          headers = batch_betas(requests)
           requests = requests.map { |request| { custom_id: request[:custom_id], params: request[:payload] } }
-          response = @connection.post batches_url, { requests: requests }, idempotent: false
+          response = @connection.post(batches_url, { requests: requests }, idempotent: false) do |request|
+            request.headers.merge!(headers)
+          end
           parse_batch_response response.body
         end
 
@@ -31,6 +34,23 @@ module RubyLLM
 
         private
 
+        # One request carries the whole batch, so it takes every beta any
+        # of its entries needs.
+        def batch_betas(requests)
+          requests.reduce({}) do |headers, request|
+            payload = request[:payload]
+            headers = beta_headers(with_request_betas(headers, request), payload)
+            headers = apply_mcp_beta(headers) if block_value(payload, :mcp_servers)
+            compaction = block_value(payload, :context_management)
+            compaction ? apply_compaction_headers(headers, compaction) : headers
+          end
+        end
+
+        def with_request_betas(headers, request)
+          betas = canonical_beta_headers(request[:headers].to_h)[Chat::BETA_HEADER]
+          betas ? add_beta(headers, betas) : headers
+        end
+
         def batches_url
           'v1/messages/batches'
         end
@@ -41,18 +61,35 @@ module RubyLLM
 
         def parse_batch_response(data)
           request_counts = data['request_counts']
+          completed = data['processing_status'] == 'ended'
 
           {
             id: data['id'],
-            raw_status: data['processing_status'],
-            completed: data['processing_status'] == 'ended',
+            raw_status: completed ? ended_batch_status(request_counts) : data['processing_status'],
+            completed:,
             request_counts:,
             request_count: request_counts&.values&.sum
           }
         end
 
+        # Anthropic ends every batch as "ended"; only the request counts say
+        # whether it was cancelled or ran out of time. A batch with any
+        # success ended, and its cancelled or expired slots fail on their own.
+        def ended_batch_status(request_counts)
+          return 'ended' if request_counts&.fetch('succeeded', 0).to_i.positive?
+
+          %w[canceled expired].find { |outcome| request_counts&.fetch(outcome, 0).to_i.positive? } || 'ended'
+        end
+
         def parse_batch_status(raw_status, completed:)
-          completed && raw_status == 'ended' ? :succeeded : :pending
+          return :pending unless completed
+
+          case raw_status
+          when 'ended' then :succeeded
+          when 'canceled' then :cancelled
+          when 'expired' then :failed
+          else :pending
+          end
         end
 
         def parse_batch_result(line)

data/lib/ruby_llm/protocols/anthropic/block_binding.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Protocols
+    class Anthropic
+      # These Claude models bind a signed thinking block to the instructions,
+      # tools, and messages it was written under, and refuse it once they
+      # change. Dropping the block lets the model think that turn again.
+      module BlockBinding # :nodoc:
+        BETA = 'thinking-binding-controls-2026-08-01'
+        MODELS = /claude-(?:(?:opus|sonnet|haiku)-5-5|fable-5-1)/
+        DROP_STALE_BLOCKS = { prefix_mismatch_behavior: 'drop_block' }.freeze
+
+        module_function
+
+        def binds?(model_id)
+          MODELS.match?(model_id.to_s)
+        end
+
+        # Returns +thinking+ with the binding added, or +nil+ when thinking
+        # is set to anything but adaptive, which the binding would replace.
+        def apply(thinking)
+          return unless thinking.nil? || thinking[:type] == 'adaptive'
+
+          { type: 'adaptive', **thinking.to_h, block_binding: DROP_STALE_BLOCKS }
+        end
+      end
+    end
+  end
+end