ruby_llm-agents 1.3.4 → 2.1.0

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

@@ -1,185 +0,0 @@
-# frozen_string_literal: true
-
-module RubyLLM
-  module Agents
-    class Workflow
-      # Simple bounded thread pool for parallel workflow execution
-      #
-      # Provides a fixed-size pool of worker threads that process submitted tasks.
-      # Supports fail-fast abort and graceful shutdown.
-      #
-      # @example Basic usage
-      #   pool = ThreadPool.new(size: 4)
-      #   pool.post { perform_task_1 }
-      #   pool.post { perform_task_2 }
-      #   pool.wait_for_completion
-      #   pool.shutdown
-      #
-      # @example With fail-fast
-      #   pool = ThreadPool.new(size: 4)
-      #   begin
-      #     pool.post { risky_task }
-      #   rescue => e
-      #     pool.abort!  # Signal workers to stop
-      #   end
-      #   pool.shutdown
-      #
-      # @api private
-      class ThreadPool
-        attr_reader :size
-
-        # Creates a new thread pool
-        #
-        # @param size [Integer] Number of worker threads (default: 4)
-        def initialize(size: 4)
-          @size = size
-          @queue = Queue.new
-          @workers = []
-          @mutex = Mutex.new
-          @completion_condition = ConditionVariable.new
-          @pending_count = 0
-          @completed_count = 0
-          @aborted = false
-          @shutdown = false
-
-          spawn_workers
-        end
-
-        # Submits a task to the pool
-        #
-        # @yield Block to execute in a worker thread
-        # @return [void]
-        # @raise [RuntimeError] If pool has been shutdown
-        def post(&block)
-          raise "ThreadPool has been shutdown" if @shutdown
-
-          @mutex.synchronize do
-            @pending_count += 1
-          end
-
-          @queue.push(block)
-        end
-
-        # Signals workers to abort remaining tasks
-        #
-        # Currently running tasks will complete, but pending tasks will be skipped.
-        #
-        # @return [void]
-        def abort!
-          @mutex.synchronize do
-            @aborted = true
-          end
-        end
-
-        # Returns whether the pool has been aborted
-        #
-        # @return [Boolean] true if abort! was called
-        def aborted?
-          @mutex.synchronize { @aborted }
-        end
-
-        # Waits for all submitted tasks to complete
-        #
-        # @param timeout [Integer, nil] Maximum seconds to wait (nil = indefinite)
-        # @return [Boolean] true if all tasks completed, false if timeout
-        def wait_for_completion(timeout: nil)
-          deadline = timeout ? Time.current + timeout : nil
-
-          @mutex.synchronize do
-            loop do
-              return true if @pending_count == @completed_count
-
-              if deadline
-                remaining = deadline - Time.current
-                return false if remaining <= 0
-
-                @completion_condition.wait(@mutex, remaining)
-              else
-                @completion_condition.wait(@mutex)
-              end
-            end
-          end
-        end
-
-        # Shuts down the pool and waits for workers to terminate
-        #
-        # @param timeout [Integer] Maximum seconds to wait for termination
-        # @return [void]
-        def shutdown(timeout: 5)
-          @shutdown = true
-
-          # Send poison pills to stop workers
-          @size.times { @queue.push(nil) }
-
-          wait_for_termination(timeout: timeout)
-        end
-
-        # Waits for all worker threads to terminate
-        #
-        # @param timeout [Integer] Maximum seconds to wait
-        # @return [void]
-        def wait_for_termination(timeout: 5)
-          deadline = Time.current + timeout
-
-          @workers.each do |worker|
-            remaining = deadline - Time.current
-            break if remaining <= 0
-
-            worker.join(remaining)
-          end
-        end
-
-        private
-
-        # Spawns the worker threads
-        #
-        # @return [void]
-        def spawn_workers
-          @size.times do |i|
-            @workers << Thread.new do
-              Thread.current.name = "pool-worker-#{i}"
-              worker_loop
-            end
-          end
-        end
-
-        # Main worker loop - processes tasks from the queue
-        #
-        # @return [void]
-        def worker_loop
-          loop do
-            task = @queue.pop
-
-            # nil is the poison pill - time to exit
-            break if task.nil?
-
-            # Skip if aborted
-            if aborted?
-              mark_completed
-              next
-            end
-
-            begin
-              task.call
-            rescue StandardError
-              # Errors are handled by the task itself (via rescue in the block)
-              # We just need to ensure we mark completion
-            ensure
-              mark_completed
-            end
-          end
-        end
-
-        # Marks a task as completed and signals waiters
-        #
-        # @return [void]
-        def mark_completed
-          @mutex.synchronize do
-            @completed_count += 1
-            @completion_condition.broadcast
-          end
-        end
-      end
-    end
-  end
-end

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

