ruby_llm 1.12.0 → 1.14.1

data/lib/generators/ruby_llm/generator_helpers.rb

@@ -53,9 +53,9 @@ module RubyLLM
         params = []
 
         add_association_params(params, :messages, message_table_name, message_model_name,
-                               owner_table: chat_table_name, plural: true)
+                               owner_table: chat_table_name, owner_model_name: chat_model_name, plural: true)
         add_association_params(params, :model, model_table_name, model_model_name,
-                               owner_table: chat_table_name)
+                               owner_table: chat_table_name, owner_model_name: chat_model_name)
 
         "acts_as_chat#{" #{params.join(', ')}" if params.any?}"
       end
@@ -64,11 +64,11 @@ module RubyLLM
         params = []
 
         add_association_params(params, :chat, chat_table_name, chat_model_name,
-                               owner_table: message_table_name)
+                               owner_table: message_table_name, owner_model_name: message_model_name)
         add_association_params(params, :tool_calls, tool_call_table_name, tool_call_model_name,
-                               owner_table: message_table_name, plural: true)
+                               owner_table: message_table_name, owner_model_name: message_model_name, plural: true)
         add_association_params(params, :model, model_table_name, model_model_name,
-                               owner_table: message_table_name)
+                               owner_table: message_table_name, owner_model_name: message_model_name)
 
         "acts_as_message#{" #{params.join(', ')}" if params.any?}"
       end
@@ -77,7 +77,7 @@ module RubyLLM
         params = []
 
         add_association_params(params, :chats, chat_table_name, chat_model_name,
-                               owner_table: model_table_name, plural: true)
+                               owner_table: model_table_name, owner_model_name: model_model_name, plural: true)
 
         "acts_as_model#{" #{params.join(', ')}" if params.any?}"
       end
@@ -86,7 +86,7 @@ module RubyLLM
         params = []
 
         add_association_params(params, :message, message_table_name, message_model_name,
-                               owner_table: tool_call_table_name)
+                               owner_table: tool_call_table_name, owner_model_name: tool_call_model_name)
 
         "acts_as_tool_call#{" #{params.join(', ')}" if params.any?}"
       end
@@ -121,6 +121,10 @@ module RubyLLM
         "[#{Rails::VERSION::MAJOR}.#{Rails::VERSION::MINOR}]"
       end
 
+      def create_migration_class_name(table_name)
+        "create_#{table_name}".camelize
+      end
+
       def postgresql?
         ::ActiveRecord::Base.connection.adapter_name.downcase.include?('postgresql')
       rescue StandardError
@@ -141,22 +145,38 @@ module RubyLLM
 
       private
 
-      def add_association_params(params, default_assoc, table_name, model_name, owner_table:, plural: false) # rubocop:disable Metrics/ParameterLists
+      # rubocop:disable Metrics/ParameterLists
+      def add_association_params(params, default_assoc, table_name, model_name,
+                                 owner_table:, owner_model_name:, plural: false)
         assoc = plural ? table_name.to_sym : table_name.singularize.to_sym
-
-        default_foreign_key = "#{default_assoc}_id"
-        # has_many/has_one: foreign key is on the associated table pointing back to owner
-        # belongs_to:       foreign key is on the owner table pointing to associated table
-        foreign_key = if plural || default_assoc.to_s.pluralize == default_assoc.to_s # has_many or has_one
-                        "#{owner_table.singularize}_id"
-                      else # belongs_to
-                        "#{table_name.singularize}_id"
-                      end
+        collection_association = collection_association?(default_assoc, plural)
+        foreign_key = inferred_foreign_key(table_name, owner_table, collection_association)
+        default_foreign_key = default_inferred_foreign_key(assoc, owner_model_name, collection_association)
 
         params << "#{default_assoc}: :#{assoc}" if assoc != default_assoc
         params << "#{default_assoc.to_s.singularize}_class: '#{model_name}'" if model_name != assoc.to_s.classify
         params << "#{default_assoc}_foreign_key: :#{foreign_key}" if foreign_key != default_foreign_key
       end
