ruby_llm 2.1.1 → 2.2.0

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

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require 'base64'
+
+module RubyLLM
+  module Providers
+    class Bedrock
+      # The Anthropic Messages API on Bedrock's InvokeModel endpoints, which
+      # serve every Claude model and cross-region inference profile. Unlike
+      # Converse, it carries Anthropic's own features, such as tool search,
+      # so a prompt cache survives the tools a model loads on demand.
+      class Anthropic < Protocols::Anthropic
+        include Protocols::Bedrock::EventStream
+
+        ANTHROPIC_VERSION = 'bedrock-2023-05-31'
+        TOOL_SEARCH_BETA = 'tool-search-tool-2025-10-19'
+
+        def completion_url
+          model_path(@model.id, 'invoke')
+        end
+
+        def stream_url
+          model_path(@model.id, 'invoke-with-response-stream')
+        end
+
+        # Bedrock counts tokens for the foundation model, not for the
+        # inference profiles that serve it.
+        def count_tokens_url
+          model_path(Protocols::Converse::Chat.foundation_model_id(@model.id), 'count-tokens')
+        end
+
+        def render_payload(messages, **)
+          payload = super.except(:model, :stream)
+          payload[:messages] = inline_url_sources(payload[:messages])
+          payload[:system] = inline_url_sources(payload[:system]) if payload[:system]
+          payload.merge(anthropic_version: ANTHROPIC_VERSION)
+        end
+
+        def parse_count_tokens_response(response)
+          response.body['inputTokens']
+        end
+
+        # The body names the foundation model; pricing and the transcript
+        # follow the inference profile or ARN that was called.
+        def parse_response_model_id(data)
+          called_model_id(super)
+        end
+
+        def parse_model_id(data)
+          called_model_id(super)
+        end
+
+        def called_model_id(named)
+          named && (@model&.id || named)
+        end
+
+        def provider_file_references?
+          false
+        end
+
+        private
+
+        def sync_response(payload, additional_headers = {})
+          headers = beta_headers(additional_headers, payload)
+          response = @connection.post(completion_url, JSON.generate(render_invoke_body(payload, headers)),
+                                      usage: @usage_tracker) do |request|
+            request.headers.merge!(without_beta_header(headers))
+          end
+          parse_completion_response(response)
+        end
+
+        def stream_events(url, payload, additional_headers = {}, &)
+          body = JSON.generate(render_invoke_body(payload, additional_headers))
+          super(url, body, without_beta_header(additional_headers), &)
+        end
+
+        def post_count_tokens(payload)
+          body = payload.except(:model).merge(anthropic_version: ANTHROPIC_VERSION, max_tokens: 1)
+          body = JSON.generate(render_invoke_body(body, beta_headers({}, payload)))
+          request = { input: { invokeModel: { body: Base64.strict_encode64(body) } } }
+          @connection.post(count_tokens_url, JSON.generate(request))
+        end
+
+        # Bedrock still gates the tool search tool behind its beta.
+        def beta_headers(additional_headers, payload)
+          headers = super
+          tools = Array(payload[:tools] || payload['tools'])
+          tools.any? { |tool| search_tool?(tool) } ? add_beta(headers, TOOL_SEARCH_BETA) : headers
+        end
+
+        # InvokeModel takes Anthropic's betas in the body, not as a header.
+        def render_invoke_body(payload, headers)
+          betas = canonical_beta_headers(headers)[BETA_HEADER].to_s.split(',').map(&:strip).reject(&:empty?)
+          return payload if betas.empty?
+
+          payload.merge(anthropic_beta: (Array(payload[:anthropic_beta]) + betas).uniq)
+        end
+
+        def without_beta_header(headers)
+          canonical_beta_headers(headers).except(BETA_HEADER)
+        end
+
+        # Bedrock does not fetch URLs, so remote images and documents travel
+        # as their bytes.
+        def inline_url_sources(blocks)
+          return blocks unless blocks.is_a?(Array)
+
+          blocks.map do |block|
+            next block unless block.is_a?(Hash)
+            next inline_url_source(block) if url_source?(block)
+
+            block[:content].is_a?(Array) ? block.merge(content: inline_url_sources(block[:content])) : block
+          end
+        end
+
+        def url_source?(block)
+          source = block[:source]
+          source.is_a?(Hash) && source[:type] == 'url'
+        end
+
+        def inline_url_source(block)
+          attachment = Attachment.new(block.dig(:source, :url))
+          block.merge(source: { type: 'base64', media_type: attachment.mime_type, data: attachment.encoded })
+        end
+
+        # Application inference profile ARNs contain '/', which Bedrock
+        # expects escaped inside the model segment.
+        def model_path(model_id, action)
+          "/model/#{model_id.to_s.gsub('/', '%2F')}/#{action}"
+        end
+      end
+    end
+  end
+end

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

