ruby_llm 2.0.0 → 2.1.0

data/lib/ruby_llm/protocols/mistral/conversations/images.rb

@@ -31,7 +31,11 @@ module RubyLLM
 
             usage = parse_conversation_usage(data['usage'] || {}).transform_keys(&:to_s)
             attachments.each_with_index.map do |attachment, index|
-              bytes = @provider.download_file(attachment.provider_file_id)
+              bytes = if attachment.provider_file?
+                        @provider.download_file(attachment.provider_file_id)
+                      else
+                        attachment.content
+                      end
               Image.new(data: Base64.strict_encode64(bytes), mime_type: RubyLLM::Files::MimeType.for(StringIO.new(bytes)),
                         model: model, usage: index.zero? ? usage : {})
             end

data/lib/ruby_llm/protocols/mistral/conversations/request_shapes.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Protocols
+    module Mistral
+      class Conversations
+        # Describes Conversations requests as RequestShape objects. Each
+        # input entry is a turn, messages carry Chat Completions content, and
+        # a function result answers its call by id.
+        module RequestShapes
+          def parse_request_shape(payload)
+            inputs = payload['inputs']
+            return unless inputs.is_a?(Array)
+
+            turns = inputs.each_with_index.map { |entry, index| shape_conversation_turn(shape_hash(entry), index) }
+            shape_request(turns, payload:, instructions: shape_instructions(payload['instructions']),
+                                 tool_names: shape_list(payload['tools']).map { |tool| shape_function_name(tool) },
+                                 thinking_settings: shape_settings(payload['completion_args'], 'reasoning_effort'))
+          end
+
+          private
+
+          def shape_conversation_turn(entry, index)
+            role = entry['role'] || entry['type']
+            case entry['type']
+            when 'message.input'
+              speaker = ChatCompletions::RequestShapes::SPEAKERS.fetch(entry['role'], :user)
+              shape_turn(index, role, speaker, shape_content(entry['content']))
+            when 'message.output' then shape_turn(index, role, :model, shape_content(entry['content']))
+            when 'function.result'
+              shape_turn(index, role, :tool, shape_tool_result(entry['result'], id: entry['tool_call_id']))
+            else shape_turn(index, role, :model, [shape_conversation_step(entry)])
+            end
+          end
+
+          def shape_conversation_step(entry)
+            return shape_other(entry['type']) unless entry['type'] == 'function.call'
+
+            shape_tool_call(entry['name'], entry['arguments'], id: entry['tool_call_id'])
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/protocols/mistral/conversations.rb

@@ -9,6 +9,7 @@ module RubyLLM
         include Conversations::Chat
         include Conversations::Streaming
         include Conversations::Images
+        include Conversations::RequestShapes
 
         public :render
 

data/lib/ruby_llm/protocols/mistral/multi_completion.rb

@@ -55,9 +55,10 @@ module RubyLLM
           end.to_h
           calls = messages.flat_map { |message| Array(message['tool_calls']) }
           pending = multi_pending_calls(calls, results, raw:)
+          attachments = content[:attachments] + parse_multi_images(calls, results)
           usage = data['usage'] || {}
           Message.new(role: :assistant, content: content[:text], thinking: Thinking.build(text: content[:thinking]),
-                      attachments: content[:attachments], citations: content[:citations],
+                      attachments: attachments.uniq(&:source), citations: content[:citations],
                       tool_calls: parse_tool_calls(pending, response: raw, finish_reason: :tool_calls),
                       server_tool_calls: parse_multi_steps(calls, results), raw_content: messages,
                       input_tokens: input_tokens(usage), output_tokens: output_tokens(usage),
@@ -65,6 +66,15 @@ module RubyLLM
                       finish_reason: normalize_finish_reason(data.dig('choices', 0, 'finish_reason')))
         end
 
+        def parse_multi_images(calls, results)
+          calls.filter_map do |call|
+            result = results[call['id']]
+            next unless result && call.dig('metadata', 'tool_type') == 'image'
+
+            parse_generated_image(result['content'])
+          end
+        end
+
         def parse_multi_steps(calls, results)
           calls.filter_map do |call|
             result = results[call['id']]

