Improve upgrade generator and add troubleshooting docs

- Fix instance variable usage in migration template
- Fix generators when using namespaced models
- Simplify upgrade instructions to point to migration guide
- Add troubleshooting section for acts_as_model error from issue #400
- Add warning about acts_as_model error directly in generator output
- Create initializer if missing during upgrade
- Use consistent helper methods across install and upgrade generators

Author: crmne

docs/_advanced/upgrading-to-1.7.md

@@ -187,6 +187,31 @@ The chat UI works with your existing Chat and Message models and includes:
 - Code syntax highlighting
 - Responsive design
 
+## Troubleshooting
+
+### "undefined local variable or method 'acts_as_model'" error during migration
+
+If you get this error when running `rails db:migrate`, add the configuration to `config/application.rb` **before** your Application class:
+
+```ruby
+# config/application.rb
+require_relative "boot"
+require "rails/all"
+
+# Configure RubyLLM before Rails::Application is inherited
+RubyLLM.configure do |config|
+  config.use_new_acts_as = true
+end
+
+module YourApp
+  class Application < Rails::Application
+    # ...
+  end
+end
+```
+
+This ensures RubyLLM is configured before ActiveRecord loads your models.
+
 ## New Applications
 
 Fresh installs get the model registry automatically:

gemfiles/rails_7.1.gemfile.lock

@@ -98,7 +98,7 @@ GEM
       rake
       thor (>= 0.14.0)
     ast (2.4.3)
-    async (2.31.0)
+    async (2.32.0)
       console (~> 1.29)
       fiber-annotation
       io-event (~> 1.11)

gemfiles/rails_7.2.gemfile.lock

@@ -92,7 +92,7 @@ GEM
       rake
       thor (>= 0.14.0)
     ast (2.4.3)
-    async (2.31.0)
+    async (2.32.0)
       console (~> 1.29)
       fiber-annotation
       io-event (~> 1.11)

gemfiles/rails_8.0.gemfile.lock

@@ -92,7 +92,7 @@ GEM
       rake
       thor (>= 0.14.0)
     ast (2.4.3)
-    async (2.31.0)
+    async (2.32.0)
       console (~> 1.29)
       fiber-annotation
       io-event (~> 1.11)

lib/generators/ruby_llm/install/install_generator.rb

@@ -64,85 +64,38 @@ def parse_model_mappings
     end
 
     def acts_as_chat_declaration
-      acts_as_chat_params = []
-      messages_assoc = message_model_name.tableize.to_sym
-      model_assoc = model_model_name.underscore.to_sym
-
-      if messages_assoc != :messages
-        acts_as_chat_params << "messages: :#{messages_assoc}"
-        if message_model_name != messages_assoc.to_s.classify
-          acts_as_chat_params << "message_class: '#{message_model_name}'"
-        end
-      end
+      params = []
 
-      if model_assoc != :model
-        acts_as_chat_params << "model: :#{model_assoc}"
-        acts_as_chat_params << "model_class: '#{model_model_name}'" if model_model_name != model_assoc.to_s.classify
-      end
+      add_association_params(params, :messages, message_table_name, message_model_name, plural: true)
+      add_association_params(params, :model, model_table_name, model_model_name)
 
-      if acts_as_chat_params.any?
-        "acts_as_chat #{acts_as_chat_params.join(', ')}"
-      else
-        'acts_as_chat'
-      end
+      "acts_as_chat#{" #{params.join(', ')}" if params.any?}"
     end
 
     def acts_as_message_declaration
       params = []
 
-      add_message_association_params(params, :chat, chat_model_name)
-      add_message_association_params(params, :tool_calls, tool_call_model_name, tableize: true)
-      add_message_association_params(params, :model, model_model_name)
+      add_association_params(params, :chat, chat_table_name, chat_model_name)
+      add_association_params(params, :tool_calls, tool_call_table_name, tool_call_model_name, plural: true)
+      add_association_params(params, :model, model_table_name, model_model_name)
 
-      params.any? ? "acts_as_message #{params.join(', ')}" : 'acts_as_message'
+      "acts_as_message#{" #{params.join(', ')}" if params.any?}"
     end
 
-    private
+    def acts_as_model_declaration
+      params = []
 
-    def add_message_association_params(params, default_assoc, model_name, tableize: false)
-      assoc = tableize ? model_name.tableize.to_sym : model_name.underscore.to_sym
+      add_association_params(params, :chats, chat_table_name, chat_model_name, plural: true)
 
