ruby_llm-agents 1.0.0 → 1.2.0

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

@@ -1,299 +0,0 @@
-# frozen_string_literal: true
-
-module RubyLLM
-  module Agents
-    class Workflow
-      # Concurrent workflow execution pattern
-      #
-      # Executes multiple agents simultaneously and aggregates their results.
-      # Supports fail-fast behavior, optional branches, and custom aggregation.
-      #
-      # @example Basic parallel execution
-      #   class ReviewAnalyzer < RubyLLM::Agents::Workflow::Parallel
-      #     version "1.0"
-      #
-      #     branch :sentiment,  agent: SentimentAgent
-      #     branch :summary,    agent: SummaryAgent
-      #     branch :categories, agent: CategoryAgent
-      #   end
-      #
-      #   result = ReviewAnalyzer.call(text: "Great product!")
-      #   result.branches[:sentiment].content  # "positive"
-      #   result.branches[:summary].content    # "User liked the product"
-      #
-      # @example With optional branches and custom aggregation
-      #   class FullAnalyzer < RubyLLM::Agents::Workflow::Parallel
-      #     branch :sentiment, agent: SentimentAgent
-      #     branch :toxicity,  agent: ToxicityAgent, optional: true
-      #
-      #     def aggregate(results)
-      #       {
-      #         sentiment: results[:sentiment]&.content,
-      #         toxicity: results[:toxicity]&.content,
-      #         safe: results[:toxicity]&.content != "toxic"
-      #       }
-      #     end
-      #   end
-      #
-      # @example With fail-fast enabled
-      #   class CriticalAnalyzer < RubyLLM::Agents::Workflow::Parallel
-      #     fail_fast true  # Stop all branches on first failure
-      #
-      #     branch :auth,     agent: AuthValidator
-      #     branch :sanity,   agent: SanityChecker
-      #   end
-      #
-      # @api public
-      class Parallel < Workflow
-        class << self
-          # Returns the defined branches
-          #
-          # @return [Hash<Symbol, Hash>] Branch configurations
-          def branches
-            @branches ||= {}
-          end
-
-          # Inherits branches from parent class
-          def inherited(subclass)
-            super
-            subclass.instance_variable_set(:@branches, branches.dup)
-            subclass.instance_variable_set(:@fail_fast, @fail_fast)
-            subclass.instance_variable_set(:@concurrency, @concurrency)
-          end
-
-          # Defines a parallel branch
-          #
-          # @param name [Symbol] Branch identifier
-          # @param agent [Class] The agent class to execute
-          # @param optional [Boolean] If true, branch failure won't fail the workflow
-          # @param input [Proc, nil] Lambda to transform input for this branch
-          # @return [void]
-          #
-          # @example Basic branch
-          #   branch :analyze, agent: AnalyzerAgent
-          #
-          # @example Optional branch
-          #   branch :enrich, agent: EnricherAgent, optional: true
-          #
-          # @example With custom input
-          #   branch :summarize, agent: SummaryAgent, input: ->(opts) { { text: opts[:content] } }
-          def branch(name, agent:, optional: false, input: nil)
-            branches[name] = {
-              agent: agent,
-              optional: optional,
-              input: input
-            }
-          end
-
-          # Sets or returns fail-fast behavior
-          #
-          # When true, cancels remaining branches when any required branch fails.
-          #
-          # @param value [Boolean, nil] Whether to fail fast
-          # @return [Boolean] Current fail-fast setting
-          def fail_fast(value = nil)
-            if value.nil?
-              @fail_fast || false
-            else
-              @fail_fast = value
-            end
-          end
-
-          # Alias for checking fail_fast setting
-          def fail_fast?
-            fail_fast
-          end
-
-          # Sets or returns concurrency limit
-          #
-          # @param value [Integer, nil] Max concurrent branches (nil = unlimited)
-          # @return [Integer, nil] Current concurrency limit
-          def concurrency(value = nil)
-            if value.nil?
-              @concurrency
-            else
-              @concurrency = value
-            end
-          end
-        end
-
-        # Executes the parallel workflow
-        #
-        # Runs all branches concurrently and aggregates results.
-        #
-        # @yield [chunk] Yields chunks when streaming (not typically used in parallel)
-        # @return [WorkflowResult] The parallel result
-        def call(&block)
-          instrument_workflow do
-            execute_parallel(&block)
-          end
-        end
-
-        # Aggregates branch results into final content
-        #
-        # Override this method to customize how results are combined.
-        #
-        # @param results [Hash<Symbol, Result>] Branch results
-        # @return [Object] Aggregated content
-        def aggregate(results)
-          # Default: return hash of branch contents
-          results.transform_values { |r| r&.content }
-        end
-
-        private
-
-        # Executes all branches in parallel
-        #
-        # @return [WorkflowResult] The parallel result
-        def execute_parallel(&block)
-          results = {}
-          errors = {}
-          mutex = Mutex.new
-
-          # Determine pool size based on concurrency setting
-          pool_size = self.class.concurrency || self.class.branches.size
-
-          # Use async executor when in async context, otherwise use thread pool
-          pool = create_executor(pool_size)
-
-          # Submit all branches to the pool
-          self.class.branches.each do |name, config|
-            pool.post do
-              Thread.current.name = "parallel-#{name}"
-              Thread.current[:branch_name] = name
-
-              begin
-                # Check if pool was aborted (fail-fast triggered)
-                if pool.aborted?
-                  mutex.synchronize { results[name] = nil }
-                  next
-                end
-
-                # Build input for this branch
-                branch_input = build_branch_input(name, config)
-
-                # Execute the branch
-                result = execute_agent(
-                  config[:agent],
-                  branch_input,
-                  step_name: name,
-                  &block
-                )
-
-                mutex.synchronize do
-                  results[name] = result
-
-                  # Check for failure and trigger fail-fast if needed
-                  if result.respond_to?(:error?) && result.error? && !config[:optional]
-                    pool.abort! if self.class.fail_fast?
-                  end
-                end
-              rescue StandardError => e
-                mutex.synchronize do
-                  errors[name] = e
-                  results[name] = nil
-                  pool.abort! if self.class.fail_fast? && !config[:optional]
-                end
-              end
-            end
-          end
-
-          # Wait for all branches to complete
-          pool.wait_for_completion
-          pool.shutdown
-
-          # Determine overall status
-          status = determine_parallel_status(results, errors)
-
-          # Aggregate results
-          final_content = begin
-            aggregate(results)
-          rescue StandardError => e
-            errors[:aggregate] = e
-            results.transform_values { |r| r&.content }
-          end
-
-          build_parallel_result(
-            content: final_content,
-            branches: results,
-            errors: errors,
-            status: status
-          )
-        end
-
-        # Builds input for a specific branch
-        #
-        # @param name [Symbol] Branch name
-        # @param config [Hash] Branch configuration
-        # @return [Hash] Input for the branch
-        def build_branch_input(name, config)
-          if config[:input]
-            config[:input].call(options)
-          elsif respond_to?(:"before_#{name}", true)
-            send(:"before_#{name}", options)
-          else
-            options.dup
-          end
-        end
-
-        # Determines the overall parallel status
-        #
-        # @param results [Hash] Branch results
-        # @param errors [Hash] Branch errors
-        # @return [String] Status: "success", "partial", or "error"
-        def determine_parallel_status(results, errors)
-          required_branches = self.class.branches.reject { |_, c| c[:optional] }.keys
-          failed_required = required_branches.select do |name|
-            errors[name] || (results[name].respond_to?(:error?) && results[name].error?)
-          end
-
-          if failed_required.any?
-            "error"
-          elsif errors.any?
-            "partial"
-          else
-            "success"
-          end
-        end
-
-        # Builds the final parallel result
-        #
-        # @param content [Object] Aggregated content
-        # @param branches [Hash] Branch results
-        # @param errors [Hash] Branch errors
-        # @param status [String] Final status
-        # @return [WorkflowResult] The parallel result
-        def build_parallel_result(content:, branches:, errors:, status:)
-          Workflow::Result.new(
-            content: content,
-            workflow_type: self.class.name,
-            workflow_id: workflow_id,
-            branches: branches,
-            errors: errors,
-            status: status,
-            started_at: @workflow_started_at,
-            completed_at: Time.current,
-            duration_ms: (((Time.current - @workflow_started_at) * 1000).round if @workflow_started_at)
-          )
-        end
-
-        # Creates the appropriate executor based on context
-        #
-        # Uses AsyncExecutor when in async context for fiber-based concurrency,
-        # otherwise falls back to ThreadPool for traditional thread-based execution.
-        #
-        # @param size [Integer] Number of concurrent workers/fibers
-        # @return [ThreadPool, AsyncExecutor] The executor instance
-        def create_executor(size)
-          config = RubyLLM::Agents.configuration
-
-          if config.async_context?
-            AsyncExecutor.new(max_concurrent: size)
-          else
-            ThreadPool.new(size: size)
-          end
-        end
-      end
-    end
-  end
-end

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

