Restructure omni services and add Chatwoot research snapshot

research/chatwoot/lib/tasks/apply_sla.rake

@@ -0,0 +1,100 @@
+# Apply SLA Policy to Conversations
+#
+# This task applies an SLA policy to existing conversations that don't have one assigned.
+# It processes conversations in batches and only affects conversations with sla_policy_id = nil.
+#
+# Usage Examples:
+#   # Using arguments (may need escaping in some shells)
+#   bundle exec rake "sla:apply_to_conversations[19,1,500]"
+#
+#   # Using environment variables (recommended)
+#   SLA_POLICY_ID=19 ACCOUNT_ID=1 BATCH_SIZE=500 bundle exec rake sla:apply_to_conversations
+#
+# Parameters:
+#   SLA_POLICY_ID: ID of the SLA policy to apply (required)
+#   ACCOUNT_ID: ID of the account (required)
+#   BATCH_SIZE: Number of conversations to process (default: 1000)
+#
+# Notes:
+#   - Only runs in development environment
+#   - Processes conversations in order of newest first (id DESC)
+#   - Safe to run multiple times - skips conversations that already have SLA policies
+#   - Creates AppliedSla records automatically via Rails callbacks
+#   - SlaEvent records are created later by background jobs when violations occur
+#
+# rubocop:disable Metrics/BlockLength
+namespace :sla do
+  desc 'Apply SLA policy to existing conversations'
+  task :apply_to_conversations, [:sla_policy_id, :account_id, :batch_size] => :environment do |_t, args|
+    unless Rails.env.development?
+      puts 'This task can only be run in the development environment.'
+      puts "Current environment: #{Rails.env}"
+      exit(1)
+    end
+
+    sla_policy_id = args[:sla_policy_id] || ENV.fetch('SLA_POLICY_ID', nil)
+    account_id = args[:account_id] || ENV.fetch('ACCOUNT_ID', nil)
+    batch_size = (args[:batch_size] || ENV['BATCH_SIZE'] || 1000).to_i
+
+    if sla_policy_id.blank?
+      puts 'Error: SLA_POLICY_ID is required'
+      puts 'Usage: bundle exec rake sla:apply_to_conversations[sla_policy_id,account_id,batch_size]'
+      puts 'Or: SLA_POLICY_ID=1 ACCOUNT_ID=1 BATCH_SIZE=500 bundle exec rake sla:apply_to_conversations'
+      exit(1)
+    end
+
+    if account_id.blank?
+      puts 'Error: ACCOUNT_ID is required'
+      puts 'Usage: bundle exec rake sla:apply_to_conversations[sla_policy_id,account_id,batch_size]'
+      puts 'Or: SLA_POLICY_ID=1 ACCOUNT_ID=1 BATCH_SIZE=500 bundle exec rake sla:apply_to_conversations'
+      exit(1)
+    end
+
+    account = Account.find_by(id: account_id)
+    unless account
+      puts "Error: Account with ID #{account_id} not found"
+      exit(1)
+    end
+
+    sla_policy = account.sla_policies.find_by(id: sla_policy_id)
+    unless sla_policy
+      puts "Error: SLA Policy with ID #{sla_policy_id} not found for Account #{account_id}"
+      exit(1)
+    end
+
+    conversations = account.conversations.where(sla_policy_id: nil).order(id: :desc).limit(batch_size)
+    total_count = conversations.count
+
+    if total_count.zero?
+      puts 'No conversations found without SLA policy'
+      exit(0)
+    end
+
+    puts "Applying SLA Policy '#{sla_policy.name}' (ID: #{sla_policy_id}) to #{total_count} conversations in Account #{account_id}"
+    puts "Processing in batches of #{batch_size}"
+    puts "Started at: #{Time.current}"
+
+    start_time = Time.current
+    processed_count = 0
+    error_count = 0
+
+    conversations.find_in_batches(batch_size: batch_size) do |batch|
+      batch.each do |conversation|
+        conversation.update!(sla_policy_id: sla_policy_id)
+        processed_count += 1
+        puts "Processed #{processed_count}/#{total_count} conversations" if (processed_count % 100).zero?
+      rescue StandardError => e
+        error_count += 1
+        puts "Error applying SLA to conversation #{conversation.id}: #{e.message}"
+      end
+    end
+
+    elapsed_time = Time.current - start_time
+    puts "\nCompleted!"
+    puts "Successfully processed: #{processed_count} conversations"
+    puts "Errors encountered: #{error_count}" if error_count.positive?
+    puts "Total time: #{elapsed_time.round(2)}s"
+    puts "Average time per conversation: #{(elapsed_time / processed_count).round(3)}s" if processed_count.positive?
+  end
+end
+# rubocop:enable Metrics/BlockLength

research/chatwoot/lib/tasks/asset_clean.rake

@@ -0,0 +1,21 @@
+# Asset clean logic taken from the article https://chwt.app/heroku-slug-size
+
+namespace :assets do
+  desc "Remove 'node_modules' folder"
+  task rm_node_modules: :environment do
+    Rails.logger.info 'Removing node_modules folder'
+    FileUtils.remove_dir('node_modules', true)
+  end
+end
+
+skip_clean = %w[no false n f].include?(ENV.fetch('WEBPACKER_PRECOMPILE', nil))
+
+unless skip_clean
+  if Rake::Task.task_defined?('assets:clean')
+    Rake::Task['assets:clean'].enhance do
+      Rake::Task['assets:rm_node_modules'].invoke
+    end
+  else
+    Rake::Task.define_task('assets:clean' => 'assets:rm_node_modules')
+  end
+end

research/chatwoot/lib/tasks/auto_annotate_models.rake

@@ -0,0 +1,61 @@
+# NOTE: only doing this in development as some production environments (Heroku)
+# NOTE: are sensitive to local FS writes, and besides -- it's just not proper
+# NOTE: to have a dev-mode tool do its thing in production.
+if Rails.env.development?
+  require 'annotate_rb'
+
+  AnnotateRb::Core.load_rake_tasks
+
+  task :set_annotation_options do
+    # You can override any of these by setting an environment variable of the
+    # same name.
+    AnnotateRb::Options.set_defaults(
+      'additional_file_patterns' => [],
+      'routes' => 'false',
+      'models' => 'true',
+      'position_in_routes' => 'before',
+      'position_in_class' => 'before',
+      'position_in_test' => 'before',
+      'position_in_fixture' => 'before',
+      'position_in_factory' => 'before',
+      'position_in_serializer' => 'before',
+      'show_foreign_keys' => 'true',
+      'show_complete_foreign_keys' => 'false',
+      'show_indexes' => 'true',
+      'simple_indexes' => 'false',
+      'model_dir' => [
+        'app/models',
+        'enterprise/app/models',
+      ],
+      'root_dir' => '',
+      'include_version' => 'false',
+      'require' => '',
+      'exclude_tests' => 'true',
+      'exclude_fixtures' => 'true',
+      'exclude_factories' => 'true',
+      'exclude_serializers' => 'true',
+      'exclude_scaffolds' => 'true',
+      'exclude_controllers' => 'true',
+      'exclude_helpers' => 'true',
+      'exclude_sti_subclasses' => 'false',
+      'ignore_model_sub_dir' => 'false',
+      'ignore_columns' => nil,
+      'ignore_routes' => nil,
+      'ignore_unknown_models' => 'false',
+      'hide_limit_column_types' => 'integer,bigint,boolean',
+      'hide_default_column_types' => 'json,jsonb,hstore',
+      'skip_on_db_migrate' => 'false',
+      'format_bare' => 'true',
+      'format_rdoc' => 'false',
+      'format_markdown' => 'false',
+      'sort' => 'false',
+      'force' => 'false',
+      'frozen' => 'false',
+      'classified_sort' => 'true',
+      'trace' => 'false',
+      'wrapper_open' => nil,
+      'wrapper_close' => nil,
+      'with_comment' => 'true'
+    )
+  end
+end

