rails_ai_admin 0.1.0

data/db/assistant_migrate/20261103000001_create_rails_ai_admin_assistant.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+# Opt-in admin Chat storage, installed only by `rails_ai_admin:assistant`.
+# Chats, messages and turns are Engine-owned. Tool calls and usages live in
+# RubyLLM's own shared tables, isolated per chat by their polymorphic message
+# and chat columns; they are created here only when the host has none yet.
+class CreateRailsAiAdminAssistant < ActiveRecord::Migration[8.0]
+  def up
+    key = reference_type
+    create_ruby_llm_tables(key)
+
+    create_table :rails_ai_admin_assistant_chats, id: key do |t|
+      t.string :ref, null: false, limit: 36
+      t.string :actor_ref, :tenant_ref, :security_version, null: false, limit: 150
+      t.string :title, limit: 120
+      t.string :status, null: false, default: "active"
+      t.references :ruby_llm_model, type: key, foreign_key: { to_table: :ruby_llm_models }, index: { name: "raa_assistant_chats_model" }
+      t.boolean :cancelled, null: false, default: false
+      t.timestamps
+    end
+    add_index :rails_ai_admin_assistant_chats, :ref, unique: true, name: "raa_assistant_chats_ref"
+    add_index :rails_ai_admin_assistant_chats, [ :tenant_ref, :actor_ref, :updated_at ], name: "raa_assistant_chats_owner"
+    add_check_constraint :rails_ai_admin_assistant_chats, "status IN ('active', 'archived')", name: "raa_assistant_chats_status"
+
+    # Columns follow RubyLLM 2.1.1's message template; the 2.2 upgrade migration adds the rest.
+    create_table :rails_ai_admin_assistant_messages, id: key do |t|
+      t.references :chat, null: false, type: key, foreign_key: { to_table: :rails_ai_admin_assistant_chats }, index: { name: "raa_assistant_messages_chat" }
+      t.string :role, null: false
+      t.text :content
+      t.boolean :cache_until_here, null: false, default: false
+      t.string :cache_ttl
+      t.text :thinking_text, :thinking_signature
+      t.json :citations, :server_tool_calls, :raw_content, :raw_reasoning
+      t.string :finish_reason
+      t.timestamps
+    end
+
+    # One persistent inbox per chat: human messages and Surface continuations
+    # are admitted once by key and run strictly in sequence under a lease.
+    create_table :rails_ai_admin_assistant_turns, id: :string, limit: 36 do |t|
+      t.references :chat, null: false, type: key, foreign_key: { to_table: :rails_ai_admin_assistant_chats }, index: false
+      t.integer :sequence, null: false
+      t.string :kind, null: false
+      t.string :admission_key, null: false, limit: 100
+      t.text :content, null: false
+      t.string :status, null: false, default: "queued"
+      t.references :user_message, type: key, foreign_key: { to_table: :rails_ai_admin_assistant_messages }, index: { name: "raa_assistant_turns_message" }
+      t.string :lease_owner, limit: 36
+      t.datetime :lease_expires_at, :next_attempt_at, :completed_at
+      t.integer :generation, :attempts, null: false, default: 0
+      t.string :error_code, limit: 64
+      t.timestamps
+    end
+    add_index :rails_ai_admin_assistant_turns, [ :chat_id, :sequence ], unique: true, name: "raa_assistant_turns_sequence"
+    add_index :rails_ai_admin_assistant_turns, [ :chat_id, :admission_key ], unique: true, name: "raa_assistant_turns_admission"
+    add_index :rails_ai_admin_assistant_turns, [ :status, :lease_expires_at ], name: "raa_assistant_turns_due"
+    add_check_constraint :rails_ai_admin_assistant_turns, "kind IN ('message', 'continuation')", name: "raa_assistant_turns_kind"
+    add_check_constraint :rails_ai_admin_assistant_turns, "status IN ('queued', 'running', 'completed', 'failed', 'cancelled')", name: "raa_assistant_turns_status"
+  end
+
+  # RubyLLM's shared tables may belong to the host product; they are kept.
+  def down
+    drop_table :rails_ai_admin_assistant_turns
+    drop_table :rails_ai_admin_assistant_messages
+    drop_table :rails_ai_admin_assistant_chats
+  end
+
+  private
+
+  # Polymorphic tool-call/usage columns must hold admin message and chat keys,
+  # so admin keys follow an existing RubyLLM installation.
+  def reference_type
+    return :bigint unless table_exists?(:ruby_llm_tool_calls)
+    column = connection.columns(:ruby_llm_tool_calls).find { |candidate| candidate.name == "message_id" }
+    column&.type == :uuid ? :uuid : :bigint
+  end
+
+  # Mirrors the RubyLLM 2.1.1 install template for the tables admin Chat uses;
+  # UpgradeRailsAiAdminAssistantToRubyLlm22 brings them to 2.2.
+  def create_ruby_llm_tables(key)
+    json = connection.adapter_name.match?(/postg/i) ? :jsonb : :json
+    unless table_exists?(:ruby_llm_models)
+      create_table :ruby_llm_models, id: key do |t|
+        t.string :model_id, :name, :provider, null: false
+        t.string :family
+        t.datetime :model_created_at
+        t.integer :context_window, :max_output_tokens
+        t.date :knowledge_cutoff
+        t.datetime :unlisted_at
+        t.column :modalities, json, default: {}
+        t.column :capabilities, json, default: []
+        t.column :pricing, json, default: {}
+        t.column :metadata, json, default: {}
+        t.timestamps
+        t.index [ :provider, :model_id ], unique: true
+        t.index :provider
+        t.index :family
+      end
+    end
+    unless table_exists?(:ruby_llm_tool_calls)
+      create_table :ruby_llm_tool_calls, id: key do |t|
+        t.references :message, polymorphic: true, null: false, type: key, index: false
+        t.references :result, polymorphic: true, type: key, index: false
+        t.string :tool_call_id, :name, null: false
+        t.text :thought_signature
+        t.string :approval
+        t.boolean :remote, default: false, null: false
+        t.column :arguments, json, default: {}
+        t.column :mcp_state, json
+        t.column :mcp_result, json
+        t.timestamps
+        t.index [ :message_type, :message_id ]
+        t.index [ :result_type, :result_id ]
+        t.index :tool_call_id, unique: true
+        t.index :name
+      end
+    end
+    return if table_exists?(:ruby_llm_usages)
+    create_table :ruby_llm_usages, id: key do |t|
+      t.references :chat, polymorphic: true, type: key, index: false
+      t.references :message, polymorphic: true, type: key, index: false
+      t.references :owner, polymorphic: true, type: key, index: false
+      t.string :operation, :provider, :model, :status, null: false
+      t.integer :input_tokens, :output_tokens, :cache_read_tokens, :cache_write_tokens, :thinking_tokens
+      t.column :server_tool_use, json
+      t.decimal :input_cost, :output_cost, :cache_read_cost, :cache_write_cost, :thinking_cost, :total_cost, precision: 16, scale: 10
+      t.timestamps
+      t.index [ :chat_type, :chat_id ]
+      t.index [ :message_type, :message_id ]
+      t.index [ :owner_type, :owner_id ]
+      t.index :status
+    end
+    entry = ::RubyLLM::Accounting::Usage::Entry
+    quote = ->(values) { values.map { |value| connection.quote(value.to_s) }.join(", ") }
+    add_check_constraint :ruby_llm_usages, "operation IN (#{quote.call(entry::OPERATIONS)})"
+    add_check_constraint :ruby_llm_usages, "status IN (#{quote.call(entry::STATUSES)})"
+  end
+end

