ruby_llm-agents 3.5.5 → 3.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fcd75502c369dc11b47f538e49ab52b0a04fa742c0df7b889915ee3b6003eebb
-  data.tar.gz: 14d32d454e00c7bf2f0c9d1f61c0d8c16b82fd6d63fd3d72bc5d263c2f143ab0
+  metadata.gz: fa3658e8503a35a228e1b1d370c7e9308efb9ec5d0ce7e7a287afa4d69c891a5
+  data.tar.gz: 8bd69d29c6dbdc13f1ba2df4a11bb3032effadf198afff3dc7f2982abf2f62d2
 SHA512:
-  metadata.gz: 8d53fe803e960be5b11e92bae6ad6923b3f648359ec476b9f56c46a355e2f71e75c63b71b546ecd170ee8e923300d6c11889ac8573071a891c8b21570094378e
-  data.tar.gz: 674ba879084fdff24c48c02b0374cff6a1a7218420582d88ad76731f53c8fa9e41b97c081a721de8578d69c8a2348a124c283910b48a8b8b144e44d3ea4ce585
+  metadata.gz: f5c1c97afd3b6448c4b9467b969aa8e521fb578e3c84b2985798d4a02fb78cccf624e771459adb9b06ff42018c705deb322b510288db12e7faaf771e19126206
+  data.tar.gz: b4ad0b9e03fef2df24bd70d0ae72af5d866d87daa6352e2948900c9996c135915fa104e0849c00c88fd13ea126fb6643eada544c87960ea1103716c7286ee4b9

data/README.md