research/chatwoot/lib/tasks/build.rake

@@ -0,0 +1,13 @@
+# ref: https://github.com/rails/rails/issues/43906#issuecomment-1094380699
+# https://github.com/rails/rails/issues/43906#issuecomment-1099992310
+task before_assets_precompile: :environment do
+  # run a command which starts your packaging
+  system('pnpm install')
+  system('echo "-------------- Bulding SDK for Production --------------"')
+  system('pnpm run build:sdk')
+  system('echo "-------------- Bulding App for Production --------------"')
+end
+
+# every time you execute 'rake assets:precompile'
+# run 'before_assets_precompile' first
+Rake::Task['assets:precompile'].enhance %w[before_assets_precompile]

research/chatwoot/lib/tasks/bulk_conversations.rake

@@ -0,0 +1,176 @@
+# Generate Bulk Conversations
+#
+# This task creates bulk conversations with fake contacts and movie dialogue messages
+# for testing purposes. Each conversation gets random messages between contacts and agents.
+#
+# Usage Examples:
+#   # Using arguments (may need escaping in some shells)
+#   bundle exec rake "conversations:generate_bulk[100,1,1]"
+#
+#   # Using environment variables (recommended)
+#   COUNT=100 ACCOUNT_ID=1 INBOX_ID=1 bundle exec rake conversations:generate_bulk
+#
+#   # Generate 50 conversations
+#   COUNT=50 ACCOUNT_ID=1 INBOX_ID=1 bundle exec rake conversations:generate_bulk
+#
+# Parameters:
+#   COUNT: Number of conversations to create (default: 10)
+#   ACCOUNT_ID: ID of the account (required)
+#   INBOX_ID: ID of the inbox that belongs to the account (required)
+#
+# What it creates:
+#   - Unique contacts with fake names, emails, phone numbers
+#   - Conversations with random status (open/resolved/pending)
+#   - 3-10 messages per conversation with movie quotes
+#   - Alternating incoming/outgoing message flow
+#
+# Notes:
+#   - Only runs in development environment
+#   - Creates realistic test data for conversation testing
+#   - Progress shown every 10 conversations
+#   - All contacts get unique email addresses to avoid conflicts
+#
+# rubocop:disable Metrics/BlockLength
+namespace :conversations do
+  desc 'Generate bulk conversations with contacts and movie dialogue messages'
+  task :generate_bulk, [:count, :account_id, :inbox_id] => :environment do |_t, args|
+    unless Rails.env.development?
+      puts 'This task can only be run in the development environment.'
+      puts "Current environment: #{Rails.env}"
+      exit(1)
+    end
+
+    count = (args[:count] || ENV['COUNT'] || 10).to_i
+    account_id = args[:account_id] || ENV.fetch('ACCOUNT_ID', nil)
+    inbox_id = args[:inbox_id] || ENV.fetch('INBOX_ID', nil)
+
+    if account_id.blank?
+      puts 'Error: ACCOUNT_ID is required'
+      puts 'Usage: bundle exec rake conversations:generate_bulk[count,account_id,inbox_id]'
+      puts 'Or: COUNT=100 ACCOUNT_ID=1 INBOX_ID=1 bundle exec rake conversations:generate_bulk'
+      exit(1)
+    end
+
+    if inbox_id.blank?
+      puts 'Error: INBOX_ID is required'
+      puts 'Usage: bundle exec rake conversations:generate_bulk[count,account_id,inbox_id]'
+      puts 'Or: COUNT=100 ACCOUNT_ID=1 INBOX_ID=1 bundle exec rake conversations:generate_bulk'
+      exit(1)
+    end
+
+    account = Account.find_by(id: account_id)
+    inbox = Inbox.find_by(id: inbox_id)
+
+    unless account
+      puts "Error: Account with ID #{account_id} not found"
+      exit(1)
+    end
+
+    unless inbox
+      puts "Error: Inbox with ID #{inbox_id} not found"
+      exit(1)
+    end
+
+    unless inbox.account_id == account.id
+      puts "Error: Inbox #{inbox_id} does not belong to Account #{account_id}"
+      exit(1)
+    end
+
+    puts "Generating #{count} conversations for Account ##{account.id} in Inbox ##{inbox.id}..."
+    puts "Started at: #{Time.current}"
+
+    start_time = Time.current
+    created_count = 0
+
+    count.times do |i|
+      contact = create_contact(account)
+      contact_inbox = create_contact_inbox(contact, inbox)
+      conversation = create_conversation(contact_inbox)
+      add_messages(conversation)
+
+      created_count += 1
+      puts "Created conversation #{i + 1}/#{count} (ID: #{conversation.id})" if ((i + 1) % 10).zero?
+    rescue StandardError => e
+      puts "Error creating conversation #{i + 1}: #{e.message}"
+      puts e.backtrace.first(5).join("\n")
+    end
+
+    elapsed_time = Time.current - start_time
+    puts "\nCompleted!"
+    puts "Successfully created: #{created_count} conversations"
+    puts "Total time: #{elapsed_time.round(2)}s"
+    puts "Average time per conversation: #{(elapsed_time / created_count).round(3)}s" if created_count.positive?
+  end
+
+  def create_contact(account)
+    Contact.create!(
+      account: account,
+      name: Faker::Name.name,
+      email: "#{SecureRandom.uuid}@example.com",
+      phone_number: generate_e164_phone_number,
+      additional_attributes: {
+        source: 'bulk_generator',
+        company: Faker::Company.name,
+        city: Faker::Address.city
+      }
+    )
+  end
+
+  def generate_e164_phone_number
+    country_code = [1, 44, 61, 91, 81].sample
+    subscriber_number = rand(1_000_000..9_999_999_999).to_s
+    subscriber_number = subscriber_number[0...(15 - country_code.to_s.length)]
+    "+#{country_code}#{subscriber_number}"
+  end
+
+  def create_contact_inbox(contact, inbox)
+    ContactInboxBuilder.new(
+      contact: contact,
+      inbox: inbox
+    ).perform
+  end
+
+  def create_conversation(contact_inbox)
+    ConversationBuilder.new(
+      params: ActionController::Parameters.new(
+        status: %w[open resolved pending].sample,
+        additional_attributes: {},
+        custom_attributes: {}
+      ),
+      contact_inbox: contact_inbox
+    ).perform
+  end
+
+  def add_messages(conversation)
+    num_messages = rand(3..10)
+    message_type = %w[incoming outgoing].sample
+
+    num_messages.times do
+      message_type = message_type == 'incoming' ? 'outgoing' : 'incoming'
+      create_message(conversation, message_type)
+    end
+  end
+
+  def create_message(conversation, message_type)
+    sender = if message_type == 'incoming'
+               conversation.contact
+             else
+               conversation.account.users.sample || conversation.account.administrators.first
+             end
+
+    conversation.messages.create!(
+      account: conversation.account,
+      inbox: conversation.inbox,
+      sender: sender,
+      message_type: message_type,
+      content: generate_movie_dialogue,
+      content_type: :text,
+      private: false
+    )
+  end
+
+  def generate_movie_dialogue
+    Faker::Movie.quote
+  end
+end
+# rubocop:enable Metrics/BlockLength

