ruby_llm 2.0.0 → 2.1.0

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

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Protocols
+    class Anthropic
+      # Describes Messages API requests, and the token counting requests
+      # that share their shape, as RequestShape objects. Claude pairs tool
+      # results with calls by id and takes a thinking block back only with
+      # its signature.
+      module RequestShapes
+        MEDIA_KINDS = { 'image' => :image, 'document' => :document }.freeze
+        THINKING_SETTINGS = %w[type budget_tokens display].freeze
+
+        def parse_request_shape(payload)
+          messages = payload['messages']
+          return unless messages.is_a?(Array)
+
+          turns = messages.each_with_index.map { |message, index| shape_anthropic_turn(shape_hash(message), index) }
+          shape_request(turns, payload:, rules: %i[signed_thinking],
+                               instructions: shape_anthropic_content(payload['system']),
+                               tool_names: shape_list(payload['tools']).map { |tool| shape_tool_name(tool) },
+                               thinking_settings: shape_anthropic_thinking(payload))
+        end
+
+        private
+
+        def shape_anthropic_thinking(payload)
+          effort = shape_settings(payload['output_config'], 'effort')
+          shape_settings(payload['thinking'], *THINKING_SETTINGS).merge(effort)
+        end
+
+        def shape_anthropic_turn(message, index)
+          parts = shape_anthropic_content(message['content'])
+          shape_turn(index, message['role'], message['role'] == 'assistant' ? :model : shape_answer(parts), parts)
+        end
+
+        def shape_anthropic_content(content)
+          return [shape_text(content)] if content.is_a?(String)
+
+          shape_list(content).flat_map { |block| shape_anthropic_block(shape_hash(block)) }
+        end
+
+        def shape_anthropic_block(block)
+          case block['type']
+          when 'text' then shape_text(block['text'])
+          when 'thinking' then shape_text(block['thinking'], kind: :thinking,
+                                                             signed: shape_signature?(block['signature']))
+          when 'redacted_thinking' then shape_text(nil, kind: :thinking, signed: shape_signature?(block['data']))
+          when 'tool_use' then shape_tool_call(block['name'], block['input'], id: block['id'])
+          when 'tool_result'
+            shape_tool_result(block['content'], id: block['tool_use_id']) { |inner| shape_anthropic_block(inner) }
+          when *MEDIA_KINDS.keys then shape_anthropic_source(MEDIA_KINDS[block['type']], shape_hash(block['source']))
+          else shape_other(block['type'])
+          end
+        end
+
+        def shape_anthropic_source(kind, source)
+          case source['type']
+          when 'base64' then shape_inline(source['data'], kind:, mime_type: source['media_type'])
+          when 'text' then shape_media(kind, source: :inline, size: shape_length(source['data']),
+                                             mime_type: source['media_type'])
+          when 'url' then shape_media(kind, source: :url)
+          when 'file' then shape_file(kind:)
+          else shape_media(kind, source: :inline, size: shape_length(source['content']))
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -7,6 +7,19 @@ module RubyLLM
     class Anthropic
       # Streaming methods of the Anthropic API integration
       module Streaming
+        ERROR_STATUSES = {
+          'invalid_request_error' => 400,
+          'authentication_error' => 401,
+          'billing_error' => 402,
+          'permission_error' => 403,
+          'not_found_error' => 404,
+          'request_too_large' => 413,
+          'rate_limit_error' => 429,
+          'api_error' => 500,
+          'timeout_error' => 504,
+          'overloaded_error' => 529
+        }.freeze
+
         private
 
         def stream_response(payload, additional_headers = {}, &)
@@ -37,6 +50,7 @@ module RubyLLM
             thinking_tokens: extract_thinking_tokens(data),
             cache_read_tokens: extract_cache_read_tokens(data),
             cache_write_tokens: extract_cache_write_tokens(data),
+            cache_write_tokens_by_ttl: extract_cache_write_by_ttl(data),
             server_tool_use: extract_server_tool_use(data),
             tool_calls: extract_tool_calls(data),
             finish_reason: normalize_finish_reason(data.dig('delta', 'stop_reason')),
@@ -84,15 +98,20 @@ module RubyLLM
           return unless block
 
           case delta_type