@@ -1,306 +0,0 @@
-# frozen_string_literal: true
-
-module RubyLLM
-  module Agents
-    class Workflow
-      # Sequential workflow execution pattern
-      #
-      # Executes agents in order, passing each step's output as input to the next.
-      # Supports conditional step skipping, error handling, and input transformation.
-      #
-      # @example Basic pipeline
-      #   class ContentPipeline < RubyLLM::Agents::Workflow::Pipeline
-      #     version "1.0"
-      #
-      #     step :extract,  agent: ExtractorAgent
-      #     step :validate, agent: ValidatorAgent
-      #     step :format,   agent: FormatterAgent
-      #   end
-      #
-      #   result = ContentPipeline.call(text: "raw input")
-      #   result.steps[:extract].content  # First step output
-      #   result.content                  # Final output
-      #
-      # @example With conditional skipping
-      #   class ConditionalPipeline < RubyLLM::Agents::Workflow::Pipeline
-      #     step :check,    agent: CheckerAgent
-      #     step :process,  agent: ProcessorAgent, skip_on: ->(ctx) { ctx[:check].content[:skip] }
-      #     step :finalize, agent: FinalizerAgent
-      #   end
-      #
-      # @example With input transformation
-      #   class TransformPipeline < RubyLLM::Agents::Workflow::Pipeline
-      #     step :analyze, agent: AnalyzerAgent
-      #     step :enrich,  agent: EnricherAgent
-      #
-      #     def before_enrich(context)
-      #       { data: context[:analyze].content, extra_field: "value" }
-      #     end
-      #   end
-      #
-      # @api public
-      class Pipeline < Workflow
-        # Simple error result for failed steps
-        # @api private
-        class ErrorResult
-          attr_reader :error_class, :error_message, :step_name
-
-          def initialize(step_name:, error_class:, error_message:)
-            @step_name = step_name
-            @error_class = error_class
-            @error_message = error_message
-          end
-
-          def content = nil
-          def success? = false
-          def error? = true
-          def input_tokens = 0
-          def output_tokens = 0
-          def total_tokens = 0
-          def cached_tokens = 0
-          def input_cost = 0.0
-          def output_cost = 0.0
-          def total_cost = 0.0
-
-          def to_h
-            {
-              error: true,
-              step_name: step_name,
-              error_class: error_class,
-              error_message: error_message
-            }
-          end
-        end
-
-        class << self
-          # Returns the defined steps
-          #
-          # @return [Hash<Symbol, Hash>] Step configurations
-          def steps
-            @steps ||= {}
-          end
-
-          # Inherits steps from parent class
-          def inherited(subclass)
-            super
-            subclass.instance_variable_set(:@steps, steps.dup)
-          end
-
-          # Defines a pipeline step
-          #
-          # @param name [Symbol] Step identifier
-          # @param agent [Class] The agent class to execute
-          # @param skip_on [Proc, nil] Lambda to determine if step should be skipped
-          # @param continue_on_error [Boolean] Whether to continue if step fails
-          # @param optional [Boolean] Mark step as optional (alias for continue_on_error)
-          # @return [void]
-          #
-          # @example Basic step
-          #   step :process, agent: ProcessorAgent
-          #
-          # @example With skip condition
-          #   step :validate, agent: ValidatorAgent, skip_on: ->(ctx) { ctx[:input][:skip_validation] }
-          #
-          # @example Optional step (won't fail pipeline)
-          #   step :enrich, agent: EnricherAgent, optional: true
-          def step(name, agent:, skip_on: nil, continue_on_error: false, optional: false)
-            steps[name] = {
-              agent: agent,
-              skip_on: skip_on,
-              continue_on_error: continue_on_error || optional,
-              index: steps.size
-            }
-          end
-        end
-
-        # Executes the pipeline
-        #
-        # Runs each step sequentially, passing output to the next step.
-        # Tracks all step results and builds aggregate metrics.
-        #
-        # @yield [chunk] Yields chunks when streaming (passed to individual agents)
-        # @return [WorkflowResult] The pipeline result
-        def call(&block)
-          instrument_workflow do
-            execute_pipeline(&block)
-          end
-        end
-
-        private
-
-        # Executes the pipeline steps
-        #
-        # @return [WorkflowResult] The pipeline result
-        def execute_pipeline(&block)
-          context = { input: options }
-          step_results = {}
-          errors = {}
-          last_successful_result = nil
-          status = "success"
-
-          self.class.steps.each do |name, config|
-            # Check skip condition
-            if should_skip_step?(config, context)
-              step_results[name] = SkippedResult.new(name, reason: "skip_on condition met")
-              next
-            end
-
-            begin
-              # Build input for this step
-              step_input = before_step(name, context)
-
-              # Execute the step
-              result = execute_agent(
-                config[:agent],
-                step_input,
-                step_name: name,
-                &block
-              )
-
-              step_results[name] = result
-              context[name] = result
-              last_successful_result = result
-
-              # Check if step failed
-              if result.respond_to?(:error?) && result.error?
-                errors[name] = StandardError.new(result.error_message || "Step failed")
-
-                unless config[:continue_on_error]
-                  status = "error"
-                  break
-                end
-
-                status = "partial" if status == "success"
-              end
-            rescue StandardError => e
-              # Handle step execution errors
-              errors[name] = e
-              step_results[name] = build_error_result(name, e)
-              context[name] = step_results[name]
-
-              # Check continue_on_error first - if true, continue without calling handler
-              if config[:continue_on_error]
-                status = "partial" if status == "success"
-                next
-              end
-
-              # Call error handler hook for non-optional steps
-              action = on_step_failure(name, e, context)
-
-              case action
-              when :skip
-                status = "partial" if status == "success"
-                next
-              when :abort
-                status = "error"
-                break
-              when Result, Workflow::Result
-                # Use the returned result as the step result
-                step_results[name] = action
-                context[name] = action
-                last_successful_result = action
-                status = "partial" if status == "success"
-              else
-                status = "error"
-                break
-              end
-            end
-          end
-
-          # Build final content from last successful step
-          final_content = extract_final_content(last_successful_result, context)
-
-          build_pipeline_result(
-            content: final_content,
-            steps: step_results,
-            errors: errors,
-            status: status
-          )
-        end
-
-        # Checks if a step should be skipped
-        #
-        # @param config [Hash] Step configuration
-        # @param context [Hash] Current workflow context
-        # @return [Boolean] true if step should be skipped
-        def should_skip_step?(config, context)
-          return false unless config[:skip_on]
-
-          config[:skip_on].call(context)
-        rescue StandardError => e
-          Rails.logger.warn("[RubyLLM::Agents::Pipeline] skip_on evaluation failed: #{e.message}")
-          false
-        end
-
-        # Hook for handling step failures
-        #
-        # Override in subclass to customize error handling.
-        #
-        # @param step_name [Symbol] The failed step
-        # @param error [Exception] The error
-        # @param context [Hash] Current workflow context
-        # @return [Symbol, Result] :skip to continue, :abort to stop, or a fallback Result
-        def on_step_failure(step_name, error, context)
-          # Default: check if method exists for specific step
-          method_name = :"on_#{step_name}_failure"
-          if respond_to?(method_name, true)
-            send(method_name, error, context)
-          else
-            :abort
-          end
-        end
-
-        # Extracts the final content from the pipeline
-        #
-        # @param last_result [Result, nil] The last successful result
-        # @param context [Hash] The workflow context
-        # @return [Object] The final content
-        def extract_final_content(last_result, context)
-          if last_result.respond_to?(:content)
-            last_result.content
-          elsif context.keys.size > 1
-            # Return the last non-input context entry
-            last_key = context.keys.reject { |k| k == :input }.last
-            context[last_key]&.content
-          else
-            nil
-          end
-        end
-
-        # Builds an error result for a failed step
-        #
-        # @param step_name [Symbol] The step name
-        # @param error [Exception] The error
-        # @return [ErrorResult] Error result object
-        def build_error_result(step_name, error)
-          ErrorResult.new(
-            step_name: step_name,
-            error_class: error.class.name,
-            error_message: error.message
-          )
-        end
-
-        # Builds the final pipeline result
-        #
-        # @param content [Object] Final content
-        # @param steps [Hash] Step results
-        # @param errors [Hash] Step errors
-        # @param status [String] Final status
-        # @return [WorkflowResult] The pipeline result
-        def build_pipeline_result(content:, steps:, errors:, status:)
-          Workflow::Result.new(
-            content: content,
-            workflow_type: self.class.name,
-            workflow_id: workflow_id,
-            steps: steps,
-            errors: errors,
-            status: status,
-            started_at: @workflow_started_at,
-            completed_at: Time.current,
-            duration_ms: (((Time.current - @workflow_started_at) * 1000).round if @workflow_started_at)
-          )
-        end
-      end
-    end
-  end
-end