ruby_llm-agents 1.3.1 → 1.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7e22cdb85d5ac5b3d3f0236e212233464883a3ec7d2831b6651436e0e026578c
-  data.tar.gz: e3a8fd1f55bf159ea69444f01c457cded6f2cb4f04a36796d6d6ee1fdbe078a6
+  metadata.gz: f5ca913fd17a05f6a541111f194a07259002280967bedb74d74173b53298eaed
+  data.tar.gz: 537f02ab5b3f40b4edcb225118ebd320f0a4a76976b9e077acfecd4bd47c5e5a
 SHA512:
-  metadata.gz: 526caa1eef7d31953417c0b6eb956657c0c05d41c2720472311ddc66afc337ec1f903e0e0e9ed550b3fe71690be4e4b8da77c2c36c08586a8000e5f971930789
-  data.tar.gz: be0e49c7f4fb56f49b94e88c67ea6a8d8baf1cd4e3c4fadca999aa063728648a2c713fda4c202053167d4676ddb405b37d0b8afd51e83c29bdb4c93fa3f9cec0
+  metadata.gz: 6016113d5051912f51f1dc1d957c9a5eb45d62028d5920284aae300189ea0e6a5347f231a252e7f76d002156421ab442f2b55299f4e7b68a73e12ef14eacb64d
+  data.tar.gz: 063ce841e9405b5afd7b9468c1db4646a7621702e5a4121c29d775339cfab550f0e85783fbcc63d12b5553efac90e7a3a9aa93a8f704d17a8a023d2a13f35fe7

data/lib/ruby_llm/agents/core/configuration.rb

@@ -621,7 +621,7 @@ module RubyLLM
         @default_fallback_models = []
         @default_total_timeout = nil
         @default_retryable_patterns = {
-          rate_limiting: ["rate limit", "rate_limit", "too many requests", "429"],
+          rate_limiting: ["rate limit", "rate_limit", "too many requests", "429", "quota"],
           server_errors: ["500", "502", "503", "504", "service unavailable",
                          "internal server error", "bad gateway", "gateway timeout"],
           capacity: ["overloaded", "capacity"]

data/lib/ruby_llm/agents/core/version.rb

@@ -4,6 +4,6 @@ module RubyLLM
   module Agents
     # Current version of the RubyLLM::Agents gem
     # @return [String] Semantic version string
-    VERSION = "1.3.1"
+    VERSION = "1.3.2"
   end
 end

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

@@ -54,6 +54,7 @@ module RubyLLM
           @total_timeout = builder.total_timeout_value if builder.total_timeout_value
           @circuit_breaker_config = builder.circuit_breaker_config if builder.circuit_breaker_config
           @retryable_patterns = builder.retryable_patterns_list if builder.retryable_patterns_list
+          @non_fallback_errors = builder.non_fallback_errors_list if builder.non_fallback_errors_list
         end
 
         # Returns the complete reliability configuration hash
@@ -70,7 +71,8 @@ module RubyLLM
             fallback_providers: fallback_providers,
             total_timeout: total_timeout,
             circuit_breaker: circuit_breaker_config,
-            retryable_patterns: retryable_patterns
+            retryable_patterns: retryable_patterns,
+            non_fallback_errors: non_fallback_errors
           }.compact
         end
 
@@ -196,6 +198,17 @@ module RubyLLM
           @retryable_patterns || inherited_retryable_patterns
         end
 
+        # Sets or returns additional error classes that should never trigger fallback
+        #
+        # @param error_classes [Array<Class>] Error classes that should fail immediately
+        # @return [Array<Class>, nil] The current non-fallback error classes
+        # @example
+        #   non_fallback_errors MyValidationError, MySchemaError
+        def non_fallback_errors(*error_classes)
+          @non_fallback_errors = error_classes.flatten if error_classes.any?
+          @non_fallback_errors || inherited_non_fallback_errors
+        end
+
         # @!endgroup
 
         private
@@ -236,6 +249,12 @@ module RubyLLM
           superclass.retryable_patterns
         end
 
