ruby_llm-agents 3.5.4 → 3.6.0

data/lib/ruby_llm/agents/base_agent.rb

@@ -46,6 +46,7 @@ module RubyLLM
       extend DSL::Base
       extend DSL::Reliability
       extend DSL::Caching
+      extend DSL::Queryable
       include CacheHelper
 
       class << self
@@ -119,6 +120,83 @@ module RubyLLM
           :conversation
         end
 
+        # Declares previous class names for this agent
+        #
+        # When an agent is renamed, old execution records still reference the
+        # previous class name. Declaring aliases allows scopes, analytics, and
+        # budget checks to automatically include records from all previous names.
+        #
+        # @param names [Array<String>] Previous class names
+        # @return [Array<String>] All declared aliases
+        #
+        # @example
+        #   class SupportBot < ApplicationAgent
+        #     aliases "CustomerSupportAgent", "HelpDeskAgent"
+        #   end
+        def aliases(*names)
+          if names.any?
+            @agent_aliases = names.map(&:to_s)
+          end
+          @agent_aliases || []
+        end
+
+        # Returns all known names for this agent (current + aliases)
+        #
+        # @return [Array<String>] Current name followed by any aliases
+        def all_agent_names
+          [name, *aliases].compact.uniq
+        end
+
+        # Returns a summary of the agent's DSL configuration
+        #
+        # Useful for debugging in the Rails console to see how an agent
+        # is configured without instantiating it.
+        #
+        # @return [Hash] Agent configuration summary
+        # @example
+        #   MyAgent.config_summary
+        def config_summary
+          {
+            agent_type: agent_type,
+            model: model,
+            temperature: temperature,
+            timeout: timeout,
+            streaming: streaming,
+            system_prompt: system_config,
+            user_prompt: user_config,
+            assistant_prompt: assistant_config,
+            description: description,
+            schema: schema&.respond_to?(:name) ? schema.name : schema&.class&.name,
+            tools: tools.map { |t| t.respond_to?(:name) ? t.name : t.to_s },
+            parameters: params.transform_values { |v| v.slice(:type, :required, :default, :desc) },
+            thinking: thinking_config,
+            caching: caching_config,
+            reliability: reliability_configured? ? reliability_config : nil
+          }.compact
+        end
+
+        # @!group Custom Middleware DSL
+
+        # Registers a custom middleware for this agent class
+        #
+        # @param middleware_class [Class] Must inherit from Pipeline::Middleware::Base
+        # @param before [Class, nil] Insert before this built-in middleware
+        # @param after [Class, nil] Insert after this built-in middleware
+        # @return [void]
+        def use_middleware(middleware_class, before: nil, after: nil)
+          @agent_middleware ||= []
+          @agent_middleware << {klass: middleware_class, before: before, after: after}
+        end
+
+        # Returns custom middleware registered on this agent (including inherited)
+        #
+        # @return [Array<Hash>] Middleware entries with :klass, :before, :after keys
+        def agent_middleware
+          @agent_middleware || (superclass.respond_to?(:agent_middleware) ? superclass.agent_middleware : []) || []
+        end
+
+        # @!endgroup
+
         # @!group Parameter DSL
 
         # Defines a parameter for the agent
@@ -131,9 +209,9 @@ module RubyLLM
         # @param default [Object, nil] Default value if not provided
         # @param type [Class, nil] Optional type for validation
         # @return [void]
-        def param(name, required: false, default: nil, type: nil)
+        def param(name, required: false, default: nil, type: nil, desc: nil, description: nil)
           @params ||= {}
-          @params[name] = {required: required, default: default, type: type}
+          @params[name] = {required: required, default: default, type: type, desc: desc || description}
           define_method(name) do
             @options[name] || @options[name.to_s] || self.class.params.dig(name, :default)
           end
@@ -255,6 +333,8 @@ module RubyLLM
       # @param options [Hash] Agent parameters defined via the param DSL
       def initialize(model: self.class.model, temperature: self.class.temperature, **options)
         @ask_message = options.delete(:_ask_message)
+        @parent_execution_id = options.delete(:_parent_execution_id)
+        @root_execution_id = options.delete(:_root_execution_id)
         @model = model
         @temperature = temperature
         @options = options