+      # rubocop:enable Metrics/ParameterLists
+
+      def collection_association?(default_assoc, plural)
+        plural || default_assoc.to_s.pluralize == default_assoc.to_s
+      end
+
+      def inferred_foreign_key(table_name, owner_table, collection_association)
+        return "#{table_name.singularize}_id" unless collection_association
+
+        "#{owner_table.singularize}_id"
+      end
+
+      # Rails default inference:
+      # belongs_to :assoc    -> assoc_id
+      # has_many/has_one     -> owner demodulized model name + _id
+      def default_inferred_foreign_key(association_name, owner_model_name, collection_association)
+        return "#{association_name}_id" unless collection_association
+
+        "#{owner_model_name.demodulize.underscore}_id"
+      end
 
       # Convert namespaced model names to proper table names
       # e.g., "Assistant::Chat" -> "assistant_chats" (not "assistant/chats")

data/lib/generators/ruby_llm/install/install_generator.rb

@@ -21,7 +21,7 @@ module RubyLLM
                                          desc: 'Skip ActiveStorage installation and attachment setup'
 
       desc 'Creates models and migrations for RubyLLM Rails integration\n' \
-           'Usage: rails g ruby_llm:install [chat:ChatName] [message:MessageName] ...'
+           'Usage: bin/rails g ruby_llm:install [chat:ChatName] [message:MessageName] ...'
 
       def self.next_migration_number(dirname)
         ::ActiveRecord::Generators::Base.next_migration_number(dirname)
@@ -30,20 +30,12 @@ module RubyLLM
       def create_migration_files
         migration_template 'create_chats_migration.rb.tt',
                            "db/migrate/create_#{chat_table_name}.rb"
-
-        sleep 1 # Ensure different timestamp
         migration_template 'create_messages_migration.rb.tt',
                            "db/migrate/create_#{message_table_name}.rb"
-
-        sleep 1 # Ensure different timestamp
         migration_template 'create_tool_calls_migration.rb.tt',
                            "db/migrate/create_#{tool_call_table_name}.rb"
-
-        sleep 1 # Ensure different timestamp
         migration_template 'create_models_migration.rb.tt',
                            "db/migrate/create_#{model_table_name}.rb"
-
-        sleep 1 # Ensure different timestamp
         migration_template 'add_references_to_chats_tool_calls_and_messages_migration.rb.tt',
                            'db/migrate/add_references_to_' \
                            "#{chat_table_name}_#{tool_call_table_name}_and_#{message_table_name}.rb"
@@ -63,6 +55,13 @@ module RubyLLM
         template 'initializer.rb.tt', 'config/initializers/ruby_llm.rb'
       end
 
+      def create_convention_directories
+        %w[agents tools schemas prompts].each do |name|
+          empty_directory "app/#{name}"
+          create_file "app/#{name}/.gitkeep" unless File.exist?(Rails.root.join("app/#{name}/.gitkeep"))
+        end
+      end
+
       def install_active_storage
         return if options[:skip_active_storage]
 
@@ -76,21 +75,18 @@ module RubyLLM
         say '  ✅ ActiveStorage configured for file attachments support', :green unless options[:skip_active_storage]
 
         say "\n  Next steps:", :yellow
-        say '     1. Run: rails db:migrate'
-        say '     2. Set your API keys in config/initializers/ruby_llm.rb'
-
-        say "     3. Start chatting: #{chat_model_name}.create!(model: 'gpt-4.1-nano').ask('Hello!')"
+        say '     1. Run: bin/rails db:migrate'
+        say '     2. Run: bin/rails ruby_llm:load_models'
+        say '     3. Set your API keys in config/initializers/ruby_llm.rb'
 
-        say "\n  🚀 Model registry is database-backed!", :cyan
-        say '     Models automatically load from the database'
-        say '     Pass model names as strings - RubyLLM handles the rest!'
-        say "     Specify provider when needed: Chat.create!(model: 'gemini-2.5-flash', provider: 'vertexai')"
+        say "     4. Start chatting: #{chat_model_name}.create!(model: 'gpt-5-nano').ask('Hello!')"
+        say "     5. Optional UI: #{chat_ui_generator_command}"
 
         if options[:skip_active_storage]
           say "\n  📎 Note: ActiveStorage was skipped", :yellow
           say '     File attachments won\'t work without ActiveStorage.'
           say '     To enable later:'
