Rails Generator for RubyLLM Models

Gemfile

@@ -8,6 +8,7 @@ group :development do
   # Rails integration dependencies
   gem 'activerecord', '>= 6.0', '< 9.0'
   gem 'activesupport', '>= 6.0', '< 9.0'
+  gem 'rails', '>= 7.0.0'
 
   # Development dependencies
   gem 'bundler', '>= 2.0'

README.md

@@ -121,6 +121,32 @@ See the [Installation Guide](https://rubyllm.com/installation) for full details.
 
 Add persistence to your chat models effortlessly:
 
+### Option 1: Rails Generate
+
+Simply run the generator to set up all required models:
+
+```bash
+rails generate ruby_llm:install
+```
+
+This creates all necessary migrations, models, and database tables. Then just use them:
+
+```ruby
+# In your controller
+chat = Chat.create!(model_id: "gpt-4o-mini")
+chat.ask("What's your favorite Ruby gem?") do |chunk|
+  Turbo::StreamsChannel.broadcast_append_to(
+    chat, target: "response", partial: "messages/chunk", locals: { chunk: chunk }
+  )
+end
+
+# That's it - chat history is automatically saved
+```
+
+### Option 2: Manually
+
+Or, add RubyLLM to your existing ActiveRecord models:
+
 ```ruby
 # app/models/chat.rb
 class Chat < ApplicationRecord

docs/guides/rails.md

@@ -7,31 +7,67 @@ permalink: /guides/rails
 ---
 
 # Rails Integration
+
 {: .no_toc }
 
-RubyLLM offers seamless integration with Ruby on Rails applications through helpers for ActiveRecord models. This allows you to easily persist chat conversations, including messages and tool interactions, directly in your database.
-{: .fs-6 .fw-300 }
+RubyLLM offers seamless integration with Ruby on Rails applications through helpers for ActiveRecord models. This allows you to easily persist chat conversations, including messages and tool interactions, directly in your database. {: .fs-6 .fw-300 }
 
 ## Table of contents
+
 {: .no_toc .text-delta }
 
-1. TOC
-{:toc}
+1. TOC {:toc}
 
 ---
 
 After reading this guide, you will know:
 
-*   How to set up ActiveRecord models for persisting chats and messages.
-*   How to use `acts_as_chat` and `acts_as_message`.
-*   How chat interactions automatically persist data.
-*   A basic approach for integrating streaming responses with Hotwire/Turbo Streams.
+- How to set up ActiveRecord models for persisting chats and messages.
+- How to use `acts_as_chat` and `acts_as_message`.
+- How chat interactions automatically persist data.
+- A basic approach for integrating streaming responses with Hotwire/Turbo Streams.
 
 ## Setup
 
-### Create Migrations
+### Using the Generator
+
+The simplest way to set up RubyLLM in your Rails application is to use the provided generator:
+
+```bash
+# Generate all necessary models, migrations, and configuration
+rails generate ruby_llm:install
+```
+
+This will create:
+
+- A `Chat` model for storing chat sessions
+- A `Message` model for storing individual messages
+- A `ToolCall` model for storing tool calls
+- Migrations for all these models
+- A RubyLLM initializer
+
+If you need to customize model names to avoid namespace collisions, you can provide options:
+
+```bash
+rails generate ruby_llm:install \
+  --chat-model-name=Conversation \
+  --message-model-name=ChatMessage \
+  --tool-call-model-name=FunctionCall
+```
+
+After running the generator, simply run the migrations:
+
+```bash
+rails db:migrate
+```
+
+### Manual Setup (Alternative)
+
+If you prefer to set up the models manually, follow these steps:
 
-First, generate migrations for your `Chat` and `Message` models. You'll also need a `ToolCall` model if you plan to use [Tools]({% link guides/tools.md %}).
+#### Create Migrations
+
+Generate migrations for your `Chat` and `Message` models. You'll also need a `ToolCall` model if you plan to use [Tools]({% link guides/tools.md %}).
 
 ```bash
 # Generate basic models and migrations
@@ -88,7 +124,7 @@ end
 
 Run the migrations: `rails db:migrate`
 
-### Set Up Models with `acts_as` Helpers
+#### Set Up Models with `acts_as` Helpers
 
 Include the RubyLLM helpers in your ActiveRecord models.
 
@@ -121,13 +157,21 @@ class ToolCall < ApplicationRecord
 end
 ```
 
-{: .note }
-The `acts_as` helpers primarily handle loading history and saving messages/tool calls related to the chat interaction. Add your application-specific logic (associations, validations, scopes, callbacks) as usual.
+{: .note } The `acts_as` helpers primarily handle loading history and saving messages/tool calls related to the chat interaction. Add your application-specific logic (associations, validations, scopes, callbacks) as usual.
 
 ### Configure RubyLLM
 
 Ensure your RubyLLM configuration (API keys, etc.) is set up, typically in `config/initializers/ruby_llm.rb`. See the [Installation Guide]({% link installation.md %}) for details.
 
+```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"]
+  # Add other provider keys as needed
+end
+```
+
 ## Basic Usage
 
 The `acts_as_chat` helper delegates common `RubyLLM::Chat` methods to your `Chat` model. When you call these methods on an ActiveRecord `Chat` instance, RubyLLM automatically handles persistence.
@@ -181,6 +225,18 @@ You can combine `acts_as_chat` with streaming and Turbo Streams for real-time UI
 Here's a simplified approach using a background job:
 
 ```ruby
+# app/jobs/chat_job.rb
+class ChatJob < ApplicationJob
+  def perform(chat_id, question)
+    chat = Chat.find(chat_id)
+    chat.ask(question) do |chunk|
+      Turbo::StreamsChannel.broadcast_append_to(
+        chat, target: "response", partial: "messages/chunk", locals: { chunk: chunk }
+      )
+    end
+  end
+end
+
 # app/models/chat.rb
 class Chat < ApplicationRecord
   acts_as_chat
@@ -235,33 +291,32 @@ end
 <!-- Your form to submit new messages -->
 <%= form_with(url: chat_messages_path(@chat), method: :post) do |f| %>
   <%= f.text_area :content %>
-  <%= f.submit "Send" %>
+  <%= f.button "Send", disable_with: "Sending..." %>
 <% end %>
 
 <%# app/views/messages/_message.html.erb %>
 <%= turbo_frame_tag message do %>
   <div class="message <%= message.role %>">
     <strong><%= message.role.capitalize %>:</strong>
     <%# Target div for streaming content %>
-    <div id="<%= dom_id(message, "content") %>" style="display: inline;">
+    <div id="<%= dom_id(message, "content") %>" class="message-content">
       <%# Render initial content if not streaming, otherwise job appends here %>
       <%= simple_format(message.content) %>
     </div>
   </div>
 <% end %>
 ```
 
-{: .note }
-This example shows the core idea. You'll need to adapt the broadcasting, targets, and partials for your specific UI needs (e.g., handling Markdown rendering, adding styling, showing typing indicators). See the [Streaming Responses Guide]({% link guides/streaming.md %}) for more on streaming itself.
+{: .note } This example shows the core idea. You'll need to adapt the broadcasting, targets, and partials for your specific UI needs (e.g., handling Markdown rendering, adding styling, showing typing indicators). See the [Streaming Responses Guide]({% link guides/streaming.md %}) for more on streaming itself.
 
 ## Customizing Models
 
 Your `Chat`, `Message`, and `ToolCall` models are standard ActiveRecord models. You can add any other associations, validations, scopes, callbacks, or methods as needed for your application logic. The `acts_as` helpers provide the core persistence bridge to RubyLLM without interfering with other model behavior.
 
 ## Next Steps
 
-*   [Chatting with AI Models]({% link guides/chat.md %})
-*   [Using Tools]({% link guides/tools.md %})
-*   [Streaming Responses]({% link guides/streaming.md %})
-*   [Working with Models]({% link guides/models.md %})
-*   [Error Handling]({% link guides/error-handling.md %})
+- [Chatting with AI Models]({% link guides/chat.md %})
+- [Using Tools]({% link guides/tools.md %})
+- [Streaming Responses]({% link guides/streaming.md %})
+- [Working with Models]({% link guides/models.md %})
+- [Error Handling]({% link guides/error-handling.md %})

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

@@ -0,0 +1,75 @@
+# 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
+
+## 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
+   ```
+
+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"]
+     # etc.
+   end
+   ```
+
+3. **Start using RubyLLM in your code:**
+   ```ruby
+   # In a background job
+   class ChatJob < ApplicationJob
+     def perform(chat_id, question)
+       chat = <%= options[:chat_model_name] %>.find(chat_id)
+       chat.ask(question) do |chunk|
+         Turbo::StreamsChannel.broadcast_append_to(
+           chat, target: "response", partial: "messages/chunk", locals: { chunk: chunk }
+         )
+       end
+     end
+   end
+
+   # Queue the job
+   chat = <%= options[:chat_model_name] %>.create!(model_id: "gpt-4o-mini")
+   ChatJob.perform_later(chat.id, "What's your favorite Ruby gem?")
+   ```
+
+4. **For streaming responses** with ActionCable or Turbo:
+   ```ruby
+   chat.ask("Tell me about Ruby on Rails") do |chunk|
+     Turbo::StreamsChannel.broadcast_append_to(
+       chat, target: "response", partial: "messages/chunk", locals: { chunk: chunk }
+     )
+   end
+   ```
+
+## Advanced Usage
+
+- Add more fields to your models as needed
+- Customize the views to match your application design
+- Create a controller for chat interactions
+
+For more information, visit the [RubyLLM Documentation](https://github.com/crmne/ruby_llm)

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,16 @@
+# This migration must be run AFTER create_<%= options[:chat_model_name].tableize %> and create_<%= options[:tool_call_model_name].tableize %> migrations
+# to ensure proper foreign key references
+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

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

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