ruby_llm-agents 1.3.4 → 2.0.0

data/lib/ruby_llm/agents/workflow/notifiers/webhook.rb

@@ -1,121 +0,0 @@
-# frozen_string_literal: true
-
-require "net/http"
-require "uri"
-require "json"
-
-module RubyLLM
-  module Agents
-    class Workflow
-      module Notifiers
-        # Generic webhook notification adapter for approval requests
-        #
-        # Posts approval notifications to any HTTP endpoint.
-        # Supports custom headers for authentication and content negotiation.
-        #
-        # @example Basic usage
-        #   notifier = Webhook.new(url: "https://api.example.com/approvals")
-        #   notifier.notify(approval, "Please review")
-        #
-        # @example With authentication
-        #   notifier = Webhook.new(
-        #     url: "https://api.example.com/approvals",
-        #     headers: { "Authorization" => "Bearer token123" }
-        #   )
-        #
-        # @api public
-        class Webhook < Base
-          class << self
-            attr_accessor :default_url, :default_headers, :timeout
-
-            # Configure the webhook notifier
-            #
-            # @yield [self] The webhook notifier class
-            # @return [void]
-            def configure
-              yield self
-            end
-
-            # Reset configuration to defaults
-            #
-            # @return [void]
-            def reset!
-              @default_url = nil
-              @default_headers = nil
-              @timeout = nil
-            end
-          end
-
-          # @param url [String] The webhook URL
-          # @param headers [Hash] Additional HTTP headers
-          # @param timeout [Integer] Request timeout in seconds
-          def initialize(url: nil, headers: {}, timeout: nil)
-            @url = url || self.class.default_url
-            @headers = (self.class.default_headers || {}).merge(headers)
-            @timeout = timeout || self.class.timeout || 10
-          end
-
-          # Send a webhook notification
-          #
-          # @param approval [Approval] The approval request
-          # @param message [String] The notification message
-          # @return [Boolean] true if webhook returned 2xx status
-          def notify(approval, message)
-            return false unless @url
-
-            payload = build_payload(approval, message)
-            send_request(payload)
-          rescue StandardError => e
-            handle_error(e, approval)
-            false
-          end
-
-          private
-
-          def build_payload(approval, message)
-            {
-              event: "approval_requested",
-              approval: {
-                id: approval.id,
-                workflow_id: approval.workflow_id,
-                workflow_type: approval.workflow_type,
-                name: approval.name,
-                status: approval.status,
-                approvers: approval.approvers,
-                expires_at: approval.expires_at&.iso8601,
-                created_at: approval.created_at.iso8601,
-                metadata: approval.metadata
-              },
-              message: message,
-              timestamp: Time.now.iso8601
-            }
-          end
-
-          def send_request(payload)
-            uri = URI.parse(@url)
-            http = Net::HTTP.new(uri.host, uri.port)
-            http.use_ssl = uri.scheme == "https"
-            http.open_timeout = @timeout
-            http.read_timeout = @timeout
-
-            request = Net::HTTP::Post.new(uri.request_uri)
-            request["Content-Type"] = "application/json"
-            @headers.each { |key, value| request[key] = value }
-            request.body = payload.to_json
-
-            response = http.request(request)
-            response.code.to_i.between?(200, 299)
-          end
-
-          def handle_error(error, approval)
-            if defined?(Rails) && Rails.logger
-              Rails.logger.error(
-                "[RubyLLM::Agents] Webhook notification failed for approval #{approval.id}: #{error.message}"
-              )
-            end
-          end
-        end
-      end
-    end
-  end
-end

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

@@ -1,70 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "notifiers/base"
-require_relative "notifiers/email"
-require_relative "notifiers/slack"
-require_relative "notifiers/webhook"
-
-module RubyLLM
-  module Agents
-    class Workflow
-      module Notifiers
-        # Configure and register default notifiers
-        #
-        # @example Register notifiers
-        #   RubyLLM::Agents::Workflow::Notifiers.setup do |config|
-        #     config.register :email, Email.new
-        #     config.register :slack, Slack.new(webhook_url: "...")
-        #   end
-        #
-        # @api public
-        class << self
-          # Setup notifiers with configuration
-          #
-          # @yield [Registry] The notifier registry
-          # @return [void]
-          def setup
-            yield Registry
-          end
-
-          # Register a notifier
-          #
-          # @param name [Symbol] The notifier name
-          # @param notifier [Base] The notifier instance
-          # @return [void]
-          def register(name, notifier)
-            Registry.register(name, notifier)
-          end
-
-          # Get a notifier
-          #
-          # @param name [Symbol] The notifier name
-          # @return [Base, nil]
-          def [](name)
-            Registry.get(name)
-          end
-
-          # Send notifications through multiple channels
-          #
-          # @param approval [Approval] The approval request
-          # @param message [String] The notification message
-          # @param channels [Array<Symbol>] The channels to notify
-          # @return [Hash<Symbol, Boolean>] Results per channel
-          def notify(approval, message, channels:)
-            Registry.notify_all(approval, message, channels: channels)
-          end
-
-          # Reset all notifier configuration
-          #
-          # @return [void]
-          def reset!
-            Registry.reset!
-            Email.reset!
-            Slack.reset!
-            Webhook.reset!
-          end
-        end
-      end
-    end
-  end
-end

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