@@ -23,7 +23,7 @@ module RubyLLM
           payload_hash = Digest::SHA256.hexdigest(body)
 
           headers = {
-            'host' => URI.parse(base_url).host,
+            'host' => signed_host(base_url),
             'x-amz-content-sha256' => payload_hash,
             'x-amz-date' => amz_date
           }
@@ -85,12 +85,21 @@ module RubyLLM
           end
 
           conn.url_prefix = base_url
+          path = url.delete_prefix('/')
+          sent = conn.build_url(path).request_uri
 
-          conn.public_send(method, url, payload) do |req|
-            req.headers.merge!(sign_headers(method.to_s.upcase, url, body, base_url:, service:))
+          conn.public_send(method, path, payload) do |req|
+            req.headers.merge!(sign_headers(method.to_s.upcase, sent, body, base_url:, service:))
           end
         end
 
+        # HTTP clients send the port in the Host header unless it is the
+        # scheme's default.
+        def signed_host(base_url)
+          uri = URI.parse(base_url)
+          uri.port == uri.default_port ? uri.host : "#{uri.host}:#{uri.port}"
+        end
+
         def canonical_query_string(raw_query)
           return '' if raw_query.nil? || raw_query.empty?
 

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    class Bedrock
+      # Keeps Bedrock's API paths under the configured endpoint. Faraday
+      # resolves a leading slash against the host, which would drop the path of
+      # an endpoint mounted behind a gateway.
+      class Connection < Transport::Connection # :nodoc:
+        private
+
+        def prepare(request)
+          super
+          request.path = request.path.delete_prefix('/')
+        end
+      end
+    end
+  end
+end

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

@@ -19,7 +19,11 @@ module RubyLLM
             'anthropic/v1/messages/count_tokens'
           end
 
-          def supports_provider_file_references?
+          def thinking_block_binding?
+            false
+          end
+
+          def provider_file_references?
             false
           end
 

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

@@ -10,10 +10,10 @@ module RubyLLM
           include Mantle
 
           def completion_url
-            'v1/chat/completions'
+            "#{openai_api_path}/chat/completions"
           end
 
-          def supports_provider_file_references?
+          def provider_file_references?
             false
           end
         end

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

@@ -10,11 +10,21 @@ module RubyLLM
         class Responses < Protocols::Responses
           include Mantle
 
+          # AWS Web Search fetches pages as part of the web_search tool, with
+          # no separate fetch tool to enable.
+          SERVER_TOOL_ALIASES = Protocols::Responses::SERVER_TOOL_ALIASES.merge(
+            web_fetch: { tool: { type: 'web_search' } }
+          ).freeze
+
+          def server_tool_aliases
+            SERVER_TOOL_ALIASES
+          end
+
           def completion_url
-            'v1/responses'
+            "#{openai_api_path}/responses"
           end
 
-          def supports_provider_file_references?
+          def provider_file_references?
             false
           end
         end

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

@@ -64,7 +64,7 @@ module RubyLLM
             raise UnsupportedAttachmentError, attachment.mime_type unless attachment.audio?
 
             content = [
-              Protocols::ChatCompletions::Media.format_audio(attachment),
+              Protocols::ChatCompletions::Media.render_audio(attachment),
               { type: 'text', text: transcription_prompt(prompt, language) }
             ]
             payload = { model:, messages: [{ role: 'user', content: }], temperature: temperature || 0 }

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

