ruby_llm-agents 0.2.3 → 0.3.0

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

@@ -3,21 +3,39 @@
 module RubyLLM
   module Agents
     class Execution
-      # Scopes concern for common query patterns
+      # Query scopes for filtering and aggregating executions
       #
-      # Provides chainable scopes for:
-      # - Time-based filtering (today, this_week, last_n_days)
-      # - Agent-based filtering (by_agent, by_version, by_model)
-      # - Status filtering (successful, failed, errors, timeouts)
-      # - Performance filtering (expensive, slow, high_token)
-      # - JSONB parameter queries
-      # - Aggregations (total_cost_sum, avg_duration)
+      # All scopes are chainable and return ActiveRecord::Relation objects.
       #
+      # @example Chaining scopes
+      #   Execution.by_agent("SearchAgent").today.successful
+      #   Execution.expensive(2.00).slow(10_000)
+      #
+      # @see RubyLLM::Agents::Execution::Analytics
+      # @api public
       module Scopes
         extend ActiveSupport::Concern
 
         included do
-          # Time-based scopes
+          # @!group Time-based Scopes
+
+          # @!method recent(limit = 100)
+          #   Returns most recent executions
+          #   @param limit [Integer] Maximum records to return
+          #   @return [ActiveRecord::Relation]
+
+          # @!method today
+          #   Returns executions from today
+          #   @return [ActiveRecord::Relation]
+
+          # @!method this_week
+          #   Returns executions from current week
+          #   @return [ActiveRecord::Relation]
+
+          # @!method last_n_days(n)
+          #   Returns executions from the last n days
+          #   @param n [Integer] Number of days
+          #   @return [ActiveRecord::Relation]
           scope :recent, ->(limit = 100) { order(created_at: :desc).limit(limit) }
           scope :oldest, ->(limit = 100) { order(created_at: :asc).limit(limit) }
           scope :all_time, -> { all }  # Explicit scope for all-time queries (used by analytics)
@@ -27,12 +45,43 @@ module RubyLLM
           scope :this_month, -> { where("created_at >= ?", Time.current.beginning_of_month) }
           scope :last_n_days, ->(n) { where("created_at >= ?", n.days.ago) }
 
-          # Agent-based scopes
+          # @!endgroup
+
+          # @!group Agent-based Scopes
+
+          # @!method by_agent(agent_type)
+          #   Filters to a specific agent type
+          #   @param agent_type [String] The agent class name
+          #   @return [ActiveRecord::Relation]
+
+          # @!method by_version(version)
+          #   Filters to a specific agent version
+          #   @param version [String] The version string
+          #   @return [ActiveRecord::Relation]
+
+          # @!method by_model(model_id)
+          #   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_version, ->(version) { where(agent_version: version.to_s) }
           scope :by_model, ->(model_id) { where(model_id: model_id.to_s) }
 
-          # Status scopes
+          # @!endgroup
+
+          # @!group Status Scopes
+
+          # @!method successful
+          #   Returns executions with success status
+          #   @return [ActiveRecord::Relation]
+
+          # @!method failed
+          #   Returns executions with error or timeout status
+          #   @return [ActiveRecord::Relation]
+
+          # @!method errors
+          #   Returns executions with error status only
+          #   @return [ActiveRecord::Relation]
           scope :running, -> { where(status: "running") }
           scope :in_progress, -> { running }  # alias
           scope :completed, -> { where.not(status: "running") }
@@ -41,12 +90,37 @@ module RubyLLM
           scope :errors, -> { where(status: "error") }
           scope :timeouts, -> { where(status: "timeout") }
 
-          # Performance scopes
+          # @!endgroup
+
+          # @!group Performance Scopes
+
+          # @!method expensive(threshold_dollars = 1.00)
+          #   Returns executions exceeding cost threshold
+          #   @param threshold_dollars [Float] Cost threshold in USD
+          #   @return [ActiveRecord::Relation]
+
+          # @!method slow(threshold_ms = 5000)
+          #   Returns executions exceeding duration threshold
+          #   @param threshold_ms [Integer] Duration threshold in milliseconds
+          #   @return [ActiveRecord::Relation]
+
+          # @!method high_token(threshold = 10_000)
+          #   Returns executions exceeding token threshold
+          #   @param threshold [Integer] Token count threshold
+          #   @return [ActiveRecord::Relation]
           scope :expensive, ->(threshold_dollars = 1.00) { where("total_cost >= ?", threshold_dollars) }
           scope :slow, ->(threshold_ms = 5000) { where("duration_ms >= ?", threshold_ms) }
           scope :high_token, ->(threshold = 10_000) { where("total_tokens >= ?", threshold) }
 