data/db/assistant_migrate/20261112000001_upgrade_rails_ai_admin_assistant_to_ruby_llm_2_2.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+# Adds the storage RubyLLM 2.2 reads and writes, following its
+# upgrade_ruby_llm_to_2_2 template. Every step is skipped when already present,
+# so it is safe beside a host that ran RubyLLM's own install or upgrade for the
+# shared tables (tool calls, usages, queued messages, chat files).
+class UpgradeRailsAiAdminAssistantToRubyLlm22 < ActiveRecord::Migration[8.0]
+  CHATS = :rails_ai_admin_assistant_chats
+  MESSAGES = :rails_ai_admin_assistant_messages
+
+  def up
+    add_column CHATS, :claim_token, :string unless column_exists?(CHATS, :claim_token)
+    add_column CHATS, :claimed_until, :datetime unless column_exists?(CHATS, :claimed_until)
+    unless index_exists?(CHATS, :claimed_until, name: "raa_assistant_chats_claim")
+      add_index CHATS, :claimed_until, where: "claim_token IS NOT NULL", name: "raa_assistant_chats_claim"
+    end
+    add_column MESSAGES, :phase, :string unless column_exists?(MESSAGES, :phase)
+    add_column MESSAGES, :continuation, :text unless column_exists?(MESSAGES, :continuation)
+
+    upgrade_tool_calls
+    upgrade_usages
+    key = reference_type
+    create_queued_messages(key)
+    create_chat_files(key)
+  end
+
+  # RubyLLM's shared tables may belong to the host product; they are kept.
+  def down
+    remove_index CHATS, name: "raa_assistant_chats_claim", if_exists: true
+    remove_column CHATS, :claimed_until, if_exists: true
+    remove_column CHATS, :claim_token, if_exists: true
+    remove_column MESSAGES, :continuation, if_exists: true
+    remove_column MESSAGES, :phase, if_exists: true
+  end
+
+  private
+
+  def upgrade_tool_calls
+    unless column_exists?(:ruby_llm_tool_calls, :provider_call_id)
+      if column_exists?(:ruby_llm_tool_calls, :provider_id)
+        rename_column :ruby_llm_tool_calls, :provider_id, :provider_call_id
+      else
+        add_column :ruby_llm_tool_calls, :provider_call_id, :string
+      end
+    end
+    add_column :ruby_llm_tool_calls, :namespace, :string unless column_exists?(:ruby_llm_tool_calls, :namespace)
+    add_column :ruby_llm_tool_calls, :claimed_until, :datetime unless column_exists?(:ruby_llm_tool_calls, :claimed_until)
+  end
+
+  # An operation check written by 2.1 lacks code_execution. Admin Chat never
+  # runs code, so it is left alone; a host that does runs RubyLLM's upgrade.
+  def upgrade_usages
+    %i[workflow_id workflow_name workflow_step_id workflow_step_name].each do |column|
+      add_column :ruby_llm_usages, column, :string unless column_exists?(:ruby_llm_usages, column)
+    end
+    add_index :ruby_llm_usages, :workflow_id unless index_exists?(:ruby_llm_usages, :workflow_id)
+    add_column :ruby_llm_usages, :characters, :integer unless column_exists?(:ruby_llm_usages, :characters)
+    add_column :ruby_llm_usages, :audio_seconds, :decimal, precision: 16, scale: 6 unless column_exists?(:ruby_llm_usages, :audio_seconds)
+    add_column :ruby_llm_usages, :search_units, :integer unless column_exists?(:ruby_llm_usages, :search_units)
+    %i[characters_cost audio_seconds_cost search_units_cost].each do |column|
+      add_column :ruby_llm_usages, column, :decimal, precision: 16, scale: 10 unless column_exists?(:ruby_llm_usages, column)
+    end
+  end
+
+  def create_queued_messages(key)
+    return if table_exists?(:ruby_llm_queued_messages)
+    create_table :ruby_llm_queued_messages, id: key do |t|
+      t.references :chat, polymorphic: true, null: false, type: key, index: false
+      t.references :sender, polymorphic: true, type: key, index: false
+      t.text :content
+      t.boolean :steer, default: true, null: false
+      t.timestamps
+      t.index [ :chat_type, :chat_id ]
+      t.index [ :sender_type, :sender_id ]
+    end
+  end
+
+  def create_chat_files(key)
+    unless table_exists?(:ruby_llm_chat_files)
+      create_table :ruby_llm_chat_files, id: key do |t|
+        t.references :chat, polymorphic: true, null: false, type: key, index: false
+        t.references :owner, polymorphic: true, type: key, index: false
+        t.string :path, null: false
+        t.string :content_type
+        t.bigint :byte_size
+        t.string :digest
+        t.text :text
+        t.string :read_digest
+        t.timestamps
+        t.index [ :chat_type, :chat_id, :path ]
+        t.index [ :owner_type, :owner_id ]
+      end
+    end
+    add_column :ruby_llm_chat_files, :read_digest, :string unless column_exists?(:ruby_llm_chat_files, :read_digest)
+  end
+
+  # New polymorphic columns hold the same keys as the existing tool calls.
+  def reference_type
+    column = connection.columns(:ruby_llm_tool_calls).find { |candidate| candidate.name == "message_id" }
+    column&.type == :uuid ? :uuid : :bigint
+  end
+end

