ruby_llm 2.1.0 → 2.2.0

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

@@ -27,12 +27,18 @@ module RubyLLM
 
           def render_payload(messages, tools:, temperature:, model:, stream: false, max_output_tokens: nil,
                              schema: nil, thinking: nil, tool_prefs: nil, **)
+            raise ArgumentError, 'Mistral has no thinking budget; use effort:' if thinking&.budget
+
             options = super(messages, tools:, temperature:, model:, stream:, max_output_tokens:,
                                       schema:, thinking:, citations: false, caching: nil, tool_prefs:)
             normalize_conversation_choice(options)
+            if options[:parallel_tool_calls] == false
+              raise ArgumentError, 'Mistral Conversations does not accept calls: :one'
+            end
+
             {
               model: model.id,
-              inputs: format_entries(messages),
+              inputs: render_entries(messages),
               instructions: messages.select { |message| message.role == :system }.map(&:content).join("\n\n"),
               completion_args: options.slice(:temperature, :max_tokens, :response_format, :reasoning_effort,
                                              :tool_choice),
@@ -51,19 +57,39 @@ module RubyLLM
             options[:tool_choice] = 'any' if choice == 'required'
           end
 
-          def format_entries(messages)
-            entries = messages.reject { |message| message.role == :system }.flat_map do |message|
-              if message.raw_content
-                Array(message.raw_content)
-              elsif message.tool_result?
-                [{ type: 'function.result', tool_call_id: message.tool_call_id, result: message.content.to_s }]
-              else
-                format_conversation_message(message)
-              end
-            end
+          def render_entries(messages)
+            entries = messages.reject { |message| message.role == :system }
+                              .chunk_while { |previous, current| previous.tool_result? && current.tool_result? }
+                              .flat_map { |group| render_entry_group(group) }
             entries.each_with_index.flat_map { |entry, index| replay_conversation_entry(entry, index) }
           end
 
+          # Function results are text-only on the wire and a round's results
+          # stay consecutive, so tool attachments ride a user entry after them.
+          def render_entry_group(group)
+            carriers = group.select do |message|
+              message.tool_result? && message.raw_content.nil? && message.attachments.any?
+            end
+
+            group.flat_map { |message| render_entry(message) } +
+              carriers.map { |message| { type: 'message.input', **tool_attachment_message(message) } }
+          end
+
+          def render_entry(message)
+            if conversation_entries?(message.raw_content)
+              Protocol::ReplayedArguments.blank(message.raw_content, message,
+                                                id: 'tool_call_id', arguments: 'arguments', empty: '{}')
+            elsif message.tool_result?
+              [{ type: 'function.result', tool_call_id: message.provider_call_id, result: message.content.to_s }]
+            else
+              render_conversation_message(message)
+            end
+          end
+
+          def conversation_entries?(content)
+            content.is_a?(Array) && content.all? { |entry| entry.is_a?(Hash) && entry['type'] }
+          end
+
           def replay_conversation_entry(entry, index)
             return replay_conversation_execution(entry, index) if entry['type'] == 'tool.execution'
 
@@ -91,16 +117,16 @@ module RubyLLM
             ]
           end
 
-          def format_conversation_message(message)
+          def render_conversation_message(message)
             entries = []
             if message.content || message.attachments.any?
               entries << {
                 type: 'message.input', role: message.role.to_s,
-                content: format_message_content(message)
+                content: render_message_content(message)
               }
             end
-            message.tool_calls&.each_value do |call|
-              entries << { type: 'function.call', tool_call_id: call.id, name: call.name,
+            message.tool_calls.each do |call|
+              entries << { type: 'function.call', tool_call_id: call.provider_call_id, name: call.name,
                            arguments: JSON.generate(call.arguments) }
             end
             entries
@@ -127,13 +153,10 @@ module RubyLLM
                               response: raw)
             end
 
-            output.select { |entry| pending_conversation_call?(entry) }.to_h do |entry|
-              call = parse_tool_calls([
-                                        { 'id' => entry['tool_call_id'], 'type' => 'function',
-                                          'function' => entry.slice('name', 'arguments') }
-                                      ], response: raw, finish_reason: :tool_calls).values.first
-              [call.id, call]
+            calls = output.select { |entry| pending_conversation_call?(entry) }.map do |entry|
+              { 'id' => entry['tool_call_id'], 'type' => 'function', 'function' => entry.slice('name', 'arguments') }
             end
