ruby_llm 1.13.2 → 1.14.0

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,22 +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. Run: rails ruby_llm:load_models'
+        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 "     4. Start chatting: #{chat_model_name}.create!(model: 'gpt-4.1-nano').ask('Hello!')"
-
-        say "\n  🚀 Model registry supports database + JSON fallback!", :cyan
-        say '     Models load from database when present, otherwise from models.json'
-        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
 
@@ -102,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_models_migration.rb.tt

@@ -27,14 +27,13 @@ class <%= create_migration_class_name(model_table_name) %> < ActiveRecord::Migra
 <% 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 -%>
     end
-
   end
 end

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

@@ -4,7 +4,7 @@ class <%= create_migration_class_name(tool_call_table_name) %> < ActiveRecord::M
     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

@@ -148,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

data/lib/ruby_llm/active_record/acts_as_legacy.rb

@@ -58,6 +58,8 @@ module RubyLLM
         end
 
         def acts_as_tool_call(message_class: 'Message', message_foreign_key: nil, result_foreign_key: nil)
+          include RubyLLM::ActiveRecord::ToolCallMethods
+
           @message_class = message_class.to_s
           @message_foreign_key = message_foreign_key || ActiveSupport::Inflector.foreign_key(@message_class)
           @result_foreign_key = result_foreign_key || ActiveSupport::Inflector.foreign_key(name)

data/lib/ruby_llm/active_record/chat_methods.rb

@@ -125,7 +125,7 @@ module RubyLLM
         self.assume_model_exists = assume_exists
         resolve_model_from_strings
         save!
-        to_llm.with_model(model.model_id, provider: model.provider.to_sym, assume_exists:)
+        to_llm.with_model(model_association.model_id, provider: model_association.provider.to_sym, assume_exists:)
         self
       end
 

data/lib/ruby_llm/active_record/message_methods.rb

@@ -39,6 +39,25 @@ module RubyLLM
         )
       end
 
+      def to_partial_path
+        partial_prefix = self.class.name.underscore.pluralize
+        role_partial = if to_llm.tool_call?
+                         'tool_calls'
+                       elsif role.to_s == 'tool'
+                         'tool'
+                       else
+                         role.to_s.presence || 'assistant'
+                       end
+        "#{partial_prefix}/#{role_partial}"
+      end
+
+      def tool_error_message
+        payload = parse_payload(content)
+        return unless payload.is_a?(Hash)
+
+        payload['error'] || payload[:error]
+      end
+
       private
 
       def thinking_text_value
@@ -109,6 +128,15 @@ module RubyLLM
         @_tempfiles << tempfile
         tempfile
       end
+
+      def parse_payload(value)
+        return value if value.is_a?(Hash) || value.is_a?(Array)
+        return if value.blank?
+
+        JSON.parse(value)
+      rescue JSON::ParserError
+        nil
+      end
     end
   end
 end

data/lib/ruby_llm/active_record/model_methods.rb

@@ -77,7 +77,7 @@ module RubyLLM
       delegate :supports?, :supports_vision?, :supports_functions?, :type,
                :input_price_per_million, :output_price_per_million,
                :function_calling?, :structured_output?, :batch?,
-               :reasoning?, :citations?, :streaming?, :provider_class,
+               :reasoning?, :citations?, :streaming?, :provider_class, :label,
                to: :to_llm
     end
   end

data/lib/ruby_llm/active_record/tool_call_methods.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module ActiveRecord
+    # Methods mixed into tool call models.
+    module ToolCallMethods
+      extend ActiveSupport::Concern
+
+      def tool_error_message
+        payload = parse_payload(arguments)
+        return unless payload.is_a?(Hash)
+
+        payload['error'] || payload[:error]
+      end
+
+      private
+
+      def parse_payload(value)
+        return value if value.is_a?(Hash) || value.is_a?(Array)
+        return if value.blank?
+
+        JSON.parse(value)
+      rescue JSON::ParserError
+        nil
+      end
+    end
+  end
+end