-      return if assoc == default_assoc
-
-      params << "#{default_assoc}: :#{assoc}"
-      expected_class = assoc.to_s.classify
-      params << "#{default_assoc.to_s.singularize}_class: '#{model_name}'" if model_name != expected_class
+      "acts_as_model#{" #{params.join(', ')}" if params.any?}"
     end
 
-    public
-
     def acts_as_tool_call_declaration
-      acts_as_tool_call_params = []
-      message_assoc = message_model_name.underscore.to_sym
+      params = []
 
-      if message_assoc != :message
-        acts_as_tool_call_params << "message: :#{message_assoc}"
-        if message_model_name != message_assoc.to_s.classify
-          acts_as_tool_call_params << "message_class: '#{message_model_name}'"
-        end
-      end
+      add_association_params(params, :message, message_table_name, message_model_name)
 
-      if acts_as_tool_call_params.any?
-        "acts_as_tool_call #{acts_as_tool_call_params.join(', ')}"
-      else
-        'acts_as_tool_call'
-      end
-    end
-
-    def acts_as_model_declaration
-      acts_as_model_params = []
-      chats_assoc = chat_model_name.tableize.to_sym
-
-      if chats_assoc != :chats
-        acts_as_model_params << "chats: :#{chats_assoc}"
-        acts_as_model_params << "chat_class: '#{chat_model_name}'" if chat_model_name != chats_assoc.to_s.classify
-      end
-
-      if acts_as_model_params.any?
-        "acts_as_model #{acts_as_model_params.join(', ')}"
-      else
-        'acts_as_model'
-      end
+      "acts_as_tool_call#{" #{params.join(', ')}" if params.any?}"
     end
 
     def create_migration_files
@@ -186,12 +139,6 @@ def install_active_storage
       rails_command 'active_storage:install'
     end
 
-    def table_name_for(model_name)
-      # Convert namespaced model names to proper table names
-      # e.g., "Assistant::Chat" -> "assistant_chats" (not "assistant/chats")
-      model_name.underscore.pluralize.tr('/', '_')
-    end
-
     def show_install_info
       say "\n  ✅ RubyLLM installed!", :green
 
@@ -223,5 +170,22 @@ def show_install_info
       say '     • 🐦 Follow for updates: https://x.com/paolino'
       say "\n"
     end
+
+    private
+
+    def add_association_params(params, default_assoc, table_name, model_name, plural: false)
+      assoc = plural ? table_name.to_sym : table_name.singularize.to_sym
+
+      return if assoc == default_assoc
+
+      params << "#{default_assoc}: :#{assoc}"
+      params << "#{default_assoc.to_s.singularize}_class: '#{model_name}'" if model_name != assoc.to_s.classify
+    end
+
+    def table_name_for(model_name)
+      # Convert namespaced model names to proper table names
+      # e.g., "Assistant::Chat" -> "assistant_chats" (not "assistant/chats")
+      model_name.underscore.pluralize.tr('/', '_')
+    end
   end
 end

lib/generators/ruby_llm/upgrade_to_v1_7/templates/migration.rb.tt

@@ -3,6 +3,14 @@ class MigrateToRubyLLMModelReferences < ActiveRecord::Migration<%= migration_ver
     model_class = <%= model_model_name %>
     chat_class = <%= chat_model_name %>
     message_class = <%= message_model_name %>
+<% if @model_table_already_existed %>
+    # Load models from models.json if Model table already existed
+    say_with_time "Loading models from models.json" do
+      RubyLLM.models.load_from_json!
+      model_class.save_to_database
+      "Loaded #{model_class.count} models"
+    end
+<% end %>
 
     # Then check for any models in existing data that aren't in models.json
     say_with_time "Checking for additional models in existing data" do

lib/generators/ruby_llm/upgrade_to_v1_7/upgrade_to_v1_7_generator.rb

@@ -57,8 +57,10 @@ def parse_model_mappings
     end
 
     def create_migration_file
+      @model_table_already_existed = table_exists?(table_name_for(model_model_name))
+
       # First check if models table exists, if not create it
-      unless table_exists?(table_name_for(model_model_name))
+      unless @model_table_already_existed
         migration_template 'create_models_migration.rb.tt',
                            "db/migrate/create_#{table_name_for(model_model_name)}.rb",
                            migration_version: migration_version,
@@ -73,7 +75,8 @@ def create_migration_file
                          chat_model_name: chat_model_name,
                          message_model_name: message_model_name,
                          tool_call_model_name: tool_call_model_name,
