ruby_llm 1.16.0 → 2.0.0.rc2

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

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

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Protocols
+    module OpenRouter
+      # OpenRouter's opt-in Responses endpoint and hosted tools.
+      class Responses < Protocols::Responses
+        SERVER_TOOL_ALIASES = %i[web_search web_fetch datetime image_generation apply_patch shell].to_h do |name|
+          [name, { tool: { type: "openrouter:#{name}" } }]
+        end.merge(
+          url_context: { tool: { type: 'openrouter:web_fetch' } },
+          code_execution: { tool: { type: 'openrouter:shell' } },
+          mcp: Protocols::Responses::SERVER_TOOL_ALIASES.fetch(:mcp)
+        ).freeze
+
+        def server_tool_aliases
+          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
+        end
+
+        def parse_usage(usage)
+          super.merge(reported_cost: reported_cost(usage), server_tool_use: server_tool_use(usage))
+        end
+
+        def reported_cost(usage)
+          cost = usage['cost']
+          return nil unless cost
+
+          cost += usage.dig('cost_details', 'upstream_inference_cost').to_f if usage['is_byok']
+          cost
+        end
+
+        def build_chunk(data)
+          return super unless data['type'] == 'response.mcp_call_arguments.done'
+
+          chunk server_tool_calls: [ServerToolCall.new(type: 'mcp_call', id: data['item_id'],
+                                                       input: data['arguments'], raw: data)]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Protocols
+    module OpenRouter
+      module Transcription # :nodoc: all
+        def transcribe(audio_file, model:, language:, format: nil, speaker_names: nil,
+                       speaker_references: nil, provider_options: {}, prompt: nil, temperature: nil, &block)
+          raise_transcription_streaming_unsupported if block
+          validate_transcription_options(format:, speaker_names:, speaker_references:, prompt:)
+          track_usage(:transcription) do
+            attachment = audio_file.is_a?(Attachment) ? audio_file : Attachment.new(audio_file, config: @config)
+            payload = {
+              model:, input_audio: { data: Base64.strict_encode64(attachment.content), format: attachment.format },
+              language:, temperature:, response_format: format || (speaker_names ? 'verbose_json' : 'json')
+            }.compact
+            if speaker_names
+              payload[:provider] =
+                { options: { azure: { diarization: { enabled: true } }, deepgram: { diarize: true } } }
+            end
+            response = @connection.post(transcription_url, Support::Utils.deep_merge(payload, provider_options),
+                                        usage: @usage_tracker)
+            parse_transcription_response(response, model:)
+          end
+        end
+
+        private
+
+        def validate_transcription_options(format:, speaker_names:, speaker_references:, prompt:)
+          if speaker_references || (speaker_names && !speaker_names.empty?)
+            raise ArgumentError,
+                  'OpenRouter accepts speaker_names: [] for diarization, but not speaker identities or reference audio'
+          end
+          if prompt
+            raise ArgumentError,
+                  'OpenRouter transcription ignores prompt; use provider_options for backend hints'
+          end
+          validate_transcription_format(format, diarization: !speaker_names.nil?)
+        end
+
+        def validate_transcription_format(format, diarization:)
+          formats = diarization ? ['verbose_json'] : %w[json verbose_json]
+          return if format.nil? || formats.include?(format.to_s)
+
+          raise ArgumentError,
+                'OpenRouter transcription accepts json or verbose_json; diarization requires verbose_json'
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+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
+
+        def find(resource_id)
+          response_id, file_id = split_resource_id(resource_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
+
+          parse_response_file(response_id, data)
+        end
+
+        def parse_response_file(response_id, data) # :nodoc:
+          file_id = data['file_id'] || data.fetch('id')
+          resource_id = "#{response_id}/files/#{file_id}"
+          split_resource_id(resource_id)
+          metadata = data.merge('response_id' => response_id)
+          uploaded_file(metadata, id: resource_id, filename: data['filename'],
+                                  byte_size: data['bytes'] || data['size_bytes'],
+                                  created_at: timestamp(data['created_at']),
+                                  mime_type: data['content_type'] || data['mime_type'], downloadable: true)
+        end
+
+        private
+
+        def download_file_url(resource_id)
+          split_resource_id(resource_id)
+          "v1/agent/#{resource_id}/content"
+        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})
+          return match.captures if match
+
+          raise ArgumentError, 'Perplexity file IDs must include their response: response_id/files/file_id'
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Protocols
+    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'
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Protocols
+    class Responses
+      # Approval requests and decisions for provider-managed tools.
+      module Approvals
+        module_function
+
+        def render_tool_approval_response(tool_call, approved:)
+          [{ type: 'mcp_approval_response', approval_request_id: tool_call.id, approve: approved }]
+        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]
+          end
+        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?
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Protocols
+    class Responses
+      # OpenAI file-backed Batch API for Responses requests.
+      module Batches
+        include Protocols::OpenAI::Batches
+
+        private
+
+        def batch_endpoint
+          '/v1/responses'
+        end
+
+        def validate_batch_requests!(requests)
+          return if requests.all? { |request| responses_payload?(request.fetch(:payload)) }
+
+          raise Error, "#{@provider.slug} batch requests require responses payloads"
+        end
+
+        def responses_payload?(payload)
+          payload.key?(:input) || payload.key?('input')
+        end
+
+        def parse_batch_completion_response(body)
+          parse_completion_body(body, raw: body)
+        end
+      end
+    end
+  end
+end