-          say '       1. Run: rails active_storage:install && rails db:migrate'
+          say '       1. Run: bin/rails active_storage:install && bin/rails db:migrate'
           say "       2. Add to your #{message_model_name} model: has_many_attached :attachments"
         end
 
@@ -101,6 +97,14 @@ module RubyLLM
         say '     • 🐦 Follow for updates: https://x.com/paolino'
         say "\n"
       end
+
+      private
+
+      def chat_ui_generator_command
+        mappings = model_mappings.join(' ')
+        mappings = " #{mappings}" unless mappings.empty?
+        "bin/rails generate ruby_llm:chat_ui#{mappings}"
+      end
     end
   end
 end

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

@@ -1,4 +1,4 @@
-class Create<%= chat_model_name.gsub('::', '').pluralize %> < ActiveRecord::Migration<%= migration_version %>
+class <%= create_migration_class_name(chat_table_name) %> < ActiveRecord::Migration<%= migration_version %>
   def change
     create_table :<%= chat_table_name %> do |t|
       t.timestamps

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

@@ -1,4 +1,4 @@
-class Create<%= message_model_name.gsub('::', '').pluralize %> < ActiveRecord::Migration<%= migration_version %>
+class <%= create_migration_class_name(message_table_name) %> < ActiveRecord::Migration<%= migration_version %>
   def change
     create_table :<%= message_table_name %> do |t|
       t.string :role, null: false

data/lib/generators/ruby_llm/install/templates/create_models_migration.rb.tt

@@ -1,4 +1,4 @@
-class Create<%= model_model_name.gsub('::', '').pluralize %> < ActiveRecord::Migration<%= migration_version %>
+class <%= create_migration_class_name(model_table_name) %> < ActiveRecord::Migration<%= migration_version %>
   def change
     create_table :<%= model_table_name %> do |t|
       t.string :model_id, null: false
@@ -27,19 +27,13 @@ class Create<%= model_model_name.gsub('::', '').pluralize %> < ActiveRecord::Mig
 <% end %>
       t.timestamps
 
-      t.index [:provider, :model_id], unique: true
+      t.index [ :provider, :model_id ], unique: true
       t.index :provider
       t.index :family
-<% if postgresql? %>
+<% if postgresql? -%>
       t.index :capabilities, using: :gin
       t.index :modalities, using: :gin
-<% end %>
-    end
-
-    # Load models from JSON
-    say_with_time "Loading models from models.json" do
-      RubyLLM.models.load_from_json!
-      <%= model_model_name %>.save_to_database
+<% end -%>
     end
   end
 end

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

@@ -1,10 +1,10 @@
 <%#- # Migration for creating tool_calls table with database-specific JSON handling -%>
-class Create<%= tool_call_model_name.gsub('::', '').pluralize %> < ActiveRecord::Migration<%= migration_version %>
+class <%= create_migration_class_name(tool_call_table_name) %> < ActiveRecord::Migration<%= migration_version %>
   def change
     create_table :<%= tool_call_table_name %> do |t|
       t.string :tool_call_id, null: false
       t.string :name, null: false
-      t.string :thought_signature
+      t.text :thought_signature
 <% if postgresql? %>
       t.jsonb :arguments, default: {}
 <% elsif mysql? %>

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

@@ -1,6 +1,6 @@
 RubyLLM.configure do |config|
-  config.openai_api_key = ENV['OPENAI_API_KEY'] || Rails.application.credentials.dig(:openai_api_key)
-  # config.default_model = "gpt-4.1-nano"
+  config.openai_api_key = ENV.fetch("OPENAI_API_KEY", Rails.application.credentials.dig(:openai_api_key))
+  # config.default_model = "gpt-5-nano"
 
   # Use the new association-based acts_as API (recommended)
   config.use_new_acts_as = true

