ruby_llm 2.0.0 → 2.1.0

data/lib/ruby_llm/provider.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'digest'
 require 'json'
 require 'ruby_llm/error'
 
@@ -110,6 +111,10 @@ module RubyLLM
       self.class.configuration_requirements
     end
 
+    def original_image_detail? # :nodoc:
+      false
+    end
+
     def protocols # :nodoc:
       self.class.protocols
     end
@@ -200,17 +205,13 @@ module RubyLLM
       )
     end
 
-    def preprocess_message(message, model:, protocol: nil) # :nodoc:
-      protocol_class = resolve_protocol(
-        protocol,
-        model,
-        tools: {},
-        schema: nil,
-        thinking: nil,
-        tool_prefs: nil,
-        citations: false
-      )
-      protocol_class.new(self, model).preprocess_message(message)
+    def preprocess_messages(messages, model:, protocol: nil, unsupported_attachment: nil) # :nodoc:
+      preprocessor = preprocessing_protocol(protocol, model)
+      messages.map { |message| preprocessor.preprocess_message(message, unsupported_attachment:) }
+    end
+
+    def discard_missing_uploads(messages, error, model:, protocol: nil) # :nodoc:
+      preprocessing_protocol(protocol, model).discard_missing_uploads(messages, error)
     end
 
     def batches? # :nodoc:
@@ -256,7 +257,13 @@ module RubyLLM
       batch_tier = pricing.batch unless long_context_pricing?(pricing, tokens)
       batch = Cost.new(tokens:, model:, category:, tier: :batch) if batch_tier
       amounts = batch_cost_amounts(standard:, batch:, batch_tier:, model:)
-      Cost.from_h(amounts, tokens:)
+      Cost.new(amounts:, missing: batch_cost_missing(amounts, standard), reported: standard.tokens?)
+    end
+
+    def batch_cost_missing(amounts, standard) # :nodoc:
+      amounts.filter_map do |component, amount|
+        component if amount.nil? && (standard.missing?(component) || standard.public_send(component)&.positive?)
+      end
     end
 
     def batch_cost_amounts(standard:, batch:, batch_tier:, model:) # :nodoc:
@@ -288,6 +295,21 @@ module RubyLLM
       protocols.key?(:files)
     end
 
+    # Returns a String naming the account that owns the files this provider
+    # uploads, or +nil+ to keep each upload within the process that made it.
+    # The base implementation returns +nil+. Rails chats reuse an upload in
+    # later processes only under the same identity, so build it from what
+    # decides where uploaded files live, such as the endpoint and API key,
+    # an organization or project, or a storage bucket. Digest anything
+    # secret, and leave out credentials that rotate, such as session tokens:
+    #
+    #   def account_identity
+    #     Digest::SHA256.hexdigest([api_base, @config.acme_api_key].join("\0"))
+    #   end
+    def account_identity
+      nil
+    end
+
     def list_models # :nodoc:
       listing_protocol.new(self).list_models
     end
@@ -316,8 +338,8 @@ module RubyLLM
       )
     end
 
-    def research_later(prompt, **options) # :nodoc:
-      fetch_protocol(:research).new(self).create_research_job(prompt, **options)
+    def research_later(prompt, **) # :nodoc:
+      fetch_protocol(:research).new(self).create_research_job(prompt, **)
     end
 
     def find_research_job(id) # :nodoc:
@@ -374,6 +396,11 @@ module RubyLLM
       protocol.new(self, model).rerank(query, documents, model: model_id_for(model), top_n:, provider_options:)
     end
 
+    def judge(input, questions:, model:, with: [], provider_options: {}) # :nodoc:
+      protocol = resolve_protocol(nil, model, operation: :judge)
+      protocol.new(self, model).judge(input, questions:, model: model_id_for(model), with:, provider_options:)
+    end
+
     def upload_file(file, filename: nil, purpose: nil, expires_in: nil, uri: nil, content_type: nil, # :nodoc:
                     provider_options: {})
       ensure_files_supported!
@@ -466,6 +493,20 @@ module RubyLLM
         nil
       end
 
