ruby_llm 2.0.0.rc2 → 2.0.0.rc4

data/lib/generators/ruby_llm/upgrade/templates/ruby_llm_upgrade.rb.tt

@@ -12,8 +12,10 @@ module RubyLLMUpgrade # :nodoc: all
 
     included do
       class_attribute :ruby_llm_upgrade_kind, instance_writer: false
+      self.enumerate_columns_in_select_statements = true
       default_scope { RubyLLMUpgrade.visible(self) }
-      around_save :guard_ruby_llm_upgrade, prepend: true
+      after_initialize { @ruby_llm_upgrade_epoch = RubyLLMUpgrade.epoch }
+      around_save :guard_ruby_llm_upgrade
       around_destroy :guard_ruby_llm_upgrade, prepend: true
       before_save { RubyLLMUpgrade.prepare_model(self) if ruby_llm_upgrade_kind == :chat }
     end
@@ -27,6 +29,9 @@ module RubyLLMUpgrade # :nodoc: all
 
   class << self
     def install(chat:, message:, tool_call:)
+      if version == 2 && message.table_exists? && message.column_names.include?('ruby_llm_content')
+        message.alias_attribute :content, :ruby_llm_content
+      end
       { chat => :chat, message => :message, tool_call => :tool_call }.each do |model, kind|
         next if model < Records
 
@@ -37,11 +42,13 @@ module RubyLLMUpgrade # :nodoc: all
       return if chat.instance_variable_defined?(:@ruby_llm_upgrade_operations)
 
       operations = guarded_operations(chat, OPERATIONS, claim: true)
-      if chat.private_method_defined?(:persist_usage_entry)
-        operations.define_method(:persist_usage_entry) do |entry|
-          RubyLLMUpgrade.guard(self) { super(entry) }
+      %i[persist_usage_entry persist_new_message persist_message_completion].each do |name|
+        next unless chat.private_method_defined?(name)
+
+        operations.define_method(name) do |*args, **options, &block|
+          RubyLLMUpgrade.guard(self) { super(*args, **options, &block) }
         end
-        operations.send(:private, :persist_usage_entry)
+        operations.send(:private, name)
       end
       chat.prepend operations
       chat.instance_variable_set(:@ruby_llm_upgrade_operations, operations)
@@ -73,7 +80,9 @@ module RubyLLMUpgrade # :nodoc: all
     def prepare_model(chat)
       return unless available?
 
-      settings = current_state.settings
+      state = current_state
+      settings = state.settings
+      return if version == 1 && settings['online'] && state.status == 'preparing'
       if version == 1
         return unless ActiveRecord::Base.connection.column_exists?(settings.fetch('chat_table'), :ruby_llm_model_id)
         return unless ActiveRecord::Base.connection.table_exists?('ruby_llm_models')
@@ -87,16 +96,30 @@ module RubyLLMUpgrade # :nodoc: all
       states = records(TABLE)
       states.uncached do
         states.transaction do
-          state = states.lock.first!
+          if ActiveRecord::Base.connection.adapter_name == 'SQLite' && claim
+            states.update_all('epoch = epoch')
+          end
+          state = states.lock(lock_clause).first!
           check_version(state)
           protect(record, state, claim: claim)
+          if record.instance_variable_get(:@ruby_llm_upgrade_epoch) != state[:epoch].to_i
+            raise ActiveRecord::ReadOnlyRecord, 'Reload the conversation after switching RubyLLM versions'
+          end
           yield
         end
       end
     end
 
+    def epoch
+      available? ? current_state[:epoch].to_i : 0
+    end
+
     private
 
+    def lock_clause
+      ActiveRecord::Base.connection.adapter_name == 'Mysql2' ? 'LOCK IN SHARE MODE' : 'FOR SHARE'
+    end
+
     def guarded_operations(model, names, claim:)
       Module.new do
         names.each do |name|
@@ -141,10 +164,15 @@ module RubyLLMUpgrade # :nodoc: all
 
     def records(table)
       @records ||= {}
-      @records[table] ||= Class.new(ActiveRecord::Base) do
+      model = @records[table] ||= Class.new(ActiveRecord::Base) do
         self.table_name = table
         self.inheritance_column = :_type_disabled
       end