data/db/assistant_migrate/20261114000001_add_streaming_and_access_tokens_to_rails_ai_admin_assistant.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+# Streaming replies keep the text of the request in progress on its turn, and
+# MCP clients authenticate with personal access tokens. Steps already present
+# are skipped.
+class AddStreamingAndAccessTokensToRailsAiAdminAssistant < ActiveRecord::Migration[8.0]
+  def up
+    add_column :rails_ai_admin_assistant_turns, :draft, :text unless column_exists?(:rails_ai_admin_assistant_turns, :draft)
+    return if table_exists?(:rails_ai_admin_access_tokens)
+    create_table :rails_ai_admin_access_tokens, id: :string, limit: 36 do |t|
+      t.string :actor_ref, :tenant_ref, null: false, limit: 150
+      t.string :security_version, null: false, limit: 150
+      t.string :name, null: false, limit: 80
+      # SHA-256 of the token; the token itself is shown once and never stored.
+      t.string :token_digest, null: false, limit: 64
+      t.datetime :expires_at, null: false
+      t.datetime :last_used_at
+      t.datetime :revoked_at
+      t.timestamps
+    end
+    add_index :rails_ai_admin_access_tokens, :token_digest, unique: true, name: "raa_access_tokens_digest"
+    add_index :rails_ai_admin_access_tokens, [ :actor_ref, :tenant_ref ], name: "raa_access_tokens_owner"
+  end
+
+  def down
+    drop_table :rails_ai_admin_access_tokens, if_exists: true
+    remove_column :rails_ai_admin_assistant_turns, :draft, if_exists: true
+  end
+end

