ruby_llm-agents 0.3.3 → 0.3.5

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

@@ -0,0 +1,299 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    class Execution
+      # Workflow concern for workflow-related methods and aggregate calculations
+      #
+      # Provides instance methods for determining workflow type, calculating
+      # aggregate statistics across child executions, and retrieving workflow
+      # step/branch information.
+      #
+      # @see RubyLLM::Agents::Execution
+      # @api public
+      module Workflow
+        extend ActiveSupport::Concern
+
+        # Returns whether this is a workflow execution (has workflow_type)
+        #
+        # @return [Boolean] true if this is a workflow execution
+        def workflow?
+          workflow_type.present?
+        end
+
+        # Returns whether this is a pipeline workflow
+        #
+        # @return [Boolean] true if workflow_type is "pipeline"
+        def pipeline_workflow?
+          workflow_type == "pipeline"
+        end
+
+        # Returns whether this is a parallel workflow
+        #
+        # @return [Boolean] true if workflow_type is "parallel"
+        def parallel_workflow?
+          workflow_type == "parallel"
+        end
+
+        # Returns whether this is a router workflow
+        #
+        # @return [Boolean] true if workflow_type is "router"
+        def router_workflow?
+          workflow_type == "router"
+        end
+
+        # Returns whether this is a root workflow execution (top-level)
+        #
+        # @return [Boolean] true if this is a workflow with no parent
+        def root_workflow?
+          workflow? && root?
+        end
+
+        # Returns all workflow steps/branches ordered by creation time
+        #
+        # @return [ActiveRecord::Relation] Child executions for this workflow
+        def workflow_steps
+          child_executions.order(:created_at)
+        end
+
+        # Returns the count of child workflow steps
+        #
+        # @return [Integer] Number of child executions
+        def workflow_steps_count
+          child_executions.count
+        end
+
+        # @!group Aggregate Statistics
+
+        # Returns aggregate stats for all child executions
+        #
+        # @return [Hash] Aggregated metrics including cost, tokens, duration
+        def workflow_aggregate_stats
+          return @workflow_aggregate_stats if defined?(@workflow_aggregate_stats)
+
+          children = child_executions.to_a
+          return empty_aggregate_stats if children.empty?
+
+          @workflow_aggregate_stats = {
+            total_cost: children.sum { |c| c.total_cost || 0 },
+            total_tokens: children.sum { |c| c.total_tokens || 0 },
+            input_tokens: children.sum { |c| c.input_tokens || 0 },
+            output_tokens: children.sum { |c| c.output_tokens || 0 },
+            total_duration_ms: children.sum { |c| c.duration_ms || 0 },
+            wall_clock_ms: calculate_wall_clock_duration(children),
+            steps_count: children.size,
+            successful_count: children.count(&:status_success?),
+            failed_count: children.count(&:status_error?),
+            timeout_count: children.count(&:status_timeout?),
+            running_count: children.count(&:status_running?),
+            success_rate: calculate_success_rate(children),
+            models_used: children.map(&:model_id).uniq.compact
+          }
+        end
+
+        # Returns aggregate total cost across all child executions
+        #
+        # @return [Float] Total cost in USD
+        def workflow_total_cost
+          workflow_aggregate_stats[:total_cost]
+        end
+
+        # Returns aggregate total tokens across all child executions
+        #
+        # @return [Integer] Total tokens used
+        def workflow_total_tokens
+          workflow_aggregate_stats[:total_tokens]
+        end
+
+        # Returns the wall-clock duration (from first start to last completion)
+        #
+        # @return [Integer, nil] Duration in milliseconds
+        def workflow_wall_clock_ms
+          workflow_aggregate_stats[:wall_clock_ms]
+        end
+
+        # Returns the sum of all step durations (may exceed wall-clock for parallel)
+        #
+        # @return [Integer] Sum of all durations in milliseconds
+        def workflow_sum_duration_ms
+          workflow_aggregate_stats[:total_duration_ms]
+        end
+
+        # Returns the overall workflow status based on child executions
+        #
+        # @return [Symbol] :success, :error, :timeout, :running, or :pending
+        def workflow_overall_status
+          stats = workflow_aggregate_stats
+          return :pending if stats[:steps_count].zero?
+          return :running if stats[:running_count] > 0
+          return :error if stats[:failed_count] > 0
+          return :timeout if stats[:timeout_count] > 0
+
+          :success
+        end
+
+        # @!endgroup
+
+        # @!group Pipeline-specific Methods
+
+        # Returns pipeline steps in order with their status
+        #
+        # @return [Array<Hash>] Array of step hashes with name, status, duration, cost
+        def pipeline_steps_detail
+          return [] unless pipeline_workflow?
+
+          workflow_steps.map do |step|
+            {
+              id: step.id,
+              name: step.workflow_step || step.agent_type.gsub(/Agent$/, ""),
+              agent_type: step.agent_type,
+              status: step.status,
+              duration_ms: step.duration_ms,
+              total_cost: step.total_cost,
+              total_tokens: step.total_tokens,
+              model_id: step.model_id
+            }
+          end
+        end
+
+        # @!endgroup
+
+        # @!group Parallel-specific Methods
+
+        # Returns parallel branches with their status and timing
+        #
+        # @return [Array<Hash>] Array of branch hashes
+        def parallel_branches_detail
+          return [] unless parallel_workflow?
+
+          branches = workflow_steps.to_a
+          return [] if branches.empty?
+
+          # Find min/max for timing comparison
+          min_duration = branches.map { |b| b.duration_ms || 0 }.min
+          max_duration = branches.map { |b| b.duration_ms || 0 }.max
+
+          branches.map do |branch|
+            duration = branch.duration_ms || 0
+            {
+              id: branch.id,
+              name: branch.workflow_step || branch.agent_type.gsub(/Agent$/, ""),
+              agent_type: branch.agent_type,
+              status: branch.status,
+              duration_ms: duration,
+              total_cost: branch.total_cost,
+              total_tokens: branch.total_tokens,
+              model_id: branch.model_id,
+              is_fastest: duration == min_duration && branches.size > 1,
+              is_slowest: duration == max_duration && branches.size > 1 && min_duration != max_duration
+            }
+          end
+        end
+
+        # @!endgroup
+
+        # @!group Router-specific Methods
+
+        # Returns router classification details
+        #
+        # @return [Hash] Classification info including method, model, timing
+        def router_classification_detail
+          return {} unless router_workflow?
+
+          result = if classification_result.is_a?(String)
+                     begin
+                       JSON.parse(classification_result)
+                     rescue JSON::ParserError
+                       {}
+                     end
+                   else
+                     classification_result || {}
+                   end
+
+          {
+            method: result["method"],
+            classifier_model: result["classifier_model"],
+            classification_time_ms: result["classification_time_ms"],
+            routed_to: routed_to,
+            confidence: result["confidence"]
+          }
+        end
+
+        # Returns available routes and which one was chosen
+        #
+        # @return [Hash] Routes info with chosen route highlighted
+        def router_routes_detail
+          return {} unless router_workflow?
+
+          # Get the routed execution (child)
+          routed_child = child_executions.first
+
+          {
+            chosen_route: routed_to,
+            routed_execution: routed_child ? {
+              id: routed_child.id,
+              agent_type: routed_child.agent_type,
+              status: routed_child.status,
+              duration_ms: routed_child.duration_ms,
+              total_cost: routed_child.total_cost
+            } : nil
+          }
+        end
+
+        # @!endgroup
+
+        private
+
+        # Returns empty aggregate stats hash
+        #
+        # @return [Hash] Empty stats with zero values
+        def empty_aggregate_stats
+          {
+            total_cost: 0,
+            total_tokens: 0,
+            input_tokens: 0,
+            output_tokens: 0,
+            total_duration_ms: 0,
+            wall_clock_ms: nil,
+            steps_count: 0,
+            successful_count: 0,
+            failed_count: 0,
+            timeout_count: 0,
+            running_count: 0,
+            success_rate: 0.0,
+            models_used: []
+          }
+        end
+
+        # Calculates wall-clock duration from child executions
+        #
+        # @param children [Array<Execution>] Child executions
+        # @return [Integer, nil] Duration in milliseconds
+        def calculate_wall_clock_duration(children)
+          started_times = children.map(&:started_at).compact
+          completed_times = children.map(&:completed_at).compact
+
+          return nil if started_times.empty? || completed_times.empty?
+
+          first_start = started_times.min
+          last_complete = completed_times.max
+
+          ((last_complete - first_start) * 1000).round
+        end
+
+        # Calculates success rate from children
+        #
+        # @param children [Array<Execution>] Child executions
+        # @return [Float] Success rate as percentage
+        def calculate_success_rate(children)
+          return 0.0 if children.empty?
+
+          completed = children.reject(&:status_running?)
+          return 0.0 if completed.empty?
+
+          (completed.count(&:status_success?).to_f / completed.size * 100).round(1)
+        end
+      end
+    end
+  end
+end

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

