feat: implement ProStaff ML

Atualmente na ProStaff tenho um modelo próprio treinado de AI para recomendações do tipo "X é melhor que Y nesse
  contexto:
  - XGBoost  para classificação binária (win/loss dado o draft + contexto) com dados tabulares, treina rápido em CPU
  - Matrix Factorization para sinergias implícitas (similar ao que o Netflix usa para recomendação) e descobre relações latentes entre campeões que o win rate bruto não captura
  - Embeddings de campeão treinados no seu próprio histórico (Word2Vec sobre sequências de picks), representação vetorial própria, mais rica que os vetores atuais baseados só em stats médios

Author: Bulletdev

app/modules/ai_intelligence/controllers/recommend_controller.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module AiIntelligence
+  module Controllers
+    # Champion pick recommendations powered by the ProStaff ML AI Service.
+    #
+    # Calls the FastAPI ML service (ai-service container) and falls back to the
+    # Ruby DraftSuggester when the ML service is unavailable.
+    #
+    # The X-AI-Source response header indicates which engine answered:
+    #   X-AI-Source: ml_v2   — ML service (XGBoost + Champion2Vec, 327 features)
+    #   X-AI-Source: legacy  — DraftSuggester (cosine similarity, AiChampionVector table)
+    class RecommendController < Api::V1::BaseController
+      before_action :require_predictive_analytics_access!
+
+      # POST /api/v1/ai/recommend-pick
+      #
+      # @param our_picks      [Array<String>] champions already picked by our team (0-4)
+      # @param opponent_picks [Array<String>] champions picked by the opponent (0-5)
+      # @param our_bans       [Array<String>] champions banned by our team (optional)
+      # @param opponent_bans  [Array<String>] champions banned by opponent (optional)
+      # @param patch          [String]        patch version, e.g. "16.08" (optional)
+      # @param league         [String]        league identifier, e.g. "LCK" (optional)
+      #
+      # @return [JSON] { recommendations: [...], source: "ml_v2"|"legacy", model_version: "v2"|nil }
+      def recommend_pick
+        result = AiRecommendationService.call(
+          our_picks: Array(params[:our_picks]),
+          opponent_picks: Array(params[:opponent_picks]),
+          our_bans: Array(params[:our_bans]),
+          opponent_bans: Array(params[:opponent_bans]),
+          patch: params[:patch],
+          league: params[:league]
+        )
+
+        response.set_header('X-AI-Source', result[:source])
+        render_success(result)
+      end
+
+      private
+
+      def require_predictive_analytics_access!
+        return if current_organization.can_access?('predictive_analytics')
+
+        render_error(
+          message: 'AI recommendations require Tier 1 (Professional) subscription',
+          code: 'UPGRADE_REQUIRED',
+          status: :forbidden
+        )
+      end
+    end
+  end
+end

app/modules/ai_intelligence/services/ai_recommendation_service.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+# HTTP client for the ProStaff ML AI Service (FastAPI).
+#
+# Calls POST /recommend on the ML service and returns top-N champion picks
+# with composite scores. Falls back to DraftSuggester (Ruby cosine-similarity
+# implementation) when the ML service is unreachable or returns an error.
+#
+# Configuration:
+#   AI_SERVICE_URL — base URL of the FastAPI service, e.g. http://ai-service:8001
+#                    Defaults to http://localhost:8001 for local development.
+#
+# Source tagging:
+#   Returns { source: "ml_v2" } when ML responded successfully.
+#   Returns { source: "legacy" } when falling back to DraftSuggester.
+#
+# @example
+#   result = AiRecommendationService.call(
+#     our_picks:      %w[Jinx Thresh Azir Gnar],
+#     opponent_picks: %w[Caitlyn Nautilus Syndra Renekton Graves],
+#     our_bans:       [],
+#     opponent_bans:  [],
+#     patch:          "16.08",
+#     league:         "LCK"
+#   )
+#   result[:source]          # => "ml_v2"
+#   result[:recommendations] # => [{ champion: "Lissandra", score: 0.52, ... }]
+class AiRecommendationService
+  class MlServiceError < StandardError; end
+
+  REQUEST_TIMEOUT = 5
+
+  def self.call(**)
+    new(**).call
+  end
+
+  def initialize(our_picks:, opponent_picks:, our_bans: [], opponent_bans: [], patch: nil, league: nil)
+    @our_picks      = our_picks
+    @opponent_picks = opponent_picks
+    @our_bans       = our_bans
+    @opponent_bans  = opponent_bans
+    @patch          = patch
+    @league         = league
+    @base_url       = ENV.fetch('AI_SERVICE_URL', 'http://localhost:8001')
+  end
+
+  def call
+    call_ml_service
+  rescue MlServiceError => e
+    Rails.logger.warn("[AiRecommendationService] ML service unavailable, using legacy fallback: #{e.message}")
+    legacy_fallback
+  end
+
+  private
+
+  def call_ml_service
+    response = connection.post('/recommend') do |req|
+      req.headers['Content-Type'] = 'application/json'
+      req.body = build_payload.to_json
+      req.options.timeout = REQUEST_TIMEOUT
+    end
+
+    raise MlServiceError, "ML service returned #{response.status}" unless response.success?
+
+    body = JSON.parse(response.body, symbolize_names: true)
+    {
+      source: body[:source] || 'ml_v2',
+      model_version: body[:model_version],
+      recommendations: body[:recommendations] || []
+    }
+  rescue Faraday::TimeoutError => e
+    raise MlServiceError, "timeout: #{e.message}"
+  rescue Faraday::ConnectionFailed => e
+    raise MlServiceError, "connection failed: #{e.message}"
+  rescue Faraday::Error => e
+    raise MlServiceError, "network error: #{e.message}"
+  rescue JSON::ParserError => e
+    raise MlServiceError, "invalid JSON response: #{e.message}"
+  end
+
+  def legacy_fallback
+    suggestions = DraftSuggester.call(team_a: @our_picks, team_b: @opponent_picks)
+    {
+      source: 'legacy',
+      model_version: nil,
+      recommendations: suggestions.map { |champ| { champion: champ, score: nil } }
+    }
+  end
+
+  def build_payload
+    {
+      our_picks: @our_picks,
+      opponent_picks: @opponent_picks,
+      our_bans: @our_bans,
+      opponent_bans: @opponent_bans,
+      patch: @patch,
+      league: @league
+    }
+  end
+
+  def connection
+    @connection ||= Faraday.new(url: @base_url) do |f|
+      f.adapter Faraday.default_adapter
+    end
+  end
+end

config/routes.rb

@@ -459,7 +459,8 @@
       # AI Intelligence Module — draft analysis and win probability
       # Requires Tier 1 (Professional) subscription.
       namespace :ai do
-        post 'draft/analyze', to: '/ai_intelligence/controllers/draft#analyze'
+        post 'draft/analyze',   to: '/ai_intelligence/controllers/draft#analyze'
+        post 'recommend-pick',  to: '/ai_intelligence/controllers/recommend#recommend_pick'
       end
 
       # Tournaments Module — ArenaBR double elimination