+      if !model.column_names.include?(VERSION_COLUMN) &&
+         ActiveRecord::Base.connection.column_exists?(table, VERSION_COLUMN)
+        model.reset_column_information
+      end
+      model
     end
 
     def current_state
@@ -156,6 +184,7 @@ module RubyLLMUpgrade # :nodoc: all
     end
 
     def check_version(state)
+      return if version == 1 && state.active_version == 1 && state.settings['online'] && state.status == 'preparing'
       return if state.active_version == version && %w[active finalized].include?(state.status)
 
       raise ActiveRecord::ReadOnlyRecord,

data/lib/generators/ruby_llm/upgrade/templates/upgrade_initializer.rb.tt

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
-require 'active_record/base'
 require Rails.root.join('app/models/concerns/ruby_llm_upgrade')
 
 Rails.application.config.to_prepare do
+  require 'active_record/base'
   tool_call = if Gem::Version.new(RubyLLM::VERSION).segments.first >= 2
                 RubyLLM::ActiveRecord::ToolCall
               else

data/lib/generators/ruby_llm/upgrade/upgrade_generator.rb

@@ -25,7 +25,9 @@ module RubyLLM
       class_option :phase, type: :string, enum: %w[prepare backfill finish cleanup],
                            desc: 'Generate one upgrade phase; cleanup runs in a later deployment'
       class_option :mode, type: :string, enum: %w[rename copy], default: 'rename',
-                          desc: 'Copy keeps a protected 1.16 rollback path until cleanup'
+                          desc: 'Copy prepares and backfills online, with protected 1.16 rollback until cleanup'
+      class_option :discard_incomplete_tool_calls, type: :boolean, default: false,
+                                                   desc: 'Discard all incomplete legacy tool calls at copy finish'
 
       argument :model_mappings,
                type: :array,
@@ -39,6 +41,7 @@ module RubyLLM
       end
 
       def create_migration_files
+        validate_cleanup_options
         parse_model_mappings(allowed_types: MODEL_MAPPING_TYPES, defaults: MODEL_MAPPING_DEFAULTS)
         say_status :models, resolved_model_mappings
 
@@ -62,15 +65,25 @@ module RubyLLM
 
             Copy mode retains the legacy tables and a separate chat model reference.
             Install the generated RubyLLMUpgrade concern and initializer in BOTH the
-            1.16 rollback build and the 2.0 build. They protect whole conversations
+            running 1.16 build and the 2.0 build BEFORE running prepare. Restart
+            all affected 1.16 processes so they load the guards and explicit column
+            selects. The guards protect whole conversations
             changed by 2.0. Direct SQL, bulk updates/deletes and attachment purges
             bypass these guards; review those application paths before upgrading.
 
-            Pause affected traffic, workers, scheduled jobs and retries. Review and
-            rehearse prepare, backfill and finish on a production database copy,
-            then migrate and load models before restarting the 2.0 application.
+            Rehearse prepare, backfill and finish on a production database copy.
+            Run prepare and backfill from the 2.0 build while 1.16 serves traffic.
+            Stop affected traffic, workers, scheduled jobs and retries BEFORE finish.
+            Finish catches up intervening writes, validates and activates 2.0.
+            Then load models and restart the 2.0 application.
             Keep the old model/tool-call classes in the 1.16 build.
 
+            PostgreSQL, MySQL and SQLite support this workflow. Schema changes can
+            block writes; SQLite also serializes backfill and app writes.
+            Use a direct connection or session-mode pool for copy migrations.
+            db:migrate runs ALL pending phases. Stop at the backfill timestamp to
+            defer finish, or pause AI before running all three together.
+
             With all affected processes stopped, use the 2.0 build to run:
               bin/rails ruby_llm:upgrade:rollback  # activates the protected 1.16 view
               bin/rails ruby_llm:upgrade:resume    # reconciles 1.16 writes, activates 2.0
@@ -122,6 +135,14 @@ module RubyLLM
       private
 
       def copy_mode? = options[:mode] == 'copy'
