ruby_llm-agents 3.7.2 → 3.8.0

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

@@ -269,11 +269,14 @@ module RubyLLM
       # Returns whether this execution made tool calls
       #
       # @return [Boolean] true if tool calls were made
-      def has_tool_calls?
+      def tool_calls?
         tool_calls_count.to_i > 0
       end
+      alias_method :has_tool_calls?, :tool_calls?
 
       # Returns real-time dashboard data for the Now Strip
+      # Optimized: 3 queries (current aggregate + previous aggregate + running count)
+      # instead of ~15 individual count/sum/average queries.
       #
       # @param range [String] Time range: "today", "7d", "30d", or "90d"
       # @return [Hash] Now strip metrics with period-over-period comparisons
@@ -292,38 +295,31 @@ module RubyLLM
         else yesterday
         end
 
-        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
-        }
+        curr = aggregate_period_stats(current_scope)
+        prev = aggregate_period_stats(previous_scope)
 
-        current.merge(
+        {
+          running: running.count,
+          success_today: curr[:success],
+          errors_today: curr[:errors],
+          timeouts_today: curr[:timeouts],
+          cost_today: curr[:cost],
+          executions_today: curr[:total],
+          success_rate: curr[:success_rate],
+          avg_duration_ms: curr[:avg_duration_ms],
+          total_tokens: curr[:tokens],
           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])
+            success_change: pct_change(prev[:success], curr[:success]),
+            errors_change: pct_change(prev[:errors], curr[:errors]),
+            cost_change: pct_change(prev[:cost], curr[:cost]),
+            duration_change: pct_change(prev[:avg_duration_ms], curr[:avg_duration_ms]),
+            tokens_change: pct_change(prev[:tokens], curr[:tokens])
           }
-        )
+        }
       end
 
       # Returns Now Strip data for a custom date range
+      # Optimized: 3 queries instead of ~15.
       #
       # Compares the selected range against the same-length window
       # immediately preceding it.
@@ -338,35 +334,27 @@ module RubyLLM
         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
-        }
+        curr = aggregate_period_stats(current_scope)
+        prev = aggregate_period_stats(previous_scope)
 
-        current.merge(
+        {
+          running: running.count,
+          success_today: curr[:success],
+          errors_today: curr[:errors],
+          timeouts_today: curr[:timeouts],
+          cost_today: curr[:cost],
+          executions_today: curr[:total],
+          success_rate: curr[:success_rate],
+          avg_duration_ms: curr[:avg_duration_ms],
+          total_tokens: curr[:tokens],
           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])
+            success_change: pct_change(prev[:success], curr[:success]),
+            errors_change: pct_change(prev[:errors], curr[:errors]),
+            cost_change: pct_change(prev[:cost], curr[:cost]),
+            duration_change: pct_change(prev[:avg_duration_ms], curr[:avg_duration_ms]),
+            tokens_change: pct_change(prev[:tokens], curr[:tokens])
           }
-        )
+        }
       end
 
       # Calculates percentage change between old and new values
@@ -390,6 +378,39 @@ module RubyLLM
         (scope.successful.count.to_f / total * 100).round(1)
       end
 
+      # Returns aggregate stats for a scope in a single query using conditional aggregation
+      #
+      # Replaces ~9 individual count/sum/average queries with one SQL query.
+      #
+      # @param scope [ActiveRecord::Relation] Time-filtered scope
+      # @return [Hash] Aggregated metrics
+      def self.aggregate_period_stats(scope)
+        total, success, errors, timeouts, cost, avg_dur, tokens = scope.pick(
+          Arel.sql("COUNT(*)"),
+          Arel.sql("SUM(CASE WHEN status = 'success' THEN 1 ELSE 0 END)"),
+          Arel.sql("SUM(CASE WHEN status = 'error' THEN 1 ELSE 0 END)"),
+          Arel.sql("SUM(CASE WHEN status = 'timeout' THEN 1 ELSE 0 END)"),
+          Arel.sql("COALESCE(SUM(total_cost), 0)"),
+          Arel.sql("AVG(duration_ms)"),
+          Arel.sql("COALESCE(SUM(total_tokens), 0)")
+        )
+
+        total = total.to_i
+        success = success.to_i
+
+        {
+          total: total,
+          success: success,
+          errors: errors.to_i,
+          timeouts: timeouts.to_i,
+          cost: cost.to_f,
+          avg_duration_ms: avg_dur.to_i,
+          tokens: tokens.to_i,
+          success_rate: (total > 0) ? (success.to_f / total * 100).round(1) : 0.0
+        }
+      end
+      private_class_method :aggregate_period_stats
+
       private
 
       # Calculates and sets total_tokens from input and output
