bulltrackers-module 1.0.768 → 1.0.770

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

@@ -0,0 +1,359 @@
+/**
+ * @fileoverview PI Recommender (v2 - Diversification-Aware)
+ * 
+ * Recommends Popular Investors to signed-in users based on:
+ * 1. User preferences (sectors, risk tolerance they're drawn to)
+ * 2. Diversification benefit (low correlation with current portfolio)
+ * 3. Quality thresholds (risk score, copiers, track record)
+ * 
+ * This replaces the legacy similarity-based approach which was harmful
+ * because it doubled down on existing exposure instead of diversifying.
+ */
+const { Computation } = require('../framework');
+
+class PiRecommender extends Computation {
+    static getConfig() {
+        return {
+            name: 'PiRecommender',
+            description: 'Recommends PIs balancing user preferences with diversification',
+            type: 'per-entity',
+            category: 'signed_in_user',
+            isHistorical: false,
+
+            // Depends on global PI feature vectors
+            dependencies: ['PiFeatureVectors'],
+
+            requires: {
+                'portfolio_snapshots': {
+                    lookback: 0,
+                    mandatory: true,
+                    fields: ['user_id', 'portfolio_data', 'date'],
+                    filter: { user_type: 'SIGNED_IN_USER' }
+                },
+                'ticker_mappings': { mandatory: false },
+                'sector_mappings': { mandatory: false }
+            },
+
+            storage: {
+                bigquery: true,
+                firestore: {
+                    enabled: true,
+                    path: 'users/{entityId}/recommendations',
+                    merge: true
+                }
+            }
+        };
+    }
+
+    async process(context) {
+        const { data, entityId, rules, getDependency, targetDate } = context;
+
+        // ===========================================================================
+        // CONFIGURATION: Scoring weights and thresholds
+        // ===========================================================================
+        const WEIGHTS = {
+            interest: 0.30,        // How much they match user preferences
+            diversification: 0.40, // How different they are (highest weight!)
+            quality: 0.30          // Performance and popularity
+        };
+
+        const THRESHOLDS = {
+            minCopiers: 10,        // Skip unpopular PIs
+            maxRiskScore: 8,       // Skip very high risk
+            minGain: -10,          // Skip extreme losers
+            excludeAlreadyCopied: true
+        };
+
+        const TOP_N = 10;  // Return top N recommendations
+
+        // ===========================================================================
+        // SETUP: Build sector lookup and helpers
+        // ===========================================================================
+        const toArray = (input) => {
+            if (!input) return [];
+            if (Array.isArray(input)) return input;
+            return Object.values(input).flat();
+        };
+
+        const tickerMap = new Map();
+        toArray(data['ticker_mappings']).forEach(row => {
+            if (row.instrument_id && row.ticker) {
+                tickerMap.set(Number(row.instrument_id), row.ticker.toUpperCase());
+            }
+        });
+
+        const sectorMap = new Map();
+        toArray(data['sector_mappings']).forEach(row => {
+            if (row.symbol && row.sector) {
+                sectorMap.set(row.symbol.toUpperCase(), row.sector);
+            }
+        });
+
+        const resolveSector = (instrumentId) => {
+            const ticker = tickerMap.get(Number(instrumentId));
+            return ticker ? (sectorMap.get(ticker) || 'Other') : 'Other';
+        };
+
+        // ===========================================================================
+        // STEP 1: Get user's current portfolio profile
+        // ===========================================================================
+        const portfolioRows = data['portfolio_snapshots']?.[entityId];
+        if (!portfolioRows || portfolioRows.length === 0) {
+            this.setResult(entityId, { recommendations: [], reason: 'No portfolio data' });
+            return;
+        }
+
+        const latestRow = Array.isArray(portfolioRows)
+            ? portfolioRows[portfolioRows.length - 1]
+            : portfolioRows;
+
+        const pData = rules.portfolio.extractPortfolioData(latestRow);
+        const positions = rules.portfolio.extractPositions(pData);
+        const mirrors = pData.AggregatedMirrors || [];
+
+        // Already copied PI IDs
+        const copiedPiIds = new Set(
+            mirrors.map(m => String(m.ParentCID || m.CID)).filter(Boolean)
+        );
+
+        // Build user's sector exposure
+        const userSectorWeights = {};
+        let userTotalValue = 0;
+
+        positions.forEach(pos => {
+            const instrumentId = rules.portfolio.getInstrumentId(pos);
+            const invested = rules.portfolio.getInvested(pos) || 0;
+            const sector = resolveSector(instrumentId);
+
+            userSectorWeights[sector] = (userSectorWeights[sector] || 0) + invested;
+            userTotalValue += invested;
+        });
+
+        // Include mirror exposures
+        mirrors.forEach(m => {
+            userTotalValue += (m.Invested || m.Amount || 0);
+        });
+
+        // Normalize to percentages
+        const userSectorProfile = {};
+        Object.entries(userSectorWeights).forEach(([sector, weight]) => {
+            userSectorProfile[sector] = userTotalValue > 0
+                ? weight / userTotalValue
+                : 0;
+        });
+
+        // Infer user preferences from copied PIs
+        const userPreferredRiskRange = this._inferRiskPreference(mirrors, rules);
+
+        // ===========================================================================
+        // STEP 2: Load global PI feature vectors
+        // ===========================================================================
+        const piFeatureData = getDependency('PiFeatureVectors');
+        if (!piFeatureData || !piFeatureData.vectors) {
+            this.setResult(entityId, { recommendations: [], reason: 'No PI features available' });
+            return;
+        }
+
+        const piVectors = piFeatureData.vectors;
+        const allPiIds = Object.keys(piVectors);
+
+        // ===========================================================================
+        // STEP 3: Score each candidate PI
+        // ===========================================================================
+        const scoredCandidates = [];
+
+        for (const piId of allPiIds) {
+            // Skip already copied
+            if (THRESHOLDS.excludeAlreadyCopied && copiedPiIds.has(piId)) {
+                continue;
+            }
+
+            const piFv = piVectors[piId];
+
+            // Apply quality thresholds
+            if (piFv.copiers < THRESHOLDS.minCopiers) continue;
+            if (piFv.riskScore > THRESHOLDS.maxRiskScore) continue;
+            if (piFv.gain < THRESHOLDS.minGain) continue;
+
+            // Calculate scores
+            const interestScore = this._calcInterestScore(piFv, userSectorProfile, userPreferredRiskRange);
+            const diversificationScore = this._calcDiversificationScore(piFv, userSectorProfile);
+            const qualityScore = this._calcQualityScore(piFv);
+
+            const totalScore =
+                (interestScore * WEIGHTS.interest) +
+                (diversificationScore * WEIGHTS.diversification) +
+                (qualityScore * WEIGHTS.quality);
+
+            scoredCandidates.push({
+                piId: piFv.piId,
+                username: piFv.username,
+                score: Number(totalScore.toFixed(4)),
+                breakdown: {
+                    interest: Number(interestScore.toFixed(3)),
+                    diversification: Number(diversificationScore.toFixed(3)),
+                    quality: Number(qualityScore.toFixed(3))
+                },
+                // Include key metrics for frontend
+                metrics: {
+                    riskScore: piFv.riskScore,
+                    gain: piFv.gain,
+                    copiers: piFv.copiers,
+                    winRatio: piFv.winRatio,
+                    topSectors: this._getTopSectors(piFv.sectors, 3)
+                },
+                reason: this._generateReason(diversificationScore, interestScore, piFv)
+            });
+        }
+
+        // ===========================================================================
+        // STEP 4: Rank and return top N
+        // ===========================================================================
+        const recommendations = scoredCandidates
+            .sort((a, b) => b.score - a.score)
+            .slice(0, TOP_N);
+
+        this.setResult(entityId, {
+            recommendations,
+            userProfile: {
+                topSectors: this._getTopSectors(userSectorProfile, 3),
+                preferredRiskRange: userPreferredRiskRange,
+                currentCopies: copiedPiIds.size
+            },
+            metadata: {
+                candidatesScored: scoredCandidates.length,
+                totalPIs: allPiIds.length,
+                computedAt: targetDate
+            }
+        });
+    }
+
+    // ===========================================================================
+    // SCORING FUNCTIONS
+    // ===========================================================================
+
+    /**
+     * Interest score: How well does the PI match user preferences?
+     * Higher = more aligned with sectors/risk they seem to like
+     */
+    _calcInterestScore(piFv, userSectorProfile, preferredRiskRange) {
+        // Sector overlap (dot product of normalized vectors)
+        let sectorOverlap = 0;
+        Object.entries(userSectorProfile).forEach(([sector, userWeight]) => {
+            const piWeight = piFv.sectors[sector] || 0;
+            sectorOverlap += userWeight * piWeight;
+        });
+
+        // Risk preference match (1 = perfect match, 0 = way off)
+        const riskMatch = preferredRiskRange.min !== null
+            ? 1 - Math.min(1, Math.abs(piFv.riskScore - preferredRiskRange.avg) / 5)
+            : 0.5;  // Neutral if no preference detected
+
+        return (sectorOverlap * 0.6) + (riskMatch * 0.4);
+    }
+
+    /**
+     * Diversification score: How different is the PI from current portfolio?
+     * Higher = more different = better for diversification
+     */
+    _calcDiversificationScore(piFv, userSectorProfile) {
+        // Calculate sector distance (1 - overlap)
+        let overlap = 0;
+        let userMagnitude = 0;
+        let piMagnitude = 0;
+
+        Object.keys(piFv.sectors).forEach(sector => {
+            const userWeight = userSectorProfile[sector] || 0;
+            const piWeight = piFv.sectors[sector] || 0;
+
+            overlap += userWeight * piWeight;
+            userMagnitude += userWeight * userWeight;
+            piMagnitude += piWeight * piWeight;
+        });
+
+        userMagnitude = Math.sqrt(userMagnitude);
+        piMagnitude = Math.sqrt(piMagnitude);
+
+        // Cosine similarity → distance
+        const cosineSim = (userMagnitude > 0 && piMagnitude > 0)
+            ? overlap / (userMagnitude * piMagnitude)
+            : 0;
+
+        const diversityScore = 1 - cosineSim;
+
+        // Bonus for low concentration (well-diversified PI)
+        const concentrationBonus = (1 - piFv.concentration) * 0.3;
+
+        return Math.min(1, diversityScore + concentrationBonus);
+    }
+
+    /**
+     * Quality score: How good is the PI objectively?
+     * Combines performance, popularity, and track record
+     */
+    _calcQualityScore(piFv) {
+        // Normalize gain to 0-1 scale (-50% to +100% typical range)
+        const gainNorm = Math.max(0, Math.min(1, (piFv.gain + 50) / 150));
+
+        // Win ratio already 0-100, normalize
+        const winRatioNorm = piFv.winRatio / 100;
+
+        // Copiers (log scale, cap at ~10k)
+        const copiersNorm = Math.min(1, Math.log10(Math.max(1, piFv.copiers)) / 4);
+
+        // Risk-adjusted (lower risk = bonus)
+        const riskBonus = (10 - piFv.riskScore) / 10 * 0.2;
+
+        return (gainNorm * 0.35) + (winRatioNorm * 0.25) + (copiersNorm * 0.2) + riskBonus;
+    }
+
+    // ===========================================================================
+    // HELPERS
+    // ===========================================================================
+
+    _inferRiskPreference(mirrors, rules) {
+        if (!mirrors || mirrors.length === 0) {
+            return { min: null, max: null, avg: null };
+        }
+
+        const riskScores = mirrors
+            .map(m => m.RiskScore || 5)
+            .filter(r => r > 0 && r <= 10);
+
+        if (riskScores.length === 0) {
+            return { min: null, max: null, avg: null };
+        }
+
+        return {
+            min: Math.min(...riskScores),
+            max: Math.max(...riskScores),
+            avg: riskScores.reduce((a, b) => a + b, 0) / riskScores.length
+        };
+    }
+
+    _getTopSectors(sectorWeights, n) {
+        return Object.entries(sectorWeights)
+            .filter(([_, weight]) => weight > 0.01)
+            .sort((a, b) => b[1] - a[1])
+            .slice(0, n)
+            .map(([sector, weight]) => ({
+                sector,
+                weight: Number((weight * 100).toFixed(1))
+            }));
+    }
+
+    _generateReason(divScore, intScore, piFv) {
+        if (divScore > 0.7) {
+            return `Diversifies your portfolio with ${this._getTopSectors(piFv.sectors, 1)[0]?.sector || 'different'} exposure`;
+        }
+        if (intScore > 0.6) {
+            return `Matches your investing style with ${piFv.gain.toFixed(0)}% returns`;
+        }
+        if (piFv.copiers > 1000) {
+            return `Popular choice with ${piFv.copiers.toLocaleString()} copiers`;
+        }
+        return `Balanced recommendation with ${piFv.winRatio}% win ratio`;
+    }
+}
+
+module.exports = PiRecommender;

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