research/chatwoot/lib/tasks/captain_chat.rake

@@ -0,0 +1,235 @@
+require 'io/console'
+require 'readline'
+
+namespace :captain do
+  desc 'Start interactive chat with Captain assistant - Usage: rake captain:chat[assistant_id] or rake captain:chat -- assistant_id'
+  task :chat, [:assistant_id] => :environment do |_, args|
+    assistant_id = args[:assistant_id] || ARGV[1]
+
+    unless assistant_id
+      puts '❌ Please provide an assistant ID'
+      puts 'Usage: rake captain:chat[assistant_id]'
+      puts "\nAvailable assistants:"
+      Captain::Assistant.includes(:account).each do |assistant|
+        puts "  ID: #{assistant.id} - #{assistant.name} (Account: #{assistant.account.name})"
+      end
+      exit 1
+    end
+
+    assistant = Captain::Assistant.find_by(id: assistant_id)
+    unless assistant
+      puts "❌ Assistant with ID #{assistant_id} not found"
+      exit 1
+    end
+
+    # Clear ARGV to prevent gets from reading files
+    ARGV.clear
+
+    chat_session = CaptainChatSession.new(assistant)
+    chat_session.start
+  end
+end
+
+class CaptainChatSession
+  def initialize(assistant)
+    @assistant = assistant
+    @message_history = []
+  end
+
+  def start
+    show_assistant_info
+    show_instructions
+    chat_loop
+    show_exit_message
+  end
+
+  private
+
+  def show_instructions
+    puts "💡 Type 'exit', 'quit', or 'bye' to end the session"
+    puts "💡 Type 'clear' to clear message history"
+    puts('-' * 50)
+  end
+
+  def chat_loop
+    loop do
+      puts '' # Add spacing before prompt
+      user_input = Readline.readline('👤 You: ', true)
+      next unless user_input # Handle Ctrl+D
+
+      break unless handle_user_input(user_input.strip)
+    end
+  end
+
+  def handle_user_input(user_input)
+    case user_input.downcase
+    when 'exit', 'quit', 'bye'
+      false
+    when 'clear'
+      clear_history
+      true
+    when ''
+      true
+    else
+      process_user_message(user_input)
+      true
+    end
+  end
+
+  def show_exit_message
+    puts "\nChat session ended"
+    puts "Final conversation log has #{@message_history.length} messages"
+  end
+
+  def show_assistant_info
+    show_basic_info
+    show_scenarios
+    show_available_tools
+    puts ''
+  end
+
+  def show_basic_info
+    puts "🤖 Starting chat with #{@assistant.name}"
+    puts "🏢 Account: #{@assistant.account.name}"
+    puts "🆔 Assistant ID: #{@assistant.id}"
+  end
+
+  def show_scenarios
+    scenarios = @assistant.scenarios.enabled
+    if scenarios.any?
+      puts "⚡ Enabled Scenarios (#{scenarios.count}):"
+      scenarios.each { |scenario| display_scenario(scenario) }
+    else
+      puts '⚡ No scenarios enabled'
+    end
+  end
+
+  def display_scenario(scenario)
+    tools_count = scenario.tools&.length || 0
+    puts "   • #{scenario.title} (#{tools_count} tools)"
+    return if scenario.description.blank?
+
+    description = truncate_description(scenario.description)
+    puts "     #{description}"
+  end
+
+  def truncate_description(description)
+    description.length > 60 ? "#{description[0..60]}..." : description
+  end
+
+  def show_available_tools
+    available_tools = @assistant.available_tool_ids
+    if available_tools.any?
+      puts "🔧 Available Tools (#{available_tools.count}): #{available_tools.join(', ')}"
+    else
+      puts '🔧 No tools available'
+    end
+  end
+
+  def process_user_message(user_input)
+    add_to_history('user', user_input)
+
+    begin
+      print "🤖 #{@assistant.name}: "
+      @current_system_messages = []
+
+      result = generate_assistant_response
+      display_response(result)
+    rescue StandardError => e
+      handle_error(e)
+    end
+  end
+
+  def generate_assistant_response
+    runner = Captain::Assistant::AgentRunnerService.new(assistant: @assistant, callbacks: build_callbacks)
+    runner.generate_response(message_history: @message_history)
+  end
+
+  def build_callbacks
+    {
+      on_agent_thinking: method(:handle_agent_thinking),
+      on_tool_start: method(:handle_tool_start),
+      on_tool_complete: method(:handle_tool_complete),
+      on_agent_handoff: method(:handle_agent_handoff)
+    }
+  end
+
+  def handle_agent_thinking(agent, _input)
+    agent_name = extract_name(agent)
+    @current_system_messages << "#{agent_name} is thinking..."
+    add_to_history('system', "#{agent_name} is thinking...")
+  end
+
+  def handle_tool_start(tool, _args)
+    tool_name = extract_tool_name(tool)
+    @current_system_messages << "Using tool: #{tool_name}"
+    add_to_history('system', "Using tool: #{tool_name}")
+  end
+
+  def handle_tool_complete(tool, _result)
+    tool_name = extract_tool_name(tool)
+    @current_system_messages << "Tool #{tool_name} completed"
+    add_to_history('system', "Tool #{tool_name} completed")
+  end
+
+  def handle_agent_handoff(from, to, reason)
+    @current_system_messages << "Handoff: #{extract_name(from)} → #{extract_name(to)} (#{reason})"
+    add_to_history('system', "Agent handoff: #{extract_name(from)} → #{extract_name(to)} (#{reason})")
+  end
+
+  def display_response(result)
+    response_text = result['response'] || 'No response generated'
+    reasoning = result['reasoning']
+
+    puts dim_text("\n#{@current_system_messages.join("\n")}") if @current_system_messages.any?
+    puts response_text
+    puts dim_italic_text("(Reasoning: #{reasoning})") if reasoning && reasoning != 'Processed by agent'
+
+    add_to_history('assistant', response_text, reasoning: reasoning)
+  end
+
+  def handle_error(error)
+    error_msg = "Error: #{error.message}"
+    puts "❌ #{error_msg}"
+    add_to_history('system', error_msg)
+  end
+
+  def add_to_history(role, content, agent_name: nil, reasoning: nil)
+    message = {
+      role: role,
+      content: content,
+      timestamp: Time.current,
+      agent_name: agent_name || (role == 'assistant' ? @assistant.name : nil)
+    }
+    message[:reasoning] = reasoning if reasoning
+
+    @message_history << message
+  end
+
+  def clear_history
+    @message_history.clear
+    puts 'Message history cleared'
+  end
+
+  def dim_text(text)
+    # ANSI escape code for very dim gray text (bright black/dark gray)
+    "\e[90m#{text}\e[0m"
+  end
+
+  def dim_italic_text(text)
+    # ANSI escape codes for dim gray + italic text
+    "\e[90m\e[3m#{text}\e[0m"
+  end
+
+  def extract_tool_name(tool)
+    return tool if tool.is_a?(String)
+
+    tool.class.name.split('::').last.gsub('Tool', '')
+  rescue StandardError
+    tool.to_s
+  end
+
+  def extract_name(obj)
+    obj.respond_to?(:name) ? obj.name : obj.to_s
+  end
+end