-                         model_model_name: model_model_name
+                         model_model_name: model_model_name,
+                         model_table_already_existed: @model_table_already_existed
     end
 
     def create_model_file
@@ -94,51 +97,51 @@ class #{model_model_name} < ApplicationRecord
     end
 
     def acts_as_model_declaration
-      acts_as_model_params = []
-      chats_assoc = chat_model_name.tableize.to_sym
+      params = []
 
-      if chats_assoc != :chats
-        acts_as_model_params << "chats: :#{chats_assoc}"
-        acts_as_model_params << "chat_class: '#{chat_model_name}'" if chat_model_name != chats_assoc.to_s.classify
-      end
+      add_association_params(params, :chats, chat_table_name, chat_model_name, plural: true)
 
-      if acts_as_model_params.any?
-        "acts_as_model #{acts_as_model_params.join(', ')}"
-      else
-        'acts_as_model'
-      end
+      "acts_as_model#{" #{params.join(', ')}" if params.any?}"
     end
 
     def update_initializer
-      initializer_content = File.read('config/initializers/ruby_llm.rb')
-
-      unless initializer_content.include?('config.use_new_acts_as')
-        inject_into_file 'config/initializers/ruby_llm.rb', before: /^end/ do
-          lines = ["\n  # Enable the new Rails-like API", '  config.use_new_acts_as = true']
-          lines << "  config.model_registry_class = \"#{model_model_name}\"" if model_model_name != 'Model'
-          lines << "\n"
-          lines.join("\n")
-        end
+      initializer_path = 'config/initializers/ruby_llm.rb'
+
+      unless File.exist?(initializer_path)
+        say_status :warning, 'No initializer found. Creating one...', :yellow
+        template '../install/templates/initializer.rb.tt', initializer_path
+        return
+      end
+
+      initializer_content = File.read(initializer_path)
+
+      return if initializer_content.include?('config.use_new_acts_as')
+
+      inject_into_file initializer_path, before: /^end/ do
+        lines = ["\n  # Enable the new Rails-like API", '  config.use_new_acts_as = true']
+        lines << "  config.model_registry_class = \"#{model_model_name}\"" if model_model_name != 'Model'
+        lines << "\n"
+        lines.join("\n")
       end
-    rescue Errno::ENOENT
-      say_status :error, 'config/initializers/ruby_llm.rb not found', :red
     end
 
     def show_next_steps
-      say_status :success, 'Migration created!', :green
+      say_status :success, 'Upgrade prepared!', :green
       say <<~INSTRUCTIONS
 
         Next steps:
-        1. Review the migration: db/migrate/*_migrate_to_ruby_llm_model_references.rb
+        1. Review the generated migrations
         2. Run: rails db:migrate
-        3. Update config/initializers/ruby_llm.rb as shown above
-        4. Test your application thoroughly
+        3. Update your code to use the new API
+
+        ⚠️  If you get "undefined method 'acts_as_model'" during migration:
+           Add this to config/application.rb BEFORE your Application class:
+
+           RubyLLM.configure do |config|
+             config.use_new_acts_as = true
+           end
 
-        The migration will:
-        - Create the Models table if it doesn't exist
-        - Load all models from models.json
-        - Migrate your existing data to use foreign keys
-        - Preserve all existing data (string columns renamed to model_id_string)
+        📚 See the full migration guide: https://rubyllm.com/upgrading-to-1-7/
 
       INSTRUCTIONS
     end
@@ -149,6 +152,15 @@ def migration_version
       "[#{Rails::VERSION::MAJOR}.#{Rails::VERSION::MINOR}]"
     end
 
+    def add_association_params(params, default_assoc, table_name, model_name, plural: false)
+      assoc = plural ? table_name.to_sym : table_name.singularize.to_sym
+
+      return if assoc == default_assoc
+
+      params << "#{default_assoc}: :#{assoc}"
+      params << "#{default_assoc}_class: '#{model_name}'" if model_name != assoc.to_s.classify
+    end
+
     def table_name_for(model_name)
       # Convert namespaced model names to proper table names
       # e.g., "Assistant::Chat" -> "assistant_chats" (not "assistant/chats")

spec/dummy/config/application.rb

@@ -9,12 +9,6 @@
 require 'action_controller/railtie'
 
 Bundler.require(*Rails.groups)
-require 'ruby_llm'
-
-# Configure RubyLLM to use Model registry for tests
-RubyLLM.configure do |config|
-  config.model_registry_class = 'Model'
-end
 
 module Dummy
   class Application < Rails::Application