data/db/migrate/20261029000001_create_rails_ai_admin_execution_tables.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+class CreateRailsAiAdminExecutionTables < ActiveRecord::Migration[8.0]
+  def change
+    create_table :rails_ai_admin_operation_runs, id: :string, limit: 36 do |t|
+      t.string :actor_ref, :tenant_ref, :security_version, null: false, limit: 150
+      t.string :resource_key, :operation, :operation_version, null: false
+      t.string :target_id, :record_id, limit: 150
+      t.bigint :expected_version
+      t.string :input_digest, :approved_digest, limit: 64
+      t.string :status, null: false, default: "proposed"
+      t.string :origin, null: false, default: "ui"
+      t.string :approved_by_ref, limit: 150
+      t.datetime :confirmed_at, :expires_at, :completed_at
+      t.bigint :audit_event_id
+      t.timestamps
+    end
+    add_index :rails_ai_admin_operation_runs, [ :tenant_ref, :actor_ref, :created_at ], name: "raa_runs_owner"
+    add_index :rails_ai_admin_operation_runs, [ :status, :expires_at ], name: "raa_runs_expiry"
+    add_check_constraint :rails_ai_admin_operation_runs, "status IN ('proposed', 'running', 'succeeded')", name: "raa_runs_status"
+
+    create_table :rails_ai_admin_audit_events do |t|
+      t.string :actor_ref, :tenant_ref, null: false, limit: 150
+      t.string :resource_key, :operation, :status, :code, null: false
+      t.string :record_id, limit: 150
+      t.string :correlation_ref, null: false, limit: 36
+      t.string :origin, null: false
+      t.json :changed_fields, null: false, default: []
+      t.datetime :created_at, null: false
+    end
+    add_index :rails_ai_admin_audit_events, [ :tenant_ref, :created_at ], name: "raa_audit_tenant"
+    add_index :rails_ai_admin_audit_events, :correlation_ref, name: "raa_audit_correlation"
+    add_foreign_key :rails_ai_admin_operation_runs, :rails_ai_admin_audit_events, column: :audit_event_id
+  end
+end