research/chatwoot/lib/tasks/companies.rake

@@ -0,0 +1,12 @@
+namespace :companies do
+  desc 'Backfill companies from existing contact email domains'
+  task backfill: :environment do
+    puts 'Starting company backfill migration...'
+    puts 'This will process all accounts and create companies from contact email domains.'
+    puts 'The job will run in the background via Sidekiq'
+    puts ''
+    Migration::CompanyBackfillJob.perform_later
+    puts 'Company backfill job has been enqueued.'
+    puts 'Monitor progress in logs or Sidekiq dashboard.'
+  end
+end

research/chatwoot/lib/tasks/db_enhancements.rake

@@ -0,0 +1,31 @@
+# We are hooking config loader to run automatically everytime migration is executed
+Rake::Task['db:migrate'].enhance do
+  if ActiveRecord::Base.connection.table_exists? 'installation_configs'
+    puts 'Loading Installation config'
+    ConfigLoader.new.process
+  end
+end
+
+# we are creating a custom database prepare task
+# the default rake db:prepare task isn't ideal for environments like heroku
+# In heroku the database is already created before the first run of db:prepare
+# In this case rake db:prepare tries to run db:migrate from all the way back from the beginning
+# Since the assumption is migrations are only run after schema load from a point x, this could lead to things breaking.
+# ref: https://github.com/rails/rails/blob/main/activerecord/lib/active_record/railties/databases.rake#L356
+db_namespace = namespace :db do
+  desc 'Runs setup if database does not exist, or runs migrations if it does'
+  task chatwoot_prepare: :load_config do
+    ActiveRecord::Base.configurations.configs_for(env_name: Rails.env).each do |db_config|
+      ActiveRecord::Base.establish_connection(db_config.configuration_hash)
+      unless ActiveRecord::Base.connection.table_exists? 'ar_internal_metadata'
+        db_namespace['load_config'].invoke if ActiveRecord.schema_format == :ruby
+        ActiveRecord::Tasks::DatabaseTasks.load_schema_current(:ruby, ENV.fetch('SCHEMA', nil))
+        db_namespace['seed'].invoke
+      end
+
+      db_namespace['migrate'].invoke
+    rescue ActiveRecord::NoDatabaseError
+      db_namespace['setup'].invoke
+    end
+  end
+end

research/chatwoot/lib/tasks/dev/variant_toggle.rake

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+# rubocop:disable Metrics/BlockLength
+namespace :chatwoot do
+  namespace :dev do
+    desc 'Toggle between Chatwoot variants with interactive menu'
+    task toggle_variant: :environment do
+      # Only allow in development environment
+      return unless Rails.env.development?
+
+      show_current_variant
+      show_variant_menu
+      handle_user_selection
+    end
+
+    desc 'Show current Chatwoot variant status'
+    task show_variant: :environment do
+      return unless Rails.env.development?
+
+      show_current_variant
+    end
+
+    private
+
+    def show_current_variant
+      puts "\n#{('=' * 50)}"
+      puts '🚀 CHATWOOT VARIANT MANAGER'
+      puts '=' * 50
+
+      # Check InstallationConfig
+      deployment_env = InstallationConfig.find_by(name: 'DEPLOYMENT_ENV')&.value
+      pricing_plan = InstallationConfig.find_by(name: 'INSTALLATION_PRICING_PLAN')&.value
+
+      # Determine current variant based on configs
+      current_variant = if deployment_env == 'cloud'
+                          'Cloud'
+                        elsif pricing_plan == 'enterprise'
+                          'Enterprise'
+                        else
+                          'Community'
+                        end
+
+      puts "📊 Current Variant: #{current_variant}"
+      puts "   Deployment Environment: #{deployment_env || 'Not set'}"
+      puts "   Pricing Plan: #{pricing_plan || 'community'}"
+      puts ''
+    end
+
+    def show_variant_menu
+      puts '🎯 Select a variant to switch to:'
+      puts ''
+      puts '1. 🆓 Community   (Free version with basic features)'
+      puts '2. 🏢 Enterprise  (Self-hosted with premium features)'
+      puts '3. 🌥️  Cloud       (Cloud deployment with premium features)'
+      puts ''
+      puts '0. ❌ Cancel'
+      puts ''
+      print 'Enter your choice (0-3): '
+    end
+
+    def handle_user_selection
+      choice = $stdin.gets.chomp
+
+      case choice
+      when '1'
+        switch_to_variant('Community') { configure_community_variant }
+      when '2'
+        switch_to_variant('Enterprise') { configure_enterprise_variant }
+      when '3'
+        switch_to_variant('Cloud') { configure_cloud_variant }
+      when '0'
+        cancel_operation
+      else
+        invalid_choice
+      end
+
+      puts "\n🎉 Changes applied successfully! No restart required."
+    end
+
+    def switch_to_variant(variant_name)
+      puts "\n🔄 Switching to #{variant_name} variant..."
+      yield
+      clear_cache
+      puts "✅ Successfully switched to #{variant_name} variant!"
+    end
+
+    def cancel_operation
+      puts "\n❌ Cancelled. No changes made."
+      exit 0
+    end
+
+    def invalid_choice
+      puts "\n❌ Invalid choice. Please select 0-3."
+      puts 'No changes made.'
+      exit 1
+    end
+
+    def configure_community_variant
+      update_installation_config('DEPLOYMENT_ENV', 'self-hosted')
+      update_installation_config('INSTALLATION_PRICING_PLAN', 'community')
+    end
+
+    def configure_enterprise_variant
+      update_installation_config('DEPLOYMENT_ENV', 'self-hosted')
+      update_installation_config('INSTALLATION_PRICING_PLAN', 'enterprise')
+    end
+
+    def configure_cloud_variant
+      update_installation_config('DEPLOYMENT_ENV', 'cloud')
+      update_installation_config('INSTALLATION_PRICING_PLAN', 'enterprise')
+    end
+
+    def update_installation_config(name, value)
+      config = InstallationConfig.find_or_initialize_by(name: name)
+      config.value = value
+      config.save!
+      puts "   💾 Updated #{name} → #{value}"
+    end
+
+    def clear_cache
+      GlobalConfig.clear_cache
+      puts '   🗑️  Cleared configuration cache'
+    end
+  end
+end
+# rubocop:enable Metrics/BlockLength