data/lib/generators/ruby_llm/schema/schema_generator.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module RubyLLM
+  module Generators
+    # Generator for RubyLLM schema classes.
+    class SchemaGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path('templates', __dir__)
+
+      namespace 'ruby_llm:schema'
+
+      desc 'Creates a RubyLLM schema class'
+
+      def create_schema_file
+        template 'schema.rb.tt', File.join('app/schemas', class_path, "#{file_name}.rb")
+      end
+
+      private
+
+      def schema_class_name
+        class_name.end_with?('Schema') ? class_name : "#{class_name}Schema"
+      end
+    end
+  end
+end

data/lib/generators/ruby_llm/schema/templates/schema.rb.tt

@@ -0,0 +1,2 @@
+class <%= schema_class_name %> < RubyLLM::Schema
+end

data/lib/generators/ruby_llm/tool/templates/tool.rb.tt

@@ -0,0 +1,9 @@
+class <%= class_name %>Tool < RubyLLM::Tool
+  description "TODO: describe what this tool does"
+
+  def execute
+    # TODO: return something to the LLM.
+    # Anything you return here gets converted to a string.
+    "TODO: implement <%= class_name %>Tool"
+  end
+end

data/lib/generators/ruby_llm/tool/templates/tool_call.html.erb.tt

@@ -0,0 +1,13 @@
+<%% tool_call_error = tool_call.tool_error_message %>
+<%% if tool_call_error.present? %>
+  <%%= render "messages/error", message: tool_calls, title: "Tool Call Error", error_message: tool_call_error %>
+<%% else %>
+  <div id="message_<%%= tool_calls.id %>" class="message"
+       style="margin-bottom: 20px; padding: 10px; border-left: 3px solid #6b7280; background: #f9fafb;">
+    <div style="font-weight: bold; margin-bottom: 5px;"><%= tool_display_name %> Call</div>
+    <pre style="white-space: pre-wrap; margin: 0;"><%%= tool_call.name %>(<%%= tool_call.arguments.map { |k, v| "#{k}: #{v.inspect}" }.join(", ") %>)</pre>
+    <div style="font-size: 0.85em; color: #666; margin-top: 5px;">
+      <%%= tool_calls.created_at&.strftime("%I:%M %p") %>
+    </div>
+  </div>
+<%% end %>

data/lib/generators/ruby_llm/tool/templates/tool_result.html.erb.tt

@@ -0,0 +1,13 @@
+<%% error_message = tool.tool_error_message %>
+<%% if error_message.present? %>
+  <%%= render "messages/error", message: tool, title: "Tool Result Error", error_message: error_message %>
+<%% else %>
+  <div id="message_<%%= tool.id %>" class="message"
+       style="margin-bottom: 20px; padding: 10px; border-left: 3px solid #6b7280; background: #f9fafb;">
+    <div style="font-weight: bold; margin-bottom: 5px;"><%= tool_display_name %> Result</div>
+    <pre style="white-space: pre-wrap; margin: 0;"><%%= tool.content.presence || "(no output)" %></pre>
+    <div style="font-size: 0.85em; color: #666; margin-top: 5px;">
+      <%%= tool.created_at&.strftime("%I:%M %p") %>
+    </div>
+  </div>
+<%% end %>

