ruby_llm-agents 0.2.4 → 0.3.1

data/lib/ruby_llm/agents/redactor.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    # Unified redaction utility for PII and sensitive data
+    #
+    # Provides methods to redact sensitive information from hashes, arrays, and strings
+    # based on configurable field names and regex patterns.
+    #
+    # @example Redacting a hash
+    #   Redactor.redact({ password: "secret", name: "John" })
+    #   # => { password: "[REDACTED]", name: "John" }
+    #
+    # @example Redacting a string with patterns
+    #   Redactor.redact_string("SSN: 123-45-6789")
+    #   # => "SSN: [REDACTED]"
+    #
+    # @see RubyLLM::Agents::Configuration
+    # @api public
+    module Redactor
+      class << self
+        # Redacts sensitive data from an object (hash, array, or primitive)
+        #
+        # @param obj [Object] The object to redact
+        # @param config [Configuration, nil] Optional configuration override
+        # @return [Object] The redacted object (new object, original not modified)
+        def redact(obj, config = nil)
+          config ||= RubyLLM::Agents.configuration
+
+          case obj
+          when Hash
+            redact_hash(obj, config)
+          when Array
+            redact_array(obj, config)
+          when String
+            redact_string(obj, config)
+          else
+            obj
+          end
+        end
+
+        # Redacts sensitive data from a string using configured patterns
+        #
+        # @param str [String, nil] The string to redact
+        # @param config [Configuration, nil] Optional configuration override
+        # @return [String, nil] The redacted string
+        def redact_string(str, config = nil)
+          return nil if str.nil?
+          return str unless str.is_a?(String)
+
+          config ||= RubyLLM::Agents.configuration
+          result = str.dup
+
+          # Apply pattern-based redaction
+          config.redaction_patterns.each do |pattern|
+            result = result.gsub(pattern, config.redaction_placeholder)
+          end
+
+          # Truncate if max length is configured
+          max_length = config.redaction_max_value_length
+          if max_length && result.length > max_length
+            result = result[0, max_length] + "..."
+          end
+
+          result
+        end
+
+        private
+
+        # Redacts sensitive fields from a hash
+        #
+        # @param hash [Hash] The hash to redact
+        # @param config [Configuration] The configuration
+        # @return [Hash] The redacted hash
+        def redact_hash(hash, config)
+          hash.each_with_object({}) do |(key, value), result|
+            key_str = key.to_s.downcase
+
+            if sensitive_field?(key_str, config)
+              result[key] = config.redaction_placeholder
+            else
+              result[key] = redact_value(value, config)
+            end
+          end
+        end
+
+        # Redacts sensitive values from an array
+        #
+        # @param array [Array] The array to redact
+        # @param config [Configuration] The configuration
+        # @return [Array] The redacted array
+        def redact_array(array, config)
+          array.map { |item| redact(item, config) }
+        end
+
+        # Redacts a single value based on its type
+        #
+        # @param value [Object] The value to redact
+        # @param config [Configuration] The configuration
+        # @return [Object] The redacted value
+        def redact_value(value, config)
+          case value
+          when Hash
+            redact_hash(value, config)
+          when Array
+            redact_array(value, config)
+          when String
+            redact_string(value, config)
+          when defined?(ActiveRecord::Base) && ActiveRecord::Base
+            # Convert ActiveRecord objects to safe references
+            { id: value&.id, type: value&.class&.name }
+          else
+            value
+          end
+        end
+
+        # Checks if a field name is sensitive
+        #
+        # @param field_name [String] The field name to check (lowercase)
+        # @param config [Configuration] The configuration
+        # @return [Boolean] true if the field should be redacted
+        def sensitive_field?(field_name, config)
+          config.redaction_fields.any? do |sensitive|
+            field_name.include?(sensitive.downcase)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/agents/reliability.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    # Reliability module providing error classes and utilities for retry/fallback logic
+    #
+    # This module defines custom error types for reliability features and provides
+    # utilities for determining which errors are retryable.
+    #
+    # @example Checking if an error is retryable
+    #   Reliability.retryable_error?(Timeout::Error.new)  # => true
+    #   Reliability.retryable_error?(ArgumentError.new)   # => false
+    #
+    # @see RubyLLM::Agents::Base
+    # @api public
+    module Reliability
+      # Base error class for all reliability-related errors
+      #
+      # @api public
+      class Error < StandardError; end
+
+      # Raised when the circuit breaker is open and requests are being blocked
+      #
+      # @example
+      #   raise CircuitBreakerOpenError.new("MyAgent", "gpt-4o")
+      #
+      # @api public
+      class CircuitBreakerOpenError < Error
+        attr_reader :agent_type, :model_id
+
+        # @param agent_type [String] The agent class name
+        # @param model_id [String] The model identifier
+        def initialize(agent_type, model_id)
+          @agent_type = agent_type
+          @model_id = model_id
+          super("Circuit breaker is open for #{agent_type} with model #{model_id}")
+        end
+      end
+
+      # Raised when budget limits have been exceeded
+      #
+      # @example
+      #   raise BudgetExceededError.new(:global_daily, 25.0, 27.5)
+      #
+      # @api public
+      class BudgetExceededError < Error
+        attr_reader :scope, :limit, :current
+
+        # @param scope [Symbol] The budget scope (:global_daily, :global_monthly, :per_agent_daily, etc.)
+        # @param limit [Float] The budget limit in USD
+        # @param current [Float] The current spend in USD
+        # @param agent_type [String, nil] The agent type for per-agent budgets
+        def initialize(scope, limit, current, agent_type: nil)
+          @scope = scope
+          @limit = limit
+          @current = current
+          @agent_type = agent_type
+
+          message = "Budget exceeded for #{scope}"
+          message += " (#{agent_type})" if agent_type
+          message += ": limit $#{limit}, current $#{current}"
+          super(message)
+        end
+      end
+
+      # Raised when the total timeout for all retry/fallback attempts is exceeded
+      #
+      # @api public
+      class TotalTimeoutError < Error
+        attr_reader :timeout_seconds, :elapsed_seconds
+
+        # @param timeout_seconds [Integer] The configured total timeout
+        # @param elapsed_seconds [Float] The elapsed time when timeout occurred
+        def initialize(timeout_seconds, elapsed_seconds)
+          @timeout_seconds = timeout_seconds
+          @elapsed_seconds = elapsed_seconds
+          super("Total timeout of #{timeout_seconds}s exceeded (elapsed: #{elapsed_seconds.round(2)}s)")
+        end
+      end
+
+      # Raised when all models in the fallback chain have been exhausted
+      #
+      # @api public
+      class AllModelsExhaustedError < Error
+        attr_reader :models_tried, :last_error
+
+        # @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)
+          @models_tried = models_tried
+          @last_error = last_error
+          super("All models exhausted: #{models_tried.join(', ')}. Last error: #{last_error.message}")
+        end
+      end
+
+      class << self
+        # Default list of error classes that are considered retryable
+        #
+        # These errors typically indicate transient issues that may resolve on retry.
+        #
+        # @return [Array<Class>] Error classes that are retryable by default
+        def default_retryable_errors
+          @default_retryable_errors ||= [
+            Timeout::Error,
+            defined?(Net::OpenTimeout) ? Net::OpenTimeout : nil,
+            defined?(Net::ReadTimeout) ? Net::ReadTimeout : nil,
+            defined?(Faraday::TimeoutError) ? Faraday::TimeoutError : nil,
+            defined?(Faraday::ConnectionFailed) ? Faraday::ConnectionFailed : nil,
+            defined?(Errno::ECONNREFUSED) ? Errno::ECONNREFUSED : nil,
+            defined?(Errno::ECONNRESET) ? Errno::ECONNRESET : nil,
+            defined?(Errno::ETIMEDOUT) ? Errno::ETIMEDOUT : nil,
+            defined?(SocketError) ? SocketError : nil,
+            defined?(OpenSSL::SSL::SSLError) ? OpenSSL::SSL::SSLError : nil
+          ].compact
+        end
+
+        # Determines if an error is retryable based on default and custom error classes
+        #
+        # @param error [Exception] The error to check
+        # @param custom_errors [Array<Class>] Additional error classes to consider retryable
+        # @return [Boolean] true if the error is retryable
+        def retryable_error?(error, custom_errors: [])
+          all_retryable = default_retryable_errors + Array(custom_errors)
+          all_retryable.any? { |klass| error.is_a?(klass) } || retryable_by_message?(error)
+        end
+
+        # Determines if an error is retryable based on its message content
+        #
+        # Some errors (like HTTP 5xx responses) may not have specific error classes
+        # but can be identified by their message.
+        #
+        # @param error [Exception] The error to check
+        # @return [Boolean] true if the error message indicates a retryable condition
+        def retryable_by_message?(error)
+          message = error.message.to_s.downcase
+          retryable_patterns.any? { |pattern| message.include?(pattern) }
+        end
+
+        # Patterns in error messages that indicate retryable errors
+        #
+        # @return [Array<String>] Patterns to match against error messages
+        def retryable_patterns
+          @retryable_patterns ||= [
+            "rate limit",
+            "rate_limit",
+            "too many requests",
+            "429",
+            "500",
+            "502",
+            "503",
+            "504",
+            "service unavailable",
+            "internal server error",
+            "bad gateway",
+            "gateway timeout",
+            "overloaded",
+            "capacity"
+          ].freeze
+        end
+
+        # Calculates the backoff delay for a retry attempt
+        #
+        # @param strategy [Symbol] The backoff strategy (:constant or :exponential)
+        # @param base [Float] The base delay in seconds
+        # @param max_delay [Float] The maximum delay in seconds
+        # @param attempt [Integer] The current attempt number (0-indexed)
+        # @return [Float] The delay in seconds (including jitter)
+        def calculate_backoff(strategy:, base:, max_delay:, attempt:)
+          delay = case strategy
+          when :constant
+            base
+          when :exponential
+            [base * (2**attempt), max_delay].min
+          else
+            base
+          end
+
+          # Add jitter (0 to 50% of delay)
+          jitter = rand * delay * 0.5
+          delay + jitter
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/agents/version.rb