@@ -1,206 +0,0 @@
-# frozen_string_literal: true
-
-module RubyLLM
-  module Agents
-    class Workflow
-      # Manages rate limiting and throttling for workflow steps
-      #
-      # Provides two modes of rate limiting:
-      # 1. Throttle: Ensures minimum time between executions of the same step
-      # 2. Rate limit: Limits the number of calls within a time window (token bucket)
-      #
-      # Thread-safe using a Mutex for concurrent access.
-      #
-      # @example Using throttle
-      #   manager = ThrottleManager.new
-      #   manager.throttle("step:fetch", 1.0) # Wait at least 1 second between calls
-      #
-      # @example Using rate limit
-      #   manager = ThrottleManager.new
-      #   manager.rate_limit("api:external", calls: 10, per: 60) # 10 calls per minute
-      #
-      # @api private
-      class ThrottleManager
-        def initialize
-          @last_execution = {}
-          @rate_limiters = {}
-          @mutex = Mutex.new
-        end
-
-        # Throttle execution to ensure minimum time between calls
-        #
-        # Blocks the current thread if necessary to maintain the minimum interval.
-        #
-        # @param key [String] Unique identifier for the throttle target
-        # @param duration [Float, Integer] Minimum seconds between executions
-        # @return [Float] Actual seconds waited (0 if no wait needed)
-        def throttle(key, duration)
-          duration_seconds = normalize_duration(duration)
-
-          @mutex.synchronize do
-            last = @last_execution[key]
-            waited = 0
-
-            if last
-              elapsed = Time.now - last
-              remaining = duration_seconds - elapsed
-
-              if remaining > 0
-                @mutex.sleep(remaining)
-                waited = remaining
-              end
-            end
-
-            @last_execution[key] = Time.now
-            waited
-          end
-        end
-
-        # Check if a call would be throttled without actually waiting
-        #
-        # @param key [String] Unique identifier for the throttle target
-        # @param duration [Float, Integer] Minimum seconds between executions
-        # @return [Float] Seconds until next allowed execution (0 if ready)
-        def throttle_remaining(key, duration)
-          duration_seconds = normalize_duration(duration)
-
-          @mutex.synchronize do
-            last = @last_execution[key]
-            return 0 unless last
-
-            elapsed = Time.now - last
-            remaining = duration_seconds - elapsed
-            [remaining, 0].max
-          end
-        end
-
-        # Apply rate limiting using a token bucket algorithm
-        #
-        # Blocks until a token is available if the rate limit is exceeded.
-        #
-        # @param key [String] Unique identifier for the rate limit target
-        # @param calls [Integer] Number of calls allowed per window
-        # @param per [Float, Integer] Time window in seconds
-        # @return [Float] Seconds waited (0 if no wait needed)
-        def rate_limit(key, calls:, per:)
-          per_seconds = normalize_duration(per)
-          bucket = get_or_create_bucket(key, calls, per_seconds)
-
-          @mutex.synchronize do
-            waited = bucket.acquire
-            waited
-          end
-        end
-
-        # Check if a call would be rate limited without consuming a token
-        #
-        # @param key [String] Unique identifier for the rate limit target
-        # @param calls [Integer] Number of calls allowed per window
-        # @param per [Float, Integer] Time window in seconds
-        # @return [Boolean] true if a call would be allowed immediately
-        def rate_limit_available?(key, calls:, per:)
-          per_seconds = normalize_duration(per)
-          bucket = get_or_create_bucket(key, calls, per_seconds)
-
-          @mutex.synchronize do
-            bucket.available?
-          end
-        end
-
-        # Reset throttle state for a specific key
-        #
-        # @param key [String] The throttle key to reset
-        # @return [void]
-        def reset_throttle(key)
-          @mutex.synchronize do
-            @last_execution.delete(key)
-          end
-        end
-
-        # Reset rate limiter state for a specific key
-        #
-        # @param key [String] The rate limiter key to reset
-        # @return [void]
-        def reset_rate_limit(key)
-          @mutex.synchronize do
-            @rate_limiters.delete(key)
-          end
-        end
-
-        # Reset all throttle and rate limit state
-        #
-        # @return [void]
-        def reset_all!
-          @mutex.synchronize do
-            @last_execution.clear
-            @rate_limiters.clear
-          end
-        end
-
-        private
-
-        def normalize_duration(duration)
-          if duration.respond_to?(:to_f)
-            duration.to_f
-          else
-            duration.to_i.to_f
-          end
-        end
-
-        def get_or_create_bucket(key, calls, per)
-          @rate_limiters[key] ||= TokenBucket.new(calls, per)
-        end
-
-        # Simple token bucket implementation for rate limiting
-        #
-        # @api private
-        class TokenBucket
-          def initialize(capacity, refill_time)
-            @capacity = capacity
-            @refill_time = refill_time
-            @tokens = capacity.to_f
-            @last_refill = Time.now
-          end
-
-          # Try to acquire a token, waiting if necessary
-          #
-          # @return [Float] Seconds waited
-          def acquire
-            refill
-            waited = 0
-
-            if @tokens < 1
-              # Calculate wait time for next token
-              tokens_needed = 1 - @tokens
-              wait_time = tokens_needed * @refill_time / @capacity
-              sleep(wait_time)
-              waited = wait_time
-              refill
-            end
-
-            @tokens -= 1
-            waited
-          end
-
-          # Check if a token is available without consuming it
-          #
-          # @return [Boolean]
-          def available?
-            refill
-            @tokens >= 1
-          end
-
-          private
-
-          def refill
-            now = Time.now
-            elapsed = now - @last_refill
-            refill_amount = elapsed * @capacity / @refill_time
-            @tokens = [@tokens + refill_amount, @capacity].min
-            @last_refill = now
-          end
-        end
-      end
-    end
-  end
-end

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

