ruby_llm 1.16.0 → 2.0.0.rc4

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

@@ -0,0 +1,251 @@
+# frozen_string_literal: true
+
+module RubyLLMUpgrade # :nodoc: all
+  TABLE = 'ruby_llm_v2_upgrades'
+  VERSION_COLUMN = 'ruby_llm_version'
+  OPERATIONS = %i[ask say ask_later add_message generate compact step complete run_tools cancel resume
+                  approve deny with_model with_instructions cache_until_here reset_messages!].freeze
+  READ_OPERATIONS = %i[reload to_llm count_tokens].freeze
+
+  module Records
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :ruby_llm_upgrade_kind, instance_writer: false
+      self.enumerate_columns_in_select_statements = true
+      default_scope { RubyLLMUpgrade.visible(self) }
+      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
+
+    private
+
+    def guard_ruby_llm_upgrade(&)
+      RubyLLMUpgrade.guard(self, &)
+    end
+  end
+
+  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
+
+        model.include Records
+        model.ruby_llm_upgrade_kind = kind
+        model.prepend guarded_operations(model, READ_OPERATIONS, claim: false)
+      end
+      return if chat.instance_variable_defined?(:@ruby_llm_upgrade_operations)
+
+      operations = guarded_operations(chat, OPERATIONS, claim: true)
+      %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, name)
+      end
+      chat.prepend operations
+      chat.instance_variable_set(:@ruby_llm_upgrade_operations, operations)
+    end
+
+    def visible(model)
+      return model.where(nil) unless available?
+
+      state = current_state
+      check_version(state)
+      return model.where(nil) if version == 2
+
+      settings = state.settings
+      return model.where(nil) unless ownership_column?(settings)
+
+      chats = records(settings.fetch('chat_table')).where(VERSION_COLUMN => 1)
+      case model.ruby_llm_upgrade_kind
+      when :chat
+        model.where(VERSION_COLUMN => 1)
+      when :message
+        model.where(settings.fetch('chat_foreign_key') => chats.select(chats.primary_key))
+      when :tool_call
+        messages = records(settings.fetch('message_table'))
+                   .where(settings.fetch('chat_foreign_key') => chats.select(chats.primary_key))
+        model.where(settings.fetch('message_foreign_key') => messages.select(messages.primary_key))
+      end
+    end
+
+    def prepare_model(chat)
+      return unless available?
+
+      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')
+      end
+      ensure_model_reference(chat, settings)
+    end
+
+    def guard(record, claim: true)
+      return yield unless available?
+
+      states = records(TABLE)
+      states.uncached do
+        states.transaction do
+          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|
+          next unless model.method_defined?(name)
+
+          define_method(name) do |*args, **options, &block|
+            RubyLLMUpgrade.guard(self, claim: claim) { nil }
+            super(*args, **options, &block)
+          end
+        end
+      end
+    end
+
+    def protect(record, state, claim:)
+      return if state.status == 'finalized'
+
+      settings = state.settings
+      return if version == 1 && !ownership_column?(settings)
+
+      owners(record, settings).each { |chat| protect_owner(chat, claim: claim) }
+      return unless claim && version == 2 && record.class.ruby_llm_upgrade_kind == :chat
+
+      record[VERSION_COLUMN] = 2
+    end
+
+    def protect_owner(chat, claim:)
+      chat.lock!
+      if version == 1 && chat[VERSION_COLUMN] != 1
+        raise ActiveRecord::ReadOnlyRecord, 'This conversation contains RubyLLM 2.0 changes'
+      end
+
+      chat.update!(VERSION_COLUMN => 2) if claim && version == 2 && chat[VERSION_COLUMN] != 2
+    end
+
+    def version
+      Gem::Version.new(RubyLLM::VERSION).segments.first >= 2 ? 2 : 1
+    end
+
+    def available?
+      ActiveRecord::Base.connection.table_exists?(TABLE)
+    end
+
+    def records(table)
+      @records ||= {}
+      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
+      records(TABLE).uncached { records(TABLE).first! }
+    end
+
+    def ownership_column?(settings)
+      ActiveRecord::Base.connection.column_exists?(settings.fetch('chat_table'), VERSION_COLUMN)
+    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,
+            "RubyLLM #{version} cannot access conversations while the copy upgrade is " \
+            "#{state.status} on #{state.active_version}"
+    end
+
+    def ensure_model_reference(chat, settings)
+      if version == 1
+        legacy_id = chat[settings.fetch('model_foreign_key')]
+        legacy_models = records(settings.fetch('model_table'))
+        legacy = legacy_models.find_by(legacy_models.primary_key => legacy_id)
+        unless legacy
+          chat.errors.add(:model, 'must identify an existing legacy model')
+          raise ActiveRecord::RecordInvalid, chat
+        end
+
+        target = records('ruby_llm_models')
+        model = target.find_by(provider: legacy.provider, model_id: legacy.model_id) ||
+                target.create!(legacy.attributes.slice(*target.column_names).except(target.primary_key))
+        chat[:ruby_llm_model_id] = model.id
+      end
+      return if chat[:ruby_llm_model_id]
+
+      chat.errors.add(:model, 'must exist before saving the conversation')
+      raise ActiveRecord::RecordInvalid, chat
+    end
+
+    def owners(record, settings)
+      chats = records(settings.fetch('chat_table'))
+      return chat_owner(record, chats) if record.class.ruby_llm_upgrade_kind == :chat
+
+      values = owner_attributes(record, settings)
+      ids = values.filter_map { |value| value[settings.fetch('chat_foreign_key')] }
+      raise ActiveRecord::ReadOnlyRecord, 'The conversation no longer exists' if ids.empty?
+
+      found = chats.where(chats.primary_key => ids).to_a
+      raise ActiveRecord::ReadOnlyRecord, 'The conversation no longer exists' unless found.length == ids.uniq.length
+
+      found
+    end
+
+    def chat_owner(record, chats)
+      found = chats.where(chats.primary_key => record.id).to_a
+      return found unless record.persisted? && found.empty?
+
+      raise ActiveRecord::ReadOnlyRecord, 'The conversation no longer exists'
+    end
+
+    def owner_attributes(record, settings)
+      values = [record.attributes]
+      if record.persisted?
+        stored = records(record.class.table_name).find(record.id)
+        values << stored.attributes
+      end
+      if record.class.ruby_llm_upgrade_kind == :tool_call
+        message_key = version == 1 ? settings.fetch('message_foreign_key') : 'message_id'
+        messages = records(settings.fetch('message_table'))
+        values = messages.where(messages.primary_key => values.map { |value| value[message_key] }).map(&:attributes)
+      end
+      values
+    end
+  end
+end

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

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+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
+                <%= v1_model_name(:tool_call) %>
+              end
+  RubyLLMUpgrade.install(chat: <%= chat_model_name %>, message: <%= message_model_name %>, tool_call: tool_call)
+end

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

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+require 'rails/generators/active_record'
+require_relative '../generator_helpers'
+
+module RubyLLM
+  module Generators
+    # Upgrades the schema generated by RubyLLM 1.16 to RubyLLM 2.0.
+    class UpgradeGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+      include RubyLLM::Generators::GeneratorHelpers
+
+      MODEL_MAPPING_DEFAULTS = {
+        chat: 'Chat',
+        message: 'Message',
+        model: 'Model',
+        tool_call: 'ToolCall'
+      }.freeze
+      MODEL_MAPPING_TYPES = MODEL_MAPPING_DEFAULTS.keys.map(&:to_s).freeze
+
+      namespace 'ruby_llm:upgrade'
+      source_root File.expand_path('templates', __dir__)
+
+      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 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,
+               default: [],
+               banner: 'chat:ChatName message:MessageName model:ModelName tool_call:ToolCallName'
+
+      desc 'Upgrades a RubyLLM 1.16 Rails schema to 2.0'
+
+      def self.next_migration_number(dirname)
+        ::ActiveRecord::Generators::Base.next_migration_number(dirname)
+      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
+
+        if copy_mode? && !options[:phase].in?(%w[backfill finish cleanup])
+          template 'ruby_llm_upgrade.rb.tt', 'app/models/concerns/ruby_llm_upgrade.rb'
+          template 'upgrade_initializer.rb.tt', 'config/initializers/ruby_llm_upgrade.rb'
+        end
+
+        phases = options[:phase] ? [options[:phase]] : %w[prepare backfill finish]
+        phases.each do |phase|
+          template = phase == 'backfill' ? 'backfill_v2_data' : "#{phase}_v2_upgrade"
+          migration = phase == 'backfill' ? 'backfill_ruby_llm_v2_data' : "#{phase}_ruby_llm_v2_upgrade"
+          migration_template "#{template}.rb.tt", "db/migrate/#{migration}.rb"
+        end
+      end
+
+      def show_next_steps
+        say_status :success, 'Upgrade prepared!', :green
+        if copy_mode?
+          say <<~INSTRUCTIONS
+
+            Copy mode retains the legacy tables and a separate chat model reference.
+            Install the generated RubyLLMUpgrade concern and initializer in BOTH the
+            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.
+
+            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
+
+            Finish pending tool calls, approvals and batches before switching.
+            Once rollback is no longer needed, run ruby_llm:upgrade:finalize, then
+            generate --mode copy --phase cleanup in a later deployment. Keep the
+            compatibility files until cleanup succeeds; remove them afterward.
+
+            Pass the same --mode and model mappings to every generator invocation.
+            Full guide: https://rubyllm.com/next/upgrading/
+
+          INSTRUCTIONS
+          return
+        end
+        say <<~INSTRUCTIONS
+
+          These migrations expect the schema generated by RubyLLM 1.16. They move
+          RubyLLM's model and tool-call records, preserve message content and usage,
+          and retain the 1.x message columns until a later cleanup deployment.
+
+          Next steps:
+          1. Review the generated migrations
+          2. Rehearse them on a recent production snapshot
+          3. Stop affected web processes, workers, scheduled jobs, and retries
+          4. Run preparation, backfill, and finish before reopening traffic
+          5. Run: bin/rails ruby_llm:load_models
+          6. Keep only the current declarations in your application models:
+             #{chat_model_path}: #{acts_as_chat_declaration}
+             #{message_model_path}: #{acts_as_message_declaration}
+          7. Remove the 1.x model and tool-call classes, config.model_registry_class,
+             and config.use_new_acts_as
+          8. Update 1.x API calls using the upgrade guide
+
+          Generate one phase with --phase prepare, backfill, or finish when the
+          backfill needs to run outside your deployment's release phase.
+          After verifying the upgrade, generate --phase cleanup in a later release.
+          Pass the same model mappings to every invocation.
+
+          The migrations are irreversible. Retained columns do not make a code
+          rollback safe; recovery requires the previous database and application.
+
+          Full upgrade guide:
+             https://rubyllm.com/next/upgrading/
+
+        INSTRUCTIONS
+      end
+
+      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
+        {
+          chat_table: chat_table_name, message_table: message_table_name,
+          model_table: v1_model_table_name, tool_call_table: v1_tool_call_table_name,
+          chat_class: chat_model_name, message_class: message_model_name,
+          model_foreign_key: v1_model_foreign_key, tool_call_foreign_key: v1_tool_call_foreign_key,
+          chat_foreign_key: chat_foreign_key, message_foreign_key: message_foreign_key
+        }
+      end
+
+      def prepare_migration_class_name = 'prepare_ruby_llm_v2_upgrade'.camelize
+      def backfill_migration_class_name = 'backfill_ruby_llm_v2_data'.camelize
+      def finish_migration_class_name = 'finish_ruby_llm_v2_upgrade'.camelize
+      def cleanup_migration_class_name = 'cleanup_ruby_llm_v2_upgrade'.camelize
+
+      def resolved_model_mappings
+        @model_names.map do |type, model_name|
+          "#{type}:#{model_name} -> #{table_name_for(model_name)}"
+        end.join(', ')
+      end
+
+      def v1_model_name(type)
+        @model_names.fetch(type)
+      end
+
+      def v1_model_table_name = table_name_for(v1_model_name(:model))
+      def v1_tool_call_table_name = table_name_for(v1_model_name(:tool_call))
+      def v1_model_foreign_key = "#{v1_model_table_name.singularize}_id"
+      def v1_tool_call_foreign_key = "#{v1_tool_call_table_name.singularize}_id"
+      def message_foreign_key = "#{message_table_name.singularize}_id"
+      def chat_foreign_key = "#{chat_table_name.singularize}_id"
+
+      def chat_model_path
+        "app/models/#{chat_model_name.underscore}.rb"
+      end
+
+      def message_model_path
+        "app/models/#{message_model_name.underscore}.rb"
+      end
+    end
+  end
+end