@@ -347,7 +427,7 @@ module RubyLLM
         content = response.content
         return content unless content.is_a?(Hash)
 
-        content.transform_keys(&:to_sym)
+        content.deep_symbolize_keys
       end
 
       # @!endgroup
@@ -424,6 +504,8 @@ module RubyLLM
           tenant: resolve_tenant,
           skip_cache: @options[:skip_cache],
           stream_block: (block if streaming_enabled?),
+          parent_execution_id: @parent_execution_id,
+          root_execution_id: @root_execution_id,
           options: execution_options
         )
       end
@@ -463,13 +545,62 @@ module RubyLLM
 
       # Resolves tools for this execution
       #
+      # Agent classes in the tools list are automatically wrapped as
+      # RubyLLM::Tool subclasses via AgentTool.for. Regular tool classes
+      # pass through unchanged.
+      #
       # @return [Array<Class>] Tool classes to use
+      # @raise [ArgumentError] If duplicate tool names are detected
       def resolved_tools
-        if self.class.method_defined?(:tools, false)
+        raw = if self.class.method_defined?(:tools, false)
           tools
         else
           self.class.tools
         end
+
+        wrapped = raw.map { |tool_class| wrap_if_agent(tool_class) }
+        detect_duplicate_tool_names!(wrapped)
+        wrapped
+      end
+
+      # Wraps an agent class as a tool, or returns the tool class as-is.
+      #
+      # @param tool_class [Class] A tool or agent class
+      # @return [Class] The original or wrapped class
+      def wrap_if_agent(tool_class)
+        if tool_class.respond_to?(:ancestors) && tool_class.ancestors.include?(RubyLLM::Agents::BaseAgent)
+          AgentTool.for(tool_class)
+        else
+          tool_class
+        end
+      end
+
+      # Raises if two tools resolve to the same name.
+      #
+      # @param tools [Array] Resolved tool classes or instances
+      # @raise [ArgumentError] On duplicate names
+      def detect_duplicate_tool_names!(tools)
+        names = tools.map { |t| tool_name_for(t) }
+        duplicates = names.group_by(&:itself).select { |_, v| v.size > 1 }.keys
+        raise ArgumentError, "Duplicate tool names: #{duplicates.join(", ")}" if duplicates.any?
+      end
+
+      # Extracts a tool name from a tool class or instance.
+      #
+      # @param tool [Class, Object] A tool class or instance
+      # @return [String] The tool name
+      def tool_name_for(tool)
+        return tool.tool_name if tool.respond_to?(:tool_name)
+
+        if tool.is_a?(Class) && tool < RubyLLM::Tool
+          tool.new.name
+        elsif tool.is_a?(Class)
+          tool.name.to_s
+        elsif tool.respond_to?(:name)
+          tool.name.to_s
+        else
+          tool.to_s
+        end
       end
 
       # Resolves messages for this execution
@@ -581,10 +712,17 @@ module RubyLLM
       # @return [void] Sets context.output with the result
       def execute(context)
         client = build_client(context)
+
+        # Make context available to AgentTool instances during tool execution
+        previous_context = Thread.current[:ruby_llm_agents_caller_context]
+        Thread.current[:ruby_llm_agents_caller_context] = context
+
         response = execute_llm_call(client, context)
         capture_response(response, context)
         result = build_result(process_response(response), response, context)
         context.output = result
+      ensure
+        Thread.current[:ruby_llm_agents_caller_context] = previous_context
       end
 
       # Builds and configures the RubyLLM client
@@ -761,7 +899,8 @@ module RubyLLM
           time_to_first_token_ms: context.time_to_first_token_ms,
           finish_reason: context.finish_reason,
           streaming: streaming_enabled?,
-          attempts_count: context.attempts_made || 1
+          attempts_count: context.attempts_made || 1,
+          execution_id: context.execution_id
         )
       end
 

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

@@ -308,13 +308,6 @@ module RubyLLM
       #   @example
       #     config.track_speech = false
 
