ruby_llm-agents 1.0.0 → 1.2.0

data/lib/ruby_llm/agents/workflow/dsl/step_executor.rb

@@ -0,0 +1,415 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    class Workflow
+      module DSL
+        # Executes individual workflow steps with retry, timeout, and error handling
+        #
+        # Responsible for:
+        # - Evaluating step conditions
+        # - Building step input
+        # - Executing agents with timeout
+        # - Handling retries with backoff
+        # - Executing fallback agents
+        # - Invoking error handlers
+        #
+        # @api private
+        class StepExecutor
+          attr_reader :workflow, :config
+
+          # @param workflow [Workflow] The workflow instance
+          # @param config [StepConfig] The step configuration
+          def initialize(workflow, config)
+            @workflow = workflow
+            @config = config
+          end
+
+          # Executes the step
+          #
+          # @param previous_result [Result, nil] Previous step result
+          # @yield [chunk] Streaming callback
+          # @return [Result, SkippedResult] Step result
+          def execute(previous_result = nil, &block)
+            # Check conditions
+            unless config.should_execute?(workflow)
+              return create_skipped_result("condition not met")
+            end
+
+            # Execute with timeout wrapper if configured
+            if config.timeout
+              execute_with_timeout(previous_result, &block)
+            else
+              execute_step(previous_result, &block)
+            end
+          end
+
+          private
+
+          def execute_with_timeout(previous_result, &block)
+            Timeout.timeout(config.timeout) do
+              execute_step(previous_result, &block)
+            end
+          rescue Timeout::Error => e
+            handle_step_error(e, previous_result, &block)
+          end
+
+          def execute_step(previous_result, &block)
+            execute_with_retry(previous_result, &block)
+          rescue StandardError => e
+            handle_step_error(e, previous_result, &block)
+          end
+
+          def execute_with_retry(previous_result, &block)
+            retry_config = config.retry_config
+            max_attempts = [retry_config[:max], 0].max + 1
+            attempts = 0
+
+            begin
+              attempts += 1
+              execute_agent_or_block(previous_result, &block)
+            rescue *retry_config[:on] => e
+              if attempts < max_attempts
+                sleep_with_backoff(retry_config, attempts)
+                retry
+              else
+                raise
+              end
+            end
+          end
+
+          def execute_agent_or_block(previous_result, &block)
+            if config.routing?
+              execute_routed_step(previous_result, &block)
+            elsif config.iteration?
+              execute_iteration_step(previous_result, &block)
+            elsif config.workflow?
+              execute_workflow_step(previous_result, &block)
+            elsif config.custom_block?
+              execute_block_step(previous_result)
+            else
+              execute_agent_step(previous_result, &block)
+            end
+          end
+
+          def execute_routed_step(previous_result, &block)
+            route = config.resolve_route(workflow)
+            agent_class = route[:agent]
+            route_options = route[:options] || {}
+
+            # Build input - use route-specific input if provided
+            step_input = if route_options[:input]
+                           workflow.instance_exec(&route_options[:input])
+                         else
+                           config.resolve_input(workflow, previous_result)
+                         end
+
+            # Execute the routed agent
+            workflow.send(:execute_agent, agent_class, step_input, step_name: config.name, &block)
+          end
+
+          def execute_block_step(previous_result)
+            # Create a block context that provides helper methods
+            context = BlockContext.new(workflow, config, previous_result)
+            result = context.instance_exec(&config.block)
+
+            # If block returns a Result, use it; otherwise wrap it
+            if result.is_a?(Result) || result.is_a?(Workflow::Result)
+              result
+            else
+              SimpleResult.new(content: result, success: true)
+            end
+          end
+
+          def execute_agent_step(previous_result, &block)
+            step_input = config.resolve_input(workflow, previous_result)
+            workflow.send(:execute_agent, config.agent, step_input, step_name: config.name, &block)
+          end
+
+          def execute_workflow_step(previous_result, &block)
+            step_input = config.resolve_input(workflow, previous_result)
+
+            # Build execution metadata for the sub-workflow
+            parent_metadata = {
+              parent_execution_id: workflow.execution_id,
+              root_execution_id: workflow.send(:root_execution_id),
+              workflow_id: workflow.workflow_id,
+              workflow_type: workflow.class.name,
+              workflow_step: config.name.to_s,
+              remaining_timeout: calculate_remaining_timeout,
+              remaining_cost_budget: calculate_remaining_cost_budget,
+              recursion_depth: (workflow.instance_variable_get(:@recursion_depth) || 0) + (self_referential_workflow? ? 1 : 0)
+            }.compact
+
+            # Merge execution metadata into input
+            merged_input = step_input.merge(
+              execution_metadata: parent_metadata.merge(step_input[:execution_metadata] || {})
+            )
+
+            # Execute the sub-workflow
+            result = config.agent.call(**merged_input, &block)
+
+            # Track accumulated cost
+            if result.respond_to?(:total_cost) && result.total_cost
+              workflow.instance_variable_set(
+                :@accumulated_cost,
+                (workflow.instance_variable_get(:@accumulated_cost) || 0.0) + result.total_cost
+              )
+              workflow.send(:check_cost_threshold!)
+            end
+
+            # Wrap in SubWorkflowResult for proper tracking
+            SubWorkflowResult.new(
+              content: result.content,
+              sub_workflow_result: result,
+              workflow_type: config.agent.name,
+              step_name: config.name
+            )
+          end
+
+          def execute_iteration_step(previous_result, &block)
+            executor = IterationExecutor.new(workflow, config, previous_result)
+            executor.execute(&block)
+          end
+
+          def calculate_remaining_timeout
+            workflow_timeout = workflow.class.timeout
+            return nil unless workflow_timeout
+
+            started_at = workflow.instance_variable_get(:@workflow_started_at)
+            return workflow_timeout unless started_at
+
+            elapsed = Time.current - started_at
+            remaining = workflow_timeout - elapsed
+            remaining > 0 ? remaining.to_i : 1
+          end
+
+          def calculate_remaining_cost_budget
+            max_cost = workflow.class.max_cost
+            return nil unless max_cost
+
+            accumulated = workflow.instance_variable_get(:@accumulated_cost) || 0.0
+            remaining = max_cost - accumulated
+            remaining > 0 ? remaining : 0.0
+          end
+
+          def self_referential_workflow?
+            config.agent == workflow.class
+          end
+
+          def handle_step_error(error, previous_result, &block)
+            # Try fallbacks first
+            if config.fallbacks.any?
+              fallback_result = try_fallbacks(previous_result, &block)
+              return fallback_result if fallback_result
+            end
+
+            # Try error handler
+            if config.error_handler
+              handler_result = invoke_error_handler(error)
+              return handler_result if handler_result.is_a?(Result) || handler_result.is_a?(Workflow::Result)
+            end
+
+            # If optional, return default or error result
+            if config.optional?
+              if config.default_value
+                return SimpleResult.new(content: config.default_value, success: true)
+              else
+                # Return an error result so status is set to "partial"
+                return Pipeline::ErrorResult.new(
+                  step_name: config.name,
+                  error_class: error.class.name,
+                  error_message: error.message
+                )
+              end
+            end
+
+            # Re-raise for critical steps
+            raise
+          end
+
+          def try_fallbacks(previous_result, &block)
+            step_input = config.resolve_input(workflow, previous_result)
+
+            config.fallbacks.each do |fallback_agent|
+              begin
+                return workflow.send(:execute_agent, fallback_agent, step_input, step_name: config.name, &block)
+              rescue StandardError
+                # Continue to next fallback
+                next
+              end
+            end
+
+            nil
+          end
+
+          def invoke_error_handler(error)
+            handler = config.error_handler
+
+            case handler
+            when Symbol
+              workflow.send(handler, error)
+            when Proc
+              workflow.instance_exec(error, &handler)
+            end
+          end
+
+          def sleep_with_backoff(retry_config, attempt)
+            base_delay = retry_config[:delay] || 1
+
+            delay = case retry_config[:backoff]
+                    when :exponential
+                      base_delay * (2**(attempt - 1))
+                    when :linear
+                      base_delay * attempt
+                    else
+                      base_delay
+                    end
+
+            sleep(delay)
+          end
+
+          def create_skipped_result(reason)
+            SkippedResult.new(config.name, reason: reason)
+          end
+        end
+
+        # Context for executing custom block steps
+        #
+        # Provides helper methods available inside step blocks.
+        #
+        # @api private
+        class BlockContext
+          def initialize(workflow, config, previous_result)
+            @workflow = workflow
+            @config = config
+            @previous_result = previous_result
+          end
+
+          # Executes an agent within the block
+          #
+          # @param agent_class [Class] Agent to execute
+          # @param input [Hash] Input for the agent
+          # @return [Result] Agent result
+          def agent(agent_class, **input)
+            @workflow.send(:execute_agent, agent_class, input, step_name: @config.name)
+          end
+
+          # Skips the current step
+          #
+          # @param reason [String] Skip reason
+          # @param default [Object] Default value to use
+          # @raise [StepSkipped]
+          def skip!(reason = nil, default: nil)
+            throw :skip_step, { skipped: true, reason: reason, default: default }
+          end
+
+          # Halts the workflow successfully
+          #
+          # @param result [Hash] Final result
+          # @raise [WorkflowHalted]
+          def halt!(result = {})
+            throw :halt_workflow, { halted: true, result: result }
+          end
+
+          # Fails the current step
+          #
+          # @param message [String] Error message
+          # @raise [StepFailedError]
+          def fail!(message)
+            raise StepFailedError, message
+          end
+
+          # Triggers a retry of the current step
+          #
+          # @param reason [String] Retry reason
+          # @raise [RetryStep]
+          def retry!(reason = nil)
+            raise RetryStep, reason
+          end
+
+          # Access workflow input
+          def input
+            @workflow.input
+          end
+
+          # Access previous step result
+          def previous
+            @previous_result
+          end
+
+          # Delegate missing methods to workflow (for accessing step results)
+          def method_missing(name, *args, &block)
+            if @workflow.respond_to?(name, true)
+              @workflow.send(name, *args, &block)
+            else
+              super
+            end
+          end
+
+          def respond_to_missing?(name, include_private = false)
+            @workflow.respond_to?(name, include_private) || super
+          end
+        end
+
+        # Simple result wrapper for block steps
+        #
+        # @api private
+        class SimpleResult
+          attr_reader :content
+
+          def initialize(content:, success: true)
+            @content = content
+            @success = success
+          end
+
+          def success?
+            @success
+          end
+
+          def error?
+            !@success
+          end
+
+          def input_tokens
+            0
+          end
+
+          def output_tokens
+            0
+          end
+
+          def total_tokens
+            0
+          end
+
+          def cached_tokens
+            0
+          end
+
+          def input_cost
+            0.0
+          end
+
+          def output_cost
+            0.0
+          end
+
+          def total_cost
+            0.0
+          end
+
+          def to_h
+            { content: content, success: success? }
+          end
+        end
+
+        # Error raised when a step explicitly fails
+        class StepFailedError < StandardError; end
+
+        # Error to trigger step retry
+        class RetryStep < StandardError; end
+      end
+    end
+  end
+end

