ruby_llm-agents 1.0.0 → 1.2.0

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

@@ -16,6 +16,24 @@ module RubyLLM
       include Paginatable
       include Filterable
 
+      # Lists all registered workflows with their details
+      #
+      # Uses AgentRegistry to discover workflows from both file system
+      # and execution history. Separates workflows by type for sub-tabs.
+      # Supports sorting by various columns.
+      #
+      # @return [void]
+      def index
+        all_items = AgentRegistry.all_with_details
+        @workflows = all_items.select { |a| a[:is_workflow] }
+        @sort_params = parse_sort_params
+        @workflows = sort_workflows(@workflows)
+      rescue StandardError => e
+        Rails.logger.error("[RubyLLM::Agents] Error loading workflows: #{e.message}")
+        @workflows = []
+        flash.now[:alert] = "Error loading workflows list"
+      end
+
       # Shows detailed view for a specific workflow
       #
       # Loads workflow configuration (if class exists), statistics,
@@ -42,23 +60,20 @@ module RubyLLM
         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"
+        redirect_to ruby_llm_agents.workflows_path, alert: "Error loading workflow details"
       end
 
       private
 
-      # Detects the workflow type kind (pipeline, parallel, router)
+      # Detects the workflow type kind
+      #
+      # All workflows now use the DSL and return "workflow" type.
       #
       # @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"
+          if @workflow_class.respond_to?(:step_configs) && @workflow_class.step_configs.any?
+            "workflow"
           end
         else
           # Fallback to execution history
@@ -157,7 +172,6 @@ module RubyLLM
       # @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
@@ -215,29 +229,6 @@ module RubyLLM
         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]
@@ -250,91 +241,252 @@ module RubyLLM
           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
+        # Load unified workflow structure for all types
+        load_unified_workflow_config
       end
 
-      # Loads pipeline-specific configuration
+      # Loads unified workflow configuration for all workflow types
       #
       # @return [void]
-      def load_pipeline_config
-        @steps = extract_steps(@workflow_class)
+      def load_unified_workflow_config
+        @parallel_groups = []
+        @input_schema_fields = {}
+        @lifecycle_hooks = {}
+
+        # All workflows use DSL
+        @steps = extract_dsl_steps(@workflow_class)
+        @parallel_groups = extract_parallel_groups(@workflow_class)
+        @lifecycle_hooks = extract_lifecycle_hooks(@workflow_class)
+
         @config[:steps_count] = @steps.size
+        @config[:parallel_groups_count] = @parallel_groups.size
+        @config[:has_routing] = @steps.any? { |s| s[:routing] }
+        @config[:has_conditions] = @steps.any? { |s| s[:if_condition] || s[:unless_condition] }
+        @config[:has_retries] = @steps.any? { |s| s[:retry_config] }
+        @config[:has_fallbacks] = @steps.any? { |s| s[:fallbacks]&.any? }
+        @config[:has_lifecycle_hooks] = @lifecycle_hooks.values.any? { |v| v.to_i > 0 }
+        @config[:has_input_schema] = @workflow_class.respond_to?(:input_schema) && @workflow_class.input_schema.present?
+
+        if @config[:has_input_schema]
+          @input_schema_fields = @workflow_class.input_schema.fields.transform_values(&:to_h)
+        end
       end
 