@@ -51,6 +51,7 @@ module RubyLLM
       include Execution::Metrics
       include Execution::Scopes
       include Execution::Analytics
+      include Execution::Workflow
 
       # Status enum
       # - running: execution in progress
@@ -85,7 +86,6 @@ module RubyLLM
 
       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_turbo_streams, on: %i[create update]
 
       # Aggregates costs from all attempts using each attempt's model pricing
       #
@@ -124,13 +124,20 @@ module RubyLLM
       #
       # @return [Boolean] true if more than one attempt was made
       def has_retries?
-        (attempts_count || 0) > 1
+        count = if self.class.column_names.include?("attempts_count")
+                  attempts_count
+                elsif self.class.column_names.include?("attempts")
+                  attempts&.size
+                end
+        (count || 0) > 1
       end
 
       # Returns whether this execution used fallback models
       #
       # @return [Boolean] true if a different model than requested succeeded
       def used_fallback?
+        return false unless self.class.column_names.include?("chosen_model_id")
+
         chosen_model_id.present? && chosen_model_id != model_id
       end
 
@@ -228,77 +235,39 @@ module RubyLLM
 
       # Returns real-time dashboard data for the Now Strip
       #
+      # @param range [String] Time range: "today", "7d", or "30d"
       # @return [Hash] Now strip metrics
