ruby_llm-agents 0.5.0 → 1.0.0

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

@@ -0,0 +1,355 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    # Controller for viewing workflow details and per-workflow analytics
+    #
+    # Provides detailed views for individual workflows including structure
+    # visualization, per-step/branch performance, route distribution,
+    # and execution history.
+    #
+    # @see AgentRegistry For workflow discovery
+    # @see Paginatable For pagination implementation
+    # @see Filterable For filter parsing and validation
+    # @api private
+    class WorkflowsController < ApplicationController
+      include Paginatable
+      include Filterable
+
+      # Shows detailed view for a specific workflow
+      #
+      # Loads workflow configuration (if class exists), statistics,
+      # filtered executions, chart data, and step-level analytics.
+      # Works for both active workflows and deleted workflows with history.
+      #
+      # @return [void]
+      def show
+        @workflow_type = CGI.unescape(params[:id])
+        @workflow_class = AgentRegistry.find(@workflow_type)
+        @workflow_active = @workflow_class.present?
+
+        # Determine workflow type from class or execution history
+        @workflow_type_kind = detect_workflow_type_kind
+
+        load_workflow_stats
+        load_filter_options
+        load_filtered_executions
+        load_chart_data
+        load_step_stats
+
+        if @workflow_class
+          load_workflow_config
+        end
+      rescue StandardError => e
+        Rails.logger.error("[RubyLLM::Agents] Error loading workflow #{@workflow_type}: #{e.message}")
+        redirect_to ruby_llm_agents.agents_path, alert: "Error loading workflow details"
+      end
+
+      private
+
+      # Detects the workflow type kind (pipeline, parallel, router)
+      #
+      # @return [String, nil] The workflow type kind
+      def detect_workflow_type_kind
+        if @workflow_class
+          ancestors = @workflow_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
+        else
+          # Fallback to execution history
+          Execution.by_agent(@workflow_type)
+                   .where.not(workflow_type: nil)
+                   .pluck(:workflow_type)
+                   .first
+        end
+      end
+
+      # Loads all-time and today's statistics for the workflow
+      #
+      # @return [void]
+      def load_workflow_stats
+        @stats = Execution.stats_for(@workflow_type, period: :all_time)
+        @stats_today = Execution.stats_for(@workflow_type, period: :today)
+
+        # Additional stats for new schema fields
+        workflow_scope = Execution.by_agent(@workflow_type)
+        @cache_hit_rate = workflow_scope.cache_hit_rate
+        @streaming_rate = workflow_scope.streaming_rate
+        @avg_ttft = workflow_scope.avg_time_to_first_token
+      end
+
+      # Loads available filter options from execution history
+      #
+      # @return [void]
+      def load_filter_options
+        filter_data = Execution.by_agent(@workflow_type)
+                               .where.not(agent_version: nil)
+                               .or(Execution.by_agent(@workflow_type).where.not(model_id: nil))
+                               .or(Execution.by_agent(@workflow_type).where.not(temperature: nil))
+                               .pluck(:agent_version, :model_id, :temperature)
+
+        @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
+      #
+      # @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 workflow's executions
+      #
+      # @return [ActiveRecord::Relation] Filtered execution scope
+      def build_filtered_scope
+        scope = Execution.by_agent(@workflow_type)
+
+        # Apply status filter with validation
+        statuses = parse_array_param(:statuses)
+        scope = apply_status_filter(scope, statuses) if statuses.any?
+
+        # Apply version filter
+        versions = parse_array_param(:versions)
+        scope = scope.where(agent_version: versions) if versions.any?
+
+        # Apply model filter
+        models = parse_array_param(:models)
+        scope = scope.where(model_id: models) if models.any?
+
+        # Apply temperature filter
+        temperatures = parse_array_param(:temperatures)
+        scope = scope.where(temperature: temperatures) if temperatures.any?
+
+        # Apply time range filter with validation
+        days = parse_days_param
+        scope = apply_time_filter(scope, days)
+
+        scope
+      end
+
+      # Loads chart data for workflow performance visualization
+      #
+      # @return [void]
+      def load_chart_data
+        @trend_data = Execution.trend_analysis(agent_type: @workflow_type, days: 30)
+        @status_distribution = Execution.by_agent(@workflow_type).group(:status).count
+        @finish_reason_distribution = Execution.by_agent(@workflow_type).finish_reason_distribution
+      end
+
+      # Loads per-step/branch statistics for workflow analytics
+      #
+      # @return [void]
+      def load_step_stats
+        @step_stats = calculate_step_stats
+        @route_distribution = calculate_route_distribution if @workflow_type_kind == "router"
+      end
+
+      # Calculates per-step/branch performance statistics
+      #
+      # @return [Array<Hash>] Array of step stats hashes
+      def calculate_step_stats
+        # Get root workflow executions
+        root_executions = Execution.by_agent(@workflow_type)
+                                   .root_executions
+                                   .where("created_at > ?", 30.days.ago)
+                                   .pluck(:id)
+
+        return [] if root_executions.empty?
+
+        # Aggregate child execution stats by workflow_step
+        child_stats = Execution.where(parent_execution_id: root_executions)
+                               .group(:workflow_step)
+                               .select(
+                                 "workflow_step",
+                                 "COUNT(*) as execution_count",
+                                 "AVG(duration_ms) as avg_duration_ms",
+                                 "SUM(total_cost) as total_cost",
+                                 "AVG(total_cost) as avg_cost",
+                                 "SUM(total_tokens) as total_tokens",
+                                 "AVG(total_tokens) as avg_tokens",
+                                 "SUM(CASE WHEN status = 'success' THEN 1 ELSE 0 END) as success_count",
+                                 "SUM(CASE WHEN status = 'error' THEN 1 ELSE 0 END) as error_count"
+                               )
+
+        # Get agent type mappings for each step
+        step_agent_map = Execution.where(parent_execution_id: root_executions)
+                                  .where.not(workflow_step: nil)
+                                  .group(:workflow_step)
+                                  .pluck(:workflow_step, Arel.sql("MAX(agent_type)"))
+                                  .to_h
+
+        child_stats.map do |row|
+          next if row.workflow_step.blank?
+
+          execution_count = row.execution_count.to_i
+          success_count = row.success_count.to_i
+          success_rate = execution_count > 0 ? (success_count.to_f / execution_count * 100).round(1) : 0
+
+          {
+            name: row.workflow_step,
+            agent_type: step_agent_map[row.workflow_step],
+            execution_count: execution_count,
+            success_rate: success_rate,
+            avg_duration_ms: row.avg_duration_ms.to_f.round(0),
+            total_cost: row.total_cost.to_f.round(4),
+            avg_cost: row.avg_cost.to_f.round(6),
+            total_tokens: row.total_tokens.to_i,
+            avg_tokens: row.avg_tokens.to_f.round(0)
+          }
+        end.compact
+      end
+
+      # Calculates route distribution for router workflows
+      #
+      # @return [Hash] Route distribution data
+      def calculate_route_distribution
+        # Get route distribution from routed_to field
+        distribution = Execution.by_agent(@workflow_type)
+                                .where("created_at > ?", 30.days.ago)
+                                .where.not(routed_to: nil)
+                                .group(:routed_to)
+                                .count
+
+        total = distribution.values.sum
+        return {} if total.zero?
+
+        # Add percentage and sorting
+        distribution.transform_values do |count|
+          {
+            count: count,
+            percentage: (count.to_f / total * 100).round(1)
+          }
+        end.sort_by { |_k, v| -v[:count] }.to_h
+      end
+
+      # Loads the current workflow class configuration
+      #
+      # @return [void]
+      def load_workflow_config
+        @config = {
+          # Basic configuration
+          version: safe_call(@workflow_class, :version),
+          description: safe_call(@workflow_class, :description),
+          timeout: safe_call(@workflow_class, :timeout),
+          max_cost: safe_call(@workflow_class, :max_cost)
+        }
+
+        # Workflow-specific configuration
+        case @workflow_type_kind
+        when "pipeline"
+          load_pipeline_config
+        when "parallel"
+          load_parallel_config
+        when "router"
+          load_router_config
+        end
+      end
+
+      # Loads pipeline-specific configuration
+      #
+      # @return [void]
+      def load_pipeline_config
+        @steps = extract_steps(@workflow_class)
+        @config[:steps_count] = @steps.size
+      end
+
+      # Loads parallel-specific configuration
+      #
+      # @return [void]
+      def load_parallel_config
+        @branches = extract_branches(@workflow_class)
+        @config[:branches_count] = @branches.size
+        @config[:fail_fast] = safe_call(@workflow_class, :fail_fast?)
+      end
+
+      # Loads router-specific configuration
+      #
+      # @return [void]
+      def load_router_config
+        @routes = extract_routes(@workflow_class)
+        @config[:routes_count] = @routes.size
+        @config[:classifier_model] = safe_call(@workflow_class, :classifier_model)
+        @config[:classifier_temperature] = safe_call(@workflow_class, :classifier_temperature)
+      end
+
+      # Extracts steps from a pipeline workflow class
+      #
+      # @param klass [Class] The workflow class
+      # @return [Array<Hash>] Array of step hashes
+      def extract_steps(klass)
+        return [] unless klass.respond_to?(:steps)
+
+        klass.steps.map do |name, config|
+          {
+            name: name,
+            agent: config[:agent]&.name,
+            optional: config[:continue_on_error] || false
+          }
+        end
+      end
+
+      # Extracts branches from a parallel workflow class
+      #
+      # @param klass [Class] The workflow class
+      # @return [Array<Hash>] Array of branch hashes
+      def extract_branches(klass)
+        return [] unless klass.respond_to?(:branches)
+
+        klass.branches.map do |name, config|
+          {
+            name: name,
+            agent: config[:agent]&.name,
+            optional: config[:optional] || false
+          }
+        end
+      end
+
+      # Extracts routes from a router workflow class
+      #
+      # @param klass [Class] The workflow class
+      # @return [Array<Hash>] Array of route hashes
+      def extract_routes(klass)
+        return [] unless klass.respond_to?(:routes)
+
+        klass.routes.map do |name, config|
+          {
+            name: name,
+            agent: config[:agent]&.name,
+            description: config[:description],
+            default: config[:default] || false
+          }
+        end
+      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
+    end
+  end
+end