@@ -2,6 +2,8 @@
 
 module RubyLLM
   module Agents
-    VERSION = "0.2.4"
+    # Current version of the RubyLLM::Agents gem
+    # @return [String] Semantic version string
+    VERSION = "0.3.1"
   end
 end

data/lib/ruby_llm/agents.rb

@@ -1,23 +1,75 @@
 # frozen_string_literal: true
 
+require "csv"
+
 require_relative "agents/version"
 require_relative "agents/configuration"
+require_relative "agents/reliability"
+require_relative "agents/redactor"
+require_relative "agents/circuit_breaker"
+require_relative "agents/budget_tracker"
+require_relative "agents/alert_manager"
+require_relative "agents/attempt_tracker"
 require_relative "agents/inflections" if defined?(Rails)
 require_relative "agents/engine" if defined?(Rails::Engine)
 
 module RubyLLM
+  # Agent framework for building LLM-powered agents with observability
+  #
+  # RubyLLM::Agents provides a DSL for creating agents that interact with
+  # large language models, with built-in execution tracking, cost monitoring,
+  # and a dashboard for observability.
+  #
+  # @example Basic configuration
+  #   RubyLLM::Agents.configure do |config|
+  #     config.default_model = "gpt-4o"
+  #     config.async_logging = true
+  #   end
+  #
+  # @example Creating an agent
+  #   class SearchAgent < ApplicationAgent
+  #     model "gpt-4o"
+  #     param :query, required: true
+  #
+  #     def user_prompt
+  #       "Search for: #{query}"
+  #     end
+  #   end
+  #
+  #   SearchAgent.call(query: "ruby gems")
+  #
+  # @see RubyLLM::Agents::Base
+  # @see RubyLLM::Agents::Configuration
   module Agents