data/lib/generators/ruby_llm/tool/tool_generator.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module RubyLLM
+  module Generators
+    # Generator for RubyLLM tool classes and related message partials.
+    class ToolGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path('templates', __dir__)
+
+      namespace 'ruby_llm:tool'
+
+      check_class_collision suffix: 'Tool'
+
+      desc 'Creates a RubyLLM tool class and matching tool call/result view partials'
+
+      def create_tool_file
+        template 'tool.rb.tt', File.join('app/tools', class_path, "#{file_name}_tool.rb")
+      end
+
+      def create_tool_view_partials
+        empty_directory 'app/views/messages/tool_calls'
+        empty_directory 'app/views/messages/tool_results'
+
+        create_tool_call_partial
+        create_tool_result_partial
+      end
+
+      private
+
+      def create_tool_call_partial
+        destination_path = File.join('app/views/messages/tool_calls', "_#{tool_partial_name}.html.erb")
+        default_partial_path = File.join(destination_root, 'app/views/messages/tool_calls/_default.html.erb')
+
+        if File.exist?(default_partial_path)
+          default_markup = tool_named_call_markup(File.read(default_partial_path))
+          indented_markup = indent_non_empty_lines(default_markup, 2)
+          create_file destination_path, <<~ERB
+            <% tool_call_error = tool_call.tool_error_message %>
+            <% if tool_call_error.present? %>
+              <%= render "messages/error", message: tool_calls, title: "Tool Call Error", error_message: tool_call_error %>
+            <% else %>
+            #{indented_markup}<% end %>
+          ERB
+        else
+          template 'tool_call.html.erb.tt', destination_path
+        end
+
+        strip_trailing_whitespace(destination_path)
+      end
+
+      def create_tool_result_partial
+        destination_path = File.join('app/views/messages/tool_results', "_#{tool_partial_name}.html.erb")
+        default_partial_path = File.join(destination_root, 'app/views/messages/tool_results/_default.html.erb')
+
+        if File.exist?(default_partial_path)
+          create_file destination_path, tool_named_result_markup(File.read(default_partial_path))
+        else
+          template 'tool_result.html.erb.tt', destination_path
+        end
+
+        strip_trailing_whitespace(destination_path)
+      end
+
+      def tool_named_call_markup(markup)
+        markup.sub('Tool Call', "#{tool_display_name} Call")
+      end
+
+      def tool_named_result_markup(markup)
+        markup.sub(/\bTool\b(?!\s*Result)/, "#{tool_display_name} Result")
+      end
+
+      def tool_display_name
+        class_name.demodulize
+      end
+
+      def tool_partial_name
+        file_name.delete_suffix('_tool')
+      end
+
+      def indent_non_empty_lines(markup, spaces)
+        indentation = ' ' * spaces
+        markup.lines.map { |line| line.strip.empty? ? line : "#{indentation}#{line}" }.join
+      end
+
+      def strip_trailing_whitespace(path)
+        content = File.read(path)
+        stripped_content = content.lines.map(&:rstrip).join("\n")
+        stripped_content = "#{stripped_content}\n" unless stripped_content.end_with?("\n")
+        return if content == stripped_content
+
+        File.write(path, stripped_content)
+      end
+    end
+  end
+end

data/lib/generators/ruby_llm/upgrade_to_v1_10/upgrade_to_v1_10_generator.rb

@@ -38,7 +38,7 @@ module RubyLLM
 
           Next steps:
           1. Review the generated migration
-          2. Run: rails db:migrate
+          2. Run: bin/rails db:migrate
           3. Restart your application server
 
           📚 See the v1.10.0 release notes for details on extended thinking support.

data/lib/generators/ruby_llm/upgrade_to_v1_14/templates/add_v1_14_tool_call_columns.rb.tt

@@ -0,0 +1,7 @@
+class AddRubyLlmV114Columns < ActiveRecord::Migration<%= migration_version %>
+  def change
+    if column_exists?(:<%= tool_call_table_name %>, :thought_signature, :string)
+      change_column :<%= tool_call_table_name %>, :thought_signature, :text
+    end
+  end
+end

data/lib/generators/ruby_llm/upgrade_to_v1_14/upgrade_to_v1_14_generator.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+require 'rails/generators/active_record'
+require_relative '../generator_helpers'
+
+module RubyLLM
+  module Generators
+    # Generator to fix tool call thought signature column type for MySQL safety.
+    class UpgradeToV114Generator < Rails::Generators::Base
+      include Rails::Generators::Migration
+      include RubyLLM::Generators::GeneratorHelpers
+
+      namespace 'ruby_llm:upgrade_to_v1_14'
+      source_root File.expand_path('templates', __dir__)
+
+      argument :model_mappings, type: :array, default: [], banner: 'tool_call:ToolCallName'
+
+      desc 'Updates tool call thought_signature column to text introduced in v1.14.0'
+
+      def self.next_migration_number(dirname)
+        ::ActiveRecord::Generators::Base.next_migration_number(dirname)
+      end
+
+      def create_migration_file
+        parse_model_mappings
+
+        migration_template 'add_v1_14_tool_call_columns.rb.tt',
+                           'db/migrate/add_ruby_llm_v1_14_columns.rb',
+                           migration_version: migration_version,
+                           tool_call_table_name: tool_call_table_name
+      end
+
+      def show_next_steps
+        say_status :success, 'Upgrade prepared!', :green
+        say <<~INSTRUCTIONS
+
+          Next steps:
+          1. Review the generated migration
+          2. Run: bin/rails db:migrate
+          3. Restart your application server
+
+          📚 See the v1.14.0 release notes for details on thought signature persistence.
+
+        INSTRUCTIONS
+      end
+    end
+  end
+end