data/db/migrate/20261029000002_add_callback_warning_to_rails_ai_admin_runs.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class AddCallbackWarningToRailsAiAdminRuns < ActiveRecord::Migration[8.0]
+  def change
+    add_column :rails_ai_admin_operation_runs, :warning_code, :string
+  end
+end

data/db/migrate/20261030000003_create_rails_ai_admin_work_items.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+class CreateRailsAiAdminWorkItems < ActiveRecord::Migration[8.0]
+  def change
+    create_table :rails_ai_admin_work_items, id: :string, limit: 36 do |t|
+      t.string :operation_run_id, null: false, limit: 36
+      t.string :work_key, :kind, :handler_version, :payload_digest, null: false
+      t.json :payload, null: false, default: {}
+      t.string :status, null: false, default: "pending"
+      t.bigint :expected_version
+      t.integer :generation, :attempts, null: false, default: 0
+      t.integer :effect_generation
+      t.string :effect_digest, limit: 64
+      t.string :lease_owner, limit: 36
+      t.datetime :lease_expires_at, :next_attempt_at, :effect_started_at, :completed_at
+      t.datetime :deadline_at, null: false
+      t.string :last_code
+      t.timestamps
+    end
+    add_index :rails_ai_admin_work_items, [ :operation_run_id, :work_key ], unique: true, name: "raa_work_intent_key"
+    add_index :rails_ai_admin_work_items, [ :status, :next_attempt_at ], name: "raa_work_pending"
+    add_index :rails_ai_admin_work_items, [ :status, :lease_expires_at ], name: "raa_work_lease"
+    add_foreign_key :rails_ai_admin_work_items, :rails_ai_admin_operation_runs, column: :operation_run_id
+    add_check_constraint :rails_ai_admin_work_items, "status IN ('pending', 'running', 'succeeded', 'failed', 'cancelled', 'reconciliation_required')", name: "raa_work_status"
+  end
+end

data/db/migrate/20261030000004_create_rails_ai_admin_selections.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+class CreateRailsAiAdminSelections < ActiveRecord::Migration[8.0]
+  def change
+    create_table :rails_ai_admin_selections, id: :string, limit: 36 do |t|
+      t.string :actor_ref, :tenant_ref, :security_version, null: false, limit: 150
+      t.string :resource_key, null: false
+      t.string :resource_version, :manifest_digest, null: false, limit: 64
+      t.integer :item_count, null: false
+      t.datetime :expires_at, null: false
+      t.timestamps
+    end
+    add_index :rails_ai_admin_selections, [ :tenant_ref, :actor_ref, :created_at ], name: "raa_selections_owner"
+    add_index :rails_ai_admin_selections, :expires_at, name: "raa_selections_expiry"
+    add_check_constraint :rails_ai_admin_selections, "item_count BETWEEN 1 AND 100", name: "raa_selections_count"
+
+    create_table :rails_ai_admin_selection_items do |t|
+      t.string :selection_id, null: false, limit: 36
+      t.string :target_id, null: false, limit: 150
+      t.bigint :expected_version, null: false
+      t.integer :position, null: false
+    end
+    add_foreign_key :rails_ai_admin_selection_items, :rails_ai_admin_selections, column: :selection_id
+    add_index :rails_ai_admin_selection_items, [ :selection_id, :target_id ], unique: true, name: "raa_selection_targets"
+    add_index :rails_ai_admin_selection_items, [ :selection_id, :position ], unique: true, name: "raa_selection_order"
+    add_check_constraint :rails_ai_admin_selection_items, "expected_version >= 0 AND position BETWEEN 0 AND 99", name: "raa_selection_item_bounds"
+  end
+end

