bulltrackers-module 1.0.766 → 1.0.768

package/functions/computation-system-v2/computations/BehavioralAnomaly.js

@@ -1,3 +1,13 @@
+/**
+ * @fileoverview Behavioral Anomaly Detection (V2)
+ * Detects significant deviations in investor behavior compared to their 60-day baseline.
+ * * MATH: Uses Mahalanobis Distance to detect outliers in multi-dimensional space.
+ * FEATURES:
+ * 1. Concentration (HHI): Are they suddenly putting all eggs in one basket?
+ * 2. Martingale (Loss Chasing): Are they increasing leverage after losses?
+ * 3. Capacity Strain: Is their AUM growing faster than their copy count implies (risk of slippage)?
+ * 4. Risk Score: Sudden spikes in risk.
+ */
 const { Computation } = require('../framework');
 
 class BehavioralAnomaly extends Computation {
@@ -10,6 +20,7 @@ class BehavioralAnomaly extends Computation {
             isHistorical: true,
             
             requires: {
+                // We need 60 days of history to build a statistical baseline
                 'portfolio_snapshots': {
                     lookback: 60,
                     mandatory: true,
@@ -36,13 +47,12 @@ class BehavioralAnomaly extends Computation {
                 }
             },
 
-            // LEGACY METADATA PRESERVED
             userType: 'POPULAR_INVESTOR',
             alert: {
                 id: 'behavioralAnomaly',
                 frontendName: 'Behavioral Anomaly',
                 description: 'Alert when a Popular Investor deviates significantly from their baseline behavior',
-                messageTemplate: 'Behavioral Alert for {piUsername}: {primaryDriver} Deviation ({driverSignificance}) detected.',
+                messageTemplate: 'Behavioral Alert for {username}: {primaryDriver} Deviation ({driverSignificance}) detected.',
                 severity: 'high',
                 configKey: 'behavioralAnomaly',
                 isDynamic: true,
@@ -50,230 +60,332 @@ class BehavioralAnomaly extends Computation {
                     {
                         key: 'anomalyScoreThreshold',
                         type: 'number',
-                        label: 'Anomaly Sensitivity',
-                        description: 'Alert when anomaly score exceeds this threshold (higher = less sensitive)',
+                        label: 'Sensitivity Threshold',
                         default: 3.5,
-                        min: 2.0,
-                        max: 5.0,
-                        step: 0.5,
-                        unit: 'σ (standard deviations)'
+                        min: 2.0, max: 10.0, step: 0.1
                     }
                 ],
-                conditions: [
-                    {
-                        key: 'watchedDrivers',
-                        type: 'array',
-                        label: 'Watched Behavior Drivers',
-                        description: 'Only alert for these specific behavioral factors (empty = all)',
-                        default: [],
-                        options: [
-                            { value: 'Concentration (HHI)', label: 'Portfolio Concentration' },
-                            { value: 'Martingale Behavior', label: 'Martingale Behavior' },
-                            { value: 'Capacity Strain', label: 'Capacity Strain' },
-                            { value: 'Risk Score', label: 'Risk Score Changes' }
-                        ]
-                    }
-                ],
-                resultKeys: ['triggered', 'anomalyScore', 'primaryDriver', 'driverSignificance', 'baselineDays']
+                resultFields: {
+                    driver: 'primaryDriver',
+                    score: 'driverSignificance'
+                }
             }
         };
     }
 
-    // --- Math Helper (Self-Contained) ---
-    static LinearAlgebra = {
-        mean(data) {
-            const sum = data.reduce((a, b) => a + b, 0);
-            return sum / data.length;
-        },
-        covarianceMatrix(vectors) {
-            const n = vectors.length;
-            const dim = vectors[0].length;
-            const means = Array(dim).fill(0).map((_, i) => this.mean(vectors.map(v => v[i])));
-            const matrix = Array(dim).fill(0).map(() => Array(dim).fill(0));
-
-            for (let i = 0; i < dim; i++) {
-                for (let j = 0; j < dim; j++) {
-                    let sum = 0;
-                    for (let k = 0; k < n; k++) {
-                        sum += (vectors[k][i] - means[i]) * (vectors[k][j] - means[j]);
-                    }
-                    matrix[i][j] = sum / (n - 1);
-                }
-            }
-            return { matrix, means };
-        },
-        invertMatrix(M) {
-            // Simple 4x4 inversion or generic Gaussian elimination
-            // For brevity, assuming 4x4 or small dimensions suitable for JS
-            // (Implementation omitted for brevity, essentially standard Gaussian elimination)
-            // Simplified check for diagonal/stability
-             if(M.length === 0) return null;
-             // Placeholder for full inversion logic - in production use a library
-             // For this migration, we check for zero variance on diagonal
-             for(let i=0; i<M.length; i++) if(M[i][i] === 0) return null;
-             return M; // Mock return: In real usage, implement numeric.js or similar
-        },
-        mahalanobisDistance(vector, means, inverseCov) {
-            // D^2 = (x - u)^T * S^-1 * (x - u)
-            // Simplified Euclidean for fallback if inversion fails, or full calc
-            // For this output, we assume full calculation logic exists here.
-            let diff = vector.map((v, i) => v - means[i]);
-            let sum = 0;
-            // Mock calculation
-            return Math.sqrt(diff.reduce((acc, val) => acc + (val * val), 0)); 
-        }
-    };
-
-    calculateHHI(portfolioData) {
-        const positions = this.rules.portfolio.extractPositions(portfolioData);
-        if (!positions || positions.length === 0) return 0;
-
-        let sumSquares = 0;
-        const totalValue = this.rules.portfolio.calculateTotalValue(positions);
-
-        positions.forEach(p => {
-            // Calculate actual % weight based on Value
-            const val = this.rules.portfolio.getValue(p);
-            const weight = totalValue > 0 ? (val / totalValue) * 100 : 0;
-            sumSquares += (weight * weight);
-        });
-        return sumSquares;
-    }
+    async process(context) {
+        const { data, entityId, date, rules } = context;
 
-    calculateMartingaleScore(historyData) {
-        const trades = this.rules.trades.extractTrades(historyData);
-        if (!trades || trades.length < 2) return 0;
+        // =====================================================================
+        // 1. DATA PREPARATION
+        // =====================================================================
         
-        // Sort by close date
-        const sorted = [...trades].sort((a, b) => 
-            (this.rules.trades.getCloseDate(a) || 0) - (this.rules.trades.getCloseDate(b) || 0)
-        );
-        const recent = sorted.slice(-30);
-
-        let lossEvents = 0;
-        let martingaleResponses = 0;
-
-        for (let i = 0; i < recent.length - 1; i++) {
-            const current = recent[i];
-            const next = recent[i+1];
-
-            if (this.rules.trades.getNetProfit(current) < 0) {
-                lossEvents++;
-                const currentLev = this.rules.trades.getLeverage(current);
-                const nextLev = this.rules.trades.getLeverage(next);
-                if (nextLev > currentLev) martingaleResponses++;
+        // Helper: Safe Date String
+        const toDateStr = (d) => {
+            if (!d) return "";
+            if (d.value) return d.value;
+            return d instanceof Date ? d.toISOString().slice(0, 10) : String(d);
+        };
+
+        // Helper: Access Data Map or Array safely (V2 Pattern)
+        const getEntityRows = (dataset) => {
+            if (!dataset) return [];
+            if (dataset[entityId]) {
+                return Array.isArray(dataset[entityId]) ? dataset[entityId] : [dataset[entityId]];
             }
-        }
-        return lossEvents > 0 ? (martingaleResponses / lossEvents) : 0;
-    }
+            if (Array.isArray(dataset)) {
+                return dataset.filter(r => String(r.pi_id || r.user_id || r.cid) === String(entityId));
+            }
+            return [];
+        };
 
-    getDailyVector(portfolioData, rankingsData, historyData) {
-        const hhi = this.calculateHHI(portfolioData);
-        const mScore = this.calculateMartingaleScore(historyData);
-        
-        let strain = 0;
-        let risk = 1;
-
-        if (rankingsData) {
-            const copiers = this.rules.rankings.getCopiers(rankingsData);
-            const aum = this.rules.rankings.getAUM(rankingsData);
-            strain = aum > 0 ? (copiers / (aum / 1000)) : 0;
-            risk = this.rules.rankings.getRiskScore(rankingsData);
+        // Fetch Data
+        const portfolios = getEntityRows(data['portfolio_snapshots']);
+        const rankings = getEntityRows(data['pi_rankings']);
+        const history = getEntityRows(data['trade_history_snapshots']);
+
+        // Index by Date for fast alignment
+        // { "2026-01-28": row }
+        const portMap = new Map(portfolios.map(r => [toDateStr(r.date), r]));
+        const rankMap = new Map(rankings.map(r => [toDateStr(r.date), r]));
+        const histMap = new Map(history.map(r => [toDateStr(r.date), r]));
+
+        // Identify "Today" (Execution Date)
+        const todayPort = portMap.get(date);
+        const todayRank = rankMap.get(date);
+        const todayHist = histMap.get(date);
+
+        if (!todayPort || !todayRank) {
+            // Cannot run anomaly detection without today's data
+            return; 
         }
 
-        return [hhi, mScore, strain, risk];
-    }
+        // =====================================================================
+        // 2. FEATURE ENGINEERING
+        // =====================================================================
+
+        /**
+         * 1. Concentration (HHI)
+         * Sum of squared weights. High HHI = Low Diversification.
+         */
+        const calculateHHI = (portRow) => {
+            const pData = rules.portfolio.extractPortfolioData(portRow);
+            const positions = rules.portfolio.extractPositions(pData);
+            
+            if (!positions || positions.length === 0) return 0;
 
-    async process(context) {
-        const { data, entityId, rules } = context;
-        this.rules = rules; // Attach rules for helper access
+            let sumSquares = 0;
+            let totalInvested = 0;
 
-        const portfolios = data['portfolio_snapshots'] || [];
-        const rankings = data['pi_rankings'] || [];
-        const histories = data['trade_history_snapshots'] || [];
+            positions.forEach(p => {
+                // Invested is typically a %. If it's absolute $, we normalize later.
+                // Assuming standard eToro data where Invested is a % (0-100 or 0-1)
+                const val = rules.portfolio.getInvested(p) || 0; 
+                totalInvested += val;
+                sumSquares += (val * val);
+            });
 
-        // Sort data by date ascending for baseline building
-        portfolios.sort((a, b) => new Date(a.date) - new Date(b.date));
-        
-        const trainingVectors = [];
-        const MIN_DATAPOINTS = 15;
+            // Normalize if total > 0 (Standard HHI ranges 0 to 10,000)
+            // If weights sum to 100, HHI is sum(w^2).
+            return sumSquares; 
+        };
 
-        // Build Baseline
-        for (const portRow of portfolios) {
-            const date = portRow.date;
-            
-            // Match ranking and history for this date
-            const rankRow = rankings.find(r => r.date === date);
-            const histRow = histories.find(h => h.date === date);
+        /**
+         * 2. Martingale Score
+         * Checks if leverage increases after a loss (Loss Chasing).
+         */
+        const calculateMartingale = (histRow) => {
+            const trades = rules.trades.extractTrades(histRow);
+            if (!trades || trades.length < 2) return 0;
+
+            // Sort by close date (Oldest -> Newest)
+            trades.sort((a, b) => {
+                const dA = rules.trades.getCloseDate(a);
+                const dB = rules.trades.getCloseDate(b);
+                return (dA || 0) - (dB || 0);
+            });
+
+            // Look at recent behavior (last 30 trades in this snapshot)
+            const recent = trades.slice(-30);
+            let lossEvents = 0;
+            let martingaleResponses = 0;
+
+            for (let i = 0; i < recent.length - 1; i++) {
+                const current = recent[i];
+                const next = recent[i+1];
+
+                const profit = rules.trades.getNetProfit(current);
+                if (profit < 0) {
+                    lossEvents++;
+                    const curLev = rules.trades.getLeverage(current) || 1;
+                    const nextLev = rules.trades.getLeverage(next) || 1;
+                    
+                    if (nextLev > curLev) {
+                        martingaleResponses++;
+                    }
+                }
+            }
 
-            const portData = rules.portfolio.extractPortfolioData(portRow);
-            const rankData = rules.rankings.extractRankingsData(rankRow);
+            return lossEvents > 0 ? (martingaleResponses / lossEvents) : 0;
+        };
+
+        /**
+         * 3. Capacity Strain
+         * Copiers / AUM. If copiers grow but AUM doesn't, efficiency drops.
+         */
+        const calculateStrain = (rankRow) => {
+            const rData = rules.rankings.extractRankingsData(rankRow);
+            if (!rData) return 0;
+
+            const copiers = rules.rankings.getCopiers(rData) || 0;
+            // AUM Tier is usually an int (1-6). We need approximate value or raw AUM if available.
+            // Using raw AUMValue if available in JSON, else estimate from tier.
+            const aum = rData.AUMValue || (rules.rankings.getAUMTier(rData) * 10000) || 1; 
             
-            // Note: History logic simplified; V1 filtered full history, 
-            // here we rely on the daily snapshots which usually contain accumulated history
-            const histData = histRow; 
+            return (copiers / (aum / 1000)); // Normalized ratio
+        };
+
+        /**
+         * 4. Risk Score
+         */
+        const getRisk = (rankRow) => {
+            const rData = rules.rankings.extractRankingsData(rankRow);
+            return rules.rankings.getRiskScore(rData) || 1;
+        };
+
+        // --- Build Vectors ---
+        const getDailyVector = (pRow, rRow, hRow) => {
+            if (!pRow || !rRow) return null;
+            return [
+                calculateHHI(pRow),
+                hRow ? calculateMartingale(hRow) : 0,
+                calculateStrain(rRow),
+                getRisk(rRow)
+            ];
+        };
 
-            if (portData) {
-                const vec = this.getDailyVector(portData, rankData, histData);
-                trainingVectors.push(vec);
+        // =====================================================================
+        // 3. BASELINE CONSTRUCTION
+        // =====================================================================
+        
+        const trainingVectors = [];
+        
+        // Loop through last 60 days (excluding today)
+        const sortedDates = Array.from(portMap.keys()).sort();
+        
+        for (const d of sortedDates) {
+            if (d === date) continue; // Don't include today in the baseline training
+
+            const pRow = portMap.get(d);
+            const rRow = rankMap.get(d); // Matches date?
+            const hRow = histMap.get(d); // History available for this date?
+
+            // We need intersection of Portfolio and Ranking to form a valid vector point
+            if (pRow && rRow) {
+                const vec = getDailyVector(pRow, rRow, hRow);
+                if (vec) trainingVectors.push(vec);
             }
         }
 
-        if (trainingVectors.length < MIN_DATAPOINTS) {
-            this.setResult(entityId, { status: 'INSUFFICIENT_BASELINE', dataPoints: trainingVectors.length });
+        // Need minimum data to be statistically significant
+        if (trainingVectors.length < 15) {
+            this.setResult(entityId, { 
+                triggered: false, 
+                status: 'INSUFFICIENT_BASELINE', 
+                dataPoints: trainingVectors.length 
+            });
             return;
         }
 
-        // Compute Stats
-        const stats = BehavioralAnomaly.LinearAlgebra.covarianceMatrix(trainingVectors);
-        // Note: Real implementation needs a robust inversion. 
-        // If variance is 0, inversion fails.
-        const inverseCov = BehavioralAnomaly.LinearAlgebra.invertMatrix(stats.matrix);
+        // =====================================================================
+        // 4. LINEAR ALGEBRA ENGINE
+        // =====================================================================
+        
+        const MathLib = {
+            // Mean of each column
+            mean: (vectors) => {
+                const dim = vectors[0].length;
+                const means = new Array(dim).fill(0);
+                for (const v of vectors) {
+                    for (let i = 0; i < dim; i++) means[i] += v[i];
+                }
+                return means.map(x => x / vectors.length);
+            },
+
+            // Covariance Matrix
+            covariance: (vectors, means) => {
+                const dim = vectors[0].length;
+                const n = vectors.length;
+                const matrix = Array(dim).fill(0).map(() => Array(dim).fill(0));
+
+                for (const v of vectors) {
+                    for (let i = 0; i < dim; i++) {
+                        for (let j = 0; j < dim; j++) {
+                            matrix[i][j] += (v[i] - means[i]) * (v[j] - means[j]);
+                        }
+                    }
+                }
+                return matrix.map(row => row.map(val => val / (n - 1))); // Sample Covariance
+            },
 
-        if (!inverseCov) {
-            this.setResult(entityId, { status: 'STABLE_STATE', info: 'Variance too low' });
-            return;
-        }
+            // Matrix Inversion (Gauss-Jordan)
+            invert: (M) => {
+                // Simplified for 4x4. Returns null if singular.
+                try {
+                    const n = M.length;
+                    const A = M.map(row => [...row]); // Clone
+                    const I = M.map((row, i) => M.map((_, j) => (i === j ? 1 : 0))); // Identity
+
+                    for (let i = 0; i < n; i++) {
+                        let pivot = A[i][i];
+                        if (Math.abs(pivot) < 1e-8) return null; // Singular
+
+                        for (let j = 0; j < n; j++) {
+                            A[i][j] /= pivot;
+                            I[i][j] /= pivot;
+                        }
+
+                        for (let k = 0; k < n; k++) {
+                            if (k !== i) {
+                                const factor = A[k][i];
+                                for (let j = 0; j < n; j++) {
+                                    A[k][j] -= factor * A[i][j];
+                                    I[k][j] -= factor * I[i][j];
+                                }
+                            }
+                        }
+                    }
+                    return I;
+                } catch (e) { return null; }
+            },
 
-        // Today's Vector (Last element in sorted array)
-        const todayPortRow = portfolios[portfolios.length - 1];
-        const todayRankRow = rankings.find(r => r.date === todayPortRow.date);
-        const todayHistRow = histories.find(h => h.date === todayPortRow.date);
+            // Mahalanobis Distance
+            distance: (v, means, invCov) => {
+                const diff = v.map((val, i) => val - means[i]);
+                const dim = diff.length;
+                let sum = 0;
+                
+                for (let i = 0; i < dim; i++) {
+                    let temp = 0;
+                    for (let j = 0; j < dim; j++) {
+                        temp += diff[j] * invCov[j][i];
+                    }
+                    sum += temp * diff[i];
+                }
+                return Math.sqrt(Math.max(0, sum));
+            }
+        };
 
-        const todayVector = this.getDailyVector(
-            rules.portfolio.extractPortfolioData(todayPortRow),
-            rules.rankings.extractRankingsData(todayRankRow),
-            todayHistRow
-        );
+        // =====================================================================
+        // 5. ANOMALY DETECTION
+        // =====================================================================
 
-        const distance = BehavioralAnomaly.LinearAlgebra.mahalanobisDistance(todayVector, stats.means, inverseCov);
-        const IS_ANOMALY = distance > 3.5;
+        const means = MathLib.mean(trainingVectors);
+        const covMatrix = MathLib.covariance(trainingVectors, means);
+        const invCov = MathLib.invert(covMatrix);
 
-        const result = {
-            triggered: IS_ANOMALY,
-            anomalyScore: parseFloat(distance.toFixed(2)),
-            baselineDays: trainingVectors.length
-        };
+        if (!invCov) {
+            this.setResult(entityId, { triggered: false, status: 'SINGULAR_MATRIX_ERROR' });
+            return;
+        }
 
-        if (IS_ANOMALY) {
-            const featureNames = ['Concentration (HHI)', 'Martingale Behavior', 'Capacity Strain', 'Risk Score'];
-            let maxZ = 0;
-            let primaryDriver = 'Unknown';
-            
+        const todayVector = getDailyVector(todayPort, todayRank, todayHist);
+        const distance = MathLib.distance(todayVector, means, invCov);
+        
+        // Threshold from Alert Config (or default 3.5 sigma)
+        const threshold = 3.5; 
+        const isAnomaly = distance > threshold;
+
+        const featureNames = ['Concentration (HHI)', 'Martingale Behavior', 'Capacity Strain', 'Risk Score'];
+        
+        let primaryDriver = 'Unknown';
+        let maxZ = 0;
+
+        // Determine *Why* it's an anomaly (Z-Score contribution)
+        if (isAnomaly) {
             todayVector.forEach((val, i) => {
-                const stdDev = Math.sqrt(stats.matrix[i][i]);
-                const z = stdDev > 0 ? Math.abs((val - stats.means[i]) / stdDev) : 0;
+                const stdDev = Math.sqrt(covMatrix[i][i]);
+                const z = stdDev > 0 ? Math.abs((val - means[i]) / stdDev) : 0;
                 if (z > maxZ) {
                     maxZ = z;
                     primaryDriver = featureNames[i];
                 }
             });
-
-            result.primaryDriver = primaryDriver;
-            result.driverSignificance = `${maxZ.toFixed(1)}σ`;
-            result.vectors = { current: todayVector, baselineMeans: stats.means };
         }
 
+        const result = {
+            triggered: isAnomaly,
+            anomalyScore: Number(distance.toFixed(2)),
+            primaryDriver: isAnomaly ? primaryDriver : null,
+            driverSignificance: isAnomaly ? `${maxZ.toFixed(1)}σ` : null,
+            baselineDays: trainingVectors.length,
+            username: rules.rankings.extractRankingsData(todayRank)?.UserName || "Unknown",
+            _debug: {
+                currentVector: todayVector,
+                baselineMeans: means
+            }
+        };
+
         this.setResult(entityId, result);
     }
 }