ruby_llm-agents 1.0.0 → 1.2.0

data/lib/generators/ruby_llm_agents/upgrade_generator.rb

@@ -147,6 +147,26 @@ module RubyLlmAgents
       )
     end
 
+    def create_rename_tenant_budgets_migration
+      # Skip if already using new table name
+      if table_exists?(:ruby_llm_agents_tenants)
+        say_status :skip, "ruby_llm_agents_tenants table already exists", :yellow
+        return
+      end
+
+      # Only run if old table exists (needs upgrade)
+      unless table_exists?(:ruby_llm_agents_tenant_budgets)
+        say_status :skip, "No tenant_budgets table to upgrade", :yellow
+        return
+      end
+
+      say_status :upgrade, "Renaming tenant_budgets to tenants", :blue
+      migration_template(
+        "rename_tenant_budgets_to_tenants_migration.rb.tt",
+        File.join(db_migrate_path, "rename_tenant_budgets_to_tenants.rb")
+      )
+    end
+
     def migrate_agents_directory
       root_dir = RubyLLM::Agents.configuration.root_directory
       namespace = RubyLLM::Agents.configuration.root_namespace
@@ -211,6 +231,12 @@ module RubyLlmAgents
       false
     end
 
+    def table_exists?(table)
+      ActiveRecord::Base.connection.table_exists?(table)
+    rescue StandardError
+      false
+    end
+
     def migrate_directory(old_dir, new_dir, namespace)
       source = Rails.root.join("app", old_dir)
       destination = Rails.root.join("app", new_dir)

data/lib/ruby_llm/agents/core/configuration.rb

@@ -702,8 +702,8 @@ module RubyLLM
         @default_background_output_format = :png  # Output format for transparency
 
         # Directory structure defaults
-        @root_directory = "llm"  # Root directory under app/
-        @root_namespace = "Llm"  # Root namespace for classes
+        @root_directory = "agents"  # Root directory under app/
+        @root_namespace = nil  # No namespace (top-level classes)
       end
 
       # Returns the configured cache store, falling back to Rails.cache
@@ -744,7 +744,8 @@ module RubyLLM
 
         alerts[:slack_webhook_url].present? ||
           alerts[:webhook_url].present? ||
-          alerts[:custom].present?
+          alerts[:custom].present? ||
+          alerts[:email_recipients].present?
       end
 
       # Returns the list of events to alert on
@@ -822,28 +823,27 @@ module RubyLLM
       #
       # @param category [Symbol, nil] Category (:audio, :image, :text, or nil for root)
       # @return [String, nil] Full namespace string, or nil if no namespace configured
-      # @example With default namespace
+      # @example With root_namespace = "Llm"
       #   namespace_for(:image) #=> "Llm::Image"
       #   namespace_for(nil)    #=> "Llm"
       # @example With no namespace (root_namespace = nil)
       #   namespace_for(:image) #=> "Image"
       #   namespace_for(nil)    #=> nil
       def namespace_for(category = nil)
-        # Handle no namespace configuration
-        if root_namespace.blank?
-          case category
-          when :audio then "Audio"
-          when :image then "Image"
-          when :text then "Text"
-          else nil
-          end
+        category_namespace = case category
+        when :images then "Images"
+        when :audio then "Audio"
+        when :embedders then "Embedders"
+        when :moderators then "Moderators"
+        when :workflows then "Workflows"
+        when :text then "Text"
+        when :image then "Image"
+        end
+
+        if root_namespace
+          category_namespace ? "#{root_namespace}::#{category_namespace}" : root_namespace
         else
-          case category
-          when :audio then "#{root_namespace}::Audio"
-          when :image then "#{root_namespace}::Image"
-          when :text then "#{root_namespace}::Text"
-          else root_namespace
-          end
+          category_namespace
         end
       end
 
@@ -852,15 +852,34 @@ module RubyLLM
       # @param category [Symbol, nil] Category (:audio, :image, :text, or nil)
       # @param type [String] Component type (e.g., "agents", "speakers", "generators")
       # @return [String] Full path relative to Rails.root