data/db/migrate/20261030000005_create_rails_ai_admin_collection_runs.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+class CreateRailsAiAdminCollectionRuns < ActiveRecord::Migration[8.0]
+  def change
+    remove_check_constraint :rails_ai_admin_operation_runs, "status IN ('proposed', 'running', 'succeeded')", name: "raa_runs_status"
+    change_table :rails_ai_admin_operation_runs do |t|
+      t.string :selection_id, :parent_run_id, limit: 36
+      t.string :selection_digest, :manifest_resource_version, limit: 64
+      t.json :input_payload, :manifest_payload
+      t.datetime :execution_deadline, :cancellation_requested_at
+    end
+    add_foreign_key :rails_ai_admin_operation_runs, :rails_ai_admin_selections, column: :selection_id
+    add_foreign_key :rails_ai_admin_operation_runs, :rails_ai_admin_operation_runs, column: :parent_run_id
+    add_index :rails_ai_admin_operation_runs, [ :parent_run_id, :target_id ], unique: true, name: "raa_child_target"
+    add_check_constraint :rails_ai_admin_operation_runs,
+      "status IN ('proposed', 'queued', 'running', 'succeeded', 'failed', 'partially_succeeded', 'cancelled', 'reconciliation_required')", name: "raa_runs_status"
+
+    create_table :rails_ai_admin_batch_items, id: :string, limit: 36 do |t|
+      t.string :parent_run_id, :operation_run_id, null: false, limit: 36
+      t.bigint :selection_item_id, null: false
+      t.string :target_id, null: false, limit: 150
+      t.bigint :expected_version, null: false
+      t.integer :position, null: false
+      t.string :status, null: false, default: "queued"
+      t.string :lease_owner, limit: 36
+      t.integer :generation, :attempts, null: false, default: 0
+      t.string :last_code, limit: 64
+      t.datetime :lease_expires_at, :next_attempt_at, :completed_at
+      t.timestamps
+    end
+    add_foreign_key :rails_ai_admin_batch_items, :rails_ai_admin_operation_runs, column: :parent_run_id
+    add_foreign_key :rails_ai_admin_batch_items, :rails_ai_admin_operation_runs, column: :operation_run_id
+    add_foreign_key :rails_ai_admin_batch_items, :rails_ai_admin_selection_items, column: :selection_item_id
+    add_index :rails_ai_admin_batch_items, :operation_run_id, unique: true, name: "raa_batch_child"
+    add_index :rails_ai_admin_batch_items, [ :parent_run_id, :target_id ], unique: true, name: "raa_batch_target"
+    add_index :rails_ai_admin_batch_items, [ :parent_run_id, :position ], unique: true, name: "raa_batch_order"
+    add_index :rails_ai_admin_batch_items, [ :status, :lease_expires_at, :next_attempt_at ], name: "raa_batch_due"
+    add_check_constraint :rails_ai_admin_batch_items, "status IN ('queued', 'running', 'succeeded', 'failed', 'cancelled')", name: "raa_batch_status"
+    add_check_constraint :rails_ai_admin_batch_items, "position BETWEEN 0 AND 99 AND expected_version >= 0 AND generation >= 0 AND attempts >= 0", name: "raa_batch_bounds"
+  end
+end

data/db/migrate/20261113000001_add_record_index_to_rails_ai_admin_audit_events.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# Serves a record's history page: one tenant, resource and record, newest first.
+class AddRecordIndexToRailsAiAdminAuditEvents < ActiveRecord::Migration[8.0]
+  def change
+    add_index :rails_ai_admin_audit_events, [ :tenant_ref, :resource_key, :record_id, :id ], name: "raa_audit_record"
+  end
+end

data/lib/generators/rails_ai_admin/assistant/assistant_generator.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require_relative "../engine_migrations"
+
+module RailsAiAdmin
+  module Generators
+    # Adds opt-in admin Chat storage and a closed provider adapter. Nothing is
+    # enabled until the host sets `config.assistant = true` and returns a
+    # RubyLLM::Context from the adapter.
+    class AssistantGenerator < Rails::Generators::Base
+      include EngineMigrations
+      source_root File.expand_path("templates", __dir__)
+
+      def install
+        copy_engine_migrations("db/assistant_migrate")
+        target = "app/rails_ai_admin/admin_assistant.rb"
+        template "admin_assistant.rb", target unless File.exist?(File.join(destination_root, target))
+        say "The assistant stays unavailable: AdminAssistant#llm_context returns nil, and no resource grants assistant?."
+        say "Add ruby_llm (#{Configuration::OPTIONAL_GEMS.fetch('ruby_llm').fetch(:requirement).join(', ')}) to the Gemfile, run db:migrate, then set config.assistant = true, config.assistant_adapter = \"AdminAssistant\" and config.assistant_model."
+        say "Schedule rails_ai_admin:assistant:scan to recover lost jobs. Guide: #{GUIDES}/_advanced/admin-assistant.md"
+      end
+    end
+  end
+end

