ruby_llm-responses_api 0.1.0

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

@@ -0,0 +1,257 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    class OpenAIResponses
+      # Registers OpenAI Responses API models with RubyLLM
+      # Models updated January 2026 based on OpenAI documentation
+      module ModelRegistry
+        MODELS = [
+          # ===================
+          # GPT-5.2 Series (Latest flagship - December 2025)
+          # ===================
+          {
+            id: 'gpt-5.2',
+            name: 'GPT-5.2',
+            provider: 'openai_responses',
+            family: 'gpt-5.2',
+            context_window: 400_000,
+            max_output_tokens: 128_000,
+            modalities: { input: %w[text image], output: ['text'] },
+            capabilities: %w[streaming function_calling structured_output vision reasoning web_search code_interpreter]
+          },
+
+          # ===================
+          # GPT-5.1 Series (November 2025)
+          # ===================
+          {
+            id: 'gpt-5.1',
+            name: 'GPT-5.1',
+            provider: 'openai_responses',
+            family: 'gpt-5.1',
+            context_window: 400_000,
+            max_output_tokens: 128_000,
+            modalities: { input: %w[text image], output: ['text'] },
+            capabilities: %w[streaming function_calling structured_output vision reasoning web_search code_interpreter]
+          },
+          {
+            id: 'gpt-5.1-codex-max',
+            name: 'GPT-5.1 Codex Max',
+            provider: 'openai_responses',
+            family: 'gpt-5.1',
+            context_window: 400_000,
+            max_output_tokens: 128_000,
+            modalities: { input: %w[text image], output: ['text'] },
+            capabilities: %w[streaming function_calling structured_output reasoning web_search]
+          },
+          {
+            id: 'gpt-5.1-codex',
+            name: 'GPT-5.1 Codex',
+            provider: 'openai_responses',
+            family: 'gpt-5.1',
+            context_window: 400_000,
+            max_output_tokens: 128_000,
+            modalities: { input: %w[text image], output: ['text'] },
+            capabilities: %w[streaming function_calling structured_output reasoning]
+          },
+          {
+            id: 'gpt-5.1-codex-mini',
+            name: 'GPT-5.1 Codex Mini',
+            provider: 'openai_responses',
+            family: 'gpt-5.1',
+            context_window: 400_000,
+            max_output_tokens: 128_000,
+            modalities: { input: %w[text image], output: ['text'] },
+            capabilities: %w[streaming function_calling structured_output reasoning]
+          },
+          {
+            id: 'gpt-5.1-chat',
+            name: 'GPT-5.1 Chat',
+            provider: 'openai_responses',
+            family: 'gpt-5.1',
+            context_window: 128_000,
+            max_output_tokens: 16_384,
+            modalities: { input: %w[text image], output: ['text'] },
+            capabilities: %w[streaming function_calling structured_output vision]
+          },
+
+          # ===================
+          # GPT-5 Series (August 2025)
+          # ===================
+          {
+            id: 'gpt-5',
+            name: 'GPT-5',
+            provider: 'openai_responses',
+            family: 'gpt-5',
+            context_window: 400_000,
+            max_output_tokens: 128_000,
+            modalities: { input: %w[text image], output: ['text'] },
+            capabilities: %w[streaming function_calling structured_output vision reasoning web_search code_interpreter]
+          },
+          {
+            id: 'gpt-5-pro',
+            name: 'GPT-5 Pro',
+            provider: 'openai_responses',
+            family: 'gpt-5',
+            context_window: 400_000,
+            max_output_tokens: 128_000,
+            modalities: { input: %w[text image], output: ['text'] },
+            capabilities: %w[streaming function_calling structured_output vision reasoning web_search code_interpreter]
+          },
+          {
+            id: 'gpt-5-mini',
+            name: 'GPT-5 Mini',
+            provider: 'openai_responses',
+            family: 'gpt-5',
+            context_window: 400_000,
+            max_output_tokens: 128_000,
+            modalities: { input: %w[text image], output: ['text'] },
+            capabilities: %w[streaming function_calling structured_output vision reasoning web_search code_interpreter]
+          },
+          {
+            id: 'gpt-5-nano',
+            name: 'GPT-5 Nano',
+            provider: 'openai_responses',
+            family: 'gpt-5',
+            context_window: 400_000,
+            max_output_tokens: 128_000,
+            modalities: { input: %w[text image], output: ['text'] },
+            capabilities: %w[streaming function_calling structured_output vision reasoning]
+          },
+
+          # ===================
+          # O-Series Reasoning Models
+          # ===================
+          {
+            id: 'o4-mini',
+            name: 'O4 Mini',
+            provider: 'openai_responses',
+            family: 'o4',
+            context_window: 200_000,
+            max_output_tokens: 100_000,
+            modalities: { input: %w[text image], output: ['text'] },
+            capabilities: %w[streaming function_calling structured_output vision reasoning web_search code_interpreter]
+          },
+          {
+            id: 'o3-pro',
+            name: 'O3 Pro',
+            provider: 'openai_responses',
+            family: 'o3',
+            context_window: 200_000,
+            max_output_tokens: 100_000,
+            modalities: { input: %w[text image], output: ['text'] },
+            capabilities: %w[streaming function_calling structured_output vision reasoning web_search code_interpreter]
+          },
+          {
+            id: 'o3',
+            name: 'O3',
+            provider: 'openai_responses',
+            family: 'o3',
+            context_window: 200_000,
+            max_output_tokens: 100_000,
+            modalities: { input: %w[text image], output: ['text'] },
+            capabilities: %w[streaming function_calling structured_output vision reasoning web_search code_interpreter]
+          },
+          {
+            id: 'o3-mini',
+            name: 'O3 Mini',
+            provider: 'openai_responses',
+            family: 'o3',
+            context_window: 200_000,
+            max_output_tokens: 100_000,
+            modalities: { input: ['text'], output: ['text'] },
+            capabilities: %w[streaming function_calling structured_output reasoning]
+          },
+          {
+            id: 'o1',
+            name: 'O1',
+            provider: 'openai_responses',
+            family: 'o1',
+            context_window: 200_000,
+            max_output_tokens: 100_000,
+            modalities: { input: %w[text image], output: ['text'] },
+            capabilities: %w[streaming function_calling structured_output vision reasoning]
+          },
+          {
+            id: 'o1-mini',
+            name: 'O1 Mini',
+            provider: 'openai_responses',
+            family: 'o1',
+            context_window: 128_000,
+            max_output_tokens: 65_536,
+            modalities: { input: ['text'], output: ['text'] },
+            capabilities: %w[streaming function_calling structured_output reasoning]
+          },
+
+          # ===================
+          # GPT-4.1 Series (Legacy - still supported)
+          # ===================
+          {
+            id: 'gpt-4.1',
+            name: 'GPT-4.1',
+            provider: 'openai_responses',
+            family: 'gpt-4.1',
+            context_window: 1_000_000,
+            max_output_tokens: 32_768,
+            modalities: { input: %w[text image], output: ['text'] },
+            capabilities: %w[streaming function_calling structured_output vision web_search code_interpreter]
+          },
+          {
+            id: 'gpt-4.1-mini',
+            name: 'GPT-4.1 Mini',
+            provider: 'openai_responses',
+            family: 'gpt-4.1',
+            context_window: 1_000_000,
+            max_output_tokens: 32_768,
+            modalities: { input: %w[text image], output: ['text'] },
+            capabilities: %w[streaming function_calling structured_output vision web_search code_interpreter]
+          },
+          {
+            id: 'gpt-4.1-nano',
+            name: 'GPT-4.1 Nano',
+            provider: 'openai_responses',
+            family: 'gpt-4.1',
+            context_window: 1_000_000,
+            max_output_tokens: 32_768,
+            modalities: { input: %w[text image], output: ['text'] },
+            capabilities: %w[streaming function_calling structured_output vision web_search code_interpreter]
+          },
+
+          # ===================
+          # GPT-4o Series (Legacy - still widely used)
+          # ===================
+          {
+            id: 'gpt-4o',
+            name: 'GPT-4o',
+            provider: 'openai_responses',
+            family: 'gpt-4o',
+            context_window: 128_000,
+            max_output_tokens: 16_384,
+            modalities: { input: %w[text image], output: ['text'] },
+            capabilities: %w[streaming function_calling structured_output vision web_search code_interpreter]
+          },
+          {
+            id: 'gpt-4o-mini',
+            name: 'GPT-4o Mini',
+            provider: 'openai_responses',
+            family: 'gpt-4o',
+            context_window: 128_000,
+            max_output_tokens: 16_384,
+            modalities: { input: %w[text image], output: ['text'] },
+            capabilities: %w[streaming function_calling structured_output vision web_search code_interpreter]
+          }
+        ].freeze
+
+        module_function
+
+        def register_all!
+          MODELS.each do |model_data|
+            model = RubyLLM::Model::Info.new(model_data)
+            existing = RubyLLM::Models.instance.all.find { |m| m.id == model.id && m.provider == model.provider }
+            RubyLLM::Models.instance.all << model unless existing
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    class OpenAIResponses
+      # Model listing methods for the OpenAI Responses API.
+      module Models
+        module_function
+
+        def models_url
+          'models'
+        end
+
+        def parse_list_models_response(response, slug, capabilities)
+          models_data = response.body
+          models_data = models_data['data'] if models_data.is_a?(Hash) && models_data['data']
+
+          Array(models_data).filter_map do |model_data|
+            model_id = model_data['id']
+
+            # Only include models that support the Responses API
+            next unless capabilities.supports_responses_api?(model_id)
+
+            Model::Info.new(
+              id: model_id,
+              name: capabilities.format_display_name(model_id),
+              provider: slug,
+              family: capabilities.model_family(model_id),
+              context_window: capabilities.context_window_for(model_id),
+              max_output_tokens: capabilities.max_tokens_for(model_id),
+              modalities: capabilities.modalities_for(model_id),
+              capabilities: capabilities.capabilities_for(model_id),
+              pricing: capabilities.pricing_for(model_id),
+              metadata: {
+                created_at: model_data['created'] ? Time.at(model_data['created']) : nil,
+                owned_by: model_data['owned_by'],
+                supports_responses_api: true,
+                supports_web_search: capabilities.supports_web_search?(model_id),
+                supports_code_interpreter: capabilities.supports_code_interpreter?(model_id),
+                reasoning_model: capabilities.reasoning_model?(model_id)
+              }.compact
+            )
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    class OpenAIResponses
+      # Statefulness support for the OpenAI Responses API.
+      # Handles conversation state via previous_response_id and store options.
+      module State
+        module_function
+
+        # Add state parameters to payload
+        # @param payload [Hash] The request payload
+        # @param params [Hash] Additional parameters that may contain state options
+        # @return [Hash] Updated payload with state parameters
+        def apply_state_params(payload, params)
+          # Handle previous_response_id for conversation chaining
+          payload[:previous_response_id] = params[:previous_response_id] if params[:previous_response_id]
+
+          # Handle store option (defaults to true in Responses API)
+          payload[:store] = params[:store] if params.key?(:store)
+
+          # Handle metadata
+          payload[:metadata] = params[:metadata] if params[:metadata]
+
+          payload
+        end
+
+        # Extract response ID from a completed response for chaining
+        # @param response [Hash] The API response
+        # @return [String, nil] The response ID
+        def extract_response_id(response)
+          response['id']
+        end
+
+        # Check if a response was stored
+        # @param response [Hash] The API response
+        # @return [Boolean]
+        def response_stored?(response)
+          # Responses are stored by default unless store: false was set
+          response['store'] != false
+        end
+
+        # Build parameters for continuing a conversation
+        # @param previous_response_id [String] The ID of the previous response
+        # @param store [Boolean] Whether to store this response (default: true)
+        # @return [Hash] Parameters to pass to the next request
+        def continuation_params(previous_response_id, store: true)
+          {
+            previous_response_id: previous_response_id,
+            store: store
+          }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    class OpenAIResponses
+      # Streaming methods for the OpenAI Responses API.
+      # Handles SSE events with typed event format.
+      module Streaming
+        module_function
+
+        def stream_url
+          'responses'
+        end
+
+        def build_chunk(data) # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/MethodLength
+          event_type = data['type']
+
+          case event_type
+          when 'response.output_text.delta'
+            # Text content delta
+            Chunk.new(
+              role: :assistant,
+              content: data['delta'],
+              model_id: data.dig('response', 'model')
+            )
+
+          when 'response.function_call_arguments.delta'
+            # Function call arguments streaming
+            Chunk.new(
+              role: :assistant,
+              content: nil,
+              tool_calls: build_streaming_tool_call(data),
+              model_id: data.dig('response', 'model')
+            )
+
+          when 'response.completed'
+            # Final response with usage stats
+            response_data = data['response'] || {}
+            usage = response_data['usage'] || {}
+            cached_tokens = usage.dig('input_tokens_details', 'cached_tokens')
+
+            Chunk.new(
+              role: :assistant,
+              content: nil,
+              input_tokens: usage['input_tokens'],
+              output_tokens: usage['output_tokens'],
+              cached_tokens: cached_tokens,
+              cache_creation_tokens: 0,
+              model_id: response_data['model'],
+              response_id: response_data['id']
+            )
+
+          when 'response.output_item.added'
+            # New output item started (function call, message, etc.)
+            item = data['item'] || {}
+            if item['type'] == 'function_call'
+              Chunk.new(
+                role: :assistant,
+                content: nil,
+                tool_calls: {
+                  item['call_id'] => ToolCall.new(
+                    id: item['call_id'],
+                    name: item['name'],
+                    arguments: ''
+                  )
+                }
+              )
+            else
+              # Other item types - return empty chunk
+              Chunk.new(role: :assistant, content: nil)
+            end
+
+          when 'response.content_part.added', 'response.content_part.done',
+               'response.output_item.done', 'response.output_text.done',
+               'response.function_call_arguments.done', 'response.created',
+               'response.in_progress'
+            # Status events - return empty chunk
+            Chunk.new(role: :assistant, content: nil)
+
+          when 'error'
+            # Error event
+            error_data = data['error'] || {}
+            raise RubyLLM::Error.new(nil, error_data['message'] || 'Unknown streaming error')
+
+          else
+            # Unknown event type - return empty chunk
+            Chunk.new(role: :assistant, content: nil)
+          end
+        end
+
+        def build_streaming_tool_call(data)
+          call_id = data['call_id'] || data['item_id']
+          return nil unless call_id
+
+          {
+            call_id => ToolCall.new(
+              id: call_id,
+              name: data['name'],
+              arguments: data['delta'] || ''
+            )
+          }
+        end
+
+        def parse_streaming_error(data)
+          error_data = JSON.parse(data)
+          return unless error_data['error'] || error_data['type'] == 'error'
+
+          error = error_data['error'] || error_data
+          error_type = error['type'] || error['code']
+          error_message = error['message']
+
+          case error_type
+          when 'server_error', 'internal_error'
+            [500, error_message]
+          when 'rate_limit_exceeded', 'insufficient_quota'
+            [429, error_message]
+          when 'invalid_request_error', 'invalid_api_key'
+            [400, error_message]
+          else
+            [400, error_message]
+          end
+        rescue JSON::ParserError
+          [500, data]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    class OpenAIResponses
+      # Tools/function calling methods for the OpenAI Responses API.
+      # Handles both custom function tools and built-in tools.
+      module Tools
+        module_function
+
+        EMPTY_PARAMETERS_SCHEMA = {
+          'type' => 'object',
+          'properties' => {},
+          'required' => [],
+          'additionalProperties' => false
+        }.freeze
+
+        # Built-in tool type constants
+        BUILT_IN_TOOLS = {
+          web_search: { type: 'web_search_preview' },
+          file_search: ->(vector_store_ids) { { type: 'file_search', vector_store_ids: vector_store_ids } },
+          code_interpreter: { type: 'code_interpreter', container: { type: 'auto' } },
+          image_generation: { type: 'image_generation' },
+          computer_use: ->(opts) { { type: 'computer_use_preview', **opts } }
+        }.freeze
+
+        def tool_for(tool)
+          # Check if it's a built-in tool specification
+          return tool if tool.is_a?(Hash) && tool[:type]
+
+          # Handle symbol references to built-in tools
+          if tool.is_a?(Symbol) && BUILT_IN_TOOLS.key?(tool)
+            built_in = BUILT_IN_TOOLS[tool]
+            return built_in.is_a?(Proc) ? built_in.call([]) : built_in
+          end
+
+          # Standard function tool
+          parameters_schema = parameters_schema_for(tool)
+
+          definition = {
+            type: 'function',
+            name: tool.name,
+            description: tool.description,
+            parameters: parameters_schema
+          }
+
+          # Add strict mode if schema supports it
+          definition[:strict] = true if parameters_schema['additionalProperties'] == false
+
+          return definition if tool.respond_to?(:provider_params) && tool.provider_params.empty?
+
+          if tool.respond_to?(:provider_params) && tool.provider_params.any?
+            RubyLLM::Utils.deep_merge(definition, tool.provider_params)
+          else
+            definition
+          end
+        end
+
+        def parameters_schema_for(tool)
+          if tool.respond_to?(:params_schema) && tool.params_schema
+            tool.params_schema
+          elsif tool.respond_to?(:parameters)
+            schema_from_parameters(tool.parameters)
+          else
+            EMPTY_PARAMETERS_SCHEMA
+          end
+        end
+
+        def schema_from_parameters(parameters)
+          return EMPTY_PARAMETERS_SCHEMA if parameters.nil? || parameters.empty?
+
+          if defined?(RubyLLM::Tool::SchemaDefinition)
+            schema_definition = RubyLLM::Tool::SchemaDefinition.from_parameters(parameters)
+            schema_definition&.json_schema || EMPTY_PARAMETERS_SCHEMA
+          else
+            # Fallback for older RubyLLM versions
+            build_schema_from_parameters(parameters)
+          end
+        end
+
+        def build_schema_from_parameters(parameters)
+          properties = {}
+          required = []
+
+          parameters.each do |name, param|
+            properties[name.to_s] = {
+              type: param.type || 'string',
+              description: param.description
+            }.compact
+
+            required << name.to_s if param.required
+          end
+
+          {
+            'type' => 'object',
+            'properties' => properties,
+            'required' => required,
+            'additionalProperties' => false
+          }
+        end
+
+        def format_tool_calls(tool_calls)
+          return nil unless tool_calls&.any?
+
+          tool_calls.map do |_, tc|
+            {
+              type: 'function_call',
+              call_id: tc.id,
+              name: tc.name,
+              arguments: tc.arguments.is_a?(String) ? tc.arguments : JSON.generate(tc.arguments)
+            }
+          end
+        end
+
+        def parse_tool_calls(tool_calls, parse_arguments: true)
+          return nil unless tool_calls&.any?
+
+          tool_calls.to_h do |tc|
+            call_id = tc['call_id'] || tc['id']
+            [
+              call_id,
+              ToolCall.new(
+                id: call_id,
+                name: tc['name'],
+                arguments: if parse_arguments
+                             parse_tool_call_arguments(tc)
+                           else
+                             tc['arguments']
+                           end
+              )
+            ]
+          end
+        end
+
+        def parse_tool_call_arguments(tool_call)
+          arguments = tool_call['arguments']
+
+          if arguments.nil? || arguments.empty?
+            {}
+          elsif arguments.is_a?(Hash)
+            arguments
+          else
+            JSON.parse(arguments)
+          end
+        rescue JSON::ParserError
+          { raw: arguments }
+        end
+
+        # Helper to create built-in tool configurations
+        def web_search_tool(search_context_size: nil)
+          tool = { type: 'web_search_preview' }
+          tool[:search_context_size] = search_context_size if search_context_size
+          tool
+        end
+
+        def file_search_tool(vector_store_ids:, max_num_results: nil, ranking_options: nil)
+          tool = {
+            type: 'file_search',
+            vector_store_ids: Array(vector_store_ids)
+          }
+          tool[:max_num_results] = max_num_results if max_num_results
+          tool[:ranking_options] = ranking_options if ranking_options
+          tool
+        end
+
+        def code_interpreter_tool(container_type: 'auto')
+          {
+            type: 'code_interpreter',
+            container: { type: container_type }
+          }
+        end
+
+        def image_generation_tool(partial_images: nil)
+          tool = { type: 'image_generation' }
+          tool[:partial_images] = partial_images if partial_images
+          tool
+        end
+
+        def mcp_tool(server_label:, server_url:, require_approval: 'never', allowed_tools: nil, headers: nil)
+          tool = {
+            type: 'mcp',
+            server_label: server_label,
+            server_url: server_url,
+            require_approval: require_approval
+          }
+          tool[:allowed_tools] = allowed_tools if allowed_tools
+          tool[:headers] = headers if headers
+          tool
+        end
+      end
+    end
+  end
+end