ruby_llm-agents 1.0.0 → 1.2.0

data/lib/ruby_llm/agents/workflow/orchestrator.rb

@@ -3,32 +3,62 @@
 require_relative "result"
 require_relative "instrumentation"
 require_relative "thread_pool"
-require_relative "pipeline"
-require_relative "parallel"
-require_relative "router"
+require_relative "dsl"
+require_relative "dsl/executor"
 
 module RubyLLM
   module Agents
     # Base class for workflow orchestration
     #
     # Provides shared functionality for composing multiple agents into
-    # coordinated workflows. Subclasses implement specific patterns:
-    # - Pipeline: Sequential execution with data flowing between steps
-    # - Parallel: Concurrent execution with result aggregation
-    # - Router: Conditional dispatch based on classification
+    # coordinated workflows using the DSL:
+    # - Sequential steps with data flowing between them
+    # - Parallel execution with result aggregation
+    # - Conditional routing based on step results
     #
-    # @example Creating a custom workflow
-    #   class MyWorkflow < RubyLLM::Agents::Workflow
-    #     version "1.0"
-    #     # ... workflow-specific DSL
+    # @example Minimal workflow
+    #   class SimpleWorkflow < RubyLLM::Agents::Workflow
+    #     step :fetch, FetcherAgent
+    #     step :process, ProcessorAgent
+    #     step :save, SaverAgent
+    #   end
+    #
+    # @example Full-featured workflow
+    #   class OrderWorkflow < RubyLLM::Agents::Workflow
+    #     description "Process customer orders end-to-end"
+    #
+    #     input do
+    #       required :order_id, String
+    #       optional :priority, String, default: "normal"
+    #     end
+    #
+    #     step :fetch, FetcherAgent, timeout: 1.minute
+    #     step :validate, ValidatorAgent
+    #
+    #     step :process, on: -> { validate.tier } do |route|
+    #       route.premium  PremiumAgent
+    #       route.standard StandardAgent
+    #       route.default  DefaultAgent
+    #     end
+    #
+    #     parallel do
+    #       step :analyze, AnalyzerAgent
+    #       step :summarize, SummarizerAgent
+    #     end
+    #
+    #     step :notify, NotifierAgent, if: :should_notify?
+    #
+    #     private
+    #
+    #     def should_notify?
+    #       input.callback_url.present?
+    #     end
     #   end
     #
-    # @see RubyLLM::Agents::Workflow::Pipeline
-    # @see RubyLLM::Agents::Workflow::Parallel
-    # @see RubyLLM::Agents::Workflow::Router
     # @api public
     class Workflow
       include Workflow::Instrumentation
+      include Workflow::DSL
 
       class << self
         # @!attribute [rw] version
@@ -47,6 +77,10 @@ module RubyLLM
         #   @return [String, nil] Description of the workflow
         attr_accessor :_description
 
+        # @!attribute [rw] max_recursion_depth
+        #   @return [Integer] Maximum recursion depth for self-referential workflows
+        attr_accessor :_max_recursion_depth
+
         # Sets or returns the workflow version
         #
         # @param value [String, nil] Version string to set
@@ -95,13 +129,34 @@ module RubyLLM
           end
         end
 
+        # Sets or returns the maximum recursion depth
+        #
+        # @param value [Integer, nil] Max depth to set
+        # @return [Integer] The current max recursion depth (default: 10)
+        def max_recursion_depth(value = nil)
+          if value
+            self._max_recursion_depth = value.to_i
+          else
+            _max_recursion_depth || 10
+          end
+        end
+
         # Factory method to instantiate and execute a workflow
         #
+        # Supports both hash and keyword argument styles:
+        #   MyWorkflow.call(order_id: "123")
+        #   MyWorkflow.call({ order_id: "123" })
+        #
+        # @param input [Hash] Input hash (optional)
         # @param kwargs [Hash] Parameters to pass to the workflow
         # @yield [chunk] Optional block for streaming support
         # @return [WorkflowResult] The workflow result with aggregate metrics
-        def call(**kwargs, &block)
-          new(**kwargs).call(&block)
+        def call(input = nil, **kwargs, &block)
+          # Support both call(hash) and call(**kwargs) patterns
+          merged_input = input.is_a?(Hash) ? input.merge(kwargs) : kwargs
+          # Pass input to constructor to maintain backward compatibility with
+          # legacy subclasses that override call without arguments
+          new(**merged_input).call(&block)
         end
       end
 