@@ -30,6 +30,13 @@ module RubyLLM
 
         private
 
+        # OpenAI's GPT models answer only under /openai/v1, and every other
+        # model, gpt-oss included, only under /v1.
+        def openai_api_path
+          id = @model&.id.to_s
+          id.start_with?('openai.') && !id.start_with?('openai.gpt-oss') ? 'openai/v1' : 'v1'
+        end
+
         def sync_response(payload, additional_headers = {})
           parse_completion_response signed_post(completion_url, payload, additional_headers)
         end

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

@@ -25,7 +25,7 @@ module RubyLLM
         end
 
         def models_dev_alias(model_id, models_dev_by_key, _provider_model = nil)
-          normalized_id = model_id.sub(/^[a-z]{2}\./, '')
+          normalized_id = model_id.sub(/\A(?:#{Protocols::Converse::REGION_PREFIXES.join('|')})\./, '')
           context_override = nil
           normalized_id = normalized_id.gsub(/:(\d+)k\b/) do
             context_override = Regexp.last_match(1).to_i * 1000
@@ -209,12 +209,6 @@ module RubyLLM
           inference_types.include?('INFERENCE_PROFILE') && !inference_types.include?('ON_DEMAND')
         end
 
-        def normalize_inference_profile_id(model_id, inference_types, region)
-          return model_id unless inference_profile_only?(inference_types)
-
-          with_region_prefix(model_id, region)
-        end
-
         def with_region_prefix(model_id, region)
           prefixed_with(model_id, region_prefix(region))
         end

data/lib/ruby_llm/providers/bedrock.rb

@@ -8,6 +8,7 @@ module RubyLLM
       include Bedrock::Models
 
       protocol :converse, Protocols::Converse, batches: Protocols::Converse::Batches
+      protocol :anthropic, Bedrock::Anthropic, batches: Bedrock::Anthropic::Batches
       protocol :mantle_anthropic, Bedrock::Mantle::Anthropic
       protocol :mantle_responses, Bedrock::Mantle::Responses
       protocol :mantle_chat_completions, Bedrock::Mantle::ChatCompletions
@@ -50,6 +51,14 @@ module RubyLLM
         Models.models_dev_alias(...)
       end
 
+      def self.open_telemetry_name # :nodoc:
+        'aws.bedrock'
+      end
+
+      def self.models_dev_provider_ids # :nodoc:
+        %w[amazon-bedrock]
+      end
+
       def initialize(config) # :nodoc:
         super
         @connection = signed_connection(api_base)
@@ -64,9 +73,14 @@ module RubyLLM
         return protocols[:rerank] if operation == :rerank
         return video_protocol_for(model_id) if operation == :animate
         return protocols[:voxtral_transcription] if voxtral_transcription?(operation, model_id)
-        return mantle_protocol_for(model_id) if mantle_model?(model_id)
 
-        super
+        chat_protocol_for(model_id) || super
+      end
+
+      # Claude speaks the Anthropic Messages API through InvokeModel, which
+      # keeps features Converse drops, such as tool search.
+      def claude_model?(model_id) # :nodoc:
+        Protocols::Converse::Chat.foundation_model_id(model_id).start_with?('anthropic.claude')
       end
 
       # Un-versioned ids such as anthropic.claude-sonnet-5 and
@@ -77,7 +91,8 @@ module RubyLLM
       end
 
       def mantle_api_base
-        @config.bedrock_mantle_api_base || "https://bedrock-mantle.#{bedrock_region}.api.aws"
+        configured_api_base(:bedrock_mantle_api_base, "https://bedrock-mantle.#{bedrock_region}.api.aws",
+                            endpoints: %r{/(?:chat/completions|responses|messages)\z})
       end
 
       def mantle_connection
@@ -85,7 +100,8 @@ module RubyLLM
       end
 
       def api_base
-        @config.bedrock_api_base || "https://bedrock-runtime.#{bedrock_region}.amazonaws.com"
+        configured_api_base(:bedrock_api_base, "https://bedrock-runtime.#{bedrock_region}.amazonaws.com",
+                            endpoints: %r{/model/.*\z})
       end
 
       # Uploads are objects in the configured bucket, readable with any
@@ -96,11 +112,13 @@ module RubyLLM
       end
 
       def control_api_base
-        @config.bedrock_api_base || "https://bedrock.#{bedrock_region}.amazonaws.com"
+        configured_api_base(:bedrock_api_base, "https://bedrock.#{bedrock_region}.amazonaws.com",
+                            endpoints: %r{/model/.*\z})
       end
 
       def agent_api_base # :nodoc:
-        @config.bedrock_api_base || "https://bedrock-agent-runtime.#{bedrock_region}.amazonaws.com"
+        configured_api_base(:bedrock_api_base, "https://bedrock-agent-runtime.#{bedrock_region}.amazonaws.com",
+                            endpoints: %r{/model/.*\z})
       end
 
       def agent_connection # :nodoc:
@@ -131,6 +149,10 @@ module RubyLLM
 
       def batch_cost_multiplier(**) = 0.5
 
+      def invoke_model_batch_protocol(model_id) # :nodoc:
+        claude_model?(model_id) ? protocols[:anthropic] : embedding_batch_protocol(model_id)
+      end
+
       def embedding_batch_protocol(model_id) # :nodoc:
         case model_id
         when 'amazon.titan-embed-text-v2:0' then protocols[:titan_text_embeddings]
@@ -146,6 +168,13 @@ module RubyLLM
         body['message'] || body['Message'] || nested_error_message(body) || body['__type'] || super
       end
 
+      def parse_error_code(response)
+        type = response.headers['x-amzn-errortype'] if response.respond_to?(:headers) && response.headers
+        type ||= parse_error_body(response).then { |body| body['__type'] if body.is_a?(Hash) }
+        code = type.to_s.split(':').first.to_s.split('#').last
+        code&.match?(Error::ERROR_CODE) ? code : super
+      end
+
       # bedrock-mantle nests code, message, and type under "error" rather
       # than answering with a bare string.
       def nested_error_message(body)
@@ -219,7 +248,7 @@ module RubyLLM
           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:)
+        Connection.new(self, @config, api_base: base_url, signer:)
       end
 
       def voxtral_transcription?(operation, model_id)
@@ -227,8 +256,12 @@ module RubyLLM
       end
 
       def batch_protocol_for(requests)
-        return super unless requests.any? { |request| request.key?(:text) }
+        return embedding_batch_protocol_for(requests) if requests.any? { |request| request.key?(:text) }
 
+        requests.all? { |request| anthropic_payload?(request[:payload]) } ? protocols[:anthropic] : super
+      end
+
+      def embedding_batch_protocol_for(requests)
         kinds = requests.map { |request| embedding_batch_protocol(request.fetch(:model)) }.uniq
         unless requests.all? { |request| request.key?(:text) } && kinds.one? && kinds.first
           raise Error, 'Bedrock embedding batches require one supported Titan embedding model'
@@ -237,6 +270,10 @@ module RubyLLM
         kinds.first
       end
 
+      def anthropic_payload?(payload)
+        payload.is_a?(Hash) && (payload.key?(:anthropic_version) || payload.key?('anthropic_version'))
+      end
+
       def bedrock_region
         @config.bedrock_region
       end
@@ -258,6 +295,12 @@ module RubyLLM
         parse_mantle_models_response(response, slug)
       end
 
+      def chat_protocol_for(model_id)
+        return mantle_protocol_for(model_id) if mantle_model?(model_id)
+
+        protocols[:anthropic] if claude_model?(model_id)
+      end
+
       def mantle_protocol_for(model_id)
         return protocols[:mantle_anthropic] if model_id.start_with?('anthropic.')
         return protocols[:mantle_responses] if Bedrock::Mantle::RESPONSES_MODELS.include?(model_id)

data/lib/ruby_llm/providers/cohere.rb

@@ -8,7 +8,7 @@ module RubyLLM
       protocol :files, Protocols::Cohere::Datasets
 
       def api_base
-        @config.cohere_api_base || 'https://api.cohere.com'
+        configured_api_base(:cohere_api_base, 'https://api.cohere.com', endpoints: %r{/v2/(?:chat|embed|rerank)\z})
       end
 
       def headers
@@ -18,6 +18,10 @@ module RubyLLM
       end
 
       class << self
+        def models_dev_provider_ids # :nodoc:
+          %w[cohere]
+        end
+
         def configuration_options
           %i[cohere_api_key cohere_api_base]
         end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    class Deepgram
+      # Deepgram's dialect of Chat Completions on POST /v1/think. It takes
+      # the full history on each request and rejects any field it does not
+      # list, including the prompt cache fields.
+      module Chat
+        def completion_url
+          @provider.think_url
+        end
+
+        # Think-Fast rejects the developer role.
+        def render_role(role)
+          role.to_s
+        end
+
+        def openai_prompt_caching?
+          false
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/providers/deepgram.rb

@@ -2,12 +2,31 @@
 
 module RubyLLM
   module Providers
-    # Integrates Deepgram transcription and speech synthesis.
+    # Integrates Deepgram transcription, speech synthesis, and chat.
     class Deepgram < Provider
+      # Deepgram's dialect of the Chat Completions API.
+      class ChatCompletions < Protocols::ChatCompletions
+        include Deepgram::Chat
+      end
+
+      THINK_BASE = 'https://agent.deepgram.com'
+      private_constant :THINK_BASE
+
       protocol :deepgram, Protocols::Deepgram
+      protocol :chat_completions, ChatCompletions
 
       def api_base
-        @config.deepgram_api_base || 'https://api.deepgram.com'
+        configured_api_base(:deepgram_api_base, 'https://api.deepgram.com', endpoints: %r{/v1/(?:listen|speak|think)\z})
+      end
+
+      # Chat runs on its own host. Speech, transcription, and the model
+      # listing stay on the Deepgram protocol.
+      def protocol_for(model, operation: nil, **)
+        operation ? super : protocols[:chat_completions]
+      end
+
+      def think_url # :nodoc:
+        "#{(@config.deepgram_api_base || THINK_BASE).chomp('/')}/v1/think"
       end
 
       def headers

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

@@ -7,15 +7,16 @@ module RubyLLM
       module Chat
         module_function
 
-        def format_role(role)
+        def render_role(role)
           role.to_s
         end
 
         def render_payload(messages, tools:, temperature:, model:, stream: false, max_output_tokens: nil,
                            schema: nil, thinking: nil, citations: false, caching: nil, tool_prefs: nil)
+          raise ArgumentError, 'DeepSeek Chat Completions cannot enforce a schema. Use protocol: :responses.' if schema
+
           payload = super
           configure_thinking_payload(payload, thinking)
-          degrade_schema_payload(payload) if schema
           payload
         end
 
@@ -26,9 +27,7 @@ module RubyLLM
         def configure_thinking_payload(payload, thinking)
           return unless thinking&.enabled?
 
-          if thinking.budget
-            RubyLLM.logger.debug { "DeepSeek has no thinking budgets; ignoring budget #{thinking.budget}" }
-          end
+          raise ArgumentError, 'DeepSeek has no thinking budget; use effort:' if thinking.budget
 
           if thinking.disabled?
             payload.delete(:reasoning_effort)
@@ -38,15 +37,7 @@ module RubyLLM
           end
         end
 
-        def degrade_schema_payload(payload)
-          RubyLLM.logger.warn(
-            'DeepSeek Chat Completions does not support json_schema response formats. ' \
-            'Use protocol: :responses to enforce the schema. Falling back to json_object mode.'
-          )
-          payload[:response_format] = { type: 'json_object' }
-        end
-
-        def format_thinking(msg)
+        def render_thinking(msg)
           return {} unless msg.role == :assistant
 
           thinking = msg.thinking
@@ -63,8 +54,8 @@ module RubyLLM
           )
         end
 