-          # Parameter-based scopes (JSONB queries)
+          # @!endgroup
+
+          # @!group Parameter Scopes
+
+          # @!method with_parameter(key, value = nil)
+          #   Filters by JSONB parameter key/value
+          #   @param key [String, Symbol] Parameter key to check
+          #   @param value [Object, nil] Optional value to match
+          #   @return [ActiveRecord::Relation]
           scope :with_parameter, ->(key, value = nil) do
             if value
               where("parameters @> ?", { key => value }.to_json)
@@ -55,25 +129,171 @@ module RubyLLM
             end
           end
 
+          # @!endgroup
+
+          # @!group Search Scopes
+
+          # @!method search(query)
+          #   Free-text search across error fields and parameters
+          #   @param query [String] Search query
+          #   @return [ActiveRecord::Relation]
+          scope :search, ->(query) do
+            return all if query.blank?
+
+            sanitized_query = "%#{sanitize_sql_like(query)}%"
+            # Use database-agnostic case-insensitive search
+            # PostgreSQL: ILIKE, SQLite: LIKE with LOWER() + ESCAPE clause
+            if connection.adapter_name.downcase.include?("postgresql")
+              where(
+                "error_class ILIKE :q OR error_message ILIKE :q OR CAST(parameters AS TEXT) ILIKE :q",
+                q: sanitized_query
+              )
+            else
+              # SQLite and other databases need ESCAPE clause for backslash to work
+              sanitized_query_lower = sanitized_query.downcase
+              where(
+                "LOWER(error_class) LIKE :q ESCAPE '\\' OR " \
+                "LOWER(error_message) LIKE :q ESCAPE '\\' OR " \
+                "LOWER(CAST(parameters AS TEXT)) LIKE :q ESCAPE '\\'",
+                q: sanitized_query_lower
+              )
+            end
+          end
+
+          # @!endgroup
+
+          # @!group Tracing Scopes
+
+          # @!method by_trace(trace_id)
+          #   Filters to a specific distributed trace
+          #   @param trace_id [String] The trace identifier
+          #   @return [ActiveRecord::Relation]
+
+          # @!method by_request(request_id)
+          #   Filters to a specific request
+          #   @param request_id [String] The request identifier
+          #   @return [ActiveRecord::Relation]
+
+          # @!method root_executions
+          #   Returns only root (top-level) executions
+          #   @return [ActiveRecord::Relation]
+
+          # @!method child_executions
+          #   Returns only child (nested) executions
+          #   @return [ActiveRecord::Relation]
+          scope :by_trace, ->(trace_id) { where(trace_id: trace_id) }
+          scope :by_request, ->(request_id) { where(request_id: request_id) }
+          scope :root_executions, -> { where(parent_execution_id: nil) }
+          scope :child_executions, -> { where.not(parent_execution_id: nil) }
+          scope :children_of, ->(execution_id) { where(parent_execution_id: execution_id) }
+
+          # @!endgroup
+
+          # @!group Routing and Retry Scopes
+
+          # @!method with_fallback
+          #   Returns executions that used a fallback model
+          #   @return [ActiveRecord::Relation]
+
+          # @!method retryable_errors
+          #   Returns executions with retryable errors
+          #   @return [ActiveRecord::Relation]
+
+          # @!method rate_limited
+          #   Returns executions that were rate limited
+          #   @return [ActiveRecord::Relation]
+          scope :with_fallback, -> { where.not(fallback_reason: nil) }
+          scope :retryable_errors, -> { where(retryable: true) }
+          scope :rate_limited, -> { where(rate_limited: true) }
+          scope :by_fallback_reason, ->(reason) { where(fallback_reason: reason) }
+
+          # @!endgroup
+
+          # @!group Caching Scopes
+
+          # @!method cached
+          #   Returns executions that were cache hits
+          #   @return [ActiveRecord::Relation]
+
+          # @!method cache_miss
+          #   Returns executions that were cache misses
+          #   @return [ActiveRecord::Relation]
+          scope :cached, -> { where(cache_hit: true) }
+          scope :cache_miss, -> { where(cache_hit: [false, nil]) }
+
+          # @!endgroup
+
+          # @!group Streaming Scopes
+
+          # @!method streaming
+          #   Returns executions that used streaming
+          #   @return [ActiveRecord::Relation]
+
+          # @!method non_streaming
+          #   Returns executions that did not use streaming
+          #   @return [ActiveRecord::Relation]
+          scope :streaming, -> { where(streaming: true) }
+          scope :non_streaming, -> { where(streaming: [false, nil]) }
+
+          # @!endgroup
+
+          # @!group Finish Reason Scopes
+
+          # @!method by_finish_reason(reason)
+          #   Filters by finish reason
+          #   @param reason [String] The finish reason (stop, length, content_filter, tool_calls)
+          #   @return [ActiveRecord::Relation]
+
+          # @!method truncated
+          #   Returns executions that hit max_tokens limit
+          #   @return [ActiveRecord::Relation]
+
+          # @!method content_filtered
+          #   Returns executions blocked by safety filter
+          #   @return [ActiveRecord::Relation]
+          scope :by_finish_reason, ->(reason) { where(finish_reason: reason) }
+          scope :truncated, -> { where(finish_reason: "length") }
+          scope :content_filtered, -> { where(finish_reason: "content_filter") }
+          scope :tool_calls, -> { where(finish_reason: "tool_calls") }
+
+          # @!endgroup
         end
 