data/app/helpers/ruby_llm/agents/application_helper.rb

@@ -24,6 +24,31 @@ module RubyLLM
         RubyLLM::Agents::Engine.routes.url_helpers
       end
 
+      # Returns the URL for "All Tenants" (clears tenant filter)
+      #
+      # Handles two scenarios:
+      # 1. Query param routes - removes tenant_id from query params
+      # 2. Path-based tenant routes - navigates to equivalent global route
+      #
+      # @return [String] URL without tenant filtering
+      def all_tenants_url
+        # Map tenant-specific path routes to their global equivalents
+        tenant_route_mappings = {
+          "tenant" => ruby_llm_agents.api_configuration_path,
+          "edit_tenant" => ruby_llm_agents.edit_api_configuration_path
+        }
+
+        # Check if current action has a global equivalent
+        if tenant_route_mappings.key?(action_name)
+          base_path = tenant_route_mappings[action_name]
+          query = request.query_parameters.except("tenant_id")
+          query.any? ? "#{base_path}?#{query.to_query}" : base_path
+        else
+          # For query param routes, just remove tenant_id
+          url_for(request.query_parameters.except("tenant_id"))
+        end
+      end
+
       # Formats large numbers with human-readable suffixes (K, M, B)
       #
       # @param number [Numeric, nil] The number to format

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