+    # Base error class for agent-related exceptions
     class Error < StandardError; end
 
     class << self
+      # Returns the global configuration instance
+      #
+      # @return [Configuration] The configuration object
       def configuration
         @configuration ||= Configuration.new
       end
 
+      # Yields the configuration for modification
+      #
+      # @yield [Configuration] The configuration object
+      # @return [void]
+      # @example
+      #   RubyLLM::Agents.configure do |config|
+      #     config.default_model = "claude-3-sonnet"
+      #   end
       def configure
         yield(configuration)
       end
 
+      # Resets configuration to defaults
+      #
+      # Primarily used for testing to ensure clean state.
+      #
+      # @return [Configuration] A new configuration instance
+      # @api private
       def reset_configuration!
         @configuration = Configuration.new
       end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_llm-agents
 version: !ruby/object:Gem::Version
-  version: 0.2.4
+  version: 0.3.1
 platform: ruby
 authors:
 - adham90
@@ -79,6 +79,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: csv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: A Rails engine for creating, managing, and monitoring LLM-powered agents.
   Includes a DSL for agent configuration, execution tracking, cost analytics, and
   a mountable dashboard UI.
@@ -91,10 +105,12 @@ files:
 - LICENSE.txt
 - README.md
 - app/channels/ruby_llm/agents/executions_channel.rb