@@ -182,7 +182,11 @@ result.save("logo.png")
 | **Image Operations** | Generation, analysis, editing, pipelines with cost tracking | [Images](https://github.com/adham90/ruby_llm-agents/wiki/Image-Generation) |
 | **Routing** | Message classification and routing with auto-generated prompts, inline classify | [Routing](https://github.com/adham90/ruby_llm-agents/wiki/Routing) |
 | **Audio** | Text-to-speech (OpenAI, ElevenLabs), speech-to-text, dynamic pricing, 28+ output formats, dashboard audio playback | [Audio](https://github.com/adham90/ruby_llm-agents/wiki/Audio) |
+| **Agent Composition** | Use agents as tools in other agents with automatic hierarchy tracking | [Tools](https://github.com/adham90/ruby_llm-agents/wiki/Tools) |
+| **Queryable Agents** | Query execution history from agent classes with stats, replay, and cost breakdown | [Querying](https://github.com/adham90/ruby_llm-agents/wiki/Querying-Executions) |
 | **Alerts** | Slack, webhook, and custom notifications | [Alerts](https://github.com/adham90/ruby_llm-agents/wiki/Alerts) |
+| **AS::Notifications** | 11 instrumentation events across execution, cache, budget, and reliability | [Events](https://github.com/adham90/ruby_llm-agents/wiki/ActiveSupport-Notifications) |
+| **Custom Middleware** | Inject custom middleware globally or per-agent with positioning control | [Middleware](https://github.com/adham90/ruby_llm-agents/wiki/Custom-Middleware) |
 
 ## Quick Start
 

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

@@ -18,43 +18,131 @@ module RubyLLM
       #
       # @return [void]
       def index
-        @selected_range = params[:range].presence || "today"
+        @selected_range = sanitize_range(params[:range])
         @days = range_to_days(@selected_range)
+        parse_custom_dates if @selected_range == "custom"
         base_scope = tenant_scoped_executions
-        @now_strip = base_scope.now_strip_data(range: @selected_range)
+        @now_strip = build_now_strip(base_scope)
         @critical_alerts = load_critical_alerts(base_scope)
         @recent_executions = base_scope.recent(10)
         @agent_stats = build_agent_comparison(base_scope)
         @top_errors = build_top_errors(base_scope)
         @tenant_budget = load_tenant_budget(base_scope)
         @model_stats = build_model_stats(base_scope)
+        @cache_savings = build_cache_savings(base_scope)
+        @top_tenants = build_top_tenants
       end
 
       # Returns chart data as JSON for live updates
       #
-      # @param range [String] Time range: "today", "7d", or "30d"
+      # @param range [String] Time range: "today", "7d", "30d", "90d", or "custom"
       # @return [JSON] Chart data with series
       def chart_data
-        range = params[:range].presence || "today"
-        data = tenant_scoped_executions.activity_chart_json(range: range)
+        range = sanitize_range(params[:range])
+        scope = tenant_scoped_executions
+
+        data = if range == "custom"
+          from = parse_date(params[:from])
+          to = parse_date(params[:to])
+          if from && to
+            from, to = [from, to].sort
+            to = [to, Date.current].min
+            scope.activity_chart_json_for_dates(from: from, to: to)
+          else
+            scope.activity_chart_json(range: "today")
+          end
+        else
+          scope.activity_chart_json(range: range)
+        end
+
         render json: data
       end
 
       private
 
+      # Whitelists valid range values, defaulting to "today"
+      #
+      # @param range [String, nil] Raw range parameter
+      # @return [String] Sanitized range value
+      def sanitize_range(range)
+        %w[today 7d 30d 90d custom].include?(range) ? range : "today"
+      end
+
       # Converts range parameter to number of days
       #
-      # @param range [String] Range parameter (today, 7d, 30d)
-      # @return [Integer] Number of days
+      # @param range [String] Range parameter (today, 7d, 30d, 90d, custom)
+      # @return [Integer, nil] Number of days, or nil for custom
       def range_to_days(range)
         case range
         when "today" then 1
         when "7d" then 7
         when "30d" then 30
+        when "90d" then 90
+        when "custom" then nil
         else 1
         end
       end
 
+      # Safely parses a date string with validation
+      #
+      # Rejects future dates and dates more than 1 year ago.
+      #
+      # @param value [String, nil] Date string (YYYY-MM-DD)
+      # @return [Date, nil] Parsed date or nil if invalid
+      def parse_date(value)
+        return nil if value.blank?
+        date = Date.parse(value)
+        return nil if date > Date.current
+        return nil if date < 1.year.ago.to_date
+        date
+      rescue ArgumentError
+        nil
+      end
+
+      # Parses custom date range params and sets instance variables
+      #
+      # Falls back to "today" if dates are missing or invalid.
+      #
+      # @return [void]
+      def parse_custom_dates
+        from = parse_date(params[:from])
+        to = parse_date(params[:to])
+
+        if from && to
+          from, to = [from, to].sort
+          @custom_from = from
+          @custom_to = [to, Date.current].min
+          @days = (@custom_to - @custom_from).to_i + 1
+        else
+          @selected_range = "today"
+          @days = 1
+        end
+      end
+
+      # Returns the correct time scope for the current range
+      #
+      # @param base_scope [ActiveRecord::Relation] Base scope to filter
+      # @return [ActiveRecord::Relation] Time-scoped relation
+      def time_scoped(base_scope)
+        if @selected_range == "custom" && @custom_from && @custom_to
+          base_scope.where(created_at: @custom_from.beginning_of_day..@custom_to.end_of_day)
+        else
+          base_scope.last_n_days(@days)
+        end
+      end
+
+      # Routes to the correct now_strip_data method based on range
+      #
+      # @param base_scope [ActiveRecord::Relation] Base scope
+      # @return [Hash] Now strip metrics
+      def build_now_strip(base_scope)
+        if @selected_range == "custom" && @custom_from && @custom_to
+          base_scope.now_strip_data_for_dates(from: @custom_from, to: @custom_to)
+        else
+          base_scope.now_strip_data(range: @selected_range)
+        end
+      end
+
       # Builds per-agent comparison statistics for all agent types
       #
       # Creates separate instance variables for each agent type:
@@ -67,7 +155,7 @@ module RubyLLM
       # @param base_scope [ActiveRecord::Relation] Base scope to filter from
       # @return [Array<Hash>] Array of base agent stats (for backward compatibility)
       def build_agent_comparison(base_scope = Execution)
-        scope = base_scope.last_n_days(@days)
+        scope = time_scoped(base_scope)
 
         # Get ALL agents from registry (file system + execution history)
         all_agent_types = AgentRegistry.all
@@ -111,7 +199,7 @@ module RubyLLM
       # @param base_scope [ActiveRecord::Relation] Base scope to filter from
       # @return [Array<Hash>] Array of model stats sorted by total cost descending
       def build_model_stats(base_scope = Execution)
-        scope = base_scope.last_n_days(@days).where.not(model_id: nil)
+        scope = time_scoped(base_scope).where.not(model_id: nil)
 
         # Batch fetch stats grouped by model
         counts = scope.group(:model_id).count
@@ -147,7 +235,7 @@ module RubyLLM
       # @param base_scope [ActiveRecord::Relation] Base scope to filter from
       # @return [Array<Hash>] Top 5 error classes with counts
       def build_top_errors(base_scope = Execution)
-        scope = base_scope.last_n_days(@days).where(status: "error")
+        scope = time_scoped(base_scope).where(status: "error")
         total_errors = scope.count
 
         scope.group(:error_class)
@@ -347,6 +435,63 @@ module RubyLLM
         alerts.take(3)
       end
 
+      # Builds cache savings statistics for the dashboard
+      #
+      # @param base_scope [ActiveRecord::Relation] Base scope to filter from
+      # @return [Hash] Cache savings data with count, estimated savings, and hit rate
+      def build_cache_savings(base_scope)
+        scope = time_scoped(base_scope)
+        total_count = scope.count
+        return {count: 0, estimated_savings: 0, hit_rate: 0, total_executions: 0} if total_count.zero?
+
+        cached_scope = scope.cached
+        cache_count = cached_scope.count
+        estimated_savings = cached_scope.sum(:total_cost)
+
+        {
+          count: cache_count,
+          estimated_savings: estimated_savings,
+          hit_rate: (cache_count.to_f / total_count * 100).round(1),
+          total_executions: total_count
+        }
+      end
+
+      # Builds top tenants list for the dashboard overview
+      #
+      # @return [Array<Hash>, nil] Top 5 tenants by monthly spend, or nil if none
+      def build_top_tenants
+        return nil unless Tenant.table_exists?
+
+        tenants = Tenant.active
+          .where("monthly_cost_spent > 0 OR monthly_executions_count > 0")
+          .order(monthly_cost_spent: :desc)
+          .limit(5)
+
+        return nil if tenants.empty?
+
+        tenants.map do |tenant|
+          tenant.ensure_daily_reset!
+          tenant.ensure_monthly_reset!
+
+          monthly_limit = tenant.effective_monthly_limit
+          daily_limit = tenant.effective_daily_limit
+
+          {
+            id: tenant.id,
+            tenant_id: tenant.tenant_id,
+            name: tenant.display_name,
+            enforcement: tenant.effective_enforcement,
+            monthly_spend: tenant.monthly_cost_spent,
+            monthly_limit: monthly_limit,
+            monthly_percentage: (monthly_limit.to_f > 0) ? (tenant.monthly_cost_spent / monthly_limit * 100).round(1) : 0,
+            daily_spend: tenant.daily_cost_spent,
+            daily_limit: daily_limit,
+            daily_percentage: (daily_limit.to_f > 0) ? (tenant.daily_cost_spent / daily_limit * 100).round(1) : 0,
+            monthly_executions: tenant.monthly_executions_count
+          }
+        end
+      end
+
       # Batch fetches execution stats for all agents in a time period
       #
       # @param scope [ActiveRecord::Relation] Base scope with time filter

data/app/helpers/ruby_llm/agents/application_helper.rb

@@ -286,7 +286,7 @@ module RubyLLM
 
       # Returns human-readable display name for time range
       #
-      # @param range [String] Range parameter (today, 7d, 30d)
+      # @param range [String] Range parameter (today, 7d, 30d, 90d, custom)
       # @return [String] Human-readable range name
       # @example
       #   range_display_name("7d") #=> "7 Days"
@@ -295,10 +295,24 @@ module RubyLLM
         when "today" then "Today"
         when "7d" then "7 Days"
         when "30d" then "30 Days"
+        when "90d" then "90 Days"
+        when "custom" then "Custom"
         else "Today"
         end
       end
 
+      # Returns preset range options for the time range dropdown
+      #
+      # @return [Array<Hash>] Array of {value:, label:} pairs
+      def range_presets
+        [
+          {value: "today", label: "Today"},
+          {value: "7d", label: "7 Days"},
+          {value: "30d", label: "30 Days"},
+          {value: "90d", label: "90 Days"}
+        ]
+      end
+
       # Formats milliseconds to human-readable duration
       #
       # @param ms [Numeric, nil] Duration in milliseconds

data/app/models/ruby_llm/agents/execution/replayable.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    class Execution
+      # Adds replay capability to execution records.
+      #
+      # Allows re-executing a previous run with the same inputs,
+      # or with tweaked parameters for A/B testing and debugging.
+      #
+      # @example Replay with same settings
+      #   run = SupportAgent.last_run
+      #   new_run = run.replay
+      #
+      # @example Replay with different model
+      #   run.replay(model: "claude-sonnet-4-6")
+      #
+      # @example Compare two models
+      #   run1 = SupportAgent.last_run
+      #   run2 = run1.replay(model: "gpt-4o-mini")
+      #   puts "Original: #{run1.total_cost} | Replay: #{run2.total_cost}"
+      #
+      module Replayable
+        extend ActiveSupport::Concern
+
+        # Re-executes this agent run with the same (or overridden) inputs.
+        #
+        # Loads the original agent class, reconstructs its parameters from
+        # the execution detail record, and executes through the full pipeline.
+        # The new execution is tracked separately and linked via metadata.
+        #
+        # @param model [String, nil] Override the model
+        # @param temperature [Float, nil] Override the temperature
+        # @param overrides [Hash] Additional parameter overrides
+        # @return [Object] The result from the new execution
+        #
+        # @raise [ReplayError] If the agent class cannot be resolved or detail is missing
+        #
+        def replay(model: nil, temperature: nil, **overrides)
+          validate_replayable!
+          agent_klass = resolve_agent_class
+          params = build_replay_params(overrides)
+
+          opts = params.merge(_replay_source_id: id)
+          opts[:model] = model if model
+          opts[:temperature] = temperature if temperature
+
+          agent_klass.call(**opts)
+        end
+
+        # Returns whether this execution can be replayed.
+        #
+        # @return [Boolean]
+        #
+        def replayable?
+          return false if agent_type.blank?
+          return false if detail.nil?
+
+          resolve_agent_class
+          true
+        rescue
+          false
+        end
+
+        # Returns all executions that are replays of this one.
+        #
+        # @return [ActiveRecord::Relation]
+        #
+        def replays
+          self.class.replays_of(id)
+        end
+
+        # Returns the original execution this was replayed from.
+        #
+        # @return [RubyLLM::Agents::Execution, nil]
+        #
+        def replay_source
+          source_id = metadata&.dig("replay_source_id")
+          return nil unless source_id
+
+          self.class.find_by(id: source_id)
+        end
+
+        # Returns whether this execution is a replay of another.
+        #
+        # @return [Boolean]
+        #
+        def replay?
+          metadata&.dig("replay_source_id").present?
+        end
+
+        private
+
+        def validate_replayable!
+          if agent_type.blank?
+            raise ReplayError, "Cannot replay: execution has no agent_type"
+          end
+
+          if detail.nil?
+            raise ReplayError,
+              "Cannot replay execution ##{id}: no detail record " \
+              "(prompts and parameters are required for replay)"
+          end
+
+          resolve_agent_class
+        end
+
+        def resolve_agent_class
+          agent_type.constantize
+        rescue NameError => e
+          raise ReplayError,
+            "Cannot replay execution ##{id}: agent class '#{agent_type}' " \
+            "not found (#{e.message})"
+        end
+
+        def build_replay_params(overrides)
+          original_params = detail.parameters || {}
+          symbolized = original_params.transform_keys(&:to_sym)
+          symbolized.merge(overrides)
+        end
+      end
+    end
+  end
+end

data/app/models/ruby_llm/agents/execution/scopes.rb

@@ -83,7 +83,10 @@ module RubyLLM
           #   Filters to a specific LLM model
           #   @param model_id [String] The model identifier
           #   @return [ActiveRecord::Relation]
-          scope :by_agent, ->(agent_type) { where(agent_type: agent_type.to_s) }
+          scope :by_agent, ->(agent_type) {
+            names = resolve_agent_names(agent_type)
+            where(agent_type: names)
+          }
           scope :by_model, ->(model_id) { where(model_id: model_id.to_s) }
 
           # @!endgroup
@@ -265,6 +268,18 @@ module RubyLLM
           scope :without_tool_calls, -> { where(tool_calls_count: 0) }
 
           # @!endgroup
+
+          # @!group Replay Scopes
+
+          # @!method replays_of(execution_id)
+          #   Returns executions that are replays of the given execution
+          #   @param execution_id [Integer, String] The source execution ID
+          #   @return [ActiveRecord::Relation]
+          scope :replays_of, ->(execution_id) {
+            metadata_value("replay_source_id", execution_id.to_s)
+          }
+
+          # @!endgroup
         end
 
         # @!group Aggregation Methods
@@ -273,6 +288,32 @@ module RubyLLM
         # They can be called on scoped relations.
 
         class_methods do
+          # Resolves all known names for an agent, including aliases
+          #
+          # Accepts a class (uses all_agent_names), or a string (looks up
+          # the class in ObjectSpace to check for aliases, falls back to
+          # the string itself).
+          #
+          # @param agent_type [Class, String] Agent class or class name
+          # @return [Array<String>] All names to query
+          def resolve_agent_names(agent_type)
+            if agent_type.is_a?(Class) && agent_type.respond_to?(:all_agent_names)
+              agent_type.all_agent_names
+            else
+              name = agent_type.to_s
+              klass = begin
+                name.constantize
+              rescue NameError
+                nil
+              end
+              if klass&.respond_to?(:all_agent_names)
+                klass.all_agent_names
+              else
+                [name]
+              end
+            end
+          end
+
           # Database-agnostic JSON metadata queries
           # These fields (fallback_reason, retryable, rate_limited, etc.) are stored
           # in the metadata JSON column rather than as direct columns.

data/app/models/ruby_llm/agents/execution.rb

@@ -49,6 +49,7 @@ module RubyLLM
       include Execution::Metrics
       include Execution::Scopes
       include Execution::Analytics
+      include Execution::Replayable
 
       # Status enum
       # - running: execution in progress
@@ -274,18 +275,20 @@ module RubyLLM
 
       # Returns real-time dashboard data for the Now Strip
       #
-      # @param range [String] Time range: "today", "7d", or "30d"
+      # @param range [String] Time range: "today", "7d", "30d", or "90d"
       # @return [Hash] Now strip metrics with period-over-period comparisons
       def self.now_strip_data(range: "today")
         current_scope = case range
         when "7d" then last_n_days(7)
         when "30d" then last_n_days(30)
+        when "90d" then last_n_days(90)
         else today
         end
 
         previous_scope = case range
         when "7d" then where(created_at: 14.days.ago.beginning_of_day..7.days.ago.beginning_of_day)
         when "30d" then where(created_at: 60.days.ago.beginning_of_day..30.days.ago.beginning_of_day)
+        when "90d" then where(created_at: 180.days.ago.beginning_of_day..90.days.ago.beginning_of_day)
         else yesterday
         end
 
@@ -320,6 +323,52 @@ module RubyLLM
         )
       end
 
+      # Returns Now Strip data for a custom date range
+      #
+      # Compares the selected range against the same-length window
+      # immediately preceding it.
+      #
+      # @param from [Date] Start date (inclusive)
+      # @param to [Date] End date (inclusive)
+      # @return [Hash] Now strip metrics with period-over-period comparisons
+      def self.now_strip_data_for_dates(from:, to:)
+        span_days = (to - from).to_i + 1
+        current_scope = where(created_at: from.beginning_of_day..to.end_of_day)
+        previous_from = from - span_days.days
+        previous_to = from - 1.day
+        previous_scope = where(created_at: previous_from.beginning_of_day..previous_to.end_of_day)
+
+        current = {
+          running: running.count,
+          success_today: current_scope.status_success.count,
+          errors_today: current_scope.status_error.count,
+          timeouts_today: current_scope.status_timeout.count,
+          cost_today: current_scope.sum(:total_cost) || 0,
+          executions_today: current_scope.count,
+          success_rate: calculate_period_success_rate(current_scope),
+          avg_duration_ms: current_scope.avg_duration&.round || 0,
+          total_tokens: current_scope.total_tokens_sum || 0
+        }
+
+        previous = {
+          success: previous_scope.status_success.count,
+          errors: previous_scope.status_error.count,
+          cost: previous_scope.sum(:total_cost) || 0,
+          avg_duration_ms: previous_scope.avg_duration&.round || 0,
+          total_tokens: previous_scope.total_tokens_sum || 0
+        }
+
+        current.merge(
+          comparisons: {
+            success_change: pct_change(previous[:success], current[:success_today]),
+            errors_change: pct_change(previous[:errors], current[:errors_today]),
+            cost_change: pct_change(previous[:cost], current[:cost_today]),
+            duration_change: pct_change(previous[:avg_duration_ms], current[:avg_duration_ms]),
+            tokens_change: pct_change(previous[:total_tokens], current[:total_tokens])
+          }
+        )
+      end
+
       # Calculates percentage change between old and new values
       #
       # @param old_val [Numeric, nil] Previous period value

data/app/models/ruby_llm/agents/tenant/budgetable.rb

@@ -125,26 +125,32 @@ module RubyLLM
 
         # Returns the effective per-agent daily limit
         #
+        # Checks the current name and all aliases for matching limits.
+        #
         # @param agent_type [String] The agent class name
         # @return [Float, nil] The limit or nil if not set
         def effective_per_agent_daily(agent_type)
-          limit = per_agent_daily&.dig(agent_type)
+          names = resolve_agent_names(agent_type)
+          limit = names.lazy.filter_map { |n| per_agent_daily&.dig(n) }.first
           return limit if limit.present?
           return nil unless inherit_global_defaults
 
-          global_config&.dig(:per_agent_daily, agent_type)
+          names.lazy.filter_map { |n| global_config&.dig(:per_agent_daily, n) }.first
         end
 
         # Returns the effective per-agent monthly limit
         #
+        # Checks the current name and all aliases for matching limits.
+        #
         # @param agent_type [String] The agent class name
         # @return [Float, nil] The limit or nil if not set
         def effective_per_agent_monthly(agent_type)
-          limit = per_agent_monthly&.dig(agent_type)
+          names = resolve_agent_names(agent_type)
+          limit = names.lazy.filter_map { |n| per_agent_monthly&.dig(n) }.first
           return limit if limit.present?
           return nil unless inherit_global_defaults
 
-          global_config&.dig(:per_agent_monthly, agent_type)
+          names.lazy.filter_map { |n| global_config&.dig(:per_agent_monthly, n) }.first
         end
 
         # Budget status checks
@@ -352,6 +358,24 @@ module RubyLLM
           RubyLLM::Agents.configuration.budgets
         end
 
+        # Resolves all known names for an agent (current name + aliases)
+        #
+        # @param agent_type [String] The agent class name
+        # @return [Array<String>] All names to check
+        def resolve_agent_names(agent_type)
+          name = agent_type.to_s
+          klass = begin
+            name.constantize
+          rescue NameError
+            nil
+          end
+          if klass&.respond_to?(:all_agent_names)
+            klass.all_agent_names
+          else
+            [name]
+          end
+        end
+
         # Merges per-agent daily limits with global defaults
         #
         # @return [Hash]