+            parse_tool_calls(calls, response: raw, finish_reason: :tool_calls) || {}
           end
 
           def pending_conversation_call?(entry)

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

@@ -5,12 +5,14 @@ module RubyLLM
     module Mistral
       # Mistral Files API.
       class Files < Protocols::Files
+        def rejected_options(operation)
+          operation == :upload ? %i[uri] : super
+        end
+
         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)
-          multipart_payload(attachment, purpose:, expiry: expiry_hours(expires_in), visibility:)
+        def render_upload_fields(_attachment, purpose: nil, expires_in: nil)
+          { purpose:, expiry: expiry_hours(expires_in) }
         end
 
         def expiry_hours(expires_in)

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

@@ -17,12 +17,23 @@ module RubyLLM
           SERVER_TOOL_ALIASES
         end
 
-        def format_message_group(group, **options)
+        def render_message_group(group, **options)
           content = group.first.raw_content
           return super unless group.one? && content.is_a?(Array) &&
-                              content.all? { |entry| entry.is_a?(Hash) && entry['role'] }
+                              content.all? { |entry| entry.is_a?(Hash) && entry['role'] && !entry['type'] }
 
-          content.map { |entry| entry.except('index') }
+          ids = Protocol::ReplayedArguments.malformed_call_ids(group.first)
+          content.map { |entry| replayed_multi_entry(entry.except('index'), ids) }
+        end
+
+        def replayed_multi_entry(entry, malformed_ids)
+          return entry if malformed_ids.empty? || !entry['tool_calls'].is_a?(Array)
+
+          entry.merge('tool_calls' => entry['tool_calls'].map do |call|
+            next call unless malformed_ids.include?(call['id'])
+
+            call.merge('function' => call['function'].to_h.merge('arguments' => '{}'))
+          end)
         end
 
         def parse_completion_body(data, raw:)
@@ -116,7 +127,7 @@ module RubyLLM
           append_multi_content(entry, delta['content'])
           append_multi_calls(entry, delta['tool_calls'])
           @multi_finish_reason = choice['finish_reason'] if choice['finish_reason']
-          content, thinking = extract_content_and_thinking(delta['content']) if entry['role'] == 'assistant'
+          content, thinking = parse_content_and_thinking(delta['content']) if entry['role'] == 'assistant'
           Chunk.new(role: :assistant, content: content, thinking: Thinking.build(text: thinking), model: data['model'])
         end
 

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

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Protocols
+    module Moonshot
+      # Kimi's Files API. A file's purpose decides what Kimi does with it, so
+      # an upload without one follows its content: images and videos are
+      # stored for the models to read, and everything else has its text
+      # extracted.
+      class Files < Protocols::OpenAI::Files
+        def rejected_options(operation)
+          operation == :upload ? %i[expires_in uri] : super
+        end
+
+        # Kimi wraps a file's extracted text in a JSON object; any other
+        # stored file comes back as it was written.
+        def download(file_id)
+          body = super
+          extracted_text(body) || body
+        end
+
+        private
+
+        def render_upload_fields(attachment, purpose: nil, **)
+          super(attachment, purpose: purpose || default_purpose(attachment))
+        end
+
+        def default_purpose(attachment)
+          return 'image' if attachment.image?
+          return 'video' if attachment.video?
+
+          'file-extract'
+        end
+
+        def parse_file_response(data, mime_type: nil)
+          super(data, mime_type: mime_type || data['file_type'])
+        end
+
+        def extracted_text(body)
+          data = JSON.parse(body)
+          data['content'] if data.is_a?(Hash) && data['type'] == 'file'
+        rescue JSON::ParserError
+          nil
+        end
+      end
+    end
+  end
+end

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

@@ -114,8 +114,9 @@ module RubyLLM
           index = batch_result_index(line['custom_id'])
           response = line['response']
 