data/lib/ruby_llm/agent.rb

@@ -121,6 +121,7 @@ module RubyLLM
         input_values, = partition_inputs(kwargs)
         record = resolved_chat_model.find(id)
         apply_configuration(record, input_values:, persist_instructions: false)
+
         record
       end
 
@@ -129,6 +130,7 @@ module RubyLLM
 
         input_values, = partition_inputs(kwargs)
         record = chat_or_id.is_a?(resolved_chat_model) ? chat_or_id : resolved_chat_model.find(chat_or_id)
+        apply_assume_model_exists(record)
         runtime = runtime_context(chat: record, inputs: input_values)
         instructions_value = resolved_instructions_value(record, runtime, inputs: input_values)
         return record if instructions_value.nil?
@@ -227,9 +229,18 @@ module RubyLLM
       end
 
       def llm_chat_for(chat_object)
+        apply_assume_model_exists(chat_object)
         chat_object.respond_to?(:to_llm) ? chat_object.to_llm : chat_object
       end
 
+      def apply_assume_model_exists(chat_object)
+        return unless chat_kwargs.key?(:assume_model_exists) &&
+                      resolved_chat_model &&
+                      chat_object.is_a?(resolved_chat_model)
+
+        chat_object.assume_model_exists = chat_kwargs[:assume_model_exists]
+      end
+
       def evaluate(value, runtime)
         value.is_a?(Proc) ? runtime.instance_exec(&value) : value
       end

data/lib/ruby_llm/aliases.json

@@ -26,8 +26,7 @@
     "bedrock": "anthropic.claude-3-haiku-20240307-v1:0:200k"
   },
   "claude-3-opus": {
-    "anthropic": "claude-3-opus-20240229",
-    "bedrock": "anthropic.claude-3-opus-20240229-v1:0"
+    "anthropic": "claude-3-opus-20240229"
   },
   "claude-3-sonnet": {
     "anthropic": "claude-3-sonnet-20240229",
@@ -62,7 +61,8 @@
   "claude-opus-4-6": {
     "anthropic": "claude-opus-4-6",
     "openrouter": "anthropic/claude-opus-4.6",
-    "bedrock": "anthropic.claude-opus-4-6-v1"
+    "bedrock": "anthropic.claude-opus-4-6-v1",
+    "azure": "claude-opus-4-6"
   },
   "claude-sonnet-4": {
     "anthropic": "claude-sonnet-4-20250514",
@@ -81,7 +81,8 @@
   "claude-sonnet-4-6": {
     "anthropic": "claude-sonnet-4-6",
     "openrouter": "anthropic/claude-sonnet-4.6",
-    "bedrock": "anthropic.claude-sonnet-4-6"
+    "bedrock": "anthropic.claude-sonnet-4-6",
+    "azure": "claude-sonnet-4-6"
   },
   "deepseek-chat": {
     "deepseek": "deepseek-chat",
@@ -337,7 +338,8 @@
   },
   "gpt-5.1": {
     "openai": "gpt-5.1",
-    "openrouter": "openai/gpt-5.1"
+    "openrouter": "openai/gpt-5.1",
+    "azure": "gpt-5.1"
   },
   "gpt-5.1-codex": {
     "openai": "gpt-5.1-codex",
@@ -367,6 +369,14 @@
     "openai": "gpt-5.3-codex",
     "openrouter": "openai/gpt-5.3-codex"
   },
+  "gpt-5.4": {
+    "openai": "gpt-5.4",
+    "openrouter": "openai/gpt-5.4"
+  },
+  "gpt-5.4-pro": {
+    "openai": "gpt-5.4-pro",
+    "openrouter": "openai/gpt-5.4-pro"
+  },
   "gpt-audio": {
     "openai": "gpt-audio",
     "openrouter": "openai/gpt-audio"

data/lib/ruby_llm/attachment.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require 'pathname'
+require 'uri'
+
 module RubyLLM
   # A class representing a file attachment.
   class Attachment