ruby_llm-agents 1.1.0 → 1.2.1

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

@@ -353,21 +353,21 @@ module RubyLLM
       #     config.async_max_concurrency = 20
 
       # @!attribute [rw] root_directory
-      #   The root directory name under app/ for all LLM components.
+      #   The root directory name under app/ for all agent components.
       #   This allows customization of the directory structure.
-      #   @return [String] Directory name (default: "llm")
+      #   @return [String] Directory name (default: "agents")
       #   @example
-      #     config.root_directory = "ai"  # Creates app/ai/ instead of app/llm/
+      #     config.root_directory = "ai"  # Creates app/ai/ instead of app/agents/
 
       # @!attribute [rw] root_namespace
-      #   The root namespace for all LLM component classes.
-      #   This should match the root_directory in camelized form.
-      #   Set to nil or "" to use no namespace (classes at top-level).
-      #   @return [String, nil] Namespace (default: "Llm")
+      #   The root namespace for all agent component classes.
+      #   When set, subdirectory namespaces are prefixed with this.
+      #   Set to nil or "" to use no root namespace.
+      #   @return [String, nil] Namespace (default: nil)
       #   @example Custom namespace
-      #     config.root_namespace = "AI"  # Uses AI:: instead of Llm::
-      #   @example No namespace (top-level classes)
-      #     config.root_namespace = nil   # Uses top-level classes (ApplicationAgent, etc.)
+      #     config.root_namespace = "AI"  # app/agents/embedders -> AI::Embedders
+      #   @example No namespace (default)
+      #     config.root_namespace = nil   # app/agents/embedders -> Embedders
 
       # Attributes without validation (simple accessors)
       attr_accessor :default_model,
@@ -821,26 +821,18 @@ module RubyLLM
 
       # Returns the full namespace for a given category
       #
-      # @param category [Symbol, nil] Category (:audio, :image, :text, or nil for root)
+      # @param category [Symbol, String, nil] Category (e.g., :embedders, :images, or nil for root)
       # @return [String, nil] Full namespace string, or nil if no namespace configured
-      # @example With root_namespace = "Llm"
-      #   namespace_for(:image) #=> "Llm::Image"
-      #   namespace_for(nil)    #=> "Llm"
+      # @example With root_namespace = "AI"
+      #   namespace_for(:embedders) #=> "AI::Embedders"
+      #   namespace_for(nil)        #=> "AI"
       # @example With no namespace (root_namespace = nil)
-      #   namespace_for(:image) #=> "Image"
-      #   namespace_for(nil)    #=> nil
+      #   namespace_for(:embedders) #=> "Embedders"
+      #   namespace_for(nil)        #=> nil
       def namespace_for(category = nil)
-        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
+        category_namespace = category&.to_s&.camelize
 
-        if root_namespace
+        if root_namespace.present?
           category_namespace ? "#{root_namespace}::#{category_namespace}" : root_namespace
         else
           category_namespace

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.1.0"
+    VERSION = "1.2.1"
   end
 end

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/rails/engine.rb

@@ -170,14 +170,16 @@ module RubyLLM
         g.factory_bot dir: "spec/factories"
       end
 
-      # Adds the host app's LLM directories to Rails autoload paths
+      # Adds the host app's agent directories to Rails autoload paths
       #
-      # This allows agent classes and other LLM components defined in app/llm/
+      # This allows agent classes and other components defined in app/agents/
       # to be automatically loaded without explicit requires.
       #
-      # Supports two structures:
-      # 1. New grouped structure: app/llm/agents/, app/llm/tools/, etc.
-      # 2. Legacy flat structure: app/agents/ (for backwards compatibility)
+      # Supports subdirectory namespacing:
+      # - app/agents/ (top-level, no namespace)
+      # - app/agents/embedders/ -> Embedders namespace
+      # - app/agents/images/ -> Images namespace
+      # - app/workflows/ (top-level, no namespace)
       #
       # @api private
       initializer "ruby_llm_agents.autoload_agents", before: :set_autoload_paths do |app|
@@ -210,42 +212,34 @@ module RubyLLM
 
       # Determines the namespace constant for a given path
       #
-      # @param path [String] Relative path like "app/llm/agents"
+      # @param path [String] Relative path like "app/agents/embedders"
       # @param config [Configuration] Current configuration
       # @return [Module, nil] Namespace module or nil for top-level
       # @api private
       def self.namespace_for_path(path, config)