+- app/controllers/concerns/ruby_llm/agents/filterable.rb
+- app/controllers/concerns/ruby_llm/agents/paginatable.rb
 - app/controllers/ruby_llm/agents/agents_controller.rb
-- app/controllers/ruby_llm/agents/application_controller.rb
 - app/controllers/ruby_llm/agents/dashboard_controller.rb
 - app/controllers/ruby_llm/agents/executions_controller.rb
+- app/controllers/ruby_llm/agents/settings_controller.rb
 - app/helpers/ruby_llm/agents/application_helper.rb
 - app/javascript/ruby_llm/agents/controllers/filter_controller.js
 - app/javascript/ruby_llm/agents/controllers/index.js
@@ -105,24 +121,41 @@ files:
 - app/models/ruby_llm/agents/execution/scopes.rb
 - app/services/ruby_llm/agents/agent_registry.rb
 - app/views/layouts/rubyllm/agents/application.html.erb
+- app/views/rubyllm/agents/agents/_version_comparison.html.erb
 - app/views/rubyllm/agents/agents/index.html.erb
 - app/views/rubyllm/agents/agents/show.html.erb
+- app/views/rubyllm/agents/dashboard/_action_center.html.erb
+- app/views/rubyllm/agents/dashboard/_alerts_feed.html.erb
+- app/views/rubyllm/agents/dashboard/_breaker_strip.html.erb
+- app/views/rubyllm/agents/dashboard/_budgets_bar.html.erb
 - app/views/rubyllm/agents/dashboard/_execution_item.html.erb
+- app/views/rubyllm/agents/dashboard/_now_strip.html.erb
+- app/views/rubyllm/agents/dashboard/_now_strip_values.html.erb
 - app/views/rubyllm/agents/dashboard/index.html.erb
 - app/views/rubyllm/agents/executions/_execution.html.erb
 - app/views/rubyllm/agents/executions/_filters.html.erb
 - app/views/rubyllm/agents/executions/_list.html.erb
+- app/views/rubyllm/agents/executions/dry_run.html.erb
 - app/views/rubyllm/agents/executions/index.html.erb
 - app/views/rubyllm/agents/executions/index.turbo_stream.erb
 - app/views/rubyllm/agents/executions/show.html.erb