-      # Loads parallel-specific configuration
+      # Extracts steps from a DSL-based workflow class with full 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?)
+      # @param klass [Class] The workflow class
+      # @return [Array<Hash>] Array of step hashes with full DSL metadata
+      def extract_dsl_steps(klass)
+        return [] unless klass.respond_to?(:step_metadata) && klass.respond_to?(:step_configs)
+
+        step_configs = klass.step_configs
+
+        klass.step_metadata.map do |meta|
+          # Handle wait steps - they have type: :wait and aren't in step_configs
+          if meta[:type] == :wait
+            {
+              name: meta[:name],
+              type: :wait,
+              wait_type: meta[:wait_type],
+              ui_label: meta[:ui_label],
+              timeout: meta[:timeout],
+              duration: meta[:duration],
+              poll_interval: meta[:poll_interval],
+              on_timeout: meta[:on_timeout],
+              notify: meta[:notify],
+              approvers: meta[:approvers],
+              parallel: false
+            }.compact
+          else
+            config = step_configs[meta[:name]]
+            step_hash = {
+              name: meta[:name],
+              agent: meta[:agent],
+              description: meta[:description],
+              ui_label: meta[:ui_label],
+              optional: meta[:optional],
+              timeout: meta[:timeout],
+              routing: meta[:routing],
+              parallel: meta[:parallel],
+              parallel_group: meta[:parallel_group],
+              custom_block: config&.custom_block?,
+              # New composition features
+              workflow: meta[:workflow],
+              iteration: meta[:iteration],
+              iteration_concurrency: meta[:iteration_concurrency]
+            }
+
+            # Add extended configuration from StepConfig
+            if config
+              step_hash.merge!(
+                retry_config: extract_retry_config(config),
+                fallbacks: config.fallbacks.map(&:name),
+                if_condition: describe_condition(config.if_condition),
+                unless_condition: describe_condition(config.unless_condition),
+                has_input_mapper: config.input_mapper.present?,
+                pick_fields: config.pick_fields,
+                pick_from: config.pick_from,
+                default_value: config.default_value,
+                routes: extract_routes(config),
+                # Iteration error handling
+                iteration_fail_fast: config.iteration_fail_fast?,
+                continue_on_error: config.continue_on_error?
+              )
+
+              # Add sub-workflow metadata for nested workflow steps
+              if config.workflow? && config.agent
+                step_hash[:sub_workflow] = extract_sub_workflow_metadata(config.agent)
+              end
+            end
+
+            step_hash.compact
+          end
+        end
       end
 
-      # Loads router-specific configuration
+      # Extracts retry configuration in a display-friendly format
       #
-      # @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)
+      # @param config [StepConfig] The step configuration
+      # @return [Hash, nil] Retry config hash or nil
+      def extract_retry_config(config)
+        retry_cfg = config.retry_config
+        return nil unless retry_cfg && retry_cfg[:max].to_i > 0
+
+        {
+          max: retry_cfg[:max],
+          backoff: retry_cfg[:backoff],
+          delay: retry_cfg[:delay]
+        }
       end
 
-      # Extracts steps from a pipeline workflow class
+      # Describes a condition for display
       #
-      # @param klass [Class] The workflow class
-      # @return [Array<Hash>] Array of step hashes
-      def extract_steps(klass)
-        return [] unless klass.respond_to?(:steps)
+      # @param condition [Symbol, Proc, nil] The condition
+      # @return [String, nil] Human-readable description
+      def describe_condition(condition)
+        return nil if condition.nil?
+
+        case condition
+        when Symbol then condition.to_s
+        when Proc then "lambda"
+        else condition.to_s
+        end
+      end
+
+      # Extracts routes from a routing step
+      #
+      # @param config [StepConfig] The step configuration
+      # @return [Array<Hash>, nil] Array of route hashes or nil
+      def extract_routes(config)
+        return nil unless config.routing? && config.block
+
+        builder = RubyLLM::Agents::Workflow::DSL::RouteBuilder.new
+        config.block.call(builder)
 
-        klass.steps.map do |name, config|
+        routes = builder.routes.map do |name, route_config|
           {
-            name: name,
-            agent: config[:agent]&.name,
-            optional: config[:continue_on_error] || false
-          }
+            name: name.to_s,
+            agent: route_config[:agent]&.name,
+            timeout: extract_timeout_value(route_config[:options][:timeout]),
+            fallback: Array(route_config[:options][:fallback]).first&.then { |f| f.respond_to?(:name) ? f.name : f.to_s },
+            has_input_mapper: route_config[:options][:input].present?,
+            if_condition: describe_condition(route_config[:options][:if]),
+            default: false
+          }.compact
+        end
+
+        # Add default route
+        if builder.default
+          routes << {
+            name: "default",
+            agent: builder.default[:agent]&.name,
+            timeout: extract_timeout_value(builder.default[:options][:timeout]),
+            has_input_mapper: builder.default[:options][:input].present?,
+            default: true
+          }.compact
         end
+
+        routes
+      rescue StandardError => e
+        Rails.logger.debug "[RubyLLM::Agents] Could not extract routes: #{e.message}"
+        nil
       end
 
-      # Extracts branches from a parallel workflow class
+      # Extracts timeout value handling ActiveSupport::Duration
       #