research/chatwoot/lib/tasks/download_report.rake

@@ -0,0 +1,183 @@
+# Download Report Rake Tasks
+#
+# Usage:
+#   POSTGRES_STATEMENT_TIMEOUT=600s NEW_RELIC_AGENT_ENABLED=false bundle exec rake download_report:agent
+#   POSTGRES_STATEMENT_TIMEOUT=600s NEW_RELIC_AGENT_ENABLED=false bundle exec rake download_report:inbox
+#   POSTGRES_STATEMENT_TIMEOUT=600s NEW_RELIC_AGENT_ENABLED=false bundle exec rake download_report:label
+#
+# The task will prompt for:
+#   - Account ID
+#   - Start Date (YYYY-MM-DD)
+#   - End Date (YYYY-MM-DD)
+#   - Timezone Offset (e.g., 0, 5.5, -5)
+#   - Business Hours (y/n) - whether to use business hours for time metrics
+#
+# Output: <account_id>_<type>_<start_date>_<end_date>.csv
+
+require 'csv'
+
+# rubocop:disable Metrics/CyclomaticComplexity
+# rubocop:disable Metrics/AbcSize
+# rubocop:disable Metrics/MethodLength
+# rubocop:disable Metrics/ModuleLength
+module DownloadReportTasks
+  def self.prompt(message)
+    print "#{message}: "
+    $stdin.gets.chomp
+  end
+
+  def self.collect_params
+    account_id = prompt('Enter Account ID')
+    abort 'Error: Account ID is required' if account_id.blank?
+
+    account = Account.find_by(id: account_id)
+    abort "Error: Account with ID '#{account_id}' not found" unless account
+
+    start_date = prompt('Enter Start Date (YYYY-MM-DD)')
+    abort 'Error: Start date is required' if start_date.blank?
+
+    end_date = prompt('Enter End Date (YYYY-MM-DD)')
+    abort 'Error: End date is required' if end_date.blank?
+
+    timezone_offset = prompt('Enter Timezone Offset (e.g., 0, 5.5, -5)')
+    timezone_offset = timezone_offset.blank? ? 0 : timezone_offset.to_f
+
+    business_hours = prompt('Use Business Hours? (y/n)')
+    business_hours = business_hours.downcase == 'y'
+
+    begin
+      tz = ActiveSupport::TimeZone[timezone_offset]
+      abort "Error: Invalid timezone offset '#{timezone_offset}'" unless tz
+
+      since = tz.parse("#{start_date} 00:00:00").to_i.to_s
+      until_date = tz.parse("#{end_date} 23:59:59").to_i.to_s
+    rescue StandardError => e
+      abort "Error parsing dates: #{e.message}"
+    end
+
+    {
+      account: account,
+      params: { since: since, until: until_date, timezone_offset: timezone_offset, business_hours: business_hours },
+      start_date: start_date,
+      end_date: end_date
+    }
+  end
+
+  def self.save_csv(filename, headers, rows)
+    CSV.open(filename, 'w') do |csv|
+      csv << headers
+      rows.each { |row| csv << row }
+    end
+    puts "Report saved to: #{filename}"
+  end
+
+  def self.format_time(seconds)
+    return '' if seconds.nil? || seconds.zero?
+
+    seconds.round(2)
+  end
+
+  def self.download_agent_report
+    data = collect_params
+    account = data[:account]
+
+    puts "\nGenerating agent report..."
+    builder = V2::Reports::AgentSummaryBuilder.new(account: account, params: data[:params])
+    report = builder.build
+
+    users = account.users.index_by(&:id)
+    headers = %w[id name email conversations_count resolved_conversations_count avg_resolution_time avg_first_response_time avg_reply_time]
+
+    rows = report.map do |row|
+      user = users[row[:id]]
+      [
+        row[:id],
+        user&.name || 'Unknown',
+        user&.email || 'Unknown',
+        row[:conversations_count],
+        row[:resolved_conversations_count],
+        format_time(row[:avg_resolution_time]),
+        format_time(row[:avg_first_response_time]),
+        format_time(row[:avg_reply_time])
+      ]
+    end
+
+    filename = "#{account.id}_agent_#{data[:start_date]}_#{data[:end_date]}.csv"
+    save_csv(filename, headers, rows)
+  end
+
+  def self.download_inbox_report
+    data = collect_params
+    account = data[:account]
+
+    puts "\nGenerating inbox report..."
+    builder = V2::Reports::InboxSummaryBuilder.new(account: account, params: data[:params])
+    report = builder.build
+
+    inboxes = account.inboxes.index_by(&:id)
+    headers = %w[id name conversations_count resolved_conversations_count avg_resolution_time avg_first_response_time avg_reply_time]
+
+    rows = report.map do |row|
+      inbox = inboxes[row[:id]]
+      [
+        row[:id],
+        inbox&.name || 'Unknown',
+        row[:conversations_count],
+        row[:resolved_conversations_count],
+        format_time(row[:avg_resolution_time]),
+        format_time(row[:avg_first_response_time]),
+        format_time(row[:avg_reply_time])
+      ]
+    end
+
+    filename = "#{account.id}_inbox_#{data[:start_date]}_#{data[:end_date]}.csv"
+    save_csv(filename, headers, rows)
+  end
+
+  def self.download_label_report
+    data = collect_params
+    account = data[:account]
+
+    puts "\nGenerating label report..."
+    builder = V2::Reports::LabelSummaryBuilder.new(account: account, params: data[:params])
+    report = builder.build
+
+    headers = %w[id name conversations_count resolved_conversations_count avg_resolution_time avg_first_response_time avg_reply_time]
+
+    rows = report.map do |row|
+      [
+        row[:id],
+        row[:name],
+        row[:conversations_count],
+        row[:resolved_conversations_count],
+        format_time(row[:avg_resolution_time]),
+        format_time(row[:avg_first_response_time]),
+        format_time(row[:avg_reply_time])
+      ]
+    end
+
+    filename = "#{account.id}_label_#{data[:start_date]}_#{data[:end_date]}.csv"
+    save_csv(filename, headers, rows)
+  end
+end
+# rubocop:enable Metrics/CyclomaticComplexity
+# rubocop:enable Metrics/AbcSize
+# rubocop:enable Metrics/MethodLength
+# rubocop:enable Metrics/ModuleLength
+
+namespace :download_report do
+  desc 'Download agent summary report as CSV'
+  task agent: :environment do
+    DownloadReportTasks.download_agent_report
+  end
+
+  desc 'Download inbox summary report as CSV'
+  task inbox: :environment do
+    DownloadReportTasks.download_inbox_report
+  end
+
+  desc 'Download label summary report as CSV'
+  task label: :environment do
+    DownloadReportTasks.download_label_report
+  end
+end