-      # @example
+      # @example With root_directory = "llm"
       #   path_for(:image, "generators") #=> "app/llm/image/generators"
       #   path_for(nil, "agents")        #=> "app/llm/agents"
-      def path_for(category, type)
-        case category
-        when :audio then "app/#{root_directory}/audio/#{type}"
-        when :image then "app/#{root_directory}/image/#{type}"
-        when :text then "app/#{root_directory}/text/#{type}"
-        else "app/#{root_directory}/#{type}"
+      # @example With root_directory = "agents" (default)
+      #   path_for(:images)              #=> "app/agents/images"
+      #   path_for(nil, "tools")         #=> "app/agents/tools"
+      def path_for(category, type = nil)
+        root = root_directory || "agents"
+        base = "app/#{root}"
+
+        category_path = case category
+        when :images then "images"
+        when :audio then "audio"
+        when :embedders then "embedders"
+        when :moderators then "moderators"
+        when :workflows then "workflows"
+        when :text then "text"
+        when :image then "image"
+        end
+
+        if category_path && type
+          "#{base}/#{category_path}/#{type}"
+        elsif category_path
+          "#{base}/#{category_path}"
+        elsif type
+          "#{base}/#{type}"
+        else
+          base
         end
       end
 
@@ -868,25 +887,18 @@ module RubyLLM
       #
       # @return [Array<String>] List of paths relative to Rails.root
       def all_autoload_paths
+        root = root_directory || "agents"
+        base = "app/#{root}"
+
         [
-          # Top-level
-          path_for(nil, "agents"),
-          path_for(nil, "workflows"),
-          path_for(nil, "tools"),
-          # Audio
-          path_for(:audio, "speakers"),
-          path_for(:audio, "transcribers"),
-          # Image
-          path_for(:image, "analyzers"),
-          path_for(:image, "background_removers"),
-          path_for(:image, "editors"),
-          path_for(:image, "generators"),
-          path_for(:image, "transformers"),
-          path_for(:image, "upscalers"),
-          path_for(:image, "variators"),
-          # Text
-          path_for(:text, "embedders"),
-          path_for(:text, "moderators")
+          base,
+          "app/workflows",           # Top-level workflows directory
+          "#{base}/images",
+          "#{base}/audio",
+          "#{base}/embedders",
+          "#{base}/moderators",
+          "#{base}/workflows",
+          "#{base}/tools"
         ]
       end
 

data/lib/ruby_llm/agents/core/llm_tenant.rb

@@ -12,21 +12,25 @@ module RubyLLM
     #
     # @example Basic usage
     #   class Organization < ApplicationRecord
+    #     include RubyLLM::Agents::LLMTenant
     #     llm_tenant
     #   end
     #
     # @example With custom ID method
     #   class Organization < ApplicationRecord
+    #     include RubyLLM::Agents::LLMTenant
     #     llm_tenant id: :slug
     #   end
     #
     # @example With auto-created budget
     #   class Organization < ApplicationRecord
+    #     include RubyLLM::Agents::LLMTenant
     #     llm_tenant id: :slug, budget: true
     #   end
     #
     # @example With limits (auto-creates budget)
     #   class Organization < ApplicationRecord
+    #     include RubyLLM::Agents::LLMTenant
     #     llm_tenant(
     #       id: :slug,
     #       name: :company_name,
@@ -41,6 +45,7 @@ module RubyLLM
     #
     # @example With API keys from model columns/methods
     #   class Organization < ApplicationRecord
+    #     include RubyLLM::Agents::LLMTenant
     #     encrypts :openai_api_key, :anthropic_api_key  # Rails 7+ encryption
     #
     #     llm_tenant(
@@ -57,7 +62,7 @@ module RubyLLM
     #     end
     #   end
     #
-    # @see RubyLLM::Agents::TenantBudget
+    # @see RubyLLM::Agents::Tenant
     # @api public
     module LLMTenant
       extend ActiveSupport::Concern