-      # @param klass [Class] The workflow class
-      # @return [Array<Hash>] Array of branch hashes
-      def extract_branches(klass)
-        return [] unless klass.respond_to?(:branches)
+      # @param timeout [Integer, ActiveSupport::Duration, nil] The timeout value
+      # @return [Integer, nil] Timeout in seconds or nil
+      def extract_timeout_value(timeout)
+        return nil if timeout.nil?
+
+        timeout.respond_to?(:to_i) ? timeout.to_i : timeout
+      end
+
+      # Extracts metadata for a nested sub-workflow
+      #
+      # @param workflow_class [Class] The sub-workflow class
+      # @return [Hash] Sub-workflow metadata including steps preview and budget info
+      def extract_sub_workflow_metadata(workflow_class)
+        return nil unless workflow_class.respond_to?(:step_metadata)
+
+        {
+          name: workflow_class.name,
+          description: safe_call(workflow_class, :description),
+          timeout: safe_call(workflow_class, :timeout),
+          max_cost: safe_call(workflow_class, :max_cost),
+          max_recursion_depth: safe_call(workflow_class, :max_recursion_depth),
+          steps_count: workflow_class.step_configs.size,
+          steps_preview: extract_sub_workflow_steps_preview(workflow_class)
+        }.compact
+      rescue StandardError => e
+        Rails.logger.debug "[RubyLLM::Agents] Could not extract sub-workflow metadata: #{e.message}"
+        nil
+      end
+
+      # Extracts a simplified steps preview for sub-workflow display
+      #
+      # @param workflow_class [Class] The sub-workflow class
+      # @return [Array<Hash>] Simplified step hashes for preview
+      def extract_sub_workflow_steps_preview(workflow_class)
+        return [] unless workflow_class.respond_to?(:step_metadata)
 
-        klass.branches.map do |name, config|
+        workflow_class.step_metadata.map do |meta|
           {
-            name: name,
-            agent: config[:agent]&.name,
-            optional: config[:optional] || false
-          }
+            name: meta[:name],
+            agent: meta[:agent]&.gsub(/Agent$/, "")&.gsub(/Workflow$/, ""),
+            routing: meta[:routing],
+            iteration: meta[:iteration],
+            workflow: meta[:workflow],
+            parallel: meta[:parallel]
+          }.compact
         end
+      rescue StandardError
+        []
       end
 
-      # Extracts routes from a router workflow class
+      # Extracts parallel groups from a DSL-based 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)
+      # @return [Array<Hash>] Array of parallel group hashes
+      def extract_parallel_groups(klass)
+        return [] unless klass.respond_to?(:parallel_groups)
 
-        klass.routes.map do |name, config|
-          {
-            name: name,
-            agent: config[:agent]&.name,
-            description: config[:description],
-            default: config[:default] || false
-          }
-        end
+        klass.parallel_groups.map(&:to_h)
+      end
+
+      # Extracts lifecycle hooks from a workflow class
+      #
+      # @param klass [Class] The workflow class
+      # @return [Hash] Hash of hook types to counts
+      def extract_lifecycle_hooks(klass)
+        return {} unless klass.respond_to?(:lifecycle_hooks)
+
+        hooks = klass.lifecycle_hooks
+        {
+          before_workflow: hooks[:before_workflow]&.size || 0,
+          after_workflow: hooks[:after_workflow]&.size || 0,
+          on_step_error: hooks[:on_step_error]&.size || 0
+        }
       end
 
       # Safely calls a method on a class, returning nil if method doesn't exist
@@ -350,6 +502,43 @@ module RubyLLM
       rescue StandardError
         nil
       end
+
+      # Parses and validates sort parameters from request
+      #
+      # @return [Hash] Hash with :column and :direction keys
+      def parse_sort_params
+        allowed_columns = %w[name workflow_type execution_count total_cost success_rate last_executed]
+        column = params[:sort]
+        direction = params[:direction]
+
+        {
+          column: allowed_columns.include?(column) ? column : "name",
+          direction: %w[asc desc].include?(direction) ? direction : "asc"
+        }
+      end
+
+      # Sorts workflows array by the specified column and direction
+      #
+      # @param workflows [Array<Hash>] Array of workflow hashes
+      # @return [Array<Hash>] Sorted array
+      def sort_workflows(workflows)
+        column = @sort_params[:column].to_sym
+        direction = @sort_params[:direction]
+
+        sorted = workflows.sort_by do |w|
+          value = w[column]
+          case column
+          when :name
+            value.to_s.downcase
+          when :last_executed
+            value || Time.at(0)
+          else
+            value || 0
+          end
+        end
+
+        direction == "desc" ? sorted.reverse : sorted
+      end
     end
   end
 end

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