@@ -1,213 +0,0 @@
-# frozen_string_literal: true
-
-module RubyLLM
-  module Agents
-    class Workflow
-      # Result object for wait step execution
-      #
-      # Encapsulates the outcome of a wait operation including success/failure status,
-      # duration waited, and any metadata like approval details.
-      #
-      # @example Success result
-      #   WaitResult.success(:delay, 5.0)
-      #
-      # @example Timeout result
-      #   WaitResult.timeout(:until, 60.0, :fail)
-      #
-      # @example Approval result
-      #   WaitResult.approved("approval-123", "user@example.com", 3600.0)
-      #
-      # @api private
-      class WaitResult
-        STATUSES = %i[success timeout approved rejected skipped].freeze
-
-        attr_reader :type, :status, :waited_duration, :metadata
-
-        # @param type [Symbol] Wait type (:delay, :until, :schedule, :approval)
-        # @param status [Symbol] Result status (:success, :timeout, :approved, :rejected, :skipped)
-        # @param waited_duration [Float, nil] Duration waited in seconds
-        # @param metadata [Hash] Additional result metadata
-        def initialize(type:, status:, waited_duration: nil, metadata: {})
-          @type = type
-          @status = status
-          @waited_duration = waited_duration
-          @metadata = metadata
-        end
-
-        # Creates a success result
-        #
-        # @param type [Symbol] Wait type
-        # @param waited_duration [Float] Duration waited
-        # @param metadata [Hash] Additional metadata
-        # @return [WaitResult]
-        def self.success(type, waited_duration, **metadata)
-          new(
-            type: type,
-            status: :success,
-            waited_duration: waited_duration,
-            metadata: metadata
-          )
-        end
-
-        # Creates a timeout result
-        #
-        # @param type [Symbol] Wait type
-        # @param waited_duration [Float] Duration waited before timeout
-        # @param action_taken [Symbol] Action taken on timeout (:fail, :continue, :skip_next)
-        # @param metadata [Hash] Additional metadata
-        # @return [WaitResult]
-        def self.timeout(type, waited_duration, action_taken, **metadata)
-          new(
-            type: type,
-            status: :timeout,
-            waited_duration: waited_duration,
-            metadata: metadata.merge(action_taken: action_taken)
-          )
-        end
-
-        # Creates a skipped result (when condition not met)
-        #
-        # @param type [Symbol] Wait type
-        # @param reason [String, nil] Reason for skipping
-        # @return [WaitResult]
-        def self.skipped(type, reason: nil)
-          new(
-            type: type,
-            status: :skipped,
-            waited_duration: 0,
-            metadata: { reason: reason }.compact
-          )
-        end
-
-        # Creates an approved result for approval waits
-        #
-        # @param approval_id [String] Approval identifier
-        # @param approved_by [String] User who approved
-        # @param waited_duration [Float] Duration waited for approval
-        # @param metadata [Hash] Additional metadata
-        # @return [WaitResult]
-        def self.approved(approval_id, approved_by, waited_duration, **metadata)
-          new(
-            type: :approval,
-            status: :approved,
-            waited_duration: waited_duration,
-            metadata: metadata.merge(
-              approval_id: approval_id,
-              approved_by: approved_by
-            )
-          )
-        end
-
-        # Creates a rejected result for approval waits
-        #
-        # @param approval_id [String] Approval identifier
-        # @param rejected_by [String] User who rejected
-        # @param waited_duration [Float] Duration waited before rejection
-        # @param reason [String, nil] Rejection reason
-        # @param metadata [Hash] Additional metadata
-        # @return [WaitResult]
-        def self.rejected(approval_id, rejected_by, waited_duration, reason: nil, **metadata)
-          new(
-            type: :approval,
-            status: :rejected,
-            waited_duration: waited_duration,
-            metadata: metadata.merge(
-              approval_id: approval_id,
-              rejected_by: rejected_by,
-              reason: reason
-            ).compact
-          )
-        end
-
-        # Returns whether the wait completed successfully
-        #
-        # @return [Boolean]
-        def success?
-          status == :success || status == :approved
-        end
-
-        # Returns whether the wait timed out
-        #
-        # @return [Boolean]
-        def timeout?
-          status == :timeout
-        end
-
-        # Returns whether the wait was skipped
-        #
-        # @return [Boolean]
-        def skipped?
-          status == :skipped
-        end
-
-        # Returns whether an approval was granted
-        #
-        # @return [Boolean]
-        def approved?
-          status == :approved
-        end
-
-        # Returns whether an approval was rejected
-        #
-        # @return [Boolean]
-        def rejected?
-          status == :rejected
-        end
-
-        # Returns whether the workflow should continue after this wait
-        #
-        # @return [Boolean]
-        def should_continue?
-          success? || skipped? || (timeout? && metadata[:action_taken] == :continue)
-        end
-
-        # Returns whether the next step should be skipped
-        #
-        # @return [Boolean]
-        def should_skip_next?
-          timeout? && metadata[:action_taken] == :skip_next
-        end
-
-        # Returns the action taken on timeout
-        #
-        # @return [Symbol, nil]
-        def timeout_action
-          metadata[:action_taken]
-        end
-
-        # Returns the approval ID for approval waits
-        #
-        # @return [String, nil]
-        def approval_id
-          metadata[:approval_id]
-        end
-
-        # Returns who approved/rejected for approval waits
-        #
-        # @return [String, nil]
-        def actor
-          metadata[:approved_by] || metadata[:rejected_by]
-        end
-
-        # Returns the rejection reason
-        #
-        # @return [String, nil]
-        def rejection_reason
-          metadata[:reason]
-        end
-
-        # Converts to hash for serialization
-        #
-        # @return [Hash]
-        def to_h
-          {
-            type: type,
-            status: status,
-            waited_duration: waited_duration,
-            metadata: metadata
-          }
-        end
-      end
-    end
-  end
-end