@@ -72,6 +72,9 @@ module RubyLLM
       has_many :child_executions, class_name: "RubyLLM::Agents::Execution",
                foreign_key: :parent_execution_id, dependent: :nullify, inverse_of: :parent_execution
 
+      # Polymorphic association to tenant model (for llm_tenant DSL)
+      belongs_to :tenant_record, polymorphic: true, optional: true
+
       # Validations
       validates :agent_type, :model_id, :started_at, presence: true
       validates :status, inclusion: { in: statuses.keys }

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

@@ -6,7 +6,7 @@ module RubyLLM
     #
     # Stores per-tenant budget limits that override the global configuration.
     # Supports runtime updates without application restarts.
-    # Supports both cost-based (USD) and token-based limits.
+    # Supports cost-based (USD), token-based, and execution-based limits.
     #
     # @!attribute [rw] tenant_id
     #   @return [String] Unique identifier for the tenant
@@ -20,6 +20,10 @@ module RubyLLM
     #   @return [Integer, nil] Daily token limit (across all models)
     # @!attribute [rw] monthly_token_limit
     #   @return [Integer, nil] Monthly token limit (across all models)
+    # @!attribute [rw] daily_execution_limit
+    #   @return [Integer, nil] Daily execution/call limit
+    # @!attribute [rw] monthly_execution_limit
+    #   @return [Integer, nil] Monthly execution/call limit
     # @!attribute [rw] per_agent_daily
     #   @return [Hash] Per-agent daily cost limits: { "AgentName" => limit }
     # @!attribute [rw] per_agent_monthly
@@ -28,25 +32,30 @@ module RubyLLM
     #   @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
+    # @!attribute [rw] tenant_record
+    #   @return [ActiveRecord::Base, nil] Polymorphic association to tenant model
     #
-    # @example Creating a tenant budget with cost and token limits
+    # @example Creating a tenant budget with cost, token, and execution limits
     #   TenantBudget.create!(
     #     tenant_id: "acme_corp",
     #     name: "Acme Corporation",