-          if response && response['status_code'].to_i.between?(200, 299)
-            [index, parse_batch_completion_response(response['body'])]
+          if batch_response_succeeded?(response)
+            body = response['body']
+            parsed_batch_result(index, line['custom_id'], body) { parse_batch_completion_response(body) }
           else
             [index, nil, batch_failure(line['custom_id'], batch_error_message(line))]
           end

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

@@ -27,13 +27,15 @@ module RubyLLM
 
         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)]
+          named = body.fetch('answers').to_h { |answer| [answer.fetch('name'), answer] }
+          answers = questions.values.to_h do |question|
+            [question.name, parse_answer(named.fetch(question.name.to_s), 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:)
+          raise Error.new('OpenAI Decisions returned an invalid judgment', provider_message: e.message, response:,
+                                                                           redact: @config&.redact_error_messages)
         end
 
         private
@@ -51,7 +53,7 @@ module RubyLLM
           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,
+          Responses::Media.render_image(image, image_url: image.for_llm,
                                                original_detail: @provider.original_image_detail?)
         end
 

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

@@ -5,19 +5,25 @@ module RubyLLM
     module OpenAI
       # OpenAI Files API.
       class Files < Protocols::Files
+        def rejected_options(operation)
+          operation == :upload ? %i[uri] : super
+        end
+
         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)
-          multipart_payload(attachment, purpose:, expires_after: expires_after(expires_in))
+        def render_upload_fields(_attachment, purpose: nil, expires_in: nil)
+          { purpose:, expires_after: expires_after(expires_in) }
         end
 
         def expires_after(expires_in)
           { anchor: 'created_at', seconds: expires_in } if expires_in
         end
 
-        def parse_file_response(data)
+        def parse_upload_response(data, attachment)
+          parse_file_response(data, mime_type: file_content_type(attachment))
+        end
+
+        def parse_file_response(data, mime_type: nil)
           uploaded_file(
             data,
             id: data['id'],
@@ -26,7 +32,8 @@ module RubyLLM
             created_at: timestamp(data['created_at']),
             expires_at: timestamp(data['expires_at']),
             status: data['status'],
-            purpose: data['purpose']
+            purpose: data['purpose'],
+            mime_type:
           )
         end
       end

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

@@ -7,10 +7,8 @@ module RubyLLM
         include RubyLLM::Batch::Helpers
 
         TERMINAL_STATUSES = %w[completed failed expired cancelled].freeze
-        MEDIA_TYPES = %w[image image_url input_image input_audio audio video video_url input_video file input_file
-                         document].freeze
         Response = Struct.new(:body)
-        private_constant :TERMINAL_STATUSES, :MEDIA_TYPES, :Response
+        private_constant :TERMINAL_STATUSES, :Response
 
         def create_batch(requests)
           model = single_batch_model!(requests, 'OpenRouter')
@@ -68,8 +66,8 @@ module RubyLLM
               raise ArgumentError,
                     'OpenRouter embedding batches accept text only, without task_type or provider preferences'
             end
-          elsif batch_media?(body) || body.keys.intersect?(%i[modalities audio image_config])
-            raise ArgumentError, 'OpenRouter batches accept text input and output only'
+          elsif body.keys.intersect?(%i[modalities audio image_config])
+            raise ArgumentError, 'OpenRouter batches return text only'
           end
         end
 
@@ -81,14 +79,6 @@ module RubyLLM
           end
         end
 
-        def batch_media?(value)
-          case value
-          when Hash then MEDIA_TYPES.include?(value[:type]) || value.values.any? { |part| batch_media?(part) }
-          when Array then value.any? { |part| batch_media?(part) }
-          else false
-          end
-        end
-
         def parse_batch_response(data)
           {
             id: data.fetch('id'), raw_status: data.fetch('status'),
@@ -116,7 +106,7 @@ module RubyLLM
           custom_id, shape = row.fetch('custom_id').split(':', 2)
           index = batch_result_index(custom_id)
           response = row['response']
-          unless response && response['status_code'].to_i.between?(200, 299) && !row['error']
+          unless batch_response_succeeded?(response) && !row['error']
             return [index, nil, batch_failure(custom_id, batch_error_message(row))]
           end
 
@@ -126,7 +116,10 @@ module RubyLLM
             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:)]