research/chatwoot/lib/tasks/generate_test_data.rake

@@ -0,0 +1,30 @@
+require_relative '../test_data'
+
+namespace :data do
+  desc 'Generate large, distributed test data'
+  task generate_distributed_data: :environment do
+    if Rails.env.production?
+      puts 'Generating large amounts of data in production can have serious performance implications.'
+      puts 'Exiting to avoid impacting a live environment.'
+      exit
+    end
+
+    # Configure logger
+    Rails.logger = ActiveSupport::Logger.new($stdout)
+    Rails.logger.formatter = proc do |severity, datetime, _progname, msg|
+      "#{datetime.strftime('%Y-%m-%d %H:%M:%S.%L')} #{severity}: #{msg}\n"
+    end
+
+    begin
+      TestData::DatabaseOptimizer.setup
+      TestData.generate
+    ensure
+      TestData::DatabaseOptimizer.restore
+    end
+  end
+
+  desc 'Clean up existing test data'
+  task cleanup_test_data: :environment do
+    TestData.cleanup
+  end
+end

research/chatwoot/lib/tasks/instance_id.rake

@@ -0,0 +1,8 @@
+namespace :instance_id do
+  desc 'Get the installation identifier'
+  task :get_installation_identifier => :environment do
+    identifier = InstallationConfig.find_by(name: 'INSTALLATION_IDENTIFIER')&.value
+    identifier ||= InstallationConfig.create!(name: 'INSTALLATION_IDENTIFIER', value: SecureRandom.uuid).value
+    puts identifier
+  end
+end

research/chatwoot/lib/tasks/ip_lookup.rake

@@ -0,0 +1,7 @@
+require 'rubygems/package'
+
+namespace :ip_lookup do
+  task setup: :environment do
+    Geocoder::SetupService.new.perform
+  end
+end

research/chatwoot/lib/tasks/mfa.rake

@@ -0,0 +1,65 @@
+module MfaTasks
+  def self.find_user_or_exit(email)
+    abort 'Error: Please provide an email address' if email.blank?
+    user = User.from_email(email)
+    abort "Error: User with email '#{email}' not found" unless user
+    user
+  end
+
+  def self.reset_user_mfa(user)
+    user.update!(
+      otp_required_for_login: false,
+      otp_secret: nil,
+      otp_backup_codes: nil
+    )
+  end
+
+  def self.reset_single(args)
+    user = find_user_or_exit(args[:email])
+    abort "MFA is already disabled for #{args[:email]}" if !user.otp_required_for_login? && user.otp_secret.nil?
+    reset_user_mfa(user)
+    puts "✓ MFA has been successfully reset for #{args[:email]}"
+  rescue StandardError => e
+    abort "Error resetting MFA: #{e.message}"
+  end
+
+  def self.reset_all
+    print 'Are you sure you want to reset MFA for ALL users? This cannot be undone! (yes/no): '
+    abort 'Operation cancelled' unless $stdin.gets.chomp.downcase == 'yes'
+
+    affected_users = User.where(otp_required_for_login: true).or(User.where.not(otp_secret: nil))
+    count = affected_users.count
+    abort 'No users have MFA enabled' if count.zero?
+
+    puts "\nResetting MFA for #{count} user(s)..."
+    affected_users.find_each { |user| reset_user_mfa(user) }
+    puts "✓ MFA has been reset for #{count} user(s)"
+  end
+
+  def self.generate_backup_codes(args)
+    user = find_user_or_exit(args[:email])
+    abort "Error: MFA is not enabled for #{args[:email]}" unless user.otp_required_for_login?
+
+    service = Mfa::ManagementService.new(user: user)
+    codes = service.generate_backup_codes!
+    puts "\nNew backup codes generated for #{args[:email]}:"
+    codes.each { |code| puts code }
+  end
+end
+
+namespace :mfa do
+  desc 'Reset MFA for a specific user by email'
+  task :reset, [:email] => :environment do |_task, args|
+    MfaTasks.reset_single(args)
+  end
+
+  desc 'Reset MFA for all users in the system'
+  task reset_all: :environment do
+    MfaTasks.reset_all
+  end
+
+  desc 'Generate new backup codes for a user'
+  task :generate_backup_codes, [:email] => :environment do |_task, args|
+    MfaTasks.generate_backup_codes(args)
+  end
+end

research/chatwoot/lib/tasks/ops/cleanup_orphan_conversations.rake

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+# Run with:
+#   bundle exec rake chatwoot:ops:cleanup_orphan_conversations
+
+namespace :chatwoot do
+  namespace :ops do
+    desc 'Identify and delete conversations without a valid contact or inbox in a timeframe'
+    task cleanup_orphan_conversations: :environment do
+      print 'Enter Account ID: '
+      account_id = $stdin.gets.to_i
+      account = Account.find(account_id)
+
+      print 'Enter timeframe in days (default: 7): '
+      days_input = $stdin.gets.strip
+      days = days_input.empty? ? 7 : days_input.to_i
+
+      service = Internal::RemoveOrphanConversationsService.new(account: account, days: days)
+
+      # Preview count using the same query logic
+      base = account
+             .conversations
+             .where('conversations.created_at > ?', days.days.ago)
+             .left_outer_joins(:contact, :inbox)
+      conversations = base.where(contacts: { id: nil }).or(base.where(inboxes: { id: nil }))
+
+      count = conversations.count
+      puts "Found #{count} conversations without a valid contact or inbox."
+
+      if count.positive?
+        print 'Do you want to delete these conversations? (y/N): '
+        confirm = $stdin.gets.strip.downcase
+        if %w[y yes].include?(confirm)
+          total_deleted = service.perform
+          puts "#{total_deleted} conversations deleted."
+        else
+          puts 'No conversations were deleted.'
+        end
+      end
+    end
+  end
+end

research/chatwoot/lib/tasks/search_test_data.rake