+      # Returns the thinking options that turn thinking off for +model_id+, or
+      # +nil+ when the provider has no off control beyond the model registry.
+      def thinking_off_control(_model_id) # :nodoc:
+        nil
+      end
+
+      # Returns the multiple of the input price that a prompt cache write
+      # with lifetime +ttl+ costs on +model_id+, or +nil+ when the
+      # registry's cache-write price applies. Providers whose models.dev
+      # cache-write price covers only the default lifetime override it.
+      def cache_write_input_multiplier(_model_id, _ttl) # :nodoc:
+        nil
+      end
+
       def models_dev_alias(_model_id, _models_dev_by_key, _provider_model = nil) # :nodoc:
         nil
       end
@@ -576,6 +617,13 @@ module RubyLLM
         model_id
       end
 
+      # Returns the id of the model that the deployment named +model_id+
+      # runs, or +nil+ when +model_id+ is not a declared deployment.
+      # Providers whose requests name deployments override it.
+      def deployed_model_id(_model_id, _config = nil)
+        nil
+      end
+
       # Returns the global registry of providers, a hash mapping slug
       # symbols to provider classes.
       def providers
@@ -624,6 +672,11 @@ module RubyLLM
       explicit ? fetch_protocol(explicit) : protocol_for(model, **request)
     end
 
+    def preprocessing_protocol(protocol, model)
+      resolve_protocol(protocol, model, tools: {}, schema: nil, thinking: nil, tool_prefs: nil, citations: false)
+        .new(self, model)
+    end
+
     def default_protocol
       fetch_protocol(configured_protocol || self.class.default_protocol)
     end
@@ -667,6 +720,10 @@ module RubyLLM
       model.respond_to?(:id) ? model.id : model
     end
 
+    def account_digest(*parts)
+      Digest::SHA256.hexdigest(parts.join("\0"))
+    end
+
     def try_parse_json(maybe_json)
       return maybe_json unless maybe_json.is_a?(String)
 
@@ -689,7 +746,22 @@ module RubyLLM
       return error if error.is_a?(String)
 
       nested_message = error['message'] if error.is_a?(Hash)
-      [nested_message, part['message'], part['detail']].find { |message| message.is_a?(String) }
+      [nested_message, part['message'], part['detail']].find { |message| message.is_a?(String) } ||
+        validation_detail_message(part['detail'])
+    end
+
+    def validation_detail_message(detail)
+      return unless detail.is_a?(Array)
+
+      messages = detail.filter_map { |error| format_validation_error(error) }
+      messages.join('; ') unless messages.empty?
+    end
+
+    def format_validation_error(error)
+      return unless error.is_a?(Hash)
+
+      text = [Array(error['loc']).join('.'), error['msg']&.to_s].compact.reject(&:empty?).join(': ')
+      text unless text.empty?
     end
 
     def ensure_configured!

data/lib/ruby_llm/providers/anthropic.rb

@@ -4,6 +4,11 @@ module RubyLLM
   module Providers
     # Anthropic Claude API integration.
     class Anthropic < Provider
+      SONNET_55_MODEL_IDS = %w[claude-sonnet-5-5 anthropic.claude-sonnet-5-5].freeze
+      private_constant :SONNET_55_MODEL_IDS
+      CACHE_WRITE_INPUT_MULTIPLIERS = { '1h' => 2 }.freeze
+      private_constant :CACHE_WRITE_INPUT_MULTIPLIERS
+
       protocol :anthropic, Protocols::Anthropic, batches: Protocols::Anthropic::Batches
       protocol :files, Protocols::Anthropic::Files
 
@@ -18,6 +23,10 @@ module RubyLLM
         }
       end
 
+      def account_identity
+        account_digest(api_base, @config.anthropic_api_key)
+      end
+
       def batch_cost_multiplier(**) = 0.5
 
       class << self
@@ -25,6 +34,20 @@ module RubyLLM
           Anthropic::Capabilities
         end
 
