ruby_llm 1.16.0 → 2.0.0.rc2

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

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Protocols
+    module Mistral
+      class Conversations
+        module Chat # :nodoc:
+          module_function
+
+          def completion_url
+            'conversations'
+          end
+
+          def render(...)
+            payload = super
+            payload[:tools] = Support::Utils.deep_stringify_keys(payload[:tools]).uniq
+            if payload[:tools].any? { |tool| Array(tool.dig('tool_configuration', 'requires_confirmation')).any? }
+              raise ArgumentError, 'Mistral hosted tool confirmations require provider conversation storage'
+            end
+
+            payload
+          end
+
+          def render_payload(messages, tools:, temperature:, model:, stream: false, max_output_tokens: nil,
+                             schema: nil, thinking: nil, tool_prefs: nil, **)
+            options = super(messages, tools:, temperature:, model:, stream:, max_output_tokens:,
+                                      schema:, thinking:, citations: false, caching: nil, tool_prefs:)
+            normalize_conversation_choice(options)
+            {
+              model: model.id,
+              inputs: format_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),
+              tools: options.fetch(:tools, []),
+              store: false,
+              stream: stream
+            }
+          end
+
+          def normalize_conversation_choice(options)
+            choice = options[:tool_choice]
+            if choice.is_a?(Hash)
+              raise ArgumentError, 'Mistral Conversations supports :auto, :none, or :required for tool choice'
+            end
+
+            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
+            entries.each_with_index.flat_map { |entry, index| replay_conversation_entry(entry, index) }
+          end
+
+          def replay_conversation_entry(entry, index)
+            return replay_conversation_execution(entry, index) if entry['type'] == 'tool.execution'
+
+            result = entry.except('id', 'object', 'created_at', 'completed_at')
+            if entry['type'] == 'message.output' && entry['content'].is_a?(Array)
+              result['content'] = entry['content'].map do |part|
+                next part unless part['type'] == 'tool_reference'
+
+                { 'type' => 'text', 'text' => "[#{part['title']}](#{part['url']})" }
+              end
+            end
+            [result]
+          end
+
+          def replay_conversation_execution(entry, index)
+            identity = entry['id'] || "#{index}:#{JSON.generate(entry)}"
+            id = entry['tool_call_id'] || Digest::SHA256.hexdigest(identity)[0, 9]
+            info = entry['info']
+            result = info.is_a?(Hash) && info.key?('result') ? info['result'] : info
+            [
+              { 'type' => 'function.call', 'tool_call_id' => id,
+                'name' => entry['function'] || entry['name'], 'arguments' => entry['arguments'] },
+              { 'type' => 'function.result', 'tool_call_id' => id,
+                'result' => result.is_a?(String) ? result : JSON.generate(result) }
+            ]
+          end
+
+          def format_conversation_message(message)
+            entries = []
+            if message.content || message.attachments.any?
+              entries << {
+                type: 'message.input', role: message.role.to_s,
+                content: format_message_content(message)
+              }
+            end
+            message.tool_calls&.each_value do |call|
+              entries << { type: 'function.call', tool_call_id: call.id, name: call.name,
+                           arguments: JSON.generate(call.arguments) }
+            end
+            entries
+          end
+
+          def parse_completion_body(data, raw:)
+            output = data.fetch('outputs')
+            content = parse_conversation_content(output)
+            calls = parse_conversation_calls(output, raw:)
+            response_model = output.filter_map { |entry| entry['model'] }.last || @model&.id
+            Message.new(
+              role: :assistant, content: content[:text], attachments: content[:attachments],
+              citations: content[:citations], thinking: Thinking.build(text: content[:thinking]),
+              tool_calls: calls, server_tool_calls: parse_conversation_steps(output),
+              raw_content: output, model: response_model,
+              finish_reason: calls.empty? ? :stop : :tool_calls, raw: raw,
+              **parse_conversation_usage(data['usage'] || {})
+            )
+          end
+
+          def parse_conversation_calls(output, raw:)
+            if output.any? { |entry| entry['type'] == 'function.call' && entry['confirmation_status'] == 'pending' }
+              raise Error.new('Mistral returned a hosted tool confirmation that requires provider conversation storage',
+                              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]
+            end
+          end
+
+          def pending_conversation_call?(entry)
+            entry['type'] == 'function.call' && entry['confirmation_status'].nil?
+          end
+
+          def parse_conversation_steps(output)
+            output.filter_map do |entry|
+              next unless entry['type'] == 'tool.execution' ||
+                          (entry['type'] == 'function.call' && !pending_conversation_call?(entry))
+
+              ServerToolCall.new(type: entry['type'], name: entry['name'], id: entry['id'],
+                                 input: entry['arguments'], result: entry['info'], raw: entry)
+            end
+          end
+
+          def parse_conversation_usage(usage)
+            input = usage['prompt_tokens'] && (usage['prompt_tokens'] + usage.fetch('connector_tokens', 0).to_i)
+            {
+              input_tokens: input,
+              output_tokens: usage['completion_tokens'], server_tool_use: usage['connectors']
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Protocols
+    module Mistral
+      class Conversations
+        module Images # :nodoc:
+          def images_url(**)
+            'conversations'
+          end
+
+          def render_image_payload(prompt, model:, size:, count: nil, with: nil, mask: nil, provider_options: {})
+            if size || (count && count != 1)
+              raise ArgumentError,
+                    'Mistral image generation does not accept size or count options'
+            end
+            raise UnsupportedAttachmentError, 'image editing' if with || mask
+
+            payload = { model: model, store: false, inputs: prompt, tools: [{ type: 'image_generation' }] }
+            Support::Utils.deep_merge(payload, provider_options)
+          end
+
+          def parse_image_response(response, model:)
+            parse_image_responses(response, model:).first
+          end
+
+          def parse_image_responses(response, model:)
+            data = response.body
+            attachments = parse_conversation_content(data.fetch('outputs'))[:attachments]
+            raise Error.new('Mistral returned no generated image', response:) if attachments.empty?
+
+            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)
+              Image.new(data: Base64.strict_encode64(bytes), mime_type: RubyLLM::Files::MimeType.for(StringIO.new(bytes)),
+                        model: model, usage: index.zero? ? usage : {})
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Protocols
+    module Mistral
+      class Conversations
+        module Streaming # :nodoc:
+          module_function
+
+          def stream_response(payload, additional_headers = {})
+            @conversation_output = {}
+            @conversation_response = { 'object' => 'conversation.response' }
+            @conversation_done = false
+            response = stream_events(completion_url, payload, additional_headers) { |data| yield build_chunk(data) }
+            raise Error.new('Mistral conversation stream ended before completion', response:) unless @conversation_done
+
+            parse_completion_body(streamed_conversation_response, raw: response)
+          end
+
+          def build_chunk(data)
+            @conversation_output ||= {}
+            @conversation_response ||= { 'object' => 'conversation.response' }
+            case data['type']
+            when 'conversation.response.done'
+              @conversation_done = true
+              @conversation_response['usage'] = data['usage']
+              return final_conversation_chunk
+            when 'conversation.response.error'
+              raise Error, data['message'] || data.dig('error', 'message') || 'Mistral conversation failed'
+            when 'message.output.delta'
+              return conversation_text_chunk(data)
+            when 'function.call.delta', 'tool.execution.started', 'tool.execution.delta', 'tool.execution.done'
+              accumulate_conversation_entry(data)
+            end
+            Chunk.new(role: :assistant, content: nil)
+          end
+
+          def streamed_conversation_response
+            @conversation_response.merge('outputs' => @conversation_output.sort.map(&:last))
+          end
+
+          def accumulate_conversation_entry(data)
+            type = data['type'].delete_suffix('.delta').delete_suffix('.started').delete_suffix('.done')
+            entry = @conversation_output[data.fetch('output_index', 0)] ||= { 'type' => type, 'arguments' => +'' }
+            entry.merge!(data.slice('id', 'model', 'name', 'tool_call_id', 'confirmation_status', 'function', 'info'))
+            entry['arguments'] << data['arguments'].to_s
+          end
+
+          def conversation_text_chunk(data)
+            entry = @conversation_output[data.fetch('output_index',
+                                                    0)] ||= { 'type' => 'message.output', 'content' => [] }
+            entry.merge!(data.slice('id', 'model', 'role'))
+            part = data['content'].is_a?(String) ? { 'type' => 'text', 'text' => data['content'] } : data['content']
+            merge_conversation_part(entry['content'], data.fetch('content_index', 0), part)
+            content = { text: +'', thinking: +'', attachments: [], citations: [] }
+            parse_conversation_parts([part], content)
+            Chunk.new(role: :assistant, content: content[:text], model: data['model'],
+                      thinking: Thinking.build(text: content[:thinking].empty? ? nil : content[:thinking]))
+          end
+
+          def merge_conversation_part(parts, index, part)
+            existing = parts[index]
+            if existing && part['type'] == 'text'
+              existing['text'] << part['text'].to_s
+            elsif existing && part['type'] == 'thinking'
+              existing['thinking'].concat(Array(part['thinking']))
+            else
+              parts[index] = Support::Utils.deep_dup(part)
+            end
+          end
+
+          def final_conversation_chunk
+            message = parse_completion_body(streamed_conversation_response, raw: nil)
+            Chunk.new(role: :assistant, content: nil, model: message.model, tokens: message.tokens,
+                      citations: message.citations, tool_calls: message.tool_calls,
+                      server_tool_calls: message.server_tool_calls, raw_content: message.raw_content,
+                      attachments: message.attachments, finish_reason: message.finish_reason)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Protocols
+    module Mistral
+      # Mistral's Conversations API, including provider-executed tools.
+      class Conversations < ChatCompletions
+        include Mistral::Content
+        include Conversations::Chat
+        include Conversations::Streaming
+        include Conversations::Images
+
+        public :render
+
+        SERVER_TOOL_ALIASES = {
+          web_search: { tool: { type: 'web_search' } },
+          web_fetch: { tool: { type: 'web_search' } },
+          code_execution: { tool: { type: 'code_interpreter' } },
+          file_search: { tool: { type: 'document_library' } },
+          image_generation: { tool: { type: 'image_generation' } },
+          mcp: { tool: { type: 'connector' } }
+        }.freeze
+
+        def server_tool_aliases
+          SERVER_TOOL_ALIASES
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Protocols
+    module Mistral
+      # Mistral Files API.
+      class Files < Protocols::Files
+        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:)
+        end
+
+        def expiry_hours(expires_in)
+          expires_in&.fdiv(3600)&.ceil
+        end
+
+        def parse_file_response(data)
+          uploaded_file(
+            data,
+            id: data['id'],
+            filename: data['filename'],
+            byte_size: data['bytes'],
+            created_at: timestamp(data['created_at']),
+            expires_at: timestamp(data['expires_at']),
+            mime_type: data['mimetype'],
+            purpose: data['purpose'],
+            status: data['deleted'] ? 'deleted' : nil
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Protocols
+    module Mistral
+      module MultiCompletion # :nodoc:
+        include Mistral::Content
+
+        SERVER_TOOL_ALIASES = {
+          image_generation: { tool: { type: 'image_generation' } },
+          mcp: { tool: { type: 'connector' } }
+        }.freeze
+
+        module_function
+
+        def server_tool_aliases
+          SERVER_TOOL_ALIASES
+        end
+
+        def format_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.map { |entry| entry.except('index') }
+        end
+
+        def parse_completion_body(data, raw:)
+          messages = data.dig('choices', 0, 'messages')
+          return super unless messages.is_a?(Array)
+
+          parse_multi_message(data, messages, raw:)
+        end
+
+        def multi_content(messages)
+          output = messages.filter_map do |message|
+            message.merge('type' => 'message.output') if message['role'] == 'assistant'
+          end
+          parse_conversation_content(output)
+        end
+
+        def multi_pending_calls(calls, results, raw:)
+          pending = calls.reject { |call| results.key?(call['id']) }
+          if pending.any? { |call| call.dig('metadata', 'tool_type') || call.dig('metadata', 'integration_id') }
+            raise Error.new('Mistral returned an unfinished hosted tool call on Chat Completions', response: raw)
+          end
+
+          pending
+        end
+
+        def parse_multi_message(data, messages, raw:)
+          content = multi_content(messages)
+          results = messages.filter_map do |message|
+            [message['tool_call_id'], message] if message['role'] == 'tool'
+          end.to_h
+          calls = messages.flat_map { |message| Array(message['tool_calls']) }
+          pending = multi_pending_calls(calls, results, raw:)
+          usage = data['usage'] || {}
+          Message.new(role: :assistant, content: content[:text], thinking: Thinking.build(text: content[:thinking]),
+                      attachments: content[:attachments], 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),
+                      cache_read_tokens: cache_read_tokens(usage), model: data['model'], raw: raw,
+                      finish_reason: normalize_finish_reason(data.dig('choices', 0, 'finish_reason')))
+        end
+
+        def parse_multi_steps(calls, results)
+          calls.filter_map do |call|
+            result = results[call['id']]
+            next unless result
+
+            ServerToolCall.new(type: result['role'], id: call['id'], name: call.dig('function', 'name'),
+                               input: call.dig('function', 'arguments'), result: result['content'], raw: result)
+          end
+        end
+
+        def stream_response(payload, additional_headers = {}, &block)
+          return super unless Array(payload[:tools]).any? { |tool| (tool[:type] || tool['type']) != 'function' }
+
+          @multi_messages = {}
+          @multi_usage = {}
+          @multi_finish_reason = nil
+          response = stream_events(completion_url, payload, additional_headers) do |data|
+            block.call(build_multi_chunk(data))
+          end
+          raise Error.new('Mistral tool stream ended before completion', response:) unless @multi_finish_reason
+
+          message = parse_completion_body(multi_response, raw: response)
+          block.call(Chunk.new(role: :assistant, content: nil, tokens: message.tokens, model: message.model,
+                               citations: message.citations, server_tool_calls: message.server_tool_calls,
+                               tool_calls: message.tool_calls, raw_content: message.raw_content,
+                               attachments: message.attachments, finish_reason: message.finish_reason))
+          message
+        end
+
+        def build_multi_chunk(data)
+          @multi_model = data['model']
+          @multi_usage[data['id']] = data['usage'] if data['usage']
+          choice = data.dig('choices', 0) || {}
+          delta = choice['delta'] || {}
+          index = delta.fetch('index', 0)
+          @multi_finish_reason = nil unless @multi_messages.key?(index)
+          entry = @multi_messages[index] ||= { 'content' => [], 'tool_calls' => [] }
+          entry.merge!(delta.slice('role', 'tool_call_id', 'metadata'))
+          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'
+          Chunk.new(role: :assistant, content: content, thinking: Thinking.build(text: thinking), model: data['model'])
+        end
+
+        def append_multi_content(entry, content)
+          return if content.nil?
+
+          if content.is_a?(String)
+            entry['content'] << { 'type' => 'text', 'text' => content }
+          else
+            entry['content'].concat(content)
+          end
+        end
+
+        def append_multi_calls(entry, calls)
+          Array(calls).each do |call|
+            target = entry['tool_calls'][call.fetch('index', 0)] ||= { 'function' => { 'arguments' => +'' } }
+            target.merge!(call.slice('id', 'type', 'metadata'))
+            target['function']['name'] = call.dig('function', 'name') if call.dig('function', 'name')
+            target['function']['arguments'] << call.dig('function', 'arguments').to_s
+          end
+        end
+
+        def multi_response
+          { 'model' => @multi_model, 'usage' => multi_usage,
+            'choices' => [{ 'messages' => multi_messages, 'finish_reason' => @multi_finish_reason }] }
+        end
+
+        def multi_usage
+          usages = @multi_usage.values
+          usage = %w[prompt_tokens completion_tokens total_tokens].to_h do |key|
+            [key, usages.sum { |value| value[key].to_i }]
+          end
+          usage['prompt_tokens_details'] = { 'cached_tokens' => usages.sum do |value|
+            value.dig('prompt_tokens_details', 'cached_tokens').to_i
+          end }
+          usage
+        end
+
+        def multi_messages
+          @multi_messages.sort.map do |_, message|
+            message = message.reject { |key, value| key == 'tool_calls' && value.empty? }
+            if message['role'] == 'tool' && message['content'].all? { |part| part['type'] == 'text' }
+              message['content'] = message['content'].map { |part| part['text'] }.join
+            end
+            message
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require 'stringio'
+
+module RubyLLM
+  module Protocols
+    module OpenAI
+      # The OpenAI file-backed Batch API: upload JSONL, create /batches,
+      # then read output/error files back in custom_id order.
+      module Batches
+        include RubyLLM::Batch::Helpers
+
+        TERMINAL_STATUSES = %w[completed failed expired cancelled].freeze
+        private_constant :TERMINAL_STATUSES
+
+        def create_batch(requests)
+          single_batch_model!(requests, @provider.slug)
+          validate_batch_requests!(requests)
+
+          response = @connection.post(batch_create_url, {
+                                        input_file_id: upload_batch_file(requests),
+                                        endpoint: batch_endpoint,
+                                        completion_window: '24h'
+                                      }, idempotent: false)
+
+          parse_batch_response(response.body)
+        end
+
+        def find_batch(id)
+          parse_batch_response @connection.get(batch_url(id)).body
+        end
+
+        def cancel_batch(id)
+          parse_batch_response @connection.post("#{batch_url(id)}/cancel", {}).body
+        end
+
+        # Results are JSONL and may arrive out of order. Each line carries the
+        # custom_id we assigned from the submission index.
+        def batch_results(id)
+          batch = @connection.get(batch_url(id)).body
+          %w[output_file_id error_file_id].flat_map do |key|
+            file_id = batch[key]
+            next [] unless file_id && !file_id.to_s.empty?
+
+            download_batch_file(file_id).to_s.each_line.filter_map { |line| parse_batch_result(JSON.parse(line)) }
+          end
+        end
+
+        private
+
+        def upload_batch_file(requests)
+          @provider.upload_file(
+            StringIO.new(batch_jsonl(requests)),
+            purpose: 'batch',
+            filename: 'ruby_llm_batch.jsonl'
+          ).id
+        end
+
+        def download_batch_file(file_id)
+          @provider.download_file(file_id)
+        end
+
+        def batch_jsonl(requests)
+          requests.map { |request| JSON.generate(batch_request_line(request)) }.join("\n")
+        end
+
+        def batch_request_line(request)
+          {
+            custom_id: request[:custom_id],
+            method: 'POST',
+            url: batch_endpoint,
+            body: batch_payload(request)
+          }
+        end
+
+        def validate_batch_requests!(_requests); end
+
+        def batch_endpoint
+          raise NotImplementedError
+        end
+
+        def batch_create_url
+          'batches'
+        end
+
+        def batch_url(id)
+          "batches/#{id}"
+        end
+
+        def parse_batch_response(data)
+          request_counts = data['request_counts']
+
+          {
+            id: data['id'],
+            raw_status: data['status'],
+            completed: TERMINAL_STATUSES.include?(data['status']),
+            request_counts:,
+            request_count: request_counts&.fetch('total', nil),
+            endpoint: data['endpoint']
+          }.compact
+        end
+
+        def parse_batch_status(raw_status, completed:)
+          return :pending unless completed
+
+          case raw_status
+          when 'completed' then :succeeded
+          when 'cancelled' then :cancelled
+          else :failed
+          end
+        end
+
+        def parse_batch_result(line)
+          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'])]
+          else
+            [index, nil, batch_failure(line['custom_id'], batch_error_message(line))]
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Protocols
+    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
+
+        def expires_after(expires_in)
+          { anchor: 'created_at', seconds: expires_in } if expires_in
+        end
+
+        def parse_file_response(data)
+          uploaded_file(
+            data,
+            id: data['id'],
+            filename: data['filename'],
+            byte_size: data['bytes'],
+            created_at: timestamp(data['created_at']),
+            expires_at: timestamp(data['expires_at']),
+            status: data['status'],
+            purpose: data['purpose']
+          )
+        end
+      end
+    end
+  end
+end