ruby_llm-agents 0.3.4 → 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
@@ -123,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
 

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

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

@@ -95,6 +95,28 @@ module RubyLLM
           end
         end
 
+        # Returns only regular agents (non-workflows)
+        #
+        # @return [Array<Hash>] Agent info hashes for non-workflow agents
+        def agents_only
+          all_with_details.reject { |a| a[:is_workflow] }
+        end
+
+        # Returns only workflows
+        #
+        # @return [Array<Hash>] Agent info hashes for workflows only
+        def workflows_only
+          all_with_details.select { |a| a[:is_workflow] }
+        end
+
+        # Returns workflows filtered by type
+        #
+        # @param type [String, Symbol] The workflow type (pipeline, parallel, router)
+        # @return [Array<Hash>] Filtered workflow info hashes
+        def workflows_by_type(type)
+          workflows_only.select { |w| w[:workflow_type] == type.to_s }
+        end
+
         # Builds detailed info hash for an agent
         #
         # @param agent_type [String] The agent class name
@@ -103,17 +125,27 @@ module RubyLLM
           agent_class = find(agent_type)
           stats = fetch_stats(agent_type)
 
+          # Check if this is a workflow class vs a regular agent
+          is_workflow = agent_class&.ancestors&.any? { |a| a.name&.include?("Workflow") }
+
+          # Determine specific workflow type and children
+          workflow_type = is_workflow ? detect_workflow_type(agent_class) : nil
+          workflow_children = is_workflow ? extract_workflow_children(agent_class) : []
+
           {
             name: agent_type,
             class: agent_class,
             active: agent_class.present?,
-            version: agent_class&.version || "N/A",
-            model: agent_class&.model || "N/A",
-            temperature: agent_class&.temperature,
-            timeout: agent_class&.timeout,
-            cache_enabled: agent_class&.cache_enabled? || false,
-            cache_ttl: agent_class&.cache_ttl,
-            params: agent_class&.params || {},
+            is_workflow: is_workflow,
+            workflow_type: workflow_type,
+            workflow_children: workflow_children,
+            version: safe_call(agent_class, :version) || "N/A",
+            model: safe_call(agent_class, :model) || (is_workflow ? "workflow" : "N/A"),
+            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) || {},
             execution_count: stats[:count],
             total_cost: stats[:total_cost],
             total_tokens: stats[:total_tokens],
@@ -124,6 +156,20 @@ module RubyLLM
           }
         end
 
+        # Safely calls a method on a class, returning nil if method doesn't exist
+        #
+        # @param klass [Class, nil] The class to call the method on
+        # @param method_name [Symbol] The method to call
+        # @return [Object, nil] The result or nil
+        def safe_call(klass, method_name)
+          return nil unless klass
+          return nil unless klass.respond_to?(method_name)
+
+          klass.public_send(method_name)
+        rescue StandardError
+          nil
+        end
+
         # Fetches statistics for an agent
         #
         # @param agent_type [String] The agent class name
@@ -143,6 +189,71 @@ module RubyLLM
         rescue StandardError
           nil
         end
+
+        # Detects the specific workflow type from class hierarchy
+        #
+        # @param agent_class [Class, nil] The agent class
+        # @return [String, nil] "pipeline", "parallel", "router", or nil
+        def detect_workflow_type(agent_class)
+          return nil unless agent_class
+
+          ancestors = agent_class.ancestors.map { |a| a.name.to_s }
+
+          if ancestors.include?("RubyLLM::Agents::Workflow::Pipeline")
+            "pipeline"
+          elsif ancestors.include?("RubyLLM::Agents::Workflow::Parallel")
+            "parallel"
+          elsif ancestors.include?("RubyLLM::Agents::Workflow::Router")
+            "router"
+          end
+        end
+
+        # Extracts child agents from workflow DSL configuration
+        #
+        # @param agent_class [Class, nil] The workflow class
+        # @return [Array<Hash>] Array of child info hashes with :name, :agent, :type, :optional keys
+        def extract_workflow_children(agent_class)
+          return [] unless agent_class
+
+          children = []
+
+          if agent_class.respond_to?(:steps) && agent_class.steps.any?
+            # Pipeline workflow - extract steps
+            agent_class.steps.each do |name, config|
+              children << {
+                name: name,
+                agent: config[:agent]&.name,
+                type: "step",
+                optional: config[:continue_on_error] || false
+              }
+            end
+          elsif agent_class.respond_to?(:branches) && agent_class.branches.any?
+            # Parallel workflow - extract branches
+            agent_class.branches.each do |name, config|
+              children << {
+                name: name,
+                agent: config[:agent]&.name,
+                type: "branch",
+                optional: config[:optional] || false
+              }
+            end
+          elsif agent_class.respond_to?(:routes) && agent_class.routes.any?
+            # Router workflow - extract routes
+            agent_class.routes.each do |name, config|
+              children << {
+                name: name,
+                agent: config[:agent]&.name,
+                type: "route",
+                description: config[:description]
+              }
+            end
+          end
+
+          children
+        rescue StandardError => e
+          Rails.logger.error("[RubyLLM::Agents] Error extracting workflow children: #{e.message}")
+          []
+        end
       end
     end
   end