@@ -117,6 +172,14 @@ module RubyLLM
       #   @return [Integer, nil] The ID of the root execution record
       attr_reader :execution_id
 
+      # @!attribute [r] step_results
+      #   @return [Hash<Symbol, Result>] Results from executed steps
+      attr_reader :step_results
+
+      # @!attribute [r] recursion_depth
+      #   @return [Integer] Current recursion depth for self-referential workflows
+      attr_reader :recursion_depth
+
       # Creates a new workflow instance
       #
       # @param kwargs [Hash] Parameters for the workflow
@@ -126,17 +189,94 @@ module RubyLLM
         @execution_id = nil
         @accumulated_cost = 0.0
         @step_results = {}
+        @validated_input = nil
+
+        # Extract recursion context from execution_metadata
+        metadata = kwargs[:execution_metadata] || {}
+        @recursion_depth = metadata[:recursion_depth] || 0
+        @remaining_timeout = metadata[:remaining_timeout]
+        @remaining_cost_budget = metadata[:remaining_cost_budget]
+
+        # Check recursion depth
+        check_recursion_depth!
       end
 
       # Executes the workflow
       #
-      # @abstract Subclasses must implement this method
+      # When using the new DSL with `step` declarations, this method
+      # automatically executes the workflow using the DSL executor.
+      # For legacy subclasses (Pipeline, Parallel, Router), this raises
+      # NotImplementedError to be overridden.
+      #
+      # Supports both hash and keyword argument styles:
+      #   workflow.call(order_id: "123")
+      #   workflow.call({ order_id: "123" })
+      #
+      # @param input [Hash] Input hash (optional)
+      # @param kwargs [Hash] Keyword arguments for input
       # @yield [chunk] Optional block for streaming support
       # @return [WorkflowResult] The workflow result
-      def call(&block)
-        raise NotImplementedError, "#{self.class} must implement #call"
+      def call(input = nil, **kwargs, &block)
+        # Merge input sources: constructor options, hash arg, keyword args
+        merged_input = @options.merge(input.is_a?(Hash) ? input : {}).merge(kwargs)
+        @options = merged_input
+
+        # Use DSL executor if steps are defined with the new DSL
+        if self.class.step_configs.any?
+          instrument_workflow do
+            execute_with_dsl(&block)
+          end
+        else
+          raise NotImplementedError, "#{self.class} must implement #call or define steps"
+        end
+      end
+
+      # Validates workflow input and executes a dry run
+      #
+      # Returns information about the workflow without executing agents.
+      # Supports both positional hash and keyword arguments.
+      #
+      # @param input_hash [Hash] Input hash (optional)
+      # @param input [Hash] Keyword arguments for input
+      # @return [Hash] Validation results and workflow structure
+      def self.dry_run(input_hash = nil, **input)
+        input = input_hash.merge(input) if input_hash.is_a?(Hash)
+        errors = []
+
+        # Validate input if schema defined
+        if input_schema
+          begin
+            input_schema.validate!(input)
+          rescue DSL::InputSchema::ValidationError => e
+            errors.concat(e.errors)
+          end
+        end
+
+        # Validate configuration
+        errors.concat(validate_configuration)
+
+        {
+          valid: errors.empty?,
+          input_errors: errors,
+          steps: step_metadata.map { |s| s[:name] },
+          agents: step_metadata.map { |s| s[:agent] }.compact,
+          parallel_groups: parallel_groups.map(&:to_h),
+          warnings: validate_configuration
+        }
+      end
+
+      private
+
+      # Executes the workflow using the DSL executor
+      #
+      # @return [WorkflowResult] The workflow result
+      def execute_with_dsl(&block)
+        executor = DSL::Executor.new(self)
+        executor.execute(&block)
       end
 
+      public
+
       protected
 
       # Executes a single agent within the workflow context
@@ -191,13 +331,29 @@ module RubyLLM
       #
       # @raise [WorkflowCostExceededError] If cost exceeds max_cost
       def check_cost_threshold!
