ruby_llm-agents 3.15.0 → 3.16.0

data/app/views/ruby_llm/agents/shared/query_timeout.html.erb

@@ -0,0 +1,18 @@
+<div class="flex items-center gap-3 mb-6">
+  <span class="text-[10px] font-medium text-gray-400 dark:text-gray-600 uppercase tracking-widest font-mono">query timed out</span>
+  <div class="flex-1 border-t border-gray-200 dark:border-gray-800"></div>
+</div>
+
+<div class="font-mono text-xs space-y-3" role="alert">
+  <p class="text-gray-900 dark:text-gray-100">
+    This view needed more than <%= @query_timeout %>s of database time, so the query was cancelled.
+  </p>
+  <p class="text-gray-500 dark:text-gray-400">
+    It aggregates every execution in the selected range. Try a shorter time range or a narrower filter.
+    The limit is <code class="text-gray-700 dark:text-gray-300">config.dashboard_query_timeout</code>.
+  </p>
+  <p>
+    <%= link_to "← back to dashboard", ruby_llm_agents.root_path,
+        class: "text-gray-400 dark:text-gray-500 hover:text-gray-700 dark:hover:text-gray-300 focus:outline-none focus:underline" %>
+  </p>
+</div>

data/app/views/ruby_llm/agents/system_config/show.html.erb

@@ -106,6 +106,10 @@
     <span class="w-36 flex-shrink-0 text-gray-500 dark:text-gray-400">recent limit</span>
     <span class="text-gray-900 dark:text-gray-200"><%= @config.recent_executions_limit %></span>
   </div>
+  <div class="flex items-center gap-3 py-0.5">
+    <span class="w-36 flex-shrink-0 text-gray-500 dark:text-gray-400">query timeout</span>
+    <span class="text-gray-900 dark:text-gray-200"><%= @config.dashboard_query_timeout ? "#{@config.dashboard_query_timeout}s" : "off" %></span>
+  </div>
   <div class="flex items-center gap-3 py-0.5">
     <span class="w-36 flex-shrink-0 text-gray-500 dark:text-gray-400">parent controller</span>
     <span class="text-gray-900 dark:text-gray-200"><%= @config.dashboard_parent_controller %></span>

data/app/views/ruby_llm/agents/tenants/index.html.erb

@@ -51,7 +51,7 @@
         class: "w-20 flex-shrink-0 text-right hidden sm:block hover:text-gray-600 dark:hover:text-gray-300 #{sort_active.call('monthly_limit')}" %>
     <%= link_to "enforcement#{sort_arrow.call('enforcement')}".html_safe, sort_url.call("enforcement"),
         class: "w-16 flex-shrink-0 hidden md:block hover:text-gray-600 dark:hover:text-gray-300 #{sort_active.call('enforcement')}" %>
-    <span class="w-16 flex-shrink-0 text-right hidden md:block">cost</span>
+    <span class="w-16 flex-shrink-0 text-right hidden md:block" title="Cost this month">cost/mo</span>
     <span class="w-24 flex-shrink-0 text-right">last run</span>
   </div>
 

data/app/views/ruby_llm/agents/tenants/show.html.erb

@@ -8,7 +8,7 @@
   total_executions = @usage_stats[:total_executions]
   total_cost = @usage_stats[:total_cost]
   total_tokens = @usage_stats[:total_tokens]
-  success_count = @tenant.executions.where(status: "success").count
+  success_count = @usage_stats[:success_count]
   success_rate = total_executions > 0 ? (success_count.to_f / total_executions * 100).round : 100
 
   has_any_limit = @tenant.effective_daily_limit || @tenant.effective_monthly_limit ||
@@ -64,6 +64,7 @@
   <!-- Right: stats -->
   <div class="flex-shrink-0 text-right font-mono text-xs text-gray-400 dark:text-gray-500 space-y-1">
     <div class="flex items-center justify-end gap-x-4">