-      # @!attribute [rw] async_max_concurrency
-      #   Maximum number of concurrent async operations when using batch processing.
-      #   Controls the semaphore limit for Async::Semaphore.
-      #   @return [Integer] Max concurrent operations (default: 10)
-      #   @example
-      #     config.async_max_concurrency = 20
-
       # @!attribute [rw] root_directory
       #   The root directory name under app/ for all agent components.
       #   This allows customization of the directory structure.
@@ -339,18 +332,6 @@ module RubyLLM
       #   @example
       #     config.tool_result_max_length = 5000
 
-      # @!attribute [rw] redaction
-      #   Configuration for PII and sensitive data redaction.
-      #   When set, sensitive data is redacted before storing in execution records.
-      #   @return [Hash, nil] Redaction config with :fields, :patterns, :placeholder, :max_value_length keys
-      #   @example
-      #     config.redaction = {
-      #       fields: %w[ssn credit_card phone_number email],
-      #       patterns: [/\b\d{3}-\d{2}-\d{4}\b/],
-      #       placeholder: "[REDACTED]",
-      #       max_value_length: 5000
-      #     }
-
       # API key and provider attributes forwarded to RubyLLM.
       # These let users configure everything in one place through
       # RubyLLM::Agents.configure instead of a separate RubyLLM.configure block.
@@ -391,12 +372,12 @@ module RubyLLM
       end
 
       # Attributes with custom setters (validation) — only readers here
-      attr_reader :default_embedding_dimensions, :default_embedding_batch_size
+      attr_reader :default_embedding_dimensions, :default_embedding_batch_size,
+        :middleware_stack
 
       # Attributes without validation (simple accessors)
       attr_accessor :default_model,
         :async_logging,
-        :async_max_concurrency,
         :retention_period,
         :dashboard_parent_controller,
         :basic_auth_username,
@@ -452,7 +433,6 @@ module RubyLLM
         :root_directory,
         :root_namespace,
         :tool_result_max_length,
-        :redaction,
         :persist_audio_data,
         :elevenlabs_base_cost_per_1k,
         :elevenlabs_models_cache_ttl,
@@ -633,7 +613,6 @@ module RubyLLM
         @default_timeout = 60
         @cache_store = nil
         @async_logging = true
-        @async_max_concurrency = 10
         @retention_period = 30.days
         @anomaly_cost_threshold = 5.00
         @anomaly_duration_threshold = 10_000
@@ -711,7 +690,7 @@ module RubyLLM
 
         # TTS pricing defaults
         @tts_model_pricing = {}
-        @default_tts_cost = 0.015
+        @default_tts_cost = nil
 
         # Execution/conversation agent tracking
         @track_executions = true
@@ -734,7 +713,7 @@ module RubyLLM
         # Image Pricing defaults
         @litellm_pricing_url = nil  # Use default from Pricing module
         @litellm_pricing_cache_ttl = nil  # Use default (24 hours)
-        @default_image_cost = 0.04  # Fallback cost per image
+        @default_image_cost = nil  # User-configurable fallback cost per image
         @image_model_pricing = {}  # User-defined pricing overrides
 
         # Phase 2: Image Variation, Editing, Transformation, Upscaling defaults
@@ -756,17 +735,18 @@ module RubyLLM
         @root_directory = "agents"  # Root directory under app/
         @root_namespace = nil  # No namespace (top-level classes)
 
+        # Custom middleware stack
+        @middleware_stack = []
+
         # Tool tracking defaults
         @tool_result_max_length = 10_000
 
-        # Redaction defaults (disabled by default)
-        @redaction = nil
-
         # Audio data persistence (disabled by default — base64 audio can be large)
         @persist_audio_data = false
 
-        # ElevenLabs dynamic pricing: base cost per 1K characters (Pro plan overage rate)
-        @elevenlabs_base_cost_per_1k = 0.30
+        # ElevenLabs dynamic pricing: base cost per 1K characters
+        # Set to your plan's overage rate (e.g., 0.30 for Pro) to enable API-based pricing
+        @elevenlabs_base_cost_per_1k = nil
         # ElevenLabs models cache TTL in seconds (6 hours)
         @elevenlabs_models_cache_ttl = 21_600
       end
@@ -801,6 +781,27 @@ module RubyLLM
         default_retryable_patterns.values.flatten.uniq
       end
 
