ruby_llm-agents 1.0.0 → 1.2.0

data/lib/generators/ruby_llm_agents/migrate_structure_generator.rb

@@ -0,0 +1,480 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "fileutils"
+
+module RubyLlmAgents
+  # Migration generator for moving from old directory structure to new
+  #
+  # Migrates from:
+  #   app/{root}/agents/
+  #   app/{root}/image/generators/
+  #   app/{root}/audio/speakers/
+  #   app/{root}/text/embedders/
+  #   app/{root}/workflows/
+  #
+  # To:
+  #   app/agents/
+  #   app/agents/images/
+  #   app/agents/audio/
+  #   app/agents/embedders/
+  #   app/workflows/
+  #
+  # Usage:
+  #   rails generate ruby_llm_agents:migrate_structure
+  #   rails generate ruby_llm_agents:migrate_structure --dry-run
+  #   rails generate ruby_llm_agents:migrate_structure --source-root=ai
+  #
+  class MigrateStructureGenerator < ::Rails::Generators::Base
+    source_root File.expand_path("templates", __dir__)
+
+    class_option :source_root,
+      type: :string,
+      default: nil,
+      desc: "Source root directory to migrate from (default: auto-detect or 'llm')"
+
+    class_option :dry_run,
+      type: :boolean,
+      default: false,
+      desc: "Show what would be done without making changes"
+
+    class_option :skip_namespace_update,
+      type: :boolean,
+      default: false,
+      desc: "Skip updating namespaces in Ruby files"
+
+    class_option :use_git,
+      type: :boolean,
+      default: true,
+      desc: "Use git mv when in a git repository"
+
+    # Maps old paths to new paths
+    # Format: old_subpath => new_path (relative to app/)
+    PATH_MAPPING = {
+      # Task agents
+      "agents" => "agents",
+
+      # Image agents (flatten operation types)
+      "image/generators" => "agents/images",
+      "image/analyzers" => "agents/images",
+      "image/editors" => "agents/images",
+      "image/upscalers" => "agents/images",
+      "image/variators" => "agents/images",
+      "image/transformers" => "agents/images",
+      "image/background_removers" => "agents/images",
+      "image/pipelines" => "agents/images",
+
+      # Audio agents
+      "audio/speakers" => "agents/audio",
+      "audio/transcribers" => "agents/audio",
+
+      # Text operations
+      "text/embedders" => "agents/embedders",
+      "text/moderators" => "agents/moderators",
+
+      # Workflows
+      "workflows" => "workflows",
+
+      # Tools
+      "tools" => "tools"
+    }.freeze
+
+    # Namespace transformations
+    # Format: old_namespace_pattern => new_namespace
+    NAMESPACE_MAPPING = {
+      # Remove root namespace from task agents
+      /\A(\w+)::(\w+Agent)\z/ => '\2',
+
+      # Image namespaces
+      /\A(\w+)::Image::(\w+)\z/ => 'Images::\2',
+
+      # Audio namespaces
+      /\A(\w+)::Audio::(\w+)\z/ => 'Audio::\2',
+
+      # Text namespaces -> Embedders/Moderators
+      /\A(\w+)::Text::(\w+Embedder)\z/ => 'Embedders::\2',
+      /\A(\w+)::Text::(\w+Moderator)\z/ => 'Moderators::\2',
+
+      # Workflows (remove root namespace)
+      /\A(\w+)::(\w+Workflow)\z/ => '\2'
+    }.freeze
+
+    def check_prerequisites
+      @source_root_dir = detect_source_root
+
+      if @source_root_dir.nil?
+        say_status :skip, "No old structure detected. Nothing to migrate.", :yellow
+        say ""
+        say "If you have an existing structure, specify the source root:"
+        say "  rails generate ruby_llm_agents:migrate_structure --source-root=llm"
+        raise Thor::Error, "Migration aborted: no source found"
+      end
+
+      say_status :found, "Old structure at app/#{@source_root_dir}/", :green
+    end
+
+    def show_migration_plan
+      say ""
+      say "=" * 60
+      say "Migration Plan", :bold
+      say "=" * 60
+      say ""
+      say "Source: app/#{@source_root_dir}/"
+      say "Target: app/agents/ and app/workflows/"
+      say ""
+
+      @files_to_migrate = []
+
+      PATH_MAPPING.each do |old_subpath, new_path|
+        old_full_path = Rails.root.join("app", @source_root_dir, old_subpath)
+        next unless File.directory?(old_full_path)
+
+        files = Dir.glob("#{old_full_path}/**/*.rb")
+        next if files.empty?
+
+        files.each do |file|
+          relative = file.sub("#{old_full_path}/", "")
+          new_file = Rails.root.join("app", new_path, relative)
+          @files_to_migrate << {
+            old: file,
+            new: new_file.to_s,
+            old_display: "app/#{@source_root_dir}/#{old_subpath}/#{relative}",
+            new_display: "app/#{new_path}/#{relative}"
+          }
+        end
+      end
+
+      if @files_to_migrate.empty?
+        say_status :skip, "No Ruby files found to migrate", :yellow
+        return
+      end
+
+      say "Files to migrate (#{@files_to_migrate.size}):"
+      @files_to_migrate.each do |f|
+        say "  #{f[:old_display]}"
+        say "    -> #{f[:new_display]}", :green
+      end
+      say ""
+    end
+
+    def create_new_directories
+      return if @files_to_migrate.nil? || @files_to_migrate.empty?
+
+      say_status :create, "Creating new directory structure", :green
+
+      directories = @files_to_migrate.map { |f| File.dirname(f[:new]) }.uniq
+
+      directories.each do |dir|
+        if options[:dry_run]
+          say_status :dry_run, "Would create #{dir.sub(Rails.root.to_s + '/', '')}", :yellow
+        else
+          FileUtils.mkdir_p(dir)
+          say_status :mkdir, dir.sub(Rails.root.to_s + "/", ""), :green
+        end
+      end
+    end
+
+    def move_files
+      return if @files_to_migrate.nil? || @files_to_migrate.empty?
+
+      say ""
+      say_status :move, "Moving files to new locations", :green
+
+      @files_to_migrate.each do |f|
+        if options[:dry_run]
+          say_status :dry_run, "Would move #{f[:old_display]} -> #{f[:new_display]}", :yellow
+        else
+          move_file(f[:old], f[:new])
+          say_status :moved, f[:new_display], :green
+        end
+      end
+    end
+
+    def update_namespaces
+      return if options[:skip_namespace_update]
+      return if @files_to_migrate.nil? || @files_to_migrate.empty?
+
+      say ""
+      say_status :update, "Updating namespaces in Ruby files", :green
+
+      @files_to_migrate.each do |f|
+        file_path = options[:dry_run] ? f[:old] : f[:new]
+        next unless File.exist?(file_path)
+
+        if options[:dry_run]
+          say_status :dry_run, "Would update namespaces in #{f[:new_display]}", :yellow
+        else
+          update_file_namespaces(f[:new])
+        end
+      end
+    end
+
+    def update_base_classes
+      return if options[:skip_namespace_update]
+      return if @files_to_migrate.nil? || @files_to_migrate.empty?
+
+      say ""
+      say_status :update, "Updating base class references", :green
+
+      @files_to_migrate.each do |f|
+        file_path = options[:dry_run] ? f[:old] : f[:new]
+        next unless File.exist?(file_path)
+
+        if options[:dry_run]
+          say_status :dry_run, "Would update base classes in #{f[:new_display]}", :yellow
+        else
+          update_file_base_classes(f[:new])
+        end
+      end
+    end
+
+    def cleanup_old_directories
+      return if @files_to_migrate.nil? || @files_to_migrate.empty?
+
+      say ""
+      say_status :cleanup, "Cleaning up old directories", :green
+
+      # Collect all old directories
+      old_dirs = PATH_MAPPING.keys.map do |old_subpath|
+        Rails.root.join("app", @source_root_dir, old_subpath)
+      end.select { |d| File.directory?(d) }
+
+      # Sort by depth (deepest first) for proper cleanup
+      old_dirs.sort_by { |d| -d.to_s.count("/") }.each do |dir|
+        cleanup_directory(dir)
+      end
+
+      # Try to remove the root directory if empty
+      root_dir = Rails.root.join("app", @source_root_dir)
+      if File.directory?(root_dir)
+        cleanup_directory(root_dir)
+      end
+    end
+
+    def show_completion_message
+      say ""
+      say "=" * 60
+      say ""
+
+      if options[:dry_run]
+        say "Dry run complete! No changes were made.", :yellow
+        say ""
+        say "To perform the actual migration, run:"
+        say "  rails generate ruby_llm_agents:migrate_structure"
+      else
+        say "Migration complete!", :green
+        say ""
+        say "Your app now uses the new directory structure:"
+        say ""
+        say "  app/"
+        say "  ├── agents/"
+        say "  │   ├── application_agent.rb"
+        say "  │   ├── your_agent.rb"
+        say "  │   ├── images/"
+        say "  │   ├── audio/"
+        say "  │   ├── embedders/"
+        say "  │   └── moderators/"
+        say "  └── workflows/"
+        say ""
+        say "Next steps:"
+        say "  1. Update class references in your code:"
+        say "     - Llm::Image::ProductGenerator -> Images::ProductGenerator"
+        say "     - Llm::Audio::MeetingTranscriber -> Audio::MeetingTranscriber"
+        say "     - Llm::Text::SemanticEmbedder -> Embedders::SemanticEmbedder"
+        say "  2. Run your test suite: bundle exec rspec"
+        say "  3. Commit the changes: git add -A && git commit -m 'Migrate to new agent structure'"
+      end
+
+      say ""
+      say "=" * 60
+    end
+
+    private
+
+    def detect_source_root
+      # Check for explicitly provided source root
+      if options[:source_root]
+        path = Rails.root.join("app", options[:source_root])
+        return options[:source_root] if File.directory?(path)
+        say_status :warning, "Specified source root 'app/#{options[:source_root]}/' not found", :yellow
+        return nil
+      end
+
+      # Try to get from configuration
+      if defined?(RubyLLM::Agents) && RubyLLM::Agents.respond_to?(:configuration)
+        config_root = RubyLLM::Agents.configuration.root_directory
+        if config_root.present?
+          path = Rails.root.join("app", config_root)
+          return config_root if File.directory?(path)
+        end
+      end
+
+      # Auto-detect common root directories
+      %w[llm ai ml agents].each do |candidate|
+        path = Rails.root.join("app", candidate)
+        if File.directory?(path) && has_old_structure?(path)
+          return candidate
+        end
+      end
+
+      nil
+    end
+
+    def has_old_structure?(path)
+      # Check if this looks like an old ruby_llm-agents structure
+      old_indicators = %w[
+        agents
+        image/generators
+        audio/speakers
+        text/embedders
+        workflows
+      ]
+
+      old_indicators.any? do |indicator|
+        File.directory?(File.join(path, indicator))
+      end
+    end
+
+    def in_git_repo?
+      @in_git_repo ||= File.directory?(Rails.root.join(".git"))
+    end
+
+    def move_file(old_path, new_path)
+      if options[:use_git] && in_git_repo?
+        # Use git mv to preserve history
+        old_relative = old_path.sub(Rails.root.to_s + "/", "")
+        new_relative = new_path.sub(Rails.root.to_s + "/", "")
+        system("git", "mv", old_relative, new_relative, chdir: Rails.root.to_s)
+      else
+        FileUtils.mv(old_path, new_path)
+      end
+    end
+
+    def update_file_namespaces(file_path)
+      content = File.read(file_path)
+      original_content = content.dup
+      modified = false
+
+      # Find and replace module/class declarations with old namespaces
+      # Pattern: module OldRoot ... end wrapping
+      old_root_pattern = /^module\s+#{Regexp.escape(camelize(@source_root_dir))}\s*$/
+
+      if content.match?(old_root_pattern)
+        # Remove the old root module wrapper
+        content = remove_root_module_wrapper(content, camelize(@source_root_dir))
+        modified = true
+      end
+
+      # Update module declarations for nested namespaces
+      # Image:: -> Images::
+      content.gsub!(/\bmodule\s+Image\b/, "module Images") && (modified = true)
+
+      # Text:: -> nothing (embedders/moderators are top-level now)
+      # This is handled by the module removal above
+
+      if modified && content != original_content
+        File.write(file_path, content)
+        say_status :updated, file_path.sub(Rails.root.to_s + "/", ""), :blue
+      end
+    end
+
+    def update_file_base_classes(file_path)
+      content = File.read(file_path)
+      original_content = content.dup
+
+      # Update base class references
+      replacements = {
+        # Application bases with old namespace
+        /class\s+Application(\w+)\s*<\s*#{Regexp.escape(camelize(@source_root_dir))}::/ =>
+          'class Application\1 < ',
+
+        # Specific base classes
+        /ApplicationImageGenerator/ => "ApplicationImageGenerator",
+        /ApplicationImageAnalyzer/ => "ApplicationImageAnalyzer",
+        /ApplicationImageEditor/ => "ApplicationImageEditor",
+        /ApplicationTranscriber/ => "ApplicationTranscriber",
+        /ApplicationSpeaker/ => "ApplicationSpeaker",
+        /ApplicationEmbedder/ => "ApplicationEmbedder"
+      }
+
+      replacements.each do |pattern, replacement|
+        content.gsub!(pattern, replacement)
+      end
+
+      if content != original_content
+        File.write(file_path, content)
+        say_status :updated, "base classes in #{file_path.sub(Rails.root.to_s + '/', '')}", :blue
+      end
+    end
+
+    def remove_root_module_wrapper(content, root_module)
+      lines = content.lines
+      result = []
+      module_depth = 0
+      root_module_line = nil
+
+      lines.each_with_index do |line, idx|
+        if line.match?(/^\s*module\s+#{Regexp.escape(root_module)}\s*$/)
+          root_module_line = idx
+          module_depth = 1
+          next
+        end
+
+        if root_module_line
+          # Track module/class/def depth
+          if line.match?(/^\s*(module|class)\s+\w/)
+            module_depth += 1
+          elsif line.match?(/^\s*end\s*$/)
+            module_depth -= 1
+            if module_depth == 0
+              # This is the closing end of the root module, skip it
+              root_module_line = nil
+              next
+            end
+          end
+
+          # Dedent by 2 spaces
+          result << line.sub(/^  /, "")
+        else
+          result << line
+        end
+      end
+
+      result.join
+    end
+
+    def cleanup_directory(dir)
+      return unless File.directory?(dir)
+
+      # First clean up any empty subdirectories
+      Dir.glob("#{dir}/**/").sort_by { |d| -d.count("/") }.each do |subdir|
+        next unless File.directory?(subdir) && Dir.empty?(subdir)
+
+        if options[:dry_run]
+          say_status :dry_run, "Would remove empty #{subdir.sub(Rails.root.to_s + '/', '')}", :yellow
+        else
+          FileUtils.rmdir(subdir)
+          say_status :removed, subdir.sub(Rails.root.to_s + "/", ""), :red
+        end
+      end
+
+      # Then try to remove the directory itself if empty
+      return unless File.directory?(dir) && Dir.empty?(dir)
+
+      if options[:dry_run]
+        say_status :dry_run, "Would remove empty #{dir.sub(Rails.root.to_s + '/', '')}", :yellow
+      else
+        FileUtils.rmdir(dir)
+        say_status :removed, dir.sub(Rails.root.to_s + "/", ""), :red
+      end
+    end
+
+    def camelize(str)
+      return "AI" if str.downcase == "ai"
+      return "ML" if str.downcase == "ml"
+      return "LLM" if str.downcase == "llm"
+
+      str.split(/[-_]/).map(&:capitalize).join
+    end
+  end
+end

data/lib/generators/ruby_llm_agents/multi_tenancy_generator.rb

@@ -10,8 +10,11 @@ module RubyLlmAgents
   #   rails generate ruby_llm_agents:multi_tenancy
   #
   # This will create migrations for:
-  #   - ruby_llm_agents_tenant_budgets table for per-tenant budget configuration
-  #   - Adding tenant_id column to ruby_llm_agents_executions
+  #   - ruby_llm_agents_tenants table for per-tenant configuration
+  #   - Adding tenant columns to ruby_llm_agents_executions
+  #
+  # For users upgrading from an older version:
+  #   - Renames ruby_llm_agents_tenant_budgets to ruby_llm_agents_tenants
   #
   class MultiTenancyGenerator < ::Rails::Generators::Base
     include ::ActiveRecord::Generators::Migration
@@ -20,21 +23,31 @@ module RubyLlmAgents
 
     desc "Adds multi-tenancy support to RubyLLM::Agents"
 
-    def create_tenant_budgets_migration
-      if table_exists?(:ruby_llm_agents_tenant_budgets)
-        say_status :skip, "ruby_llm_agents_tenant_budgets table already exists", :yellow
+    def create_tenants_migration
+      if table_exists?(:ruby_llm_agents_tenants)
+        say_status :skip, "ruby_llm_agents_tenants table already exists", :yellow
         return
       end
 
-      migration_template(
-        "create_tenant_budgets_migration.rb.tt",
-        File.join(db_migrate_path, "create_ruby_llm_agents_tenant_budgets.rb")
-      )
+      if table_exists?(:ruby_llm_agents_tenant_budgets)
+        # Upgrade path: rename existing table
+        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")
+        )
+      else
+        # Fresh install: create new table
+        migration_template(
+          "create_tenants_migration.rb.tt",
+          File.join(db_migrate_path, "create_ruby_llm_agents_tenants.rb")
+        )
+      end
     end
 
     def create_add_tenant_to_executions_migration
       if column_exists?(:ruby_llm_agents_executions, :tenant_id)