data/lib/generators/ruby_llm/upgrade_to_v1_7/upgrade_to_v1_7_generator.rb

@@ -25,7 +25,7 @@ module RubyLLM
       argument :model_mappings, type: :array, default: [], banner: 'chat:ChatName message:MessageName ...'
 
       desc 'Upgrades existing RubyLLM apps to v1.7 with new Rails-like API\n' \
-           'Usage: rails g ruby_llm:upgrade_to_v1_7 [chat:ChatName] [message:MessageName] ...'
+           'Usage: bin/rails g ruby_llm:upgrade_to_v1_7 [chat:ChatName] [message:MessageName] ...'
 
       def self.next_migration_number(dirname)
         ::ActiveRecord::Generators::Base.next_migration_number(dirname)
@@ -40,8 +40,6 @@ module RubyLLM
                              "db/migrate/create_#{table_name_for(model_model_name)}.rb",
                              migration_version: migration_version,
                              model_model_name: model_model_name
-
-          sleep 1 # Ensure different timestamp
         end
 
         migration_template 'migration.rb.tt',
@@ -93,7 +91,7 @@ module RubyLLM
 
           Next steps:
           1. Review the generated migrations
-          2. Run: rails db:migrate
+          2. Run: bin/rails db:migrate
           3. Update your code to use the new API: #{chat_model_name}.create! now has the same signature as RubyLLM.chat
 
           ⚠️  If you get "undefined method 'acts_as_model'" during migration:

data/lib/generators/ruby_llm/upgrade_to_v1_9/upgrade_to_v1_9_generator.rb

@@ -37,7 +37,7 @@ module RubyLLM
 
           Next steps:
           1. Review the generated migration
-          2. Run: rails db:migrate
+          2. Run: bin/rails db:migrate
           3. Restart your application server
 
           📚 See the v1.9.0 release notes for details on cached token tracking and raw content support.

data/lib/ruby_llm/active_record/acts_as.rb

@@ -12,15 +12,21 @@ module RubyLLM
         # Monkey-patch Models to use database when ActsAs is active
         RubyLLM::Models.class_eval do
           def self.load_models
-            read_from_database
+            database_models = read_from_database
+            return database_models if database_models.any?
+
+            RubyLLM.logger.debug { 'Model registry is empty in database, falling back to JSON registry' }
+            read_from_json
           rescue StandardError => e
-            RubyLLM.logger.debug "Failed to load models from database: #{e.message}, falling back to JSON"
+            RubyLLM.logger.debug { "Failed to load models from database: #{e.message}, falling back to JSON" }
             read_from_json
           end
 
           def self.read_from_database
             model_class = RubyLLM.config.model_registry_class
             model_class = model_class.constantize if model_class.is_a?(String)
+            return [] unless model_class.table_exists?
+
             model_class.all.map(&:to_llm)
           end
 
@@ -53,8 +59,6 @@ module RubyLLM
                      foreign_key: model_foreign_key,
                      optional: true
 
-          delegate :add_message, to: :to_llm
-
           define_method :messages_association do
             send(messages_association_name)
           end
@@ -144,6 +148,8 @@ module RubyLLM
 
         def acts_as_tool_call(message: :message, message_class: nil, message_foreign_key: nil, # rubocop:disable Metrics/ParameterLists
                               result: :result, result_class: nil, result_foreign_key: nil)
+          include RubyLLM::ActiveRecord::ToolCallMethods
+
           class_attribute :message_association_name, :result_association_name, :message_class, :result_class
 
           self.message_association_name = message