ruby_llm-agents 1.3.4 → 2.1.0

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

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

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

@@ -1,187 +0,0 @@
-# frozen_string_literal: true
-
-module RubyLLM
-  module Agents
-    class Workflow
-      module DSL
-        # Helper methods for scheduling wait_until time calculations
-        #
-        # These methods can be used within workflow definitions to create
-        # dynamic scheduling logic for wait_until time: expressions.
-        #
-        # @example Using in a workflow
-        #   class ReportWorkflow < RubyLLM::Agents::Workflow
-        #     include ScheduleHelpers
-        #
-        #     step :generate, ReportAgent
-        #     wait_until time: -> { next_weekday_at(9, 0) }
-        #     step :send, EmailAgent
-        #   end
-        #
-        # @api public
-        module ScheduleHelpers
-          # Returns the next occurrence of a weekday (Mon-Fri) at the specified time
-          #
-          # @param hour [Integer] Hour (0-23)
-          # @param minute [Integer] Minute (0-59)
-          # @param timezone [String, nil] Timezone name (uses system timezone if nil)
-          # @return [Time]
-          def next_weekday_at(hour, minute, timezone: nil)
-            now = current_time(timezone)
-            target = build_time(now, hour, minute, timezone)
-
-            # If target time has passed today or it's a weekend, find next weekday
-            if target <= now || weekend?(target)
-              target = advance_to_next_weekday(target)
-            end
-
-            target
-          end
-
-          # Returns the start of the next hour
-          #
-          # @param timezone [String, nil] Timezone name
-          # @return [Time]
-          def next_hour(timezone: nil)
-            now = current_time(timezone)
-            Time.new(now.year, now.month, now.day, now.hour + 1, 0, 0, now.utc_offset)
-          end
-
-          # Returns tomorrow at the specified time
-          #
-          # @param hour [Integer] Hour (0-23)
-          # @param minute [Integer] Minute (0-59)
-          # @param timezone [String, nil] Timezone name
-          # @return [Time]
-          def tomorrow_at(hour, minute, timezone: nil)
-            now = current_time(timezone)
-            tomorrow = now + 86_400 # Add one day in seconds
-            build_time(tomorrow, hour, minute, timezone)
-          end
-
-          # Returns the next available time within business hours
-          #
-          # Business hours default to Mon-Fri, 9am-5pm.
-          #
-          # @param start_hour [Integer] Business day start hour (default: 9)
-          # @param end_hour [Integer] Business day end hour (default: 17)
-          # @param timezone [String, nil] Timezone name
-          # @return [Time]
-          def in_business_hours(start_hour: 9, end_hour: 17, timezone: nil)
-            now = current_time(timezone)
-
-            # If current time is within business hours, return now
-            if within_business_hours?(now, start_hour, end_hour)
-              return now
-            end
-
-            # If before business hours today and it's a weekday
-            if now.hour < start_hour && !weekend?(now)
-              return build_time(now, start_hour, 0, timezone)
-            end
-
-            # Find next business day
-            target = next_weekday_at(start_hour, 0, timezone: timezone)
-            target
-          end
-
-          # Returns a specific day of the week at the specified time
-          #
-          # @param day [Symbol] Day name (:monday, :tuesday, etc.)
-          # @param hour [Integer] Hour (0-23)
-          # @param minute [Integer] Minute (0-59)
-          # @param timezone [String, nil] Timezone name
-          # @return [Time]
-          def next_day_at(day, hour, minute, timezone: nil)
-            days = %i[sunday monday tuesday wednesday thursday friday saturday]
-            target_wday = days.index(day.to_sym)
-            raise ArgumentError, "Unknown day: #{day}" unless target_wday
-
-            now = current_time(timezone)
-            current_wday = now.wday
-            days_ahead = (target_wday - current_wday) % 7
-
-            # If it's the same day but time has passed, add a week
-            if days_ahead == 0
-              target = build_time(now, hour, minute, timezone)
-              days_ahead = 7 if target <= now
-            end
-
-            future = now + (days_ahead * 86_400)
-            build_time(future, hour, minute, timezone)
-          end
-
-          # Returns time at the start of the next month
-          #
-          # @param day [Integer] Day of month (default: 1)
-          # @param hour [Integer] Hour (default: 0)
-          # @param minute [Integer] Minute (default: 0)
-          # @param timezone [String, nil] Timezone name
-          # @return [Time]
-          def next_month_at(day: 1, hour: 0, minute: 0, timezone: nil)
-            now = current_time(timezone)
-            year = now.year
-            month = now.month + 1
-
-            if month > 12
-              month = 1
-              year += 1
-            end
-
-            Time.new(year, month, day, hour, minute, 0, now.utc_offset)
-          end
-
-          # Returns a time offset from now
-          #
-          # @param seconds [Integer, Float] Seconds to add
-          # @param timezone [String, nil] Timezone name
-          # @return [Time]
-          def from_now(seconds, timezone: nil)
-            current_time(timezone) + seconds
-          end
-
-          private
-
-          def current_time(timezone)
-            if timezone && defined?(ActiveSupport::TimeZone)
-              ActiveSupport::TimeZone[timezone]&.now || Time.now
-            else
-              Time.now
-            end
-          end
-
-          def build_time(base, hour, minute, timezone)
-            if timezone && defined?(ActiveSupport::TimeZone)
-              zone = ActiveSupport::TimeZone[timezone]
-              if zone
-                zone.local(base.year, base.month, base.day, hour, minute, 0)
-              else
-                Time.new(base.year, base.month, base.day, hour, minute, 0, base.utc_offset)
-              end
-            else
-              Time.new(base.year, base.month, base.day, hour, minute, 0, base.utc_offset)
-            end
-          end
-
-          def weekend?(time)
-            time.saturday? || time.sunday?
-          end
-
-          def advance_to_next_weekday(time)
-            loop do
-              time += 86_400 # Add one day
-              break unless weekend?(time)
-            end
-            time
-          end
-
-          def within_business_hours?(time, start_hour, end_hour)
-            !weekend?(time) &&
-              time.hour >= start_hour &&
-              time.hour < end_hour
-          end
-        end
-      end
-    end
-  end
-end

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

