ruby_llm_swarm 1.9.1

data/lib/ruby_llm/providers/openai/tools.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    class OpenAI
+      # Tools methods of the OpenAI API integration
+      module Tools
+        module_function
+
+        EMPTY_PARAMETERS_SCHEMA = {
+          'type' => 'object',
+          'properties' => {},
+          'required' => [],
+          'additionalProperties' => false,
+          'strict' => true
+        }.freeze
+
+        def parameters_schema_for(tool)
+          tool.params_schema ||
+            schema_from_parameters(tool.parameters)
+        end
+
+        def schema_from_parameters(parameters)
+          schema_definition = RubyLLM::Tool::SchemaDefinition.from_parameters(parameters)
+          schema_definition&.json_schema || EMPTY_PARAMETERS_SCHEMA
+        end
+
+        def tool_for(tool)
+          parameters_schema = parameters_schema_for(tool)
+
+          definition = {
+            type: 'function',
+            function: {
+              name: tool.name,
+              description: tool.description,
+              parameters: parameters_schema
+            }
+          }
+
+          return definition if tool.provider_params.empty?
+
+          RubyLLM::Utils.deep_merge(definition, tool.provider_params)
+        end
+
+        def param_schema(param)
+          {
+            type: param.type,
+            description: param.description
+          }.compact
+        end
+
+        def format_tool_calls(tool_calls)
+          return nil unless tool_calls&.any?
+
+          tool_calls.map do |_, tc|
+            {
+              id: tc.id,
+              type: 'function',
+              function: {
+                name: tc.name,
+                arguments: JSON.generate(tc.arguments)
+              }
+            }
+          end
+        end
+
+        def parse_tool_call_arguments(tool_call)
+          arguments = tool_call.dig('function', 'arguments')
+
+          if arguments.nil? || arguments.empty?
+            {}
+          else
+            JSON.parse(arguments)
+          end
+        end
+
+        def parse_tool_calls(tool_calls, parse_arguments: true)
+          return nil unless tool_calls&.any?
+
+          tool_calls.to_h do |tc|
+            [
+              tc['id'],
+              ToolCall.new(
+                id: tc['id'],
+                name: tc.dig('function', 'name'),
+                arguments: if parse_arguments
+                             parse_tool_call_arguments(tc)
+                           else
+                             tc.dig('function', 'arguments')
+                           end
+              )
+            ]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/providers/openai/transcription.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    class OpenAI
+      # Audio transcription methods for the OpenAI API integration
+      module Transcription
+        module_function
+
+        def transcription_url
+          'audio/transcriptions'
+        end
+
+        def render_transcription_payload(file_part, model:, language:, **options)
+          {
+            model: model,
+            file: file_part,
+            language: language,
+            chunking_strategy: (options[:chunking_strategy] || 'auto' if supports_chunking_strategy?(model, options)),
+            response_format: response_format_for(model, options),
+            prompt: options[:prompt],
+            temperature: options[:temperature],
+            timestamp_granularities: options[:timestamp_granularities],
+            known_speaker_names: options[:speaker_names],
+            known_speaker_references: encode_speaker_references(options[:speaker_references])
+          }.compact
+        end
+
+        def encode_speaker_references(references)
+          return nil unless references
+
+          references.map do |ref|
+            Attachment.new(ref).for_llm
+          end
+        end
+
+        def response_format_for(model, options)
+          return options[:response_format] if options.key?(:response_format)
+
+          'diarized_json' if model.include?('diarize')
+        end
+
+        def supports_chunking_strategy?(model, options)
+          return false if model.start_with?('whisper')
+          return true if options.key?(:chunking_strategy)
+
+          model.include?('diarize')
+        end
+
+        def parse_transcription_response(response, model:)
+          data = response.body
+
+          return RubyLLM::Transcription.new(text: data, model: model) if data.is_a?(String)
+
+          usage = data['usage'] || {}
+
+          RubyLLM::Transcription.new(
+            text: data['text'],
+            model: model,
+            language: data['language'],
+            duration: data['duration'],
+            segments: data['segments'],
+            input_tokens: usage['input_tokens'] || usage['prompt_tokens'],
+            output_tokens: usage['output_tokens'] || usage['completion_tokens']
+          )
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/providers/openai.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    # OpenAI API integration.
+    class OpenAI < Provider
+      include OpenAI::Chat
+      include OpenAI::Embeddings
+      include OpenAI::Models
+      include OpenAI::Moderation
+      include OpenAI::Streaming
+      include OpenAI::Tools
+      include OpenAI::Images
+      include OpenAI::Media
+      include OpenAI::Transcription
+
+      def api_base
+        @config.openai_api_base || 'https://api.openai.com/v1'
+      end
+
+      def headers
+        {
+          'Authorization' => "Bearer #{@config.openai_api_key}",
+          'OpenAI-Organization' => @config.openai_organization_id,
+          'OpenAI-Project' => @config.openai_project_id
+        }.compact
+      end
+
+      def maybe_normalize_temperature(temperature, model)
+        OpenAI::Capabilities.normalize_temperature(temperature, model.id)
+      end
+
+      class << self
+        def capabilities
+          OpenAI::Capabilities
+        end
+
+        def configuration_requirements
+          %i[openai_api_key]
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/providers/openai_responses.rb