+      # Registers a custom middleware class for all agents
+      #
+      # @param middleware_class [Class] Must inherit from Pipeline::Middleware::Base
+      # @param before [Class, nil] Insert before this built-in middleware
+      # @param after [Class, nil] Insert after this built-in middleware
+      # @return [self] For method chaining
+      # @raise [ArgumentError] If middleware_class is invalid
+      def use_middleware(middleware_class, before: nil, after: nil)
+        validate_middleware_class!(middleware_class)
+        @middleware_stack << {klass: middleware_class, before: before, after: after}
+        self
+      end
+
+      # Removes all custom middleware
+      #
+      # @return [self] For method chaining
+      def clear_middleware!
+        @middleware_stack = []
+        self
+      end
+
       # Returns whether multi-tenancy is enabled
       #
       # @return [Boolean] true if multi-tenancy is enabled
@@ -889,6 +890,136 @@ module RubyLLM
         end
       end
 
+      # Attribute names that contain sensitive values (API keys, passwords)
+      SENSITIVE_ATTRIBUTES = (
+        FORWARDED_RUBY_LLM_ATTRIBUTES.select { |a| a.to_s.match?(/api_key|secret_key|session_token/) } +
+        %i[basic_auth_password elevenlabs_api_key]
+      ).freeze
+
+      # Returns all configuration as a hash grouped by category
+      #
+      # Useful for debugging in the Rails console. Sensitive values
+      # (API keys, passwords) are hidden by default.
+      #
+      # @param include_sensitive [Boolean] Whether to include API keys and passwords
+      # @return [Hash] Configuration grouped by category
+      # @example
+      #   RubyLLM::Agents.configuration.to_h
+      #   RubyLLM::Agents.configuration.to_h(include_sensitive: true)
+      def to_h(include_sensitive: false)
+        {
+          model: {
+            default_model: default_model,
+            default_temperature: default_temperature,
+            default_timeout: default_timeout,
+            default_streaming: default_streaming,
+            default_thinking: default_thinking
+          },
+          reliability: {
+            default_retries: default_retries,
+            default_fallback_models: default_fallback_models,
+            default_total_timeout: default_total_timeout,
+            default_retryable_patterns: default_retryable_patterns
+          },
+          governance: {
+            budgets: budgets,
+            on_alert: on_alert&.class&.name,
+            persist_prompts: persist_prompts,
+            persist_responses: persist_responses,
+            persist_messages_summary: persist_messages_summary,
+            messages_summary_max_length: messages_summary_max_length
+          },
+          multi_tenancy: {
+            enabled: multi_tenancy_enabled,
+            tenant_resolver: tenant_resolver&.class&.name,
+            tenant_config_resolver: tenant_config_resolver&.class&.name
+          },
+          dashboard: {
+            per_page: per_page,
+            recent_executions_limit: recent_executions_limit,
+            dashboard_parent_controller: dashboard_parent_controller,
+            basic_auth_username: basic_auth_username,
+            dashboard_auth: dashboard_auth&.class&.name
+          },
+          logging: {
+            async_logging: async_logging,
+            retention_period: retention_period,
+            job_retry_attempts: job_retry_attempts,
+            track_executions: track_executions,
+            track_cache_hits: track_cache_hits,
+            track_audio: track_audio
+          },
+          anomaly: {
+            anomaly_cost_threshold: anomaly_cost_threshold,
+            anomaly_duration_threshold: anomaly_duration_threshold
+          },
+          tools: {
+            default_tools: default_tools,
+            tool_result_max_length: tool_result_max_length
+          },
+          embedding: {
+            default_embedding_model: default_embedding_model,
+            default_embedding_dimensions: default_embedding_dimensions,
+            default_embedding_batch_size: default_embedding_batch_size,
+            track_embeddings: track_embeddings
+          },
+          transcription: {
+            default_transcription_model: default_transcription_model,
+            track_transcriptions: track_transcriptions,
+            transcription_model_pricing: transcription_model_pricing,
+            default_transcription_cost: default_transcription_cost
+          },
+          speech: {
+            default_tts_provider: default_tts_provider,
+            default_tts_model: default_tts_model,
+            default_tts_voice: default_tts_voice,
+            track_speech: track_speech,
+            tts_model_pricing: tts_model_pricing,
+            default_tts_cost: default_tts_cost,
+            persist_audio_data: persist_audio_data,
+            elevenlabs_api_base: elevenlabs_api_base,
+            elevenlabs_base_cost_per_1k: elevenlabs_base_cost_per_1k,
+            elevenlabs_models_cache_ttl: elevenlabs_models_cache_ttl
+          },
+          image: {
+            default_image_model: default_image_model,
+            default_image_size: default_image_size,
+            default_image_quality: default_image_quality,
+            default_image_style: default_image_style,
+            max_image_prompt_length: max_image_prompt_length,
+            track_image_generation: track_image_generation,
+            image_model_aliases: image_model_aliases,
+            default_image_cost: default_image_cost,
+            image_model_pricing: image_model_pricing,
+            default_variator_model: default_variator_model,
+            default_editor_model: default_editor_model,
+            default_transformer_model: default_transformer_model,
+            default_upscaler_model: default_upscaler_model,
+            default_variation_strength: default_variation_strength,
+            default_transform_strength: default_transform_strength,
+            default_analyzer_model: default_analyzer_model,
+            default_analysis_type: default_analysis_type,
+            default_analyzer_max_tags: default_analyzer_max_tags,
+            default_background_remover_model: default_background_remover_model,
+            default_background_output_format: default_background_output_format
+          },
+          pricing: {
+            pricing_cache_ttl: pricing_cache_ttl,
+            portkey_pricing_enabled: portkey_pricing_enabled,
+            openrouter_pricing_enabled: openrouter_pricing_enabled,
+            helicone_pricing_enabled: helicone_pricing_enabled,
+            llmpricing_enabled: llmpricing_enabled,
+            litellm_pricing_url: litellm_pricing_url,
+            litellm_pricing_cache_ttl: litellm_pricing_cache_ttl
+          },
+          directory: {
+            root_directory: root_directory,
+            root_namespace: root_namespace
+          },
+          api_keys: include_sensitive ? sensitive_api_keys : "(hidden, pass include_sensitive: true)"
+        }
+      end
+
       # Returns all autoload paths for LLM components
       #
       # @return [Array<String>] List of paths relative to Rails.root
