lex-llm 0.1.1

data/lib/generators/lex_llm/upgrade_to_v1_7/templates/migration.rb.tt

@@ -0,0 +1,145 @@
+class MigrateToLexLlmModelReferences < ActiveRecord::Migration<%= migration_version %>
+  def up
+    model_class = <%= model_model_name %>
+    chat_class = <%= chat_model_name %>
+    message_class = <%= message_model_name %>
+<% if @model_table_already_existed %>
+    # Load models from models.json if Model table already existed
+    say_with_time "Loading models from models.json" do
+      LexLLM.models.load_from_json!
+      model_class.save_to_database
+      "Loaded #{model_class.count} models"
+    end
+<% end %>
+
+    # Then check for any models in existing data that aren't in models.json
+    say_with_time "Checking for additional models in existing data" do
+      collect_and_create_models(chat_class, :<%= chat_table_name %>, model_class)
+      collect_and_create_models(message_class, :<%= message_table_name %>, model_class)
+      model_class.count
+    end
+
+    # Migrate foreign keys
+    migrate_foreign_key(:<%= chat_table_name %>, chat_class, model_class, :<%= model_table_name.singularize %>)
+    migrate_foreign_key(:<%= message_table_name %>, message_class, model_class, :<%= model_table_name.singularize %>)
+  end
+
+  def down
+    # Remove foreign key references
+    if column_exists?(:<%= message_table_name %>, :<%= model_table_name.singularize %>_id)
+      remove_reference :<%= message_table_name %>, :<%= model_table_name.singularize %>, foreign_key: true
+    end
+
+    if column_exists?(:<%= chat_table_name %>, :<%= model_table_name.singularize %>_id)
+      remove_reference :<%= chat_table_name %>, :<%= model_table_name.singularize %>, foreign_key: true
+    end
+
+    # Restore original model_id string columns
+    if column_exists?(:<%= message_table_name %>, :model_id_string)
+      rename_column :<%= message_table_name %>, :model_id_string, :model_id
+    end
+
+    if column_exists?(:<%= chat_table_name %>, :model_id_string)
+      rename_column :<%= chat_table_name %>, :model_id_string, :model_id
+    end
+  end
+
+  private
+
+  def collect_and_create_models(record_class, table_name, model_class)
+    return unless column_exists?(table_name, :model_id)
+
+    has_provider = column_exists?(table_name, :provider)
+
+    # Collect unique model/provider combinations using read_attribute to bypass overrides
+    models_set = Set.new
+
+    record_class.find_each do |record|
+      model_id = record.read_attribute(:model_id)
+      next if model_id.blank?
+
+      provider = has_provider ? record.read_attribute(:provider) : nil
+      models_set.add([ model_id, provider ])
+    end
+
+    models_set.each do |model_id, provider|
+      find_or_create_model(model_id, provider, model_class)
+    end
+  end
+
+  def find_or_create_model(model_id, provider, model_class)
+    return if model_id.blank?
+
+    begin
+      model_info, _provider = LexLLM.models.resolve(model_id, provider: provider)
+
+      model_class.find_or_create_by!(
+        model_id: model_info.id,
+        provider: model_info.provider
+      ) do |m|
+        m.name = model_info.name || model_info.id
+        m.family = model_info.family
+        m.model_created_at = model_info.created_at
+        m.context_window = model_info.context_window
+        m.max_output_tokens = model_info.max_output_tokens
+        m.knowledge_cutoff = model_info.knowledge_cutoff
+        m.modalities = model_info.modalities.to_h
+        m.capabilities = model_info.capabilities
+        m.pricing = model_info.pricing.to_h
+        m.metadata = model_info.metadata
+      end
+    rescue => e
+      # Skip models that can't be resolved - they'll need manual fixing
+      Rails.logger.warn "Skipping unresolvable model: #{model_id} - will need manual update"
+      nil
+    end
+  end
+
+
+  def migrate_foreign_key(table_name, record_class, model_class, foreign_key_name)
+    return unless column_exists?(table_name, :model_id)
+
+    # Check if we need to rename the string column to avoid collision
+    if column_exists?(table_name, :model_id) && !foreign_key_exists?(table_name, :models)
+      # Temporarily rename the string column
+      rename_column table_name, :model_id, :model_id_string
+    end
+
+    # Add the foreign key reference
+    unless column_exists?(table_name, "#{foreign_key_name}_id")
+      add_reference table_name, foreign_key_name, foreign_key: true
+    end
+
+    say_with_time "Migrating #{table_name} model references" do
+      record_class.reset_column_information
+      has_provider = column_exists?(table_name, :provider)
+
+      # Determine which column to read from (renamed or original)
+      model_id_column = column_exists?(table_name, :model_id_string) ? :model_id_string : :model_id
+
+      record_class.find_each do |record|
+        model_id = record.read_attribute(model_id_column)
+        next if model_id.blank?
+
+        provider = has_provider ? record.read_attribute(:provider) : nil
+
+        model = if has_provider && provider.present?
+          model_class.find_by(model_id: model_id, provider: provider)
+        else
+          find_model_for_record(model_id, model_class)
+        end
+
+        record.update_column("#{foreign_key_name}_id", model.id) if model
+      end
+    end
+  end
+
+  def find_model_for_record(model_id, model_class)
+    begin
+      model_info, _provider = LexLLM.models.resolve(model_id)
+      model_class.find_by(model_id: model_info.id, provider: model_info.provider)
+    rescue => e
+      model_class.find_by(model_id: model_id)
+    end
+  end
+end

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

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+require 'rails/generators/active_record'
+require_relative '../generator_helpers'
+
+module LexLLM
+  module Generators
+    # Generator to upgrade existing LexLLM apps to v1.7 with new Rails-like API
+    class UpgradeToV17Generator < Rails::Generators::Base
+      include Rails::Generators::Migration
+      include LexLLM::Generators::GeneratorHelpers
+
+      namespace 'lex_llm:upgrade_to_v1_7'
+      source_root File.expand_path('templates', __dir__)
+
+      # Override source_paths to include install templates
+      def self.source_paths
+        [
+          File.expand_path('templates', __dir__),
+          File.expand_path('../install/templates', __dir__)
+        ]
+      end
+
+      argument :model_mappings, type: :array, default: [], banner: 'chat:ChatName message:MessageName ...'
+
+      desc 'Upgrades existing LexLLM apps to v1.7 with new Rails-like API\n' \
+           'Usage: bin/rails g lex_llm:upgrade_to_v1_7 [chat:ChatName] [message:MessageName] ...'
+
+      def self.next_migration_number(dirname)
+        ::ActiveRecord::Generators::Base.next_migration_number(dirname)
+      end
+
+      def create_migration_file
+        @model_table_already_existed = table_exists?(table_name_for(model_model_name))
+
+        # First check if models table exists, if not create it
+        unless @model_table_already_existed
+          migration_template 'create_models_migration.rb.tt',
+                             "db/migrate/create_#{table_name_for(model_model_name)}.rb",
+                             migration_version: migration_version,
+                             model_model_name: model_model_name
+        end
+
+        migration_template 'migration.rb.tt',
+                           'db/migrate/migrate_to_lex_llm_model_references.rb',
+                           migration_version: migration_version,
+                           chat_model_name: chat_model_name,
+                           message_model_name: message_model_name,
+                           tool_call_model_name: tool_call_model_name,
+                           model_model_name: model_model_name,
+                           model_table_already_existed: @model_table_already_existed
+      end
+
+      def create_model_file
+        create_namespace_modules
+
+        template 'model_model.rb.tt', "app/models/#{model_model_name.underscore}.rb"
+      end
+
+      def update_existing_models
+        update_model_acts_as(chat_model_name, 'acts_as_chat', acts_as_chat_declaration)
+        update_model_acts_as(message_model_name, 'acts_as_message', acts_as_message_declaration)
+        update_model_acts_as(tool_call_model_name, 'acts_as_tool_call', acts_as_tool_call_declaration)
+      end
+
+      def update_initializer
+        initializer_path = 'config/initializers/lex_llm.rb'
+
+        unless File.exist?(initializer_path)
+          say_status :warning, 'No initializer found. Creating one...', :yellow
+          template 'initializer.rb.tt', initializer_path
+          return
+        end
+
+        initializer_content = File.read(initializer_path)
+
+        return if initializer_content.include?('config.use_new_acts_as')
+
+        inject_into_file initializer_path, after: /^LexLLM\.configure do \|config\|\n/ do
+          lines = ['  # Enable the new Rails-like API', '  config.use_new_acts_as = true']
+          lines << "  config.model_registry_class = \"#{model_model_name}\"" if model_model_name != 'Model'
+          lines << ''
+          lines.join("\n")
+        end
+      end
+
+      def show_next_steps
+        say_status :success, 'Upgrade prepared!', :green
+        say <<~INSTRUCTIONS
+
+          Next steps:
+          1. Review the generated migrations
+          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 LexLLM.chat
+
+          ⚠️  If you get "undefined method 'acts_as_model'" during migration:
+            Add this to config/application.rb BEFORE your Application class:
+
+            LexLLM.configure do |config|
+              config.use_new_acts_as = true
+            end
+
+          📚 See the full migration guide: https://github.com/LegionIO/lex-llm
+
+        INSTRUCTIONS
+      end
+
+      private
+
+      def update_model_acts_as(model_name, old_acts_as, new_acts_as)
+        model_path = "app/models/#{model_name.underscore}.rb"
+        return unless File.exist?(Rails.root.join(model_path))
+
+        content = File.read(Rails.root.join(model_path))
+        return unless content.match?(/^\s*#{old_acts_as}/)
+
+        gsub_file model_path, /^\s*#{old_acts_as}.*$/, "  #{new_acts_as}"
+      end
+    end
+  end
+end

data/lib/generators/lex_llm/upgrade_to_v1_9/templates/add_v1_9_message_columns.rb.tt

@@ -0,0 +1,15 @@
+class AddLexLlmV19Columns < ActiveRecord::Migration<%= migration_version %>
+  def change
+    unless column_exists?(:<%= message_table_name %>, :cached_tokens)
+      add_column :<%= message_table_name %>, :cached_tokens, :integer
+    end
+
+    unless column_exists?(:<%= message_table_name %>, :cache_creation_tokens)
+      add_column :<%= message_table_name %>, :cache_creation_tokens, :integer
+    end
+
+    unless column_exists?(:<%= message_table_name %>, :content_raw)
+      add_column :<%= message_table_name %>, :content_raw, :json
+    end
+  end
+end

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+require 'rails/generators/active_record'
+require_relative '../generator_helpers'
+
+module LexLLM
+  module Generators
+    # Generator to add v1.9 columns (cached tokens + raw content support) to existing apps.
+    class UpgradeToV19Generator < Rails::Generators::Base
+      include Rails::Generators::Migration
+      include LexLLM::Generators::GeneratorHelpers
+
+      namespace 'lex_llm:upgrade_to_v1_9'
+      source_root File.expand_path('templates', __dir__)
+
+      argument :model_mappings, type: :array, default: [], banner: 'message:MessageName'
+
+      desc 'Adds cached token columns and raw content storage fields introduced in v1.9.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_9_message_columns.rb.tt',
+                           'db/migrate/add_lex_llm_v1_9_columns.rb',
+                           migration_version: migration_version,
+                           message_table_name: message_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.9.0 release notes for details on cached token tracking and raw content support.
+
+        INSTRUCTIONS
+      end
+    end
+  end
+end

data/lib/legion/extensions/llm/provider_settings.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Llm
+      # Builds shared provider defaults for lex-llm-* extension gems.
+      module ProviderSettings
+        module_function
+
+        def build(family:, instance: {}, enabled: true, discovery: {}, instances: {})
+          deep_merge(
+            Legion::Extensions::Llm.default_settings,
+            {
+              enabled: enabled,
+              provider_family: family,
+              discovery: deep_merge({ enabled: true, interval_seconds: 300 }, discovery || {}),
+              instances: deep_merge(
+                {
+                  default: deep_merge(
+                    { enabled: true, credentials: nil, fleet: { enabled: false, consumer_priority: 0, prefetch: 1 } },
+                    instance || {}
+                  )
+                },
+                instances || {}
+              )
+            }
+          )
+        end
+
+        def deep_dup(value)
+          case value
+          when Hash
+            value.to_h { |key, inner_value| [key, deep_dup(inner_value)] }
+          when Array
+            value.map { |inner_value| deep_dup(inner_value) }
+          else
+            value
+          end
+        end
+
+        def deep_merge(left, right)
+          deep_dup(left || {}).merge(deep_dup(right || {})) do |_key, left_value, right_value|
+            left_value.is_a?(Hash) && right_value.is_a?(Hash) ? deep_merge(left_value, right_value) : right_value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/llm/transport/fleet_lane.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Llm
+      module Transport
+        # Shared RabbitMQ live-work lane defaults for provider fleet workers.
+        module FleetLane
+          DEFAULTS = {
+            queue_expires_ms: 60_000,
+            message_ttl_ms: 120_000,
+            queue_max_length: 100,
+            delivery_limit: 3,
+            consumer_ack_timeout_ms: 300_000
+          }.freeze
+
+          module_function
+
+          def queue_options(settings = {})
+            config = DEFAULTS.merge((settings || {}).compact.transform_keys(&:to_sym))
+            {
+              durable: true,
+              auto_delete: false,
+              arguments: queue_arguments(config)
+            }
+          end
+
+          def queue_arguments(config)
+            {
+              'x-queue-type' => 'quorum',
+              'x-queue-leader-locator' => 'balanced',
+              'x-expires' => config.fetch(:queue_expires_ms),
+              'x-message-ttl' => config.fetch(:message_ttl_ms),
+              'x-overflow' => 'reject-publish',
+              'x-max-length' => config.fetch(:queue_max_length),
+              'x-delivery-limit' => config.fetch(:delivery_limit),
+              'x-consumer-timeout' => config.fetch(:consumer_ack_timeout_ms)
+            }
+          end
+
+          def build_queue_class(queue_name:, exchange_class:, routing_key: queue_name, base_queue_class: nil,
+                                settings: {})
+            parent = base_queue_class || legion_queue_class
+            unless parent
+              raise ArgumentError,
+                    'base_queue_class is required when Legion::Transport::Queue is not loaded'
+            end
+
+            options = queue_options(settings)
+            Class.new(parent) do
+              define_method(:queue_name) { queue_name }
+              define_method(:queue_options) { options }
+              define_method(:dlx_enabled) { false }
+              define_method(:initialize) do
+                super()
+                bind(exchange_class.new, routing_key: routing_key)
+              end
+            end
+          end
+
+          def legion_queue_class
+            return nil unless defined?(::Legion::Transport::Queue)
+
+            ::Legion::Transport::Queue
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/llm.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require 'lex_llm'
+require 'legion/extensions/llm/provider_settings'
+require 'legion/extensions/llm/transport/fleet_lane'
+
+module Legion
+  module Extensions
+    # Legion-native namespace for the shared LLM provider framework.
+    module Llm
+      VERSION = LexLLM::VERSION unless const_defined?(:VERSION, false)
+
+      # Provider-neutral value objects exposed under the Legion extension namespace.
+      module Types
+        ModelOffering = LexLLM::Routing::ModelOffering unless const_defined?(:ModelOffering, false)
+      end
+
+      # Shared routing helpers exposed under the Legion extension namespace.
+      module Routing
+        LaneKey = LexLLM::Routing::LaneKey unless const_defined?(:LaneKey, false)
+      end
+
+      def self.default_settings
+        {
+          fleet: {
+            enabled: false,
+            scheduler: :basic_get,
+            consumer_priority: 0,
+            queue_expires_ms: 60_000,
+            message_ttl_ms: 120_000,
+            queue_max_length: 100,
+            delivery_limit: 3,
+            consumer_ack_timeout_ms: 300_000,
+            endpoint: {
+              enabled: false,
+              empty_lane_backoff_ms: 250,
+              idle_backoff_ms: 1_000,
+              max_consecutive_pulls_per_lane: 0,
+              accept_when: []
+            }
+          }
+        }
+      end
+
+      def self.provider_settings(...)
+        ProviderSettings.build(...)
+      end
+    end
+  end
+end

data/lib/lex_llm/active_record/acts_as.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+module LexLLM
+  module ActiveRecord
+    # Adds chat and message persistence capabilities to ActiveRecord models.
+    module ActsAs
+      extend ActiveSupport::Concern
+
+      # When ActsAs is included, ensure models are loaded from database
+      def self.included(base)
+        super
+        # Monkey-patch Models to use database when ActsAs is active
+        LexLLM::Models.class_eval do
+          def self.load_models
+            database_models = read_from_database
+            return database_models if database_models.any?
+
+            LexLLM.logger.debug { 'Model registry is empty in database, falling back to JSON registry' }
+            read_from_json
+          rescue StandardError => e
+            LexLLM.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 = LexLLM.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
+
+          def load_from_database!
+            @models = self.class.read_from_database
+          end
+        end
+      end
+
+      class_methods do # rubocop:disable Metrics/BlockLength
+        def acts_as_chat(messages: :messages, message_class: nil, messages_foreign_key: nil, # rubocop:disable Metrics/ParameterLists
+                         model: :model, model_class: nil, model_foreign_key: nil)
+          include LexLLM::ActiveRecord::ChatMethods
+
+          class_attribute :messages_association_name, :model_association_name, :message_class, :model_class
+
+          self.messages_association_name = messages
+          self.model_association_name = model
+          self.message_class = (message_class || messages.to_s.classify).to_s
+          self.model_class = (model_class || model.to_s.classify).to_s
+
+          has_many messages,
+                   -> { order(created_at: :asc) },
+                   class_name: self.message_class,
+                   foreign_key: messages_foreign_key,
+                   dependent: :destroy
+
+          belongs_to model,
+                     class_name: self.model_class,
+                     foreign_key: model_foreign_key,
+                     optional: true
+
+          define_method :messages_association do
+            send(messages_association_name)
+          end
+
+          define_method :model_association do
+            send(model_association_name)
+          end
+
+          define_method :'model_association=' do |value|
+            send("#{model_association_name}=", value)
+          end
+        end
+
+        def acts_as_model(chats: :chats, chat_class: nil, chats_foreign_key: nil)
+          include LexLLM::ActiveRecord::ModelMethods
+
+          class_attribute :chats_association_name, :chat_class
+
+          self.chats_association_name = chats
+          self.chat_class = (chat_class || chats.to_s.classify).to_s
+
+          validates :model_id, presence: true, uniqueness: { scope: :provider }
+          validates :provider, presence: true
+          validates :name, presence: true
+
+          has_many chats, class_name: self.chat_class, foreign_key: chats_foreign_key
+
+          define_method :chats_association do
+            send(chats_association_name)
+          end
+        end
+
+        def acts_as_message(chat: :chat, chat_class: nil, chat_foreign_key: nil, touch_chat: false, # rubocop:disable Metrics/ParameterLists
+                            tool_calls: :tool_calls, tool_call_class: nil, tool_calls_foreign_key: nil,
+                            model: :model, model_class: nil, model_foreign_key: nil)
+          include LexLLM::ActiveRecord::MessageMethods
+
+          class_attribute :chat_association_name, :tool_calls_association_name, :model_association_name,
+                          :chat_class, :tool_call_class, :model_class
+
+          self.chat_association_name = chat
+          self.tool_calls_association_name = tool_calls
+          self.model_association_name = model
+          self.chat_class = (chat_class || chat.to_s.classify).to_s
+          self.tool_call_class = (tool_call_class || tool_calls.to_s.classify).to_s
+          self.model_class = (model_class || model.to_s.classify).to_s
+
+          belongs_to chat,
+                     class_name: self.chat_class,
+                     foreign_key: chat_foreign_key,
+                     touch: touch_chat
+
+          has_many tool_calls,
+                   class_name: self.tool_call_class,
+                   foreign_key: tool_calls_foreign_key,
+                   dependent: :destroy
+
+          belongs_to :parent_tool_call,
+                     class_name: self.tool_call_class,
+                     foreign_key: ActiveSupport::Inflector.foreign_key(tool_calls.to_s.singularize),
+                     optional: true
+
+          has_many :tool_results,
+                   through: tool_calls,
+                   source: :result,
+                   class_name: name
+
+          belongs_to model,
+                     class_name: self.model_class,
+                     foreign_key: model_foreign_key,
+                     optional: true
+
+          delegate :tool_call?, :tool_result?, to: :to_llm
+
+          define_method :chat_association do
+            send(chat_association_name)
+          end
+
+          define_method :tool_calls_association do
+            send(tool_calls_association_name)
+          end
+
+          define_method :model_association do
+            send(model_association_name)
+          end
+        end
+
+        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 LexLLM::ActiveRecord::ToolCallMethods
+
+          class_attribute :message_association_name, :result_association_name, :message_class, :result_class
+
+          self.message_association_name = message
+          self.result_association_name = result
+          self.message_class = (message_class || message.to_s.classify).to_s
+          self.result_class = (result_class || self.message_class).to_s
+
+          belongs_to message,
+                     class_name: self.message_class,
+                     foreign_key: message_foreign_key
+
+          has_one result,
+                  class_name: self.result_class,
+                  foreign_key: result_foreign_key,
+                  dependent: :nullify
+
+          define_method :message_association do
+            send(message_association_name)
+          end
+
+          define_method :result_association do
+            send(result_association_name)
+          end
+        end
+      end
+    end
+  end
+end