@@ -0,0 +1,183 @@
+# rubocop:disable Metrics/BlockLength
+namespace :search do
+  desc 'Create test messages for advanced search manual testing across multiple inboxes'
+  task setup_test_data: :environment do
+    puts '🔍 Setting up test data for advanced search...'
+
+    account = Account.first
+    unless account
+      puts '❌ No account found. Please create an account first.'
+      exit 1
+    end
+
+    agents = account.users.to_a
+    unless agents.any?
+      puts '❌ No agents found. Please create users first.'
+      exit 1
+    end
+
+    puts "✅ Using account: #{account.name} (ID: #{account.id})"
+    puts "✅ Found #{agents.count} agent(s)"
+
+    # Create missing inbox types for comprehensive testing
+    puts "\n📥 Checking and creating inboxes..."
+
+    # API inbox
+    unless account.inboxes.exists?(channel_type: 'Channel::Api')
+      puts '  Creating API inbox...'
+      account.inboxes.create!(
+        name: 'Search Test API',
+        channel: Channel::Api.create!(account: account)
+      )
+    end
+
+    # Web Widget inbox
+    unless account.inboxes.exists?(channel_type: 'Channel::WebWidget')
+      puts '  Creating WebWidget inbox...'
+      account.inboxes.create!(
+        name: 'Search Test WebWidget',
+        channel: Channel::WebWidget.create!(account: account, website_url: 'https://example.com')
+      )
+    end
+
+    # Email inbox
+    unless account.inboxes.exists?(channel_type: 'Channel::Email')
+      puts '  Creating Email inbox...'
+      account.inboxes.create!(
+        name: 'Search Test Email',
+        channel: Channel::Email.create!(
+          account: account,
+          email: 'search-test@example.com',
+          imap_enabled: false,
+          smtp_enabled: false
+        )
+      )
+    end
+
+    inboxes = account.inboxes.to_a
+    puts "✅ Using #{inboxes.count} inbox(es):"
+    inboxes.each { |i| puts "   - #{i.name} (ID: #{i.id}, Type: #{i.channel_type})" }
+
+    # Create 10 test contacts
+    contacts = []
+    10.times do |i|
+      contacts << account.contacts.find_or_create_by!(
+        email: "test-customer-#{i}@example.com"
+      ) do |c|
+        c.name = Faker::Name.name
+      end
+    end
+    puts "✅ Created/found #{contacts.count} test contacts"
+
+    target_messages = 50_000
+    messages_per_conversation = 100
+    total_conversations = target_messages / messages_per_conversation
+
+    puts "\n📝 Creating #{target_messages} messages across #{total_conversations} conversations..."
+    puts "   Distribution: #{inboxes.count} inboxes × #{total_conversations / inboxes.count} conversations each"
+
+    start_time = 2.years.ago
+    end_time = Time.current
+    time_range = end_time - start_time
+
+    created_count = 0
+    failed_count = 0
+    conversations_per_inbox = total_conversations / inboxes.count
+    conversation_statuses = [:open, :resolved]
+
+    inboxes.each do |inbox|
+      conversations_per_inbox.times do
+        # Pick random contact and agent for this conversation
+        contact = contacts.sample
+        agent = agents.sample
+
+        # Create or find ContactInbox
+        contact_inbox = ContactInbox.find_or_create_by!(
+          contact: contact,
+          inbox: inbox
+        ) do |ci|
+          ci.source_id = "test_#{SecureRandom.hex(8)}"
+        end
+
+        # Create conversation
+        conversation = inbox.conversations.create!(
+          account: account,
+          contact: contact,
+          inbox: inbox,
+          contact_inbox: contact_inbox,
+          status: conversation_statuses.sample
+        )
+
+        # Create messages for this conversation (50 incoming, 50 outgoing)
+        50.times do
+          random_time = start_time + (rand * time_range)
+
+          # Incoming message from contact
+          begin
+            Message.create!(
+              content: Faker::Movie.quote,
+              account: account,
+              inbox: inbox,
+              conversation: conversation,
+              message_type: :incoming,
+              sender: contact,
+              created_at: random_time,
+              updated_at: random_time
+            )
+            created_count += 1
+          rescue StandardError => e
+            failed_count += 1
+            puts "❌ Failed to create message: #{e.message}" if failed_count <= 5
+          end
+
+          # Outgoing message from agent
+          begin
+            Message.create!(
+              content: Faker::Movie.quote,
+              account: account,
+              inbox: inbox,
+              conversation: conversation,
+              message_type: :outgoing,
+              sender: agent,
+              created_at: random_time + rand(60..600),
+              updated_at: random_time + rand(60..600)
+            )
+            created_count += 1
+          rescue StandardError => e
+            failed_count += 1
+            puts "❌ Failed to create message: #{e.message}" if failed_count <= 5
+          end
+
+          print "\r🔄 Progress: #{created_count}/#{target_messages} messages created..." if (created_count % 500).zero?
+        end
+      end
+    end
+
+    puts "\n\n✅ Successfully created #{created_count} messages!"
+    puts "❌ Failed: #{failed_count}" if failed_count.positive?
+
+    puts "\n📊 Summary:"
+    puts "  - Total messages: #{Message.where(account: account).count}"
+    puts "  - Total conversations: #{Conversation.where(account: account).count}"
+
+    min_date = Message.where(account: account).minimum(:created_at)&.strftime('%Y-%m-%d')
+    max_date = Message.where(account: account).maximum(:created_at)&.strftime('%Y-%m-%d')
+    puts "  - Date range: #{min_date} to #{max_date}"
+    puts "\nBreakdown by inbox:"
+    inboxes.each do |inbox|
+      msg_count = Message.where(inbox: inbox).count
+      conv_count = Conversation.where(inbox: inbox).count
+      puts "  - #{inbox.name} (#{inbox.channel_type}): #{msg_count} messages, #{conv_count} conversations"
+    end
+    puts "\nBreakdown by sender type:"
+    puts "  - Incoming (from contacts): #{Message.where(account: account, message_type: :incoming).count}"
+    puts "  - Outgoing (from agents): #{Message.where(account: account, message_type: :outgoing).count}"
+
+    puts "\n🔧 Next steps:"
+    puts '  1. Ensure OpenSearch is running: mise elasticsearch-start'
+    puts '  2. Reindex messages: rails runner "Message.search_index.import Message.all"'
+    puts "  3. Enable feature: rails runner \"Account.find(#{account.id}).enable_features('advanced_search')\""
+    puts "\n💡 Then test the search with filters via API or Rails console!"
+  end
+end
+# rubocop:enable Metrics/BlockLength

research/chatwoot/lib/tasks/seed_reports_data.rake

@@ -0,0 +1,24 @@
+namespace :db do
+  namespace :seed do
+    desc 'Seed test data for reports with conversations, contacts, agents, teams, and realistic reporting events'
+    task reports_data: :environment do
+      if ENV['ACCOUNT_ID'].blank?
+        puts 'Please provide an ACCOUNT_ID environment variable'
+        puts 'Usage: ACCOUNT_ID=1 ENABLE_ACCOUNT_SEEDING=true bundle exec rake db:seed:reports_data'
+        exit 1
+      end
+
+      ENV['ENABLE_ACCOUNT_SEEDING'] = 'true' if ENV['ENABLE_ACCOUNT_SEEDING'].blank?
+
+      account_id = ENV.fetch('ACCOUNT_ID', nil)
+      account = Account.find(account_id)
+
+      puts "Starting reports data seeding for account: #{account.name} (ID: #{account.id})"
+
+      seeder = Seeders::Reports::ReportDataSeeder.new(account: account)
+      seeder.perform!
+
+      puts "Finished seeding reports data for account: #{account.name}"
+    end
+  end
+end