@@ -69,12 +74,16 @@ module RubyLLM
                  as: :tenant_record,
                  dependent: :nullify
 
-        # Budget association (optional)
-        has_one :llm_budget,
-                class_name: "RubyLLM::Agents::TenantBudget",
+        # Link to gem's Tenant model (new name)
+        has_one :llm_tenant_record,
+                class_name: "RubyLLM::Agents::Tenant",
                 as: :tenant_record,
                 dependent: :destroy
 
+        # Backward compatible alias (llm_budget points to same Tenant record)
+        # @deprecated Use llm_tenant_record instead
+        alias_method :llm_budget_association, :llm_tenant_record
+
         # Store options at class level
         class_attribute :llm_tenant_options, default: {}
       end
@@ -84,7 +93,7 @@ module RubyLLM
         #
         # @param id [Symbol] Method to call for tenant_id string (default: :id)
         # @param name [Symbol] Method for budget display name (default: :to_s)
-        # @param budget [Boolean] Auto-create TenantBudget on model creation (default: false)
+        # @param budget [Boolean] Auto-create Tenant record on model creation (default: false)
         # @param limits [Hash] Default budget limits (implies budget: true)
         # @param enforcement [Symbol] Budget enforcement mode (:none, :soft, :hard)
         # @param inherit_global [Boolean] Inherit from global config (default: true)
@@ -101,8 +110,8 @@ module RubyLLM
             api_keys: api_keys
           }
 
-          # Auto-create budget callback
-          after_create :create_default_llm_budget if llm_tenant_options[:budget]
+          # Auto-create tenant record callback
+          after_create :create_default_llm_tenant if llm_tenant_options[:budget]
         end
 
         private
@@ -152,13 +161,42 @@ module RubyLLM
         end.compact
       end
 
+      # Returns or builds the associated Tenant record
+      #
+      # @return [Tenant] The tenant record
+      def llm_tenant
+        llm_tenant_record || build_llm_tenant_record(tenant_id: llm_tenant_id)
+      end
+
+      # Backward compatible alias for llm_tenant
+      # @deprecated Use llm_tenant instead
+      alias_method :llm_budget, :llm_tenant
+
+      # Configure tenant with a block
+      #
+      # @yield [tenant] The tenant to configure
+      # @return [Tenant] The saved tenant
+      def llm_configure(&block)
+        tenant = llm_tenant
+        yield(tenant) if block_given?
+        tenant.save!
+        tenant
+      end
+
+      # Backward compatible alias
+      # @deprecated Use llm_configure instead
+      alias_method :llm_configure_budget, :llm_configure
+
+      # Tracking methods using llm_executions association
+      # These query executions via the polymorphic tenant_record association
+
       # Returns cost for a given period
       #
       # @param period [Symbol, Range, nil] Time period (:today, :this_month, etc.)
       # @return [BigDecimal] Total cost
       def llm_cost(period: nil)
         scope = llm_executions
-        scope = apply_period_scope(scope, period) if period
+        scope = apply_llm_period_scope(scope, period) if period
         scope.sum(:total_cost) || 0
       end
 
@@ -182,7 +220,7 @@ module RubyLLM
       # @return [Integer] Total tokens
       def llm_tokens(period: nil)
         scope = llm_executions
-        scope = apply_period_scope(scope, period) if period
+        scope = apply_llm_period_scope(scope, period) if period
         scope.sum(:total_tokens) || 0
       end
 
@@ -206,7 +244,7 @@ module RubyLLM
       # @return [Integer] Execution count
       def llm_execution_count(period: nil)
         scope = llm_executions
-        scope = apply_period_scope(scope, period) if period
+        scope = apply_llm_period_scope(scope, period) if period
         scope.count
       end
 
@@ -237,29 +275,13 @@ module RubyLLM
         }
       end
 