+      <span class="text-gray-300 dark:text-gray-700">this month</span>
       <span><span class="text-gray-800 dark:text-gray-200"><%= number_with_delimiter(total_executions) %></span> runs</span>
       <span class="<%= success_rate >= 95 ? 'text-green-500' : success_rate >= 80 ? 'text-yellow-500' : 'text-red-500' %>"><%= success_rate %>% ok</span>
       <span><span class="text-gray-800 dark:text-gray-200">$<%= number_with_precision(total_cost, precision: 4) %></span> cost</span>
@@ -127,10 +128,10 @@
   <% if @error_count > 0 %>
     <div class="mt-3 font-mono text-xs text-gray-500 dark:text-gray-400">
       <span class="text-red-500">$<%= number_with_precision(@error_cost, precision: 4) %></span>
-      wasted on <span class="text-red-500"><%= number_with_delimiter(@error_count) %></span> failed executions
+      wasted on <span class="text-red-500"><%= number_with_delimiter(@error_count) %></span> failed executions this month
       <% error_pct = total_cost.to_f > 0 ? (@error_cost.to_f / total_cost * 100).round(1) : 0 %>
       <% if error_pct > 0 %>
-        (<%= error_pct %>% of total cost)
+        (<%= error_pct %>% of this month's cost)
       <% end %>
     </div>
   <% end %>
@@ -321,7 +322,7 @@
 <% if @usage_by_agent.present? %>
   <!-- ── usage by agent ──────────────────── -->
   <div class="flex items-center gap-3 mt-6 mb-3">
-    <span class="text-[10px] font-medium text-gray-400 dark:text-gray-600 uppercase tracking-widest font-mono">usage by agent</span>
+    <span class="text-[10px] font-medium text-gray-400 dark:text-gray-600 uppercase tracking-widest font-mono">usage by agent &middot; this month</span>
     <div class="flex-1 border-t border-gray-200 dark:border-gray-800"></div>
   </div>
 
@@ -359,7 +360,7 @@
 <% if @usage_by_model.present? %>
   <!-- ── usage by model ──────────────────── -->
   <div class="flex items-center gap-3 mt-6 mb-3">
-    <span class="text-[10px] font-medium text-gray-400 dark:text-gray-600 uppercase tracking-widest font-mono">usage by model</span>
+    <span class="text-[10px] font-medium text-gray-400 dark:text-gray-600 uppercase tracking-widest font-mono">usage by model &middot; this month</span>
     <div class="flex-1 border-t border-gray-200 dark:border-gray-800"></div>
   </div>
 

data/config/routes.rb

@@ -2,7 +2,7 @@
 
 RubyLLM::Agents::Engine.routes.draw do
   root to: "dashboard#index"
-  get "chart_data", to: "dashboard#chart_data"
+  get "chart_data", to: "dashboard#chart_data", defaults: {format: :json}
 
   resources :agents, only: [:index, :show, :update] do
     member do
@@ -26,6 +26,6 @@ RubyLLM::Agents::Engine.routes.draw do
   end
 
   get "analytics", to: "analytics#index", as: :analytics
-  get "analytics/chart_data", to: "analytics#chart_data", as: :analytics_chart_data
+  get "analytics/chart_data", to: "analytics#chart_data", as: :analytics_chart_data, defaults: {format: :json}
   resource :system_config, only: [:show], controller: "system_config"
 end

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+# Migration to add the covering index behind the dashboard's aggregate queries
+#
+# Dashboard, analytics and agent stats all aggregate executions over a time
+# range, reading a handful of narrow columns from each row. Fetching those
+# rows from the table drags the wide ones along (metadata JSON, in practice
+# most of each row), so the cost of every figure grows with the size of the
+# range: seconds for 30 days on a table with millions of executions.
+#
+# This index stores the aggregated columns next to created_at, so those
+# queries are answered from the index alone. PostgreSQL keeps them out of the
+# key with INCLUDE; SQLite takes them as trailing key columns.
+#
+# The index is built CONCURRENTLY on PostgreSQL so executions keep being
+# recorded while it builds. On a large table that takes a while; an
+# interrupted build leaves an invalid index behind, which re-running this
+# migration replaces.
+class AddExecutionsAnalyticsIndex < ActiveRecord::Migration<%= migration_version %>
+  disable_ddl_transaction!
+
+  TABLE = :ruby_llm_agents_executions
+  INDEX = "idx_executions_analytics"
+  COVERED = %i[
+    agent_type model_id chosen_model_id status error_class tenant_id parent_execution_id
+    total_cost total_tokens input_tokens output_tokens duration_ms cache_hit streaming
+  ].freeze
+
+  def up
+    covered = COVERED.select { |column| column_exists?(TABLE, column) }
+
+    case connection.adapter_name.downcase
+    when /postg/
+      execute "DROP INDEX CONCURRENTLY IF EXISTS #{INDEX}"
+      execute "CREATE INDEX CONCURRENTLY #{INDEX} ON #{TABLE} (created_at) INCLUDE (#{covered.join(", ")})"
+    when /sqlite/
+      add_index TABLE, [:created_at, *covered], name: INDEX, if_not_exists: true
+    else
+      say "Skipping #{INDEX}: covering index is only defined for PostgreSQL and SQLite"
+    end
+  end
+
+  def down
+    if connection.adapter_name.downcase.include?("postg")
+      execute "DROP INDEX CONCURRENTLY IF EXISTS #{INDEX}"
+    else
+      remove_index TABLE, name: INDEX, if_exists: true
+    end
+  end
+end

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

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# Migration to add the index behind the executions dashboard list
+#
+# The list page runs `WHERE parent_execution_id IS NULL ORDER BY created_at DESC`
+# plus a COUNT over the same predicate. With only the single-column
+# parent_execution_id and created_at indexes available, the planner has to pick
+# one and filter the rest, which degrades to a sequential scan once child
+# executions make up a meaningful share of the table.
+class AddRootExecutionListIndex < ActiveRecord::Migration<%= migration_version %>
+  def change
+    add_index :ruby_llm_agents_executions, [:parent_execution_id, :created_at],
+              name: "idx_executions_parent_created_at",
+              if_not_exists: true
+  end
+end

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

@@ -132,6 +132,11 @@ RubyLLM::Agents.configure do |config|
   # Number of recent executions shown on the dashboard home
   # config.recent_executions_limit = 10
 
+  # Seconds a single dashboard query may run before the database cancels it
+  # (PostgreSQL only). Keeps a wide time range on a large executions table from
+  # tying up a web worker and the database; nil disables it.
+  # config.dashboard_query_timeout = 5
+
   # ============================================
   # Reliability Defaults
   # ============================================

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

@@ -76,11 +76,37 @@ class CreateRubyLLMAgentsExecutions < ActiveRecord::Migration<%= migration_versi
     add_index :ruby_llm_agents_executions, :trace_id
     add_index :ruby_llm_agents_executions, :request_id
     add_index :ruby_llm_agents_executions, :parent_execution_id
+    add_index :ruby_llm_agents_executions, [:parent_execution_id, :created_at]
     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]
 