data/lib/generators/rails_ai_admin/assistant/templates/admin_assistant.rb

@@ -0,0 +1,18 @@
+# Builds the admin assistant's provider configuration for one admin Context.
+# Returning nil keeps the assistant unavailable for that actor; this is the
+# default. Read credentials from your secret store and never change global
+# RubyLLM settings here: the admin's provider settings stay separate from your
+# product's.
+class AdminAssistant
+  def llm_context(context:)
+    nil
+    # key = Rails.application.credentials.dig(:admin_assistant, :openai_api_key)
+    # return unless key
+    #
+    # RubyLLM.context do |config|
+    #   config.openai_api_key = key
+    #   config.request_timeout = 60
+    #   config.max_retries = 1
+    # end
+  end
+end

data/lib/generators/rails_ai_admin/engine_migrations.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "rails/generators/migration"
+
+module RailsAiAdmin
+  module Generators
+    # Copies each engine migration the host does not have yet. A migration the
+    # host already has is kept even with --force: it may have run, and
+    # replacing it under a new timestamp would run it twice. Schema changes
+    # ship as new migrations.
+    # The gem ships no docs/ directory, so generator output links the guides
+    # in the source repository (RAA-026).
+    GUIDES = "https://github.com/yorzi/rails_ai_admin/blob/main/docs/site"
+
+    module EngineMigrations # :nodoc:
+      def self.included(base)
+        base.include Rails::Generators::Migration
+        base.extend ClassMethods
+      end
+
+      module ClassMethods # :nodoc:
+        def next_migration_number(dirname)
+          [ Time.now.utc.strftime("%Y%m%d%H%M%S"), format("%014d", current_migration_number(dirname) + 1) ].max
+        end
+      end
+
+      private
+
+      def copy_engine_migrations(directory)
+        Engine.root.join(directory).glob("*.rb").sort.each do |source|
+          stem = source.basename(".rb").to_s.sub(/\A\d+_/, "")
+          existing = self.class.migration_exists?(File.join(destination_root, "db/migrate"), stem)
+          if existing
+            say_status :exist, Pathname.new(existing).relative_path_from(Pathname.new(destination_root)).to_s, :blue
+          else
+            migration_template source.to_s, "db/migrate/#{stem}.rb"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/generators/rails_ai_admin/install/engine_mounts.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module RailsAiAdmin
+  module Generators
+    # Uses Rails' loaded routes, including drawn files and namespace prefixes.
+    module EngineMounts # :nodoc:
+      def self.names(routes)
+        routes.routes.filter_map do |route|
+          endpoint = route.app
+          while endpoint.is_a?(ActionDispatch::Routing::Mapper::Constraints)
+            endpoint = endpoint.app
+          end
+          next unless endpoint.equal?(RailsAiAdmin::Engine) || endpoint.is_a?(RailsAiAdmin::Engine)
+          route.parts.empty? && route.verb.empty? ? route.name.to_s : :unsupported
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require_relative "engine_mounts"
+require_relative "../engine_migrations"
+
+module RailsAiAdmin
+  module Generators
+    # Installs conventional tables and a deliberately closed host context.
+    class InstallGenerator < Rails::Generators::Base
+      include EngineMigrations
+      source_root File.expand_path("templates", __dir__)
+
+      def initialize(args = [], options = {}, config = {})
+        @host_application = config.fetch(:application) { Rails.application }
+        super
+      end
+
+      def install
+        unless @host_application && @host_application.root.realpath == Pathname.new(destination_root).realpath
+          raise Rails::Generators::Error, "Run install inside the target Rails application so its actual routes can be checked. No files were changed."
+        end
+        mounts = EngineMounts.names(@host_application.routes)
+        if mounts.empty? && @host_application.routes.named_routes.names.map(&:to_s).include?("rails_ai_admin")
+          raise Rails::Generators::Error, "The rails_ai_admin route name belongs to another endpoint. Resolve the conflict before installation. No files were changed."
+        end
+        if mounts.any? && mounts != [ "rails_ai_admin" ]
+          raise Rails::Generators::Error, "Use one RailsAiAdmin::Engine mount whose final helper is rails_ai_admin. Custom paths are supported; other aliases, name prefixes, dynamic parameters and multiple mounts require review. No files were changed."
+        end
+        %w[AdminContext AdminPolicyAdapter ExampleAdmin].each do |constant|
+          target = File.join(destination_root, "app/rails_ai_admin/#{constant.underscore}.rb")
+          if Object.const_defined?(constant) && !File.exist?(target)
+            raise Rails::Generators::Error, "Constant #{constant} already exists outside the generated path"
+          end
+        end
+        copy_engine_migrations("db/migrate")
+        template "initializer.rb", "config/initializers/rails_ai_admin.rb"
+        template "admin_context.rb", "app/rails_ai_admin/admin_context.rb"
+        {
+          "admin_policy_adapter.rb" => "app/rails_ai_admin/admin_policy_adapter.rb",
+          "example_admin.rb" => "app/rails_ai_admin/example_admin.rb",
+          "access_test.rb" => "test/rails_ai_admin/access_test.rb"
+        }.each do |source, target|
+          template source, target unless File.exist?(File.join(destination_root, target))
+        end
+        route 'mount RailsAiAdmin::Engine => "/admin", as: :rails_ai_admin' if mounts.empty?
+        say "Access remains closed. Implement AdminContext and an explicit policy adapter; then run db:migrate and rails_ai_admin:doctor."
+        say "ExampleAdmin is unregistered. Review it or generate your own resource. Run bin/rails test test/rails_ai_admin/access_test.rb."
+        say "Guide: #{GUIDES}/_getting_started/getting-started.md"
+      end
+    end
+  end
+end