-        return unless self.class.max_cost
-        return if @accumulated_cost <= self.class.max_cost
+        # Check against remaining budget if we're in a sub-workflow
+        effective_max = @remaining_cost_budget || self.class.max_cost
+        return unless effective_max
+        return if @accumulated_cost <= effective_max
 
         raise WorkflowCostExceededError.new(
-          "Workflow cost ($#{@accumulated_cost.round(4)}) exceeded maximum ($#{self.class.max_cost})",
+          "Workflow cost ($#{@accumulated_cost.round(4)}) exceeded maximum ($#{effective_max})",
           accumulated_cost: @accumulated_cost,
-          max_cost: self.class.max_cost
+          max_cost: effective_max
+        )
+      end
+
+      # Checks if recursion depth exceeds the maximum
+      #
+      # @raise [RecursionDepthExceededError] If depth exceeds max
+      def check_recursion_depth!
+        max_depth = self.class.max_recursion_depth
+        return if @recursion_depth <= max_depth
+
+        raise RecursionDepthExceededError.new(
+          "Workflow recursion depth (#{@recursion_depth}) exceeded maximum (#{max_depth})",
+          current_depth: @recursion_depth,
+          max_depth: max_depth
         )
       end
 
@@ -245,5 +401,16 @@ module RubyLLM
         @max_cost = max_cost
       end
     end
+
+    # Error raised when workflow recursion depth exceeds the maximum
+    class RecursionDepthExceededError < StandardError
+      attr_reader :current_depth, :max_depth
+
+      def initialize(message, current_depth:, max_depth:)
+        super(message)
+        @current_depth = current_depth
+        @max_depth = max_depth
+      end
+    end
   end
 end

data/lib/ruby_llm/agents/workflow/result.rb

@@ -385,6 +385,208 @@ module RubyLLM
           { skipped: true, step_name: step_name, reason: reason }
         end
       end