@@ -905,36 +1036,30 @@ module RubyLLM
         ]
       end
 
-      # Returns the redaction fields (parameter names to redact)
-      #
-      # @return [Array<String>] Fields to redact
-      def redaction_fields
-        redaction&.dig(:fields) || []
-      end
-
-      # Returns the redaction regex patterns
-      #
-      # @return [Array<Regexp>] Patterns to match and redact
-      def redaction_patterns
-        redaction&.dig(:patterns) || []
-      end
+      private
 
-      # Returns the redaction placeholder string
+      # Returns all sensitive API key values as a hash
       #
-      # @return [String] Placeholder for redacted values (default: "[REDACTED]")
-      def redaction_placeholder
-        redaction&.dig(:placeholder) || "[REDACTED]"
+      # @return [Hash] API key attributes and their values
+      def sensitive_api_keys
+        FORWARDED_RUBY_LLM_ATTRIBUTES.each_with_object({}) do |attr, h|
+          h[attr] = public_send(attr)
+        end.merge(
+          elevenlabs_api_key: elevenlabs_api_key,
+          basic_auth_password: basic_auth_password
+        )
       end
 
-      # Returns the max value length for redaction
+      # Validates that a middleware class inherits from Pipeline::Middleware::Base
       #
-      # @return [Integer, nil] Max length before truncation, or nil for no limit
-      def redaction_max_value_length
-        redaction&.dig(:max_value_length)
+      # @param klass [Class] The class to validate
+      # @raise [ArgumentError] If the class is invalid
+      def validate_middleware_class!(klass)
+        unless klass.is_a?(Class) && klass <= RubyLLM::Agents::Pipeline::Middleware::Base
+          raise ArgumentError, "#{klass} must inherit from RubyLLM::Agents::Pipeline::Middleware::Base"
+        end
       end
 
-      private
-
       # Validates that a value is within a range
       #
       # @param attr [Symbol] Attribute name for error message

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

@@ -5,83 +5,6 @@ module RubyLLM
     # Base error class for RubyLLM::Agents
     class Error < StandardError; end
 