+        def inherited_non_fallback_errors
+          return nil unless superclass.respond_to?(:non_fallback_errors)
+
+          superclass.non_fallback_errors
+        end
+
         def default_retries_config
           {
             max: 0,
@@ -249,7 +268,8 @@ module RubyLLM
         # Inner builder class for block-style configuration
         class ReliabilityBuilder
           attr_reader :retries_config, :fallback_models_list, :total_timeout_value,
-                      :circuit_breaker_config, :retryable_patterns_list, :fallback_providers_list
+                      :circuit_breaker_config, :retryable_patterns_list, :fallback_providers_list,
+                      :non_fallback_errors_list
 
           def initialize
             @retries_config = nil
@@ -258,6 +278,7 @@ module RubyLLM
             @circuit_breaker_config = nil
             @retryable_patterns_list = nil
             @fallback_providers_list = []
+            @non_fallback_errors_list = nil
           end
 
           def retries(max: 0, backoff: :exponential, base: 0.4, max_delay: 3.0, on: [])
@@ -300,6 +321,10 @@ module RubyLLM
           def retryable_patterns(*patterns)
             @retryable_patterns_list = patterns.flatten
           end
+
+          def non_fallback_errors(*error_classes)
+            @non_fallback_errors_list = error_classes.flatten
+          end
         end
       end
     end

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

@@ -88,18 +88,46 @@ module RubyLLM
       #
       # @api public
       class AllModelsExhaustedError < Error
-        attr_reader :models_tried, :last_error
+        attr_reader :models_tried, :last_error, :attempts
 
         # @param models_tried [Array<String>] List of models that were attempted
         # @param last_error [Exception] The last error that occurred
-        def initialize(models_tried, last_error)
+        # @param attempts [Array<Hash>, nil] Per-model attempt data from AttemptTracker
+        def initialize(models_tried, last_error, attempts: nil)
           @models_tried = models_tried
           @last_error = last_error
+          @attempts = attempts
           super("All models exhausted: #{models_tried.join(', ')}. Last error: #{last_error.message}")
         end
       end
 
       class << self
+        # Default list of error classes that should never trigger fallback
+        #
+        # These errors indicate programming bugs that won't be fixed by trying
+        # a different model. They should fail immediately.
+        #
+        # @return [Array<Class>] Error classes that are non-fallback by default
+        def default_non_fallback_errors
+          @default_non_fallback_errors ||= [
+            ArgumentError,
+            TypeError,
+            NameError,
+            NoMethodError,
+            NotImplementedError
+          ]
+        end
+
+        # Determines if an error is a programming error that should not trigger fallback
+        #
+        # @param error [Exception] The error to check
+        # @param custom_errors [Array<Class>] Additional error classes to consider non-fallback
+        # @return [Boolean] true if the error should fail immediately
+        def non_fallback_error?(error, custom_errors: [])
+          all = default_non_fallback_errors + Array(custom_errors)
+          all.any? { |klass| error.is_a?(klass) }
+        end
+
         # Default list of error classes that are considered retryable
         #
         # These errors typically indicate transient issues that may resolve on retry.

data/lib/ruby_llm/agents/pipeline/middleware/instrumentation.rb

@@ -232,6 +232,17 @@ module RubyLLM
               data[:tool_calls_count] = context[:tool_calls].size
             end
 
+            # Add reliability attempts if present
+            if context[:reliability_attempts].present?
+              data[:attempts] = context[:reliability_attempts]
+              data[:attempts_count] = context[:reliability_attempts].size
+            end
+
+            # Add response if persist_responses is enabled
+            if global_config.persist_responses && context.output.respond_to?(:content)
+              data[:response] = serialize_response(context)
+            end
+
             data
           end
 
@@ -304,6 +315,17 @@ module RubyLLM
               data[:tool_calls_count] = context[:tool_calls].size
             end
 
+            # Add reliability attempts if present
+            if context[:reliability_attempts].present?
+              data[:attempts] = context[:reliability_attempts]
+              data[:attempts_count] = context[:reliability_attempts].size
+            end
+
+            # Add response if persist_responses is enabled
+            if global_config.persist_responses && context.output.respond_to?(:content)
+              data[:response] = serialize_response(context)
+            end
+
             data
           end
 
@@ -359,6 +381,33 @@ module RubyLLM
             message.to_s[0, 1000]
           end
 
+          # Serializes the response content for storage
+          #
+          # @param context [Context] The execution context
+          # @return [Hash, nil] Serialized response data
+          def serialize_response(context)
+            return nil unless context.output
+
+            content = context.output.content
+            return nil if content.nil?
+
+            # Build response hash similar to core instrumentation
+            response_data = { content: content }
+
+            # Add model_id if available
+            response_data[:model_id] = context.model_used if context.model_used
+
+            # Add token info if available
+            response_data[:input_tokens] = context.input_tokens if context.input_tokens
+            response_data[:output_tokens] = context.output_tokens if context.output_tokens
+
+            # Apply redaction for sensitive data
+            Redactor.redact(response_data)
+          rescue StandardError => e
+            error("Failed to serialize response: #{e.message}")
+            nil
+          end
+
           # Queues async logging via background job
           #
           # @param data [Hash] Execution data

data/lib/ruby_llm/agents/pipeline/middleware/reliability.rb

@@ -97,12 +97,14 @@ module RubyLLM
             started_at = Time.current
             last_error = nil
             context.attempts_made = 0
+            tracker = Agents::AttemptTracker.new
 
             models_to_try.each do |current_model|
               # Check circuit breaker for this model
               breaker = get_circuit_breaker(current_model, context)
               if breaker&.open?
                 debug("Circuit breaker open for #{current_model}, skipping")
+                tracker.record_short_circuit(current_model)
                 next
               end
 
@@ -112,17 +114,27 @@ module RubyLLM
                 config: config,
                 total_deadline: total_deadline,
                 started_at: started_at,
-                breaker: breaker
+                breaker: breaker,
+                tracker: tracker
               )
 
