Rails Generator for RubyLLM Models (#75)

This PR adds a Rails generator for RubyLLM models, making it easier to
integrate RubyLLM with Rails applications.

### Changes in this PR

- Added generator that creates Chat, Message, and ToolCall models with
migrations
- Updated Rails integration guide with generator instructions
- Added support for customizing model names to avoid namespace
collisions
- Added cross-database support for JSON columns

### Recent updates to address PR comments

1. **Renamed README.md.tt to INSTALL_INFO.md.tt** to avoid confusion
with the project README, and updated the reference in the
install_generator.rb file.

2. **Fixed migration order** by using timestamps in the migration
filenames in the install_generator.rb file. This ensures that migrations
run in the correct order (chats first, then tool_calls, then messages).

3. **Updated railtie.rb** to include rake tasks from the
lib/ruby_llm/tasks directory, which addresses the issue mentioned in the
comments about rake tasks not showing up in Rails applications.

4. **Reverted several changes in docs/guides/rails.md** as requested in
the comments, including fixing formatting issues and removing
unnecessary content.

5. **Removed the comment about migration order** from the
create_messages_migration.rb.tt file since we're now enforcing it with
timestamps.

These changes should address all the issues mentioned in the PR
comments.

---------

Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Jason Amster <jayamster@gmail.com>
Co-authored-by: Carmine Paolino <carmine@paolino.me>

Author: 4 people

README.md

@@ -123,34 +123,31 @@ See the [Installation Guide](https://rubyllm.com/installation) for full details.
 
 Add persistence to your chat models effortlessly:
 
+```bash
+# Generate models and migrations (available in v1.4.0)
+rails generate ruby_llm:install
+```
+
 ```ruby
-# app/models/chat.rb
+# Or add to existing models
 class Chat < ApplicationRecord
   acts_as_chat # Automatically saves messages & tool calls
-  # ... your other model logic ...
 end
 
-# app/models/message.rb
 class Message < ApplicationRecord
   acts_as_message
-  # ...
 end
 
-# app/models/tool_call.rb (if using tools)
 class ToolCall < ApplicationRecord
   acts_as_tool_call
-  # ...
 end
 
-# Now interacting with a Chat record persists the conversation:
-chat_record = Chat.create!(model_id: "gpt-4.1-nano")
-chat_record.ask("Explain Active Record callbacks.") # User & Assistant messages saved
-
-# Works seamlessly with file attachments - types automatically detected
-chat_record.ask("What's in this file?", with: "report.pdf")
-chat_record.ask("Analyze these", with: ["image.jpg", "data.csv", "notes.txt"])
+# Now chats persist automatically
+chat = Chat.create!(model_id: "gpt-4.1-nano")
+chat.ask("What's in this file?", with: "report.pdf")
 ```
-Check the [Rails Integration Guide](https://rubyllm.com/guides/rails) for more.
+
+See the [Rails Integration Guide](https://rubyllm.com/guides/rails) for details.
 
 ## Learn More
 

docs/guides/rails.md

@@ -59,9 +59,46 @@ This approach has one important consequence: **you cannot use `validates :conten
 
 ## Setting Up Your Rails Application
 
-### Database Migrations
+### Quick Setup with Generator
 
-First, generate migrations for your `Chat`, `Message`, and `ToolCall` models.
+{: .d-inline-block }
+
+Available in v1.4.0
+{: .label .label-yellow }
+
+The easiest way to get started is using the provided Rails generator:
+
+```bash
+rails generate ruby_llm:install
+```
+
+This generator automatically creates:
+- All required migrations (Chat, Message, ToolCall tables)
+- Model files with `acts_as_chat`, `acts_as_message`, and `acts_as_tool_call` configured
+- A RubyLLM initializer in `config/initializers/ruby_llm.rb`
+
+After running the generator:
+
+```bash
+rails db:migrate
+```
+
+You're ready to go! The generator handles all the setup complexity for you.
+
+#### Generator Options
+
+The generator supports custom model names if needed:
+
+```bash
+# Use custom model names
+rails generate ruby_llm:install --chat-model-name=Conversation --message-model-name=ChatMessage --tool-call-model-name=FunctionCall
+```
+
+This is useful if you already have models with these names or prefer different naming conventions.
+
+### Manual Setup
+
+If you prefer to set up manually or need custom table/model names, you can create the migrations yourself:
 
 ```bash
 # Generate basic models and migrations
@@ -70,7 +107,7 @@ rails g model Message chat:references role:string content:text model_id:string i
 rails g model ToolCall message:references tool_call_id:string:index name:string arguments:jsonb
 ```
 
-Adjust the migrations as needed (e.g., `null: false` constraints, `jsonb` type for PostgreSQL).
+Then adjust the migrations as needed (e.g., `null: false` constraints, `jsonb` type for PostgreSQL).
 
 ```ruby
 # db/migrate/YYYYMMDDHHMMSS_create_chats.rb
@@ -105,17 +142,23 @@ class CreateToolCalls < ActiveRecord::Migration[7.1]
   def change
     create_table :tool_calls do |t|
       t.references :message, null: false, foreign_key: true # Assistant message making the call
-      t.string :tool_call_id, null: false, index: { unique: true } # Provider's ID for the call
+      t.string :tool_call_id, null: false # Provider's ID for the call
       t.string :name, null: false
-      t.jsonb :arguments, default: {} # Use jsonb for PostgreSQL
+      # Use jsonb for PostgreSQL, json for MySQL/SQLite
+      t.jsonb :arguments, default: {} # Change to t.json for non-PostgreSQL databases
       t.timestamps
     end
+
+    add_index :tool_calls, :tool_call_id, unique: true
   end
 end
 ```
 
 Run the migrations: `rails db:migrate`
 
+{: .note }
+**Database Compatibility:** The generator automatically detects your database and uses `jsonb` for PostgreSQL or `json` for MySQL/SQLite. If setting up manually, adjust the column type accordingly.
+
 ### ActiveStorage Setup for Attachments (Optional)
 
 If you want to use attachments (images, audio, PDFs) with your AI chats, you need to set up ActiveStorage:

docs/index.md

@@ -150,31 +150,28 @@ See the [Installation Guide](https://rubyllm.com/installation) for full details.
 
 Add persistence to your chat models effortlessly:
 
+```bash
+# Generate models and migrations (available in v1.4.0)
+rails generate ruby_llm:install
+```
+
 ```ruby
-# app/models/chat.rb
+# Or add to existing models
 class Chat < ApplicationRecord
   acts_as_chat # Automatically saves messages & tool calls
-  # ... your other model logic ...
 end
 
-# app/models/message.rb
 class Message < ApplicationRecord
   acts_as_message
-  # ...
 end
 
-# app/models/tool_call.rb (if using tools)
 class ToolCall < ApplicationRecord
   acts_as_tool_call
-  # ...
 end
 
-# Now interacting with a Chat record persists the conversation:
-chat_record = Chat.create!(model_id: "gpt-4.1-nano")
-chat_record.ask("Explain Active Record callbacks.") # User & Assistant messages saved
-
-# Works seamlessly with file attachments - types automatically detected
-chat_record.ask("What's in this file?", with: "report.pdf")
-chat_record.ask("Analyze these", with: ["image.jpg", "data.csv", "notes.txt"])
+# Now chats persist automatically
+chat = Chat.create!(model_id: "gpt-4.1-nano")
+chat.ask("What's in this file?", with: "report.pdf")
 ```
-Check the [Rails Integration Guide](https://rubyllm.com/guides/rails) for more.
+
+See the [Rails Integration Guide](https://rubyllm.com/guides/rails) for details.

lib/generators/ruby_llm/install/templates/INSTALL_INFO.md.tt

@@ -0,0 +1,108 @@
+# RubyLLM Rails Setup Complete!
+
+Thanks for installing RubyLLM in your Rails application. Here's what was created:
+
+## Models
+
+- `<%= options[:chat_model_name] %>` - Stores chat sessions and their associated model ID
+- `<%= options[:message_model_name] %>` - Stores individual messages in a chat
+- `<%= options[:tool_call_model_name] %>` - Stores tool calls made by language models
+
+**Note:** Do not add `validates :content, presence: true` to your Message model - RubyLLM creates empty assistant messages before API calls for streaming support.
+
+## Configuration Options
+
+The generator supports the following options to customize model names:
+
+```bash
+rails generate ruby_llm:install \
+  --chat-model-name=Conversation \
+  --message-model-name=ChatMessage \
+  --tool-call-model-name=FunctionCall
+```
+
+This is useful when you need to avoid namespace collisions with existing models in your application. Table names will be automatically derived from the model names following Rails conventions.
+
+## Next Steps
+
+1. **Run migrations:**
+   ```bash
+   rails db:migrate
+   ```
+
+   **Database Note:** The migrations use `jsonb` for PostgreSQL and `json` for MySQL/SQLite automatically.
+
+2. **Set your API keys** in `config/initializers/ruby_llm.rb` or using environment variables:
+   ```ruby
+   # config/initializers/ruby_llm.rb
+   RubyLLM.configure do |config|
+     config.openai_api_key = ENV['OPENAI_API_KEY']
+     config.anthropic_api_key = ENV['ANTHROPIC_API_KEY']
+     config.gemini_api_key = ENV['GEMINI_API_KEY']
+     # ... add other providers as needed
+   end
+   ```
+
+3. **Start using RubyLLM in your code:**
+   ```ruby
+   # Basic usage
+   chat = <%= options[:chat_model_name] %>.create!(model_id: 'gpt-4.1-nano')
+   response = chat.ask("What is Ruby on Rails?")
+
+   # With file attachments (requires ActiveStorage setup)
+   chat.ask("What's in this file?", with: "report.pdf")
+   chat.ask("Analyze these files", with: ["image.jpg", "data.csv", "notes.txt"])
+   ```
+
+4. **For streaming responses** with Hotwire/Turbo:
+   ```ruby
+   # app/models/<%= options[:message_model_name].underscore %>.rb
+   class <%= options[:message_model_name] %> < ApplicationRecord
+     acts_as_message
+
+     # Helper to broadcast chunks during streaming
+     def broadcast_append_chunk(chunk_content)
+       broadcast_append_to [ chat, "messages" ],
+         target: dom_id(self, "content"),
+         html: chunk_content
+     end
+   end
+
+   # app/jobs/chat_stream_job.rb
+   class ChatStreamJob < ApplicationJob
+     def perform(chat_id, user_content)
+       chat = <%= options[:chat_model_name] %>.find(chat_id)
+       chat.ask(user_content) do |chunk|
+         assistant_message = chat.messages.last
+         if chunk.content && assistant_message
+           assistant_message.broadcast_append_chunk(chunk.content)
+         end
+       end
+     end
+   end
+
+   # In your controller
+   ChatStreamJob.perform_later(@chat.id, params[:content])
+   ```
+
+## Optional: ActiveStorage for Attachments
+
+If you want to use file attachments (PDFs, images, etc.), set up ActiveStorage:
+
+```bash
+rails active_storage:install
+rails db:migrate
+```
+
+Then add to your Message model:
+```ruby
+class <%= options[:message_model_name] %> < ApplicationRecord
+  acts_as_message
+  has_many_attached :attachments
+end
+```
+
+## Learn More
+
+- See the [Rails Integration Guide](https://rubyllm.com/guides/rails) for detailed examples
+- Visit the [RubyLLM Documentation](https://rubyllm.com) for full API reference

lib/generators/ruby_llm/install/templates/chat_model.rb.tt

@@ -0,0 +1,3 @@
+class <%= options[:chat_model_name] %> < ApplicationRecord
+  <%= acts_as_chat_declaration %>
+end

lib/generators/ruby_llm/install/templates/create_chats_migration.rb.tt

@@ -0,0 +1,8 @@
+class Create<%= options[:chat_model_name].pluralize %> < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :<%= options[:chat_model_name].tableize %> do |t|
+      t.string :model_id
+      t.timestamps
+    end
+  end
+end

lib/generators/ruby_llm/install/templates/create_messages_migration.rb.tt

@@ -0,0 +1,15 @@
+# Migration for creating messages table with references to chats and tool_calls
+class Create<%= options[:message_model_name].pluralize %> < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :<%= options[:message_model_name].tableize %> do |t|
+      t.references :<%= options[:chat_model_name].tableize.singularize %>, null: false, foreign_key: true
+      t.string :role
+      t.text :content
+      t.string :model_id
+      t.integer :input_tokens
+      t.integer :output_tokens
+      t.references :<%= options[:tool_call_model_name].tableize.singularize %>
+      t.timestamps
+    end
+  end
+end

lib/generators/ruby_llm/install/templates/create_tool_calls_migration.rb.tt

@@ -0,0 +1,14 @@
+<%#- # Migration for creating tool_calls table with database-specific JSON handling -%>
+class Create<%= options[:tool_call_model_name].pluralize %> < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :<%= options[:tool_call_model_name].tableize %> do |t|
+      t.references :<%= options[:message_model_name].tableize.singularize %>, null: false, foreign_key: true
+      t.string :tool_call_id, null: false
+      t.string :name, null: false
+      t.<%= postgresql? ? 'jsonb' : 'json' %> :arguments, default: {}
+      t.timestamps
+    end
+
+    add_index :<%= options[:tool_call_model_name].tableize %>, :tool_call_id
+  end
+end

lib/generators/ruby_llm/install/templates/initializer.rb.tt

@@ -0,0 +1,14 @@
+# RubyLLM configuration
+RubyLLM.configure do |config|
+  # Set your API keys here or use environment variables
+  # config.openai_api_key = ENV["OPENAI_API_KEY"]
+  # config.anthropic_api_key = ENV["ANTHROPIC_API_KEY"]
+  # config.gemini_api_key = ENV["GEMINI_API_KEY"]
+  # config.deepseek_api_key = ENV["DEEPSEEK_API_KEY"]
+  
+  # Uncomment to set a default model
+  # config.default_model = "gpt-4o-mini"
+  
+  # Uncomment to set default options
+  # config.default_options = { temperature: 0.7 }
+end

lib/generators/ruby_llm/install/templates/message_model.rb.tt

@@ -0,0 +1,3 @@
+class <%= options[:message_model_name] %> < ApplicationRecord
+  <%= acts_as_message_declaration %>
+end