@@ -420,7 +441,8 @@ module RubyLLM
         return nil unless lookup_model_id
 
         RubyLLM::Models.find(lookup_model_id)
-      rescue
+      rescue => e
+        Rails.logger.debug("[RubyLLM::Agents] Model lookup failed for #{lookup_model_id}: #{e.message}") if defined?(Rails) && Rails.logger
         nil
       end
     end

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

@@ -13,6 +13,8 @@ module RubyLLM
       self.table_name = "ruby_llm_agents_execution_details"
 
       belongs_to :execution, class_name: "RubyLLM::Agents::Execution"
+
+      validates :execution_id, presence: true
     end
   end
 end

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

@@ -53,6 +53,45 @@ module RubyLLM
       scope :linked, -> { where.not(tenant_record_type: nil) }
       scope :unlinked, -> { where(tenant_record_type: nil) }
 
+      # Returns top tenants by monthly spend for dashboard display
+      #
+      # Ensures counter resets are current before returning data.
+      #
+      # @param limit [Integer] Max tenants to return
+      # @return [Array<Hash>, nil] Tenant spend data or nil if none
+      def self.top_by_spend(limit: 5)
+        return nil unless table_exists?
+
+        tenants = active
+          .where("monthly_cost_spent > 0 OR monthly_executions_count > 0")
+          .order(monthly_cost_spent: :desc)
+          .limit(limit)
+
+        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
+
       # Find tenant for given record or ID
       #
       # Supports multiple lookup strategies:

data/app/services/ruby_llm/agents/agent_registry.rb

@@ -54,8 +54,106 @@ module RubyLLM
           end
         end
 
+        # Extracts full configuration for an agent class
+        #
+        # Combines base config with type-specific config for display.
+        #
+        # @param agent_class [Class] The agent class
+        # @return [Hash] Configuration hash
+        def config_for(agent_class)
+          return {} unless agent_class
+
+          base = {
+            model: safe_call(agent_class, :model),
+            version: safe_call(agent_class, :version),
+            description: safe_call(agent_class, :description)
+          }
+
+          type = detect_agent_type(agent_class)
+          base.merge(type_config_for(agent_class, type))
+        end
+
         private
 
