swarm_memory 2.1.2 → 2.1.4

data/lib/swarm_sdk/node_orchestrator.rb

@@ -1,591 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  # NodeOrchestrator executes a multi-node workflow
-  #
-  # Each node represents a mini-swarm execution stage. The orchestrator:
-  # - Builds execution order from node dependencies (topological sort)
-  # - Creates a separate swarm instance for each node
-  # - Passes output from one node as input to dependent nodes
-  # - Supports input/output transformers for data flow customization
-  #
-  # @example
-  #   orchestrator = NodeOrchestrator.new(
-  #     swarm_name: "Dev Team",
-  #     agent_definitions: { backend: def1, tester: def2 },
-  #     nodes: { planning: node1, implementation: node2 },
-  #     start_node: :planning
-  #   )
-  #   result = orchestrator.execute("Build auth system")
-  class NodeOrchestrator
-    attr_reader :swarm_name, :nodes, :start_node
-
-    def initialize(swarm_name:, agent_definitions:, nodes:, start_node:, scratchpad_enabled: true)
-      @swarm_name = swarm_name
-      @agent_definitions = agent_definitions
-      @nodes = nodes
-      @start_node = start_node
-      @scratchpad_enabled = scratchpad_enabled
-      @agent_instance_cache = {} # Cache for preserving agent context across nodes
-
-      validate!
-      @execution_order = build_execution_order
-    end
-
-    # Alias for compatibility with Swarm interface
-    alias_method :name, :swarm_name
-
-    # Return the lead agent of the start node for CLI compatibility
-    #
-    # @return [Symbol] Lead agent of the start node
-    def lead_agent
-      @nodes[@start_node].lead_agent
-    end
-
-    # Execute the node workflow
-    #
-    # Executes nodes in topological order, passing output from each node
-    # to its dependents. Supports streaming logs if block given.
-    #
-    # @param prompt [String] Initial prompt for the workflow
-    # @yield [Hash] Log entry if block given (for streaming)
-    # @return [Result] Final result from last node execution
-    def execute(prompt, &block)
-      logs = []
-      current_input = prompt
-      results = {}
-      @original_prompt = prompt # Store original prompt for NodeContext
-
-      # Setup logging if block given
-      if block_given?
-        # Register callback to collect logs and forward to user's block
-        LogCollector.on_log do |entry|
-          logs << entry
-          block.call(entry)
-        end
-
-        # Set LogStream to use LogCollector as emitter
-        LogStream.emitter = LogCollector
-      end
-
-      # Dynamic execution with support for goto_node
-      execution_index = 0
-      last_result = nil
-
-      while execution_index < @execution_order.size
-        node_name = @execution_order[execution_index]
-        node = @nodes[node_name]
-        node_start_time = Time.now
-
-        # Emit node_start event
-        emit_node_start(node_name, node)
-
-        # Transform input if node has transformer (Ruby block or bash command)
-        skip_execution = false
-        skip_content = nil
-
-        if node.has_input_transformer?
-          # Build NodeContext based on dependencies
-          #
-          # For single dependency: previous_result has original Result metadata,
-          #                       transformed_content has output from previous transformer
-          # For multiple dependencies: previous_result is hash of Results
-          # For no dependencies: previous_result is initial prompt string
-          previous_result = if node.dependencies.size > 1
-            # Multiple dependencies: pass hash of original results
-            node.dependencies.to_h { |dep| [dep, results[dep]] }
-          elsif node.dependencies.size == 1
-            # Single dependency: pass the original result
-            results[node.dependencies.first]
-          else
-            # No dependencies: initial prompt
-            current_input
-          end
-
-          # Create NodeContext for input transformer
-          input_context = NodeContext.for_input(
-            previous_result: previous_result,
-            all_results: results,
-            original_prompt: @original_prompt,
-            node_name: node_name,
-            dependencies: node.dependencies,
-            transformed_content: node.dependencies.size == 1 ? current_input : nil,
-          )
-
-          # Apply input transformer (passes current_input for bash command fallback)
-          # Bash transformer exit codes:
-          # - Exit 0: Use STDOUT as transformed content
-          # - Exit 1: Skip node execution, use current_input unchanged (STDOUT ignored)
-          # - Exit 2: Halt workflow with error from STDERR (STDOUT ignored)
-          transformed = node.transform_input(input_context, current_input: current_input)
-
-          # Check for control flow from transformer
-          control_result = handle_transformer_control_flow(
-            transformed: transformed,
-            node_name: node_name,
-            node: node,
-            node_start_time: node_start_time,
-          )
-
-          case control_result[:action]
-          when :halt
-            return control_result[:result]
-          when :goto
-            execution_index = find_node_index(control_result[:target])
-            current_input = control_result[:content]
-            next
-          when :skip
-            skip_execution = true
-            skip_content = control_result[:content]
-          when :continue
-            current_input = control_result[:content]
-          end
-        end
-
-        # Execute node (or skip if requested)
-        if skip_execution
-          # Skip execution: return result immediately with provided content
-          result = Result.new(
-            content: skip_content,
-            agent: "skipped:#{node_name}",
-            logs: [],
-            duration: 0.0,
-          )
-        elsif node.agent_less?
-          # Agent-less node: run pure computation without LLM
-          result = execute_agent_less_node(node, current_input)
-        else
-          # Normal node: build mini-swarm and execute with LLM
-          # NOTE: Don't pass block to mini-swarm - LogCollector already captures all logs
-          mini_swarm = build_swarm_for_node(node)
-          result = mini_swarm.execute(current_input)
-
-          # Cache agent instances for context preservation
-          cache_agent_instances(mini_swarm, node)
-
-          # If result has error, log it with backtrace
-          if result.error
-            RubyLLM.logger.error("NodeOrchestrator: Node '#{node_name}' failed: #{result.error.message}")
-            RubyLLM.logger.error("  Backtrace: #{result.error.backtrace&.first(5)&.join("\n  ")}")
-          end
-        end
-
-        results[node_name] = result
-        last_result = result
-
-        # Transform output for next node using NodeContext
-        output_context = NodeContext.for_output(
-          result: result,
-          all_results: results,
-          original_prompt: @original_prompt,
-          node_name: node_name,
-        )
-        transformed_output = node.transform_output(output_context)
-
-        # Check for control flow from output transformer
-        control_result = handle_output_transformer_control_flow(
-          transformed: transformed_output,
-          node_name: node_name,
-          node: node,
-          node_start_time: node_start_time,
-          skip_execution: skip_execution,
-          result: result,
-        )
-
-        case control_result[:action]
-        when :halt
-          return control_result[:result]
-        when :goto
-          execution_index = find_node_index(control_result[:target])
-          current_input = control_result[:content]
-          emit_node_stop(node_name, node, result, Time.now - node_start_time, skip_execution)
-          next
-        when :continue
-          current_input = control_result[:content]
-        end
-
-        # For agent-less nodes, update the result with transformed content
-        # This ensures all_results contains the actual output, not the input
-        if node.agent_less? && current_input != result.content
-          results[node_name] = Result.new(
-            content: current_input,
-            agent: result.agent,
-            logs: result.logs,
-            duration: result.duration,
-            error: result.error,
-          )
-          last_result = results[node_name]
-        end
-
-        # Emit node_stop event
-        node_duration = Time.now - node_start_time
-        emit_node_stop(node_name, node, result, node_duration, skip_execution)
-
-        execution_index += 1
-      end
-
-      last_result
-    ensure
-      # Reset logging state for next execution
-      LogCollector.reset!
-      LogStream.reset!
-    end
-
-    private
-
-    # Emit node_start event
-    #
-    # @param node_name [Symbol] Name of the node
-    # @param node [Node::Builder] Node configuration
-    # @return [void]
-    def emit_node_start(node_name, node)
-      return unless LogStream.emitter
-
-      LogStream.emit(
-        type: "node_start",
-        node: node_name.to_s,
-        agent_less: node.agent_less?,
-        agents: node.agent_configs.map { |ac| ac[:agent].to_s },
-        dependencies: node.dependencies.map(&:to_s),
-        timestamp: Time.now.utc.iso8601,
-      )
-    end
-
-    # Emit node_stop event
-    #
-    # @param node_name [Symbol] Name of the node
-    # @param node [Node::Builder] Node configuration
-    # @param result [Result] Node execution result
-    # @param duration [Float] Node execution duration in seconds
-    # @param skipped [Boolean] Whether execution was skipped
-    # @return [void]
-    def emit_node_stop(node_name, node, result, duration, skipped)
-      return unless LogStream.emitter
-
-      LogStream.emit(
-        type: "node_stop",
-        node: node_name.to_s,
-        agent_less: node.agent_less?,
-        skipped: skipped,
-        agents: node.agent_configs.map { |ac| ac[:agent].to_s },
-        duration: duration.round(3),
-        timestamp: Time.now.utc.iso8601,
-      )
-    end
-
-    # Execute an agent-less (computation-only) node
-    #
-    # Agent-less nodes run pure Ruby code without LLM execution.
-    # Creates a minimal Result object with the transformed content.
-    #
-    # @param node [Node::Builder] Agent-less node configuration
-    # @param input [String] Input content
-    # @return [Result] Result with transformed content
-    def execute_agent_less_node(node, input)
-      # For agent-less nodes, the "content" is just the input passed through
-      # The output transformer will do the actual work
-      Result.new(
-        content: input,
-        agent: "computation:#{node.name}",
-        logs: [],
-        duration: 0.0,
-      )
-    end
-
-    # Validate orchestrator configuration
-    #
-    # @return [void]
-    # @raise [ConfigurationError] If configuration is invalid
-    def validate!
-      # Validate start_node exists
-      unless @nodes.key?(@start_node)
-        raise ConfigurationError,
-          "start_node '#{@start_node}' not found. Available nodes: #{@nodes.keys.join(", ")}"
-      end
-
-      # Validate all nodes
-      @nodes.each_value(&:validate!)
-
-      # Validate node dependencies reference existing nodes
-      @nodes.each do |node_name, node|
-        node.dependencies.each do |dep|
-          unless @nodes.key?(dep)
-            raise ConfigurationError,
-              "Node '#{node_name}' depends on unknown node '#{dep}'"
-          end
-        end
-      end
-
-      # Validate all agents referenced in nodes exist (skip agent-less nodes)
-      @nodes.each do |node_name, node|
-        next if node.agent_less? # Skip validation for agent-less nodes
-
-        node.agent_configs.each do |config|
-          agent_name = config[:agent]
-          unless @agent_definitions.key?(agent_name)
-            raise ConfigurationError,
-              "Node '#{node_name}' references undefined agent '#{agent_name}'"
-          end
-
-          # Validate delegation targets exist
-          config[:delegates_to].each do |delegate|
-            unless @agent_definitions.key?(delegate)
-              raise ConfigurationError,
-                "Node '#{node_name}' agent '#{agent_name}' delegates to undefined agent '#{delegate}'"
-            end
-          end
-        end
-      end
-    end
-
-    # Build a swarm instance for a specific node
-    #
-    # Creates a new Swarm with only the agents specified in the node,
-    # configured with the node's delegation topology.
-    #
-    # For agents with reset_context: false, injects cached instances
-    # to preserve conversation history across nodes.
-    #
-    # Inherits scratchpad_enabled setting from NodeOrchestrator.
-    #
-    # @param node [Node::Builder] Node configuration
-    # @return [Swarm] Configured swarm instance
-    def build_swarm_for_node(node)
-      swarm = Swarm.new(
-        name: "#{@swarm_name}:#{node.name}",
-        scratchpad_enabled: @scratchpad_enabled,
-      )
-
-      # Add each agent specified in this node
-      node.agent_configs.each do |config|
-        agent_name = config[:agent]
-        delegates_to = config[:delegates_to]
-
-        # Get global agent definition
-        agent_def = @agent_definitions[agent_name]
-
-        # Clone definition with node-specific delegation
-        node_specific_def = clone_with_delegation(agent_def, delegates_to)
-
-        swarm.add_agent(node_specific_def)
-      end
-
-      # Set lead agent
-      swarm.lead = node.lead_agent
-
-      # Inject cached agent instances for context preservation
-      inject_cached_agents(swarm, node)
-
-      swarm
-    end
-
-    # Clone an agent definition with different delegates_to
-    #
-    # @param agent_def [Agent::Definition] Original definition
-    # @param delegates_to [Array<Symbol>] New delegation targets
-    # @return [Agent::Definition] Cloned definition
-    def clone_with_delegation(agent_def, delegates_to)
-      config = agent_def.to_h
-      config[:delegates_to] = delegates_to
-      Agent::Definition.new(agent_def.name, config)
-    end
-
-    # Build execution order using topological sort (Kahn's algorithm)
-    #
-    # Processes all nodes in dependency order, starting from start_node.
-    # Ensures all nodes are reachable from start_node.
-    #
-    # @return [Array<Symbol>] Ordered list of node names
-    # @raise [CircularDependencyError] If circular dependency detected
-    def build_execution_order
-      # Build in-degree map and adjacency list
-      in_degree = {}
-      adjacency = Hash.new { |h, k| h[k] = [] }
-
-      @nodes.each do |node_name, node|
-        in_degree[node_name] = node.dependencies.size
-        node.dependencies.each do |dep|
-          adjacency[dep] << node_name
-        end
-      end
-
-      # Start with nodes that have no dependencies
-      queue = in_degree.select { |_, degree| degree == 0 }.keys
-      order = []
-
-      while queue.any?
-        # Process nodes with all dependencies satisfied
-        node_name = queue.shift
-        order << node_name
-
-        # Reduce in-degree for dependent nodes
-        adjacency[node_name].each do |dependent|
-          in_degree[dependent] -= 1
-          queue << dependent if in_degree[dependent] == 0
-        end
-      end
-
-      # Check for circular dependencies
-      if order.size < @nodes.size
-        unprocessed = @nodes.keys - order
-        raise CircularDependencyError,
-          "Circular dependency detected. Unprocessed nodes: #{unprocessed.join(", ")}. " \
-            "Use goto_node in transformers to create loops instead of circular depends_on."
-      end
-
-      # Verify start_node is in the execution order
-      unless order.include?(@start_node)
-        raise ConfigurationError,
-          "start_node '#{@start_node}' is not reachable in the dependency graph"
-      end
-
-      # Verify start_node is actually first (or rearrange to make it first)
-      # This ensures we start from the declared start_node
-      start_index = order.index(@start_node)
-      if start_index && start_index > 0
-        # start_node has dependencies - this violates the assumption
-        raise ConfigurationError,
-          "start_node '#{@start_node}' has dependencies: #{@nodes[@start_node].dependencies.join(", ")}. " \
-            "start_node must have no dependencies."
-      end
-
-      order
-    end
-
-    # Handle control flow from input transformer
-    #
-    # @param transformed [String, Hash] Result from transformer
-    # @param node_name [Symbol] Current node name
-    # @param node [Node::Builder] Node configuration
-    # @param node_start_time [Time] Node execution start time
-    # @return [Hash] Control result with :action and relevant data
-    def handle_transformer_control_flow(transformed:, node_name:, node:, node_start_time:)
-      return { action: :continue, content: transformed } unless transformed.is_a?(Hash)
-
-      if transformed[:halt_workflow]
-        # Halt entire workflow
-        halt_result = Result.new(
-          content: transformed[:content],
-          agent: "halted:#{node_name}",
-          logs: [],
-          duration: Time.now - node_start_time,
-        )
-        emit_node_stop(node_name, node, halt_result, Time.now - node_start_time, false)
-        { action: :halt, result: halt_result }
-      elsif transformed[:goto_node]
-        # Jump to different node
-        { action: :goto, target: transformed[:goto_node], content: transformed[:content] }
-      elsif transformed[:skip_execution]
-        # Skip node execution
-        { action: :skip, content: transformed[:content] }
-      else
-        # No control flow - continue normally
-        { action: :continue, content: transformed[:content] }
-      end
-    end
-
-    # Handle control flow from output transformer
-    #
-    # @param transformed [String, Hash] Result from transformer
-    # @param node_name [Symbol] Current node name
-    # @param node [Node::Builder] Node configuration
-    # @param node_start_time [Time] Node execution start time
-    # @param skip_execution [Boolean] Whether node execution was skipped
-    # @param result [Result] Node execution result
-    # @return [Hash] Control result with :action and relevant data
-    def handle_output_transformer_control_flow(transformed:, node_name:, node:, node_start_time:, skip_execution:, result:)
-      # If not a hash, it's just transformed content - continue normally
-      return { action: :continue, content: transformed } unless transformed.is_a?(Hash)
-
-      if transformed[:halt_workflow]
-        # Halt entire workflow
-        halt_result = Result.new(
-          content: transformed[:content],
-          agent: result.agent,
-          logs: result.logs,
-          duration: result.duration,
-        )
-        emit_node_stop(node_name, node, halt_result, Time.now - node_start_time, skip_execution)
-        { action: :halt, result: halt_result }
-      elsif transformed[:goto_node]
-        # Jump to different node
-        { action: :goto, target: transformed[:goto_node], content: transformed[:content] }
-      else
-        # Hash without control flow keys - treat as regular hash with :content key
-        # This handles the case where transformer returns a hash that's not for control flow
-        { action: :continue, content: transformed[:content] || transformed }
-      end
-    end
-
-    # Find the index of a node in the execution order
-    #
-    # @param node_name [Symbol] Node name to find
-    # @return [Integer] Index in execution order
-    # @raise [ConfigurationError] If node not found
-    def find_node_index(node_name)
-      index = @execution_order.index(node_name)
-      unless index
-        raise ConfigurationError,
-          "goto_node target '#{node_name}' not found. Available nodes: #{@execution_order.join(", ")}"
-      end
-      index
-    end
-
-    # Cache agent instances from a swarm for potential reuse
-    #
-    # Only caches agents that have reset_context: false in this node.
-    # This allows preserving conversation history across nodes.
-    #
-    # @param swarm [Swarm] Swarm instance that just executed
-    # @param node [Node::Builder] Node configuration
-    # @return [void]
-    def cache_agent_instances(swarm, node)
-      return unless swarm.agents # Only cache if agents were initialized
-
-      node.agent_configs.each do |config|
-        agent_name = config[:agent]
-        reset_context = config[:reset_context]
-
-        # Only cache if reset_context is false
-        next if reset_context
-
-        # Cache the agent instance
-        agent_instance = swarm.agents[agent_name]
-        @agent_instance_cache[agent_name] = agent_instance if agent_instance
-      end
-    end
-
-    # Inject cached agent instances into a swarm
-    #
-    # For agents with reset_context: false, reuses cached instances to preserve context.
-    # Forces agent initialization first (by accessing .agents), then swaps in cached instances.
-    #
-    # @param swarm [Swarm] Swarm instance to inject into
-    # @param node [Node::Builder] Node configuration
-    # @return [void]
-    def inject_cached_agents(swarm, node)
-      # Check if any agents need context preservation
-      has_preserved_agents = node.agent_configs.any? { |c| !c[:reset_context] && @agent_instance_cache[c[:agent]] }
-      return unless has_preserved_agents
-
-      # Force agent initialization by accessing .agents (triggers lazy init)
-      # Then inject cached instances
-      agents_hash = swarm.agents
-
-      node.agent_configs.each do |config|
-        agent_name = config[:agent]
-        reset_context = config[:reset_context]
-
-        # Skip if reset_context is true (want fresh instance)
-        next if reset_context
-
-        # Check if we have a cached instance
-        cached_agent = @agent_instance_cache[agent_name]
-        next unless cached_agent
-
-        # Inject the cached instance (replace the freshly initialized one)
-        agents_hash[agent_name] = cached_agent
-      end
-    end
-  end
-end