ruby_llm-agents 0.2.4 → 0.3.0

data/lib/ruby_llm/agents/configuration.rb

@@ -2,7 +2,182 @@
 
 module RubyLLM
   module Agents
+    # Global configuration for RubyLLM::Agents
+    #
+    # Provides centralized settings for agent behavior, dashboard authentication,
+    # caching, and observability thresholds.
+    #
+    # @example Basic configuration
+    #   RubyLLM::Agents.configure do |config|
+    #     config.default_model = "gpt-4o"
+    #     config.default_temperature = 0.7
+    #     config.async_logging = true
+    #   end
+    #
+    # @example Dashboard with HTTP Basic Auth
+    #   RubyLLM::Agents.configure do |config|
+    #     config.basic_auth_username = ENV["AGENTS_USER"]
+    #     config.basic_auth_password = ENV["AGENTS_PASS"]
+    #   end
+    #
+    # @example Dashboard with custom authentication
+    #   RubyLLM::Agents.configure do |config|
+    #     config.dashboard_parent_controller = "AdminController"
+    #     config.dashboard_auth = ->(controller) { controller.current_user&.admin? }
+    #   end
+    #
+    # @see RubyLLM::Agents.configure
+    # @api public
     class Configuration
+      # @!attribute [rw] default_model
+      #   The default LLM model identifier for all agents.
+      #   Can be overridden per-agent using the `model` DSL method.
+      #   @return [String] Model identifier (default: "gemini-2.0-flash")
+      #   @example
+      #     config.default_model = "gpt-4o"
+
+      # @!attribute [rw] default_temperature
+      #   The default temperature for LLM responses (0.0 to 2.0).
+      #   Lower values produce more deterministic outputs.
+      #   @return [Float] Temperature value (default: 0.0)
+
+      # @!attribute [rw] default_timeout
+      #   Maximum seconds to wait for an LLM response before timing out.
+      #   @return [Integer] Timeout in seconds (default: 60)
+
+      # @!attribute [rw] async_logging
+      #   Whether to log executions via background job (recommended for production).
+      #   When false, executions are logged synchronously.
+      #   @return [Boolean] Enable async logging (default: true)
+
+      # @!attribute [rw] retention_period
+      #   How long to retain execution records before cleanup.
+      #   @return [ActiveSupport::Duration] Retention period (default: 30.days)
+
+      # @!attribute [rw] anomaly_cost_threshold
+      #   Cost threshold in dollars that triggers anomaly logging.
+      #   Executions exceeding this cost are logged as warnings.
+      #   @return [Float] Cost threshold in USD (default: 5.00)
+
+      # @!attribute [rw] anomaly_duration_threshold
+      #   Duration threshold in milliseconds that triggers anomaly logging.
+      #   @return [Integer] Duration threshold in ms (default: 10_000)
+
+      # @!attribute [rw] dashboard_auth
+      #   Lambda for custom dashboard authentication.
+      #   Receives the controller instance, should return truthy to allow access.
+      #   @return [Proc] Authentication lambda (default: allows all)
+      #   @example
+      #     config.dashboard_auth = ->(c) { c.current_user&.admin? }
+
+      # @!attribute [rw] dashboard_parent_controller
+      #   Parent controller class name for the dashboard.
+      #   Use this to inherit authentication from your app's admin controller.
+      #   @return [String] Controller class name (default: "ActionController::Base")
+
+      # @!attribute [rw] basic_auth_username
+      #   Username for HTTP Basic Auth on the dashboard.
+      #   Both username and password must be set to enable Basic Auth.
+      #   @return [String, nil] Username or nil to disable (default: nil)
+
+      # @!attribute [rw] basic_auth_password
+      #   Password for HTTP Basic Auth on the dashboard.
+      #   @return [String, nil] Password or nil to disable (default: nil)
+
+      # @!attribute [rw] per_page
+      #   Number of records per page in dashboard listings.
+      #   @return [Integer] Records per page (default: 25)
+
+      # @!attribute [rw] recent_executions_limit
+      #   Number of recent executions shown on the dashboard home.
+      #   @return [Integer] Limit for recent executions (default: 10)
+
+      # @!attribute [rw] job_retry_attempts
+      #   Number of retry attempts for the async logging job on failure.
+      #   @return [Integer] Retry attempts (default: 3)
+
+      # @!attribute [w] cache_store
+      #   Custom cache store for agent response caching.
+      #   Falls back to Rails.cache if not set.
+      #   @return [ActiveSupport::Cache::Store, nil]
+
+      # @!attribute [rw] default_retries
+      #   Default retry configuration for all agents.
+      #   Can be overridden per-agent using the `retries` DSL method.
+      #   @return [Hash] Retry config with :max, :backoff, :base, :max_delay, :on keys
+      #   @example
+      #     config.default_retries = { max: 2, backoff: :exponential, base: 0.4, max_delay: 3.0, on: [] }
+
+      # @!attribute [rw] default_fallback_models
+      #   Default fallback models for all agents.
+      #   Can be overridden per-agent using the `fallback_models` DSL method.
+      #   @return [Array<String>] List of model identifiers to try on failure
+
+      # @!attribute [rw] default_total_timeout
+      #   Default total timeout across all retry attempts.
+      #   Can be overridden per-agent using the `total_timeout` DSL method.
+      #   @return [Integer, nil] Total timeout in seconds, or nil for no limit
+
+      # @!attribute [rw] default_streaming
+      #   Whether streaming mode is enabled by default for all agents.
+      #   When enabled and a block is passed to call, chunks are yielded as they arrive.
+      #   Can be overridden per-agent using the `streaming` DSL method.
+      #   @return [Boolean] Enable streaming (default: false)
+      #   @example
+      #     config.default_streaming = true
+
+      # @!attribute [rw] default_tools
+      #   Default tools available to all agents.
+      #   Should be an array of RubyLLM::Tool classes.
+      #   Can be overridden or extended per-agent using the `tools` DSL method.
+      #   @return [Array<Class>] Tool classes (default: [])
+      #   @example
+      #     config.default_tools = [WeatherTool, SearchTool]
+
+      # @!attribute [rw] budgets
+      #   Budget configuration for cost governance.
+      #   @return [Hash, nil] Budget config with :global_daily, :global_monthly, :per_agent_daily, :per_agent_monthly, :enforcement keys
+      #   @example
+      #     config.budgets = {
+      #       global_daily: 25.0,
+      #       global_monthly: 300.0,
+      #       per_agent_daily: { "ContentAgent" => 5.0 },
+      #       per_agent_monthly: { "ContentAgent" => 120.0 },
+      #       enforcement: :soft
+      #     }
+
+      # @!attribute [rw] alerts
+      #   Alert configuration for notifications.
+      #   @return [Hash, nil] Alert config with :slack_webhook_url, :webhook_url, :on_events, :custom keys
+      #   @example
+      #     config.alerts = {
+      #       slack_webhook_url: ENV["SLACK_WEBHOOK"],
+      #       webhook_url: ENV["AGENTS_WEBHOOK"],
+      #       on_events: [:budget_soft_cap, :budget_hard_cap, :breaker_open],
+      #       custom: ->(event, payload) { Rails.logger.info("Alert: #{event}") }
+      #     }
+
+      # @!attribute [rw] persist_prompts
+      #   Whether to persist system and user prompts in execution records.
+      #   Set to false to reduce storage or for privacy compliance.
+      #   @return [Boolean] Enable prompt persistence (default: true)
+
+      # @!attribute [rw] persist_responses
+      #   Whether to persist LLM responses in execution records.
+      #   Set to false to reduce storage or for privacy compliance.
+      #   @return [Boolean] Enable response persistence (default: true)
+
+      # @!attribute [rw] redaction
+      #   Redaction configuration for PII and sensitive data.
+      #   @return [Hash, nil] Redaction config with :fields, :patterns, :placeholder, :max_value_length keys
+      #   @example
+      #     config.redaction = {
+      #       fields: %w[password api_key email ssn],
+      #       patterns: [/\b\d{3}-\d{2}-\d{4}\b/],
+      #       placeholder: "[REDACTED]",
+      #       max_value_length: 5000
+      #     }
+
       attr_accessor :default_model,
                     :default_temperature,
                     :default_timeout,