-              return result if result
+              if result
+                context[:reliability_attempts] = tracker.to_json_array
+                return result
+              end
 
               # Capture the last error from context for the final error
               last_error = context.error
             end
 
+            # Store attempts even on total failure
+            context[:reliability_attempts] = tracker.to_json_array
+
             # All models exhausted
-            raise Agents::Reliability::AllModelsExhaustedError.new(models_to_try, last_error)
+            raise Agents::Reliability::AllModelsExhaustedError.new(
+              models_to_try, last_error,
+              attempts: tracker.to_json_array
+            )
           end
 
           # Tries a model with retry logic
@@ -134,7 +146,7 @@ module RubyLLM
           # @param started_at [Time] When execution started
           # @param breaker [CircuitBreaker, nil] The circuit breaker for this model
           # @return [Context, nil] The context if successful, nil to try next model
-          def try_model_with_retries(context:, model:, config:, total_deadline:, started_at:, breaker:)
+          def try_model_with_retries(context:, model:, config:, total_deadline:, started_at:, breaker:, tracker:)
             retries_config = config[:retries] || {}
             max_retries = retries_config[:max] || 0
             attempt_index = 0
@@ -146,6 +158,8 @@ module RubyLLM
               context.attempt = attempt_index + 1
               context.attempts_made += 1
 
+              attempt = tracker.start_attempt(model)
+
               begin
                 # Override the model for this attempt
                 original_model = context.model
@@ -153,14 +167,19 @@ module RubyLLM
 
                 @app.call(context)
 
-                # Success - record in circuit breaker
+                # Success - record in circuit breaker and tracker
                 breaker&.record_success!
+                tracker.complete_attempt(attempt, success: true, response: context.output)
 
                 return context
 
               rescue StandardError => e
                 context.error = e
                 breaker&.record_failure!
+                tracker.complete_attempt(attempt, success: false, error: e)
+
+                # Programming errors fail immediately — no retry, no fallback
+                raise if non_fallback_error?(e, config)
 
                 # Check if we should retry
                 if should_retry?(e, config, attempt_index, max_retries, total_deadline)
@@ -202,10 +221,31 @@ module RubyLLM
           def should_retry?(error, config, attempt_index, max_retries, total_deadline)
             return false if attempt_index >= max_retries
             return false if total_deadline && Time.current > total_deadline
+            # Don't retry if fallback models are available — move to next model instead
+            return false if has_fallback_models?(config)
 
             retryable_error?(error, config)
           end
 
+          # Checks if an error is a programming error that should not trigger fallback
+          #
+          # @param error [Exception] The error to check
+          # @param config [Hash] The reliability configuration
+          # @return [Boolean] Whether the error should fail immediately
+          def non_fallback_error?(error, config)
+            custom_errors = config[:non_fallback_errors] || []
+            Agents::Reliability.non_fallback_error?(error, custom_errors: custom_errors)
+          end
+
+          # Returns whether fallback models are configured
+          #
+          # @param config [Hash] The reliability configuration
+          # @return [Boolean]
+          def has_fallback_models?(config)
+            fallbacks = config[:fallback_models]
+            fallbacks.is_a?(Array) && fallbacks.any?
+          end
+
           # Checks if an error is retryable
           #
           # @param error [Exception] The error to check

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_llm-agents
 version: !ruby/object:Gem::Version
-  version: 1.3.1
+  version: 1.3.2
 platform: ruby
 authors:
 - adham90