-      def self.now_strip_data
-        today_scope = today
+      def self.now_strip_data(range: "today")
+        scope = case range
+                when "7d" then last_n_days(7)
+                when "30d" then last_n_days(30)
+                else today
+                end
+
         {
           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
+          success_today: scope.status_success.count,
+          errors_today: scope.status_error.count,
+          timeouts_today: scope.status_timeout.count,
+          cost_today: scope.sum(:total_cost) || 0,
+          executions_today: scope.count,
+          success_rate: calculate_period_success_rate(scope)
         }
       end
 
-      # Calculates today's success rate
+      # Calculates success rate for a given scope
       #
+      # @param scope [ActiveRecord::Relation] The execution scope
       # @return [Float] Success rate as percentage
-      def self.calculate_today_success_rate
-        total = today.count
+      def self.calculate_period_success_rate(scope)
+        total = scope.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,
-            now_strip_html: render_now_strip_html
-          }
-        )
-      rescue StandardError => e
-        Rails.logger.error("[RubyLLM::Agents] Failed to broadcast execution: #{e.message}")
+        (scope.successful.count.to_f / total * 100).round(1)
       end
 
       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
-        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

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

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    # Database-backed budget configuration for multi-tenant environments
+    #
+    # Stores per-tenant budget limits that override the global configuration.
+    # Supports runtime updates without application restarts.
+    #
+    # @!attribute [rw] tenant_id
+    #   @return [String] Unique identifier for the tenant
+    # @!attribute [rw] daily_limit
+    #   @return [BigDecimal, nil] Daily budget limit in USD
+    # @!attribute [rw] monthly_limit
+    #   @return [BigDecimal, nil] Monthly budget limit in USD
+    # @!attribute [rw] per_agent_daily
+    #   @return [Hash] Per-agent daily limits: { "AgentName" => limit }
+    # @!attribute [rw] per_agent_monthly
+    #   @return [Hash] Per-agent monthly limits: { "AgentName" => limit }
+    # @!attribute [rw] enforcement
+    #   @return [String] Enforcement mode: "none", "soft", or "hard"
+    # @!attribute [rw] inherit_global_defaults
+    #   @return [Boolean] Whether to fall back to global config for unset limits
+    #
+    # @example Creating a tenant budget
+    #   TenantBudget.create!(
+    #     tenant_id: "acme_corp",
+    #     daily_limit: 50.0,
+    #     monthly_limit: 500.0,
+    #     per_agent_daily: { "ContentAgent" => 10.0 },
+    #     enforcement: "hard"
+    #   )
+    #
+    # @example Fetching budget for a tenant
+    #   budget = TenantBudget.for_tenant("acme_corp")
+    #   budget.effective_daily_limit  # => 50.0
+    #
+    # @see RubyLLM::Agents::BudgetTracker
+    # @api public
+    class TenantBudget < ::ActiveRecord::Base
+      self.table_name = "ruby_llm_agents_tenant_budgets"
+
+      # Valid enforcement modes
+      ENFORCEMENT_MODES = %w[none soft hard].freeze
+
+      # Validations
+      validates :tenant_id, presence: true, uniqueness: true
+      validates :enforcement, inclusion: { in: ENFORCEMENT_MODES }, allow_nil: true
+      validates :daily_limit, :monthly_limit,
+                numericality: { greater_than_or_equal_to: 0 }, allow_nil: true
+
+      # Finds a budget for the given tenant
+      #
+      # @param tenant_id [String] The tenant identifier
+      # @return [TenantBudget, nil] The budget record or nil if not found
+      def self.for_tenant(tenant_id)
+        return nil if tenant_id.blank?
+
+        find_by(tenant_id: tenant_id)
+      end
+
+      # Returns the effective daily limit, considering inheritance
+      #
+      # @return [Float, nil] The daily limit or nil if not set
+      def effective_daily_limit
+        return daily_limit if daily_limit.present?
+        return nil unless inherit_global_defaults
+
+        global_config&.dig(:global_daily)
+      end
+
+      # Returns the effective monthly limit, considering inheritance
+      #
+      # @return [Float, nil] The monthly limit or nil if not set
+      def effective_monthly_limit
+        return monthly_limit if monthly_limit.present?
+        return nil unless inherit_global_defaults
+
+        global_config&.dig(:global_monthly)
+      end
+
+      # Returns the effective per-agent daily limit
+      #
+      # @param agent_type [String] The agent class name
+      # @return [Float, nil] The limit or nil if not set
+      def effective_per_agent_daily(agent_type)
+        limit = per_agent_daily&.dig(agent_type)
+        return limit if limit.present?
+        return nil unless inherit_global_defaults
+
+        global_config&.dig(:per_agent_daily, agent_type)
+      end
+
+      # Returns the effective per-agent monthly limit
+      #
+      # @param agent_type [String] The agent class name
+      # @return [Float, nil] The limit or nil if not set
+      def effective_per_agent_monthly(agent_type)
+        limit = per_agent_monthly&.dig(agent_type)
+        return limit if limit.present?
+        return nil unless inherit_global_defaults
+
+        global_config&.dig(:per_agent_monthly, agent_type)
+      end
+
+      # Returns the effective enforcement mode
+      #
+      # @return [Symbol] :none, :soft, or :hard
+      def effective_enforcement
+        return enforcement.to_sym if enforcement.present?
+        return :soft unless inherit_global_defaults
+
+        RubyLLM::Agents.configuration.budget_enforcement
+      end
+
+      # Checks if budget enforcement is enabled for this tenant
+      #
+      # @return [Boolean] true if enforcement is :soft or :hard
+      def budgets_enabled?
+        effective_enforcement != :none
+      end
+
+      # Returns a hash suitable for BudgetTracker
+      #
+      # @return [Hash] Budget configuration hash
+      def to_budget_config
+        {
+          enabled: budgets_enabled?,
+          enforcement: effective_enforcement,
+          global_daily: effective_daily_limit,
+          global_monthly: effective_monthly_limit,
+          per_agent_daily: merged_per_agent_daily,
+          per_agent_monthly: merged_per_agent_monthly
+        }
+      end
+
+      private
+
+      # Returns the global budgets configuration
+      #
+      # @return [Hash, nil] Global budget config
+      def global_config
+        RubyLLM::Agents.configuration.budgets
+      end
+
+      # Merges per-agent daily limits with global defaults
+      #
+      # @return [Hash] Merged per-agent daily limits
+      def merged_per_agent_daily
+        return per_agent_daily || {} unless inherit_global_defaults
+
+        (global_config&.dig(:per_agent_daily) || {}).merge(per_agent_daily || {})
+      end
+
+      # Merges per-agent monthly limits with global defaults
+      #
+      # @return [Hash] Merged per-agent monthly limits
+      def merged_per_agent_monthly
+        return per_agent_monthly || {} unless inherit_global_defaults
+
+        (global_config&.dig(:per_agent_monthly) || {}).merge(per_agent_monthly || {})
+      end
+    end
+  end
+end