-          when 'text_delta' then block['text'] = block['text'].to_s + data.dig('delta', 'text').to_s
-          when 'thinking_delta' then block['thinking'] = block['thinking'].to_s + data.dig('delta', 'thinking').to_s
+          when 'text_delta' then append_stream_text(block, 'text', data.dig('delta', 'text'))
+          when 'thinking_delta' then append_stream_text(block, 'thinking', data.dig('delta', 'thinking'))
           when 'signature_delta' then block['signature'] = data.dig('delta', 'signature')
           when 'input_json_delta' then @stream_block_json&.dig(data['index'])&.<< data.dig('delta', 'partial_json').to_s
           when 'citations_delta' then (block['citations'] ||= []) << data.dig('delta', 'citation')
-          when 'compaction_delta' then block['content'] = block['content'].to_s + data.dig('delta', 'content').to_s
+          when 'compaction_delta' then append_stream_text(block, 'content', data.dig('delta', 'content'))
           end
         end
 
+        def append_stream_text(block, key, text)
+          block[key] = +block[key].to_s
+          block[key] << text.to_s
+        end
+
         def finalize_stream_block(index)
           json = @stream_block_json&.dig(index)
           block = @stream_blocks&.dig(index)
@@ -154,12 +173,7 @@ module RubyLLM
           error = error_data['error']
           return [500, error.to_s] unless error.is_a?(Hash)
 
-          case error['type']
-          when 'overloaded_error'
-            [529, error['message']]
-          else
-            [500, error['message']]
-          end
+          [ERROR_STATUSES.fetch(error['type'], 500), error['message']]
         end
       end
     end

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

@@ -7,10 +7,21 @@ module RubyLLM
       module Tools
         module_function
 
+        NATIVE_TOOL_SEARCH = {
+          type: 'tool_search_tool_bm25_20251119',
+          name: 'tool_search_tool_bm25'
+        }.freeze
+
         def find_tool_uses(blocks)
           blocks.select { |c| c['type'] == 'tool_use' }
         end
 
+        def tool_search_block?(block)
+          return true if block['type'] == 'tool_search_tool_result'
+
+          block['type'] == 'server_tool_use' && block['name'].to_s.start_with?('tool_search_tool_')
+        end
+
         def format_tool_result(msg)
           {
             role: 'user',
@@ -56,12 +67,44 @@ module RubyLLM
             description: tool.description,
             input_schema: input_schema || default_input_schema
           }
+          declaration[:defer_loading] = true if deferred?(tool)
 
           return declaration if tool.provider_options.empty?
 
           RubyLLM::Support::Utils.deep_merge(declaration, tool.provider_options)
         end
 
+        def deferred?(tool)
+          tool.is_a?(RubyLLM::Tool::Deferred)
+        end
+
+        # The API requires a search tool next to deferred tools, and rejects
+        # search blocks in the history of a request that declares none.
+        def apply_tool_search(payload)
+          tools = Array(payload[:tools])
+          return payload if tools.any? { |tool| search_tool?(tool) }
+          return payload.merge(tools: tools + [NATIVE_TOOL_SEARCH.dup]) if defers_loading?(tools)
+
+          payload.merge(messages: without_tool_search_blocks(payload[:messages]))
+        end
+
+        def defers_loading?(tools)
+          tools.any? { |tool| tool[:defer_loading] || tool['defer_loading'] }
+        end
+
+        def search_tool?(tool)
+          (tool[:type] || tool['type']).to_s.start_with?('tool_search_tool_')
+        end
+
+        def without_tool_search_blocks(messages)
+          messages.filter_map do |message|
+            next message unless message[:content].is_a?(Array)
+
+            content = message[:content].reject { |block| tool_search_block?(block) }
+            message.merge(content:) unless content.empty?
+          end
+        end
+
         def extract_tool_calls(data)
           if json_delta?(data)
             extract_tool_call_delta(data)

data/lib/ruby_llm/protocols/anthropic.rb

@@ -8,6 +8,7 @@ module RubyLLM
       include Anthropic::Embeddings
       include Anthropic::Media
       include Anthropic::Models
+      include Anthropic::RequestShapes
       include Anthropic::Streaming
       include Anthropic::Tools
 
@@ -15,6 +16,8 @@ module RubyLLM
       # continued before RubyLLM returns what it has.
       MAX_PAUSE_TURN_CONTINUATIONS = 8
 
+      DEFAULT_MAX_OUTPUT_TOKENS = 4096
+
       # web_search/web_fetch pin allowed_callers to direct invocation: their
       # 2026 tool versions otherwise default to requiring programmatic tool
       # calling, which not every model supports.
