ruby_llm-agents 0.3.6 → 0.5.0

data/lib/ruby_llm/agents/reliability/breaker_manager.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    module Reliability
+      # Manages circuit breakers for multiple models
+      #
+      # Provides centralized access to circuit breakers with
+      # multi-tenant support and caching.
+      #
+      # @example
+      #   manager = BreakerManager.new("MyAgent", config: { errors: 5, within: 60 })
+      #   manager.open?("gpt-4o")        # => false
+      #   manager.record_failure!("gpt-4o")
+      #   manager.record_success!("gpt-4o")
+      #
+      # @api private
+      class BreakerManager
+        # @param agent_type [String] The agent class name
+        # @param config [Hash, nil] Circuit breaker configuration
+        # @param tenant_id [String, nil] Optional tenant identifier
+        def initialize(agent_type, config:, tenant_id: nil)
+          @agent_type = agent_type
+          @config = config
+          @tenant_id = tenant_id
+          @breakers = {}
+        end
+
+        # Gets or creates a circuit breaker for a model
+        #
+        # @param model_id [String] Model identifier
+        # @return [CircuitBreaker, nil] The circuit breaker or nil if not configured
+        def for_model(model_id)
+          return nil unless @config
+
+          @breakers[model_id] ||= CircuitBreaker.from_config(
+            @agent_type,
+            model_id,
+            @config,
+            tenant_id: @tenant_id
+          )
+        end
+
+        # Checks if a model's circuit breaker is open
+        #
+        # @param model_id [String] Model identifier
+        # @return [Boolean] true if breaker is open
+        def open?(model_id)
+          breaker = for_model(model_id)
+          breaker&.open? || false
+        end
+
+        # Records a success for a model
+        #
+        # @param model_id [String] Model identifier
+        # @return [void]
+        def record_success!(model_id)
+          for_model(model_id)&.record_success!
+        end
+
+        # Records a failure for a model
+        #
+        # @param model_id [String] Model identifier
+        # @return [Boolean] true if breaker is now open
+        def record_failure!(model_id)
+          breaker = for_model(model_id)
+          breaker&.record_failure!
+          breaker&.open? || false
+        end
+
+        # Checks if circuit breaker is configured
+        #
+        # @return [Boolean] true if config present
+        def enabled?
+          @config.present?
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/agents/reliability/execution_constraints.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    module Reliability
+      # Manages execution constraints like total timeout and budget
+      #
+      # Tracks elapsed time and enforces timeout limits across
+      # all retry and fallback attempts.
+      #
+      # @example
+      #   constraints = ExecutionConstraints.new(total_timeout: 30)
+      #   constraints.timeout_exceeded?  # => false
+      #   constraints.enforce_timeout!   # raises if exceeded
+      #   constraints.elapsed            # => 5.2
+      #
+      # @api private
+      class ExecutionConstraints
+        attr_reader :total_timeout, :started_at, :deadline
+
+        # @param total_timeout [Integer, nil] Total timeout in seconds
+        def initialize(total_timeout: nil)
+          @total_timeout = total_timeout
+          @started_at = Time.current
+          @deadline = total_timeout ? @started_at + total_timeout : nil
+        end
+
+        # Checks if total timeout has been exceeded
+        #
+        # @return [Boolean] true if past deadline
+        def timeout_exceeded?
+          deadline && Time.current > deadline
+        end
+
+        # Returns elapsed time since start
+        #
+        # @return [Float] Elapsed seconds
+        def elapsed
+          Time.current - started_at
+        end
+
+        # Raises TotalTimeoutError if timeout exceeded
+        #
+        # @raise [TotalTimeoutError] If timeout exceeded
+        # @return [void]
+        def enforce_timeout!
+          if timeout_exceeded?
+            raise TotalTimeoutError.new(total_timeout, elapsed)
+          end
+        end
+
+        # Returns remaining time until deadline
+        #
+        # @return [Float, nil] Remaining seconds or nil if no timeout
+        def remaining
+          return nil unless deadline
+          [deadline - Time.current, 0].max
+        end
+
+        # Checks if there's a timeout configured
+        #
+        # @return [Boolean] true if timeout is set
+        def has_timeout?
+          total_timeout.present?
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/agents/reliability/executor.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    module Reliability
+      # Coordinates reliability features during agent execution
+      #
+      # Orchestrates retry strategy, fallback routing, circuit breakers,
+      # and execution constraints into a cohesive execution flow.
+      #
+      # @example
+      #   executor = Executor.new(
+      #     config: { retries: { max: 3 }, fallback_models: ["gpt-4o-mini"] },
+      #     primary_model: "gpt-4o",
+      #     agent_type: "MyAgent"
+      #   )
+      #   executor.execute { |model| call_llm(model) }
+      #
+      # @api private
+      class Executor
+        attr_reader :retry_strategy, :fallback_routing, :breaker_manager, :constraints
+
+        # @param config [Hash] Reliability configuration
+        # @param primary_model [String] Primary model identifier
+        # @param agent_type [String] Agent class name
+        # @param tenant_id [String, nil] Optional tenant identifier
+        def initialize(config:, primary_model:, agent_type:, tenant_id: nil)
+          retries_config = config[:retries] || {}
+
+          @retry_strategy = RetryStrategy.new(
+            max: retries_config[:max] || 0,
+            backoff: retries_config[:backoff] || :exponential,
+            base: retries_config[:base] || 0.4,
+            max_delay: retries_config[:max_delay] || 3.0,
+            on: retries_config[:on] || []
+          )
+
+          @fallback_routing = FallbackRouting.new(
+            primary_model,
+            fallback_models: config[:fallback_models] || []
+          )
+
+          @breaker_manager = BreakerManager.new(
+            agent_type,
+            config: config[:circuit_breaker],
+            tenant_id: tenant_id
+          )
+
+          @constraints = ExecutionConstraints.new(
+            total_timeout: config[:total_timeout]
+          )
+
+          @last_error = nil
+        end
+
+        # Returns all models that will be tried
+        #
+        # @return [Array<String>] Model identifiers
+        def models_to_try
+          fallback_routing.models
+        end
+
+        # Executes with full reliability support
+        #
+        # Iterates through models with retries, respecting circuit breakers
+        # and timeout constraints.
+        #
+        # @yield [model] Block to execute with the current model
+        # @yieldparam model [String] The model to use for this attempt
+        # @return [Object] Result of successful execution
+        # @raise [AllModelsExhaustedError] If all models fail
+        # @raise [TotalTimeoutError] If total timeout exceeded
+        def execute
+          until fallback_routing.exhausted?
+            model = fallback_routing.current_model
+
+            # Check circuit breaker
+            if breaker_manager.open?(model)
+              fallback_routing.advance!
+              next
+            end
+
+            # Try with retries
+            result = execute_with_retries(model) { |m| yield(m) }
+            return result if result
+
+            fallback_routing.advance!
+          end
+
+          raise AllModelsExhaustedError.new(
+            fallback_routing.models,
+            @last_error || StandardError.new("All models failed")
+          )
+        end
+
+        private
+
+        def execute_with_retries(model)
+          attempt_index = 0
+
+          loop do
+            constraints.enforce_timeout!
+
+            begin
+              result = yield(model)
+              breaker_manager.record_success!(model)
+              return result
+            rescue => e
+              @last_error = e
+              breaker_manager.record_failure!(model)
+
+              if retry_strategy.retryable?(e) && retry_strategy.should_retry?(attempt_index)
+                attempt_index += 1
+                sleep(retry_strategy.delay_for(attempt_index))
+              else
+                return nil # Move to next model
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/agents/reliability/fallback_routing.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    module Reliability
+      # Routes execution through fallback models when primary fails
+      #
+      # Manages the model fallback chain and tracks which models have been tried.
+      #
+      # @example
+      #   routing = FallbackRouting.new("gpt-4o", fallback_models: ["gpt-4o-mini"])
+      #   routing.current_model  # => "gpt-4o"
+      #   routing.advance!       # => "gpt-4o-mini"
+      #   routing.exhausted?     # => false
+      #
+      # @api private
+      class FallbackRouting
+        attr_reader :models
+
+        # @param primary_model [String] The primary model identifier
+        # @param fallback_models [Array<String>] Fallback model identifiers
+        def initialize(primary_model, fallback_models: [])
+          @models = [primary_model, *fallback_models].uniq
+          @current_index = 0
+        end
+
+        # Returns the current model to try
+        #
+        # @return [String, nil] Model identifier or nil if exhausted
+        def current_model
+          models[@current_index]
+        end
+
+        # Advances to the next fallback model
+        #
+        # @return [String, nil] Next model or nil if exhausted
+        def advance!
+          @current_index += 1
+          current_model
+        end
+
+        # Checks if more models are available after current
+        #
+        # @return [Boolean] true if more models to try
+        def has_more?
+          @current_index < models.length - 1
+        end
+
+        # Checks if all models have been exhausted
+        #
+        # @return [Boolean] true if no more models
+        def exhausted?
+          @current_index >= models.length
+        end
+
+        # Resets to the first model
+        #
+        # @return [void]
+        def reset!
+          @current_index = 0
+        end
+
+        # Returns models that have been tried so far
+        #
+        # @return [Array<String>] Models already attempted
+        def tried_models
+          models[0..@current_index]
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/agents/reliability/retry_strategy.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    module Reliability
+      # Handles retry logic with configurable backoff strategies
+      #
+      # Provides exponential and constant backoff with jitter,
+      # retry counting, and delay calculation.
+      #
+      # @example
+      #   strategy = RetryStrategy.new(max: 3, backoff: :exponential, base: 0.4)
+      #   strategy.should_retry?(attempt_index) # => true/false
+      #   strategy.delay_for(attempt_index)     # => 0.6 (with jitter)
+      #
+      # @api private
+      class RetryStrategy
+        attr_reader :max, :backoff, :base, :max_delay, :custom_errors
+
+        # @param max [Integer] Maximum retry attempts
+        # @param backoff [Symbol] :constant or :exponential
+        # @param base [Float] Base delay in seconds
+        # @param max_delay [Float] Maximum delay cap
+        # @param on [Array<Class>] Additional error classes to retry on
+        def initialize(max: 0, backoff: :exponential, base: 0.4, max_delay: 3.0, on: [])
+          @max = max
+          @backoff = backoff
+          @base = base
+          @max_delay = max_delay
+          @custom_errors = Array(on)
+        end
+
+        # Determines if retry should occur
+        #
+        # @param attempt_index [Integer] Current attempt number (0-indexed)
+        # @return [Boolean] true if should retry
+        def should_retry?(attempt_index)
+          attempt_index < max
+        end
+
+        # Calculates delay before next retry
+        #
+        # @param attempt_index [Integer] Current attempt number
+        # @return [Float] Delay in seconds (includes jitter)
+        def delay_for(attempt_index)
+          base_delay = case backoff
+          when :constant
+            base
+          when :exponential
+            [base * (2**attempt_index), max_delay].min
+          else
+            base
+          end
+
+          # Add jitter (0-50% of base delay)
+          base_delay + (rand * base_delay * 0.5)
+        end
+
+        # Checks if an error is retryable
+        #
+        # @param error [Exception] The error to check
+        # @return [Boolean] true if retryable
+        def retryable?(error)
+          RubyLLM::Agents::Reliability.retryable_error?(error, custom_errors: custom_errors)
+        end
+
+        # Returns all retryable error classes
+        #
+        # @return [Array<Class>] Error classes to retry on
+        def retryable_errors
+          RubyLLM::Agents::Reliability.default_retryable_errors + custom_errors
+        end
+      end
+    end
+  end
+end