-        say_status :skip, "tenant_id column already exists", :yellow
+        say_status :skip, "tenant_id column already exists on executions", :yellow
         return
       end
 
@@ -50,23 +63,30 @@ module RubyLlmAgents
       say ""
       say "Next steps:"
       say "  1. Run: rails db:migrate"
-      say "  2. Configure multi-tenancy in your initializer:"
+      say "  2. Add llm_tenant to your tenant model:"
       say ""
-      say "     RubyLLM::Agents.configure do |config|"
-      say "       config.multi_tenancy_enabled = true"
-      say "       config.tenant_resolver = -> { Current.tenant&.id }"
+      say "     class Organization < ApplicationRecord"
+      say "       include RubyLLM::Agents::LLMTenant"
+      say ""
+      say "       llm_tenant id: :id,            # Method for tenant_id"
+      say "                  budget: true,       # Auto-create budget on creation"
+      say "                  limits: {           # Optional default limits"
+      say "                    daily_cost: 100,"
+      say "                    monthly_cost: 1000"
+      say "                  },"
+      say "                  enforcement: :hard  # :none, :soft, or :hard"
       say "     end"
       say ""
-      say "  3. Set Current.tenant in your ApplicationController"
+      say "  3. Pass tenant to agents:"
+      say ""
+      say "     MyAgent.call(prompt, tenant: current_organization)"
       say ""