+        def between_tools_off?(model_id) # :nodoc:
+          SONNET_55_MODEL_IDS.include?(model_id.to_s)
+        end
+
+        def thinking_off_control(model_id) # :nodoc:
+          { enabled: false } if between_tools_off?(model_id)
+        end
+
+        # models.dev prices the five-minute cache write; Anthropic bills a
+        # one-hour write at twice the input price.
+        def cache_write_input_multiplier(_model_id, ttl) # :nodoc:
+          CACHE_WRITE_INPUT_MULTIPLIERS[ttl.to_s]
+        end
+
         def configuration_options
           %i[anthropic_api_key anthropic_api_base]
         end

data/lib/ruby_llm/providers/azure/chat.rb

@@ -9,6 +9,10 @@ module RubyLLM
           azure_endpoint(:chat)
         end
 
+        def supported_attachment?(attachment)
+          Azure::Media.supported_attachment?(attachment)
+        end
+
         def format_content(content, attachments = [])
           Media.format_content(content, attachments)
         end

data/lib/ruby_llm/providers/azure/images.rb

@@ -9,8 +9,8 @@ module RubyLLM
           @provider.azure_media_url(super)
         end
 
-        def render_edit_payload(prompt, size:, provider_options:, **options)
-          super(prompt, size:, provider_options: { size: size }.compact.merge(provider_options), **options)
+        def render_edit_payload(prompt, size:, provider_options:, **)
+          super(prompt, size:, provider_options: { size: size }.compact.merge(provider_options), **)
         end
 
         def json_image_references?(_model)

data/lib/ruby_llm/providers/azure/media.rb

@@ -7,17 +7,22 @@ module RubyLLM
       module Media
         module_function
 
+        def supported_attachment?(attachment)
+          %i[image audio text].include?(attachment.type)
+        end
+
         def format_content(content, attachments = [])
           Protocols::ChatCompletions::Media.format_parts(content, attachments) do |attachment|
+            raise UnsupportedAttachmentError, attachment.mime_type unless supported_attachment?(attachment)
+
             case attachment.type
             when :image
-              format_image(attachment)
+              Protocols::ChatCompletions::Media.with_image_detail(format_image(attachment), attachment,
+                                                                  original_detail: true)
             when :audio
               Protocols::ChatCompletions::Media.format_audio(attachment)
             when :text
               Protocols::ChatCompletions::Media.format_text_file(attachment)
-            else
-              raise UnsupportedAttachmentError, attachment.mime_type
             end
           end
         end

data/lib/ruby_llm/providers/azure/videos.rb

@@ -17,11 +17,16 @@ module RubyLLM
           { model: model, prompt: prompt }.merge(provider_options)
         end
 
-        def parse_video_job(response, model:)
+        def parse_video_job(response, model:, **request)
           id = response.body['id']
           raise Error.new('Azure did not return a video generation job', response:) unless id
 
-          VideoJob.new(id: id, protocol: self, model: model, raw: response.body)
+          VideoJob.new(id: id, protocol: self, model: model, raw: response.body, **request)
+        end
+
+        def video_request_settings(request)
+          width, height = request.values_at(:width, :height)
+          { duration: request[:n_seconds], resolution: ("#{width}x#{height}" if width && height) }
         end
 
         def video_job_url(job)

data/lib/ruby_llm/providers/azure.rb

@@ -13,12 +13,22 @@ module RubyLLM
       protocol :files, Protocols::Azure::Files
       protocol :cohere, Azure::Cohere
 
+      def original_image_detail? # :nodoc:
+        true
+      end
+
       def api_base
         @config.azure_api_base
       end
 
-      # Deployments named after gpt-5.4+ models need the Responses API for
-      # tool use, so they route there automatically. Deployment names often
+      # Files belong to the Azure resource, whichever key or Entra ID token
+      # signs the request.
+      def account_identity
+        account_digest(azure_openai_v1_base)
+      end
+
+      # Deployments named after gpt-5.4+ and gpt-6+ models need the Responses
+      # API for tool use, so they route there automatically. Deployment names often
       # differ from model ids, so the routing stays conservative; an explicit
       # protocol: or the azure_protocol configuration option overrides it.
       def protocol_for(model, operation: nil, **)