+
+      # Result wrapper for sub-workflow execution
+      #
+      # Wraps a nested workflow result while providing access to
+      # aggregate metrics and the underlying workflow result.
+      #
+      # @api public
+      class SubWorkflowResult
+        attr_reader :content, :sub_workflow_result, :workflow_type, :step_name
+
+        def initialize(content:, sub_workflow_result:, workflow_type:, step_name:)
+          @content = content
+          @sub_workflow_result = sub_workflow_result
+          @workflow_type = workflow_type
+          @step_name = step_name
+        end
+
+        def success?
+          sub_workflow_result.respond_to?(:success?) ? sub_workflow_result.success? : true
+        end
+
+        def error?
+          sub_workflow_result.respond_to?(:error?) ? sub_workflow_result.error? : false
+        end
+
+        def skipped?
+          false
+        end
+
+        # Delegate metrics to sub-workflow result
+        def input_tokens
+          sub_workflow_result.respond_to?(:input_tokens) ? sub_workflow_result.input_tokens : 0
+        end
+
+        def output_tokens
+          sub_workflow_result.respond_to?(:output_tokens) ? sub_workflow_result.output_tokens : 0
+        end
+
+        def total_tokens
+          input_tokens + output_tokens
+        end
+
+        def cached_tokens
+          sub_workflow_result.respond_to?(:cached_tokens) ? sub_workflow_result.cached_tokens : 0
+        end
+
+        def input_cost
+          sub_workflow_result.respond_to?(:input_cost) ? sub_workflow_result.input_cost : 0.0
+        end
+
+        def output_cost
+          sub_workflow_result.respond_to?(:output_cost) ? sub_workflow_result.output_cost : 0.0
+        end
+
+        def total_cost
+          sub_workflow_result.respond_to?(:total_cost) ? sub_workflow_result.total_cost : 0.0
+        end
+
+        # Access sub-workflow steps
+        def steps
+          sub_workflow_result.respond_to?(:steps) ? sub_workflow_result.steps : {}
+        end
+
+        def to_h
+          {
+            content: content,
+            workflow_type: workflow_type,
+            step_name: step_name,
+            sub_workflow: sub_workflow_result.respond_to?(:to_h) ? sub_workflow_result.to_h : sub_workflow_result,
+            input_tokens: input_tokens,
+            output_tokens: output_tokens,
+            total_cost: total_cost
+          }
+        end
+
+        # Delegate hash access to content
+        def [](key)
+          content.is_a?(Hash) ? content[key] : nil
+        end
+
+        def dig(*keys)
+          content.is_a?(Hash) ? content.dig(*keys) : nil
+        end
+      end
+
+      # Result wrapper for iteration execution
+      #
+      # Tracks results for each item in an iteration with
+      # aggregate success/failure counts and metrics.
+      #
+      # @api public
+      class IterationResult
+        attr_reader :step_name, :item_results, :errors
+
+        def initialize(step_name:, item_results: [], errors: {})
+          @step_name = step_name
+          @item_results = item_results
+          @errors = errors
+        end
+
+        def content
+          item_results.map do |result|
+            result.respond_to?(:content) ? result.content : result
+          end
+        end
+
+        def success?
+          errors.empty? && item_results.all? do |r|
+            !r.respond_to?(:error?) || !r.error?
+          end
+        end
+
+        def error?
+          !success?
+        end
+
+        def partial?
+          errors.any? && item_results.any? do |r|
+            !r.respond_to?(:error?) || !r.error?
+          end
+        end
+
+        def skipped?
+          false
+        end
+
+        def successful_count
+          item_results.count { |r| !r.respond_to?(:error?) || !r.error? }
+        end
+
+        def failed_count
+          errors.size + item_results.count { |r| r.respond_to?(:error?) && r.error? }
+        end
+
+        def total_count
+          item_results.size + errors.size
+        end
+
+        # Aggregate metrics across all items
+        def input_tokens
+          item_results.sum { |r| r.respond_to?(:input_tokens) ? r.input_tokens : 0 }
+        end
+
+        def output_tokens
+          item_results.sum { |r| r.respond_to?(:output_tokens) ? r.output_tokens : 0 }
+        end
+
+        def total_tokens
+          input_tokens + output_tokens
+        end
+
+        def cached_tokens
+          item_results.sum { |r| r.respond_to?(:cached_tokens) ? r.cached_tokens : 0 }
+        end
+
+        def input_cost
+          item_results.sum { |r| r.respond_to?(:input_cost) ? r.input_cost : 0.0 }
+        end
+
+        def output_cost
+          item_results.sum { |r| r.respond_to?(:output_cost) ? r.output_cost : 0.0 }
+        end
+
+        def total_cost
+          item_results.sum { |r| r.respond_to?(:total_cost) ? r.total_cost : 0.0 }
+        end
+
+        def to_h
+          {
+            step_name: step_name,
+            total_count: total_count,
+            successful_count: successful_count,
+            failed_count: failed_count,
+            success: success?,
+            items: item_results.map { |r| r.respond_to?(:to_h) ? r.to_h : r },
+            errors: errors.transform_values { |e| { class: e.class.name, message: e.message } },
+            input_tokens: input_tokens,
+            output_tokens: output_tokens,
+            total_cost: total_cost
+          }
+        end
+
+        # Access individual item results by index
+        def [](index)
+          item_results[index]
+        end
+
+        def each(&block)
+          item_results.each(&block)
+        end
+
+        def map(&block)
+          item_results.map(&block)
+        end
+
+        include Enumerable
+
+        # Empty iteration result factory
+        def self.empty(step_name)
+          new(step_name: step_name, item_results: [], errors: {})
+        end
+      end
     end
   end
 end