data/lib/ruby_llm/protocols/openai/decisions.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Protocols
+    module OpenAI
+      # OpenAI Decisions: typed questions answered with probabilities.
+      class Decisions < Protocol
+        TYPES = { probability: 'predicate', choice: 'choice', score: 'score' }.freeze
+        OUTCOMES = { 'yes' => 'Yes', 'true' => 'Yes', 'no' => 'No', 'false' => 'No' }.freeze
+
+        def judgment_url
+          'decisions'
+        end
+
+        def render_judgment_payload(input, questions:, model:, with: [], provider_options: {})
+          reserved = provider_options.keys.map(&:to_s) & %w[model input questions]
+          unless reserved.empty?
+            raise ArgumentError, "Use the judgment arguments instead of provider_options for #{reserved.join(', ')}"
+          end
+
+          {
+            model:,
+            input: render_input(input, with),
+            questions: questions.values.map { |question| render_question(question) }
+          }.merge(provider_options)
+        end
+
+        def parse_judgment_response(response, questions:)
+          body = response.body
+          answers = questions.values.zip(body.fetch('answers')).to_h do |question, answer|
+            [question.name, parse_answer(answer, question)]
+          end
+          RubyLLM::Judgment.new(answers:, model: body.fetch('model'), raw: response, model_info: @model,
+                                tokens: parse_tokens(body['usage']))
+        rescue KeyError, NoMethodError, TypeError => e
+          raise Error.new("OpenAI Decisions returned an invalid judgment: #{e.message}", response:)
+        end
+
+        private
+
+        def render_input(input, attachments)
+          text = describe(input)
+          return text if attachments.empty?
+
+          content = attachments.map { |attachment| render_image(attachment) }
+          content.unshift({ type: 'input_text', text: }) unless text.nil? || text.empty?
+          [{ type: 'message', role: 'user', content: }]
+        end
+
+        def render_image(image)
+          raise UnsupportedAttachmentError, image.mime_type unless image.image?
+          return { type: 'input_image', file_id: image.provider_file_id } if image.provider_file?
+
+          Responses::Media.format_image(image, image_url: image.for_llm,
+                                               original_detail: @provider.original_image_detail?)
+        end
+
+        def render_question(question)
+          question_payload = { type: TYPES.fetch(question.type), name: question.name.to_s,
+                               instructions: render_instructions(question) }.compact
+
+          case question.type
+          when :choice then question_payload.merge(choices: render_choices(question))
+          when :score then question_payload.merge(levels: render_levels(question))
+          else question_payload
+          end
+        end
+
+        def render_instructions(question)
+          lines = [describe(question.instructions)]
+          if question.type == :probability && question.criteria
+            question.criteria.each do |outcome, description|
+              lines << "#{OUTCOMES.fetch(outcome.to_s)}: #{describe(description)}" unless description.nil?
+            end
+          end
+          instructions = lines.compact.join("\n")
+          instructions unless instructions.empty?
+        end
+
+        def render_choices(question)
+          question.criteria.map do |value, description|
+            { value: value.to_s, description: describe(description) }.compact
+          end
+        end
+
+        def render_levels(question)
+          question.criteria.each_with_index.map do |description, index|
+            { label: index.to_s, description: describe(description) }
+          end
+        end
+
+        def describe(value)
+          value.nil? || value.is_a?(String) ? value : JSON.generate(value)
+        end
+
+        def parse_answer(answer, question)
+          case question.type
+          when :probability then RubyLLM::Probability.new(probability: answer.fetch('probability'))
+          when :choice then parse_choice(answer, question)
+          when :score then parse_score(answer, question)
+          end
+        end
+
+        def parse_choice(answer, question)
+          options = question.criteria.keys.to_h { |key| [key.to_s, key] }
+          RubyLLM::Choice.new(
+            choice: options.fetch(answer.fetch('choice')),
+            probabilities: parse_distribution(answer.fetch('probabilities'), 'value', options),
+            confidence: answer.fetch('confidence')
+          )
+        end
+
+        def parse_score(answer, question)
+          indexes = question.criteria.each_index.to_h { |index| [index.to_s, index] }
+          RubyLLM::Score.new(
+            score: answer.fetch('score'), levels: question.criteria,
+            probabilities: parse_distribution(answer.fetch('probabilities'), 'label', indexes),
+            confidence: answer.fetch('confidence')
+          )
+        end
+
+        def parse_distribution(entries, key, names)
+          entries.to_h { |entry| [names.fetch(entry.fetch(key)), entry.fetch('probability')] }
+        end
+
+        def parse_tokens(usage)
+          tokens = Responses::Chat.parse_usage(usage || {})
+          Tokens.new(input: tokens[:input_tokens], output: tokens[:output_tokens],
+                     cache_read: tokens[:cache_read_tokens], cache_write: tokens[:cache_write_tokens],
+                     thinking: tokens[:thinking_tokens])
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/protocols/openai/files.rb