+      def discard_incomplete_tool_calls? = options[:discard_incomplete_tool_calls]
+
+      def validate_cleanup_options
+        return unless discard_incomplete_tool_calls?
+        return if copy_mode? && options[:phase].in?([nil, 'finish'])
+
+        raise Thor::Error, 'Discard incomplete tool calls only with --mode copy and the finish phase'
+      end
 
       def copy_upgrade_settings
         {

data/lib/generators/ruby_llm/upgrade/upgrade_migration.rb

@@ -6,12 +6,22 @@ module RubyLLM
       TABLE = :ruby_llm_v2_upgrades
       VERSION_COLUMN = :ruby_llm_version
 
+      def self.for(connection: ::ActiveRecord::Base.connection)
+        require_relative 'online_copy_migration'
+        OnlineCopyMigration.new(connection:)
+      end
+
       def initialize(connection: ::ActiveRecord::Base.connection)
         @connection = connection
       end
 
       def prepare(settings)
         create_state_table unless @connection.table_exists?(TABLE)
+        prepare_state(settings)
+        yield if block_given?
+      end
+
+      def prepare_state(settings)
         existing = states.first
         if existing
           raise 'This database has a different RubyLLM copy upgrade' unless existing.settings == settings.stringify_keys
@@ -24,6 +34,9 @@ module RubyLLM
           states.create!(settings: settings.stringify_keys)
         end
       end
+      private :prepare_state
+
+      def online? = false
 
       def copy_table(source, target)
         return if @connection.table_exists?(target)
@@ -146,6 +159,7 @@ module RubyLLM
           table.integer :active_version, null: false, default: 1
           table.string :status, null: false, default: 'preparing'
           table.boolean :needs_reconcile, null: false, default: false
+          table.bigint :epoch, null: false, default: 0
           table.json :settings, null: false
         end
       end
@@ -234,7 +248,8 @@ module RubyLLM
         calls = records(:ruby_llm_tool_calls).where(message_type: configuration.fetch('message_class'), result_id: nil)
         return unless calls.exists?
 
-        raise 'Finish pending tool calls and approvals before switching versions'
+        raise 'Finish pending tool calls and approvals before switching versions. ' \
+              'For abandoned legacy calls, see https://rubyllm.com/upgrading/#incomplete-tool-calls'
       end
 
       def reconcile

data/lib/ruby_llm/accounting/usage.rb

@@ -163,6 +163,7 @@ module RubyLLM
           # A request that produced several results, like a multi-image
           # generation, is billed once: the first result carries the call.
           billed = result.is_a?(Array) ? result.first : result
+          billed.model_info = message_model(billed) if billed.is_a?(Message)
           pending = @pending.dup
           if pending.empty?
             attach_to_result(billed)
@@ -187,6 +188,14 @@ module RubyLLM
 
         private
 
+        def message_model(message)
+          return @model_info if message.model.nil? || message.model == @model_info&.id
+
+          RubyLLM.models.find(message.model, provider: @provider.slug, config: @config)
+        rescue ModelNotFoundError
+          @model_info
+        end
+
         # A request that never reached the provider, or that the provider
         # refused before running it, cannot have been billed; possibly-billed
         # failures keep their usage unknown.

data/lib/ruby_llm/agent.rb

@@ -53,8 +53,7 @@ module RubyLLM
       :@input_names => [],
       :@fallbacks => [],
       :@fallback_options => {},
-      :@rescue_handlers => [],
-      :@instructions => []
+      :@rescue_handlers => []
     }.freeze
     # Simple value options: a class-level getter/setter macro whose value the
     # agent forwards to the matching Chat#with_* when it builds its chat.
@@ -177,15 +176,16 @@ module RubyLLM
       #     "Today is #{Date.current}"
       #   end
       #
-      # A named agent uses its conventional template automatically when it
-      # exists, even without calling this method. In Rails mode, declarations
-      # persist when the record is created unless <tt>persist: false</tt>;
+      # The class's own declarations take precedence over its conventional
+      # template. Inherited declarations are used only when neither exists.
+      # In Rails mode, declarations persist when the record is created unless
+      # <tt>persist: false</tt>;
       # ::find always reapplies them without rewriting history. Called with no
       # arguments, returns the declarations.
       def instructions(text = nil, append: false, persist: true, cache_until_here: false, **prompt_locals, &block)
         return instruction_declarations if text.nil? && prompt_locals.empty? && !block_given?
 
