bulltrackers-module 1.0.766 → 1.0.769

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

@@ -0,0 +1,227 @@
+/**
+ * @fileoverview PI Feature Vectors
+ * 
+ * Global computation that builds normalized feature vectors for all Popular Investors.
+ * Used by PiRecommender to find balanced recommendations.
+ * 
+ * Features computed per PI:
+ * - Sector exposure (normalized %)
+ * - Risk profile (volatility, risk score)
+ * - Performance metrics (gain %, win ratio)
+ * - Quality indicators (AUM tier, copiers)
+ */
+const { Computation } = require('../framework');
+
+class PiFeatureVectors extends Computation {
+    static getConfig() {
+        return {
+            name: 'PiFeatureVectors',
+            description: 'Computes feature vectors for all PIs for recommendation matching',
+            type: 'global',
+            category: 'popular_investor',
+            isHistorical: false,
+
+            requires: {
+                'portfolio_snapshots': {
+                    lookback: 0,
+                    mandatory: true,
+                    fields: ['user_id', 'portfolio_data', 'date'],
+                    filter: { user_type: 'POPULAR_INVESTOR' }
+                },
+                'pi_rankings': {
+                    lookback: 1,
+                    mandatory: true,
+                    fields: ['pi_id', 'rankings_data', 'username', 'date']
+                },
+                'pi_master_list': {
+                    lookback: 1,
+                    mandatory: false,
+                    fields: ['cid', 'username', 'verified_date']
+                },
+                'ticker_mappings': { mandatory: false },
+                'sector_mappings': { mandatory: false }
+            },
+
+            storage: {
+                bigquery: true,
+                firestore: { enabled: false }
+            }
+        };
+    }
+
+    async process(context) {
+        const { data, rules, targetDate } = context;
+
+        // ===========================================================================
+        // SETUP: Helpers and reference data
+        // ===========================================================================
+        const toArray = (input) => {
+            if (!input) return [];
+            if (Array.isArray(input)) return input;
+            // Handle Map-like structure from DataFetcher
+            return Object.values(input).flat();
+        };
+
+        // Build sector lookup
+        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';
+        };
+
+        // All known sectors for consistent vector dimensions
+        const ALL_SECTORS = [
+            'Technology', 'Healthcare', 'Financial Services', 'Consumer Cyclical',
+            'Industrials', 'Energy', 'Utilities', 'Real Estate', 'Communication Services',
+            'Consumer Defensive', 'Basic Materials', 'Crypto', 'Commodities', 'ETF', 'Other'
+        ];
+
+        // ===========================================================================
+        // GATHER: PI portfolio and rankings data
+        // ===========================================================================
+        const rankings = toArray(data['pi_rankings']);
+        const portfolios = data['portfolio_snapshots']; // Map { piId: [rows] }
+        const masterList = toArray(data['pi_master_list']);
+
+        // Build username lookup
+        const usernameMap = new Map();
+        rankings.forEach(r => {
+            const id = String(r.pi_id || r.CustomerId);
+            usernameMap.set(id, r.username || r.UserName);
+        });
+        masterList.forEach(m => {
+            if (m.cid && m.username) usernameMap.set(String(m.cid), m.username);
+        });
+
+        // ===========================================================================
+        // COMPUTE: Feature vectors for each PI
+        // ===========================================================================
+        const featureVectors = {};
+
+        // Process each PI's portfolio
+        const piIds = Object.keys(portfolios || {});
+
+        for (const piId of piIds) {
+            const rows = Array.isArray(portfolios[piId]) ? portfolios[piId] : [portfolios[piId]];
+            const latestRow = rows[rows.length - 1];
+            if (!latestRow) continue;
+
+            // Extract positions
+            const pData = rules.portfolio.extractPortfolioData(latestRow);
+            const positions = rules.portfolio.extractPositions(pData);
+
+            if (positions.length === 0) continue;
+
+            // Calculate sector exposure
+            const sectorWeights = {};
+            let totalValue = 0;
+
+            positions.forEach(pos => {
+                const instrumentId = rules.portfolio.getInstrumentId(pos);
+                const invested = rules.portfolio.getInvested(pos) || 0;
+                const sector = resolveSector(instrumentId);
+
+                sectorWeights[sector] = (sectorWeights[sector] || 0) + invested;
+                totalValue += invested;
+            });
+
+            // Normalize sector exposure to percentages
+            const sectorVector = {};
+            ALL_SECTORS.forEach(s => {
+                sectorVector[s] = totalValue > 0
+                    ? Number(((sectorWeights[s] || 0) / totalValue).toFixed(4))
+                    : 0;
+            });
+
+            // Get ranking data
+            if (piIds.indexOf(piId) === 0) {
+                const availableIds = rankings.map(r => r.pi_id || 'undefined').join(',');
+                console.log(`[DEBUG] Available IDs in rankings: ${availableIds}`);
+                console.log(`[DEBUG] First ranking row keys: ${Object.keys(rankings[0] || {}).join(',')}`);
+                if (rankings[0]) console.log(`[DEBUG] First ranking row pi_id: ${rankings[0].pi_id}`);
+            }
+            const rankRow = rankings.find(r => String(r.pi_id || r.CustomerId) === String(piId));
+
+            if (piIds.indexOf(piId) === 0) {
+                console.log(`[DEBUG] PiId: ${piId}`);
+                console.log(`[DEBUG] RankRow found: ${!!rankRow}`);
+                if (rankRow) {
+                    console.log(`[DEBUG] RankRow keys: ${Object.keys(rankRow).join(',')}`);
+                    console.log(`[DEBUG] RankingsData type: ${typeof rankRow.rankings_data}`);
+                    if (typeof rankRow.rankings_data === 'object') {
+                        console.log(`[DEBUG] RankingsData keys: ${Object.keys(rankRow.rankings_data).join(',')}`);
+                        console.log(`[DEBUG] RankingsData.Gain: ${rankRow.rankings_data.Gain}`);
+                    }
+                }
+            }
+
+            let riskScore = 5, gain = 0, copiers = 0, winRatio = 0, aumTier = 0;
+
+            if (rankRow) {
+                const rData = rules.rankings.extractRankingsData(rankRow);
+                if (rData) {
+                    riskScore = rules.rankings.getRiskScore(rData) || 5;
+                    gain = rules.rankings.getTotalGain(rData) || 0;
+                    copiers = rules.rankings.getCopiers(rData) || 0;
+                    winRatio = rules.rankings.getWinRatio(rData) || 0;
+                    aumTier = rules.rankings.getAUMTier(rData) || 0;
+                }
+            }
+
+            // Calculate concentration (Herfindahl index) - higher = more concentrated
+            const weights = Object.values(sectorWeights).filter(w => w > 0);
+            const hhi = totalValue > 0
+                ? weights.reduce((sum, w) => sum + Math.pow(w / totalValue, 2), 0)
+                : 1;
+
+            // Assemble feature vector
+            featureVectors[piId] = {
+                piId: String(piId),
+                username: usernameMap.get(String(piId)) || 'Unknown',
+
+                // Sector exposure (normalized)
+                sectors: sectorVector,
+
+                // Risk profile
+                riskScore: riskScore,
+                concentration: Number(hhi.toFixed(4)),  // 0-1, higher = less diversified
+
+                // Performance
+                gain: gain,
+                winRatio: winRatio,
+
+                // Quality
+                copiers: copiers,
+                aumTier: aumTier,
+                positionCount: positions.length,
+
+                // Metadata
+                totalValue: Number(totalValue.toFixed(2)),
+                computedAt: targetDate
+            };
+        }
+
+        // Store all vectors as a single global result
+        this.setResult('_global', {
+            vectors: featureVectors,
+            piCount: Object.keys(featureVectors).length,
+            sectorDimensions: ALL_SECTORS,
+            computedAt: targetDate
+        });
+    }
+}
+
+module.exports = PiFeatureVectors;

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;