@@ -13,10 +188,27 @@ module RubyLLM
                     :dashboard_auth,
                     :dashboard_parent_controller,
                     :basic_auth_username,
-                    :basic_auth_password
+                    :basic_auth_password,
+                    :per_page,
+                    :recent_executions_limit,
+                    :job_retry_attempts,
+                    :default_retries,
+                    :default_fallback_models,
+                    :default_total_timeout,
+                    :default_streaming,
+                    :default_tools,
+                    :budgets,
+                    :alerts,
+                    :persist_prompts,
+                    :persist_responses,
+                    :redaction
 
       attr_writer :cache_store
 
+      # Initializes configuration with default values
+      #
+      # @return [Configuration] A new configuration instance with defaults
+      # @api private
       def initialize
         @default_model = "gemini-2.0-flash"
         @default_temperature = 0.0
@@ -30,11 +222,97 @@ module RubyLLM
         @dashboard_parent_controller = "ActionController::Base"
         @basic_auth_username = nil
         @basic_auth_password = nil
+        @per_page = 25
+        @recent_executions_limit = 10
+        @job_retry_attempts = 3
+
+        # Reliability defaults (all disabled by default for backward compatibility)
+        @default_retries = { max: 0, backoff: :exponential, base: 0.4, max_delay: 3.0, on: [] }
+        @default_fallback_models = []
+        @default_total_timeout = nil
+
+        # Streaming and tools defaults
+        @default_streaming = false
+        @default_tools = []
+
+        # Governance defaults
+        @budgets = nil
+        @alerts = nil
+        @persist_prompts = true
+        @persist_responses = true
+        @redaction = nil
       end
 