+          billed = body unless endpoint == '/v1/embeddings'
+          parsed_batch_result(index, custom_id, billed, parser: batch_parser(endpoint)) do
+            parse_batch_body(body, endpoint:, model: data.fetch('model'), shape:)
+          end
         end
 
         def embedding_positions?(body)
@@ -137,8 +130,11 @@ module RubyLLM
         def parse_batch_body(body, endpoint:, model:, shape:)
           return parse_batch_embedding(body, model:, shape:) if endpoint == '/v1/embeddings'
 
-          parser = endpoint == '/v1/responses' ? OpenRouter::Responses.new(@provider) : self
-          parser.send(:parse_completion_body, body, raw: body)
+          batch_parser(endpoint).send(:parse_completion_body, body, raw: body)
+        end
+
+        def batch_parser(endpoint)
+          endpoint == '/v1/responses' ? OpenRouter::Responses.new(@provider) : self
         end
 
         def parse_batch_embedding(body, model:, shape:)

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

@@ -17,16 +17,12 @@ module RubyLLM
           SERVER_TOOL_ALIASES
         end
 
-        def merge_server_tool_entries(payload, entries)
-          entries.each do |entry|
-            tool = Support::Utils.deep_symbolize_keys(entry)
-            next unless tool[:type] == 'mcp'
-            next if tool[:require_approval].to_s == 'never'
-
-            raise ArgumentError,
-                  "OpenRouter MCP requires explicit require_approval: 'never'; approval events are not returned"
-          end
-          super
+        def document_urls?
+          true
+        end
+
+        def provider_file_upload_options(_attachment)
+          {}
         end
 
         def parse_usage(usage)

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

@@ -5,17 +5,23 @@ module RubyLLM
     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.
+      # instructions, or a model in provider/model form.
       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'
+        SERVER_TOOL_ALIASES = Responses::SERVER_TOOL_ALIASES.merge(
+          web_fetch: { tool: { type: 'fetch_url' } },
+          code_execution: { tool: { type: 'sandbox' } },
+          code_interpreter: { tool: { type: 'sandbox' } }
+        ).freeze
+        SERVER_TOOL_USAGE_NAMES = {
+          'search_web' => 'web_search',
+          'fetch_url' => 'web_fetch',
+          'sandbox' => 'code_execution'
         }.freeze
-        SERVER_TOOL_USAGE_NAMES = { 'search_web' => 'web_search', 'fetch_url' => 'web_fetch' }.freeze
+
+        def server_tool_aliases
+          SERVER_TOOL_ALIASES
+        end
 
         def completion_url
           @provider.agent_url
@@ -24,19 +30,10 @@ module RubyLLM
         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
+          return payload unless PRESETS.include?(model.id)
 
           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)
+          payload.merge(preset: model.id)
         end
 
         private
@@ -45,19 +42,6 @@ module RubyLLM
           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?