+- app/views/rubyllm/agents/settings/show.html.erb
 - app/views/rubyllm/agents/shared/_executions_table.html.erb
+- app/views/rubyllm/agents/shared/_filter_dropdown.html.erb
+- app/views/rubyllm/agents/shared/_select_dropdown.html.erb
 - app/views/rubyllm/agents/shared/_stat_card.html.erb
 - app/views/rubyllm/agents/shared/_status_badge.html.erb
 - app/views/rubyllm/agents/shared/_status_dot.html.erb
 - config/routes.rb
 - lib/generators/ruby_llm_agents/agent_generator.rb
 - lib/generators/ruby_llm_agents/install_generator.rb
+- lib/generators/ruby_llm_agents/templates/add_attempts_migration.rb.tt
+- lib/generators/ruby_llm_agents/templates/add_caching_migration.rb.tt
+- lib/generators/ruby_llm_agents/templates/add_finish_reason_migration.rb.tt
 - lib/generators/ruby_llm_agents/templates/add_prompts_migration.rb.tt
+- lib/generators/ruby_llm_agents/templates/add_routing_migration.rb.tt
+- lib/generators/ruby_llm_agents/templates/add_streaming_migration.rb.tt
+- lib/generators/ruby_llm_agents/templates/add_tracing_migration.rb.tt
 - lib/generators/ruby_llm_agents/templates/agent.rb.tt
 - lib/generators/ruby_llm_agents/templates/application_agent.rb.tt
 - lib/generators/ruby_llm_agents/templates/initializer.rb.tt
@@ -130,12 +163,18 @@ files:
 - lib/generators/ruby_llm_agents/upgrade_generator.rb
 - lib/ruby_llm-agents.rb
 - lib/ruby_llm/agents.rb
+- lib/ruby_llm/agents/alert_manager.rb
+- lib/ruby_llm/agents/attempt_tracker.rb
 - lib/ruby_llm/agents/base.rb
+- lib/ruby_llm/agents/budget_tracker.rb
+- lib/ruby_llm/agents/circuit_breaker.rb
 - lib/ruby_llm/agents/configuration.rb
 - lib/ruby_llm/agents/engine.rb
 - lib/ruby_llm/agents/execution_logger_job.rb
 - lib/ruby_llm/agents/inflections.rb
 - lib/ruby_llm/agents/instrumentation.rb
+- lib/ruby_llm/agents/redactor.rb
+- lib/ruby_llm/agents/reliability.rb
 - lib/ruby_llm/agents/version.rb
 homepage: https://github.com/adham90/ruby_llm-agents
 licenses:

data/app/controllers/ruby_llm/agents/application_controller.rb

@@ -1,37 +0,0 @@
-# frozen_string_literal: true
-
-module RubyLLM
-  module Agents
-    class ApplicationController < ActionController::Base
-      layout "rubyllm/agents/application"
-
-      before_action :authenticate_dashboard!
-
-      private
-
-      def authenticate_dashboard!
-        if basic_auth_configured?
-          authenticate_with_http_basic_auth
-        else
-          auth_proc = RubyLLM::Agents.configuration.dashboard_auth
-          return if auth_proc.call(self)
-
-          render plain: "Unauthorized", status: :unauthorized
-        end
-      end
-
-      def basic_auth_configured?
-        config = RubyLLM::Agents.configuration
-        config.basic_auth_username.present? && config.basic_auth_password.present?
-      end
-
-      def authenticate_with_http_basic_auth
-        config = RubyLLM::Agents.configuration
-        authenticate_or_request_with_http_basic("RubyLLM Agents") do |username, password|
-          ActiveSupport::SecurityUtils.secure_compare(username, config.basic_auth_username) &&
-            ActiveSupport::SecurityUtils.secure_compare(password, config.basic_auth_password)
-        end
-      end
-    end
-  end
-end