-      # Returns or builds the associated TenantBudget
-      #
-      # @return [TenantBudget] The budget record
-      def llm_budget
-        super || build_llm_budget(tenant_id: llm_tenant_id)
-      end
-
-      # Configure budget with a block
-      #
-      # @yield [budget] The budget to configure
-      # @return [TenantBudget] The saved budget
-      def llm_configure_budget
-        budget = llm_budget
-        yield(budget) if block_given?
-        budget.save!
-        budget
-      end
+      # Delegate budget methods to the Tenant record
 
       # Returns the budget status from BudgetTracker
       #
       # @return [Hash] Budget status
       def llm_budget_status
-        BudgetTracker.status(tenant_id: llm_tenant_id)
+        llm_tenant.budget_status
       end
 
       # Checks if within budget for a given limit type
@@ -267,11 +289,7 @@ module RubyLLM
       # @param type [Symbol] Limit type (:daily_cost, :monthly_cost, :daily_tokens, etc.)
       # @return [Boolean] true if within budget
       def llm_within_budget?(type: :daily_cost)
-        status = llm_budget_status
-        return true unless status[:enabled]
-
-        key = budget_status_key(type)
-        status.dig(key, :percentage_used).to_f < 100
+        llm_tenant.within_budget?(type: type)
       end
 
       # Returns remaining budget for a given limit type
@@ -279,9 +297,7 @@ module RubyLLM
       # @param type [Symbol] Limit type
       # @return [Numeric, nil] Remaining amount
       def llm_remaining_budget(type: :daily_cost)
-        status = llm_budget_status
-        key = budget_status_key(type)
-        status.dig(key, :remaining)
+        llm_tenant.remaining_budget(type: type)
       end
 
       # Raises an error if over budget
@@ -289,7 +305,7 @@ module RubyLLM
       # @raise [BudgetExceededError] if budget is exceeded
       # @return [void]
       def llm_check_budget!
-        BudgetTracker.check_budget!(self.class.name, tenant_id: llm_tenant_id)
+        llm_tenant.check_budget!(self.class.name)
       end
 
       private
@@ -299,7 +315,7 @@ module RubyLLM
       # @param scope [ActiveRecord::Relation] The query scope
       # @param period [Symbol, Range] The period to filter by
       # @return [ActiveRecord::Relation] Filtered scope
-      def apply_period_scope(scope, period)
+      def apply_llm_period_scope(scope, period)
         case period
         when :today then scope.where(created_at: Time.current.all_day)
         when :yesterday then scope.where(created_at: 1.day.ago.all_day)
@@ -310,34 +326,18 @@ module RubyLLM
         end
       end
 
-      # Maps user-friendly type to budget status key
-      #
-      # @param type [Symbol] User-friendly type
-      # @return [Symbol] Status key
-      def budget_status_key(type)
-        case type
-        when :daily_cost then :global_daily
-        when :monthly_cost then :global_monthly
-        when :daily_tokens then :global_daily_tokens
-        when :monthly_tokens then :global_monthly_tokens
-        when :daily_executions then :global_daily_executions
-        when :monthly_executions then :global_monthly_executions
-        else :global_daily
-        end
-      end
-
-      # Creates the default budget on model creation
+      # Creates the default tenant record on model creation
       #
       # @return [void]
-      def create_default_llm_budget
+      def create_default_llm_tenant
         return if self.class.llm_tenant_options.blank?
-        return if llm_budget&.persisted?
+        return if llm_tenant_record&.persisted?
 
         options = self.class.llm_tenant_options
         limits = options[:limits] || {}
         name_method = options[:name] || :to_s
 
