ruby_llm-agents 0.2.3 → 0.3.0

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

@@ -2,98 +2,267 @@
 
 module RubyLLM
   module Agents
+    # Controller for viewing agent details and per-agent analytics
+    #
+    # Provides an overview of all registered agents and detailed views
+    # for individual agents including configuration, execution history,
+    # and performance metrics.
+    #
+    # @see AgentRegistry For agent discovery
+    # @see Paginatable For pagination implementation
+    # @see Filterable For filter parsing and validation
+    # @api private
     class AgentsController < ApplicationController
+      include Paginatable
+      include Filterable
+
+      # Lists all registered agents with their details
+      #
+      # Uses AgentRegistry to discover agents from both file system
+      # and execution history, ensuring deleted agents with history
+      # are still visible.
+      #
+      # @return [void]
       def index
         @agents = AgentRegistry.all_with_details
+      rescue StandardError => e
+        Rails.logger.error("[RubyLLM::Agents] Error loading agents: #{e.message}")
+        @agents = []
+        flash.now[:alert] = "Error loading agents list"
       end
 
+      # Shows detailed view for a specific agent
+      #
+      # Loads agent configuration (if class exists), statistics,
+      # filtered executions, and chart data for visualization.
+      # Works for both active agents and deleted agents with history.
+      #
+      # @return [void]
       def show
         @agent_type = params[:id]
         @agent_class = AgentRegistry.find(@agent_type)
         @agent_active = @agent_class.present?
 
-        # Get stats for different time periods
+        load_agent_stats
+        load_filter_options
+        load_filtered_executions
+        load_chart_data
+
+        if @agent_class
+          load_agent_config
+          load_circuit_breaker_status
+        end
+      rescue StandardError => e
+        Rails.logger.error("[RubyLLM::Agents] Error loading agent #{@agent_type}: #{e.message}")
+        redirect_to ruby_llm_agents.agents_path, alert: "Error loading agent details"
+      end
+
+      private
+
+      # Loads all-time and today's statistics for the agent
+      #
+      # @return [void]
+      def load_agent_stats
         @stats = Execution.stats_for(@agent_type, period: :all_time)
         @stats_today = Execution.stats_for(@agent_type, period: :today)
 
-        # Get available filter options for this agent
-        @versions = Execution.by_agent(@agent_type).distinct.pluck(:agent_version).compact.sort.reverse
-        @models = Execution.by_agent(@agent_type).distinct.pluck(:model_id).compact.sort
-        @temperatures = Execution.by_agent(@agent_type).distinct.pluck(:temperature).compact.sort
+        # Additional stats for new schema fields
+        agent_scope = Execution.by_agent(@agent_type)
+        @cache_hit_rate = agent_scope.cache_hit_rate
+        @streaming_rate = agent_scope.streaming_rate
+        @avg_ttft = agent_scope.avg_time_to_first_token
+      end
 
-        # Build filtered scope
-        base_scope = Execution.by_agent(@agent_type)
+      # Loads available filter options from execution history
+      #
+      # Uses a single optimized query to fetch all filter values
+      # (versions, models, temperatures) avoiding N+1 queries.
+      #
+      # @return [void]
+      def load_filter_options
+        # Single query to get all filter options (fixes N+1)
+        filter_data = Execution.by_agent(@agent_type)
+                               .where.not(agent_version: nil)
+                               .or(Execution.by_agent(@agent_type).where.not(model_id: nil))
+                               .or(Execution.by_agent(@agent_type).where.not(temperature: nil))
+                               .pluck(:agent_version, :model_id, :temperature)
 
-        # Apply status filter
-        if params[:statuses].present?
-          statuses = params[:statuses].is_a?(Array) ? params[:statuses] : params[:statuses].split(",")
-          base_scope = base_scope.where(status: statuses) if statuses.any?(&:present?)
-        end
+        @versions = filter_data.map(&:first).compact.uniq.sort.reverse
+        @models = filter_data.map { |d| d[1] }.compact.uniq.sort
+        @temperatures = filter_data.map(&:last).compact.uniq.sort
+      end
+
+      # Loads paginated and filtered executions with statistics
+      #
+      # Sets @executions, @pagination, and @filter_stats for the view.
+      #
+      # @return [void]
+      def load_filtered_executions
+        base_scope = build_filtered_scope
+        result = paginate(base_scope)
+        @executions = result[:records]
+        @pagination = result[:pagination]
+
+        @filter_stats = {
+          total_count: result[:pagination][:total_count],
+          total_cost: base_scope.sum(:total_cost),
+          total_tokens: base_scope.sum(:total_tokens)
+        }
+      end
+
+      # Builds a filtered scope for the current agent's executions
+      #
+      # Applies filters in order: status, version, model, temperature, time.
+      # Each filter is optional and only applied if values are provided.
+      #
+      # @return [ActiveRecord::Relation] Filtered execution scope
+      def build_filtered_scope
+        scope = Execution.by_agent(@agent_type)
+
+        # Apply status filter with validation
+        statuses = parse_array_param(:statuses)
+        scope = apply_status_filter(scope, statuses) if statuses.any?
 
         # Apply version filter