@@ -0,0 +1,395 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    # OpenAI Responses API provider.
+    # Uses v1/responses endpoint instead of v1/chat/completions.
+    # Inherits from OpenAI and overrides only what differs.
+    class OpenAIResponses < OpenAI
+      attr_reader :responses_session, :responses_config
+
+      def initialize(config, responses_session = nil, responses_config = {})
+        @responses_session = responses_session || ResponsesSession.new
+        @responses_config = {
+          stateful: false,
+          store: true,
+          truncation: :disabled,
+          include: []
+        }.merge(responses_config)
+
+        super(config)
+      end
+
+      # Override endpoint URL - no conditionals needed
+      def completion_url
+        'responses'
+      end
+
+      # Override complete to handle response ID failures
+      def complete(messages, tools:, temperature:, model:, params: {}, headers: {}, schema: nil, &block) # rubocop:disable Metrics/ParameterLists
+        super
+      rescue BadRequestError => e
+        raise unless response_id_not_found_error?(e)
+
+        handle_response_id_failure
+        retry
+      end
+
+      # Override render_payload for Responses API format
+      def render_payload(messages, tools:, temperature:, model:, stream: false, schema: nil) # rubocop:disable Metrics/ParameterLists
+        system_msgs, other_msgs = partition_messages(messages)
+
+        payload = build_base_payload(model, stream)
+        add_instructions(payload, system_msgs)
+        add_input(payload, other_msgs)
+        add_temperature(payload, temperature)
+        add_tools(payload, tools)
+        add_schema(payload, schema)
+        add_optional_parameters(payload)
+        add_stream_options(payload, stream)
+
+        payload
+      end
+
+      # Override parse_completion_response for Responses API format
+      def parse_completion_response(response)
+        data = response.body
+        return if data.nil? || !data.is_a?(Hash) || data.empty?
+
+        # Check status first to handle failed responses appropriately
+        case data['status']
+        when 'completed'
+          parse_completed_response(data, response)
+        when 'failed'
+          raise ResponseFailedError.new(response, data.dig('error', 'message') || 'Response failed')
+        when 'in_progress', 'queued'
+          raise ResponseInProgressError.new(response, "Response still processing: #{data['id']}")
+        when 'cancelled'
+          raise ResponseCancelledError.new(response, "Response was cancelled: #{data['id']}")
+        when 'incomplete'
+          parse_incomplete_response(data, response)
+        else
+          # For responses without status, check for error
+          raise Error.new(response, data.dig('error', 'message')) if data.dig('error', 'message')
+
+          parse_completed_response(data, response)
+        end
+      end
+
+      # Override tool_for for flat format (not nested under 'function')
+      def tool_for(tool)
+        parameters_schema = parameters_schema_for(tool)
+
+        definition = {
+          type: 'function',
+          name: tool.name,
+          description: tool.description,
+          parameters: parameters_schema
+        }
+
+        return definition if tool.provider_params.empty?
+
+        RubyLLM::Utils.deep_merge(definition, tool.provider_params)
+      end
+
+      # Override build_chunk for Responses API streaming events
+      def build_chunk(data)
+        if responses_api_event?(data)
+          build_responses_chunk(data)
+        else
+          super
+        end
+      end
+
+      private
+
+      def stateful_mode?
+        @responses_config[:stateful] == true
+      end
+
+      def partition_messages(messages)
+        system_msgs = messages.select { |m| m.role == :system }
+        other_msgs = messages.reject { |m| m.role == :system }
+        [system_msgs, other_msgs]
+      end
+
+      def build_base_payload(model, stream)
+        {
+          model: model.id,
+          stream: stream,
+          store: @responses_config[:store]
+        }
+      end
+
+      def add_instructions(payload, system_msgs)
+        payload[:instructions] = format_instructions(system_msgs) if system_msgs.any?
+      end
+
+      def add_input(payload, other_msgs)
+        if stateful_mode? && @responses_session.valid?
+          payload[:previous_response_id] = @responses_session.response_id
+          payload[:input] = format_new_input_only(other_msgs)
+        else
+          payload[:input] = format_responses_input(other_msgs)
+        end
+      end
+
+      def add_temperature(payload, temperature)
+        payload[:temperature] = temperature unless temperature.nil?
+      end
+
+      def add_tools(payload, tools)
+        payload[:tools] = tools.map { |_, tool| tool_for(tool) } if tools.any?
+      end
+
+      def add_schema(payload, schema)
+        return unless schema
+
+        payload[:text] = {
+          format: {
+            type: 'json_schema',
+            name: 'response',
+            schema: schema,
+            strict: schema[:strict] != false
+          }
+        }
+      end
+
+      def add_stream_options(payload, stream)
+        payload[:stream_options] = { include_usage: true } if stream
+      end
+
+      def response_id_not_found_error?(error)
+        return false unless @responses_session.response_id
+
+        error.message.include?('not found')
+      end
+
+      def handle_response_id_failure
+        @responses_session.record_failure!
+
+        if @responses_session.disabled?
+          RubyLLM.logger.warn('Responses API: Disabling stateful mode after repeated failures')
+        else
+          RubyLLM.logger.debug('Responses API: Response ID not found, retrying fresh')
+        end
+      end
+
+      def format_instructions(system_messages)
+        system_messages.map { |m| m.content.to_s }.join("\n\n")
+      end
+
+      def format_responses_input(messages)
+        messages.filter_map do |msg|
+          case msg.role
+          when :user
+            {
+              type: 'message',
+              role: 'user',
+              content: format_input_content(msg.content)
+            }
+          when :assistant
+            next if msg.content.nil? || msg.content.to_s.strip.empty?
+
+            {
+              type: 'message',
+              role: 'assistant',
+              content: format_output_content(msg.content)
+            }
+          when :tool
+            {
+              type: 'function_call_output',
+              call_id: msg.tool_call_id,
+              output: msg.content.to_s
+            }
+          end
+        end
+      end
+
+      def format_new_input_only(messages)
+        formatted = []
+        last_assistant_idx = messages.rindex { |msg| msg.role == :assistant }
+
+        if last_assistant_idx
+          new_messages = messages[(last_assistant_idx + 1)..]
+          new_messages.each do |msg|
+            case msg.role
+            when :tool
+              formatted << {
+                type: 'function_call_output',
+                call_id: msg.tool_call_id,
+                output: msg.content.to_s
+              }
+            when :user
+              formatted << {
+                type: 'message',
+                role: 'user',
+                content: format_input_content(msg.content)
+              }
+            end
+          end
+        else
+          messages.each do |msg|
+            next unless msg.role == :user
+
+            formatted << {
+              type: 'message',
+              role: 'user',
+              content: format_input_content(msg.content)
+            }
+          end
+        end
+
+        formatted
+      end
+
+      def format_input_content(content)
+        case content
+        when String
+          [{ type: 'input_text', text: content }]
+        when Content
+          parts = []
+          parts << { type: 'input_text', text: content.text } if content.text && !content.text.empty?
+          content.attachments.each do |attachment|
+            parts << format_input_attachment(attachment)
+          end
+          parts
+        when Content::Raw
+          content.value
+        else
+          [{ type: 'input_text', text: content.to_s }]
+        end
+      end
+
+      def format_output_content(content)
+        if content.is_a?(String)
+          [{ type: 'output_text', text: content }]
+        elsif content.is_a?(Content)
+          [{ type: 'output_text', text: content.text || '' }]
+        else
+          [{ type: 'output_text', text: content.to_s }]
+        end
+      end
+
+      def format_input_attachment(attachment)
+        case attachment.type
+        when :image
+          if attachment.url?
+            { type: 'input_image', image_url: attachment.source.to_s }
+          else
+            { type: 'input_image', image_url: attachment.for_llm }
+          end
+        when :file, :pdf
+          { type: 'input_file', file_data: attachment.encoded, filename: attachment.filename }
+        else
+          { type: 'input_text', text: "[Unsupported attachment: #{attachment.type}]" }
+        end
+      end
+
+      def add_optional_parameters(payload)
+        if @responses_config[:truncation] && @responses_config[:truncation] != :disabled
+          payload[:truncation] = @responses_config[:truncation].to_s
+        end
+
+        if @responses_config[:include] && !@responses_config[:include].empty?
+          payload[:include] = @responses_config[:include].map { |i| i.to_s.tr('_', '.') }
+        end
+
+        payload[:service_tier] = @responses_config[:service_tier].to_s if @responses_config[:service_tier]
+        payload[:max_tool_calls] = @responses_config[:max_tool_calls] if @responses_config[:max_tool_calls]
+      end
+
+      def parse_completed_response(data, response)
+        output = data['output'] || []
+        content_parts = []
+        tool_calls = {}
+
+        output.each do |item|
+          case item['type']
+          when 'message'
+            content_parts << extract_message_content(item)
+          when 'function_call'
+            tool_calls[item['call_id']] = ToolCall.new(
+              id: item['call_id'],
+              name: item['name'],
+              arguments: parse_tool_arguments(item['arguments'])
+            )
+          end
+        end
+
+        usage = data['usage'] || {}
+
+        Message.new(
+          role: :assistant,
+          content: content_parts.join("\n"),
+          tool_calls: tool_calls.empty? ? nil : tool_calls,
+          response_id: data['id'],
+          reasoning_summary: data.dig('reasoning', 'summary'),
+          reasoning_tokens: usage.dig('output_tokens_details', 'reasoning_tokens'),
+          input_tokens: usage['input_tokens'] || 0,
+          output_tokens: usage['output_tokens'] || 0,
+          cached_tokens: usage.dig('prompt_tokens_details', 'cached_tokens'),
+          cache_creation_tokens: 0,
+          model_id: data['model'],
+          raw: response
+        )
+      end
+
+      def parse_tool_arguments(arguments)
+        if arguments.nil? || arguments.empty?
+          {}
+        elsif arguments.is_a?(String)
+          JSON.parse(arguments)
+        else
+          arguments
+        end
+      rescue JSON::ParserError
+        {}
+      end
+
+      def parse_incomplete_response(data, response)
+        message = parse_completed_response(data, response)
+        RubyLLM.logger.warn("Responses API: Incomplete response: #{data['incomplete_details']}")
+        message
+      end
+
+      def extract_message_content(item)
+        return '' unless item['content'].is_a?(Array)
+
+        item['content'].filter_map do |content_item|
+          content_item['text'] if content_item['type'] == 'output_text'
+        end.join
+      end
+
+      def responses_api_event?(data)
+        data.is_a?(Hash) && data['type']&.start_with?('response.')
+      end
+
+      def build_responses_chunk(data)
+        case data['type']
+        when 'response.content_part.delta'
+          Chunk.new(
+            role: :assistant,
+            content: data.dig('delta', 'text') || '',
+            model_id: nil,
+            input_tokens: nil,
+            output_tokens: nil
+          )
+        when 'response.completed'
+          usage = data.dig('response', 'usage') || {}
+          Chunk.new(
+            role: :assistant,
+            content: nil,
+            model_id: data.dig('response', 'model'),
+            input_tokens: usage['input_tokens'],
+            output_tokens: usage['output_tokens'],
+            cached_tokens: usage.dig('prompt_tokens_details', 'cached_tokens'),
+            cache_creation_tokens: 0
+          )
+        else
+          Chunk.new(role: :assistant, content: nil, model_id: nil, input_tokens: nil, output_tokens: nil)
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/providers/openrouter/models.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    class OpenRouter
+      # Models methods of the OpenRouter API integration
+      module Models
+        module_function
+
+        def models_url
+          'models'
+        end
+
+        def parse_list_models_response(response, slug, _capabilities)
+          Array(response.body['data']).map do |model_data| # rubocop:disable Metrics/BlockLength
+            modalities = {
+              input: Array(model_data.dig('architecture', 'input_modalities')),
+              output: Array(model_data.dig('architecture', 'output_modalities'))
+            }
+
+            pricing = { text_tokens: { standard: {} } }
+
+            pricing_types = {
+              prompt: :input_per_million,
+              completion: :output_per_million,
+              input_cache_read: :cached_input_per_million,
+              internal_reasoning: :reasoning_output_per_million
+            }
+
+            pricing_types.each do |source_key, target_key|
+              value = model_data.dig('pricing', source_key.to_s).to_f
+              pricing[:text_tokens][:standard][target_key] = value * 1_000_000 if value.positive?
+            end
+
+            capabilities = supported_parameters_to_capabilities(model_data['supported_parameters'])
+
+            Model::Info.new(
+              id: model_data['id'],
+              name: model_data['name'],
+              provider: slug,
+              family: model_data['id'].split('/').first,
+              created_at: model_data['created'] ? Time.at(model_data['created']) : nil,
+              context_window: model_data['context_length'],
+              max_output_tokens: model_data.dig('top_provider', 'max_completion_tokens'),
+              modalities: modalities,
+              capabilities: capabilities,
+              pricing: pricing,
+              metadata: {
+                description: model_data['description'],
+                architecture: model_data['architecture'],
+                top_provider: model_data['top_provider'],
+                per_request_limits: model_data['per_request_limits'],
+                supported_parameters: model_data['supported_parameters']
+              }
+            )
+          end
+        end
+
+        def supported_parameters_to_capabilities(params)
+          return [] unless params
+
+          capabilities = []
+          capabilities << 'streaming'
+          capabilities << 'function_calling' if params.include?('tools') || params.include?('tool_choice')
+          capabilities << 'structured_output' if params.include?('response_format')
+          capabilities << 'batch' if params.include?('batch')
+          capabilities << 'predicted_outputs' if params.include?('logit_bias') && params.include?('top_k')
+          capabilities
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/providers/openrouter.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    # OpenRouter API integration.
+    class OpenRouter < OpenAI
+      include OpenRouter::Models
+
+      def api_base
+        'https://openrouter.ai/api/v1'
+      end
+
+      def headers
+        {
+          'Authorization' => "Bearer #{@config.openrouter_api_key}"
+        }
+      end
+
+      class << self
+        def configuration_requirements
+          %i[openrouter_api_key]
+        end
+      end
+    end
+  end
+end