-        budget = build_llm_budget(
+        tenant = build_llm_tenant_record(
           tenant_id: llm_tenant_id,
           name: send(name_method).to_s,
           daily_limit: limits[:daily_cost],
@@ -350,8 +350,8 @@ module RubyLLM
           inherit_global_defaults: options.fetch(:inherit_global, true)
         )
 
-        budget.tenant_record = self
-        budget.save!
+        tenant.tenant_record = self
+        tenant.save!
       end
     end
   end

data/lib/ruby_llm/agents/core/version.rb

@@ -4,6 +4,6 @@ module RubyLLM
   module Agents
     # Current version of the RubyLLM::Agents gem
     # @return [String] Semantic version string
-    VERSION = "1.0.0"
+    VERSION = "1.2.0"
   end
 end

data/lib/ruby_llm/agents/infrastructure/alert_manager.rb

@@ -46,6 +46,14 @@ module RubyLLM
             call_custom_alert(alerts[:custom], event, full_payload)
           end
 
+          # Send email alerts
+          if alerts[:email_recipients].present?
+            email_events = alerts[:email_events] || config.alert_events
+            if email_events.include?(event)
+              send_email_alerts(event, full_payload, alerts[:email_recipients])
+            end
+          end
+
           # Emit ActiveSupport::Notification for observability
           emit_notification(event, full_payload)
         rescue StandardError => e
@@ -92,6 +100,24 @@ module RubyLLM
           Rails.logger.warn("[RubyLLM::Agents::AlertManager] Custom alert failed: #{e.message}")
         end
 
+        # Sends email alerts to configured recipients
+        #
+        # @param event [Symbol] The event type
+        # @param payload [Hash] The payload
+        # @param recipients [Array<String>] Email addresses
+        # @return [void]
+        def send_email_alerts(event, payload, recipients)
+          Array(recipients).each do |recipient|
+            AlertMailer.alert_notification(
+              event: event,
+              payload: payload,
+              recipient: recipient
+            ).deliver_later
+          end
+        rescue StandardError => e
+          Rails.logger.warn("[RubyLLM::Agents::AlertManager] Email alert failed: #{e.message}")
+        end
+
         # Emits an ActiveSupport::Notification
         #
         # @param event [Symbol] The event type

data/lib/ruby_llm/agents/infrastructure/budget/config_resolver.rb

@@ -125,13 +125,15 @@ module RubyLLM
             nil
           end
 
-          # Checks if the tenant_budgets table exists
+          # Checks if the tenants table exists (supports old and new table names)
           #
           # @return [Boolean] true if table exists
           def tenant_budget_table_exists?
             return @tenant_budget_table_exists if defined?(@tenant_budget_table_exists)
 
-            @tenant_budget_table_exists = ::ActiveRecord::Base.connection.table_exists?(:ruby_llm_agents_tenant_budgets)
+            # Check for new table name (tenants) or old table name (tenant_budgets) for backward compatibility
+            @tenant_budget_table_exists = ::ActiveRecord::Base.connection.table_exists?(:ruby_llm_agents_tenants) ||
+                                          ::ActiveRecord::Base.connection.table_exists?(:ruby_llm_agents_tenant_budgets)
           rescue StandardError
             @tenant_budget_table_exists = false
           end

data/lib/ruby_llm/agents/pipeline.rb

@@ -40,6 +40,75 @@ require_relative "pipeline/middleware/reliability"
 module RubyLLM
   module Agents
     module Pipeline
+      # Represents an error result from a failed step
+      #
+      # Used to track errors that occurred during step execution while
+      # allowing the workflow to continue (for optional steps).
+      #
+      # @api public
+      class ErrorResult
+        attr_reader :step_name, :error_class, :error_message
+
+        def initialize(step_name:, error_class:, error_message:)
+          @step_name = step_name
+          @error_class = error_class
+          @error_message = error_message
+        end
+
+        def content
+          nil
+        end
+
+        def success?
+          false
+        end
+
+        def error?
+          true
+        end
+
+        def skipped?
+          false
+        end
+
+        def input_tokens
+          0
+        end
+
+        def output_tokens
+          0
+        end
+
+        def total_tokens
+          0
+        end
+
+        def cached_tokens
+          0
+        end
+
+        def input_cost
+          0.0
+        end
+
+        def output_cost
+          0.0
+        end
+
+        def total_cost
+          0.0
+        end
+
+        def to_h
+          {
+            error: true,
+            step_name: step_name,
+            error_class: error_class,
+            error_message: error_message
+          }
+        end
+      end
+
       class << self
         # Build a pipeline for an agent class with default middleware
         #