-        if params[:versions].present?
-          versions = params[:versions].is_a?(Array) ? params[:versions] : params[:versions].split(",")
-          base_scope = base_scope.where(agent_version: versions) if versions.any?(&:present?)
-        end
+        versions = parse_array_param(:versions)
+        scope = scope.where(agent_version: versions) if versions.any?
 
         # Apply model filter
-        if params[:models].present?
-          models = params[:models].is_a?(Array) ? params[:models] : params[:models].split(",")
-          base_scope = base_scope.where(model_id: models) if models.any?(&:present?)
-        end
+        models = parse_array_param(:models)
+        scope = scope.where(model_id: models) if models.any?
 
         # Apply temperature filter
-        if params[:temperatures].present?
-          temps = params[:temperatures].is_a?(Array) ? params[:temperatures] : params[:temperatures].split(",")
-          base_scope = base_scope.where(temperature: temps) if temps.any?(&:present?)
-        end
+        temperatures = parse_array_param(:temperatures)
+        scope = scope.where(temperature: temperatures) if temperatures.any?
 
-        # Apply time range filter
-        base_scope = base_scope.where("created_at >= ?", params[:days].to_i.days.ago) if params[:days].present?
+        # Apply time range filter with validation
+        days = parse_days_param
+        scope = apply_time_filter(scope, days)
 
-        # Paginate
-        page = (params[:page] || 1).to_i
-        per_page = 25
-        offset = (page - 1) * per_page
+        scope
+      end
+
+      # Loads chart data for agent performance visualization
+      #
+      # Fetches 30-day trend analysis and status/finish_reason distribution for charts.
+      #
+      # @return [void]
+      def load_chart_data
+        @trend_data = Execution.trend_analysis(agent_type: @agent_type, days: 30)
+        @status_distribution = Execution.by_agent(@agent_type).group(:status).count
+        @finish_reason_distribution = Execution.by_agent(@agent_type).finish_reason_distribution
+        load_version_comparison
+      end
+
+      # Loads version comparison data if multiple versions exist
+      #
+      # Includes trend data for sparkline charts.
+      #
+      # @return [void]
+      def load_version_comparison
+        return unless @versions.size >= 2
+
+        # Default to comparing two most recent versions
+        v1 = params[:compare_v1] || @versions[0]
+        v2 = params[:compare_v2] || @versions[1]
 
-        filtered_scope = base_scope.order(created_at: :desc)
-        total_count = filtered_scope.count
-        @executions = filtered_scope.limit(per_page).offset(offset)
+        comparison_data = Execution.compare_versions(@agent_type, v1, v2, period: :this_month)
 