@@ -28,13 +31,29 @@ module RubyLLM
           name = options[:name] || 'mcp'
           server = { type: 'url', name: name }.merge(options.slice(:url, :authorization_token))
           {
-            tool: { type: 'mcp_toolset', mcp_server_name: name }.merge(options.slice(:default_config, :configs)),
+            tool: { type: 'mcp_toolset', mcp_server_name: name }
+              .merge(Anthropic.mcp_tool_filter(options))
+              .merge(options.slice(:default_config, :configs)),
             payload: { mcp_servers: [server] },
             headers: { 'anthropic-beta' => 'mcp-client-2025-11-20' }
           }
         end
       }.freeze
 
+      def self.mcp_tool_filter(options) # :nodoc:
+        approval = options[:require_approval]
+        unless approval.nil? || approval.to_s == 'never'
+          raise ArgumentError, "Anthropic runs MCP tools without approval; use require_approval: 'never'"
+        end
+
+        tools = options[:allowed_tools]
+        tools = tools[:tool_names] if tools.is_a?(Hash) && tools.keys == [:tool_names]
+        return {} if tools.nil?
+        raise ArgumentError, 'Anthropic filters MCP tools by name; use allowed_tools: [name]' unless tools.is_a?(Array)
+
+        { default_config: { enabled: false }, configs: tools.to_h { |tool| [tool.to_sym, { enabled: true }] } }
+      end
+
       def server_tool_aliases
         SERVER_TOOL_ALIASES
       end

data/lib/ruby_llm/protocols/bedrock/async_videos.rb

@@ -5,18 +5,12 @@ module RubyLLM
     module Bedrock
       # Luma Ray 2 video generation through Bedrock asynchronous invocation.
       class AsyncVideos < Protocol
-        IMAGE_TYPES = %w[image/png image/jpeg].freeze
-
         def video_url
           '/async-invoke'
         end
 
         def render_video_payload(prompt, model:, with: [], provider_options: {})
           output_uri = video_output_uri
-          unless prompt.is_a?(String) && (1..5000).cover?(prompt.length)
-            raise ArgumentError, 'Luma Ray 2 requires a prompt between 1 and 5000 characters'
-          end
-
           options = Support::Utils.deep_symbolize_keys(provider_options)
           outer = options.slice(:clientRequestToken, :tags)
           input = { prompt: prompt }.merge(render_keyframes(with)).merge(options.except(*outer.keys))
@@ -25,16 +19,18 @@ module RubyLLM
         end
 
         def post_video(url, payload)
-          @connection.post(url, payload, idempotent: false) do |request|
-            request.headers.merge!(@provider.sign_headers('POST', url, JSON.generate(payload)))
-          end
+          @connection.post(url, JSON.generate(payload), idempotent: false)
         end
 
-        def parse_video_job(response, model:)
+        def parse_video_job(response, model:, **request)
           id = response.body['invocationArn']
           raise Error.new('Bedrock did not return a video invocation ARN', 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)
+          super(request[:modelInput])
         end
 
         def video_job_url(job)
@@ -42,11 +38,7 @@ module RubyLLM
         end
 
         def refresh_video_job(job)
-          url = video_job_url(job)
-          response = @connection.get(url) do |request|
-            request.headers.merge!(@provider.sign_headers('GET', url, ''))
-          end
-          parse_video_job_status(response, job:)
+          parse_video_job_status(@connection.get(video_job_url(job)), job:)
         end
 
         def parse_video_job_status(response, **)
@@ -91,7 +83,7 @@ module RubyLLM
               raise ArgumentError, 'Luma Ray 2 requires image bytes or URLs, not uploaded file ids'
             end
 
-            raise UnsupportedAttachmentError, attachment.mime_type unless IMAGE_TYPES.include?(attachment.mime_type)
+            raise UnsupportedAttachmentError, attachment.mime_type unless attachment.image?
           end
         end
 

data/lib/ruby_llm/protocols/bedrock/guardrails.rb

@@ -14,9 +14,8 @@ module RubyLLM
         }.freeze
         private_constant :POLICY_FILTERS
 
-        IMAGE_TYPES = %w[image/png image/jpeg].freeze
         INTERVENTIONS = %w[BLOCKED ANONYMIZED].freeze
-        private_constant :IMAGE_TYPES, :INTERVENTIONS
+        private_constant :INTERVENTIONS
 
         def moderate(input, model:, with: [], provider_options: {})
           raise ArgumentError, 'Bedrock guardrails do not accept a model' unless model.nil?