@@ -5,18 +5,11 @@ module RubyLLM
     module OpenAI
       # OpenAI Files API.
       class Files < Protocols::Files
-        UPLOAD_PURPOSES = %w[assistants batch fine-tune vision user_data evals].freeze
-
         private
 
         # rubocop:disable-next Lint/UnusedMethodArgument
         def render_upload_payload(attachment, purpose: nil, expires_in: nil, visibility: nil,
                                   display_name: nil, uri: nil, content_type: nil)
-          unless purpose
-            raise ArgumentError, "#{@provider.name} file uploads require purpose: " \
-                                 "#{UPLOAD_PURPOSES.join(', ')}"
-          end
-
           multipart_payload(attachment, purpose:, expires_after: expires_after(expires_in))
         end
 

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

@@ -34,12 +34,7 @@ module RubyLLM
 
         def batch_results(id)
           data = batch_data(id)
-          results = Array(data['results']).map { |row| parse_batch_result(row, data:) }
-          unless results.map(&:first).uniq.size == results.size
-            raise Error, 'OpenRouter returned duplicate batch request IDs'
-          end
-
-          results
+          Array(data['results']).map { |row| parse_batch_result(row, data:) }
         end
 
         private
@@ -125,8 +120,18 @@ module RubyLLM
             return [index, nil, batch_failure(custom_id, batch_error_message(row))]
           end
 
-          [index, parse_batch_body(response.fetch('body'), endpoint: data.fetch('endpoint'),
-                                                           model: data.fetch('model'), shape:)]
+          body = response.fetch('body')
+          endpoint = data.fetch('endpoint')
+          if endpoint == '/v1/embeddings' && !embedding_positions?(body)
+            return [index, nil, batch_failure(custom_id, 'Invalid or duplicate embedding record positions')]
+          end
+
+          [index, parse_batch_body(body, endpoint:, model: data.fetch('model'), shape:)]
+        end
+
+        def embedding_positions?(body)
+          positions = body.fetch('data').map { |row| row['index'] }
+          positions.all?(Integer) && positions.sort == (0...positions.size).to_a
         end
 
         def parse_batch_body(body, endpoint:, model:, shape:)

data/lib/ruby_llm/protocols/openrouter/responses.rb

@@ -30,7 +30,11 @@ module RubyLLM
         end
 
         def parse_usage(usage)
-          super.merge(reported_cost: reported_cost(usage), server_tool_use: server_tool_use(usage))
+          super.merge(reported_cost: reported_cost(usage))
+        end
+
+        def parse_server_tool_use(response)
+          server_tool_use(response['usage'].to_h)
         end
 
         def reported_cost(usage)