+    # Covering index behind the dashboard's aggregate queries. They read a
+    # time range and only these columns, so with this index they are answered
+    # without fetching the (much wider) table rows. PostgreSQL keeps the extra
+    # columns out of the key with INCLUDE; SQLite takes them as key columns.
+    analytics_columns = %w[
+      agent_type model_id chosen_model_id status error_class tenant_id parent_execution_id
+      total_cost total_tokens input_tokens output_tokens duration_ms cache_hit streaming
+    ]
+    case connection.adapter_name.downcase
+    when /postg/
+      reversible do |dir|
+        dir.up do
+          execute "CREATE INDEX idx_executions_analytics ON ruby_llm_agents_executions " \
+                  "(created_at) INCLUDE (#{analytics_columns.join(", ")})"
+        end
+        # Dropped explicitly: both this and the plain created_at index are
+        # keyed on created_at alone, so reverting that one by column would
+        # otherwise be ambiguous.
+        dir.down { execute "DROP INDEX IF EXISTS idx_executions_analytics" }
+      end
+    when /sqlite/
+      add_index :ruby_llm_agents_executions, ["created_at", *analytics_columns],
+                name: "idx_executions_analytics"
+    end
+
     # Foreign keys for execution hierarchy
     add_foreign_key :ruby_llm_agents_executions, :ruby_llm_agents_executions,
                     column: :parent_execution_id, on_delete: :nullify

