ruby_llm 1.16.0 → 2.0.0.rc1

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

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

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Protocols
+    module OpenRouter
+      module Batches # :nodoc: all
+        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
+
+        def create_batch(requests)
+          model = single_batch_model!(requests, 'OpenRouter')
+          endpoints = requests.map { |request| batch_request_endpoint(request) }.uniq
+          raise ArgumentError, 'OpenRouter batches require one API protocol per submission' unless endpoints.one?
+
+          endpoint = endpoints.first
+          rows = requests.map { |request| render_batch_request(request, endpoint:) }
+          response = @connection.post(@provider.batch_api_base, { endpoint:, model:, requests: rows },
+                                      idempotent: false)
+          parse_batch_response(response.body)
+        end
+
+        def find_batch(id)
+          parse_batch_response(batch_data(id))
+        end
+
+        def cancel_batch(_id)
+          raise Error, 'OpenRouter does not expose batch cancellation'
+        end
+
+        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
+        end
+
+        private
+
+        def batch_data(id)
+          @connection.get("#{@provider.batch_api_base}/#{id}").body
+        end
+
+        def batch_request_endpoint(request)
+          return '/v1/embeddings' if request.key?(:text)
+
+          payload = Support::Utils.deep_symbolize_keys(request.fetch(:payload))
+          return '/v1/chat/completions' if payload.key?(:messages)
+          return '/v1/responses' if payload.key?(:input)
+
+          raise ArgumentError, 'OpenRouter batches require chat or embedding requests'
+        end
+
+        def render_batch_request(request, endpoint:)
+          body = Support::Utils.deep_symbolize_keys(batch_payload(request))
+          validate_batch_body(body, endpoint:)
+          id = request.fetch(:custom_id)
+          id = "#{id}:array" if endpoint == '/v1/embeddings' && request.fetch(:text).is_a?(Array)
+          { custom_id: id, body: }
+        end
+
+        def validate_batch_body(body, endpoint:)
+          if endpoint == '/v1/embeddings'
+            unsupported = body.keys & %i[input_type provider]
+            if unsupported.any? || !text_embedding_input?(body[:input])
+              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'
+          end
+        end
+
+        def text_embedding_input?(input)
+          case input
+          when String then true
+          when Array then input.flatten.all? { |part| part.is_a?(String) || part.is_a?(Integer) }
+          else false
+          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'),
+            completed: TERMINAL_STATUSES.include?(data['status']),
+            reported_cost: parse_batch_reported_cost(data['usage']),
+            request_counts: data['request_counts'], request_count: data.dig('request_counts', 'total')
+          }
+        end
+
+        def parse_batch_reported_cost(usage)
+          return if usage.nil? || usage['cost'].nil?
+
+          Cost.from_h({ total: usage.fetch('cost') })
+        end
+
+        def parse_batch_status(raw_status, completed:)
+          return :pending unless completed
+          return :succeeded if raw_status == 'completed'
+          return :cancelled if raw_status == 'cancelled'
+
+          :failed
+        end
+
+        def parse_batch_result(row, data:)
+          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']
+            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:)]
+        end
+
+        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)
+        end
+
+        def parse_batch_embedding(body, model:, shape:)
+          ordered = body.merge('data' => body.fetch('data').sort_by { |row| row.fetch('index') })
+          parse_embedding_response(Response.new(ordered), model: body['model'] || model,
+                                                          text: shape == 'array' ? [] : nil)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Protocols
+    module OpenRouter
+      # OpenRouter Files API.
+      class Files < Protocols::Files
+        private
+
+        def parse_file_response(data)
+          uploaded_file(
+            data,
+            id: data['id'],
+            filename: data['filename'],
+            byte_size: data['size_bytes'],
+            created_at: timestamp(data['created_at']),
+            mime_type: data['mime_type'],
+            downloadable: data['downloadable']
+          )
+        end
+      end
+    end
+  end
+end