data/lib/ruby_llm/protocols/perplexity/agent.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Protocols
+    module Perplexity
+      # Perplexity's Agent API, a dialect of the Responses API. A request names
+      # either a preset, which bundles a model, search settings, and
+      # instructions, or a model in provider/model form. The retired Sonar
+      # model ids run the presets Perplexity recommends in their place.
+      class Agent < Responses
+        PRESETS = %w[fast low medium high xhigh wide-research].freeze
+        SONAR_PRESETS = {
+          'sonar' => 'fast',
+          'sonar-pro' => 'low',
+          'sonar-reasoning-pro' => 'medium',
+          'sonar-deep-research' => 'high'
+        }.freeze
+        SERVER_TOOL_USAGE_NAMES = { 'search_web' => 'web_search', 'fetch_url' => 'web_fetch' }.freeze
+
+        def completion_url
+          @provider.agent_url
+        end
+
+        def render_payload(messages, model:, max_output_tokens: nil, **)
+          max_output_tokens ||= default_max_output_tokens(model)
+          payload = super
+          preset = preset_for(model.id)
+          return payload unless preset
+
+          payload.delete(:model)
+          payload.merge(preset: preset)
+        end
+
+        def format_document(document)
+          raise UnsupportedAttachmentError, document.mime_type
+        end
+
+        def supported_attachment?(attachment)
+          attachment.provider_file? || (%i[image text].include?(attachment.type) && super)
+        end
+
+        private
+
+        def default_max_output_tokens(model)
+          model.max_output_tokens || Anthropic::DEFAULT_MAX_OUTPUT_TOKENS if model.id.start_with?('anthropic/')
+        end
+
+        def preset_for(model_id)
+          return model_id if PRESETS.include?(model_id)
+
+          preset = SONAR_PRESETS[model_id]
+          if preset
+            RubyLLM.deprecator.warn(
+              "Perplexity retires Sonar on September 27, 2026. #{model_id} now runs the #{preset} " \
+              "Agent API preset; use model: \"#{preset}\" instead."
+            )
+          end
+          preset
+        end
+
+        def parse_citations(data, output, content)
+          citations = super
+          return citations if citations.any?
+
+          results = output.select { |item| item['type'] == 'search_results' }.flat_map { |item| Array(item['results']) }
+          parse_search_results(results)
+        end
+
+        def parse_usage(usage)
+          details = usage['input_tokens_details'] || {}
+          details = { 'cache_write_tokens' => details['cache_creation_input_tokens'] }.merge(details)
+
+          super(usage.merge('input_tokens_details' => details)).merge(reported_cost: usage.dig('cost', 'total_cost'))
+        end
+
+        def parse_server_tool_use(response)
+          response.dig('usage', 'tool_calls_details').to_h.to_h do |tool, details|
+            ["#{SERVER_TOOL_USAGE_NAMES.fetch(tool, tool)}_requests", details['invocation']]
+          end
+        end
+
+        # Perplexity sends each function call whole, without argument deltas,
+        # and announces its own web searches as function calls whose items
+        # finish as search_results. Only a finished function_call item is a
+        # call for the application to run.
+        def build_item_added_chunk(data)
+          data.dig('item', 'type') == 'function_call' ? chunk : super
+        end
+
+        def build_item_done_chunk(data)
+          item = data['item']
+          return super unless item['type'] == 'function_call'
+
+          chunk tool_calls: {
+            data['output_index'] => ToolCall.new(id: item['call_id'], name: item['name'],
+                                                 arguments: +item['arguments'].to_s)
+          }
+        end
+
+        # Perplexity rejects its own search_results and fetch_url_results
+        # items as input, so a replayed turn keeps only messages, reasoning,
+        # and function calls.
+        def format_assistant_items(msg)
+          super.select do |item|
+            type = item[:type] || item['type']
+            type.nil? || Responses::Chat::CLIENT_OUTPUT_ITEM_TYPES.include?(type)
+          end
+        end
+
+        def supports_provider_file_references?
+          false
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/protocols/perplexity/router.rb

@@ -5,53 +5,12 @@ module RubyLLM
     module Perplexity
       # Perplexity Router's Chat Completions dialect.
       class Router < ChatCompletions
-        REJECTED_OPTIONS = %i[seed logit_bias top_logprobs functions function_call modalities audio prediction
-                              web_search_options moderation verbosity].freeze
-        DEFAULT_OPTIONS = { n: 1, logprobs: false, store: false, presence_penalty: 0, frequency_penalty: 0 }.freeze
-        private_constant :REJECTED_OPTIONS, :DEFAULT_OPTIONS
-
         def completion_url
           @provider.router_url('chat/completions')
         end
 