-        # Aggregation methods (not scopes - these return values, not relations)
+        # @!group Aggregation Methods
+        #
+        # These methods return scalar values, not relations.
+        # They can be called on scoped relations.
+
         class_methods do
+          # Returns sum of total_cost for the current scope
+          #
+          # @return [Float, nil] Total cost in USD
           def total_cost_sum
             sum(:total_cost)
           end
 
+          # Returns sum of total_tokens for the current scope
+          #
+          # @return [Integer, nil] Total token count
           def total_tokens_sum
             sum(:total_tokens)
           end
 
+          # Returns average duration for the current scope
+          #
+          # @return [Float, nil] Average duration in milliseconds
           def avg_duration
             average(:duration_ms)
           end
 
+          # Returns average token count for the current scope
+          #
+          # @return [Float, nil] Average tokens per execution
           def avg_tokens
             average(:total_tokens)
           end
+
+          # @!endgroup
         end
       end
     end

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

@@ -2,18 +2,49 @@
 
 module RubyLLM
   module Agents
-    # Execution model for tracking agent executions
+    # ActiveRecord model for tracking agent executions
     #
-    # Stores all agent execution data including:
-    # - Agent identification (type, version)
-    # - Model configuration (model_id, temperature)
-    # - Timing (started_at, completed_at, duration_ms)
-    # - Token usage (input_tokens, output_tokens, cached_tokens)
-    # - Costs (input_cost, output_cost, total_cost in dollars)
-    # - Status (success, error, timeout)
-    # - Parameters and metadata (JSONB)
-    # - Error tracking (error_class, error_message)
+    # Stores comprehensive execution data for observability and analytics.
     #
+    # @!attribute [rw] agent_type
+    #   @return [String] Full class name of the agent (e.g., "SearchAgent")
+    # @!attribute [rw] agent_version
+    #   @return [String] Version string for cache invalidation
+    # @!attribute [rw] model_id
+    #   @return [String] LLM model identifier used
+    # @!attribute [rw] temperature
+    #   @return [Float] Temperature setting used (0.0-2.0)
+    # @!attribute [rw] status
+    #   @return [String] Execution status: "running", "success", "error", "timeout"
+    # @!attribute [rw] started_at
+    #   @return [Time] When execution started
+    # @!attribute [rw] completed_at
+    #   @return [Time, nil] When execution completed
+    # @!attribute [rw] duration_ms
+    #   @return [Integer, nil] Execution duration in milliseconds
+    # @!attribute [rw] input_tokens
+    #   @return [Integer, nil] Number of input tokens
+    # @!attribute [rw] output_tokens
+    #   @return [Integer, nil] Number of output tokens
+    # @!attribute [rw] total_tokens
+    #   @return [Integer, nil] Sum of input and output tokens
+    # @!attribute [rw] input_cost
+    #   @return [BigDecimal, nil] Cost of input tokens in USD
+    # @!attribute [rw] output_cost
+    #   @return [BigDecimal, nil] Cost of output tokens in USD
+    # @!attribute [rw] total_cost
+    #   @return [BigDecimal, nil] Total cost in USD
+    # @!attribute [rw] parameters
+    #   @return [Hash] Sanitized parameters passed to the agent
+    # @!attribute [rw] metadata
+    #   @return [Hash] Custom metadata from execution_metadata hook
+    # @!attribute [rw] error_class
+    #   @return [String, nil] Exception class name if failed
+    # @!attribute [rw] error_message
+    #   @return [String, nil] Exception message if failed
+    #
+    # @see RubyLLM::Agents::Instrumentation
+    # @api public
     class Execution < ::ActiveRecord::Base
       self.table_name = "ruby_llm_agents_executions"
 
