swarm_sdk 2.0.0.pre.2

data/lib/swarm_sdk/providers/openai_with_responses.rb

@@ -0,0 +1,582 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Providers
+    # Extended OpenAI provider with responses API support
+    #
+    # RubyLLM's OpenAI provider only supports v1/chat/completions.
+    # This provider extends it to also support v1/responses for models
+    # that require it (e.g., gpt-5-pro, o-series models).
+    #
+    # ## Usage
+    #
+    # Set via AgentChat when api_version is configured:
+    #
+    # @example Via SwarmSDK AgentChat (automatic)
+    #   # In swarm.yml:
+    #   agents:
+    #     researcher:
+    #       model: gpt-5-pro
+    #       api_version: "v1/responses"  # Automatically uses this provider
+    #
+    # @example Direct instantiation
+    #   provider = OpenAIWithResponses.new(config, use_responses_api: true)
+    #   chat = RubyLLM::Chat.new(model: "gpt-5-pro", provider: provider)
+    #
+    # ## Features
+    #
+    # - **Stateful mode**: Uses `previous_response_id` with `store: true` for efficient multi-turn
+    # - **Stateless fallback**: Automatically falls back to sending full history if server doesn't store responses
+    # - **TTL tracking**: Expires response IDs after 5 minutes to prevent "not found" errors
+    # - **Auto-recovery**: Detects repeated failures and disables `previous_response_id` entirely
+    #
+    class OpenAIWithResponses < RubyLLM::Providers::OpenAI
+      attr_accessor :use_responses_api
+      attr_writer :agent_name
+
+      # OpenAI Responses API expires response IDs after inactivity
+      # Conservative estimate: 5 minutes (300 seconds)
+      RESPONSE_ID_TTL = 300
+
+      # Initialize the provider
+      #
+      # @param config [RubyLLM::Configuration] Configuration object
+      # @param use_responses_api [Boolean, nil] Force endpoint choice (nil = auto-detect)
+      def initialize(config, use_responses_api: nil)
+        super(config)
+        @use_responses_api = use_responses_api
+        @model_id = nil
+        @last_response_id = nil # Track last response ID for conversation state
+        @last_response_time = nil # Track when response ID was created
+        @response_id_failures = 0 # Track consecutive failures with response IDs
+        @disable_response_id = false # Disable previous_response_id if repeatedly failing
+        @agent_name = nil # Agent name for logging context (set externally)
+      end
+
+      # Return the completion endpoint URL
+      #
+      # @return [String] Either 'responses' or 'chat/completions'
+      def completion_url
+        endpoint = determine_endpoint
+        RubyLLM.logger.debug("SwarmSDK OpenAIWithResponses: Using endpoint '#{endpoint}' (use_responses_api=#{@use_responses_api}, model=#{@model_id})")
+        endpoint
+      end
+
+      # Return the streaming endpoint URL
+      #
+      # @return [String] Same as completion_url
+      def stream_url
+        completion_url
+      end
+
+      # Override complete to capture model_id before making request
+      #
+      # This allows auto-detection to work by inspecting the model being used
+      def complete(messages, tools:, temperature:, model:, params: {}, headers: {}, schema: nil, &block)
+        @model_id = model.id
+        super
+      rescue RubyLLM::BadRequestError => e
+        # Handle "response not found" errors by starting a fresh conversation
+        if e.message.include?("not found") && @last_response_id
+          @response_id_failures += 1
+
+          # After 2 failures, disable previous_response_id entirely
+          if @response_id_failures >= 2
+            RubyLLM.logger.debug("SwarmSDK: Response IDs repeatedly not found (#{@response_id_failures} failures). " \
+              "The server may not support storing responses. Disabling previous_response_id for this session.")
+            @disable_response_id = true
+          else
+            RubyLLM.logger.debug("SwarmSDK: Response ID '#{@last_response_id}' not found (failure ##{@response_id_failures}), starting fresh conversation")
+          end
+
+          @last_response_id = nil
+          @last_response_time = nil
+          retry
+        else
+          raise
+        end
+      rescue RubyLLM::Error => e
+        # If error explicitly mentions responses API and we're not using it, retry with responses API
+        if should_retry_with_responses_api?(e)
+          RubyLLM.logger.warn("SwarmSDK: Retrying with responses API for model: #{@model_id}")
+          @use_responses_api = true
+          retry
+        else
+          raise
+        end
+      end
+
+      # Override render_payload to transform request body for Responses API
+      #
+      # The Responses API uses 'input' instead of 'messages' parameter
+      #
+      # @param messages [Array<RubyLLM::Message>] Conversation messages
+      # @param tools [Hash] Available tools
+      # @param temperature [Float, nil] Sampling temperature
+      # @param model [RubyLLM::Model] Model to use
+      # @param stream [Boolean] Enable streaming
+      # @param schema [Hash, nil] Response format schema
+      # @return [Hash] Request payload
+      def render_payload(messages, tools:, temperature:, model:, stream: false, schema: nil)
+        if should_use_responses_api?
+          render_responses_payload(messages, tools: tools, temperature: temperature, model: model, stream: stream, schema: schema)
+        else
+          # Use original OpenAI chat/completions format
+          super
+        end
+      end
+
+      # Override parse_completion_response to handle Responses API response format
+      #
+      # @param response [Faraday::Response] HTTP response
+      # @return [RubyLLM::Message, nil] Parsed message or nil
+      def parse_completion_response(response)
+        # Guard against nil response body before delegating to parsers
+        if response.body.nil?
+          log_parse_error("nil", "Received nil response body from API", response.body)
+          return
+        end
+
+        if should_use_responses_api?
+          parse_responses_api_response(response)
+        else
+          super
+        end
+      rescue NoMethodError => e
+        # Catch fetch/dig errors on nil and provide better context
+        if e.message.include?("undefined method") && (e.message.include?("fetch") || e.message.include?("dig"))
+          log_parse_error(e.class.name, e.message, response.body)
+          nil
+        else
+          raise
+        end
+      end
+
+      private
+
+      # Determine which endpoint to use based on configuration and model
+      #
+      # @return [String] 'responses' or 'chat/completions'
+      def determine_endpoint
+        if @use_responses_api.nil?
+          # Auto-detect based on model name
+          requires_responses_api? ? "responses" : "chat/completions"
+        elsif @use_responses_api
+          "responses"
+        else
+          "chat/completions"
+        end
+      end
+
+      # Check if the current model requires the responses API
+      #
+      # Since we control this via api_version configuration, we don't auto-detect.
+      # This method is only called when use_responses_api is nil (no explicit setting).
+      #
+      # @return [Boolean] false - default to chat/completions for auto-detect
+      def requires_responses_api?
+        # Default to chat/completions when not explicitly configured
+        # Users should set api_version: "v1/responses" to use responses API
+        false
+      end
+
+      # Check if we should use responses API for the current request
+      #
+      # @return [Boolean] true if responses API should be used
+      def should_use_responses_api?
+        if @use_responses_api.nil?
+          # Auto-detect based on model
+          requires_responses_api?
+        else
+          @use_responses_api
+        end
+      end
+
+      # Build request body for Responses API
+      #
+      # The Responses API uses conversation state via previous_response_id.
+      # For multi-turn conversations:
+      # 1. First turn: Send input with user message
+      # 2. Get response with tool calls in output
+      # 3. Next turn: Send previous_response_id + input with function_call_output items
+      #
+      # @param messages [Array<RubyLLM::Message>] Conversation messages
+      # @param tools [Hash] Available tools
+      # @param temperature [Float, nil] Sampling temperature
+      # @param model [RubyLLM::Model] Model to use
+      # @param stream [Boolean] Enable streaming
+      # @param schema [Hash, nil] Response format schema
+      # @return [Hash] Request payload
+      def render_responses_payload(messages, tools:, temperature:, model:, stream: false, schema: nil)
+        payload = {
+          model: model.id,
+          stream: stream,
+        }
+
+        # Use previous_response_id for multi-turn conversations
+        # Only use it if:
+        # 1. Not disabled due to repeated failures
+        # 2. We have a response ID and timestamp
+        # 3. It hasn't expired (based on TTL)
+        # 4. There are new messages to send
+        use_previous_response = !@disable_response_id &&
+          @last_response_id &&
+          @last_response_time &&
+          (Time.now - @last_response_time) < RESPONSE_ID_TTL &&
+          has_new_messages?(messages)
+
+        if use_previous_response
+          RubyLLM.logger.debug("SwarmSDK: Multi-turn request with previous_response_id=#{@last_response_id}")
+          payload[:previous_response_id] = @last_response_id
+          # Only send NEW input (messages after the last response)
+          new_input = format_new_input_messages(messages)
+          payload[:input] = new_input
+          RubyLLM.logger.debug("SwarmSDK: New input for multi-turn: #{JSON.pretty_generate(new_input)}")
+        else
+          if @last_response_id && @last_response_time && (Time.now - @last_response_time) >= RESPONSE_ID_TTL
+            RubyLLM.logger.debug("SwarmSDK: Response ID expired (age: #{(Time.now - @last_response_time).round}s), starting new conversation chain")
+          else
+            RubyLLM.logger.debug("SwarmSDK: First turn request (no previous_response_id)")
+          end
+          # First turn or no conversation state or expired
+          initial_input = format_input_messages(messages)
+          payload[:input] = initial_input
+          RubyLLM.logger.debug("SwarmSDK: Initial input: #{JSON.pretty_generate(initial_input)}")
+        end
+
+        payload[:temperature] = temperature unless temperature.nil?
+
+        # CRITICAL: Explicitly set store: true to ensure responses are saved
+        # Without this, previous_response_id will not work because the response won't be retrievable
+        payload[:store] = true
+
+        # Use flat tool format for Responses API
+        payload[:tools] = tools.map { |_, tool| responses_tool_for(tool) } if tools.any?
+
+        if schema
+          strict = schema[:strict] != false
+          payload[:response_format] = {
+            type: "json_schema",
+            json_schema: {
+              name: "response",
+              schema: schema,
+              strict: strict,
+            },
+          }
+        end
+
+        payload[:stream_options] = { include_usage: true } if stream
+        payload
+      end
+
+      # Check if there are new messages since the last response
+      #
+      # @param messages [Array<RubyLLM::Message>] All conversation messages
+      # @return [Boolean] True if there are new messages (tool results or user messages)
+      def has_new_messages?(messages)
+        return false if messages.empty?
+
+        # Check if the last few messages include tool results (role: :tool)
+        # This indicates we need to send them with previous_response_id
+        messages.last(5).any? { |msg| msg.role == :tool }
+      end
+
+      # Format only NEW messages for Responses API (used with previous_response_id)
+      #
+      # When using previous_response_id, only send new input that wasn't in the previous request.
+      # This typically includes:
+      # - Tool results (as function_call_output items)
+      # - New user messages
+      #
+      # @param messages [Array<RubyLLM::Message>] All conversation messages
+      # @return [Array<Hash>] Formatted input array with only new messages
+      def format_new_input_messages(messages)
+        formatted = []
+
+        # Find messages after the last assistant response
+        # Typically this will be tool results and potentially new user input
+        last_assistant_idx = messages.rindex { |msg| msg.role == :assistant }
+
+        if last_assistant_idx
+          new_messages = messages[(last_assistant_idx + 1)..-1]
+
+          new_messages.each do |msg|
+            case msg.role
+            when :tool
+              # Tool results become function_call_output items
+              formatted << {
+                type: "function_call_output",
+                call_id: msg.tool_call_id,
+                output: msg.content.to_s,
+              }
+            when :user
+              # New user messages
+              formatted << {
+                role: "user",
+                content: Media.format_content(msg.content),
+              }
+            when :system
+              # New system messages (rare but possible)
+              formatted << {
+                role: "developer",
+                content: Media.format_content(msg.content),
+              }
+            end
+          end
+        end
+
+        formatted
+      end
+
+      # Format messages for Responses API input (first turn)
+      #
+      # For the first request in a conversation, include all user/system/assistant messages.
+      # Tool calls and tool results are excluded as they're part of the conversation state.
+      #
+      # @param messages [Array<RubyLLM::Message>] Conversation messages
+      # @return [Array<Hash>] Formatted input array
+      def format_input_messages(messages)
+        formatted = []
+
+        messages.each do |msg|
+          case msg.role
+          when :user
+            formatted << {
+              role: "user",
+              content: Media.format_content(msg.content),
+            }
+          when :system
+            formatted << {
+              role: "developer", # Responses API uses 'developer' instead of 'system'
+              content: Media.format_content(msg.content),
+            }
+          when :assistant
+            # Assistant messages - only include if they have text content (not just tool calls)
+            unless msg.content.nil? || msg.content.empty?
+              formatted << {
+                role: "assistant",
+                content: Media.format_content(msg.content),
+              }
+            end
+            # NOTE: Tool calls are NOT included in input - they're part of the output/conversation state
+          when :tool
+            # Tool result messages should NOT be in the first request
+            # They're only sent with previous_response_id
+            nil
+          end
+        end
+
+        formatted
+      end
+
+      # Convert tool to Responses API format (flat structure)
+      #
+      # Responses API uses a flat format with type at top level:
+      # { type: "function", name: "tool_name", description: "...", parameters: {...} }
+      #
+      # This differs from chat/completions which nests under 'function':
+      # { type: "function", function: { name: "tool_name", ... } }
+      #
+      # @param tool [RubyLLM::Tool] Tool to convert
+      # @return [Hash] Tool definition in Responses API format
+      def responses_tool_for(tool)
+        {
+          type: "function",
+          name: tool.name,
+          description: tool.description,
+          parameters: {
+            type: "object",
+            properties: tool.parameters.transform_values { |param| param_schema(param) },
+            required: tool.parameters.select { |_, p| p.required }.keys,
+          },
+        }
+      end
+
+      # Build parameter schema for a tool parameter
+      #
+      # @param param [RubyLLM::Tool::Parameter] Parameter to convert
+      # @return [Hash] Parameter schema
+      def param_schema(param)
+        {
+          type: param.type,
+          description: param.description,
+        }.compact
+      end
+
+      # Parse Responses API response
+      #
+      # The Responses API may have a different response structure than chat/completions.
+      # This method tries multiple possible paths to find the message data.
+      # IMPORTANT: Also captures the response ID for multi-turn conversations.
+      #
+      # @param response [Faraday::Response] HTTP response
+      # @return [RubyLLM::Message, nil] Parsed message or nil
+      def parse_responses_api_response(response)
+        data = response.body
+
+        # Handle nil or non-hash response body
+        unless data.is_a?(Hash)
+          log_parse_error("TypeError", "Expected response body to be Hash, got #{data.class}", data)
+          return
+        end
+
+        # Debug logging to see actual response structure
+        RubyLLM.logger.debug("SwarmSDK Responses API response: #{JSON.pretty_generate(data)}")
+
+        return if data.empty?
+
+        raise RubyLLM::Error.new(response, data.dig("error", "message")) if data.dig("error", "message")
+
+        # Capture response ID and timestamp for conversation state (if not disabled)
+        unless @disable_response_id
+          @last_response_id = data["id"]
+          @last_response_time = Time.now
+          @response_id_failures = 0 # Reset failure counter on success
+          RubyLLM.logger.debug("SwarmSDK captured response_id: #{@last_response_id} at #{@last_response_time}")
+        end
+
+        # Try different possible paths for the message data
+        message_data = extract_message_data(data)
+
+        RubyLLM.logger.debug("SwarmSDK extracted message_data: #{message_data.inspect} (class: #{message_data.class})")
+
+        return unless message_data
+
+        # Ensure message_data is a hash
+        unless message_data.is_a?(Hash)
+          RubyLLM.logger.error("SwarmSDK expected message_data to be Hash, got #{message_data.class}")
+          return
+        end
+
+        RubyLLM::Message.new(
+          role: :assistant,
+          content: message_data["content"] || "", # Provide empty string as fallback
+          tool_calls: parse_tool_calls(message_data["tool_calls"]),
+          input_tokens: extract_input_tokens(data),
+          output_tokens: extract_output_tokens(data),
+          model_id: data["model"],
+          raw: response,
+        )
+      end
+
+      # Extract message data from Responses API response
+      #
+      # The Responses API uses an 'output' array with different item types:
+      # - reasoning: Model's internal reasoning
+      # - function_call: Tool call to execute
+      # - message: Text response
+      #
+      # @param data [Hash] Response body
+      # @return [Hash] Message data synthesized from output array
+      def extract_message_data(data)
+        output = data["output"]
+
+        # If no output array, try fallback paths
+        unless output.is_a?(Array)
+          return data.dig("choices", 0, "message") || # Standard OpenAI format
+              data.dig("response") ||                    # Another possible format
+              data.dig("message")                        # Direct message format
+        end
+
+        # Parse the output array to extract content and tool calls
+        content_parts = []
+        tool_calls = []
+
+        output.each do |item|
+          case item["type"]
+          when "message"
+            # Message contains a content array with typed items
+            if item["content"].is_a?(Array)
+              item["content"].each do |content_item|
+                case content_item["type"]
+                when "output_text"
+                  content_parts << content_item["text"]
+                when "text"
+                  content_parts << content_item["text"]
+                end
+              end
+            elsif item["content"].is_a?(String)
+              content_parts << item["content"]
+            elsif item["text"]
+              content_parts << item["text"]
+            end
+          when "function_call"
+            # Convert to RubyLLM tool call format
+            tool_calls << {
+              "id" => item["call_id"],
+              "type" => "function",
+              "function" => {
+                "name" => item["name"],
+                "arguments" => item["arguments"],
+              },
+            }
+          when "reasoning"
+            # Skip reasoning items (internal model thought process)
+            nil
+          end
+        end
+
+        # Synthesize a message data hash
+        {
+          "role" => "assistant",
+          "content" => content_parts.join("\n"),
+          "tool_calls" => tool_calls.empty? ? nil : tool_calls,
+        }
+      end
+
+      # Extract input tokens from various possible locations
+      #
+      # @param data [Hash] Response body
+      # @return [Integer] Input token count
+      def extract_input_tokens(data)
+        data.dig("usage", "prompt_tokens") ||
+          data.dig("usage", "input_tokens") ||
+          0
+      end
+
+      # Extract output tokens from various possible locations
+      #
+      # @param data [Hash] Response body
+      # @return [Integer] Output token count
+      def extract_output_tokens(data)
+        data.dig("usage", "completion_tokens") ||
+          data.dig("usage", "output_tokens") ||
+          0
+      end
+
+      # Check if we should retry with responses API after an error
+      #
+      # @param error [RubyLLM::Error] The error that occurred
+      # @return [Boolean] true if we should retry with responses API
+      def should_retry_with_responses_api?(error)
+        # Only retry if we haven't already tried responses API
+        return false if @use_responses_api
+
+        # Check if error message explicitly mentions responses API
+        error.message.include?("v1/responses") ||
+          error.message.include?("only supported in") && error.message.include?("responses")
+      end
+
+      # Log response parsing errors as JSON events through LogStream
+      #
+      # @param error_class [String] Error class name
+      # @param error_message [String] Error message
+      # @param response_body [Object] Response body that failed to parse
+      def log_parse_error(error_class, error_message, response_body)
+        if @agent_name
+          # Emit structured JSON log through LogStream
+          LogStream.emit(
+            type: "response_parse_error",
+            agent: @agent_name,
+            error_class: error_class,
+            error_message: error_message,
+            response_body: response_body.inspect,
+          )
+        else
+          # Fallback to RubyLLM logger if agent name not set
+          RubyLLM.logger.error("SwarmSDK: #{error_class}: #{error_message}\nResponse: #{response_body.inspect}")
+        end
+      end
+    end
+  end
+end

