ruby_llm-agents 1.0.0 → 1.2.0

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

@@ -0,0 +1,289 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    class Workflow
+      module DSL
+        # Executes iteration steps with sequential or parallel processing
+        #
+        # Handles `each:` option on steps to process collections with support for:
+        # - Sequential iteration
+        # - Parallel iteration with configurable concurrency
+        # - Fail-fast behavior
+        # - Continue-on-error behavior
+        #
+        # @api private
+        class IterationExecutor
+          attr_reader :workflow, :config, :previous_result
+
+          # @param workflow [Workflow] The workflow instance
+          # @param config [StepConfig] The step configuration
+          # @param previous_result [Result, nil] Previous step result
+          def initialize(workflow, config, previous_result)
+            @workflow = workflow
+            @config = config
+            @previous_result = previous_result
+          end
+
+          # Executes the iteration
+          #
+          # @yield [chunk] Streaming callback
+          # @return [IterationResult] Aggregated results for all items
+          def execute(&block)
+            items = resolve_items
+            return Workflow::IterationResult.empty(config.name) if items.empty?
+
+            if config.iteration_concurrency && config.iteration_concurrency > 1
+              execute_parallel(items, &block)
+            else
+              execute_sequential(items, &block)
+            end
+          end
+
+          private
+
+          def resolve_items
+            source = config.each_source
+            items = workflow.instance_exec(&source)
+            Array(items)
+          rescue StandardError => e
+            raise IterationSourceError, "Failed to resolve iteration source: #{e.message}"
+          end
+
+          def execute_sequential(items, &block)
+            item_results = []
+            errors = {}
+
+            items.each_with_index do |item, index|
+              begin
+                result = execute_for_item(item, index, &block)
+                item_results << result
+
+                # Check for fail-fast on error
+                if config.iteration_fail_fast? && result.respond_to?(:error?) && result.error?
+                  break
+                end
+              rescue StandardError => e
+                if config.iteration_fail_fast?
+                  errors[index] = e
+                  break
+                elsif config.continue_on_error?
+                  errors[index] = e
+                  # Continue to next item
+                else
+                  raise
+                end
+              end
+            end
+
+            Workflow::IterationResult.new(
+              step_name: config.name,
+              item_results: item_results,
+              errors: errors
+            )
+          end
+
+          def execute_parallel(items, &block)
+            results_mutex = Mutex.new
+            item_results = Array.new(items.size)
+            errors = {}
+            aborted = false
+
+            pool = create_executor_pool(config.iteration_concurrency)
+
+            items.each_with_index do |item, index|
+              pool.post do
+                next if aborted
+
+                begin
+                  result = execute_for_item(item, index, &block)
+
+                  results_mutex.synchronize do
+                    item_results[index] = result
+
+                    # Check for fail-fast
+                    if config.iteration_fail_fast? && result.respond_to?(:error?) && result.error?
+                      aborted = true
+                      pool.abort! if pool.respond_to?(:abort!)
+                    end
+                  end
+                rescue StandardError => e
+                  results_mutex.synchronize do
+                    errors[index] = e
+
+                    if config.iteration_fail_fast?
+                      aborted = true
+                      pool.abort! if pool.respond_to?(:abort!)
+                    end
+                  end
+
+                  raise unless config.continue_on_error? || config.iteration_fail_fast?
+                end
+              end
+            end
+
+            pool.wait_for_completion
+            pool.shutdown
+
+            # Remove nil entries from results (unfilled due to abort)
+            item_results.compact!
+
+            Workflow::IterationResult.new(
+              step_name: config.name,
+              item_results: item_results,
+              errors: errors
+            )
+          end
+
+          def execute_for_item(item, index, &block)
+            if config.custom_block?
+              execute_block_for_item(item, index, &block)
+            elsif config.workflow?
+              execute_workflow_for_item(item, index, &block)
+            else
+              execute_agent_for_item(item, index, &block)
+            end
+          end
+
+          def execute_block_for_item(item, index, &block)
+            context = IterationContext.new(workflow, config, previous_result, item, index)
+            result = context.instance_exec(item, &config.block)
+
+            # If block returns a Result, use it; otherwise wrap it
+            if result.is_a?(Workflow::Result) || result.is_a?(RubyLLM::Agents::Result)
+              result
+            else
+              SimpleResult.new(content: result, success: true)
+            end
+          end
+
+          def execute_agent_for_item(item, index, &block)
+            # Build input for this item
+            step_input = build_item_input(item, index)
+            workflow.send(:execute_agent, config.agent, step_input, step_name: config.name, &block)
+          end
+
+          def execute_workflow_for_item(item, index, &block)
+            step_input = build_item_input(item, index)
+
+            # Build execution metadata
+            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,
+              iteration_index: index,
+              recursion_depth: (workflow.instance_variable_get(:@recursion_depth) || 0) + (config.agent == workflow.class ? 1 : 0)
+            }.compact
+
+            merged_input = step_input.merge(
+              execution_metadata: parent_metadata.merge(step_input[:execution_metadata] || {})
+            )
+
+            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
+
+            Workflow::SubWorkflowResult.new(
+              content: result.content,
+              sub_workflow_result: result,
+              workflow_type: config.agent.name,
+              step_name: config.name
+            )
+          end
+
+          def build_item_input(item, index)
+            # If there's an input mapper, use it with item context
+            if config.input_mapper
+              # Create a temporary context that has access to item and index
+              context = IterationInputContext.new(workflow, item, index)
+              context.instance_exec(&config.input_mapper)
+            else
+              # Default: wrap item in a hash
+              item.is_a?(Hash) ? item : { item: item, index: index }
+            end
+          end
+
+          def create_executor_pool(size)
+            config_obj = RubyLLM::Agents.configuration
+
+            if config_obj.respond_to?(:async_context?) && config_obj.async_context?
+              AsyncExecutor.new(max_concurrent: size)
+            else
+              ThreadPool.new(size: size)
+            end
+          end
+        end
+
+        # Context for executing iteration block steps
+        #
+        # Extends BlockContext with item and index access.
+        #
+        # @api private
+        class IterationContext < BlockContext
+          attr_reader :item, :index
+
+          def initialize(workflow, config, previous_result, item, index)
+            super(workflow, config, previous_result)
+            @item = item
+            @index = index
+          end
+
+          # Access the current item being processed
+          def current_item
+            @item
+          end
+
+          # Access the current iteration index
+          def current_index
+            @index
+          end
+        end
+
+        # Context for building iteration input
+        #
+        # Provides access to item and index for input mappers.
+        #
+        # @api private
+        class IterationInputContext
+          def initialize(workflow, item, index)
+            @workflow = workflow
+            @item = item
+            @index = index
+          end
+
+          attr_reader :item, :index
+
+          # Access workflow input
+          def input
+            @workflow.input
+          end
+
+          # Delegate to workflow for step results access
+          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
+
+        # Error raised when iteration source resolution fails
+        class IterationSourceError < StandardError; end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    class Workflow
+      module DSL
+        # Represents a group of steps that execute in parallel
+        #
+        # Parallel groups allow multiple steps to run concurrently and
+        # their results to be available to subsequent steps.
+        #
+        # @example Basic parallel group
+        #   parallel do
+        #     step :sentiment, SentimentAgent
+        #     step :keywords, KeywordAgent
+        #     step :entities, EntityAgent
+        #   end
+        #
+        # @example Named parallel group
+        #   parallel :analysis do
+        #     step :sentiment, SentimentAgent
+        #     step :keywords, KeywordAgent
+        #   end
+        #
+        #   step :combine, CombinerAgent,
+        #        input: -> { { analysis: analysis } }
+        #
+        # @api private
+        class ParallelGroup
+          attr_reader :name, :step_names, :options
+
+          # @param name [Symbol, nil] Optional name for the group
+          # @param step_names [Array<Symbol>] Names of steps in the group
+          # @param options [Hash] Group options
+          def initialize(name: nil, step_names: [], options: {})
+            @name = name
+            @step_names = step_names
+            @options = options
+          end
+
+          # Adds a step to the group
+          #
+          # @param step_name [Symbol]
+          # @return [void]
+          def add_step(step_name)
+            @step_names << step_name
+          end
+
+          # Returns the number of steps in the group
+          #
+          # @return [Integer]
+          def size
+            @step_names.size
+          end
+
+          # Returns whether the group is empty
+          #
+          # @return [Boolean]
+          def empty?
+            @step_names.empty?
+          end
+
+          # Returns the fail-fast setting for this group
+          #
+          # @return [Boolean]
+          def fail_fast?
+            options[:fail_fast] == true
+          end
+
+          # Returns the concurrency limit for this group
+          #
+          # @return [Integer, nil]
+          def concurrency
+            options[:concurrency]
+          end
+
+          # Returns the timeout for the entire group
+          #
+          # @return [Integer, nil]
+          def timeout
+            options[:timeout]
+          end
+
+          # Converts to hash for serialization
+          #
+          # @return [Hash]
+          def to_h
+            {
+              name: name,
+              step_names: step_names,
+              fail_fast: fail_fast?,
+              concurrency: concurrency,
+              timeout: timeout
+            }.compact
+          end
+
+          # String representation
+          #
+          # @return [String]
+          def inspect
+            "#<ParallelGroup name=#{name.inspect} steps=#{step_names.inspect}>"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    class Workflow
+      module DSL
+        # Builder for defining routing options in a step
+        #
+        # Used with the `on:` option to route to different agents based on
+        # a runtime value. Supports a fluent interface for defining routes.
+        #
+        # @example Basic routing
+        #   step :process, on: -> { enrich.tier } do |route|
+        #     route.premium  PremiumAgent
+        #     route.standard StandardAgent
+        #     route.default  DefaultAgent
+        #   end
+        #
+        # @example With per-route options
+        #   step :process, on: -> { enrich.tier } do |route|
+        #     route.premium  PremiumAgent, input: -> { { vip: true } }, timeout: 5.minutes
+        #     route.standard StandardAgent
+        #     route.default  DefaultAgent
+        #   end
+        #
+        # @api private
+        class RouteBuilder
+          # Error raised when no route matches and no default is defined
+          class NoRouteError < StandardError
+            attr_reader :value, :available_routes
+
+            def initialize(message, value: nil, available_routes: [])
+              super(message)
+              @value = value
+              @available_routes = available_routes
+            end
+          end
+
+          def initialize
+            @routes = {}
+            @default = nil
+          end
+
+          # Returns all defined routes
+          #
+          # @return [Hash<Symbol, Hash>]
+          attr_reader :routes
+
+          # Returns or sets the default route
+          #
+          # When called with no arguments, returns the current default.
+          # When called with an agent, sets the default route.
+          #
+          # @param agent [Class, nil] Agent class for the default route
+          # @param options [Hash] Route options
+          # @return [Hash, nil]
+          def default(agent = nil, **options)
+            if agent.nil? && options.empty?
+              @default
+            else
+              @default = { agent: agent, options: options }
+            end
+          end
+
+          # Handles dynamic route definitions
+          #
+          # Any method call becomes a route definition.
+          #
+          # @param name [Symbol] Route name
+          # @param agent [Class] Agent class for this route
+          # @param options [Hash] Route options
+          # @return [void]
+          def method_missing(name, agent = nil, **options)
+            if name == :default
+              @default = { agent: agent, options: options }
+            else
+              @routes[name.to_sym] = { agent: agent, options: options }
+            end
+          end
+
+          def respond_to_missing?(name, include_private = false)
+            true
+          end
+
+          # Resolves the route for a given value
+          #
+          # @param value [Object] The routing key value
+          # @return [Hash] Route configuration with :agent and :options
+          # @raise [NoRouteError] If no route matches and no default is defined
+          def resolve(value)
+            key = normalize_key(value)
+
+            route = @routes[key] || @default
+
+            unless route
+              raise NoRouteError.new(
+                "No route defined for value: #{value.inspect} (normalized: #{key}). " \
+                "Available routes: #{@routes.keys.join(', ')}",
+                value: value,
+                available_routes: @routes.keys
+              )
+            end
+
+            route
+          end
+
+          # Returns all route names
+          #
+          # @return [Array<Symbol>]
+          def route_names
+            @routes.keys
+          end
+
+          # Checks if a route exists
+          #
+          # @param name [Symbol] Route name
+          # @return [Boolean]
+          def route_exists?(name)
+            @routes.key?(name.to_sym) || @default.present?
+          end
+
+          # Converts to hash for serialization
+          #
+          # @return [Hash]
+          def to_h
+            {
+              routes: @routes.transform_values do |r|
+                { agent: r[:agent]&.name, options: r[:options] }
+              end,
+              default: @default ? { agent: @default[:agent]&.name, options: @default[:options] } : nil
+            }
+          end
+
+          private
+
+          def normalize_key(value)
+            case value
+            when Symbol then value
+            when String then value.to_sym
+            when TrueClass then :true
+            when FalseClass then :false
+            when NilClass then :nil
+            else value.to_s.to_sym
+            end
+          end
+        end
+      end
+    end
+  end
+end