@@ -1,352 +0,0 @@
-# frozen_string_literal: true
-
-module RubyLLM
-  module Agents
-    class Workflow
-      module DSL
-        # Configuration object for a workflow step
-        #
-        # Holds all the configuration options for a step including the agent,
-        # input mapping, conditions, retry settings, error handling, and metadata.
-        #
-        # @example Basic step config
-        #   StepConfig.new(name: :validate, agent: ValidatorAgent)
-        #
-        # @example Full configuration
-        #   StepConfig.new(
-        #     name: :process,
-        #     agent: ProcessorAgent,
-        #     description: "Process the order",
-        #     timeout: 30,
-        #     retry_config: { max: 3, on: [Timeout::Error] },
-        #     critical: true
-        #   )
-        #
-        # @api private
-        class StepConfig
-          attr_reader :name, :agent, :description, :options, :block
-
-          # @param name [Symbol] Step identifier
-          # @param agent [Class, nil] Agent class to execute
-          # @param description [String, nil] Human-readable description
-          # @param options [Hash] Step configuration options
-          # @param block [Proc, nil] Block for routing or custom logic
-          def initialize(name:, agent: nil, description: nil, options: {}, block: nil)
-            @name = name
-            @agent = agent
-            @options = normalize_options(options)
-            # description can come from direct param or from :desc option
-            @description = description || @options[:description]
-            @block = block
-          end
-
-          # Returns whether this step uses routing
-          #
-          # @return [Boolean]
-          def routing?
-            options[:on].present? && block.present?
-          end
-
-          # Returns whether this step has a custom block
-          #
-          # @return [Boolean]
-          def custom_block?
-            block.present? && !routing?
-          end
-
-          # Returns whether this step is optional (continues on failure)
-          #
-          # @return [Boolean]
-          def optional?
-            options[:optional] == true
-          end
-
-          # Returns whether this step executes a sub-workflow
-          #
-          # @return [Boolean]
-          def workflow?
-            return false unless agent.present?
-            return false unless agent.is_a?(Class)
-
-            # agent < Workflow returns nil if agent is not a subclass
-            (agent < RubyLLM::Agents::Workflow) == true
-          rescue TypeError, ArgumentError
-            # agent < Workflow raises TypeError/ArgumentError if agent is not a valid Class
-            false
-          end
-
-          # Returns whether this step uses iteration
-          #
-          # @return [Boolean]
-          def iteration?
-            options[:each].present?
-          end
-
-          # Returns the source for iteration items
-          #
-          # @return [Proc, nil]
-          def each_source
-            options[:each]
-          end
-
-          # Returns the concurrency level for iteration
-          #
-          # @return [Integer, nil]
-          def iteration_concurrency
-            options[:concurrency]
-          end
-
-          # Returns whether iteration should fail fast on first error
-          #
-          # @return [Boolean]
-          def iteration_fail_fast?
-            options[:fail_fast] == true
-          end
-
-          # Returns whether iteration should continue on individual item errors
-          #
-          # @return [Boolean]
-          def continue_on_error?
-            options[:continue_on_error] == true
-          end
-
-          # Returns whether this step is critical (fails workflow on error)
-          #
-          # @return [Boolean]
-          def critical?
-            options[:critical] != false && !optional?
-          end
-
-          # Returns the timeout for this step
-          #
-          # @return [Integer, nil] Timeout in seconds
-          def timeout
-            value = options[:timeout]
-            return nil unless value
-            value.respond_to?(:to_i) ? value.to_i : value
-          end
-
-          # Returns retry configuration
-          #
-          # @return [Hash] Retry settings
-          def retry_config
-            @retry_config ||= normalize_retry_config
-          end
-
-          # Returns the fallback agent(s)
-          #
-          # @return [Array<Class>] Fallback agents
-          def fallbacks
-            @fallbacks ||= Array(options[:fallback]).compact
-          end
-
-          # Returns the condition for step execution
-          #
-          # @return [Symbol, Proc, nil]
-          def if_condition
-            options[:if]
-          end
-
-          # Returns the negative condition for step execution
-          #
-          # @return [Symbol, Proc, nil]
-          def unless_condition
-            options[:unless]
-          end
-
-          # Returns the input mapper (lambda or pick config)
-          #
-          # @return [Proc, nil]
-          def input_mapper
-            options[:input]
-          end
-
-          # Returns fields to pick from previous step
-          #
-          # @return [Array<Symbol>, nil]
-          def pick_fields
-            options[:pick]
-          end
-
-          # Returns the source step for pick operation
-          #
-          # @return [Symbol, nil]
-          def pick_from
-            options[:from]
-          end
-
-          # Returns the default value when step is skipped or fails (optional)
-          #
-          # @return [Object, nil]
-          def default_value
-            options[:default]
-          end
-
-          # Returns the error handler
-          #
-          # @return [Symbol, Proc, nil]
-          def error_handler
-            options[:on_error]
-          end
-
-          # Returns UI-friendly label
-          #
-          # @return [String, nil]
-          def ui_label
-            options[:ui_label]
-          end
-
-          # Returns tags for the step
-          #
-          # @return [Array<Symbol>]
-          def tags
-            Array(options[:tags])
-          end
-
-          # Returns the throttle duration for this step
-          #
-          # @return [Integer, Float, nil] Minimum seconds between executions
-          def throttle
-            value = options[:throttle]
-            return nil unless value
-
-            value.respond_to?(:to_f) ? value.to_f : value
-          end
-
-          # Returns the rate limit configuration for this step
-          #
-          # @return [Hash, nil] Rate limit config with :calls and :per keys
-          def rate_limit
-            options[:rate_limit]
-          end
-
-          # Returns whether this step has throttling enabled
-          #
-          # @return [Boolean]
-          def throttled?
-            throttle.present? || rate_limit.present?
-          end
-
-          # Resolves the input for this step
-          #
-          # @param workflow [Workflow] The workflow instance
-          # @param previous_result [Result, nil] Previous step result
-          # @return [Hash] Input for the agent
-          def resolve_input(workflow, previous_result)
-            if input_mapper
-              workflow.instance_exec(&input_mapper)
-            elsif pick_fields
-              source = pick_from ? workflow.step_result(pick_from) : previous_result
-              source_hash = extract_content_hash(source)
-              source_hash.slice(*pick_fields)
-            else
-              # Default: merge original input with previous step output
-              base = workflow.input.to_h
-              previous_hash = extract_content_hash(previous_result)
-              base.merge(previous_hash)
-            end
-          end
-
-          # Resolves the route for routing steps
-          #
-          # @param workflow [Workflow] The workflow instance
-          # @return [Hash] Route configuration with :agent and :options
-          def resolve_route(workflow)
-            raise "Not a routing step" unless routing?
-
-            value = workflow.instance_exec(&options[:on])
-            builder = RouteBuilder.new
-            block.call(builder)
-            builder.resolve(value)
-          end
-
-          # Evaluates whether the step should execute
-          #
-          # @param workflow [Workflow] The workflow instance
-          # @return [Boolean]
-          def should_execute?(workflow)
-            passes_if = if_condition.nil? || evaluate_condition(workflow, if_condition)
-            passes_unless = unless_condition.nil? || !evaluate_condition(workflow, unless_condition)
-            passes_if && passes_unless
-          end
-
-          # Converts to hash for serialization
-          #
-          # @return [Hash]
-          def to_h
-            {
-              name: name,
-              agent: agent&.name,
-              description: description,
-              timeout: timeout,
-              optional: optional?,
-              critical: critical?,
-              retry_config: retry_config,
-              fallbacks: fallbacks.map(&:name),
-              tags: tags,
-              ui_label: ui_label,
-              workflow: workflow?,
-              iteration: iteration?,
-              iteration_concurrency: iteration_concurrency,
-              iteration_fail_fast: iteration_fail_fast?,
-              throttle: throttle,
-              rate_limit: rate_limit
-            }.compact
-          end
-
-          private
-
-          def normalize_options(opts)
-            # Handle desc as alias for description
-            opts[:description] ||= opts.delete(:desc)
-            opts
-          end
-
-          def normalize_retry_config
-            retry_opt = options[:retry]
-            on_opt = options[:on]
-
-            case retry_opt
-            when Integer
-              {
-                max: retry_opt,
-                on: normalize_error_classes(on_opt) || [StandardError],
-                backoff: :none,
-                delay: 1
-              }
-            when Hash
-              {
-                max: retry_opt[:max] || 3,
-                on: normalize_error_classes(retry_opt[:on] || on_opt) || [StandardError],
-                backoff: retry_opt[:backoff] || :none,
-                delay: retry_opt[:delay] || 1
-              }
-            else
-              { max: 0, on: [], backoff: :none, delay: 1 }
-            end
-          end
-
-          def normalize_error_classes(classes)
-            return nil if classes.nil?
-            Array(classes)
-          end
-
-          def evaluate_condition(workflow, condition)
-            case condition
-            when Symbol then workflow.send(condition)
-            when Proc then workflow.instance_exec(&condition)
-            else condition
-            end
-          end
-
-          def extract_content_hash(result)
-            return {} if result.nil?
-
-            content = result.respond_to?(:content) ? result.content : result
-            content.is_a?(Hash) ? content : {}
-          end
-        end
-      end
-    end
-  end
-end