ruby_llm 1.16.0 → 2.0.0.rc1

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