-        instruction_declarations << {
+        (@instruction_declarations ||= []) << {
           value: block || text || { prompt: 'instructions', locals: prompt_locals },
           append: append,
           persist: persist,
@@ -611,6 +611,8 @@ module RubyLLM
       end
 
       def copy_inherited_config_to(subclass)
+        subclass.instance_variable_set(:@inherited_instruction_declarations, instruction_declarations.dup)
+
         DUPED_INHERITED_CONFIG.each do |ivar, default|
           value = instance_variable_defined?(ivar) ? instance_variable_get(ivar) : default
           subclass.instance_variable_set(ivar, value.respond_to?(:dup) ? value.dup : value)
@@ -767,8 +769,7 @@ module RubyLLM
       end
 
       def instructions_config
-        return instruction_declarations if instruction_declarations.any?
-        return [] unless default_instructions_prompt_exists?
+        return instruction_declarations if @instruction_declarations&.any? || !default_instructions_prompt_exists?
 
         [{
           value: { prompt: 'instructions', locals: {} },
@@ -779,7 +780,7 @@ module RubyLLM
       end
 
       def instruction_declarations
-        @instruction_declarations ||= []
+        @instruction_declarations || @inherited_instruction_declarations || []
       end
 
       def rails_chat_record?(chat)

data/lib/ruby_llm/aliases.json

@@ -1,8 +1,4 @@
 {
-  "claude-3-haiku": {
-    "bedrock": "anthropic.claude-3-haiku-20240307-v1:0",
-    "openrouter": "anthropic/claude-3-haiku"
-  },
   "claude-fable-5": {
     "anthropic": "claude-fable-5",
     "openrouter": "anthropic/claude-fable-5",
@@ -471,6 +467,14 @@
     "openrouter": "openai/gpt-image-2",
     "azure": "gpt-image-2"
   },
+  "gpt-image-2.5-flare": {
+    "openai": "gpt-image-2.5-flare",
+    "openrouter": "openai/gpt-image-2.5-flare"
+  },
+  "gpt-image-2.5-sunburst": {
+    "openai": "gpt-image-2.5-sunburst",
+    "openrouter": "openai/gpt-image-2.5-sunburst"
+  },
   "gpt-oss-120b": {
     "vertexai": "openai/gpt-oss-120b-maas",
     "openrouter": "openai/gpt-oss-120b"
@@ -532,6 +536,24 @@
   "grok-4-latest": {
     "xai": "grok-4.3"
   },
+  "grok-4.1-fast-non-reasoning": {
+    "vertexai": "xai/grok-4.1-fast-non-reasoning"
+  },
+  "grok-4.1-fast-reasoning": {
+    "vertexai": "xai/grok-4.1-fast-reasoning"
+  },
+  "grok-4.20-non-reasoning": {
+    "vertexai": "xai/grok-4.20-non-reasoning"
+  },
+  "grok-4.20-reasoning": {
+    "vertexai": "xai/grok-4.20-reasoning"
+  },
+  "grok-4.3": {
+    "vertexai": "xai/grok-4.3"
+  },
+  "grok-4.6": {
+    "vertexai": "xai/grok-4.6"
+  },
   "grok-latest": {
     "xai": "grok-4.3"
   },

data/lib/ruby_llm/attachment.rb

@@ -67,6 +67,11 @@ module RubyLLM
     #
     # +config:+ is the Configuration a URL source is downloaded with, and
     # defaults to the global one.
+    #
+    # Paths and URLs must be trusted and authorized by the application.
+    # They can be read or fetched during construction to detect the MIME type.
+    # Validate upload parameters before passing them here: an unchecked String
+    # can access local files or internal network endpoints.
     def initialize(source, filename: nil, config: nil)
       @config = config
       @source = source

data/lib/ruby_llm/batch.rb

@@ -101,7 +101,7 @@ module RubyLLM
         chats = normalize_chats(records)
 
         provider = shared_provider(chats)
-        payload = { provider: provider.slug, provider_class: provider.class.display_name, requests: chats.size }
+        payload = { provider: provider.slug, provider_class: provider.name, requests: chats.size }
         RubyLLM.instrument('batch.ruby_llm', payload, config: provider.config) do |event|
           requests = chats.each_with_index.map do |chat, index|
             { custom_id: index.to_s, model: chat.model.id, payload: chat.render }
@@ -120,7 +120,7 @@ module RubyLLM
         end
 
         provider = shared_provider(requests)
-        payload = { provider: provider.slug, provider_class: provider.class.display_name, requests: requests.size }
+        payload = { provider: provider.slug, provider_class: provider.name, requests: requests.size }
         RubyLLM.instrument('batch.ruby_llm', payload, config: provider.config) do |event|
           lines = requests.each_with_index.map do |request, index|
             { custom_id: index.to_s, model: request.model.id, payload: request.render, text: request.text }

data/lib/ruby_llm/chat.rb

@@ -145,6 +145,10 @@ module RubyLLM
     # treating it as a final answer. Attach files with +with:+.
     # A given block receives streamed Chunk objects as they arrive.
     #
+    # String attachments read local paths or fetch URLs. Only pass trusted,
+    # authorized sources; validate user uploads before calling this method.
+    # See Attachment.new.
+    #
     #   chat.ask "What's the best way to learn Ruby?"
     #   chat.ask "What's in this image?", with: "ruby_conf.jpg"
     #   chat.ask "Analyze these files", with: ["diagram.png", "report.pdf"]
@@ -999,7 +1003,7 @@ module RubyLLM
       {
         chat: self,
         provider: @provider.slug,
-        provider_class: @provider.class.display_name,
+        provider_class: @provider.name,
         model: @model.id,
         model_info: @model,
         input_messages: messages.dup,
@@ -1343,7 +1347,7 @@ module RubyLLM
       payload = {
         chat: self,
         provider: @provider.slug,
-        provider_class: @provider.class.display_name,
+        provider_class: @provider.name,
         model: @model.id,
         model_info: @model,
         tool: tool,

data/lib/ruby_llm/embedding.rb

@@ -117,7 +117,7 @@ module RubyLLM
 
       payload = {
         provider: provider_instance.slug,
-        provider_class: provider_instance.class.display_name,
+        provider_class: provider_instance.name,
         model: model_id,
         model_info: model,
         input: text,

data/lib/ruby_llm/image.rb

@@ -75,7 +75,7 @@ module RubyLLM
       empty_tokens = Tokens.new
       payload = {
         provider: provider_instance.slug,
-        provider_class: provider_instance.class.display_name,
+        provider_class: provider_instance.name,
         model: model.id,
         model_info: model,
         prompt: prompt,

data/lib/ruby_llm/message.rb

@@ -35,6 +35,8 @@ module RubyLLM
     # The ID of the model that produced the message, +nil+ on user messages.
     attr_reader :model
 
+    attr_writer :model_info # :nodoc:
+
     # The tool calls the assistant requested, as a Hash of ToolCall objects
     # keyed by call ID, or +nil+.
     attr_reader :tool_calls
@@ -238,12 +240,19 @@ module RubyLLM
       }.merge(tokens.to_h).compact
     end
 
-    # Returns the Model record for #model from the model registry, or
-    # +nil+ when the message has no model or the model is unknown.
+    # Returns the response's Model from its provider's registry, falling
+    # back to the requested model when the response ID is unknown.
+    # Restored messages use the last successful attempt's provider and model.
+    # Messages without request context look up #model, or return +nil+ if unknown.
     def model_info
-      return unless model
-
-      @model_info ||= RubyLLM.models.find(model)
+      return @model_info if @model_info
+
+      entry = ruby_llm_usage_entries.reverse.find(&:succeeded?)
+      @model_info = if entry&.model
+                      RubyLLM.models.find(entry.model, provider: entry.provider)
+                    elsif model
+                      RubyLLM.models.find(model)
+                    end
     rescue ModelNotFoundError
       nil
     end