+      # Returns the configured cache store, falling back to Rails.cache
+      #
+      # @return [ActiveSupport::Cache::Store] The cache store instance
+      # @example Using a custom cache store
+      #   config.cache_store = ActiveSupport::Cache::MemoryStore.new
       def cache_store
         @cache_store || Rails.cache
       end
+
+      # Returns whether budgets are configured and enforcement is enabled
+      #
+      # @return [Boolean] true if budgets are configured with enforcement
+      def budgets_enabled?
+        budgets.is_a?(Hash) && budgets[:enforcement] && budgets[:enforcement] != :none
+      end
+
+      # Returns the budget enforcement mode
+      #
+      # @return [Symbol] :none, :soft, or :hard
+      def budget_enforcement
+        budgets&.dig(:enforcement) || :none
+      end
+
+      # Returns whether alerts are configured
+      #
+      # @return [Boolean] true if any alert destination is configured
+      def alerts_enabled?
+        return false unless alerts.is_a?(Hash)
+
+        alerts[:slack_webhook_url].present? ||
+          alerts[:webhook_url].present? ||
+          alerts[:custom].present?
+      end
+
+      # Returns the list of events to alert on
+      #
+      # @return [Array<Symbol>] Event names to trigger alerts
+      def alert_events
+        alerts&.dig(:on_events) || []
+      end
+
+      # Returns merged redaction fields (default sensitive keys + configured)
+      #
+      # @return [Array<String>] Field names to redact
+      def redaction_fields
+        default_fields = %w[password token api_key secret credential auth key access_token]
+        configured_fields = redaction&.dig(:fields) || []
+        (default_fields + configured_fields).map(&:downcase).uniq
+      end
+
+      # Returns redaction patterns
+      #
+      # @return [Array<Regexp>] Patterns to match and redact
+      def redaction_patterns
+        redaction&.dig(:patterns) || []
+      end
+
+      # Returns the redaction placeholder string
+      #
+      # @return [String] Placeholder to replace redacted values
+      def redaction_placeholder
+        redaction&.dig(:placeholder) || "[REDACTED]"
+      end
+
+      # Returns the maximum value length before truncation
+      #
+      # @return [Integer, nil] Max length, or nil for no limit
+      def redaction_max_value_length
+        redaction&.dig(:max_value_length)
+      end
     end
   end
 end