research/chatwoot/lib/tasks/sidekiq_tasks.rake

@@ -0,0 +1,17 @@
+namespace :sidekiq do
+  desc "Clear ActionCableJobs from sidekiq's critical queue"
+  task clear_action_cable_broadcast_jobs: :environment do
+    queue_name = 'critical'
+    queue = Sidekiq::Queue.new(queue_name)
+    jobs_cleared = 0
+
+    queue.each do |job|
+      if job['wrapped'] == 'ActionCableBroadcastJob'
+        job.delete
+        jobs_cleared += 1
+      end
+    end
+
+    puts "Cleared #{jobs_cleared} ActionCableBroadcastJob(s) from the #{queue_name} queue."
+  end
+end

research/chatwoot/lib/tasks/swagger.rake

@@ -0,0 +1,156 @@
+require 'json_refs'
+require 'fileutils'
+require 'pathname'
+require 'yaml'
+require 'json'
+
+module SwaggerTaskActions
+  def self.execute_build
+    swagger_dir = Rails.root.join('swagger')
+    # Paths relative to swagger_dir for use within Dir.chdir
+    index_yml_relative_path = 'index.yml'
+    swagger_json_relative_path = 'swagger.json'
+
+    Dir.chdir(swagger_dir) do
+      # Operations within this block are relative to swagger_dir
+      swagger_index_content = File.read(index_yml_relative_path)
+      swagger_index = YAML.safe_load(swagger_index_content)
+
+      final_build = JsonRefs.call(
+        swagger_index,
+        resolve_local_ref: false,
+        resolve_file_ref: true, # Uses CWD (swagger_dir) for resolving file refs
+        logging: true
+      )
+      File.write(swagger_json_relative_path, JSON.pretty_generate(final_build))
+
+      # For user messages, provide the absolute path
+      absolute_swagger_json_path = swagger_dir.join(swagger_json_relative_path)
+      puts 'Swagger build was successful.'
+      puts "Generated #{absolute_swagger_json_path}"
+      puts 'Go to http://localhost:3000/swagger see the changes.'
+
+      # Trigger dependent task
+      Rake::Task['swagger:build_tag_groups'].invoke
+    end
+  end
+
+  def self.execute_build_tag_groups
+    base_swagger_path = Rails.root.join('swagger')
+    tag_groups_output_dir = base_swagger_path.join('tag_groups')
+    full_spec_path = base_swagger_path.join('swagger.json')
+    index_yml_path = base_swagger_path.join('index.yml')
+
+    full_spec = JSON.parse(File.read(full_spec_path))
+    swagger_index = YAML.safe_load(File.read(index_yml_path))
+    tag_groups = swagger_index['x-tagGroups']
+
+    FileUtils.mkdir_p(tag_groups_output_dir)
+
+    tag_groups.each do |tag_group|
+      _process_tag_group(tag_group, full_spec, tag_groups_output_dir)
+    end
+
+    puts 'Tag-specific swagger files generated successfully.'
+  end
+
+  def self.execute_build_for_docs
+    Rake::Task['swagger:build'].invoke # Ensure all swagger files are built first
+
+    developer_docs_public_path = Rails.root.join('developer-docs/public')
+    tag_groups_in_dev_docs_path = developer_docs_public_path.join('swagger/tag_groups')
+    source_tag_groups_path = Rails.root.join('swagger/tag_groups')
+
+    FileUtils.mkdir_p(tag_groups_in_dev_docs_path)
+    puts 'Creating symlinks for developer-docs...'
+
+    symlink_files = %w[platform_swagger.json application_swagger.json client_swagger.json other_swagger.json]
+    symlink_files.each do |file|
+      _create_symlink(source_tag_groups_path.join(file), tag_groups_in_dev_docs_path.join(file))
+    end
+
+    puts 'Symlinks created successfully.'
+    puts 'You can now run the Mintlify dev server to preview the documentation.'
+  end
+
+  # Private helper methods
+  class << self
+    private
+
+    def _process_tag_group(tag_group, full_spec, output_dir)
+      group_name = tag_group['name']
+      tags_in_current_group = tag_group['tags']
+
+      tag_spec = JSON.parse(JSON.generate(full_spec)) # Deep clone
+
+      tag_spec['paths'] = _filter_paths_for_tag_group(tag_spec['paths'], tags_in_current_group)
+      tag_spec['tags'] = _filter_tags_for_tag_group(tag_spec['tags'], tags_in_current_group)
+
+      output_filename = _determine_output_filename(group_name)
+      File.write(output_dir.join(output_filename), JSON.pretty_generate(tag_spec))
+    end
+
+    def _operation_has_matching_tags?(operation, tags_in_group)
+      return false unless operation.is_a?(Hash)
+
+      operation_tags = operation['tags']
+      return false unless operation_tags.is_a?(Array)
+
+      operation_tags.intersect?(tags_in_group)
+    end
+
+    def _filter_paths_for_tag_group(paths_spec, tags_in_group)
+      (paths_spec || {}).filter_map do |path, path_item|
+        next unless path_item.is_a?(Hash)
+
+        operations_with_group_tags = path_item.any? do |_method, operation|
+          _operation_has_matching_tags?(operation, tags_in_group)
+        end
+        [path, path_item] if operations_with_group_tags
+      end.to_h
+    end
+
+    def _filter_tags_for_tag_group(tags_spec, tags_in_group)
+      if tags_spec.is_a?(Array)
+        tags_spec.select { |tag_definition| tags_in_group.include?(tag_definition['name']) }
+      else
+        []
+      end
+    end
+
+    def _determine_output_filename(group_name)
+      return 'other_swagger.json' if group_name.casecmp('others').zero?
+
+      sanitized_group_name = group_name.downcase.tr(' ', '_').gsub(/[^a-z0-9_]+/, '')
+      "#{sanitized_group_name}_swagger.json"
+    end
+
+    def _create_symlink(source_file_path, target_file_path)
+      FileUtils.rm_f(target_file_path) # Remove existing to avoid errors
+
+      if File.exist?(source_file_path)
+        relative_source_path = Pathname.new(source_file_path).relative_path_from(target_file_path.dirname)
+        FileUtils.ln_sf(relative_source_path, target_file_path)
+      else
+        puts "Warning: Source file #{source_file_path} not found. Skipping symlink for #{File.basename(target_file_path)}."
+      end
+    end
+  end
+end
+
+namespace :swagger do
+  desc 'build combined swagger.json file from all the fragmented definitions and paths inside swagger folder'
+  task build: :environment do
+    SwaggerTaskActions.execute_build
+  end
+
+  desc 'build separate swagger files for each tag group'
+  task build_tag_groups: :environment do
+    SwaggerTaskActions.execute_build_tag_groups
+  end
+
+  desc 'build swagger files and create symlinks in developer-docs'
+  task build_for_docs: :environment do
+    SwaggerTaskActions.execute_build_for_docs
+  end
+end