-      say "  4. Create tenant budgets:"
+      say "  4. Query usage:"
       say ""
-      say "     RubyLLM::Agents::TenantBudget.create!("
-      say "       tenant_id: 'acme_corp',"
-      say "       daily_limit: 50.0,"
-      say "       monthly_limit: 500.0,"
-      say "       enforcement: 'hard'"
-      say "     )"
+      say "     tenant = RubyLLM::Agents::Tenant.for(organization)"
+      say "     tenant.cost_today        # => 12.34"
+      say "     tenant.tokens_this_month # => 50000"
+      say "     tenant.usage_summary     # => { cost: ..., tokens: ..., ... }"
       say ""
     end
 

data/lib/generators/ruby_llm_agents/restructure_generator.rb

@@ -121,7 +121,7 @@ module RubyLlmAgents
         namespace = config.namespace_for(mapping[:category])
 
         Dir.glob("#{directory_path}/**/*.rb").each do |file|
-          update_file_namespace(file, namespace)
+          update_file_namespace(file, namespace) if namespace
         end
       end
     end
@@ -190,7 +190,7 @@ module RubyLlmAgents
     private
 
     def root_directory
-      @root_directory ||= options[:root] || RubyLLM::Agents.configuration.root_directory
+      @root_directory ||= options[:root] || RubyLLM::Agents.configuration.root_directory || "agents"
     end
 
     def root_namespace