data/lib/generators/rails_ai_admin/install/templates/access_test.rb

@@ -0,0 +1,17 @@
+require "test_helper"
+
+class RailsAiAdminAccessTest < ActionDispatch::IntegrationTest
+  # Closed means no admin page renders: a 401, or with config.authentication_path
+  # a redirect to sign-in.
+  test "anonymous access stays closed" do
+    path = Rails.application.routes.url_helpers.rails_ai_admin_path
+    get path
+    sign_in = RailsAiAdmin.configuration.authentication_path
+    if sign_in
+      assert_response :see_other
+      assert_equal sign_in, URI(response.location).path
+    else
+      assert_response :unauthorized
+    end
+  end
+end

data/lib/generators/rails_ai_admin/install/templates/admin_context.rb

@@ -0,0 +1,25 @@
+class AdminContext
+  def resolve(controller)
+    # TODO: authenticate through your host's public session/authentication API.
+    # Return RailsAiAdmin::Context.new(actor:, tenant:, security_version:).
+    # Increment security_version when session, role or tenant authority changes.
+    nil
+  end
+
+  # Working example for an app made with `bin/rails generate authentication`
+  # and a boolean `admin` column on users. Replace the method above with it
+  # once you have reviewed it. Devise apps read controller.warden.user(:user).
+  #
+  # # One fixed tenant for an app without accounts. With an Account model,
+  # # pass the user's account instead and scope the policy by it.
+  # SingleTenant = Data.define(:id)
+  # TENANT = SingleTenant.new(id: "app")
+  #
+  # def resolve(controller)
+  #   session = Session.find_by(id: controller.request.cookie_jar.signed[:session_id])
+  #   user = session&.user
+  #   return unless user&.admin?
+  #   # Any change to the user, including the admin flag, invalidates open forms.
+  #   RailsAiAdmin::Context.new(actor: user, tenant: TENANT, security_version: user.updated_at.to_i.to_s)
+  # end
+end