+        # Extracts type-specific configuration
+        #
+        # @param agent_class [Class] The agent class
+        # @param type [String] The detected agent type
+        # @return [Hash] Type-specific config
+        def type_config_for(agent_class, type)
+          case type
+          when "embedder"
+            {
+              dimensions: safe_call(agent_class, :dimensions),
+              batch_size: safe_call(agent_class, :batch_size),
+              cache_enabled: safe_call(agent_class, :cache_enabled?) || false,
+              cache_ttl: safe_call(agent_class, :cache_ttl)
+            }
+          when "speaker"
+            {
+              provider: safe_call(agent_class, :provider),
+              voice: safe_call(agent_class, :voice),
+              voice_id: safe_call(agent_class, :voice_id),
+              speed: safe_call(agent_class, :speed),
+              output_format: safe_call(agent_class, :output_format),
+              streaming: safe_call(agent_class, :streaming?),
+              ssml_enabled: safe_call(agent_class, :ssml_enabled?),
+              cache_enabled: safe_call(agent_class, :cache_enabled?) || false,
+              cache_ttl: safe_call(agent_class, :cache_ttl)
+            }
+          when "transcriber"
+            {
+              language: safe_call(agent_class, :language),
+              output_format: safe_call(agent_class, :output_format),
+              include_timestamps: safe_call(agent_class, :include_timestamps),
+              cache_enabled: safe_call(agent_class, :cache_enabled?) || false,
+              cache_ttl: safe_call(agent_class, :cache_ttl),
+              fallback_models: safe_call(agent_class, :fallback_models)
+            }
+          when "image_generator"
+            {
+              size: safe_call(agent_class, :size),
+              quality: safe_call(agent_class, :quality),
+              style: safe_call(agent_class, :style),
+              content_policy: safe_call(agent_class, :content_policy),
+              template: safe_call(agent_class, :template_string),
+              negative_prompt: safe_call(agent_class, :negative_prompt),
+              seed: safe_call(agent_class, :seed),
+              guidance_scale: safe_call(agent_class, :guidance_scale),
+              steps: safe_call(agent_class, :steps),
+              cache_enabled: safe_call(agent_class, :cache_enabled?) || false,
+              cache_ttl: safe_call(agent_class, :cache_ttl)
+            }
+          when "router"
+            routes = safe_call(agent_class, :routes) || {}
+            {
+              temperature: safe_call(agent_class, :temperature),
+              timeout: safe_call(agent_class, :timeout),
+              cache_enabled: safe_call(agent_class, :cache_enabled?) || false,
+              cache_ttl: safe_call(agent_class, :cache_ttl),
+              default_route: safe_call(agent_class, :default_route_name),
+              routes: routes.transform_values { |v| v[:description] },
+              route_count: routes.size,
+              retries: safe_call(agent_class, :retries),
+              fallback_models: safe_call(agent_class, :fallback_models),
+              total_timeout: safe_call(agent_class, :total_timeout),
+              circuit_breaker: safe_call(agent_class, :circuit_breaker_config)
+            }
+          else # base agent
+            {
+              temperature: safe_call(agent_class, :temperature),
+              timeout: safe_call(agent_class, :timeout),
+              cache_enabled: safe_call(agent_class, :cache_enabled?) || false,
+              cache_ttl: safe_call(agent_class, :cache_ttl),
+              params: safe_call(agent_class, :params) || {},
+              retries: safe_call(agent_class, :retries),
+              fallback_models: safe_call(agent_class, :fallback_models),
+              total_timeout: safe_call(agent_class, :total_timeout),
+              circuit_breaker: safe_call(agent_class, :circuit_breaker_config)
+            }
+          end
+        end
+
         # Finds agent classes from the file system
         #
         # @return [Array<String>] Agent class names

data/app/views/ruby_llm/agents/executions/_list.html.erb

@@ -2,26 +2,12 @@
 <% show_tenant_column = tenant_filter_enabled? && current_tenant_id.blank? %>
 
 <%
-  # Inline sort helper
+  # Sort params for the sort_header_link helper
   sort_column = @sort_params[:column]
   sort_direction = @sort_params[:direction]
 