@@ -28,6 +59,18 @@ module RubyLLM
       # - timeout: completed due to timeout
       enum :status, %w[running success error timeout].index_by(&:itself), prefix: true
 
+      # Allowed finish reasons from LLM providers
+      FINISH_REASONS = %w[stop length content_filter tool_calls other].freeze
+
+      # Allowed fallback reasons for model switching
+      FALLBACK_REASONS = %w[price_limit quality_fail rate_limit timeout safety error other].freeze
+
+      # Execution hierarchy associations
+      belongs_to :parent_execution, class_name: "RubyLLM::Agents::Execution", optional: true
+      belongs_to :root_execution, class_name: "RubyLLM::Agents::Execution", optional: true
+      has_many :child_executions, class_name: "RubyLLM::Agents::Execution",
+               foreign_key: :parent_execution_id, dependent: :nullify, inverse_of: :parent_execution
+
       # Validations
       validates :agent_type, :model_id, :started_at, presence: true
       validates :status, inclusion: { in: statuses.keys }
@@ -36,21 +79,187 @@ module RubyLLM
       validates :input_tokens, :output_tokens, numericality: { greater_than_or_equal_to: 0 }, allow_nil: true
       validates :duration_ms, numericality: { greater_than_or_equal_to: 0 }, allow_nil: true
       validates :input_cost, :output_cost, :total_cost, numericality: { greater_than_or_equal_to: 0 }, allow_nil: true
+      validates :finish_reason, inclusion: { in: FINISH_REASONS }, allow_nil: true
+      validates :fallback_reason, inclusion: { in: FALLBACK_REASONS }, allow_nil: true
+      validates :time_to_first_token_ms, numericality: { greater_than_or_equal_to: 0 }, allow_nil: true
 
-      # Callbacks
       before_save :calculate_total_tokens, if: -> { input_tokens_changed? || output_tokens_changed? }
       before_save :calculate_total_cost, if: -> { input_cost_changed? || output_cost_changed? }
-      after_commit :broadcast_execution, on: %i[create update]
+      after_commit :broadcast_turbo_streams, on: %i[create update]
+
+      # Aggregates costs from all attempts using each attempt's model pricing
+      #
+      # Used for multi-attempt executions (retries/fallbacks) where different models
+      # may have been used. Calculates total cost by summing individual attempt costs.
+      #
+      # @return [void]
+      def aggregate_attempt_costs!
+        return if attempts.blank?
+
+        total_input_cost = 0
+        total_output_cost = 0
+
+        attempts.each do |attempt|
+          # Skip short-circuited attempts (no actual API call made)
+          next if attempt["short_circuited"]
+
+          model_info = resolve_model_info(attempt["model_id"])
+          next unless model_info&.pricing
+
+          input_price = model_info.pricing.text_tokens&.input || 0
+          output_price = model_info.pricing.text_tokens&.output || 0
+
+          input_tokens = attempt["input_tokens"] || 0
+          output_tokens = attempt["output_tokens"] || 0
+
+          total_input_cost += (input_tokens / 1_000_000.0) * input_price
+          total_output_cost += (output_tokens / 1_000_000.0) * output_price
+        end
+
+        self.input_cost = total_input_cost.round(6)
+        self.output_cost = total_output_cost.round(6)
+      end
+
+      # Returns whether this execution had multiple attempts
+      #
+      # @return [Boolean] true if more than one attempt was made
+      def has_retries?
+        (attempts_count || 0) > 1
+      end
+
+      # Returns whether this execution used fallback models
+      #
+      # @return [Boolean] true if a different model than requested succeeded
+      def used_fallback?
+        chosen_model_id.present? && chosen_model_id != model_id
+      end
+
+      # Returns the successful attempt data (if any)
+      #
+      # @return [Hash, nil] The successful attempt or nil
+      def successful_attempt
+        return nil if attempts.blank?
+
+        attempts.find { |a| a["error_class"].nil? && !a["short_circuited"] }
+      end
+
+      # Returns failed attempts
+      #
+      # @return [Array<Hash>] Failed attempt data
+      def failed_attempts
+        return [] if attempts.blank?
+
+        attempts.select { |a| a["error_class"].present? }
+      end
+
+      # Returns short-circuited attempts (circuit breaker blocked)
+      #
+      # @return [Array<Hash>] Short-circuited attempt data
+      def short_circuited_attempts
+        return [] if attempts.blank?
+
+        attempts.select { |a| a["short_circuited"] }
+      end
+
+      # Returns whether this is a root (top-level) execution
+      #
+      # @return [Boolean] true if this is a root execution
+      def root?
+        parent_execution_id.nil?
+      end
+
+      # Returns whether this is a child (nested) execution
+      #
+      # @return [Boolean] true if this has a parent execution
+      def child?
+        parent_execution_id.present?
+      end
 