-        # Parse the path to determine namespace
         parts = path.split("/")
-        return nil unless parts.length >= 3
 
-        category = parts[2] # e.g., "agents", "audio", "image", "text"
+        # app/workflows -> no namespace (top-level workflows)
+        return nil if parts == ["app", "workflows"]
 
-        # Determine the namespace name based on category and root_namespace setting
+        # Need at least app/{root_directory}
+        return nil unless parts.length >= 2 && parts[0] == "app"
+        return nil unless parts[1] == config.root_directory
+
+        # app/agents -> no namespace (root level)
+        return nil if parts.length == 2
+
+        # app/agents/embedders -> Embedders namespace
+        subdirectory = parts[2]
         namespace_name = if config.root_namespace.blank?
-          # No root namespace - use category namespace only for audio/image/text
-          case category
-          when "audio", "image", "text"
-            category.camelize # "Audio", "Image", "Text"
-          else
-            nil # Top-level for agents, workflows, tools
-          end
+          subdirectory.camelize
         else
-          # With root namespace - prefix category with root namespace
-          case category
-          when "audio", "image", "text"
-            "#{config.root_namespace}::#{category.camelize}"
-          else
-            config.root_namespace
-          end
+          "#{config.root_namespace}::#{subdirectory.camelize}"
         end
 
-        return nil if namespace_name.nil?
-
-        # Return the constant, creating intermediate modules if needed
+        # Create the namespace module if needed
         namespace_name.constantize
       rescue NameError
-        # Create the namespace module if it doesn't exist
         namespace_name.split("::").inject(Object) do |mod, name|
           mod.const_defined?(name, false) ? mod.const_get(name) : mod.const_set(name, Module.new)
         end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_llm-agents
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.1
 platform: ruby
 authors:
 - adham90
@@ -95,6 +95,10 @@ files:
 - app/models/ruby_llm/agents/execution/metrics.rb
 - app/models/ruby_llm/agents/execution/scopes.rb
 - app/models/ruby_llm/agents/execution/workflow.rb
+- app/models/ruby_llm/agents/tenant.rb
+- app/models/ruby_llm/agents/tenant/budgetable.rb
+- app/models/ruby_llm/agents/tenant/configurable.rb
+- app/models/ruby_llm/agents/tenant/trackable.rb
 - app/models/ruby_llm/agents/tenant_budget.rb
 - app/services/ruby_llm/agents/agent_registry.rb
 - app/views/layouts/ruby_llm/agents/application.html.erb
@@ -155,6 +159,7 @@ files:
 - app/views/ruby_llm/agents/tenants/edit.html.erb
 - app/views/ruby_llm/agents/tenants/index.html.erb
 - app/views/ruby_llm/agents/tenants/show.html.erb
+- app/views/ruby_llm/agents/workflows/_empty_state.html.erb
 - app/views/ruby_llm/agents/workflows/_step_performance.html.erb
 - app/views/ruby_llm/agents/workflows/_structure_dsl.html.erb
 - app/views/ruby_llm/agents/workflows/_structure_parallel.html.erb
@@ -208,6 +213,7 @@ files:
 - lib/generators/ruby_llm_agents/templates/background_remover.rb.tt
 - lib/generators/ruby_llm_agents/templates/create_api_configurations_migration.rb.tt
 - lib/generators/ruby_llm_agents/templates/create_tenant_budgets_migration.rb.tt
+- lib/generators/ruby_llm_agents/templates/create_tenants_migration.rb.tt
 - lib/generators/ruby_llm_agents/templates/embedder.rb.tt
 - lib/generators/ruby_llm_agents/templates/image_analyzer.rb.tt
 - lib/generators/ruby_llm_agents/templates/image_editor.rb.tt
@@ -218,6 +224,7 @@ files:
 - lib/generators/ruby_llm_agents/templates/image_variator.rb.tt
 - lib/generators/ruby_llm_agents/templates/initializer.rb.tt
 - lib/generators/ruby_llm_agents/templates/migration.rb.tt
+- lib/generators/ruby_llm_agents/templates/rename_tenant_budgets_to_tenants_migration.rb.tt
 - lib/generators/ruby_llm_agents/templates/skills/AGENTS.md.tt
 - lib/generators/ruby_llm_agents/templates/skills/BACKGROUND_REMOVERS.md.tt
 - lib/generators/ruby_llm_agents/templates/skills/EMBEDDERS.md.tt