data/lib/generators/ruby_llm_agents/speaker_generator.rb

@@ -9,10 +9,9 @@ module RubyLlmAgents
   #   rails generate ruby_llm_agents:speaker Narrator
   #   rails generate ruby_llm_agents:speaker Narrator --provider elevenlabs
   #   rails generate ruby_llm_agents:speaker Narrator --voice alloy --speed 1.25
-  #   rails generate ruby_llm_agents:speaker Narrator --root=ai
   #
   # This will create:
-  #   - app/{root}/audio/speakers/narrator_speaker.rb
+  #   - app/agents/audio/narrator_speaker.rb
   #
   class SpeakerGenerator < ::Rails::Generators::NamedBase
     source_root File.expand_path("templates", __dir__)
@@ -29,48 +28,36 @@ module RubyLlmAgents
                  desc: "Output format (mp3, wav, ogg, flac)"
     class_option :cache, type: :string, default: nil,
                  desc: "Cache TTL (e.g., '7.days')"
-    class_option :root,
-                 type: :string,
-                 default: nil,
-                 desc: "Root directory name (default: uses config or 'llm')"
-    class_option :namespace,
-                 type: :string,
-                 default: nil,
-                 desc: "Root namespace (default: camelized root or config)"
 
     def ensure_base_class_and_skill_file