@@ -28,7 +38,7 @@ module RubyLLM
           return protocols[:cohere]
         end
 
-        model.id.match?(/gpt-5\.[4-9]|gpt-5\d/) ? protocols[:responses] : super
+        model.id.match?(/gpt-5\.[4-9]|gpt-5\d|gpt-[6-9]/) ? protocols[:responses] : super
       end
 
       def headers
@@ -108,7 +118,17 @@ module RubyLLM
         end
 
         def configuration_options
-          %i[azure_api_base azure_api_key azure_ai_auth_token]
+          %i[azure_api_base azure_api_key azure_ai_auth_token azure_deployments]
+        end
+
+        def deployed_model_id(deployment, config = RubyLLM.config)
+          deployments = config.azure_deployments || {}
+          unless deployments.is_a?(Hash)
+            raise ConfigurationError, 'azure_deployments must be a Hash of deployment names to model ids, ' \
+                                      "got #{deployments.class}"
+          end
+
+          (deployments[deployment.to_s] || deployments[deployment.to_sym])&.to_s
         end
 
         def configuration_requirements

data/lib/ruby_llm/providers/bedrock/auth.rb

@@ -79,7 +79,7 @@ module RubyLLM
           service = options.fetch(:service, 'bedrock')
           conn = Transport::Connection.basic(@config) do |f|
             f.request :json
-            f.response :json
+            f.use Transport::JsonResponse
             f.adapter :net_http
             f.use :llm_errors, provider: self
           end

data/lib/ruby_llm/providers/bedrock/mantle/anthropic.rb

@@ -29,7 +29,7 @@ module RubyLLM
             signed_post(count_tokens_url, payload)
           end
 
-          def mantle_headers(url, body)
+          def mantle_headers
             super.merge('anthropic-version' => ANTHROPIC_VERSION)
           end
         end

data/lib/ruby_llm/providers/bedrock/mantle/voxtral.rb

@@ -61,9 +61,7 @@ module RubyLLM
             raise ArgumentError, 'Transcription requires exactly one audio file' unless attachments.one?
 
             attachment = attachments.first