data/lib/generators/ruby_llm_agents/upgrade_generator.rb

@@ -117,6 +117,44 @@ module RubyLlmAgents
       )
     end
 
+    # Add the composite index behind the executions dashboard list
+    def create_add_root_execution_list_index_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, [:parent_execution_id, :created_at])
+        say_status :skip, "root execution list index already exists", :yellow
+        return
+      end
+
+      say_status :upgrade, "Adding root execution list index", :blue
+      migration_template(
+        "add_root_execution_list_index_migration.rb.tt",
+        File.join(db_migrate_path, "add_root_execution_list_index.rb")
+      )
+    end
+
+    # Add the covering index behind the dashboard's aggregate queries
+    def create_add_executions_analytics_index_migration
+      unless table_exists?(:ruby_llm_agents_executions)
+        say_status :skip, "executions table does not exist yet", :yellow
+        return
+      end
+
+      if index_name_exists?(:ruby_llm_agents_executions, "idx_executions_analytics")
+        say_status :skip, "executions analytics index already exists", :yellow
+        return
+      end
+
+      say_status :upgrade, "Adding executions analytics index", :blue
+      migration_template(
+        "add_executions_analytics_index_migration.rb.tt",
+        File.join(db_migrate_path, "add_executions_analytics_index.rb")
+      )
+    end
+
     # Create overrides table for dashboard-managed agent settings
     def create_overrides_migration
       if table_exists?(:ruby_llm_agents_overrides)
@@ -231,5 +269,11 @@ module RubyLlmAgents
     rescue
       false
     end
+
+    def index_name_exists?(table, name)
+      ActiveRecord::Base.connection.index_name_exists?(table, name)
+    rescue
+      false
+    end
   end
 end

data/lib/ruby_llm/agents/audio/transcriber.rb

@@ -117,37 +117,10 @@ module RubyLLM
 
         # @!endgroup
 
-        # @!group Reliability DSL
-
-        # Configures reliability options (retries, fallbacks)
-        #
-        # @yield Block for configuring reliability options
-        # @return [ReliabilityConfig] The reliability configuration
-        def reliability(&block)
-          @reliability_config ||= ReliabilityConfig.new
-          @reliability_config.instance_eval(&block) if block_given?
-          @reliability_config
-        end
-
-        # Returns reliability configuration
-        #
-        # @return [ReliabilityConfig, nil] The reliability configuration
-        def reliability_config
-          @reliability_config || inherited_or_default(:reliability_config, nil)
-        end
-
-        # Sets fallback models directly (shorthand for reliability block)
-        #
-        # @param models [Array<String>] Model identifiers to try on failure
-        # @return [Array<String>] The fallback models
-        def fallback_models(*models)
-          if models.any?
-            @fallback_models = models.flatten
-          end
-          @fallback_models || inherited_or_default(:fallback_models, [])
-        end
-
-        # @!endgroup
+        # Reliability (retries, fallbacks, circuit breakers) comes from the
+        # shared DSL::Reliability on BaseAgent and is executed by the
+        # Reliability middleware — the middleware expects the Hash config that
+        # DSL produces, so Transcriber must not shadow it with its own object.
 
         # Factory method to instantiate and execute transcription
         #
@@ -197,40 +170,6 @@ module RubyLLM
         end
       end
 