-      # Broadcast execution changes via ActionCable
-      def broadcast_execution
+      # Returns the execution tree depth
+      #
+      # @return [Integer] depth level (0 for root)
+      def depth
+        return 0 if root?
+
+        parent_execution&.depth.to_i + 1
+      end
+
+      # Returns whether this execution was a cache hit
+      #
+      # @return [Boolean] true if response was served from cache
+      def cached?
+        cache_hit == true
+      end
+
+      # Returns whether this execution was rate limited
+      #
+      # @return [Boolean] true if rate limiting occurred
+      def rate_limited?
+        rate_limited == true
+      end
+
+      # Returns whether this execution used streaming
+      #
+      # @return [Boolean] true if streaming was enabled
+      def streaming?
+        streaming == true
+      end
+
+      # Returns whether the response was truncated due to max_tokens
+      #
+      # @return [Boolean] true if hit token limit
+      def truncated?
+        finish_reason == "length"
+      end
+
+      # Returns whether the response was blocked by content filter
+      #
+      # @return [Boolean] true if blocked by safety filter
+      def content_filtered?
+        finish_reason == "content_filter"
+      end
+
+      # Returns real-time dashboard data for the Now Strip
+      #
+      # @return [Hash] Now strip metrics
+      def self.now_strip_data
+        today_scope = today
+        {
+          running: running.count,
+          success_today: today_scope.status_success.count,
+          errors_today: today_scope.status_error.count,
+          timeouts_today: today_scope.status_timeout.count,
+          cost_today: today_scope.sum(:total_cost) || 0,
+          executions_today: today_scope.count,
+          success_rate: calculate_today_success_rate
+        }
+      end
+
+      # Calculates today's success rate
+      #
+      # @return [Float] Success rate as percentage
+      def self.calculate_today_success_rate
+        total = today.count
+        return 0.0 if total.zero?
+
+        (today.successful.count.to_f / total * 100).round(1)
+      end
+
+      # Broadcasts execution changes via ActionCable for real-time dashboard updates
+      #
+      # Sends JSON with action, id, status, and rendered HTML partials.
+      # The JavaScript client handles DOM updates based on the action type.
+      #
+      # @return [void]
+      def broadcast_turbo_streams
         ActionCable.server.broadcast(
           "ruby_llm_agents:executions",
           {
             action: previously_new_record? ? "created" : "updated",
             id: id,
             status: status,
-            html: render_execution_html
+            html: render_execution_html,
+            now_strip_html: render_now_strip_html
           }
         )
       rescue StandardError => e
@@ -59,23 +268,57 @@ module RubyLLM
 
       private
 
+      # Renders the execution item partial for broadcast
+      #
+      # @return [String, nil] HTML string or nil if rendering fails
       def render_execution_html
         ApplicationController.render(
           partial: "rubyllm/agents/dashboard/execution_item",
           locals: { execution: self }
         )
       rescue StandardError
-        # Partial may not exist in all contexts
         nil
       end
 
+      # Renders the Now Strip values partial for broadcast
+      #
+      # @return [String, nil] HTML string or nil if rendering fails
+      def render_now_strip_html
+        ApplicationController.render(
+          partial: "rubyllm/agents/dashboard/now_strip_values",
+          locals: { now_strip: self.class.now_strip_data }
+        )
+      rescue StandardError
+        nil
+      end
+
+      # Calculates and sets total_tokens from input and output
+      #
+      # @return [Integer] The calculated total
       def calculate_total_tokens
         self.total_tokens = (input_tokens || 0) + (output_tokens || 0)
       end
 
+      # Calculates and sets total_cost from input and output costs
+      #
+      # @return [BigDecimal] The calculated total
       def calculate_total_cost
         self.total_cost = (input_cost || 0) + (output_cost || 0)
       end
+
+      # Resolves model info for cost calculation
+      #
+      # @param lookup_model_id [String, nil] The model identifier (defaults to self.model_id)
+      # @return [Object, nil] Model info or nil
+      def resolve_model_info(lookup_model_id = nil)
+        lookup_model_id ||= model_id
+        return nil unless lookup_model_id
+
+        model, _provider = RubyLLM::Models.resolve(lookup_model_id)
+        model
+      rescue StandardError
+        nil
+      end
     end
   end
 end