-    # ============================================================
-    # Pipeline Errors
-    # ============================================================
-
-    # Base class for pipeline-related errors
-    class PipelineError < Error; end
-
-    # ============================================================
-    # Reliability Errors
-    # ============================================================
-
-    # Base class for reliability-related errors
-    class ReliabilityError < Error; end
-
-    # Raised when an error is retryable (transient)
-    class RetryableError < ReliabilityError; end
-
-    # Raised when a circuit breaker is open
-    class CircuitOpenError < ReliabilityError
-      # @return [String] The model that has an open circuit
-      attr_reader :model
-
-      def initialize(message = nil, model: nil)
-        @model = model
-        super(message || "Circuit breaker is open#{" for #{model}" if model}")
-      end
-    end
-
-    # Raised when total timeout is exceeded across all attempts
-    class TotalTimeoutError < ReliabilityError
-      # @return [Float] The timeout that was exceeded
-      attr_reader :timeout
-
-      # @return [Float] The elapsed time
-      attr_reader :elapsed
-
-      def initialize(message = nil, timeout: nil, elapsed: nil)
-        @timeout = timeout
-        @elapsed = elapsed
-        super(message || "Total timeout of #{timeout}s exceeded (elapsed: #{elapsed&.round(2)}s)")
-      end
-    end
-
-    # Raised when all models (primary + fallbacks) fail
-    class AllModelsFailedError < ReliabilityError
-      # @return [Array<Hash>] Details of each failed attempt
-      attr_reader :attempts
-
-      def initialize(message = nil, attempts: [])
-        @attempts = attempts
-        models = attempts.map { |a| a[:model] }.compact.join(", ")
-        super(message || "All models failed: #{models}")
-      end
-    end
-
-    # ============================================================
-    # Budget Errors
-    # ============================================================
-
-    # Base class for budget-related errors
-    class BudgetError < Error; end
-
-    # Raised when budget is exceeded
-    class BudgetExceededError < BudgetError
-      # @return [String, nil] The tenant ID
-      attr_reader :tenant_id
-
-      # @return [String, nil] The budget type (daily, monthly, etc.)
-      attr_reader :budget_type
-
-      def initialize(message = nil, tenant_id: nil, budget_type: nil)
-        @tenant_id = tenant_id
-        @budget_type = budget_type
-        super(message || "Budget exceeded#{" for tenant #{tenant_id}" if tenant_id}")
-      end
-    end
-
     # ============================================================
     # Configuration Errors
     # ============================================================
@@ -103,6 +26,9 @@ module RubyLLM
       end
     end
 
+    # Raised when an execution cannot be replayed
+    class ReplayError < Error; end
+
     # Raised when the TTS API returns an error response
     class SpeechApiError < Error
       attr_reader :status, :response_body

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

@@ -836,23 +836,6 @@ module RubyLLM
         }.compact
       end
 
-      # Serializes tool calls to an array of hashes for storage
-      #
-      # @param response [RubyLLM::Message] The LLM response
-      # @return [Array<Hash>, nil] Serialized tool calls or nil if none
-      def serialize_tool_calls(response)
-        tool_calls = safe_response_value(response, :tool_calls)
-        return nil if tool_calls.nil? || tool_calls.empty?
-
-        tool_calls.map do |id, tool_call|
-          if tool_call.respond_to?(:to_h)
-            tool_call.to_h
-          else
-            {id: id, name: tool_call[:name], arguments: tool_call[:arguments]}
-          end
-        end
-      end
-
       # Records an execution for a cache hit
       #
       # Creates a minimal execution record with cache_hit: true, 0 tokens,

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 = "3.5.4"
+    VERSION = "3.6.0"
   end
 end

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

@@ -123,14 +123,6 @@ module RubyLLM
           @user_template || inherited_or_default(:user_config, nil)
         end
 
-        # Returns the prompt configuration (alias for user_config)
-        #
-        # @deprecated Use `user_config` instead
-        # @return [String, nil] The prompt template, or nil
-        def prompt_config
-          user_config
-        end
-
         # Sets the system prompt/instructions
         #
         # When a string is provided, {placeholder} syntax is supported for