data/lib/ruby_llm/agents/engine.rb

@@ -2,22 +2,49 @@
 
 module RubyLLM
   module Agents
+    # Rails Engine for RubyLLM::Agents
+    #
+    # Provides a mountable dashboard for monitoring agent executions,
+    # with configurable authentication and automatic agent autoloading.
+    #
+    # @example Mounting the engine in routes.rb
+    #   Rails.application.routes.draw do
+    #     mount RubyLLM::Agents::Engine => "/agents"
+    #   end
+    #
+    # @example With authentication via parent controller
+    #   RubyLLM::Agents.configure do |config|
+    #     config.dashboard_parent_controller = "AdminController"
+    #   end
+    #
+    # @see RubyLLM::Agents::Configuration
+    # @api public
     class Engine < ::Rails::Engine
       isolate_namespace RubyLLM::Agents
 
-      # Use to_prepare to load classes after autoloading is set up
-      # This ensures app/models are available when referenced
+      # Dynamically creates the ApplicationController after Rails autoloading is ready.
+      # This allows the parent controller to be configured at runtime.
+      #
+      # The generated controller:
+      # - Inherits from the configured dashboard_parent_controller
+      # - Uses the engine's layout and helpers
+      # - Applies authentication via before_action
+      #
+      # @api private
       config.to_prepare do
         require_relative "execution_logger_job"
         require_relative "instrumentation"
         require_relative "base"
 
-        # Dynamically set parent controller based on configuration
+        # Resolve the parent controller class from configuration
+        # Default is ActionController::Base, but can be set to inherit from app controllers
         parent_class = RubyLLM::Agents.configuration.dashboard_parent_controller.constantize
 
-        # Remove existing constant if defined, then redefine with correct parent
+        # Remove existing constant to allow redefinition on configuration change
+        # This is necessary for Rails reloading in development
         RubyLLM::Agents.send(:remove_const, :ApplicationController) if RubyLLM::Agents.const_defined?(:ApplicationController, false)
 
+        # Define the ApplicationController dynamically with the configured parent
         RubyLLM::Agents.const_set(:ApplicationController, Class.new(parent_class) do
           layout "rubyllm/agents/application"
           helper RubyLLM::Agents::ApplicationHelper
@@ -25,6 +52,14 @@ module RubyLLM
 
           private
 
+          # Authenticates dashboard access using configured method
+          #
+          # Authentication priority:
+          # 1. HTTP Basic Auth (if username/password configured)
+          # 2. Custom auth proc (dashboard_auth lambda)
+          #
+          # @return [void]
+          # @api private
           def authenticate_dashboard!
             if basic_auth_configured?
               authenticate_with_http_basic_auth
@@ -36,11 +71,21 @@ module RubyLLM
             end
           end
 
+          # Checks if HTTP Basic Auth credentials are configured
+          #
+          # @return [Boolean] true if both username and password are present
+          # @api private
           def basic_auth_configured?
             config = RubyLLM::Agents.configuration
             config.basic_auth_username.present? && config.basic_auth_password.present?
           end
 
+          # Performs HTTP Basic Auth with timing-safe comparison
+          #
+          # Uses secure_compare to prevent timing attacks on credentials.
+          #
+          # @return [void]
+          # @api private
           def authenticate_with_http_basic_auth
             config = RubyLLM::Agents.configuration
             authenticate_or_request_with_http_basic("RubyLLM Agents") do |username, password|
@@ -51,14 +96,21 @@ module RubyLLM
         end)
       end
 