-    #     daily_limit: 50.0,           # USD
-    #     monthly_limit: 500.0,        # USD
+    #     daily_limit: 50.0,              # USD
+    #     monthly_limit: 500.0,           # USD
     #     daily_token_limit: 1_000_000,
     #     monthly_token_limit: 10_000_000,
-    #     per_agent_daily: { "ContentAgent" => 10.0 },
+    #     daily_execution_limit: 500,
+    #     monthly_execution_limit: 10_000,
     #     enforcement: "hard"
     #   )
     #
-    # @example Fetching budget for a tenant
-    #   budget = TenantBudget.for_tenant("acme_corp")
-    #   budget.effective_daily_limit        # => 50.0 (cost)
-    #   budget.effective_daily_token_limit  # => 1_000_000 (tokens)
+    # @example Fetching budget for a tenant object
+    #   budget = TenantBudget.for_tenant(organization)
+    #   budget.effective_daily_limit           # => 50.0 (cost)
+    #   budget.effective_daily_token_limit     # => 1_000_000 (tokens)
+    #   budget.effective_daily_execution_limit # => 500 (executions)
     #
     # @see RubyLLM::Agents::BudgetTracker
+    # @see RubyLLM::Agents::LLMTenant
     # @api public
     class TenantBudget < ::ActiveRecord::Base
       self.table_name = "ruby_llm_agents_tenant_budgets"
@@ -54,6 +63,9 @@ module RubyLLM
       # Valid enforcement modes
       ENFORCEMENT_MODES = %w[none soft hard].freeze
 
+      # Polymorphic association to the tenant model (e.g., Organization, Account)
+      belongs_to :tenant_record, polymorphic: true, optional: true
+
       # Validations
       validates :tenant_id, presence: true, uniqueness: true
       validates :enforcement, inclusion: { in: ENFORCEMENT_MODES }, allow_nil: true
@@ -61,15 +73,23 @@ module RubyLLM
                 numericality: { greater_than_or_equal_to: 0 }, allow_nil: true
       validates :daily_token_limit, :monthly_token_limit,
                 numericality: { greater_than_or_equal_to: 0, only_integer: true }, allow_nil: true
+      validates :daily_execution_limit, :monthly_execution_limit,
+                numericality: { greater_than_or_equal_to: 0, only_integer: true }, allow_nil: true
 
       # Finds a budget for the given tenant
       #
-      # @param tenant_id [String] The tenant identifier
+      # @param tenant [String, Object] The tenant identifier string or object with llm_tenant_id
       # @return [TenantBudget, nil] The budget record or nil if not found
-      def self.for_tenant(tenant_id)
-        return nil if tenant_id.blank?
+      def self.for_tenant(tenant)
+        return nil if tenant.blank?
 
-        find_by(tenant_id: tenant_id)
+        if tenant.respond_to?(:llm_tenant_id)
+          # Object with llm_tenant DSL - try polymorphic first, then tenant_id
+          find_by(tenant_record: tenant) || find_by(tenant_id: tenant.llm_tenant_id)
+        else
+          # String tenant_id
+          find_by(tenant_id: tenant.to_s)
+        end
       end
 
       # Finds or creates a budget for the given tenant
@@ -154,6 +174,26 @@ module RubyLLM
         global_config&.dig(:global_monthly_tokens)
       end
 
+      # Returns the effective daily execution limit, considering inheritance
+      #
+      # @return [Integer, nil] The daily execution limit or nil if not set
+      def effective_daily_execution_limit
+        return daily_execution_limit if daily_execution_limit.present?
+        return nil unless inherit_global_defaults
+
+        global_config&.dig(:global_daily_executions)
+      end
+
+      # Returns the effective monthly execution limit, considering inheritance
+      #
+      # @return [Integer, nil] The monthly execution limit or nil if not set
+      def effective_monthly_execution_limit
+        return monthly_execution_limit if monthly_execution_limit.present?
+        return nil unless inherit_global_defaults
+
+        global_config&.dig(:global_monthly_executions)
+      end
+
       # Returns the effective enforcement mode
       #
       # @return [Symbol] :none, :soft, or :hard
@@ -183,9 +223,12 @@ module RubyLLM
           global_monthly: effective_monthly_limit,
           per_agent_daily: merged_per_agent_daily,
           per_agent_monthly: merged_per_agent_monthly,
-          # Token limits (global only)
+          # Token limits
           global_daily_tokens: effective_daily_token_limit,
