feat: add ai intelligence module

Author: Bulletdev

Gemfile

@@ -84,6 +84,9 @@ gem 'meilisearch', '~> 0.33'
 # LLM Integration for Support Chatbot
 gem 'ruby-openai', '~> 7.0'
 
+# Linear algebra for AI draft analysis
+gem 'numo-narray', '~> 0.9'
+
 # Structured JSON logging (12-Factor XI)
 gem 'lograge'
 
@@ -114,6 +117,7 @@ end
 
 group :test do
   gem 'database_cleaner-active_record'
+  gem 'pundit-matchers'
   gem 'shoulda-matchers'
   gem 'simplecov', require: false
   gem 'vcr'

Gemfile.lock

@@ -238,6 +238,7 @@ GEM
     nio4r (2.7.4)
     nokogiri (1.19.1-x86_64-linux-gnu)
       racc (~> 1.4)
+    numo-narray (0.9.2.1)
     ostruct (0.6.3)
     parallel (1.27.0)
     parser (3.3.9.0)
@@ -256,6 +257,11 @@ GEM
       nio4r (~> 2.0)
     pundit (2.5.2)
       activesupport (>= 3.0.0)
+    pundit-matchers (4.0.0)
+      rspec-core (~> 3.12)
+      rspec-expectations (~> 3.12)
+      rspec-mocks (~> 3.12)
+      rspec-support (~> 3.12)
     raabro (1.4.0)
     racc (1.8.1)
     rack (3.1.20)
@@ -450,9 +456,11 @@ DEPENDENCIES
   kaminari
   lograge
   meilisearch (~> 0.33)
+  numo-narray (~> 0.9)
   pg (~> 1.1)
   puma (~> 6.0)
   pundit
+  pundit-matchers
   rack (~> 3.1.20)
   rack-attack
   rack-cors

app/modules/ai_intelligence/channels/draft_channel.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# WebSocket channel for real-time draft analysis.
+# Frontend connects with: { channel: 'DraftChannel', draft_id: '<id>' }
+# Authentication is handled by ApplicationCable::Connection (JWT via ?token= query param).
+class DraftChannel < ApplicationCable::Channel
+  def subscribed
+    draft_id = params[:draft_id]
+    reject and return if draft_id.blank?
+
+    stream_from "draft_#{draft_id}"
+  end
+
+  def unsubscribed
+    stop_all_streams
+  end
+
+  # Client sends: { team_a: [...], team_b: [...] }
+  def picks_updated(data)
+    team_a = data['team_a'].presence || []
+    team_b = data['team_b'].presence || []
+
+    return unless team_a.any? || team_b.any?
+
+    result = DraftAnalyzer.call(team_a:, team_b:)
+
+    ActionCable.server.broadcast("draft_#{params[:draft_id]}", {
+                                   type: 'ai_update',
+                                   payload: DraftAnalysisBlueprint.render_as_hash(result)
+                                 })
+  end
+end

app/modules/ai_intelligence/controllers/draft_controller.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module AiIntelligence
+  module Controllers
+    # REST endpoint for AI draft analysis.
+    # Requires Tier 1 (Professional) subscription — feature: predictive_analytics.
+    class DraftController < Api::V1::BaseController
+      before_action :require_predictive_analytics_access!
+
+      # POST /api/v1/ai/draft/analyze
+      def analyze
+        result = DraftAnalyzer.call(
+          team_a: params.require(:team_a),
+          team_b: params.require(:team_b),
+          patch: params[:patch]
+        )
+        render_success(DraftAnalysisBlueprint.render_as_hash(result))
+      end
+
+      private
+
+      def require_predictive_analytics_access!
+        return if current_organization.can_access?('predictive_analytics')
+
+        render_error(
+          message: 'AI draft analysis requires Tier 1 (Professional) subscription',
+          code: 'UPGRADE_REQUIRED',
+          status: :forbidden
+        )
+      end
+    end
+  end
+end

app/modules/ai_intelligence/jobs/rebuild_champion_matrix_job.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module AiIntelligence
+  # Rebuilds champion matrices and vectors from all CompetitiveMatch records.
+  # Runs in low_priority queue — triggered after each scraper sync or nightly via sidekiq-scheduler.
+  # Uses CompetitiveMatch.unscoped intentionally (global dataset, no org context needed).
+  class RebuildChampionMatrixJob < ApplicationJob
+    queue_as :low_priority
+
+    def perform(scope: :all, league: nil)
+      Rails.logger.info("[AI] Starting champion matrix rebuild scope=#{scope} league=#{league}")
+
+      ChampionMatrixBuilder.call(scope: scope.to_sym, league:)
+      ChampionVectorBuilder.rebuild_all!
+
+      Rails.logger.info("[AI] Champion matrices rebuilt at #{Time.current}")
+    end
+  end
+end