-        def format_content(content, attachments = [])
-          Protocols::ChatCompletions::Media.format_content(
+        def render_content(content, attachments = [])
+          Protocols::ChatCompletions::Media.render_content(
             content,
             attachments,
             document_attachments: :none,

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

@@ -8,6 +8,7 @@ module RubyLLM
       # instead of summaries, both in responses and in the stream.
       class Responses < Protocols::Responses
         SERVER_TOOL_ALIASES = {
+          web_search: { tool: { type: 'web_search' } },
           apply_patch: { tool: { type: 'custom', name: 'apply_patch' } }
         }.freeze
 
@@ -15,6 +16,22 @@ module RubyLLM
           SERVER_TOOL_ALIASES
         end
 
+        def render_payload(messages, thinking: nil, **)
+          raise ArgumentError, 'DeepSeek has no thinking budget; use effort:' if thinking&.budget
+
+          super
+        end
+
+        SERVER_TOOL_USAGE_NAMES = { 'tool_search' => 'web_search', 'tool_fetch' => 'web_fetch' }.freeze
+
+        # DeepSeek counts searches and page opens in usage, unlike tool_usage
+        # on the other Responses APIs.
+        def parse_server_tool_use(response)
+          response.dig('usage', 'server_tool_use').to_h.transform_keys do |tool|
+            "#{SERVER_TOOL_USAGE_NAMES.fetch(tool, tool)}_requests"
+          end
+        end
+
         def apply_end_user(payload, identifier)
           payload.merge(user_id: identifier)
         end
@@ -33,32 +50,32 @@ module RubyLLM
           texts.empty? ? super : texts.join("\n")
         end
 
-        def format_assistant_items(message)
+        def render_assistant_items(message)
           items = super
           return items if message.raw_content || message.thinking&.text.to_s.empty? || message.thinking.signature
 
-          items.unshift(format_reasoning_item(message.thinking))
+          items.unshift(render_reasoning_item(message.thinking))
         end
 
-        def format_reasoning_item(thinking)
+        def render_reasoning_item(thinking)
           { type: 'reasoning', content: [{ type: 'reasoning_text', text: thinking.text }] }
         end
 
-        def format_tool_items(message)
+        def render_tool_items(message)
           [{
             type: 'function_call_output',
-            call_id: message.tool_call_id,
-            output: format_content(message.content, message.attachments)
+            call_id: message.provider_call_id,
+            output: render_content(message.content, message.attachments)
           }]
         end
 
-        def format_provider_file(file)
+        def render_provider_file(file)
           raise UnsupportedAttachmentError, file.mime_type unless file.image?
 
           { type: 'input_image', file_id: file.provider_file_id }
         end
 
-        def format_document(document)
+        def render_document(document)
           raise UnsupportedAttachmentError, document.mime_type
         end
 

data/lib/ruby_llm/providers/deepseek.rb

@@ -14,7 +14,7 @@ module RubyLLM
       protocol :files, Protocols::DeepSeek::Files
 
       def api_base
-        @config.deepseek_api_base || 'https://api.deepseek.com'
+        configured_api_base(:deepseek_api_base, 'https://api.deepseek.com', endpoints: Protocols::ChatCompletions::ENDPOINT_PATHS)
       end
 
       def headers
@@ -28,6 +28,10 @@ module RubyLLM
       end
 
       class << self
+        def models_dev_provider_ids # :nodoc:
+          %w[deepseek]
+        end
+
         def capabilities
           DeepSeek::Capabilities
         end

data/lib/ruby_llm/providers/elevenlabs.rb

@@ -14,7 +14,8 @@ module RubyLLM
       end
 
       def api_base
-        @config.elevenlabs_api_base || 'https://api.elevenlabs.io'
+        configured_api_base(:elevenlabs_api_base, 'https://api.elevenlabs.io',
+                            endpoints: %r{/v1/(?:speech-to-text\z|text-to-speech/.*\z)})
       end
 
       def headers