ruby_llm-agents 0.3.4 → 0.3.5

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

@@ -0,0 +1,306 @@
+# 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

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

@@ -0,0 +1,390 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    class Workflow
+      # Result wrapper for workflow executions with aggregate metrics
+      #
+      # Extends the base Result class with workflow-specific data including
+      # step results, branch results, routing information, and aggregated
+      # token/cost metrics across all child executions.
+      #
+      # @example Pipeline result
+      #   result = ContentPipeline.call(text: "input")
+      #   result.content              # Final output
+      #   result.steps[:extract]      # Individual step result
+      #   result.total_cost          # Sum of all steps
+      #
+      # @example Parallel result
+      #   result = ReviewAnalyzer.call(text: "review")
+      #   result.branches[:sentiment] # Branch result
+      #   result.failed_branches      # [:toxicity] if it failed
+      #
+      # @example Router result
+      #   result = SupportRouter.call(message: "billing issue")
+      #   result.routed_to           # :billing
+      #   result.classification      # Classification details
+      #
+      # @api public
+      class Result
+        extend ActiveSupport::Delegation
+
+        # @!attribute [r] content
+        #   @return [Object] The final processed content
+        attr_reader :content
+
+        # @!attribute [r] workflow_type
+        #   @return [String] The workflow class name
+        attr_reader :workflow_type
+
+        # @!attribute [r] workflow_id
+        #   @return [String] Unique identifier for this workflow execution
+        attr_reader :workflow_id
+
+        # @!group Step/Branch Results
+
+        # @!attribute [r] steps
+        #   @return [Hash<Symbol, Result>] Results from pipeline steps
+        attr_reader :steps
+
+        # @!attribute [r] branches
+        #   @return [Hash<Symbol, Result>] Results from parallel branches
+        attr_reader :branches
+
+        # @!endgroup
+
+        # @!group Router Results
+
+        # @!attribute [r] routed_to
+        #   @return [Symbol, nil] The route that was selected
+        attr_reader :routed_to
+
+        # @!attribute [r] classification
+        #   @return [Hash, nil] Classification details from router
+        attr_reader :classification
+
+        # @!attribute [r] classifier_result
+        #   @return [Result, nil] The classifier agent's result
+        attr_reader :classifier_result
+
+        # @!endgroup
+
+        # @!group Timing
+
+        # @!attribute [r] started_at
+        #   @return [Time] When the workflow started
+        attr_reader :started_at
+
+        # @!attribute [r] completed_at
+        #   @return [Time] When the workflow completed
+        attr_reader :completed_at
+
+        # @!attribute [r] duration_ms
+        #   @return [Integer] Total workflow duration in milliseconds
+        attr_reader :duration_ms
+
+        # @!endgroup
+
+        # @!group Status
+
+        # @!attribute [r] status
+        #   @return [String] Workflow status: "success", "error", "partial"
+        attr_reader :status
+
+        # @!attribute [r] error_class
+        #   @return [String, nil] Error class if failed
+        attr_reader :error_class
+
+        # @!attribute [r] error_message
+        #   @return [String, nil] Error message if failed
+        attr_reader :error_message
+
+        # @!attribute [r] errors
+        #   @return [Hash<Symbol, Exception>] Errors by step/branch name
+        attr_reader :errors
+
+        # @!endgroup
+
+        # Creates a new WorkflowResult
+        #
+        # @param content [Object] The final processed content
+        # @param options [Hash] Additional result metadata
+        def initialize(content:, **options)
+          @content = content
+          @workflow_type = options[:workflow_type]
+          @workflow_id = options[:workflow_id]
+
+          # Step/branch results
+          @steps = options[:steps] || {}
+          @branches = options[:branches] || {}
+
+          # Router results
+          @routed_to = options[:routed_to]
+          @classification = options[:classification]
+          @classifier_result = options[:classifier_result]
+
+          # Timing
+          @started_at = options[:started_at]
+          @completed_at = options[:completed_at]
+          @duration_ms = options[:duration_ms]
+
+          # Status
+          @status = options[:status] || "success"
+          @error_class = options[:error_class]
+          @error_message = options[:error_message]
+          @errors = options[:errors] || {}
+        end
+
+        # Returns all child results (steps + branches + classifier)
+        #
+        # @return [Array<Result>] All child results
+        def child_results
+          results = []
+          results.concat(steps.values) if steps.any?
+          results.concat(branches.values) if branches.any?
+          results << classifier_result if classifier_result
+          results.compact
+        end
+
+        # @!group Aggregate Metrics
+
+        # Returns total input tokens across all child executions
+        #
+        # @return [Integer] Total input tokens
+        def input_tokens
+          child_results.sum { |r| r.input_tokens || 0 }
+        end
+
+        # Returns total output tokens across all child executions
+        #
+        # @return [Integer] Total output tokens
+        def output_tokens
+          child_results.sum { |r| r.output_tokens || 0 }
+        end
+
+        # Returns total tokens across all child executions
+        #
+        # @return [Integer] Total tokens
+        def total_tokens
+          input_tokens + output_tokens
+        end
+
+        # Returns total cached tokens across all child executions
+        #
+        # @return [Integer] Total cached tokens
+        def cached_tokens
+          child_results.sum { |r| r.cached_tokens || 0 }
+        end
+
+        # Returns total input cost across all child executions
+        #
+        # @return [Float] Total input cost in USD
+        def input_cost
+          child_results.sum { |r| r.input_cost || 0.0 }
+        end
+
+        # Returns total output cost across all child executions
+        #
+        # @return [Float] Total output cost in USD
+        def output_cost
+          child_results.sum { |r| r.output_cost || 0.0 }
+        end
+
+        # Returns total cost across all child executions
+        #
+        # @return [Float] Total cost in USD
+        def total_cost
+          child_results.sum { |r| r.total_cost || 0.0 }
+        end
+
+        # Returns classification cost (router workflows only)
+        #
+        # @return [Float] Classification cost in USD
+        def classification_cost
+          classifier_result&.total_cost || 0.0
+        end
+
+        # @!endgroup
+
+        # @!group Status Helpers
+
+        # Returns whether the workflow succeeded
+        #
+        # @return [Boolean] true if status is "success"
+        def success?
+          status == "success"
+        end
+
+        # Returns whether the workflow failed
+        #
+        # @return [Boolean] true if status is "error"
+        def error?
+          status == "error"
+        end
+
+        # Returns whether the workflow partially succeeded
+        #
+        # @return [Boolean] true if status is "partial"
+        def partial?
+          status == "partial"
+        end
+
+        # @!endgroup
+
+        # @!group Pipeline Helpers
+
+        # Returns whether all pipeline steps succeeded
+        #
+        # @return [Boolean] true if all steps successful
+        def all_steps_successful?
+          return true if steps.empty?
+
+          steps.values.all? { |r| r.respond_to?(:success?) ? r.success? : true }
+        end
+
+        # Returns the names of failed steps
+        #
+        # @return [Array<Symbol>] Failed step names
+        def failed_steps
+          steps.select { |_, r| r.respond_to?(:error?) && r.error? }.keys
+        end
+
+        # Returns the names of skipped steps
+        #
+        # @return [Array<Symbol>] Skipped step names
+        def skipped_steps
+          steps.select { |_, r| r.respond_to?(:skipped?) && r.skipped? }.keys
+        end
+
+        # @!endgroup
+
+        # @!group Parallel Helpers
+
+        # Returns whether all parallel branches succeeded
+        #
+        # @return [Boolean] true if all branches successful
+        def all_branches_successful?
+          return true if branches.empty?
+
+          branches.values.all? { |r| r.nil? || (r.respond_to?(:success?) ? r.success? : true) }
+        end
+
+        # Returns the names of failed branches
+        #
+        # @return [Array<Symbol>] Failed branch names
+        def failed_branches
+          failed = branches.select { |_, r| r.respond_to?(:error?) && r.error? }.keys
+          failed += errors.keys
+          failed.uniq
+        end
+
+        # Returns the names of successful branches
+        #
+        # @return [Array<Symbol>] Successful branch names
+        def successful_branches
+          branches.select { |_, r| r.respond_to?(:success?) && r.success? }.keys
+        end
+
+        # @!endgroup
+
+        # Converts the result to a hash
+        #
+        # @return [Hash] All result data
+        def to_h
+          {
+            content: content,
+            workflow_type: workflow_type,
+            workflow_id: workflow_id,
+            status: status,
+            steps: steps.transform_values { |r| r.respond_to?(:to_h) ? r.to_h : r },
+            branches: branches.transform_values { |r| r.respond_to?(:to_h) ? r.to_h : r },
+            routed_to: routed_to,
+            classification: classification,
+            input_tokens: input_tokens,
+            output_tokens: output_tokens,
+            total_tokens: total_tokens,
+            cached_tokens: cached_tokens,
+            input_cost: input_cost,
+            output_cost: output_cost,
+            total_cost: total_cost,
+            started_at: started_at,
+            completed_at: completed_at,
+            duration_ms: duration_ms,
+            error_class: error_class,
+            error_message: error_message,
+            errors: errors.transform_values { |e| { class: e.class.name, message: e.message } }
+          }
+        end
+
+        # Delegate hash methods to content for convenience
+        delegate :[], :dig, :keys, :values, :each, :map, to: :content, allow_nil: true
+
+        # Custom to_json that includes workflow metadata
+        #
+        # @param args [Array] Arguments passed to to_json
+        # @return [String] JSON representation
+        def to_json(*args)
+          to_h.to_json(*args)
+        end
+      end
+
+      # Represents a skipped step result
+      class SkippedResult
+        attr_reader :step_name, :reason
+
+        def initialize(step_name, reason: nil)
+          @step_name = step_name
+          @reason = reason
+        end
+
+        def content
+          nil
+        end
+
+        def success?
+          true
+        end
+
+        def error?
+          false
+        end
+
+        def skipped?
+          true
+        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
+          { skipped: true, step_name: step_name, reason: reason }
+        end
+      end
+    end
+  end
+end