data/lib/ruby_llm/agents/workflow/throttle_manager.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    class Workflow
+      # Manages rate limiting and throttling for workflow steps
+      #
+      # Provides two modes of rate limiting:
+      # 1. Throttle: Ensures minimum time between executions of the same step
+      # 2. Rate limit: Limits the number of calls within a time window (token bucket)
+      #
+      # Thread-safe using a Mutex for concurrent access.
+      #
+      # @example Using throttle
+      #   manager = ThrottleManager.new
+      #   manager.throttle("step:fetch", 1.0) # Wait at least 1 second between calls
+      #
+      # @example Using rate limit
+      #   manager = ThrottleManager.new
+      #   manager.rate_limit("api:external", calls: 10, per: 60) # 10 calls per minute
+      #
+      # @api private
+      class ThrottleManager
+        def initialize
+          @last_execution = {}
+          @rate_limiters = {}
+          @mutex = Mutex.new
+        end
+
+        # Throttle execution to ensure minimum time between calls
+        #
+        # Blocks the current thread if necessary to maintain the minimum interval.
+        #
+        # @param key [String] Unique identifier for the throttle target
+        # @param duration [Float, Integer] Minimum seconds between executions
+        # @return [Float] Actual seconds waited (0 if no wait needed)
+        def throttle(key, duration)
+          duration_seconds = normalize_duration(duration)
+
+          @mutex.synchronize do
+            last = @last_execution[key]
+            waited = 0
+
+            if last
+              elapsed = Time.now - last
+              remaining = duration_seconds - elapsed
+
+              if remaining > 0
+                @mutex.sleep(remaining)
+                waited = remaining
+              end
+            end
+
+            @last_execution[key] = Time.now
+            waited
+          end
+        end
+
+        # Check if a call would be throttled without actually waiting
+        #
+        # @param key [String] Unique identifier for the throttle target
+        # @param duration [Float, Integer] Minimum seconds between executions
+        # @return [Float] Seconds until next allowed execution (0 if ready)
+        def throttle_remaining(key, duration)
+          duration_seconds = normalize_duration(duration)
+
+          @mutex.synchronize do
+            last = @last_execution[key]
+            return 0 unless last
+
+            elapsed = Time.now - last
+            remaining = duration_seconds - elapsed
+            [remaining, 0].max
+          end
+        end
+
+        # Apply rate limiting using a token bucket algorithm
+        #
+        # Blocks until a token is available if the rate limit is exceeded.
+        #
+        # @param key [String] Unique identifier for the rate limit target
+        # @param calls [Integer] Number of calls allowed per window
+        # @param per [Float, Integer] Time window in seconds
+        # @return [Float] Seconds waited (0 if no wait needed)
+        def rate_limit(key, calls:, per:)
+          per_seconds = normalize_duration(per)
+          bucket = get_or_create_bucket(key, calls, per_seconds)
+
+          @mutex.synchronize do
+            waited = bucket.acquire
+            waited
+          end
+        end
+
+        # Check if a call would be rate limited without consuming a token
+        #
+        # @param key [String] Unique identifier for the rate limit target
+        # @param calls [Integer] Number of calls allowed per window
+        # @param per [Float, Integer] Time window in seconds
+        # @return [Boolean] true if a call would be allowed immediately
+        def rate_limit_available?(key, calls:, per:)
+          per_seconds = normalize_duration(per)
+          bucket = get_or_create_bucket(key, calls, per_seconds)
+
+          @mutex.synchronize do
+            bucket.available?
+          end
+        end
+
+        # Reset throttle state for a specific key
+        #
+        # @param key [String] The throttle key to reset
+        # @return [void]
+        def reset_throttle(key)
+          @mutex.synchronize do
+            @last_execution.delete(key)
+          end
+        end
+
+        # Reset rate limiter state for a specific key
+        #
+        # @param key [String] The rate limiter key to reset
+        # @return [void]
+        def reset_rate_limit(key)
+          @mutex.synchronize do
+            @rate_limiters.delete(key)
+          end
+        end
+
+        # Reset all throttle and rate limit state
+        #
+        # @return [void]
+        def reset_all!
+          @mutex.synchronize do
+            @last_execution.clear
+            @rate_limiters.clear
+          end
+        end
+
+        private
+
+        def normalize_duration(duration)
+          if duration.respond_to?(:to_f)
+            duration.to_f
+          else
+            duration.to_i.to_f
+          end
+        end
+
+        def get_or_create_bucket(key, calls, per)
+          @rate_limiters[key] ||= TokenBucket.new(calls, per)
+        end
+
+        # Simple token bucket implementation for rate limiting
+        #
+        # @api private
+        class TokenBucket
+          def initialize(capacity, refill_time)
+            @capacity = capacity
+            @refill_time = refill_time
+            @tokens = capacity.to_f
+            @last_refill = Time.now
+          end
+
+          # Try to acquire a token, waiting if necessary
+          #
+          # @return [Float] Seconds waited
+          def acquire
+            refill
+            waited = 0
+
+            if @tokens < 1
+              # Calculate wait time for next token
+              tokens_needed = 1 - @tokens
+              wait_time = tokens_needed * @refill_time / @capacity
+              sleep(wait_time)
+              waited = wait_time
+              refill
+            end
+
+            @tokens -= 1
+            waited
+          end
+
+          # Check if a token is available without consuming it
+          #
+          # @return [Boolean]
+          def available?
+            refill
+            @tokens >= 1
+          end
+
+          private
+
+          def refill
+            now = Time.now
+            elapsed = now - @last_refill
+            refill_amount = elapsed * @capacity / @refill_time
+            @tokens = [@tokens + refill_amount, @capacity].min
+            @last_refill = now
+          end
+        end
+      end
+    end
+  end
+end