data/lib/swarm_sdk/result.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  class Result
+    attr_reader :content, :agent, :cost, :tokens, :duration, :logs, :error, :metadata
+
+    def initialize(content: nil, agent:, cost: 0.0, tokens: {}, duration: 0.0, logs: [], error: nil, metadata: {})
+      @content = content
+      @agent = agent
+      @cost = cost
+      @tokens = tokens
+      @duration = duration
+      @logs = logs
+      @error = error
+      @metadata = metadata
+    end
+
+    def success?
+      @error.nil?
+    end
+
+    def failure?
+      !success?
+    end
+
+    def to_h
+      {
+        content: @content,
+        agent: @agent,
+        cost: @cost,
+        tokens: @tokens,
+        duration: @duration,
+        success: success?,
+        error: @error&.message,
+        metadata: @metadata,
+      }.compact
+    end
+
+    def to_json(*args)
+      to_h.to_json(*args)
+    end
+
+    # Calculate total cost across all LLM responses
+    #
+    # Cost accumulation works as follows:
+    # - Input cost: The LAST response's input_cost already includes the cost for the
+    #   full conversation history (all previous messages + current context)
+    # - Output cost: Each response generates NEW tokens, so we SUM all output_costs
+    # - Total = Last input_cost + Sum of all output_costs
+    #
+    # IMPORTANT: Do NOT sum total_cost across all entries - that would count
+    # input costs multiple times since each call includes the full history!
+    def total_cost
+      entries_with_usage = @logs.select { |entry| entry.dig(:usage, :total_cost) }
+      return 0.0 if entries_with_usage.empty?
+
+      # Last entry's input cost (includes full conversation history)
+      last_input_cost = entries_with_usage.last.dig(:usage, :input_cost) || 0.0
+
+      # Sum all output costs (each response generates new tokens)
+      total_output_cost = entries_with_usage.sum { |entry| entry.dig(:usage, :output_cost) || 0.0 }
+
+      last_input_cost + total_output_cost
+    end
+
+    # Get total tokens from the last LLM response with cumulative tracking
+    #
+    # Token accumulation works as follows:
+    # - Input tokens: Each API call sends the full conversation history, so the latest
+    #   response's cumulative_input_tokens already represents the full context
+    # - Output tokens: Each response generates new tokens, cumulative_output_tokens sums them
+    # - The cumulative_total_tokens in the last response already does this correctly
+    #
+    # IMPORTANT: Do NOT sum total_tokens across all log entries - that would count
+    # input tokens multiple times since each call includes the full history!
+    def total_tokens
+      last_entry = @logs.reverse.find { |entry| entry.dig(:usage, :cumulative_total_tokens) }
+      last_entry&.dig(:usage, :cumulative_total_tokens) || 0
+    end
+
+    # Get list of all agents involved in execution
+    def agents_involved
+      @logs.map { |entry| entry[:agent] }.compact.uniq.map(&:to_sym)
+    end
+
+    # Count total LLM requests made
+    # Each LLM API call produces either agent_step (tool calls) or agent_stop (final answer)
+    def llm_requests
+      @logs.count { |entry| entry[:type] == "agent_step" || entry[:type] == "agent_stop" }
+    end
+
+    # Count total tool calls made
+    def tool_calls_count
+      @logs.count { |entry| entry[:type] == "tool_call" }
+    end
+  end
+end