ruby_llm-responses_api 0.1.0

data/lib/ruby_llm/providers/openai_responses/capabilities.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    class OpenAIResponses
+      # Model capabilities for OpenAI Responses API models.
+      # Defines which models support which features.
+      module Capabilities
+        module_function
+
+        # Models that support the Responses API
+        RESPONSES_API_MODELS = %w[
+          gpt-4o gpt-4o-mini gpt-4o-2024-05-13 gpt-4o-2024-08-06 gpt-4o-2024-11-20
+          gpt-4o-mini-2024-07-18
+          gpt-4.1 gpt-4.1-mini gpt-4.1-nano
+          gpt-4-turbo gpt-4-turbo-2024-04-09 gpt-4-turbo-preview
+          o1 o1-mini o1-preview o1-2024-12-17
+          o3 o3-mini o4-mini
+          chatgpt-4o-latest
+        ].freeze
+
+        # Models with vision capabilities
+        VISION_MODELS = %w[
+          gpt-4o gpt-4o-mini gpt-4o-2024-05-13 gpt-4o-2024-08-06 gpt-4o-2024-11-20
+          gpt-4o-mini-2024-07-18
+          gpt-4.1 gpt-4.1-mini gpt-4.1-nano
+          gpt-4-turbo gpt-4-turbo-2024-04-09
+          o1 o3 o4-mini
+          chatgpt-4o-latest
+        ].freeze
+
+        # Reasoning models (o-series)
+        REASONING_MODELS = %w[o1 o1-mini o1-preview o1-2024-12-17 o3 o3-mini o4-mini].freeze
+
+        # Models that support web search
+        WEB_SEARCH_MODELS = %w[
+          gpt-4o gpt-4o-mini gpt-4.1 gpt-4.1-mini gpt-4.1-nano
+          o1 o3 o3-mini o4-mini
+        ].freeze
+
+        # Models that support code interpreter
+        CODE_INTERPRETER_MODELS = %w[
+          gpt-4o gpt-4o-mini gpt-4.1 gpt-4.1-mini gpt-4.1-nano
+          o1 o3 o3-mini o4-mini
+        ].freeze
+
+        # Context windows by model
+        CONTEXT_WINDOWS = {
+          'gpt-4o' => 128_000,
+          'gpt-4o-mini' => 128_000,
+          'gpt-4o-2024-05-13' => 128_000,
+          'gpt-4o-2024-08-06' => 128_000,
+          'gpt-4o-2024-11-20' => 128_000,
+          'gpt-4o-mini-2024-07-18' => 128_000,
+          'gpt-4.1' => 1_000_000,
+          'gpt-4.1-mini' => 1_000_000,
+          'gpt-4.1-nano' => 1_000_000,
+          'gpt-4-turbo' => 128_000,
+          'gpt-4-turbo-2024-04-09' => 128_000,
+          'o1' => 200_000,
+          'o1-mini' => 128_000,
+          'o1-preview' => 128_000,
+          'o3' => 200_000,
+          'o3-mini' => 200_000,
+          'o4-mini' => 200_000
+        }.freeze
+
+        # Max output tokens by model
+        MAX_OUTPUT_TOKENS = {
+          'gpt-4o' => 16_384,
+          'gpt-4o-mini' => 16_384,
+          'gpt-4o-2024-05-13' => 4_096,
+          'gpt-4o-2024-08-06' => 16_384,
+          'gpt-4o-2024-11-20' => 16_384,
+          'gpt-4o-mini-2024-07-18' => 16_384,
+          'gpt-4.1' => 32_768,
+          'gpt-4.1-mini' => 32_768,
+          'gpt-4.1-nano' => 32_768,
+          'gpt-4-turbo' => 4_096,
+          'o1' => 100_000,
+          'o1-mini' => 65_536,
+          'o3' => 100_000,
+          'o3-mini' => 100_000,
+          'o4-mini' => 100_000
+        }.freeze
+
+        # Pricing per million tokens (as of late 2024)
+        PRICING = {
+          'gpt-4o' => { input: 2.50, output: 10.00, cached_input: 1.25 },
+          'gpt-4o-mini' => { input: 0.15, output: 0.60, cached_input: 0.075 },
+          'gpt-4.1' => { input: 2.00, output: 8.00, cached_input: 0.50 },
+          'gpt-4.1-mini' => { input: 0.40, output: 1.60, cached_input: 0.10 },
+          'gpt-4.1-nano' => { input: 0.10, output: 0.40, cached_input: 0.025 },
+          'o1' => { input: 15.00, output: 60.00, cached_input: 7.50 },
+          'o1-mini' => { input: 1.10, output: 4.40, cached_input: 0.55 },
+          'o3' => { input: 10.00, output: 40.00, cached_input: 2.50 },
+          'o3-mini' => { input: 1.10, output: 4.40, cached_input: 0.275 },
+          'o4-mini' => { input: 1.10, output: 4.40, cached_input: 0.275 }
+        }.freeze
+
+        def supports_responses_api?(model_id)
+          model_matches?(model_id, RESPONSES_API_MODELS)
+        end
+
+        def supports_vision?(model_id)
+          model_matches?(model_id, VISION_MODELS)
+        end
+
+        def supports_functions?(model_id)
+          supports_responses_api?(model_id)
+        end
+
+        def supports_structured_output?(model_id)
+          supports_responses_api?(model_id)
+        end
+
+        def supports_web_search?(model_id)
+          model_matches?(model_id, WEB_SEARCH_MODELS)
+        end
+
+        def supports_code_interpreter?(model_id)
+          model_matches?(model_id, CODE_INTERPRETER_MODELS)
+        end
+
+        def reasoning_model?(model_id)
+          model_matches?(model_id, REASONING_MODELS)
+        end
+
+        def context_window_for(model_id)
+          find_capability(model_id, CONTEXT_WINDOWS) || 128_000
+        end
+
+        def max_tokens_for(model_id)
+          find_capability(model_id, MAX_OUTPUT_TOKENS) || 16_384
+        end
+
+        def input_price_for(model_id)
+          pricing = find_capability(model_id, PRICING)
+          pricing ? pricing[:input] : 0.0
+        end
+
+        def output_price_for(model_id)
+          pricing = find_capability(model_id, PRICING)
+          pricing ? pricing[:output] : 0.0
+        end
+
+        def pricing_for(model_id)
+          pricing = find_capability(model_id, PRICING) || { input: 0.0, output: 0.0 }
+          {
+            text_tokens: {
+              standard: {
+                input_per_million: pricing[:input],
+                output_per_million: pricing[:output],
+                cached_input_per_million: pricing[:cached_input] || (pricing[:input] / 2)
+              }
+            }
+          }
+        end
+
+        def modalities_for(model_id)
+          input = ['text']
+          input << 'image' if supports_vision?(model_id)
+
+          {
+            input: input,
+            output: ['text']
+          }
+        end
+
+        def capabilities_for(model_id)
+          caps = %w[streaming function_calling structured_output]
+          caps << 'vision' if supports_vision?(model_id)
+          caps << 'web_search' if supports_web_search?(model_id)
+          caps << 'code_interpreter' if supports_code_interpreter?(model_id)
+          caps << 'reasoning' if reasoning_model?(model_id)
+          caps
+        end
+
+        def model_family(model_id)
+          case model_id
+          when /^gpt-4\.1/ then 'gpt-4.1'
+          when /^gpt-4o-mini/ then 'gpt-4o-mini'
+          when /^gpt-4o/ then 'gpt-4o'
+          when /^gpt-4-turbo/ then 'gpt-4-turbo'
+          when /^o1/ then 'o1'
+          when /^o3/ then 'o3'
+          when /^o4/ then 'o4'
+          else 'other'
+          end
+        end
+
+        def format_display_name(model_id)
+          model_id
+            .gsub(/[-_]/, ' ')
+            .split
+            .map(&:capitalize)
+            .join(' ')
+        end
+
+        # Temperature is not supported for reasoning models
+        def normalize_temperature(temperature, model_id)
+          return nil if reasoning_model?(model_id)
+
+          temperature
+        end
+
+        private_class_method def find_capability(model_id, mapping)
+          # Direct match
+          return mapping[model_id] if mapping.key?(model_id)
+
+          # Try base model name (without date suffix)
+          base_model = model_id.gsub(/-\d{4}-\d{2}-\d{2}$/, '')
+          return mapping[base_model] if mapping.key?(base_model)
+
+          nil
+        end
+
+        private_class_method def model_matches?(model_id, model_list)
+          model_list.any? do |pattern|
+            model_id == pattern || model_id.start_with?("#{pattern}-")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/providers/openai_responses/chat.rb