@@ -11,6 +11,39 @@ module RubyLLM
     module ApplicationHelper
       include Chartkick::Helper if defined?(Chartkick)
 
+      # Wiki base URL for documentation links
+      WIKI_BASE_URL = "https://github.com/adham90/ruby_llm-agents/wiki/".freeze
+
+      # Page to documentation mapping
+      DOC_PAGES = {
+        "dashboard/index" => "Dashboard",
+        "agents/index" => "Agent-DSL",
+        "agents/show" => "Agent-DSL",
+        "workflows/index" => "Workflows",
+        "workflows/show" => "Workflows",
+        "executions/index" => "Execution-Tracking",
+        "executions/show" => "Execution-Tracking",
+        "tenants/index" => "Multi-Tenancy",
+        "system_config/show" => "Configuration",
+        "api_configurations/show" => "Configuration"
+      }.freeze
+
+      # Returns the documentation URL for the current page or a specific page key
+      #
+      # @param page_key [String, nil] Optional page key (e.g., "agents/index")
+      # @return [String, nil] The documentation URL or nil if no mapping exists
+      # @example Get documentation URL for current page
+      #   documentation_url #=> "https://github.com/adham90/ruby_llm-agents/wiki/Agent-DSL"
+      # @example Get documentation URL for specific page
+      #   documentation_url("dashboard/index") #=> "https://github.com/adham90/ruby_llm-agents/wiki/Dashboard"
+      def documentation_url(page_key = nil)
+        key = page_key || "#{controller_name}/#{action_name}"
+        doc_page = DOC_PAGES[key]
+        return nil unless doc_page
+
+        "#{WIKI_BASE_URL}#{doc_page}"
+      end
+
       # Returns the URL helpers for the engine's routes
       #
       # Use this to generate paths and URLs within the dashboard views.
@@ -250,6 +283,73 @@ module RubyLLM
         end
       end
 
+      # Compact comparison indicator with arrow for now strip metrics
+      #
+      # Shows a colored arrow indicator showing percentage change vs previous period.
+      # For errors/cost/duration: decrease is good (green). For success/tokens: increase is good.
+      #
+      # @param change_pct [Float, nil] Percentage change from previous period
+      # @param metric_type [Symbol] Type of metric (:success, :errors, :cost, :duration, :tokens)
+      # @return [ActiveSupport::SafeBuffer, String] HTML span with indicator or empty string
+      def comparison_indicator(change_pct, metric_type: :count)
+        return "".html_safe if change_pct.nil?
+
+        # For errors/cost/duration, decrease is good. For success/tokens, increase is good.
+        positive_is_good = metric_type.in?(%i[success tokens count])
+        is_improvement = positive_is_good ? change_pct > 0 : change_pct < 0
+
+        arrow = change_pct > 0 ? "\u2191" : "\u2193"
+        color = is_improvement ? "text-green-600 dark:text-green-400" : "text-red-600 dark:text-red-400"
+
+        content_tag(:span, "#{arrow}#{change_pct.abs}%", class: "text-xs font-medium #{color} ml-1")
+      end
+
+      # Returns human-readable display name for time range
+      #
+      # @param range [String] Range parameter (today, 7d, 30d, 60d, 90d, or custom YYYY-MM-DD_YYYY-MM-DD)
+      # @return [String] Human-readable range name
+      # @example
+      #   range_display_name("7d") #=> "Last 7 Days"
+      #   range_display_name("2024-01-01_2024-01-15") #=> "Jan 1 - Jan 15"
+      def range_display_name(range)
+        case range
+        when "today" then "Today"
+        when "7d" then "Last 7 Days"
+        when "30d" then "Last 30 Days"
+        when "60d" then "Last 60 Days"
+        when "90d" then "Last 90 Days"
+        else
+          if range&.include?("_")
+            from_str, to_str = range.split("_")
+            from_date = Date.parse(from_str) rescue nil
+            to_date = Date.parse(to_str) rescue nil
+            if from_date && to_date
+              "#{from_date.strftime('%b %-d')} - #{to_date.strftime('%b %-d')}"
+            else
+              "Custom Range"
+            end
+          else
+            "Today"
+          end
+        end
+      end
+
+      # Formats milliseconds to human-readable duration
+      #
+      # @param ms [Numeric, nil] Duration in milliseconds
+      # @return [String] Human-readable duration (e.g., "150ms", "2.5s", "1.2m")
+      def format_duration_ms(ms)
+        return "0ms" if ms.nil? || ms.zero?
+
+        if ms < 1000
+          "#{ms.round}ms"
+        elsif ms < 60_000
+          "#{(ms / 1000.0).round(1)}s"
+        else
+          "#{(ms / 60_000.0).round(1)}m"
+        end
+      end
+
       # Returns the appropriate row background class based on change significance
       #
       # @param change_pct [Float] Percentage change