-        @pagination = {
-          current_page: page,
-          per_page: per_page,
-          total_count: total_count,
-          total_pages: (total_count.to_f / per_page).ceil
+        # Fetch trend data for sparklines
+        v1_trend = Execution.version_trend_data(@agent_type, v1, days: 14)
+        v2_trend = Execution.version_trend_data(@agent_type, v2, days: 14)
+
+        @version_comparison = {
+          v1: v1,
+          v2: v2,
+          data: comparison_data,
+          v1_trend: v1_trend,
+          v2_trend: v2_trend
         }
+      rescue StandardError => e
+        Rails.logger.debug("[RubyLLM::Agents] Version comparison error: #{e.message}")
+        @version_comparison = nil
+      end
 
-        # Filter stats for summary display
-        @filter_stats = {
-          total_count: total_count,
-          total_cost: base_scope.sum(:total_cost),
-          total_tokens: base_scope.sum(:total_tokens)
+      # Loads the current agent class configuration
+      #
+      # Extracts DSL-configured values from the agent class for display.
+      # Only called if the agent class still exists.
+      #
+      # @return [void]
+      def load_agent_config
+        @config = {
+          # Basic configuration
+          model: @agent_class.model,
+          temperature: @agent_class.temperature,
+          version: @agent_class.version,
+          timeout: @agent_class.timeout,
+          cache_enabled: @agent_class.cache_enabled?,
+          cache_ttl: @agent_class.cache_ttl,
+          params: @agent_class.params,
+
+          # Reliability configuration
+          retries: @agent_class.retries,
+          fallback_models: @agent_class.fallback_models,
+          total_timeout: @agent_class.total_timeout,
+          circuit_breaker: @agent_class.circuit_breaker_config
         }
+      end
 
-        # Get trend data for charts (30 days)
-        @trend_data = Execution.trend_analysis(agent_type: @agent_type, days: 30)
+      # Loads circuit breaker status for the agent's models
+      #
+      # Checks the primary model and any fallback models configured.
+      # Only returns data if reliability features are enabled.
+      #
+      # @return [void]
+      def load_circuit_breaker_status
+        return unless @agent_class.respond_to?(:reliability_config)
 
-        # Get status distribution for pie chart
-        @status_distribution = Execution.by_agent(@agent_type)
-                                         .group(:status)
-                                         .count
+        config = @agent_class.reliability_config rescue nil
+        return unless config
 
-        # Agent configuration (if class exists)
-        if @agent_class
-          @config = {
-            model: @agent_class.model,
-            temperature: @agent_class.temperature,
-            version: @agent_class.version,
-            timeout: @agent_class.timeout,
-            cache_enabled: @agent_class.cache_enabled?,
-            cache_ttl: @agent_class.cache_ttl,
-            params: @agent_class.params
+        # Collect all models: primary + fallbacks
+        models_to_check = [@agent_class.model]
+        models_to_check.concat(config[:fallback_models]) if config[:fallback_models].present?
+        models_to_check = models_to_check.compact.uniq
+
+        return if models_to_check.empty?
+
+        breaker_config = config[:circuit_breaker] || {}
+        errors_threshold = breaker_config[:errors] || 10
+        window = breaker_config[:within] || 60
+        cooldown = breaker_config[:cooldown] || 300
+
+        @circuit_breaker_status = {}
+
+        models_to_check.each do |model_id|
+          breaker = CircuitBreaker.new(
+            @agent_type,
+            model_id,
+            errors: errors_threshold,
+            within: window,
+            cooldown: cooldown
+          )
+
+          status = {
+            open: breaker.open?,
+            threshold: errors_threshold
           }
+
+          # Get additional details
+          if breaker.open?
+            # Calculate remaining cooldown (approximate)
+            status[:cooldown_remaining] = cooldown
+          else
+            # Get current failure count if available
+            status[:failure_count] = breaker.failure_count
+          end
+
+          @circuit_breaker_status[model_id] = status
         end
+      rescue StandardError => e
+        Rails.logger.debug("[RubyLLM::Agents] Could not load circuit breaker status: #{e.message}")
+        @circuit_breaker_status = {}
       end
     end
   end

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

@@ -2,33 +2,188 @@
 
 module RubyLLM
   module Agents
+    # Dashboard controller for the RubyLLM::Agents observability UI
+    #
+    # Displays high-level statistics, recent executions, and activity charts
+    # for monitoring agent performance at a glance.
+    #
+    # @see ExecutionsController For detailed execution browsing
+    # @see AgentsController For per-agent analytics
+    # @api private
     class DashboardController < ApplicationController
+      # Renders the main dashboard view
+      #
+      # Loads now strip data, critical alerts, hourly activity,
+      # and recent executions for real-time monitoring.
+      #
+      # @return [void]
       def index
-        @stats = daily_stats
-        @recent_executions = Execution.recent(10)
+        @now_strip = Execution.now_strip_data
+        @critical_alerts = load_critical_alerts
         @hourly_activity = Execution.hourly_activity_chart
+        @recent_executions = Execution.recent(10)
+      end
+
+      # Returns chart data as JSON for live updates
+      #
+      # @return [JSON] Chart data with categories and series
+      def chart_data
+        render json: Execution.hourly_activity_chart_json
       end
 
       private
 
+      # Fetches cached daily statistics for the dashboard
+      #
+      # Results are cached for 1 minute to reduce database load while
+      # keeping the dashboard reasonably up-to-date.
+      #
+      # @return [Hash] Daily statistics
+      # @option return [Integer] :total_executions Total execution count today
+      # @option return [Integer] :successful Successful execution count
+      # @option return [Integer] :failed Failed execution count
+      # @option return [Float] :total_cost Combined cost of all executions
+      # @option return [Integer] :total_tokens Combined token usage
+      # @option return [Integer] :avg_duration_ms Average execution duration
+      # @option return [Float] :success_rate Percentage of successful executions
       def daily_stats
-        scope = Execution.today
-        {
-          total_executions: scope.count,
-          successful: scope.successful.count,
-          failed: scope.failed.count,
-          total_cost: scope.total_cost_sum || 0,
-          total_tokens: scope.total_tokens_sum || 0,
-          avg_duration_ms: scope.avg_duration&.round || 0,
-          success_rate: calculate_success_rate(scope)
-        }
+        Rails.cache.fetch("ruby_llm_agents/daily_stats/#{Date.current}", expires_in: 1.minute) do
+          scope = Execution.today
+          {
+            total_executions: scope.count,
+            successful: scope.successful.count,
+            failed: scope.failed.count,
+            total_cost: scope.total_cost_sum || 0,
+            total_tokens: scope.total_tokens_sum || 0,
+            avg_duration_ms: scope.avg_duration&.round || 0,
+            success_rate: calculate_success_rate(scope)
+          }
+        end
       end
 
+      # Calculates the success rate percentage for a scope
+      #
+      # @param scope [ActiveRecord::Relation] The execution scope to calculate from
+      # @return [Float] Success rate as a percentage (0.0-100.0)
       def calculate_success_rate(scope)
         total = scope.count
         return 0.0 if total.zero?
         (scope.successful.count.to_f / total * 100).round(1)
       end
+
+      # Loads budget status for display on dashboard
+      #
+      # @return [Hash] Budget status with global daily and monthly info
+      def load_budget_status
+        BudgetTracker.status
+      end
+
+      # Loads all open circuit breakers across agents
+      #
+      # @return [Array<Hash>] Array of open breaker information
+      def load_open_breakers
+        open_breakers = []
+
+        # Get all agents from execution history
+        agent_types = Execution.distinct.pluck(:agent_type)
+
+        agent_types.each do |agent_type|
+          # Get the agent class if available
+          agent_class = AgentRegistry.find(agent_type)
+          next unless agent_class
+
+          # Get circuit breaker config from class methods
+          cb_config = agent_class.respond_to?(:circuit_breaker_config) ? agent_class.circuit_breaker_config : nil
+          next unless cb_config
+
+          # Get models to check (primary + fallbacks)
+          primary_model = agent_class.respond_to?(:model) ? agent_class.model : RubyLLM::Agents.configuration.default_model
+          fallbacks = agent_class.respond_to?(:fallback_models) ? agent_class.fallback_models : []
+          models_to_check = [primary_model, *fallbacks].compact.uniq
+
+          models_to_check.each do |model_id|
+            breaker = CircuitBreaker.from_config(agent_type, model_id, cb_config)
+            next unless breaker
+
+            if breaker.open?
+              open_breakers << {
+                agent_type: agent_type,
+                model_id: model_id,
+                cooldown_remaining: breaker.time_until_close,
+                failure_count: breaker.failure_count,
+                threshold: cb_config[:errors] || 5
+              }
+            end
+          end
+        end
+
+        open_breakers
+      rescue StandardError => e
+        Rails.logger.debug("[RubyLLM::Agents] Error loading open breakers: #{e.message}")
+        []
+      end
+
+      # Loads recent alerts from cache
+      #
+      # @return [Array<Hash>] Array of recent alert events
+      def load_recent_alerts
+        Rails.cache.fetch("ruby_llm_agents/recent_alerts", expires_in: 1.minute) do
+          # Fetch from cache-based alert store (ephemeral for Phase 1)
+          alerts_key = "ruby_llm_agents:alerts:recent"
+          cached_alerts = RubyLLM::Agents.configuration.cache_store.read(alerts_key) || []
+          cached_alerts.take(10)
+        end
+      end
+
+      # Loads critical alerts for the Action Center
+      #
+      # Combines open circuit breakers, budget breaches, and error spikes
+      # into a single prioritized list (max 3 items).
+      #
+      # @return [Array<Hash>] Critical alerts with type and data
+      def load_critical_alerts
+        alerts = []
+
+        # Open circuit breakers
+        load_open_breakers.each do |breaker|
+          alerts << { type: :breaker, data: breaker }
+        end
+
+        # Budget breaches (>100% of limit)
+        budget_status = load_budget_status
+        daily_budget = budget_status&.dig(:global_daily)
+        monthly_budget = budget_status&.dig(:global_monthly)
+
+        if daily_budget && daily_budget[:percentage_used].to_f >= 100
+          alerts << {
+            type: :budget_breach,
+            data: {
+              period: :daily,
+              current: daily_budget[:current_spend],
+              limit: daily_budget[:limit]
+            }
+          }
+        end
+
+        if monthly_budget && monthly_budget[:percentage_used].to_f >= 100
+          alerts << {
+            type: :budget_breach,
+            data: {
+              period: :monthly,
+              current: monthly_budget[:current_spend],
+              limit: monthly_budget[:limit]
+            }
+          }
+        end
+
+        # Error spike detection (>5 errors in last 15 minutes)
+        error_count_15m = Execution.status_error.where("created_at > ?", 15.minutes.ago).count
+        if error_count_15m >= 5
+          alerts << { type: :error_spike, data: { count: error_count_15m } }
+        end
+
+        alerts.take(3)
+      end
     end
   end
 end