-      # Configure generators
+      # Configures default generators for the engine
+      # Sets up RSpec and FactoryBot for generated specs
+      # @api private
       config.generators do |g|
         g.test_framework :rspec
         g.fixture_replacement :factory_bot
         g.factory_bot dir: "spec/factories"
       end
 
-      # Add app/agents to autoload paths for host app (must be done before initialization)
+      # Adds the host app's app/agents directory to Rails autoload paths
+      #
+      # This allows agent classes defined in app/agents/ to be automatically
+      # loaded without explicit requires. Must run before set_autoload_paths.
+      #
+      # @api private
       initializer "ruby_llm_agents.autoload_agents", before: :set_autoload_paths do |app|
         agents_path = app.root.join("app/agents")
         if agents_path.exist?

data/lib/ruby_llm/agents/execution_logger_job.rb

@@ -4,23 +4,26 @@ module RubyLLM
   module Agents
     # Background job for logging agent executions to the database
     #
-    # This job is called automatically after each agent execution to:
-    # - Create an Execution record with all execution data
-    # - Calculate costs based on token usage
-    # - Log anomalies (expensive, slow, or failed executions)
+    # Called automatically after each agent execution to create records,
+    # calculate costs, and detect anomalies.
     #
-    # Configuration:
+    # @example Configuration
     #   RubyLLM::Agents.configure do |config|
     #     config.anomaly_cost_threshold = 5.00       # Log if cost > $5
     #     config.anomaly_duration_threshold = 10_000 # Log if duration > 10s
     #   end
     #
+    # @see RubyLLM::Agents::Instrumentation
+    # @api private
     class ExecutionLoggerJob < ActiveJob::Base
       queue_as :default
 
-      # Retry with polynomial backoff
       retry_on StandardError, wait: :polynomially_longer, attempts: 3
 
+      # Creates execution record and performs post-processing
+      #
+      # @param execution_data [Hash] Execution attributes from instrumentation
+      # @return [void]
       def perform(execution_data)
         execution = Execution.create!(execution_data)
 
@@ -36,6 +39,10 @@ module RubyLLM
 
       private
 
+      # Checks if execution should be flagged as anomalous
+      #
+      # @param execution [Execution] The execution to check
+      # @return [Boolean] true if cost/duration exceeds thresholds or status is error
       def anomaly?(execution)
         config = RubyLLM::Agents.configuration
 
@@ -44,6 +51,10 @@ module RubyLLM
           execution.status_error?
       end
 
+      # Logs a warning about an anomalous execution
+      #
+      # @param execution [Execution] The anomalous execution
+      # @return [void]
       def log_anomaly(execution)
         Rails.logger.warn(
           "[RubyLLM::Agents] Execution anomaly detected: " \

data/lib/ruby_llm/agents/inflections.rb

@@ -1,11 +1,22 @@
 # frozen_string_literal: true
 
-# Configure acronym for Rails inflector (used in routes)
+# Inflection configuration for Rails autoloading
+#
+# Configures Rails and Zeitwerk to properly handle the "LLM" acronym
+# and the "ruby_llm" directory naming convention.
+#
+# This ensures:
+# - "LLM" is recognized as an acronym (not "Llm")
+# - "ruby_llm" directory maps to "RubyLLM" module
+#
+# @api private
+
+# Register "LLM" as an acronym for ActiveSupport inflector
 ActiveSupport::Inflector.inflections(:en) do |inflect|
   inflect.acronym "LLM"
 end
 
-# Configure Zeitwerk inflection when autoloaders are available
+# Configure Zeitwerk to map directory names correctly
 ActiveSupport.on_load(:before_configuration) do
   Rails.autoloaders.each do |autoloader|
     autoloader.inflector.inflect("ruby_llm" => "RubyLLM")