data/app/mailers/ruby_llm/agents/alert_mailer.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    # Mailer for sending alert notifications via email
+    #
+    # Delivers alert notifications when important events occur like
+    # budget exceedance or circuit breaker activation.
+    #
+    # @example Sending an alert email
+    #   AlertMailer.alert_notification(
+    #     event: :budget_hard_cap,
+    #     payload: { limit: 100.0, total: 105.0 },
+    #     recipient: "admin@example.com"
+    #   ).deliver_later
+    #
+    # @api public
+    class AlertMailer < ApplicationMailer
+      # Sends an alert notification email
+      #
+      # @param event [Symbol] The event type (e.g., :budget_soft_cap, :breaker_open)
+      # @param payload [Hash] Event-specific data
+      # @param recipient [String] Email address of the recipient
+      # @return [Mail::Message]
+      def alert_notification(event:, payload:, recipient:)
+        @event = event
+        @payload = payload
+        @title = event_title(event)
+        @severity = event_severity(event)
+        @color = event_color(event)
+        @timestamp = Time.current
+
+        mail(
+          to: recipient,
+          subject: "[RubyLLM::Agents Alert] #{@title}"
+        )
+      end
+
+      private
+
+      # Returns human-readable title for event type
+      #
+      # @param event [Symbol] The event type
+      # @return [String] Human-readable title
+      def event_title(event)
+        case event
+        when :budget_soft_cap then "Budget Soft Cap Reached"
+        when :budget_hard_cap then "Budget Hard Cap Exceeded"
+        when :breaker_open then "Circuit Breaker Opened"
+        when :agent_anomaly then "Agent Anomaly Detected"
+        else event.to_s.titleize
+        end
+      end
+
+      # Returns severity level for event type
+      #
+      # @param event [Symbol] The event type
+      # @return [String] Severity level
+      def event_severity(event)
+        case event
+        when :budget_soft_cap then "Warning"
+        when :budget_hard_cap then "Critical"
+        when :breaker_open then "Critical"
+        when :agent_anomaly then "Warning"
+        else "Info"
+        end
+      end
+
+      # Returns color for event type
+      #
+      # @param event [Symbol] The event type
+      # @return [String] Hex color code
+      def event_color(event)
+        case event
+        when :budget_soft_cap then "#FFA500"  # Orange
+        when :budget_hard_cap then "#FF0000"  # Red
+        when :breaker_open then "#FF0000"     # Red
+        when :agent_anomaly then "#FFA500"    # Orange
+        else "#0000FF"                        # Blue
+        end
+      end
+    end
+  end
+end

data/app/mailers/ruby_llm/agents/application_mailer.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    # Base mailer class for RubyLLM::Agents
+    #
+    # Host application must configure ActionMailer with SMTP settings
+    # for email delivery to work.
+    #
+    # @api private
+    class ApplicationMailer < ::ActionMailer::Base
+      default from: -> { default_from_address }
+
+      layout false  # Templates are self-contained
+
+      private
+
+      def default_from_address
+        RubyLLM::Agents.configuration.alerts&.dig(:email_from) ||
+          "noreply@#{default_host}"
+      end
+
+      def default_host
+        ::ActionMailer::Base.default_url_options[:host] || "example.com"
+      end
+    end
+  end
+end