-        def render(...)
-          super.tap do |payload|
-            validate_router_options(payload)
-            validate_router_tools(payload[:tools])
-          end
-        end
-
-        def render_payload(messages, schema: nil, **options)
-          if schema && schema[:strict] == false
-            raise ArgumentError, 'Perplexity Router requires strict structured output'
-          end
-
-          super(messages, schema: schema&.merge(strict: true), **options)
-        end
-
-        def format_audio(audio)
-          raise UnsupportedAttachmentError, audio.mime_type unless %w[mp3 wav].include?(audio.format)
-
-          super
-        end
-
-        private
-
-        def validate_router_options(payload)
-          unsupported = payload.keys & REJECTED_OPTIONS
-          unsupported.concat(DEFAULT_OPTIONS.keys.select do |key|
-            payload.key?(key) && payload[key] != DEFAULT_OPTIONS[key]
-          end)
-          unsupported << :include_obfuscation if payload.dig(:stream_options, :include_obfuscation)
-          return if unsupported.empty?
-
-          raise ArgumentError, "Perplexity Router does not support these options: #{unsupported.join(', ')}"
-        end
-
-        def validate_router_tools(tools)
-          return if Array(tools).all? { |tool| tool.dig(:function, :description).is_a?(String) }
-
-          raise ArgumentError, 'Perplexity Router function tools require a description'
+        def render_payload(messages, schema: nil, **)
+          super(messages, schema: schema && { strict: true }.merge(schema), **)
         end
       end
     end

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

@@ -10,7 +10,6 @@ module RubyLLM
         end
 
         OPENAI_INLINE_FILE_LIMIT = 50 * 1024 * 1024
-        OPENAI_FILE_UPLOAD_LIMIT = 512 * 1024 * 1024
         PROMPT_CACHE_OPTIONS = %i[key ttl mode retention].freeze
 
         module_function
@@ -69,11 +68,12 @@ module RubyLLM
             ),
             tool_calls: parse_pending_tool_calls(output, response: raw, finish_reason: finish_reason),
             server_tool_calls: server_tool_calls,
-            raw_content: server_tool_calls.any? ? output : nil,
+            raw_content: keep_raw_output?(output, server_tool_calls) ? output : nil,
             model: data['model'],
             raw: raw,
             finish_reason: finish_reason,
-            **parse_usage(data['usage'] || {})
+            **parse_usage(data['usage'] || {}),
+            server_tool_use: parse_server_tool_use(data)
           )
         end
 
@@ -105,6 +105,26 @@ module RubyLLM
         end
 
         CLIENT_OUTPUT_ITEM_TYPES = %w[message reasoning function_call].freeze
+        TOOL_SEARCH_ITEM_TYPES = %w[tool_search_call tool_search_output].freeze
+
+        PORTABLE_OUTPUT_ITEM_TYPES = (%w[message function_call] + TOOL_SEARCH_ITEM_TYPES).freeze
+
+        def keep_raw_output?(output, server_tool_calls)
+          server_tool_calls.any? || output.any? { |item| namespaced_call?(item) }
+        end
+
+        def namespaced_call?(item)
+          item['type'] == 'function_call' && !item['namespace'].nil?
+        end
+
+        def portable_raw_content(message)
+          items = message.raw_content
+          return unless items.is_a?(Array)
+          return unless items.any? { |item| TOOL_SEARCH_ITEM_TYPES.include?(item['type']) || namespaced_call?(item) }
+
+          kept = items.reject { |item| item['type'] == 'reasoning' }
+          kept if kept.all? { |item| PORTABLE_OUTPUT_ITEM_TYPES.include?(item['type']) }
+        end
 
         # Output items beyond text, reasoning, and function calls record
         # provider-executed tool steps (web_search_call, code_interpreter_call,
@@ -251,6 +271,14 @@ module RubyLLM
           }
         end
 
+        # Searches are billed by tool_usage, not by the web_search_call items
+        # in the output, which can each run several.
+        def parse_server_tool_use(response)
+          response['tool_usage'].to_h.filter_map do |tool, usage|
+            ["#{tool}_requests", usage['num_requests']] if usage['num_requests']
+          end.to_h
+        end
+
         def schema_format(schema)
           {
             type: 'json_schema',
@@ -260,32 +288,42 @@ module RubyLLM
           }
         end
 
-        # System messages marked as cache boundaries, or carrying attachments,
-        # ride along as input items, because the +instructions+ parameter is a
-        # plain string and cannot carry a breakpoint marker or a file.
+        # The +instructions+ parameter is a plain string and cannot carry a
+        # breakpoint marker or a file. When any system message needs one, every
+        # system message rides along as an input item, so their order holds.
         def format_instructions(messages, caching: nil)