-      # Configuration class for reliability options
-      class ReliabilityConfig
-        attr_accessor :max_retries, :backoff, :fallback_models_list, :total_timeout_seconds
-
-        def initialize
-          @max_retries = 3
-          @backoff = :exponential
-          @fallback_models_list = []
-          @total_timeout_seconds = nil
-        end
-
-        def retries(max: 3, backoff: :exponential)
-          @max_retries = max
-          @backoff = backoff
-        end
-
-        def fallback_models(*models)
-          @fallback_models_list = models.flatten
-        end
-
-        def total_timeout(seconds)
-          @total_timeout_seconds = seconds
-        end
-
-        def to_h
-          {
-            max_retries: max_retries,
-            backoff: backoff,
-            fallback_models: fallback_models_list,
-            total_timeout: total_timeout_seconds
-          }
-        end
-      end
-
       # @!attribute [r] audio
       #   @return [String, File, IO] Audio input
       # @!attribute [r] audio_format
@@ -308,8 +247,9 @@ module RubyLLM
         audio_input = normalize_audio_input(@audio, @audio_format)
         validate_audio_input!(audio_input)
 
-        # Execute transcription with reliability (retries, fallbacks)
-        raw_result = execute_with_reliability(audio_input)
+        # context.model is set per-attempt by the Reliability middleware, so
+        # fallback models actually take effect here
+        raw_result = execute_transcription(audio_input, context.model || resolved_model)
 
         execution_completed_at = Time.current
         duration_ms = ((execution_completed_at - execution_started_at) * 1000).to_i
@@ -455,37 +395,6 @@ module RubyLLM
         end
       end
 
-      # Executes transcription with reliability features
-      #
-      # @param audio_input [Hash] Normalized audio input
-      # @return [Hash] Raw transcription result
-      def execute_with_reliability(audio_input)
-        models_to_try = [resolved_model] + self.class.fallback_models
-        last_error = nil
-
-        models_to_try.each do |model|
-          retries = 0
-          max_retries = reliability_max_retries
-
-          begin
-            return execute_transcription(audio_input, model)
-          rescue => e
-            last_error = e
-            retries += 1
-
-            if retryable_error?(e) && retries < max_retries
-              sleep(calculate_backoff(retries))
-              retry
-            end
-
-            # Try next model
-            next
-          end
-        end
-
-        raise last_error || StandardError.new("All transcription models exhausted")
-      end
-
       # Executes the actual transcription API call
       #
       # @param audio_input [Hash] Normalized audio input
@@ -663,29 +572,6 @@ module RubyLLM
       def resolved_language
         @runtime_language || self.class.language
       end
-
-      # Returns max retries from reliability config
-      def reliability_max_retries
-        config = self.class.reliability_config
-        config&.max_retries || 3
-      end
-
-      # Checks if error is retryable
-      def retryable_error?(error)
-        message = error.message.to_s.downcase
-        retryable_patterns = ["rate limit", "timeout", "503", "502", "429", "overloaded"]
-        retryable_patterns.any? { |pattern| message.include?(pattern) }
-      end
-
-      # Calculates exponential backoff delay
-      def calculate_backoff(attempt)
-        config = self.class.reliability_config
-        base = (config&.backoff == :constant) ? 1.0 : 0.4
-        max_delay = 10.0
-
-        delay = base * (2**(attempt - 1))
-        [delay, max_delay].min
-      end
     end
   end
 end

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

@@ -109,6 +109,14 @@ module RubyLLM
       #   Number of recent executions shown on the dashboard home.
       #   @return [Integer] Limit for recent executions (default: 10)
 
+      # @!attribute [rw] dashboard_query_timeout
+      #   Seconds a single dashboard query may run before the database cancels
+      #   it. A cancelled query renders a "narrow the time range" notice
+      #   instead of leaving the request (and the database) grinding on a scan
+      #   of the whole executions table. Enforced on PostgreSQL only; a
+      #   stricter statement_timeout already set on the connection wins.
+      #   @return [Numeric, nil] Timeout in seconds, or nil to disable (default: 5)
+
       # @!attribute [rw] job_retry_attempts
       #   Number of retry attempts for the async logging job on failure.
       #   @return [Integer] Retry attempts (default: 3)
@@ -494,6 +502,7 @@ module RubyLLM
         :anomaly_duration_threshold,
         :per_page,
         :recent_executions_limit,