@@ -1,416 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "result"
-require_relative "instrumentation"
-require_relative "thread_pool"
-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 using the DSL:
-    # - Sequential steps with data flowing between them
-    # - Parallel execution with result aggregation
-    # - Conditional routing based on step results
-    #
-    # @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
-    #
-    # @api public
-    class Workflow
-      include Workflow::Instrumentation
-      include Workflow::DSL
-
-      class << self
-        # @!attribute [rw] version
-        #   @return [String] Version identifier for the workflow
-        attr_accessor :_version
-
-        # @!attribute [rw] timeout
-        #   @return [Integer, nil] Total timeout for the entire workflow in seconds
-        attr_accessor :_timeout
-
-        # @!attribute [rw] max_cost
-        #   @return [Float, nil] Maximum cost threshold for the workflow
-        attr_accessor :_max_cost
-
-        # @!attribute [rw] description
-        #   @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
-        # @return [String] The current version
-        def version(value = nil)
-          if value
-            self._version = value
-          else
-            _version || "1.0"
-          end
-        end
-
-        # Sets or returns the workflow timeout
-        #
-        # @param value [Integer, ActiveSupport::Duration, nil] Timeout to set
-        # @return [Integer, nil] The current timeout in seconds
-        def timeout(value = nil)
-          if value
-            self._timeout = value.is_a?(ActiveSupport::Duration) ? value.to_i : value
-          else
-            _timeout
-          end
-        end
-
-        # Sets or returns the maximum cost threshold
-        #
-        # @param value [Float, nil] Max cost in USD
-        # @return [Float, nil] The current max cost
-        def max_cost(value = nil)
-          if value
-            self._max_cost = value.to_f
-          else
-            _max_cost
-          end
-        end
-
-        # Sets or returns the workflow description
-        #
-        # @param value [String, nil] Description text to set
-        # @return [String, nil] The current description
-        def description(value = nil)
-          if value
-            self._description = value
-          else
-            _description
-          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(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
-
-      # @!attribute [r] options
-      #   @return [Hash] The options passed to the workflow
-      attr_reader :options
-
-      # @!attribute [r] workflow_id
-      #   @return [String] Unique identifier for this workflow execution
-      attr_reader :workflow_id
-
-      # @!attribute [r] execution_id
-      #   @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
-      def initialize(**kwargs)
-        @options = kwargs
-        @workflow_id = SecureRandom.uuid
-        @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
-      #
-      # 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(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
-      #
-      # Passes execution metadata for proper tracking and hierarchy.
-      #
-      # @param agent_class [Class] The agent class to execute
-      # @param input [Hash] Parameters to pass to the agent
-      # @param step_name [String, Symbol] Name of the workflow step
-      # @yield [chunk] Optional block for streaming
-      # @return [Result] The agent result
-      def execute_agent(agent_class, input, step_name: nil, &block)
-        metadata = {
-          parent_execution_id: execution_id,
-          root_execution_id: root_execution_id,
-          workflow_id: workflow_id,
-          workflow_type: self.class.name,
-          workflow_step: step_name&.to_s
-        }.compact
-
-        # Merge workflow metadata with any existing metadata
-        merged_input = input.merge(
-          execution_metadata: metadata.merge(input[:execution_metadata] || {})
-        )
-
-        result = agent_class.call(**merged_input, &block)
-
-        # Track accumulated cost for max_cost enforcement
-        @accumulated_cost += result.total_cost if result.respond_to?(:total_cost) && result.total_cost
-
-        # Check cost threshold
-        check_cost_threshold!
-
-        result
-      end
-
-      # Returns the root execution ID for the workflow
-      #
-      # @return [Integer, nil] The root execution ID
-      def root_execution_id
-        @root_execution_id || execution_id
-      end
-
-      # Sets the root execution ID
-      #
-      # @param id [Integer] The root execution ID
-      def root_execution_id=(id)
-        @root_execution_id = id
-      end
-
-      # Checks if accumulated cost exceeds the threshold
-      #
-      # @raise [WorkflowCostExceededError] If cost exceeds max_cost
-      def check_cost_threshold!
-        # 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 ($#{effective_max})",
-          accumulated_cost: @accumulated_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
-
-      # Hook for subclasses to transform input before a step
-      #
-      # @param step_name [Symbol] The step name
-      # @param context [Hash] Current workflow context
-      # @return [Hash] Transformed input for the step
-      def before_step(step_name, context)
-        method_name = :"before_#{step_name}"
-        if respond_to?(method_name, true)
-          send(method_name, context)
-        else
-          extract_step_input(context)
-        end
-      end
-
-      # Extracts input for the next step from context
-      #
-      # Default behavior: use the last step's content or original input
-      #
-      # @param context [Hash] Current workflow context
-      # @return [Hash] Input for the next step
-      def extract_step_input(context)
-        # Get the last non-input result
-        last_result = context.except(:input).values.last
-
-        if last_result.is_a?(Result) || last_result.is_a?(Workflow::Result)
-          # If content is a hash, use it; otherwise wrap it
-          content = last_result.content
-          content.is_a?(Hash) ? content : { input: content }
-        else
-          context[:input] || {}
-        end
-      end
-    end
-
-    # Error raised when workflow cost exceeds the configured maximum
-    class WorkflowCostExceededError < StandardError
-      attr_reader :accumulated_cost, :max_cost
-
-      def initialize(message, accumulated_cost:, max_cost:)
-        super(message)
-        @accumulated_cost = accumulated_cost
-        @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