-          instructions = messages.select { |msg| msg.role == :system && !system_input_item?(msg, caching:) }
-                                 .map { |msg| msg.content.to_s }
+          system = messages.select { |msg| msg.role == :system }
+          return if system.empty? || system_input_items?(system, caching:)
 
-          instructions.empty? ? nil : instructions.join("\n\n")
+          system.map { |msg| msg.content.to_s }.join("\n\n")
         end
 
         def format_input(messages, caching: nil)
-          system_items = []
-          messages.each_with_object([]) do |message, input|
-            next if message.role == :system && !system_input_item?(message, caching:)
+          system, conversation = messages.partition { |msg| msg.role == :system }
+          system_items = if system_input_items?(system, caching:)
+                           system.flat_map { |msg| [format_item(msg, caching:)].flatten(1) }
+                         else
+                           []
+                         end
 
+          system_items + format_conversation(conversation, caching:)
+        end
+
+        def format_conversation(messages, caching: nil)
+          messages.each_with_object([]) do |message, input|
             raw = message.raw_content
             if raw.is_a?(Hash) && raw['object'] == 'response.compaction'
-              input.replace(system_items + raw.fetch('output'))
+              input.replace(raw.fetch('output'))
             else
-              items = [format_item(message, caching:)].flatten(1)
-              system_items.concat(items) if message.role == :system
-              input.concat(items)
+              input.concat([format_item(message, caching:)].flatten(1))
             end
           end
         end
 
+        def system_input_items?(messages, caching: nil)
+          messages.any? { |msg| system_input_item?(msg, caching:) }
+        end
+
         def system_input_item?(msg, caching: nil)
           msg.role == :system && ((caching != false && msg.cache_until_here?) || msg.attachments.any?)
         end
@@ -333,7 +371,7 @@ module RubyLLM
 
           if msg.attachments.any?
             parts = [{ type: 'input_text', text: "Attachments from tool call #{msg.tool_call_id}:" }]
-            parts.concat(Media.format_content(nil, msg.attachments))
+            parts.concat(format_content(nil, msg.attachments))
             items << { role: 'user', content: parts }
           end
 
@@ -346,7 +384,7 @@ module RubyLLM
           return msg.raw_content if msg.raw_content
 
           items = []
-          items << format_reasoning_item(msg.thinking) if msg.thinking&.signature
+          items << format_reasoning_item(msg.thinking) if own_signature(msg)
           items << { role: 'assistant', content: format_output_content(msg) } unless empty_content?(msg.content)
           items.concat(format_function_call_items(msg.tool_calls)) if msg.tool_call?
           items
@@ -449,10 +487,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? || attachment.document?
         end

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

@@ -7,6 +7,10 @@ module RubyLLM
       module Media
         module_function
 
+        def supported_attachment?(attachment)
+          attachment.provider_file? || %i[image pdf document text].include?(attachment.type)
+        end
+
         def format_content(content, attachments = [])
           return content if attachments.empty?
 
@@ -17,6 +21,8 @@ module RubyLLM
         end
 
         def format_attachment(attachment)
+          raise UnsupportedAttachmentError, attachment.mime_type unless supported_attachment?(attachment)
+
           return format_provider_file(attachment) if attachment.provider_file?
 
           case attachment.type
@@ -26,16 +32,14 @@ module RubyLLM
             format_document(attachment)
           when :text
             { type: 'input_text', text: attachment.for_llm }
-          else
-            raise UnsupportedAttachmentError, attachment.mime_type
           end
         end
 
-        def format_image(image)
-          {
-            type: 'input_image',
-            image_url: image.url? ? image.source.to_s : image.for_llm
-          }
+        def format_image(image, image_url: image.url_or_data_uri, original_detail: @provider&.original_image_detail?)
+          part = { type: 'input_image', image_url: }
+          return part unless image.resolution
+
+          part.merge(detail: ChatCompletions::Media.image_detail(image.resolution, original_detail:))
         end
 
         # The Responses API extracts text from documents, presentations, and