@@ -6,17 +6,17 @@ class RiskScoreIncrease extends Computation {
         return {
             name: 'RiskScoreIncrease',
             // V2 Migration: Switch to per-entity for parallel processing
-            type: 'per-entity', 
+            type: 'per-entity',
             category: 'alerts',
             isHistorical: true,
-            
+
             // V2 Migration: Define strict data requirements
             requires: {
-                'rankings': {
+                'pi_rankings': {
                     lookback: 1, // Fetches Today + Yesterday
                     mandatory: true,
                     // Optimization: Only fetch needed fields
-                    fields: ['user_id', 'rankings_data', 'date'],
+                    fields: ['pi_id', 'rankings_data', 'date'],
                     // Filter applied at data fetch level (replacing V1 userType logic)
                     filter: { user_type: 'POPULAR_INVESTOR' }
                 }
@@ -28,7 +28,7 @@ class RiskScoreIncrease extends Computation {
                 firestore: {
                     enabled: true,
                     // Ensures V1 alert system can find the document
-                    path: 'alerts/{date}/RiskScoreIncrease/{entityId}', 
+                    path: 'alerts/{date}/RiskScoreIncrease/{entityId}',
                     merge: true
                 }
             },
@@ -44,7 +44,7 @@ class RiskScoreIncrease extends Computation {
                 description: 'Alert when a Popular Investor\'s risk score increases',
                 messageTemplate: '{piUsername}\'s risk score increased by {change} points (from {previous} to {current})',
                 severity: 'high',
-                configKey: 'increasedRisk', 
+                configKey: 'increasedRisk',
                 isDynamic: true,
                 dynamicConfig: {
                     thresholds: [
@@ -72,9 +72,9 @@ class RiskScoreIncrease extends Computation {
                         }
                     ],
                     resultFields: {
-                        change: 'change',           
-                        newValue: 'currentRisk',    
-                        oldValue: 'previousRisk'    
+                        change: 'change',
+                        newValue: 'currentRisk',
+                        oldValue: 'previousRisk'
                     }
                 }
             }
@@ -87,15 +87,15 @@ class RiskScoreIncrease extends Computation {
         // 1. Data Access
         // In V2 with lookback: 1, this is an array of entries sorted by date
         const rankingHistory = data['rankings'] || [];
-        
+
         // Find today's and yesterday's entries specifically by date string
         const todayEntry = rankingHistory.find(d => d.date === date);
-        
+
         // Calculate yesterday's date string for lookup
         const yesterdayDate = new Date(date);
         yesterdayDate.setDate(yesterdayDate.getDate() - 1);
         const yesterdayStr = yesterdayDate.toISOString().split('T')[0];
-        
+
         const yesterdayEntry = rankingHistory.find(d => d.date === yesterdayStr);
 
         // 2. Business Logic (Using Rules)
@@ -112,7 +112,7 @@ class RiskScoreIncrease extends Computation {
         // If today's risk data is missing, we cannot evaluate
         if (currentRisk === null || currentRisk === undefined) {
             this.log('WARN', `No current risk data for ${entityId}`);
-            return; 
+            return;
         }
 
         // 4. Comparison Logic

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

@@ -0,0 +1,138 @@
+const { Computation } = require('../framework');
+
+class SignedInUserMirrorHistory extends Computation {
+    static getConfig() {
+        return {
+            name: 'SignedInUserMirrorHistory',
+            type: 'per-entity',
+            category: 'signed_in_user',
+            
+            // CRITICAL: Must be historical to accumulate the "Past" list over time
+            // without needing huge lookbacks.
+            isHistorical: true, 
+            
+            requires: {
+                'portfolio_snapshots': {
+                    lookback: 0,
+                    mandatory: true,
+                    fields: ['user_id', 'portfolio_data', 'date']
+                },
+                // Reduced from 90 to 30 to comply with DAG limits
+                'trade_history_snapshots': {
+                    lookback: 30, 
+                    mandatory: false,
+                    fields: ['user_id', 'history_data']
+                },
+                'pi_master_list': {
+                    lookback: 1,
+                    mandatory: false,
+                    fields: ['cid', 'username']
+                }
+            },
+            
+            storage: {
+                bigquery: true,
+                firestore: {
+                    enabled: true,
+                    path: 'users/{entityId}/mirror_history',
+                    merge: true
+                }
+            }
+        };
+    }
+
+    async process(context) {
+        const { data, entityId, rules, previousResult } = context;
+
+        // 1. Setup & Username Map
+        const masterList = data['pi_master_list'] || [];
+        const usernameMap = new Map();
+        const toArray = (input) => Array.isArray(input) ? input : Object.values(input || {});
+        
+        toArray(masterList).forEach(row => {
+            if (row.cid && row.username) usernameMap.set(String(row.cid), row.username);
+        });
+
+        // 2. Determine CURRENT Mirrors (From Today's Portfolio)
+        const currentMap = new Map();
+        const portfolioRow = data['portfolio_snapshots'];
+        
+        if (portfolioRow) {
+            const pData = rules.portfolio.extractPortfolioData(portfolioRow);
+            const rawMirrors = rules.portfolio.extractMirrors(pData); 
+            
+            rawMirrors.forEach(m => {
+                const cid = String(m.ParentCID || m.MirrorID);
+                if (cid && cid !== '0') {
+                    currentMap.set(cid, {
+                        cid: Number(cid),
+                        username: usernameMap.get(cid) || m.ParentUsername || 'Unknown',
+                        invested: m.Invested || 0,
+                        profit: m.NetProfit || 0,
+                        status: 'active',
+                        startedAt: m.InitDate || null 
+                    });
+                }
+            });
+        }
+
+        // 3. Determine PAST Mirrors (Merge Previous State + New Closures)
+        const pastMap = new Map();
+
+        // A. Load existing past mirrors from yesterday's result
+        if (previousResult && Array.isArray(previousResult.past)) {
+            previousResult.past.forEach(pm => pastMap.set(String(pm.cid), pm));
+        }
+
+        // B. Detect New Closures (Was in Previous Current, NOT in Today's Current)
+        if (previousResult && Array.isArray(previousResult.current)) {
+            previousResult.current.forEach(prevCurr => {
+                const cidStr = String(prevCurr.cid);
+                if (!currentMap.has(cidStr)) {
+                    // This mirror was active yesterday but is gone today -> It closed.
+                    pastMap.set(cidStr, {
+                        ...prevCurr,
+                        status: 'closed',
+                        closedAt: context.date, // Mark closure date as today
+                        invested: 0 // Reset invested for closed items
+                    });
+                }
+            });
+        }
+
+        // C. Supplement with Trade History (Only look back 30 days for metadata)
+        // This catches any explicit "Stop Copy" events that might provide better metadata
+        const historyRows = data['trade_history_snapshots'] || [];
+        historyRows.forEach(row => {
+            const trades = rules.trades.extractTrades(row);
+            trades.forEach(trade => {
+                const parentCID = trade.ParentCID || trade.MirrorID || trade.CopyTraderID;
+                const cidStr = String(parentCID);
+                
+                // If we found a past interaction that isn't currently active
+                if (parentCID && cidStr !== '0' && !currentMap.has(cidStr)) {
+                    if (!pastMap.has(cidStr)) {
+                        // Found a copy in history that wasn't in our previous state
+                        // (e.g. from before we started tracking, or within the 30d window)
+                        pastMap.set(cidStr, {
+                            cid: Number(parentCID),
+                            username: usernameMap.get(cidStr) || 'Unknown',
+                            status: 'closed',
+                            lastInteraction: rules.trades.getCloseDate(trade) || row.date
+                        });
+                    }
+                }
+            });
+        });
+
+        // 4. Final Output
+        this.setResult(entityId, {
+            current: Array.from(currentMap.values()),
+            past: Array.from(pastMap.values()),
+            totalUniqueCopied: currentMap.size + pastMap.size,
+            updatedAt: new Date().toISOString()
+        });
+    }
+}
+
+module.exports = SignedInUserMirrorHistory;

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

@@ -0,0 +1,106 @@
+const { Computation } = require('../framework');
+
+class SignedInUserPIProfileMetrics extends Computation {
+    static getConfig() {
+        return {
+            name: 'SignedInUserPIProfileMetrics',
+            type: 'per-entity',
+            category: 'signed_in_user',
+            isHistorical: true,
+            userType: 'SIGNED_IN_USER',
+
+            requires: {
+                // DRIVER TABLE
+                // lookback: 0 prevents "All history" fetch.
+                // filter: user_type ensures only signed-in users are fetched.
+                'portfolio_snapshots': {
+                    lookback: 0,
+                    mandatory: true,
+                    fields: ['user_id', 'user_type', 'portfolio_data', 'date'],
+                    filter: { user_type: 'SIGNED_IN_USER' }
+                },
+                'trade_history_snapshots': {
+                    lookback: 0,
+                    fields: ['user_id', 'user_type', 'history_data', 'date'],
+                    filter: { user_type: 'SIGNED_IN_USER' }
+                },
+                'ticker_mappings': { mandatory: false, fields: ['instrument_id', 'ticker'] },
+                'sector_mappings': { mandatory: false, fields: ['symbol', 'sector'] }
+            },
+
+            storage: {
+                bigquery: true,
+                firestore: {
+                    enabled: true,
+                    path: 'users/{entityId}/pi_profile_metrics/{date}',
+                    merge: true
+                }
+            }
+        };
+    }
+
+    async process(context) {
+        const { data, entityId, rules, dataFetcher } = context;
+        const portfolioRow = data['portfolio_snapshots'];
+
+        // Guard clause REMOVED to prove framework filtering works
+
+        // 2. PI STATUS CHECK (Intersection)
+        // Dynamically verify if this specific customer ID exists in the master list.
+        const piCheck = await dataFetcher.fetch({
+            table: 'pi_master_list',
+            filter: { cid: parseInt(entityId, 10) },
+            fields: ['cid'],
+            lookback: 0
+        });
+
+        if (!piCheck || piCheck.length === 0) {
+            return;
+        }
+
+        // 3. CORE LOGIC
+        const result = {
+            isPopularInvestor: true,
+            portfolioSummary: { totalValue: 0, profitPercent: 0, winRatio: 0 },
+            sectorExposure: {},
+            updatedAt: new Date().toISOString()
+        };
+
+        const pData = rules.portfolio.extractPortfolioData(portfolioRow);
+        const positions = rules.portfolio.extractPositions(pData);
+
+        result.portfolioSummary = {
+            totalValue: rules.portfolio.calculateTotalValue(positions),
+            profitPercent: rules.portfolio.calculateWeightedProfitPercent(positions),
+            winRatio: rules.portfolio.calculateWinRatio(positions)
+        };
+
+        const tickerMap = this._buildTickerMap(data['ticker_mappings']);
+        const sectorMap = this._buildSectorMap(data['sector_mappings']);
+        const instrumentSectorMap = {};
+        Object.keys(tickerMap).forEach(instId => {
+            const ticker = tickerMap[instId];
+            if (sectorMap[ticker]) instrumentSectorMap[instId] = sectorMap[ticker];
+        });
+
+        result.sectorExposure = rules.portfolio.calculateSectorExposure(positions, instrumentSectorMap);
+
+        this.setResult(entityId, result);
+    }
+
+    _buildTickerMap(rows) {
+        const map = {};
+        const arr = Array.isArray(rows) ? rows : Object.values(rows || {});
+        arr.forEach(r => { if (r.instrument_id) map[r.instrument_id] = r.ticker; });
+        return map;
+    }
+
+    _buildSectorMap(rows) {
+        const map = {};
+        const arr = Array.isArray(rows) ? rows : Object.values(rows || {});
+        arr.forEach(r => { if (r.symbol) map[r.symbol] = r.sector; });
+        return map;
+    }
+}
+
+module.exports = SignedInUserPIProfileMetrics;