@@ -92,7 +76,7 @@ module RubyLLM
           return super unless item['type'] == 'function_call'
 
           chunk tool_calls: {
-            data['output_index'] => ToolCall.new(id: item['call_id'], name: item['name'],
+            data['output_index'] => ToolCall.new(provider_call_id: item['call_id'], name: item['name'],
                                                  arguments: +item['arguments'].to_s)
           }
         end
@@ -100,14 +84,14 @@ module RubyLLM
         # 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)
+        def render_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?
+        def provider_file_references?
           false
         end
       end

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

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Protocols
+    module Perplexity
+      # Perplexity's Batch API, the OpenAI batch shape for Agent API requests.
+      module Batches
+        include Protocols::Responses::Batches
+
+        # The Idempotency-Key lets the connection retry the create after a 429,
+        # which arrives whenever the upload just used the 1 request per second
+        # that the batch and file endpoints allow at the lowest usage tier.
+        def create_batch(requests)
+          single_batch_model!(requests, @provider.slug)
+          validate_batch_requests!(requests)
+
+          payload = { input_file_id: upload_batch_file(requests), endpoint: batch_endpoint, completion_window: '24h' }
+          response = @connection.post(batch_create_url, payload) do |request|
+            request.headers['Idempotency-Key'] = SecureRandom.uuid
+          end
+
+          parse_batch_response(response.body)
+        end
+
+        private
+
+        def batch_create_url
+          'v1/batches'
+        end
+
+        def batch_url(id)
+          "v1/batches/#{id}"
+        end
+      end
+    end
+  end
+end

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

@@ -3,14 +3,18 @@
 module RubyLLM
   module Protocols
     module Perplexity
-      # Generated files belonging to a Perplexity Agent response.
-      class Files < Protocols::Files
-        def upload(*)
-          raise Error, 'Perplexity Agent only supports downloading generated response files'
-        end
+      # Perplexity's two kinds of stored file: batch input and output under
+      # /v1/files, and files an Agent response generated, which belong to it
+      # and are named response_id/files/file_id.
+      class Files < Protocols::OpenAI::Files
+        STORED_FILE_ID = /\A[A-Za-z0-9_-]+\z/
+        RESPONSE_FILE_ID = %r{\A([A-Za-z0-9_-]+)/files/([A-Za-z0-9_-]+)\z}
+        private_constant :STORED_FILE_ID, :RESPONSE_FILE_ID
 
         def find(resource_id)
           response_id, file_id = split_resource_id(resource_id)
+          return super unless response_id
+
           response = @connection.get("v1/agent/#{response_id}/files")
           data = Array(response.body['data']).find { |item| item['id'] == file_id }
           raise Error.new('Perplexity response file was not found', response:) unless data
@@ -31,16 +35,22 @@ module RubyLLM
 
         private
 
+        def files_url
+          'v1/files'
+        end
+
         def download_file_url(resource_id)
-          split_resource_id(resource_id)
-          "v1/agent/#{resource_id}/content"
+          split_resource_id(resource_id) ? "v1/agent/#{resource_id}/content" : super
         end
 
         def split_resource_id(resource_id)
-          match = resource_id.to_s.match(%r{\A([A-Za-z0-9_-]+)/files/([A-Za-z0-9_-]+)\z})
+          id = resource_id.to_s
+          return if id.match?(STORED_FILE_ID)
+
+          match = id.match(RESPONSE_FILE_ID)
           return match.captures if match
 
-          raise ArgumentError, 'Perplexity file IDs must include their response: response_id/files/file_id'
+          raise ArgumentError, 'Perplexity file IDs must be a file id or response_id/files/file_id'
         end
       end
     end

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

@@ -7,24 +7,25 @@ module RubyLLM
       module Approvals
         module_function
 
-        def render_tool_approval_response(tool_call, approved:)
-          [{ type: 'mcp_approval_response', approval_request_id: tool_call.id, approve: approved }]
+        def render_tool_approval_response(tool_call, approved:, note: nil)
+          [{ type: 'mcp_approval_response', approval_request_id: tool_call.provider_call_id, approve: approved,
+             reason: note }.compact]
         end
 
         def parse_tool_approvals(output, response: nil, finish_reason: nil)
-          output.select { |item| item['type'] == 'mcp_approval_request' }.to_h do |item|
-            arguments = item['arguments']
-            arguments = parse_function_call_arguments(arguments, response:, finish_reason:) unless arguments.is_a?(Hash)
-            call = ToolCall.new(id: item.fetch('id'), name: item.fetch('name'), arguments:,
-                                remote: true)
-            [call.id, call]
+          calls = output.filter_map do |item|
+            next unless item['type'] == 'mcp_approval_request'
+
+            arguments = ToolCall.parse_arguments(item['arguments'], response:, finish_reason:)
+            ToolCall.new(provider_call_id: item.fetch('id'), name: item.fetch('name'), **arguments, remote: true)
           end
+          ToolCall.index(calls, by: :provider_call_id)
         end
 
         def parse_pending_tool_calls(output, response: nil, finish_reason: nil)
-          calls = (parse_function_calls(output, response:, finish_reason:) || {})
-                  .merge(parse_tool_approvals(output, response:, finish_reason:))
-          calls unless calls.empty?
+          calls = (parse_function_calls(output, response:, finish_reason:) || {}).values +
+                  parse_tool_approvals(output, response:, finish_reason:).values
+          ToolCall.index(calls, by: :provider_call_id) unless calls.empty?
         end
       end
     end