@@ -27,7 +26,7 @@ module RubyLLM
           payloads = (input.is_a?(Array) ? input : [input]).map do |text|
             render_moderation_payload(text, attachments, provider_options)
           end
-          track_usage(:moderation) do
+          track_usage(:moderation, model_id: guardrail_model_id) do
             responses = payloads.map do |payload|
               response = post_moderation(url, payload)
               result = parse_moderation_result(response)
@@ -40,6 +39,10 @@ module RubyLLM
 
         private
 
+        def guardrail_model_id
+          "#{@config.bedrock_guardrail_id}:#{@config.bedrock_guardrail_version}"
+        end
+
         def parse_moderation_responses(responses)
           RubyLLM::Moderation.new(
             id: responses.one? ? responses.first.first.headers['x-amzn-requestid'] : nil,
@@ -59,9 +62,7 @@ module RubyLLM
           raise ArgumentError, 'Bedrock moderation requires text or an image' if input.nil? && attachments.empty?
 
           attachments.each do |attachment|
-            next if IMAGE_TYPES.include?(attachment.mime_type)
-
-            raise UnsupportedAttachmentError, attachment.mime_type
+            raise UnsupportedAttachmentError, attachment.mime_type unless attachment.image?
           end
         end
 
@@ -88,9 +89,7 @@ module RubyLLM
         end
 
         def post_moderation(url, payload)
-          @connection.post(url, payload, usage: @usage_tracker) do |request|
-            request.headers.merge!(@provider.sign_headers('POST', url, JSON.generate(payload)))
-          end
+          @connection.post(url, JSON.generate(payload), usage: @usage_tracker)
         end
 
         def parse_moderation_result(response)

data/lib/ruby_llm/protocols/bedrock/rerank.rb

@@ -16,7 +16,6 @@ module RubyLLM
         private
 
         def render_rerank_payload(query, documents, model:, top_n:, provider_options:)
-          validate_rerank_input(query, documents, top_n)
           payload = {
             queries: [{ type: 'TEXT', textQuery: { text: query } }],
             sources: documents.map { |document| render_rerank_source(document) },
@@ -31,18 +30,6 @@ module RubyLLM
           Support::Utils.deep_merge(payload, provider_options)
         end
 
-        def validate_rerank_input(query, documents, top_n)
-          unless query.is_a?(String) && !query.empty?
-            raise ArgumentError, 'Bedrock reranking requires one nonempty text query'
-          end
-          unless documents.is_a?(Array) && (1..1000).cover?(documents.length)
-            raise ArgumentError, 'Bedrock reranking accepts between 1 and 1000 documents'
-          end
-          return if top_n.nil? || (top_n.is_a?(Integer) && (1..1000).cover?(top_n))
-
-          raise ArgumentError, 'Bedrock reranking top_n must be between 1 and 1000'
-        end
-
         def render_rerank_source(document)
           content = case document
                     when String then { type: 'TEXT', textDocument: { text: document } }
@@ -70,10 +57,7 @@ module RubyLLM
         end
 
         def post_rerank(payload)
-          @provider.agent_connection.post('/rerank', payload, usage: @usage_tracker) do |request|
-            request.headers.merge!(@provider.sign_headers('POST', '/rerank', JSON.generate(payload),
-                                                          base_url: @provider.agent_api_base))
-          end
+          @provider.agent_connection.post('/rerank', JSON.generate(payload), usage: @usage_tracker)
         end
 
         def parse_rerank_pages(pages, model:, documents:)

data/lib/ruby_llm/protocols/chat_completions/chat.rb

@@ -11,7 +11,6 @@ module RubyLLM
         }.freeze
 
         OPENAI_INLINE_FILE_LIMIT = 50 * 1024 * 1024
-        OPENAI_FILE_UPLOAD_LIMIT = 512 * 1024 * 1024
         PROMPT_CACHE_OPTIONS = %i[key ttl mode retention].freeze
 
         def completion_url
@@ -106,7 +105,7 @@ module RubyLLM
         end
 
         def parse_completion_body(data, raw:)
-          raise Error.new(data.dig('error', 'message'), response: raw) if data.dig('error', 'message')
+          raise_stream_error(JSON.generate(data), data, nil) if data.dig('error', 'message')
 
           message_data = data.dig('choices', 0, 'message')
           raise no_completion_message_error(data, raw) unless message_data
@@ -143,8 +142,11 @@ module RubyLLM
           nil
         end
 
+        # Per-tool counters end in _requests; OpenRouter's tool_calls_requested
+        # and tool_calls_executed count every tool at once.
         def server_tool_use(usage)
-          usage['server_tool_use'] || usage['server_tool_use_details']
+          counters = usage['server_tool_use'] || usage['server_tool_use_details']
+          counters.to_h.select { |counter, _| counter.end_with?('_requests') }
         end
 
         def no_completion_message_error(data, raw)
@@ -404,10 +406,6 @@ module RubyLLM
           OPENAI_INLINE_FILE_LIMIT
         end
 
-        def provider_file_upload_limit
-          OPENAI_FILE_UPLOAD_LIMIT
-        end
-
         def provider_file_attachable?(attachment)
           attachment.pdf?
         end

data/lib/ruby_llm/protocols/chat_completions/media.rb

@@ -7,6 +7,20 @@ module RubyLLM
       module Media
         module_function
 
+        def supported_attachment?(attachment, document_attachments: :pdf, image_attachments: true,
+                                  audio_attachments: true)
+          return document_attachments != :none if attachment.provider_file?
+
+          case attachment.type
+          when :image then image_attachments
+          when :audio then audio_attachments
+          when :text then true
+          when :pdf, :document
+            document_attachments == :all || (document_attachments == :pdf && attachment.pdf?)
+          else false
+          end
+        end
+
         def format_content(content, attachments = [], document_attachments: :pdf, image_attachments: true,
                            audio_attachments: true)
           format_parts(content, attachments) do |attachment|
@@ -35,23 +49,21 @@ module RubyLLM
         end
 
         def format_attachment(attachment, document_attachments:, image_attachments:, audio_attachments:)
+          unless supported_attachment?(attachment, document_attachments:, image_attachments:, audio_attachments:)
+            raise UnsupportedAttachmentError, attachment.mime_type
+          end
+
           return format_provider_file(attachment, document_attachments:) if attachment.provider_file?
 
           case attachment.type
           when :image
-            raise UnsupportedAttachmentError, attachment.mime_type unless image_attachments
-
-            format_image(attachment)
+            with_image_detail(format_image(attachment), attachment)
           when :audio
-            raise UnsupportedAttachmentError, attachment.mime_type unless audio_attachments
-
             format_audio(attachment)
           when :pdf, :document
             format_document_attachment(attachment, document_attachments)
           when :text
             format_text_file(attachment)
-          else
-            raise UnsupportedAttachmentError, attachment.mime_type
           end
         end
 
@@ -59,11 +71,25 @@ module RubyLLM
           {
             type: 'image_url',
             image_url: {
-              url: image.url? ? image.source.to_s : image.for_llm
+              url: image.url_or_data_uri
             }
           }
         end
 
+        def with_image_detail(part, image, original_detail: @provider&.original_image_detail?)
+          return part unless image.resolution
+
+          part[:image_url][:detail] = image_detail(image.resolution, original_detail:)
+          part
+        end
+
+        def image_detail(resolution, original_detail: false)
+          return 'low' if resolution == :low
+          return 'original' if resolution == :original && original_detail
+
+          'high'
+        end
+
         def format_document(document)
           {
             type: 'file',

data/lib/ruby_llm/protocols/chat_completions/request_shapes.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Protocols
+    class ChatCompletions
+      # Describes Chat Completions requests as RequestShape objects. Cohere
+      # v2 sends messages in the same shape. Tool messages answer calls by id.
+      module RequestShapes
+        SPEAKERS = {
+          'system' => :system, 'developer' => :system, 'assistant' => :model, 'tool' => :tool, 'function' => :tool
+        }.freeze
+
+        def parse_request_shape(payload)
+          messages = payload['messages']
+          return unless messages.is_a?(Array)
+
+          turns = messages.each_with_index.map { |message, index| shape_message(shape_hash(message), index) }
+          tool_names = shape_list(payload['tools']).map { |tool| shape_function_name(tool) }
+          shape_request(turns, payload:, tool_names:, thinking_settings: shape_reasoning_settings(payload))
+        end
+
+        private
+
+        def shape_message(message, index)
+          speaker = SPEAKERS.fetch(message['role'], :user)
+          content = message['content']
+          parts = shape_message_thinking(message)
+          if speaker == :tool
+            parts.concat(shape_tool_result(content, name: message['name'], id: message['tool_call_id']) do |block|
+              shape_content_part(block)
+            end)
+          else
+            parts.concat(shape_content(content))
+          end
+          parts.concat(shape_list(message['tool_calls']).map { |call| shape_function_call(shape_hash(call)) })
+          shape_turn(index, message['role'], speaker, parts)
+        end
+
+        def shape_reasoning_settings(payload)
+          shape_settings(payload, 'reasoning_effort')
+            .merge(shape_settings(payload['reasoning'], 'effort', 'max_tokens', 'enabled', 'exclude'))
+            .merge(shape_settings(payload['thinking'], 'type', 'token_budget', 'budget_tokens'))
+        end
+
+        def shape_message_thinking(message)
+          details = message['reasoning_details']
+          return details.map { |detail| shape_reasoning_detail(shape_hash(detail)) } if details.is_a?(Array)
+
+          text = message['reasoning_content'] || message['reasoning']
+          signed = shape_signature?(message['reasoning_signature'])
+          text || signed ? [shape_text(text, kind: :thinking, signed:)] : []
+        end
+
+        def shape_reasoning_detail(detail)
+          case detail['type']
+          when 'reasoning.encrypted' then shape_text(nil, kind: :thinking, signed: shape_signature?(detail['data']))
+          when 'reasoning.summary' then shape_text(detail['summary'], kind: :thinking)
+          else shape_text(detail['text'], kind: :thinking, signed: shape_signature?(detail['signature']))
+          end
+        end
+
+        def shape_content(content)
+          return [shape_text(content)] if content.is_a?(String)
+
+          shape_list(content).map { |part| shape_content_part(shape_hash(part)) }
+        end
+
+        def shape_content_part(part)
+          case part['type']
+          when 'text' then shape_text(part['text'])
+          when 'image_url' then shape_url(shape_url_field(part['image_url']), kind: :image)
+          when 'video_url' then shape_url(shape_url_field(part['video_url']), kind: :video)
+          when 'input_audio' then shape_inline(shape_hash(part['input_audio'])['data'], kind: :audio)
+          when 'file' then shape_content_file(shape_hash(part['file']))
+          when 'document_url' then shape_url(shape_url_field(part['document_url']), kind: :document)
+          when 'file_url' then shape_file_url(shape_url_field(part['file_url']))
+          when 'thinking' then shape_content_thinking(part)
+          else shape_other(part['type'])
+          end
+        end
+
+        def shape_url_field(value)
+          value.is_a?(Hash) ? value['url'] : value
+        end
+
+        def shape_content_file(file)
+          return shape_file(kind: :document) if file.key?('file_id')
+
+          shape_url(file['file_data'], kind: :document)
+        end
+
+        # Perplexity sends a document's bytes as bare base64 where its link
+        # would go, and base64 never holds the colon that starts a scheme.
+        def shape_file_url(url)
+          return shape_inline(url, kind: :document) if url.is_a?(String) && !url.include?(':')
+
+          shape_url(url, kind: :document)
+        end
+
+        def shape_content_thinking(part)
+          thinking = part['thinking']
+          signed = shape_signature?(part['signature'])
+          return shape_summary(thinking, signed:) if thinking.is_a?(Array)
+
+          shape_text(thinking, kind: :thinking, signed:)
+        end
+
+        def shape_function_call(call)
+          function = shape_hash(call['function'])
+          signature = shape_hash(shape_hash(call['extra_content'])['google'])['thought_signature']
+          shape_tool_call(function['name'], function['arguments'], id: call['id'], signed: shape_signature?(signature))
+        end
+
+        def shape_function_name(tool)
+          tool = shape_hash(tool)
+          shape_hash(tool['function'])['name'] || tool['type']
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/protocols/chat_completions/streaming.rb

@@ -54,6 +54,9 @@ module RubyLLM
           error = error_data['error']
           return [nil, error.to_s] unless error.is_a?(Hash)
 
+          code = error['code']
+          return [code, error['message']] if code.is_a?(Integer) && code.between?(400, 599)
+
           case error['type']
           when 'server_error'
             [500, error['message']]

data/lib/ruby_llm/protocols/chat_completions.rb

@@ -8,6 +8,7 @@ module RubyLLM
       include ChatCompletions::Embeddings
       include ChatCompletions::Models
       include ChatCompletions::Moderation
+      include ChatCompletions::RequestShapes
       include ChatCompletions::Streaming
       include ChatCompletions::Tools
       include ChatCompletions::Images