lex-llm 0.1.1

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

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+require 'rails/generators/active_record'
+require_relative '../generator_helpers'
+
+module LexLLM
+  module Generators
+    # Generator for LexLLM Rails models and migrations
+    class InstallGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+      include LexLLM::Generators::GeneratorHelpers
+
+      namespace 'lex_llm:install'
+
+      source_root File.expand_path('templates', __dir__)
+
+      argument :model_mappings, type: :array, default: [], banner: 'chat:ChatName message:MessageName ...'
+
+      class_option :skip_active_storage, type: :boolean, default: false,
+                                         desc: 'Skip ActiveStorage installation and attachment setup'
+
+      desc 'Creates models and migrations for LexLLM Rails integration\n' \
+           'Usage: bin/rails g lex_llm:install [chat:ChatName] [message:MessageName] ...'
+
+      def self.next_migration_number(dirname)
+        ::ActiveRecord::Generators::Base.next_migration_number(dirname)
+      end
+
+      def create_migration_files
+        migration_template 'create_chats_migration.rb.tt',
+                           "db/migrate/create_#{chat_table_name}.rb"
+        migration_template 'create_messages_migration.rb.tt',
+                           "db/migrate/create_#{message_table_name}.rb"
+        migration_template 'create_tool_calls_migration.rb.tt',
+                           "db/migrate/create_#{tool_call_table_name}.rb"
+        migration_template 'create_models_migration.rb.tt',
+                           "db/migrate/create_#{model_table_name}.rb"
+        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"
+      end
+
+      def create_model_files
+        create_namespace_modules
+
+        template 'chat_model.rb.tt', "app/models/#{chat_model_name.underscore}.rb"
+        template 'message_model.rb.tt', "app/models/#{message_model_name.underscore}.rb"
+        template 'tool_call_model.rb.tt', "app/models/#{tool_call_model_name.underscore}.rb"
+
+        template 'model_model.rb.tt', "app/models/#{model_model_name.underscore}.rb"
+      end
+
+      def create_initializer
+        template 'initializer.rb.tt', 'config/initializers/lex_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]
+
+        say '  Installing ActiveStorage for file attachments...', :cyan
+        rails_command 'active_storage:install'
+      end
+
+      def show_install_info
+        say "\n  ✅ LexLLM installed!", :green
+
+        say '  ✅ ActiveStorage configured for file attachments support', :green unless options[:skip_active_storage]
+
+        say "\n  Next steps:", :yellow
+        say '     1. Run: bin/rails db:migrate'
+        say '     2. Run: bin/rails lex_llm:load_models'
+        say '     3. Install a lex-llm-* provider gem and configure its settings'
+
+        say "     4. Start chatting: #{chat_model_name}.create!(model: 'your-provider-model').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: bin/rails active_storage:install && bin/rails db:migrate'
+          say "       2. Add to your #{message_model_name} model: has_many_attached :attachments"
+        end
+
+        say "\n  📚 Documentation: https://github.com/LegionIO/lex-llm", :cyan
+
+        say "\n  ❤️  Love LexLLM?", :magenta
+        say '     • ⭐ Star on GitHub: https://github.com/LegionIO/lex-llm'
+        say "\n"
+      end
+
+      private
+
+      def chat_ui_generator_command
+        mappings = model_mappings.join(' ')
+        mappings = " #{mappings}" unless mappings.empty?
+        "bin/rails generate lex_llm:chat_ui#{mappings}"
+      end
+    end
+  end
+end

data/lib/generators/lex_llm/install/templates/add_references_to_chats_tool_calls_and_messages_migration.rb.tt

@@ -0,0 +1,9 @@
+class AddReferencesTo<%= "#{chat_model_name.gsub('::', '').pluralize}#{tool_call_model_name.gsub('::', '').pluralize}And#{message_model_name.gsub('::', '').pluralize}" %> < ActiveRecord::Migration<%= migration_version %>
+  def change
+    add_reference :<%= chat_table_name %>, :<%= model_table_name.singularize %>, foreign_key: true
+    add_reference :<%= tool_call_table_name %>, :<%= message_table_name.singularize %>, null: false, foreign_key: true
+    add_reference :<%= message_table_name %>, :<%= chat_table_name.singularize %>, null: false, foreign_key: true
+    add_reference :<%= message_table_name %>, :<%= model_table_name.singularize %>, foreign_key: true
+    add_reference :<%= message_table_name %>, :<%= tool_call_table_name.singularize %>, foreign_key: true
+  end
+end

data/lib/generators/lex_llm/install/templates/chat_model.rb.tt

@@ -0,0 +1,3 @@
+class <%= chat_model_name %> < ApplicationRecord
+  <%= acts_as_chat_declaration %>
+end

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

@@ -0,0 +1,7 @@
+class <%= create_migration_class_name(chat_table_name) %> < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :<%= chat_table_name %> do |t|
+      t.timestamps
+    end
+  end
+end

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

@@ -0,0 +1,19 @@
+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
+      t.text :content
+      t.json :content_raw
+      t.text :thinking_text
+      t.text :thinking_signature
+      t.integer :thinking_tokens
+      t.integer :input_tokens
+      t.integer :output_tokens
+      t.integer :cached_tokens
+      t.integer :cache_creation_tokens
+      t.timestamps
+    end
+
+    add_index :<%= message_table_name %>, :role
+  end
+end

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