-            unless attachment.audio? && %w[mp3 wav].include?(attachment.format)
-              raise UnsupportedAttachmentError, attachment.mime_type
-            end
+            raise UnsupportedAttachmentError, attachment.mime_type unless attachment.audio?
 
             content = [
               Protocols::ChatCompletions::Media.format_audio(attachment),

data/lib/ruby_llm/providers/bedrock/mantle.rb

@@ -35,21 +35,17 @@ module RubyLLM
         end
 
         def signed_post(url, payload, additional_headers = {})
-          body = JSON.generate(payload)
-
-          @connection.post(url, payload, usage: @usage_tracker) do |req|
-            req.headers.merge!(mantle_headers(url, body))
-            req.headers.merge!(additional_headers) unless additional_headers.empty?
+          @connection.post(url, JSON.generate(payload), usage: @usage_tracker) do |req|
+            req.headers.merge!(mantle_headers.merge(additional_headers))
           end
         end
 
         def stream_response(payload, additional_headers = {}, &)
-          body = JSON.generate(payload)
-          super(payload, mantle_headers(stream_url, body).merge(additional_headers), &)
+          super(JSON.generate(payload), mantle_headers.merge(additional_headers), &)
         end
 
-        def mantle_headers(url, body)
-          @provider.sign_headers('POST', url, body, base_url: @provider.mantle_api_base, service: SIGNING_SERVICE)
+        def mantle_headers
+          {}
         end
       end
     end

data/lib/ruby_llm/providers/bedrock.rb

@@ -28,6 +28,20 @@ module RubyLLM
         Bedrock::Capabilities
       end
 
+      def self.between_tools_off?(model_id) # :nodoc:
+        Providers::Anthropic.between_tools_off?(Protocols::Converse::Chat.foundation_model_id(model_id))
+      end
+
+      def self.thinking_off_control(model_id) # :nodoc:
+        { enabled: false } if between_tools_off?(model_id)
+      end
+
+      def self.cache_write_input_multiplier(model_id, ttl) # :nodoc:
+        return unless Protocols::Converse::Chat.foundation_model_id(model_id).start_with?('anthropic.')
+
+        Providers::Anthropic.cache_write_input_multiplier(model_id, ttl)
+      end
+
       def self.resolve_registry_id(model_id, models, config = RubyLLM.config)
         Models.resolve_registry_id(model_id, models, config)
       end
@@ -36,6 +50,11 @@ module RubyLLM
         Models.models_dev_alias(...)
       end
 
+      def initialize(config) # :nodoc:
+        super
+        @connection = signed_connection(api_base)
+      end
+
       def protocol_for(model, operation: nil, **)
         return protocols[:guardrails] if operation == :moderate
 
@@ -62,13 +81,20 @@ module RubyLLM
       end
 
       def mantle_connection
-        @mantle_connection ||= Transport::Connection.new(self, @config, api_base: mantle_api_base)
+        @mantle_connection ||= signed_connection(mantle_api_base, service: Bedrock::Mantle::SIGNING_SERVICE)
       end
 
       def api_base
         @config.bedrock_api_base || "https://bedrock-runtime.#{bedrock_region}.amazonaws.com"
       end
 
+      # Uploads are objects in the configured bucket, readable with any
+      # credentials the bucket admits.
+      def account_identity
+        bucket = @config.bedrock_batch_s3_uri
+        account_digest(bucket) if bucket
+      end
+
       def control_api_base
         @config.bedrock_api_base || "https://bedrock.#{bedrock_region}.amazonaws.com"
       end
@@ -78,16 +104,12 @@ module RubyLLM
       end
 
       def agent_connection # :nodoc:
-        @agent_connection ||= Transport::Connection.new(self, @config, api_base: agent_api_base)
+        @agent_connection ||= signed_connection(agent_api_base)
       end
 
       def rerank_model_arn(model_id) # :nodoc:
         return model_id if model_id.start_with?('arn:')
 
-        unless %w[amazon.rerank-v1:0 cohere.rerank-v3-5:0].include?(model_id)
-          raise Error, "Bedrock reranking is not supported for #{model_id.inspect}"
-        end
-
         "arn:aws:bedrock:#{bedrock_region}::foundation-model/#{model_id}"
       end
 
@@ -190,6 +212,16 @@ module RubyLLM
 
       private
 
+      # Signs each attempt as it is sent, so a retry never replays a
+      # signature that expired while the previous attempt waited.
+      def signed_connection(base_url, service: 'bedrock')
+        signer = lambda do |env|
+          signed = sign_headers(env.method.to_s.upcase, env.url.request_uri, env.body.to_s, base_url:, service:)
+          { 'X-Amz-Security-Token' => nil }.merge(signed)
+        end
+        Transport::Connection.new(self, @config, api_base: base_url, signer:)
+      end
+
       def voxtral_transcription?(operation, model_id)
         operation == :transcribe && model_id == 'mistral.voxtral-small-24b-2507'
       end

data/lib/ruby_llm/providers/deepseek/chat.rb

@@ -57,12 +57,17 @@ module RubyLLM
           payload
         end
 
+        def supported_attachment?(attachment)
+          Protocols::ChatCompletions::Media.supported_attachment?(
+            attachment, document_attachments: :none, audio_attachments: false
+          )
+        end
+
         def format_content(content, attachments = [])
           Protocols::ChatCompletions::Media.format_content(
             content,
             attachments,
             document_attachments: :none,
-            image_attachments: false,
             audio_attachments: false
           )
         end

data/lib/ruby_llm/providers/deepseek/responses.rb

@@ -61,6 +61,12 @@ module RubyLLM
         def format_document(document)
           raise UnsupportedAttachmentError, document.mime_type
         end
+
+        def supported_attachment?(attachment)
+          return attachment.image? if attachment.provider_file?
+
+          %i[image text].include?(attachment.type)
+        end
       end
     end
   end

data/lib/ruby_llm/providers/deepseek.rb

@@ -23,6 +23,10 @@ module RubyLLM
         }
       end
 