-  sort_link = ->(column, label, align: "left", extra_class: "") {
-    is_active = column == sort_column
-    next_dir = is_active && sort_direction == "asc" ? "desc" : "asc"
-    url = url_for(request.query_parameters.merge(sort: column, direction: next_dir, page: 1))
-
-    arrow = if is_active && sort_direction == "asc"
-              raw('<svg class="w-2.5 h-2.5 inline" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M5 15l7-7 7 7"/></svg>')
-            elsif is_active
-              raw('<svg class="w-2.5 h-2.5 inline" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M19 9l-7 7-7-7"/></svg>')
-            else
-              ""
-            end
-
-    active_class = is_active ? "text-gray-700 dark:text-gray-300" : ""
-
-    raw(%(<a href="#{url}" class="group inline-flex items-center gap-0.5 hover:text-gray-700 dark:hover:text-gray-300 #{active_class} #{extra_class}"><span>#{label}</span><span class="#{is_active ? 'opacity-100' : 'opacity-0 group-hover:opacity-50'} transition-opacity">#{arrow}</span></a>))
+  sort_link = ->(column, label, extra_class: "") {
+    sort_header_link(column, label, current_column: sort_column, current_direction: sort_direction, extra_class: extra_class)
   }
 %>
 

data/lib/generators/ruby_llm_agents/templates/add_dashboard_performance_indexes_migration.rb.tt

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# Migration to add composite indexes for dashboard query performance
+#
+# These indexes optimize the most frequent dashboard queries:
+# - [status, created_at]: now_strip_data conditional counts, error spike detection, top_errors
+# - [model_id, status]: model_stats GROUP BY with success count
+# - [cache_hit, created_at]: cache_savings queries
+class AddDashboardPerformanceIndexes < ActiveRecord::Migration<%= migration_version %>
+  def change
+    add_index :ruby_llm_agents_executions, [:status, :created_at],
+              name: "idx_executions_status_created_at",
+              if_not_exists: true
+
+    add_index :ruby_llm_agents_executions, [:model_id, :status],
+              name: "idx_executions_model_id_status",
+              if_not_exists: true
+
+    add_index :ruby_llm_agents_executions, [:cache_hit, :created_at],
+              name: "idx_executions_cache_hit_created_at",
+              if_not_exists: true
+  end
+end

data/lib/generators/ruby_llm_agents/templates/migration.rb.tt

@@ -77,6 +77,9 @@ class CreateRubyLLMAgentsExecutions < ActiveRecord::Migration<%= migration_versi
     add_index :ruby_llm_agents_executions, :request_id
     add_index :ruby_llm_agents_executions, :parent_execution_id
     add_index :ruby_llm_agents_executions, :root_execution_id
+    add_index :ruby_llm_agents_executions, [:status, :created_at]
+    add_index :ruby_llm_agents_executions, [:model_id, :status]
+    add_index :ruby_llm_agents_executions, [:cache_hit, :created_at]
 
     # Foreign keys for execution hierarchy
     add_foreign_key :ruby_llm_agents_executions, :ruby_llm_agents_executions,

data/lib/generators/ruby_llm_agents/upgrade_generator.rb

@@ -98,6 +98,25 @@ module RubyLlmAgents
       )
     end
 
+    # Add dashboard performance indexes
+    def create_add_dashboard_performance_indexes_migration
+      unless table_exists?(:ruby_llm_agents_executions)
+        say_status :skip, "executions table does not exist yet", :yellow
+        return
+      end
+
+      if index_exists?(:ruby_llm_agents_executions, [:status, :created_at])
+        say_status :skip, "dashboard performance indexes already exist", :yellow
+        return
+      end
+
+      say_status :upgrade, "Adding dashboard performance indexes", :blue
+      migration_template(
+        "add_dashboard_performance_indexes_migration.rb.tt",
+        File.join(db_migrate_path, "add_dashboard_performance_indexes.rb")
+      )
+    end
+
     def suggest_config_consolidation
       ruby_llm_initializer = File.join(destination_root, "config/initializers/ruby_llm.rb")
       agents_initializer = File.join(destination_root, "config/initializers/ruby_llm_agents.rb")
@@ -192,5 +211,11 @@ module RubyLlmAgents
     rescue
       false
     end
+
+    def index_exists?(table, columns)
+      ActiveRecord::Base.connection.index_exists?(table, columns)
+    rescue
+      false
+    end
   end
 end

data/lib/ruby_llm/agents/base_agent.rb

@@ -731,7 +731,13 @@ module RubyLLM
       # @return [RubyLLM::Chat] Configured chat client
       def build_client(context = nil)
         effective_model = context&.model || model
-        client = RubyLLM.chat(model: effective_model)
+        chat_opts = {model: effective_model}
+
+        # Pass scoped RubyLLM context for thread-safe per-tenant API keys
+        llm_ctx = context&.llm
+        chat_opts[:context] = llm_ctx if llm_ctx.is_a?(RubyLLM::Context)
+
+        client = RubyLLM.chat(**chat_opts)
           .with_temperature(temperature)
 
         client = client.with_instructions(system_prompt) if system_prompt

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

@@ -349,6 +349,7 @@ module RubyLLM
         perplexity_api_key
         xai_api_key
         gpustack_api_key
+        inception_api_key
         openai_api_base
         openai_organization_id
         openai_project_id

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

@@ -2,31 +2,27 @@
 
 module RubyLLM
   module Agents
-    # Instrumentation concern for tracking agent executions
+    # @deprecated This module is deprecated and will be removed in a future version.
+    #   All agents now use {Pipeline::Middleware::Instrumentation} automatically
+    #   via the middleware pipeline. This module is no longer included in any
+    #   production class. It remains only for backward compatibility with code
+    #   that explicitly includes it.
     #
-    # Provides comprehensive execution tracking including:
-    # - Timing metrics (started_at, completed_at, duration_ms)
-    # - Token usage tracking (input, output, cached)
-    # - Cost calculation via RubyLLM pricing data
-    # - Error and timeout handling with status tracking
-    # - Safe parameter sanitization for logging
-    #
-    # Included automatically in {RubyLLM::Agents::Base}.
-    #
-    # @example Adding custom metadata to executions
-    #   class MyAgent < ApplicationAgent
-    #     def metadata
-    #       { user_id: Current.user&.id, request_id: request.uuid }
-    #     end
-    #   end
-    #
-    # @see RubyLLM::Agents::Execution
-    # @see RubyLLM::Agents::ExecutionLoggerJob
+    # @see Pipeline::Middleware::Instrumentation
     # @api private
     module Instrumentation
       extend ActiveSupport::Concern
 
       included do
+        if defined?(RubyLLM::Agents::Deprecations)
+          RubyLLM::Agents::Deprecations.warn(
+            "RubyLLM::Agents::Instrumentation is deprecated. " \
+            "All agents now use Pipeline::Middleware::Instrumentation automatically. " \
+            "Remove `include RubyLLM::Agents::Instrumentation` from #{name || "your class"}.",
+            caller
+          )
+        end
+
         # @!attribute [rw] execution_id
         #   The ID of the current execution record
         #   @return [Integer, nil]

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.7.2"
+    VERSION = "3.8.0"
   end
 end

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

@@ -83,8 +83,8 @@ module RubyLLM
         # @return [void]
         def emit_notification(event, payload)
           ActiveSupport::Notifications.instrument("ruby_llm_agents.alert.#{event}", payload)
-        rescue
-          # Ignore notification failures
+        rescue => e
+          Rails.logger.debug("[RubyLLM::Agents::AlertManager] Notification failed: #{e.message}") if defined?(Rails) && Rails.logger
         end
 
         # Stores the alert in cache for dashboard display
@@ -106,8 +106,8 @@ module RubyLLM
           alerts = alerts.first(50)
 
           cache.write(key, alerts, expires_in: 24.hours)
-        rescue
-          # Ignore cache failures
+        rescue => e
+          Rails.logger.debug("[RubyLLM::Agents::AlertManager] Cache store failed: #{e.message}") if defined?(Rails) && Rails.logger
         end
 
         # Formats a human-readable message for the event

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

@@ -44,7 +44,7 @@ module RubyLLM
         # @raise [Reliability::BudgetExceededError] If hard cap is exceeded
         # @return [void]
         def check_budget!(agent_type, tenant_id: nil, tenant_config: nil)
-          tenant_id = Budget::ConfigResolver.resolve_tenant_id(tenant_id)
+          tenant_id = resolve_tid(tenant_id)
           budget_config = Budget::ConfigResolver.resolve_budget_config(tenant_id, runtime_config: tenant_config)
 
           return unless budget_config[:enabled]
@@ -61,7 +61,7 @@ module RubyLLM
         # @raise [Reliability::BudgetExceededError] If hard cap is exceeded
         # @return [void]
         def check_token_budget!(agent_type, tenant_id: nil, tenant_config: nil)
-          tenant_id = Budget::ConfigResolver.resolve_tenant_id(tenant_id)
+          tenant_id = resolve_tid(tenant_id)
           budget_config = Budget::ConfigResolver.resolve_budget_config(tenant_id, runtime_config: tenant_config)
 
           return unless budget_config[:enabled]
@@ -80,7 +80,7 @@ module RubyLLM
         def record_spend!(agent_type, amount, tenant_id: nil, tenant_config: nil)
           return if amount.nil? || amount <= 0
 
-          tenant_id = Budget::ConfigResolver.resolve_tenant_id(tenant_id)
+          tenant_id = resolve_tid(tenant_id)
           budget_config = Budget::ConfigResolver.resolve_budget_config(tenant_id, runtime_config: tenant_config)
 
           Budget::SpendRecorder.record_spend!(agent_type, amount, tenant_id: tenant_id, budget_config: budget_config)
@@ -96,7 +96,7 @@ module RubyLLM
         def record_tokens!(agent_type, tokens, tenant_id: nil, tenant_config: nil)
           return if tokens.nil? || tokens <= 0
 
-          tenant_id = Budget::ConfigResolver.resolve_tenant_id(tenant_id)
+          tenant_id = resolve_tid(tenant_id)
           budget_config = Budget::ConfigResolver.resolve_budget_config(tenant_id, runtime_config: tenant_config)
 
           Budget::SpendRecorder.record_tokens!(agent_type, tokens, tenant_id: tenant_id, budget_config: budget_config)
@@ -110,7 +110,7 @@ module RubyLLM
         # @param tenant_id [String, nil] Optional tenant identifier (uses resolver if not provided)
         # @return [Float] Current spend in USD
         def current_spend(scope, period, agent_type: nil, tenant_id: nil)
-          tenant_id = Budget::ConfigResolver.resolve_tenant_id(tenant_id)
+          tenant_id = resolve_tid(tenant_id)
           Budget::BudgetQuery.current_spend(scope, period, agent_type: agent_type, tenant_id: tenant_id)
         end
 
@@ -120,7 +120,7 @@ module RubyLLM
         # @param tenant_id [String, nil] Optional tenant identifier (uses resolver if not provided)
         # @return [Integer] Current token usage
         def current_tokens(period, tenant_id: nil)
-          tenant_id = Budget::ConfigResolver.resolve_tenant_id(tenant_id)
+          tenant_id = resolve_tid(tenant_id)
           Budget::BudgetQuery.current_tokens(period, tenant_id: tenant_id)
         end
 
@@ -132,7 +132,7 @@ module RubyLLM
         # @param tenant_id [String, nil] Optional tenant identifier (uses resolver if not provided)
         # @return [Float, nil] Remaining budget in USD, or nil if no limit configured
         def remaining_budget(scope, period, agent_type: nil, tenant_id: nil)
-          tenant_id = Budget::ConfigResolver.resolve_tenant_id(tenant_id)
+          tenant_id = resolve_tid(tenant_id)
           budget_config = Budget::ConfigResolver.resolve_budget_config(tenant_id)
 
           Budget::BudgetQuery.remaining_budget(scope, period, agent_type: agent_type, tenant_id: tenant_id, budget_config: budget_config)
@@ -144,7 +144,7 @@ module RubyLLM
         # @param tenant_id [String, nil] Optional tenant identifier (uses resolver if not provided)
         # @return [Integer, nil] Remaining token budget, or nil if no limit configured
         def remaining_token_budget(period, tenant_id: nil)
-          tenant_id = Budget::ConfigResolver.resolve_tenant_id(tenant_id)
+          tenant_id = resolve_tid(tenant_id)
           budget_config = Budget::ConfigResolver.resolve_budget_config(tenant_id)
 
           Budget::BudgetQuery.remaining_token_budget(period, tenant_id: tenant_id, budget_config: budget_config)
@@ -156,7 +156,7 @@ module RubyLLM
         # @param tenant_id [String, nil] Optional tenant identifier (uses resolver if not provided)
         # @return [Hash] Budget status information
         def status(agent_type: nil, tenant_id: nil)
-          tenant_id = Budget::ConfigResolver.resolve_tenant_id(tenant_id)
+          tenant_id = resolve_tid(tenant_id)
           budget_config = Budget::ConfigResolver.resolve_budget_config(tenant_id)
 
           Budget::BudgetQuery.status(agent_type: agent_type, tenant_id: tenant_id, budget_config: budget_config)
@@ -167,7 +167,7 @@ module RubyLLM
         # @param tenant_id [String, nil] Optional tenant identifier (uses resolver if not provided)
         # @return [Hash, nil] Forecast information
         def calculate_forecast(tenant_id: nil)
-          tenant_id = Budget::ConfigResolver.resolve_tenant_id(tenant_id)
+          tenant_id = resolve_tid(tenant_id)
           budget_config = Budget::ConfigResolver.resolve_budget_config(tenant_id)
 
           Budget::Forecaster.calculate_forecast(tenant_id: tenant_id, budget_config: budget_config)
@@ -178,7 +178,7 @@ module RubyLLM
         # @param tenant_id [String, nil] Optional tenant identifier to reset only that tenant's counters
         # @return [void]
         def reset!(tenant_id: nil)
-          tenant_id = Budget::ConfigResolver.resolve_tenant_id(tenant_id)
+          tenant_id = resolve_tid(tenant_id)
           tenant_part = Budget::SpendRecorder.tenant_key_part(tenant_id)
           today = Budget::SpendRecorder.date_key_part(:daily)
           month = Budget::SpendRecorder.date_key_part(:monthly)
@@ -192,6 +192,14 @@ module RubyLLM
 
         private
 
+        # Resolves tenant ID, falling back to the configured resolver
+        #
+        # @param tenant_id [String, nil] Explicit tenant ID or nil
+        # @return [String, nil] Resolved tenant ID
+        def resolve_tid(tenant_id)
+          Budget::ConfigResolver.resolve_tenant_id(tenant_id)
+        end
+
         # Checks budget limits and raises error if exceeded
         #
         # @param agent_type [String] The agent class name