data/lib/ruby_llm/agents/workflow/dsl/wait_config.rb

@@ -0,0 +1,257 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    class Workflow
+      module DSL
+        # Configuration object for a workflow wait step
+        #
+        # Holds all the configuration options for a wait step including
+        # the type (delay, until, schedule, approval), duration, conditions,
+        # timeout settings, and notification options.
+        #
+        # @example Simple delay
+        #   WaitConfig.new(type: :delay, duration: 5.seconds)
+        #
+        # @example Conditional wait
+        #   WaitConfig.new(
+        #     type: :until,
+        #     condition: -> { payment.confirmed? },
+        #     poll_interval: 5.seconds,
+        #     timeout: 10.minutes
+        #   )
+        #
+        # @example Human approval
+        #   WaitConfig.new(
+        #     type: :approval,
+        #     name: :manager_approval,
+        #     notify: [:email, :slack],
+        #     timeout: 24.hours
+        #   )
+        #
+        # @api private
+        class WaitConfig
+          TYPES = %i[delay until schedule approval].freeze
+
+          attr_reader :type, :duration, :condition, :name, :options
+
+          # @param type [Symbol] Wait type (:delay, :until, :schedule, :approval)
+          # @param duration [ActiveSupport::Duration, Integer, nil] Duration for delay
+          # @param condition [Proc, nil] Condition for until/schedule waits
+          # @param name [Symbol, nil] Name for approval waits
+          # @param options [Hash] Additional options
+          def initialize(type:, duration: nil, condition: nil, name: nil, **options)
+            raise ArgumentError, "Unknown wait type: #{type}" unless TYPES.include?(type)
+
+            @type = type
+            @duration = duration
+            @condition = condition
+            @name = name
+            @options = options
+          end
+
+          # Returns whether this is a simple delay
+          #
+          # @return [Boolean]
+          def delay?
+            type == :delay
+          end
+
+          # Returns whether this is a conditional wait
+          #
+          # @return [Boolean]
+          def conditional?
+            type == :until
+          end
+
+          # Returns whether this is a scheduled wait
+          #
+          # @return [Boolean]
+          def scheduled?
+            type == :schedule
+          end
+
+          # Returns whether this is an approval wait
+          #
+          # @return [Boolean]
+          def approval?
+            type == :approval
+          end
+
+          # Returns the poll interval for conditional waits
+          #
+          # @return [ActiveSupport::Duration, Integer] Default: 1 second
+          def poll_interval
+            options[:poll_interval] || 1
+          end
+
+          # Returns the timeout for the wait
+          #
+          # @return [ActiveSupport::Duration, Integer, nil]
+          def timeout
+            options[:timeout]
+          end
+
+          # Returns the action to take on timeout
+          #
+          # @return [Symbol] :fail, :continue, or :skip_next (default: :fail)
+          def on_timeout
+            options[:on_timeout] || :fail
+          end
+
+          # Returns the backoff multiplier for exponential backoff
+          #
+          # @return [Numeric, nil]
+          def backoff
+            options[:backoff]
+          end
+
+          # Returns the maximum poll interval when using backoff
+          #
+          # @return [ActiveSupport::Duration, Integer, nil]
+          def max_interval
+            options[:max_interval]
+          end
+
+          # Returns whether this wait uses exponential backoff
+          #
+          # @return [Boolean]
+          def exponential_backoff?
+            backoff.present?
+          end
+
+          # Returns the notification channels for approval waits
+          #
+          # @return [Array<Symbol>]
+          def notify_channels
+            Array(options[:notify])
+          end
+
+          # Returns the message for approval notifications
+          #
+          # @return [String, Proc, nil]
+          def message
+            options[:message]
+          end
+
+          # Returns the reminder interval
+          #
+          # @return [ActiveSupport::Duration, Integer, nil]
+          def reminder_after
+            options[:reminder_after]
+          end
+
+          # Returns the reminder repeat interval
+          #
+          # @return [ActiveSupport::Duration, Integer, nil]
+          def reminder_interval
+            options[:reminder_interval]
+          end
+
+          # Returns the escalation target on timeout
+          #
+          # @return [Symbol, nil]
+          def escalate_to
+            options[:escalate_to]
+          end
+
+          # Returns the list of approvers
+          #
+          # @return [Array<String, Symbol>]
+          def approvers
+            Array(options[:approvers])
+          end
+
+          # Returns the timezone for scheduled waits
+          #
+          # @return [String, nil]
+          def timezone
+            options[:timezone]
+          end
+
+          # Returns the condition for executing this wait
+          #
+          # @return [Symbol, Proc, nil]
+          def if_condition
+            options[:if]
+          end
+
+          # Returns the negative condition for executing this wait
+          #
+          # @return [Symbol, Proc, nil]
+          def unless_condition
+            options[:unless]
+          end
+
+          # Evaluates whether this wait should execute
+          #
+          # @param workflow [Workflow] The workflow instance
+          # @return [Boolean]
+          def should_execute?(workflow)
+            passes_if = if_condition.nil? || evaluate_condition(workflow, if_condition)
+            passes_unless = unless_condition.nil? || !evaluate_condition(workflow, unless_condition)
+            passes_if && passes_unless
+          end
+
+          # Returns a UI-friendly label for this wait
+          #
+          # @return [String]
+          def ui_label
+            case type
+            when :delay
+              "Wait #{format_duration(duration)}"
+            when :until
+              "Wait until condition"
+            when :schedule
+              "Wait until scheduled time"
+            when :approval
+              "Awaiting #{name || 'approval'}"
+            end
+          end
+
+          # Converts to hash for serialization
+          #
+          # @return [Hash]
+          def to_h
+            {
+              type: type,
+              duration: duration,
+              name: name,
+              poll_interval: poll_interval,
+              timeout: timeout,
+              on_timeout: on_timeout,
+              backoff: backoff,
+              max_interval: max_interval,
+              notify: notify_channels,
+              approvers: approvers,
+              ui_label: ui_label
+            }.compact
+          end
+
+          private
+
+          def evaluate_condition(workflow, condition)
+            case condition
+            when Symbol then workflow.send(condition)
+            when Proc then workflow.instance_exec(&condition)
+            else condition
+            end
+          end
+
+          def format_duration(dur)
+            return "unknown" unless dur
+
+            seconds = dur.respond_to?(:to_i) ? dur.to_i : dur
+            if seconds >= 3600
+              "#{seconds / 3600}h"
+            elsif seconds >= 60
+              "#{seconds / 60}m"
+            else
+              "#{seconds}s"
+            end
+          end
+        end
+      end
+    end
+  end
+end