@@ -0,0 +1,39 @@
+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
+      t.string :name, null: false
+      t.string :provider, null: false
+      t.string :family
+      t.datetime :model_created_at
+      t.integer :context_window
+      t.integer :max_output_tokens
+      t.date :knowledge_cutoff
+<% if postgresql? %>
+      t.jsonb :modalities, default: {}
+      t.jsonb :capabilities, default: []
+      t.jsonb :pricing, default: {}
+      t.jsonb :metadata, default: {}
+<% elsif mysql? %>
+      t.json :modalities
+      t.json :capabilities
+      t.json :pricing
+      t.json :metadata
+<% else %>
+      t.json :modalities, default: {}
+      t.json :capabilities, default: []
+      t.json :pricing, default: {}
+      t.json :metadata, default: {}
+<% end %>
+      t.timestamps
+
+      t.index [ :provider, :model_id ], unique: true
+      t.index :provider
+      t.index :family
+<% if postgresql? -%>
+      t.index :capabilities, using: :gin
+      t.index :modalities, using: :gin
+<% end -%>
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+<%#- # Migration for creating tool_calls table with database-specific JSON handling -%>
+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.text :thought_signature
+<% if postgresql? %>
+      t.jsonb :arguments, default: {}
+<% elsif mysql? %>
+      t.json :arguments
+<% else %>
+      t.json :arguments, default: {}
+<% end %>
+      t.timestamps
+    end
+
+    add_index :<%= tool_call_table_name %>, :tool_call_id, unique: true
+    add_index :<%= tool_call_table_name %>, :name
+  end
+end

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

@@ -0,0 +1,20 @@
+require "lex_llm"
+require "lex_llm/active_record/acts_as"
+
+LexLLM.configure do |config|
+  # Provider gems register their own settings.
+  # Example after installing a provider extension:
+  # config.default_model = "your-provider-model"
+
+  # Use the new association-based acts_as API (recommended)
+  config.use_new_acts_as = true
+<% if model_model_name != 'Model' -%>
+
+  # Custom model registry class name
+  config.model_registry_class = "<%= model_model_name %>"
+<% end -%>
+end
+
+ActiveSupport.on_load :active_record do
+  ::ActiveRecord::Base.include LexLLM::ActiveRecord::ActsAs
+end

data/lib/generators/lex_llm/install/templates/message_model.rb.tt

@@ -0,0 +1,4 @@
+class <%= message_model_name %> < ApplicationRecord
+  <%= acts_as_message_declaration %><% unless options[:skip_active_storage] %>
+  has_many_attached :attachments<% end %>
+end

data/lib/generators/lex_llm/install/templates/model_model.rb.tt

@@ -0,0 +1,3 @@
+class <%= model_model_name %> < ApplicationRecord
+  <%= acts_as_model_declaration %>
+end

data/lib/generators/lex_llm/install/templates/tool_call_model.rb.tt

@@ -0,0 +1,3 @@
+class <%= tool_call_model_name %> < ApplicationRecord
+  <%= acts_as_tool_call_declaration %>
+end

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

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module LexLLM
+  module Generators
+    # Generator for LexLLM schema classes.
+    class SchemaGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path('templates', __dir__)
+
+      namespace 'lex_llm:schema'
+
+      desc 'Creates a LexLLM 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/lex_llm/schema/templates/schema.rb.tt

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

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

@@ -0,0 +1,9 @@
+class <%= class_name %>Tool < LexLLM::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/lex_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/lex_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/lex_llm/tool/tool_generator.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module LexLLM
+  module Generators
+    # Generator for LexLLM tool classes and related message partials.
+    class ToolGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path('templates', __dir__)
+
+      namespace 'lex_llm:tool'
+
+      check_class_collision suffix: 'Tool'
+
+      desc 'Creates a LexLLM 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/lex_llm/upgrade_to_v1_10/templates/add_v1_10_message_columns.rb.tt

@@ -0,0 +1,19 @@
+class AddLexLlmV110Columns < ActiveRecord::Migration<%= migration_version %>
+  def change
+    unless column_exists?(:<%= message_table_name %>, :thinking_text)
+      add_column :<%= message_table_name %>, :thinking_text, :text
+    end
+
+    unless column_exists?(:<%= message_table_name %>, :thinking_signature)
+      add_column :<%= message_table_name %>, :thinking_signature, :text
+    end
+
+    unless column_exists?(:<%= message_table_name %>, :thinking_tokens)
+      add_column :<%= message_table_name %>, :thinking_tokens, :integer
+    end
+
+    unless column_exists?(:<%= tool_call_table_name %>, :thought_signature)
+      add_column :<%= tool_call_table_name %>, :thought_signature, :string
+    end
+  end
+end

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+require 'rails/generators/active_record'
+require_relative '../generator_helpers'
+
+module LexLLM
+  module Generators
+    # Generator to add v1.10 columns (thinking output + thinking tokens) to existing apps.
+    class UpgradeToV110Generator < Rails::Generators::Base
+      include Rails::Generators::Migration
+      include LexLLM::Generators::GeneratorHelpers
+
+      namespace 'lex_llm:upgrade_to_v1_10'
+      source_root File.expand_path('templates', __dir__)
+
+      argument :model_mappings, type: :array, default: [], banner: 'message:MessageName'
+
+      desc 'Adds thinking output columns and thinking token tracking introduced in v1.10.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_10_message_columns.rb.tt',
+                           'db/migrate/add_lex_llm_v1_10_columns.rb',
+                           migration_version: migration_version,
+                           message_table_name: message_table_name,
+                           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.10.0 release notes for details on extended thinking support.
+
+        INSTRUCTIONS
+      end
+    end
+  end
+end

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

@@ -0,0 +1,7 @@
+class AddLexLlmV114Columns < 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/lex_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 LexLLM
+  module Generators
+    # Generator to fix tool call thought signature column type for MySQL safety.
+    class UpgradeToV114Generator < Rails::Generators::Base
+      include Rails::Generators::Migration
+      include LexLLM::Generators::GeneratorHelpers
+
+      namespace 'lex_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_lex_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