-      @root_namespace = root_namespace
-      @audio_namespace = "#{root_namespace}::Audio"
-      speakers_dir = "app/#{root_directory}/audio/speakers"
+      audio_dir = "app/agents/audio"
 
       # Create directory if needed
-      empty_directory speakers_dir
+      empty_directory audio_dir
 
       # Create base class if it doesn't exist
-      base_class_path = "#{speakers_dir}/application_speaker.rb"
+      base_class_path = "#{audio_dir}/application_speaker.rb"
       unless File.exist?(File.join(destination_root, base_class_path))
         template "application_speaker.rb.tt", base_class_path
       end
 
       # Create skill file if it doesn't exist
-      skill_file_path = "#{speakers_dir}/SPEAKERS.md"
+      skill_file_path = "#{audio_dir}/SPEAKERS.md"
       unless File.exist?(File.join(destination_root, skill_file_path))
         template "skills/SPEAKERS.md.tt", skill_file_path
       end
     end
 
     def create_speaker_file
-      # Support nested paths: "article/narrator" -> "app/{root}/audio/speakers/article/narrator_speaker.rb"
-      @root_namespace = root_namespace
-      @audio_namespace = "#{root_namespace}::Audio"
+      # Support nested paths: "article/narrator" -> "app/agents/audio/article/narrator_speaker.rb"
       speaker_path = name.underscore