@@ -0,0 +1,265 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    class OpenAIResponses
+      # Chat completion methods for the OpenAI Responses API.
+      # Handles converting RubyLLM messages to Responses API format and parsing responses.
+      module Chat
+        def completion_url
+          'responses'
+        end
+
+        module_function
+
+        def render_payload(messages, tools:, temperature:, model:, stream: false, schema: nil) # rubocop:disable Metrics/ParameterLists
+          # Extract system messages for instructions
+          system_messages = messages.select { |m| m.role == :system }
+          non_system_messages = messages.reject { |m| m.role == :system }
+
+          instructions = system_messages.map { |m| extract_text_content(m.content) }.join("\n\n")
+
+          payload = {
+            model: model.id,
+            input: format_input(non_system_messages),
+            stream: stream
+          }
+
+          payload[:instructions] = instructions unless instructions.empty?
+          payload[:temperature] = temperature unless temperature.nil?
+
+          payload[:tools] = tools.map { |_, tool| tool_for(tool) } if tools.any?
+
+          if schema
+            payload[:text] = {
+              format: {
+                type: 'json_schema',
+                name: 'response',
+                schema: schema,
+                strict: schema[:strict] != false
+              }
+            }
+          end
+
+          # Auto-chain conversations: find the last response_id from assistant messages
+          # This enables automatic stateful conversations without manual tracking
+          last_response_id = extract_last_response_id(messages)
+          payload[:previous_response_id] = last_response_id if last_response_id
+
+          payload
+        end
+
+        def extract_last_response_id(messages)
+          messages
+            .select { |m| m.role == :assistant && m.respond_to?(:response_id) }
+            .map(&:response_id)
+            .compact
+            .last
+        end
+
+        def parse_completion_response(response)
+          data = response.body
+          return if data.nil? || data.empty?
+
+          data = JSON.parse(data) if data.is_a?(String)
+
+          raise RubyLLM::Error.new(response, data.dig('error', 'message')) if data.dig('error', 'message')
+
+          output = data['output'] || []
+
+          # Extract text content from output
+          content = extract_output_text(output)
+
+          # Extract tool calls from function_call outputs
+          tool_calls = extract_tool_calls(output)
+
+          usage = data['usage'] || {}
+          cached_tokens = usage.dig('input_tokens_details', 'cached_tokens')
+
+          Message.new(
+            role: :assistant,
+            content: content,
+            tool_calls: tool_calls,
+            input_tokens: usage['input_tokens'],
+            output_tokens: usage['output_tokens'],
+            cached_tokens: cached_tokens,
+            cache_creation_tokens: 0,
+            model_id: data['model'],
+            response_id: data['id'],
+            raw: response
+          )
+        end
+
+        def format_input(messages) # rubocop:disable Metrics/MethodLength
+          result = []
+
+          messages.each do |msg|
+            if msg.tool_call_id
+              # Tool result message - function_call_output type
+              result << {
+                type: 'function_call_output',
+                call_id: msg.tool_call_id,
+                output: extract_text_content(msg.content)
+              }
+            elsif msg.tool_calls&.any?
+              # Assistant message with tool calls
+              # First add any text content as a message
+              text = extract_text_content(msg.content)
+              if text && !text.empty?
+                result << {
+                  type: 'message',
+                  role: 'assistant',
+                  content: text
+                }
+              end
+
+              # Then add each function call as a separate item
+              msg.tool_calls.each_value do |tc|
+                result << {
+                  type: 'function_call',
+                  call_id: tc.id,
+                  name: tc.name,
+                  arguments: tc.arguments.is_a?(String) ? tc.arguments : JSON.generate(tc.arguments)
+                }
+              end
+            else
+              # Regular message
+              result << {
+                type: 'message',
+                role: format_role(msg.role),
+                content: format_message_content(msg.content, nil)
+              }
+            end
+          end
+
+          result
+        end
+
+        def format_message_content(content, tool_calls = nil)
+          parts = []
+
+          # Add text content
+          text = extract_text_content(content)
+          parts << { type: 'input_text', text: text } if text && !text.empty?
+
+          # Add attachments if present
+          if content.is_a?(RubyLLM::Content)
+            content.attachments.each do |attachment|
+              parts << format_attachment(attachment)
+            end
+          end
+
+          # Add tool calls if present (for assistant messages)
+          if tool_calls&.any?
+            tool_calls.each_value do |tc|
+              parts << {
+                type: 'function_call',
+                call_id: tc.id,
+                name: tc.name,
+                arguments: tc.arguments.is_a?(String) ? tc.arguments : JSON.generate(tc.arguments)
+              }
+            end
+          end
+
+          # Return simple text for single text content
+          return parts.first[:text] if parts.length == 1 && parts.first[:type] == 'input_text'
+
+          parts
+        end
+
+        def format_attachment(attachment)
+          case attachment.type
+          when :image
+            if attachment.url?
+              { type: 'input_image', image_url: attachment.source }
+            else
+              { type: 'input_image', image_url: attachment.for_llm }
+            end
+          when :pdf
+            {
+              type: 'input_file',
+              filename: File.basename(attachment.source.to_s),
+              file_data: attachment.for_llm
+            }
+          when :audio
+            {
+              type: 'input_audio',
+              data: attachment.for_llm,
+              format: detect_audio_format(attachment.source)
+            }
+          else
+            { type: 'input_text', text: "[Unsupported attachment: #{attachment.type}]" }
+          end
+        end
+
+        def detect_audio_format(source)
+          ext = File.extname(source.to_s).downcase
+          case ext
+          when '.mp3' then 'mp3'
+          when '.wav' then 'wav'
+          when '.webm' then 'webm'
+          when '.ogg' then 'ogg'
+          when '.flac' then 'flac'
+          else 'mp3'
+          end
+        end
+
+        def extract_text_content(content)
+          case content
+          when String
+            content
+          when RubyLLM::Content
+            content.text
+          when Hash
+            content[:text] || content['text']
+          else
+            content.to_s
+          end
+        end
+
+        def format_role(role)
+          case role
+          when :system then 'developer'
+          when :assistant then 'assistant'
+          when :tool then 'user' # Tool results come from user perspective
+          else role.to_s
+          end
+        end
+
+        def extract_output_text(output)
+          output
+            .select { |item| item['type'] == 'message' }
+            .flat_map { |item| item['content'] || [] }
+            .select { |c| c['type'] == 'output_text' }
+            .map { |c| c['text'] }
+            .join
+        end
+
+        def extract_tool_calls(output)
+          function_calls = output.select { |item| item['type'] == 'function_call' }
+          return nil if function_calls.empty?
+
+          function_calls.to_h do |fc|
+            [
+              fc['call_id'],
+              ToolCall.new(
+                id: fc['call_id'],
+                name: fc['name'],
+                arguments: parse_arguments(fc['arguments'])
+              )
+            ]
+          end
+        end
+
+        def parse_arguments(arguments)
+          return {} if arguments.nil? || arguments.empty?
+          return arguments if arguments.is_a?(Hash)
+
+          JSON.parse(arguments)
+        rescue JSON::ParserError
+          { raw: arguments }
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/providers/openai_responses/media.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    class OpenAIResponses
+      # Media handling methods for the OpenAI Responses API.
+      # Handles images, audio, PDFs, and other file types.
+      module Media
+        module_function
+
+        def format_content(content)
+          return content if content.is_a?(RubyLLM::Content::Raw)
+          return content unless content.is_a?(RubyLLM::Content)
+
+          parts = []
+          parts << format_text(content.text) if content.text && !content.text.empty?
+
+          content.attachments.each do |attachment|
+            parts << format_attachment(attachment)
+          end
+
+          # Return simple string for text-only content
+          return content.text if parts.length == 1 && parts.first[:type] == 'input_text'
+
+          parts
+        end
+
+        def format_text(text)
+          { type: 'input_text', text: text }
+        end
+
+        def format_attachment(attachment)
+          case attachment.type
+          when :image
+            format_image(attachment)
+          when :pdf
+            format_pdf(attachment)
+          when :audio
+            format_audio(attachment)
+          else
+            format_unknown(attachment)
+          end
+        end
+
+        def format_image(image)
+          if image.url?
+            {
+              type: 'input_image',
+              image_url: image.source
+            }
+          else
+            {
+              type: 'input_image',
+              image_url: image.for_llm
+            }
+          end
+        end
+
+        def format_pdf(pdf)
+          {
+            type: 'input_file',
+            filename: extract_filename(pdf.source),
+            file_data: pdf.for_llm
+          }
+        end
+
+        def format_audio(audio)
+          {
+            type: 'input_audio',
+            data: audio.for_llm,
+            format: detect_audio_format(audio.source)
+          }
+        end
+
+        def format_unknown(attachment)
+          {
+            type: 'input_text',
+            text: "[Attachment: #{attachment.type}]"
+          }
+        end
+
+        def extract_filename(source)
+          return 'file' unless source
+
+          if source.respond_to?(:path)
+            File.basename(source.path)
+          else
+            File.basename(source.to_s)
+          end
+        end
+
+        def detect_audio_format(source)
+          return 'mp3' unless source
+
+          ext = if source.respond_to?(:path)
+                  File.extname(source.path)
+                else
+                  File.extname(source.to_s)
+                end
+
+          case ext.downcase
+          when '.mp3' then 'mp3'
+          when '.wav' then 'wav'
+          when '.webm' then 'webm'
+          when '.ogg' then 'ogg'
+          when '.flac' then 'flac'
+          when '.m4a' then 'm4a'
+          else 'mp3'
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/providers/openai_responses/message_extension.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    class OpenAIResponses
+      # Extends RubyLLM::Message to support response_id for stateful conversations
+      module MessageExtension
+        attr_accessor :response_id
+
+        def self.included(base)
+          base.class_eval do
+            alias_method :original_initialize, :initialize
+
+            define_method(:initialize) do |options = {}|
+              original_initialize(options)
+              @response_id = options[:response_id]
+            end
+
+            alias_method :original_to_h, :to_h
+
+            define_method(:to_h) do
+              original_to_h.merge(response_id: response_id).compact
+            end
+          end
+        end
+      end
+    end
+  end
+end
+
+# Apply the extension to RubyLLM::Message
+RubyLLM::Message.include(RubyLLM::Providers::OpenAIResponses::MessageExtension)