app/modules/ai_intelligence/models/ai_champion_matrix.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# Stores historical win-rate data between pairs of champions.
+# Global table (no organization_id, no RLS) — aggregates public competitive tournament data.
+class AiChampionMatrix < ApplicationRecord
+  validates :champion_a, :champion_b, presence: true
+  validates :champion_a, uniqueness: { scope: %i[champion_b patch league] }
+
+  scope :with_sufficient_sample, -> { where('total_games >= ?', 10) }
+
+  def self.upsert_win(winner, loser, patch: nil, league: nil)
+    matrix = find_or_initialize_by(champion_a: winner, champion_b: loser, patch: patch, league: league)
+    matrix.wins_a      = matrix.wins_a.to_i + 1
+    matrix.total_games = matrix.total_games.to_i + 1
+    matrix.updated_at  = Time.current
+    matrix.save!
+  end
+
+  def win_rate
+    return 0.5 if total_games.zero?
+
+    wins_a.to_f / total_games
+  end
+end

app/modules/ai_intelligence/models/ai_champion_vector.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# Stores normalized 5-dimensional performance vectors per champion.
+# Dimensions: [win_rate, avg_kda, avg_damage_share, avg_gold_share, avg_cs]
+# Global table (no organization_id, no RLS).
+class AiChampionVector < ApplicationRecord
+  validates :champion_name, presence: true, uniqueness: true
+
+  def vector
+    Numo::DFloat[*vector_data]
+  end
+end

app/modules/ai_intelligence/serializers/draft_analysis_blueprint.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+# Serializes DraftAnalyzer::Result for the POST /api/v1/ai/draft/analyze response.
+class DraftAnalysisBlueprint < Blueprinter::Base
+  field :win_probability
+  field :confidence
+  field :low_sample
+
+  field :top_synergies do |result|
+    result.synergy_scores
+          .sort_by { |_, v| -v[:score].to_f }
+          .first(5)
+          .map { |(a, b), v| { pair: [a, b], score: v[:score], games: v[:games] } }
+  end
+
+  field :top_counters do |result|
+    result.counter_scores
+          .sort_by { |_, v| -v[:advantage].to_f.abs }
+          .first(5)
+          .map do |(a, b), v|
+      { matchup: [a, b], advantage: v[:advantage], games: v[:games],
+        confidence: v[:confidence] }
+    end
+  end
+
+  field :suggested_picks do |result|
+    result.suggested_picks || []
+  end
+end

app/modules/ai_intelligence/services/champion_matrix_builder.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+# Reads CompetitiveMatch records (via unscoped) and builds the ai_champion_matrices table.
+# victory=true means our_picks won; victory=false means opponent_picks won.
+class ChampionMatrixBuilder
+  def initialize(scope: :all, league: nil)
+    @scope  = scope
+    @league = league
+  end
+
+  def self.call(scope: :all, league: nil)
+    new(scope:, league:).build
+  end
+
+  def build
+    AiChampionMatrix.delete_all if @scope == :all
+
+    query = CompetitiveMatch.unscoped
+    query = query.where(tournament_name: @league) if @league
+
+    query.find_each do |match|
+      winner_picks = match.victory ? match.our_picks : match.opponent_picks
+      loser_picks  = match.victory ? match.opponent_picks : match.our_picks
+
+      next if winner_picks.blank? || loser_picks.blank?
+
+      register_matchups(winner_picks, loser_picks)
+    end
+  end
+
+  private
+
+  def register_matchups(winner_picks, loser_picks)
+    winner_champions = winner_picks.map { |p| p['champion'] }.compact
+    loser_champions  = loser_picks.map  { |p| p['champion'] }.compact
+
+    winner_champions.each do |winner|
+      loser_champions.each do |loser|
+        AiChampionMatrix.upsert_win(winner, loser)
+        record_appearance(loser, winner)
+      end
+    end
+  end
+
+  def record_appearance(champion_a, champion_b)
+    AiChampionMatrix
+      .find_or_initialize_by(champion_a:, champion_b:)
+      .tap do |m|
+      m.total_games = m.total_games.to_i + 1
+      m.updated_at = Time.current
+      m.save!
+    end
+  end
+end