+      def account_identity
+        account_digest(api_base, @config.deepseek_api_key)
+      end
+
       class << self
         def capabilities
           DeepSeek::Capabilities

data/lib/ruby_llm/providers/gemini.rb

@@ -26,6 +26,10 @@ module RubyLLM
         }
       end
 
+      def account_identity
+        account_digest(api_base, @config.gemini_api_key)
+      end
+
       def batch_cost_multiplier(component:, **)
         %i[cache_read cache_write].include?(component) ? 1 : 0.5
       end

data/lib/ruby_llm/providers/gpustack/media.rb

@@ -3,13 +3,18 @@
 module RubyLLM
   module Providers
     class GPUStack
-      # Handles formatting of media content for GPUStack. Images ride inline
-      # as base64 data URLs so the cluster never has to fetch remote sources.
+      # Formats media content for GPUStack chat completions.
       module Media
         module_function
 
+        def supported_attachment?(attachment)
+          %i[image audio video text].include?(attachment.type)
+        end
+
         def format_content(content, attachments = [])
           Protocols::ChatCompletions::Media.format_parts(content, attachments) do |attachment|
+            raise UnsupportedAttachmentError, attachment.mime_type unless supported_attachment?(attachment)
+
             case attachment.type
             when :image
               format_image(attachment)
@@ -19,8 +24,6 @@ module RubyLLM
               format_video(attachment)
             when :text
               Protocols::ChatCompletions::Media.format_text_file(attachment)
-            else
-              raise UnsupportedAttachmentError, attachment.mime_type
             end
           end
         end
@@ -38,7 +41,7 @@ module RubyLLM
         def format_video(video)
           {
             type: 'video_url',
-            video_url: { url: video.url? ? video.source.to_s : video.for_llm }
+            video_url: { url: video.for_llm }
           }
         end
       end

data/lib/ruby_llm/providers/hetzner/chat.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    class Hetzner
+      # Chat methods of the Hetzner Inference API integration
+      module Chat
+        module_function
+
+        def format_role(role)
+          role.to_s
+        end
+
+        def supported_attachment?(attachment)
+          Protocols::ChatCompletions::Media.supported_attachment?(
+            attachment, document_attachments: :none, audio_attachments: false
+          )
+        end
+
+        def format_content(content, attachments = [])
+          Protocols::ChatCompletions::Media.format_parts(content, attachments) do |attachment|
+            if attachment.type == :image && !attachment.provider_file?
+              format_inline_image(attachment)
+            else
+              Protocols::ChatCompletions::Media.format_attachment(
+                attachment, document_attachments: :none, image_attachments: true, audio_attachments: false
+              )
+            end
+          end
+        end
+
+        # Hetzner's servers can't fetch URLs, so remote images travel inline too.
+        def format_inline_image(image)
+          { type: 'image_url', image_url: { url: image.for_llm } }
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/providers/hetzner.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    # Hetzner Inference API integration.
+    class Hetzner < Provider
+      # Hetzner's dialect of the Chat Completions API.
+      class ChatCompletions < Protocols::ChatCompletions
+        include Hetzner::Chat
+      end
+
+      protocol :chat_completions, ChatCompletions
+
+      def api_base
+        @config.hetzner_api_base || 'https://inference.hetzner.com/api/v1'
+      end
+
+      def headers
+        { 'Authorization' => "Bearer #{@config.hetzner_api_key}" }
+      end
+
+      class << self
+        def configuration_options
+          %i[hetzner_api_key hetzner_api_base]
+        end
+
+        def configuration_requirements
+          %i[hetzner_api_key]
+        end
+
+        # Returns +true+: Hetzner Inference is experimental and changes its
+        # model selection faster than the registry tracks it, so model ids
+        # are accepted as given. Call RubyLLM.models.refresh to pull the
+        # live catalog.
+        def assume_models_exist?
+          true
+        end
+      end
+    end
+  end
+end