-          global_monthly_tokens: effective_monthly_token_limit
+          global_monthly_tokens: effective_monthly_token_limit,
+          # Execution limits
+          global_daily_executions: effective_daily_execution_limit,
+          global_monthly_executions: effective_monthly_execution_limit
         }
       end
 

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

@@ -60,12 +60,19 @@ module RubyLLM
         #
         # @return [Array<String>] Agent class names
         def file_system_agents
-          # Ensure all agent classes are loaded
+          # Ensure all agent and workflow classes are loaded
           eager_load_agents!
 
-          # Find all descendants of the base class
-          base_class = RubyLLM::Agents::Base
-          base_class.descendants.map(&:name).compact
+          # Find all descendants of all base classes
+          agents = RubyLLM::Agents::Base.descendants.map(&:name).compact
+          workflows = RubyLLM::Agents::Workflow.descendants.map(&:name).compact
+          embedders = RubyLLM::Agents::Embedder.descendants.map(&:name).compact
+          moderators = RubyLLM::Agents::Moderator.descendants.map(&:name).compact
+          speakers = RubyLLM::Agents::Speaker.descendants.map(&:name).compact
+          transcribers = RubyLLM::Agents::Transcriber.descendants.map(&:name).compact
+          image_generators = RubyLLM::Agents::ImageGenerator.descendants.map(&:name).compact
+
+          (agents + workflows + embedders + moderators + speakers + transcribers + image_generators).uniq
         rescue StandardError => e
           Rails.logger.error("[RubyLLM::Agents] Error loading agents from file system: #{e.message}")
           []
@@ -81,17 +88,19 @@ module RubyLLM
           []
         end
 
-        # Eager loads all agent files to register descendants
+        # Eager loads all agent and workflow files to register descendants
         #
         # @return [void]
         def eager_load_agents!
-          agents_path = Rails.root.join("app", "agents")
-          return unless agents_path.exist?
+          %w[agents workflows embedders moderators speakers transcribers image_generators].each do |dir|
+            path = Rails.root.join("app", dir)
+            next unless path.exist?
 
-          Dir.glob(agents_path.join("**", "*.rb")).each do |file|
-            require_dependency file
-          rescue LoadError, StandardError => e
-            Rails.logger.error("[RubyLLM::Agents] Failed to load agent file #{file}: #{e.message}")
+            Dir.glob(path.join("**", "*.rb")).each do |file|
+              require_dependency file
+            rescue LoadError, StandardError => e
+              Rails.logger.error("[RubyLLM::Agents] Failed to load file #{file}: #{e.message}")
+            end
           end
         end
 
@@ -125,8 +134,11 @@ module RubyLLM
           agent_class = find(agent_type)
           stats = fetch_stats(agent_type)
 
+          # Detect the agent type (agent, workflow, embedder, moderator, speaker, transcriber)
+          detected_type = detect_agent_type(agent_class)
+
           # Check if this is a workflow class vs a regular agent
-          is_workflow = agent_class&.ancestors&.any? { |a| a.name&.include?("Workflow") }
+          is_workflow = detected_type == "workflow"
 
           # Determine specific workflow type and children
           workflow_type = is_workflow ? detect_workflow_type(agent_class) : nil
@@ -136,6 +148,7 @@ module RubyLLM
             name: agent_type,
             class: agent_class,
             active: agent_class.present?,
+            agent_type: detected_type,
             is_workflow: is_workflow,
             workflow_type: workflow_type,
             workflow_children: workflow_children,
@@ -209,6 +222,32 @@ module RubyLLM
           end
         end
 
+        # Detects the agent type from class hierarchy
+        #
+        # @param agent_class [Class, nil] The agent class
+        # @return [String] "agent", "workflow", "embedder", "moderator", "speaker", "transcriber", or "image_generator"
+        def detect_agent_type(agent_class)
+          return "agent" unless agent_class
+
+          ancestors = agent_class.ancestors.map { |a| a.name.to_s }
+
+          if ancestors.include?("RubyLLM::Agents::Embedder")
+            "embedder"
+          elsif ancestors.include?("RubyLLM::Agents::Moderator")
+            "moderator"
+          elsif ancestors.include?("RubyLLM::Agents::Speaker")
+            "speaker"
+          elsif ancestors.include?("RubyLLM::Agents::Transcriber")
+            "transcriber"
+          elsif ancestors.include?("RubyLLM::Agents::ImageGenerator")
+            "image_generator"
+          elsif ancestors.include?("RubyLLM::Agents::Workflow")
+            "workflow"
+          else
+            "agent"
+          end
+        end
+
         # Extracts child agents from workflow DSL configuration
         #
         # @param agent_class [Class, nil] The workflow class