-      template "speaker.rb.tt", "app/#{root_directory}/audio/speakers/#{speaker_path}_speaker.rb"
+      template "speaker.rb.tt", "app/agents/audio/#{speaker_path}_speaker.rb"
     end
 
     def show_usage
       # Build full class name from path
       speaker_class_name = name.split("/").map(&:camelize).join("::")
-      full_class_name = "#{root_namespace}::Audio::#{speaker_class_name}Speaker"
+      full_class_name = "Audio::#{speaker_class_name}Speaker"
       say ""
       say "Speaker #{full_class_name} created!", :green
       say ""
@@ -91,24 +78,6 @@ module RubyLlmAgents
 
     private
 
-    def root_directory
-      @root_directory ||= options[:root] || RubyLLM::Agents.configuration.root_directory
-    end
-
-    def root_namespace
-      @root_namespace ||= options[:namespace] || camelize(root_directory)
-    end
-
-    def camelize(str)
-      # Handle special cases for common abbreviations
-      return "AI" if str.downcase == "ai"
-      return "ML" if str.downcase == "ml"
-      return "LLM" if str.downcase == "llm"
-
-      # Standard camelization
-      str.split(/[-_]/).map(&:capitalize).join
-    end
-
     def default_model
       case options[:provider].to_s
       when "elevenlabs"