+        :dashboard_query_timeout,
         :job_retry_attempts,
         :messages_summary_max_length,
         :dashboard_auth,
@@ -560,6 +569,15 @@ module RubyLLM
         @recent_executions_limit = value
       end
 
+      # Sets dashboard_query_timeout with validation
+      #
+      # @param value [Numeric, nil] Seconds (must be > 0), or nil to disable
+      # @raise [ArgumentError] If value is not positive
+      def dashboard_query_timeout=(value)
+        validate_positive!(:dashboard_query_timeout, value) unless value.nil?
+        @dashboard_query_timeout = value
+      end
+
       # Sets job_retry_attempts with validation
       #
       # @param value [Integer] Retry attempts (must be >= 0)
@@ -702,6 +720,7 @@ module RubyLLM
         @basic_auth_password = nil
         @per_page = 25
         @recent_executions_limit = 10
+        @dashboard_query_timeout = 5
         @job_retry_attempts = 3
 
         # Reliability defaults (all disabled by default for backward compatibility)
@@ -1031,6 +1050,7 @@ module RubyLLM
           dashboard: {
             per_page: per_page,
             recent_executions_limit: recent_executions_limit,
+            dashboard_query_timeout: dashboard_query_timeout,
             dashboard_parent_controller: dashboard_parent_controller,
             basic_auth_username: basic_auth_username,
             dashboard_auth: dashboard_auth&.class&.name

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.15.0"
+    VERSION = "3.16.0"
   end
 end

data/lib/ruby_llm/agents/pipeline/middleware/instrumentation.rb

@@ -172,6 +172,12 @@ module RubyLLM
           # Falls back to creating a new record if the initial record is nil.
           # Errors are re-raised to allow the ensure block to handle them.
           #
+          # The record is locked and reloaded before updating: the instance
+          # held here was created when the pipeline started and may be stale —
+          # a concurrent transition (e.g. operator cancellation or a timeout
+          # sweep) can have written a terminal status in the meantime, and the
+          # completion must not overwrite it.
+          #
           # @param execution [Execution, nil] The execution record to update
           # @param context [Context] The execution context
           # @param status [String] Final status ("success", "error", "timeout")
@@ -188,7 +194,7 @@ module RubyLLM
             end
 
             update_data = build_completion_data(context, status)
-            execution.update!(update_data)
+            return unless complete_running_execution(execution, update_data)
 
             # Save detail data (prompts, responses, tool calls, etc.)
             save_execution_details(execution, context, status)
@@ -197,6 +203,31 @@ module RubyLLM
             raise # Re-raise for ensure block to handle via mark_execution_failed!
           end
 
+          # Applies the completion update unless the execution already left
+          # "running" state.
+          #
+          # Locks the row and reloads it, so the status check and the update
+          # are atomic with respect to concurrent status transitions: whichever
+          # side wins the row lock first keeps the row. A completion that finds
+          # a terminal status is dropped instead of overwriting it.
+          #
+          # @param execution [Execution] The execution record to update
+          # @param update_data [Hash] The completion attributes
+          # @return [Boolean] Whether the completion update was applied
+          def complete_running_execution(execution, update_data)
+            return execution.update!(update_data) unless execution.persisted?
+
+            execution.with_lock do
+              if execution.status == "running"
+                execution.update!(update_data)
+                true
+              else
+                debug("Skipped completion for execution #{execution.id}: already #{execution.status}")
+                false
+              end
+            end
+          end
+
           # Emergency fallback to mark execution as failed
           #
           # Uses update_all to bypass ActiveRecord callbacks and validations,
@@ -431,6 +462,13 @@ module RubyLLM
               data[:attempts_count] = context[:reliability_attempts].size
             end
 
+            # Carry the tracker request_id/tags that
+            # build_running_execution_data injected through the metadata
+            # rebuild — otherwise a completed execution loses them. Only
+            # merge into a rebuild that actually produced metadata: when
+            # none did, the running record's metadata stays untouched.
+            inject_tracker_data(context, data) if data[:metadata]
+
             data
           end