bulltrackers-module 1.0.733 → 1.0.734

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

@@ -0,0 +1,176 @@
+/**
+ * @fileoverview Popular Investor Risk Assessment - v2
+ * 
+ * This computation DEPENDS on PopularInvestorProfileMetrics.
+ * It uses the profile metrics to calculate additional risk assessments.
+ * 
+ * This tests:
+ * 1. Dependency declaration works
+ * 2. Pass assignment is incremented (should be Pass 2)
+ * 3. Dependency data is loaded and passed to process()
+ */
+
+const { Computation } = require('../framework');
+
+class PopularInvestorRiskAssessment extends Computation {
+    
+    static getConfig() {
+        return {
+            name: 'PopularInvestorRiskAssessment',
+            category: 'popular_investor',
+            
+            // Only needs rankings for additional risk factors
+            requires: {
+                'pi_rankings': {
+                    lookback: 0,
+                    mandatory: true,
+                    filter: null
+                }
+            },
+            
+            // DEPENDS ON PopularInvestorProfileMetrics!
+            dependencies: ['PopularInvestorProfileMetrics'],
+            
+            type: 'per-entity',
+            isHistorical: false,
+            ttlDays: 30
+        };
+    }
+    
+    static getSchema() {
+        return {
+            type: 'object',
+            properties: {
+                riskScore: { type: 'number' },
+                riskLevel: { type: 'string' },
+                diversificationScore: { type: 'number' },
+                volatilityScore: { type: 'number' },
+                concentrationRisk: { type: 'number' },
+                sectorConcentration: { type: 'object' },
+                recommendations: { type: 'array' }
+            }
+        };
+    }
+    
+    static getWeight() {
+        return 3.0;
+    }
+    
+    async process(context) {
+        const { date, entityId: userId, data, dependencies } = context;
+        
+        // Get the profile metrics from our dependency
+        const profileMetrics = dependencies?.['popularinvestorprofilemetrics']?.[userId];
+        
+        // Get rankings data
+        const rankingsData = data['pi_rankings'];
+        const rankEntry = this._findRankEntry(rankingsData, userId);
+        
+        // Initialize result
+        const result = {
+            riskScore: 0,
+            riskLevel: 'Unknown',
+            diversificationScore: 0,
+            volatilityScore: 0,
+            concentrationRisk: 0,
+            sectorConcentration: {},
+            recommendations: []
+        };
+        
+        // If we don't have profile metrics, we can still calculate basic risk from rankings
+        if (rankEntry) {
+            const riskScore = rankEntry.RiskScore || rankEntry.riskScore || 0;
+            result.riskScore = riskScore;
+            result.riskLevel = this._getRiskLevel(riskScore);
+        }
+        
+        // If we have profile metrics, enhance the assessment
+        if (profileMetrics) {
+            // Use sector exposure for diversification analysis
+            const sectorExposure = profileMetrics.sectorExposure?.data || {};
+            const sectors = Object.keys(sectorExposure);
+            
+            if (sectors.length > 0) {
+                // Diversification score (more sectors = better diversification)
+                result.diversificationScore = Math.min(100, sectors.length * 15);
+                
+                // Concentration risk (highest sector weight)
+                const maxExposure = Math.max(...Object.values(sectorExposure), 0);
+                result.concentrationRisk = maxExposure;
+                
+                // Copy sector breakdown
+                result.sectorConcentration = sectorExposure;
+                
+                // Generate recommendations
+                if (maxExposure > 50) {
+                    result.recommendations.push(`High concentration in single sector (${maxExposure.toFixed(1)}%). Consider diversifying.`);
+                }
+                if (sectors.length < 3) {
+                    result.recommendations.push('Portfolio is concentrated in few sectors. Consider adding exposure to other sectors.');
+                }
+            }
+            
+            // Use portfolio summary for additional risk factors
+            const portfolioSummary = profileMetrics.portfolioSummary || {};
+            if (portfolioSummary.profitPercent < -10) {
+                result.recommendations.push('Portfolio showing significant losses. Review position sizing.');
+            }
+            
+            // Use rankings data from profile for win ratio analysis
+            const rankingsFromProfile = profileMetrics.rankingsData || {};
+            if (rankingsFromProfile.winRatio < 0.5) {
+                result.volatilityScore = 80;  // Lower win ratio = higher volatility risk
+                result.recommendations.push('Win ratio below 50%. Trading strategy may need review.');
+            } else {
+                result.volatilityScore = Math.max(0, 100 - (rankingsFromProfile.winRatio * 100));
+            }
+            
+            // Adjust overall risk score based on analysis
+            const adjustedRisk = (
+                (result.riskScore * 0.4) +
+                (result.concentrationRisk * 0.3) +
+                (result.volatilityScore * 0.3)
+            );
+            result.riskScore = Math.round(adjustedRisk);
+            result.riskLevel = this._getRiskLevel(result.riskScore);
+        }
+        
+        this.setResult(userId, result);
+    }
+    
+    _findRankEntry(rankings, userId) {
+        if (!rankings) return null;
+        
+        // Rankings might be date-keyed or an array
+        if (typeof rankings === 'object' && !Array.isArray(rankings)) {
+            const dates = Object.keys(rankings).sort().reverse();
+            for (const dateStr of dates) {
+                const dayRankings = rankings[dateStr];
+                if (Array.isArray(dayRankings)) {
+                    const entry = dayRankings.find(r => 
+                        String(r.CustomerId || r.pi_id || r.userId) === String(userId)
+                    );
+                    if (entry) return entry;
+                }
+            }
+        }
+        
+        if (Array.isArray(rankings)) {
+            return rankings.find(r => 
+                String(r.CustomerId || r.pi_id || r.userId) === String(userId)
+            );
+        }
+        
+        return null;
+    }
+    
+    _getRiskLevel(score) {
+        if (score <= 2) return 'Very Low';
+        if (score <= 4) return 'Low';
+        if (score <= 6) return 'Medium';
+        if (score <= 8) return 'High';
+        return 'Very High';
+    }
+}
+
+module.exports = PopularInvestorRiskAssessment;

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

@@ -0,0 +1,294 @@
+/**
+ * @fileoverview Popular Investor Risk Metrics Computation
+ * 
+ * Calculates comprehensive risk metrics for each popular investor:
+ * - Sharpe Ratio (risk-adjusted returns)
+ * - Sortino Ratio (downside risk)
+ * - Max Drawdown
+ * - Win Ratio
+ * - Portfolio concentration
+ * 
+ * This computation demonstrates:
+ * - Using both metrics and portfolio rules
+ * - Per-entity computation pattern
+ * - Dual storage (BigQuery + Firestore)
+ * - User-centric Firestore path
+ */
+
+const { Computation } = require('../framework');
+
+class PopularInvestorRiskMetrics extends Computation {
+    static getConfig() {
+        return {
+            name: 'PopularInvestorRiskMetrics',
+            category: 'risk_analytics',
+            
+            // Data requirements
+            requires: {
+                'portfolio_snapshots': {
+                    lookback: 30,  // Need 30 days of history for risk metrics
+                    mandatory: true,
+                    filter: { user_type: 'POPULAR_INVESTOR' }
+                },
+                'trade_history_snapshots': {
+                    lookback: 30,
+                    mandatory: false  // Optional, used for trade-based metrics
+                }
+            },
+            
+            // No computation dependencies
+            dependencies: [],
+            
+            // Per-entity means we process each user separately
+            type: 'per-entity',
+            
+            // Keep 90 days of history
+            ttlDays: 90,
+            
+            // Schedule: Run daily at 3 AM
+            schedule: {
+                frequency: 'daily',
+                time: '03:00'
+            },
+            
+            // =========================================================================
+            // STORAGE: Write to both BigQuery and Firestore
+            // =========================================================================
+            storage: {
+                // BigQuery: for analytics queries and as dependency for other computations
+                bigquery: true,
+                
+                // Firestore: for real-time frontend access
+                // Each user gets their risk metrics in their user document
+                firestore: {
+                    enabled: true,
+                    path: '/users/{entityId}/computations/risk_metrics',
+                    merge: false,  // Overwrite the entire document
+                    includeMetadata: true  // Include _computedAt, _codeHash, etc.
+                }
+            }
+        };
+    }
+    
+    static getSchema() {
+        return {
+            type: 'object',
+            properties: {
+                userId: { type: 'string' },
+                date: { type: 'string' },
+                
+                // Portfolio overview
+                portfolioValue: { type: 'number' },
+                positionCount: { type: 'number' },
+                
+                // Risk metrics
+                sharpeRatio: { type: 'number' },
+                sortinoRatio: { type: 'number' },
+                maxDrawdown: { type: 'number' },
+                valueAtRisk95: { type: 'number' },
+                
+                // Performance metrics
+                winRatio: { type: 'number' },
+                avgDailyReturn: { type: 'number' },
+                returnVolatility: { type: 'number' },
+                
+                // Concentration metrics
+                top3Concentration: { type: 'number' },
+                
+                // Risk grade (A-F)
+                riskGrade: { type: 'string' }
+            },
+            required: ['userId', 'date', 'riskGrade']
+        };
+    }
+    
+    static getWeight() {
+        return 2.0;  // Higher weight = more expensive
+    }
+    
+    /**
+     * Process a single investor's risk metrics.
+     */
+    async process(context) {
+        const { date, entityId, data, rules } = context;
+        
+        const portfolioHistory = data['portfolio_snapshots'];
+        
+        // Need portfolio history to calculate risk metrics
+        if (!portfolioHistory || !Array.isArray(portfolioHistory) || portfolioHistory.length === 0) {
+            this.log('DEBUG', `No portfolio history for user ${entityId}`);
+            this.setResult(entityId, this._emptyResult(entityId, date));
+            return;
+        }
+        
+        // Sort by date ascending
+        const sortedHistory = [...portfolioHistory].sort((a, b) => 
+            new Date(a.date || a.snapshot_date) - new Date(b.date || b.snapshot_date)
+        );
+        
+        // =====================================================================
+        // STEP 1: Extract daily portfolio values and calculate returns
+        // =====================================================================
+        
+        const dailyValues = sortedHistory.map(snapshot => {
+            const positions = rules.portfolio.extractPositions(snapshot);
+            return rules.portfolio.calculateTotalValue(positions);
+        });
+        
+        // Calculate daily returns (percentage change)
+        const dailyReturns = [];
+        for (let i = 1; i < dailyValues.length; i++) {
+            if (dailyValues[i - 1] > 0) {
+                const returnPct = ((dailyValues[i] - dailyValues[i - 1]) / dailyValues[i - 1]) * 100;
+                dailyReturns.push(returnPct);
+            }
+        }
+        
+        // Need at least a few returns for meaningful metrics
+        if (dailyReturns.length < 5) {
+            this.log('DEBUG', `Insufficient return history for user ${entityId}: ${dailyReturns.length} days`);
+            this.setResult(entityId, this._emptyResult(entityId, date));
+            return;
+        }
+        
+        // =====================================================================
+        // STEP 2: Calculate risk metrics using rules.metrics
+        // =====================================================================
+        
+        // Sharpe Ratio (risk-free rate = 4% annualized)
+        const sharpeRatio = rules.metrics.calculateSharpeRatio(dailyReturns, 4, 252);
+        
+        // Sortino Ratio (target return = 0)
+        const sortinoRatio = rules.metrics.calculateSortinoRatio(dailyReturns, 0, 252);
+        
+        // Max Drawdown
+        const { maxDrawdown } = rules.metrics.calculateMaxDrawdown(dailyValues);
+        
+        // Value at Risk (95% confidence)
+        const valueAtRisk95 = rules.metrics.calculateVaR(dailyReturns, 0.95);
+        
+        // Basic statistics
+        const avgDailyReturn = rules.metrics.mean(dailyReturns);
+        const returnVolatility = rules.metrics.standardDeviation(dailyReturns);
+        
+        // =====================================================================
+        // STEP 3: Calculate portfolio metrics using rules.portfolio
+        // =====================================================================
+        
+        // Get latest portfolio snapshot
+        const latestSnapshot = sortedHistory[sortedHistory.length - 1];
+        const positions = rules.portfolio.extractPositions(latestSnapshot);
+        
+        const portfolioValue = rules.portfolio.calculateTotalValue(positions);
+        const positionCount = positions.length;
+        const winRatio = rules.portfolio.calculateWinRatio(positions);
+        
+        // Calculate concentration (top 3 positions as % of portfolio)
+        const top3 = rules.portfolio.getTopPositions(positions, 3);
+        const top3Value = top3.reduce((sum, pos) => sum + rules.portfolio.getValue(pos), 0);
+        const top3Concentration = portfolioValue > 0 ? (top3Value / portfolioValue) * 100 : 0;
+        
+        // =====================================================================
+        // STEP 4: Calculate risk grade (A-F based on combined metrics)
+        // =====================================================================
+        
+        const riskGrade = this._calculateRiskGrade({
+            sharpeRatio,
+            sortinoRatio,
+            maxDrawdown,
+            winRatio,
+            top3Concentration
+        }, rules);
+        
+        // =====================================================================
+        // STEP 5: Build and store result
+        // =====================================================================
+        
+        this.setResult(entityId, {
+            userId: entityId,
+            date,
+            
+            // Portfolio overview
+            portfolioValue: rules.metrics.round(portfolioValue, 2),
+            positionCount,
+            
+            // Risk metrics (annualized where applicable)
+            sharpeRatio: rules.metrics.round(sharpeRatio, 3),
+            sortinoRatio: rules.metrics.round(sortinoRatio, 3),
+            maxDrawdown: rules.metrics.round(maxDrawdown, 2),
+            valueAtRisk95: rules.metrics.round(valueAtRisk95, 2),
+            
+            // Performance
+            winRatio: rules.metrics.round(winRatio, 4),
+            avgDailyReturn: rules.metrics.round(avgDailyReturn, 4),
+            returnVolatility: rules.metrics.round(returnVolatility, 4),
+            
+            // Concentration
+            top3Concentration: rules.metrics.round(top3Concentration, 2),
+            
+            // Overall grade
+            riskGrade,
+            
+            // Metadata for debugging
+            daysAnalyzed: dailyReturns.length + 1
+        });
+    }
+    
+    /**
+     * Calculate a risk grade from A (best) to F (worst).
+     */
+    _calculateRiskGrade(metrics, rules) {
+        let score = 50;  // Start at middle
+        
+        // Sharpe Ratio: > 2 is excellent, < 0.5 is poor
+        if (metrics.sharpeRatio > 2) score += 20;
+        else if (metrics.sharpeRatio > 1) score += 10;
+        else if (metrics.sharpeRatio < 0.5) score -= 10;
+        else if (metrics.sharpeRatio < 0) score -= 20;
+        
+        // Max Drawdown: < 10% is good, > 30% is poor
+        if (metrics.maxDrawdown < 10) score += 15;
+        else if (metrics.maxDrawdown < 20) score += 5;
+        else if (metrics.maxDrawdown > 30) score -= 15;
+        else if (metrics.maxDrawdown > 50) score -= 25;
+        
+        // Win Ratio: > 60% is good, < 40% is poor
+        if (metrics.winRatio > 0.6) score += 10;
+        else if (metrics.winRatio < 0.4) score -= 10;
+        
+        // Concentration: > 50% in top 3 is risky
+        if (metrics.top3Concentration > 70) score -= 15;
+        else if (metrics.top3Concentration > 50) score -= 5;
+        else if (metrics.top3Concentration < 30) score += 5;
+        
+        // Clamp and convert to grade
+        score = rules.metrics.clamp(score, 0, 100);
+        
+        if (score >= 80) return 'A';
+        if (score >= 65) return 'B';
+        if (score >= 50) return 'C';
+        if (score >= 35) return 'D';
+        return 'F';
+    }
+    
+    _emptyResult(entityId, date) {
+        return {
+            userId: entityId,
+            date,
+            portfolioValue: 0,
+            positionCount: 0,
+            sharpeRatio: 0,
+            sortinoRatio: 0,
+            maxDrawdown: 0,
+            valueAtRisk95: 0,
+            winRatio: 0,
+            avgDailyReturn: 0,
+            returnVolatility: 0,
+            top3Concentration: 0,
+            riskGrade: 'N/A',
+            daysAnalyzed: 0
+        };
+    }
+}
+
+module.exports = PopularInvestorRiskMetrics;

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

@@ -0,0 +1,46 @@
+/**
+ * @fileoverview Test Computation for E2E Verification
+ */
+const { Computation } = require('../framework');
+
+class TestComputation extends Computation {
+    static getConfig() {
+        return {
+            name: 'TestComputation',
+            version: '1.0.0',
+            type: 'per-entity', // Forces the Streaming/Batching path
+            schedule: 'daily',
+            requires: {
+                // We will mock these tables in the test
+                users: { fields: ['id', 'status'], mandatory: true },
+                transactions: { fields: ['userId', 'amount'], mandatory: false }
+            },
+            dependencies: []
+        };
+    }
+
+    async process(context) {
+        const { entityId, data, rules } = context;
+        
+        // 1. Validate Data Injection
+        const user = data.users;
+        const txs = data.transactions || []; // Should be array of transactions for this user
+
+        // 2. Validate Rule Injection (Dynamic)
+        // We expect the test framework to provide a mock rule named 'math'
+        const multiplier = rules.math ? rules.math.double(1) : 1; 
+
+        // 3. Perform Calculation
+        const totalAmount = txs.reduce((sum, t) => sum + t.amount, 0);
+        
+        // 4. Return Result
+        this.results[entityId] = {
+            userId: entityId,
+            score: totalAmount * multiplier,
+            status: user.status,
+            processedAt: new Date().toISOString()
+        };
+    }
+}
+
+module.exports = TestComputation;

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

@@ -0,0 +1,172 @@
+/**
+ * @fileoverview User Portfolio Summary - v2 Computation
+ * 
+ * This computation demonstrates the "simple recipe" pattern:
+ * - No complex calculations inline
+ * - Uses injected rules for all business logic
+ * - The computation itself just orchestrates
+ * 
+ * When rules.portfolio changes, this computation automatically re-runs
+ * because the rules hash is included in the computation hash.
+ */
+
+const { Computation } = require('../framework');
+
+class UserPortfolioSummary extends Computation {
+    /**
+     * Configuration - What the framework needs to know.
+     */
+    static getConfig() {
+        return {
+            name: 'UserPortfolioSummary',
+            category: 'analytics',
+            
+            requires: {
+                'portfolio_snapshots': {
+                    lookback: 0,
+                    mandatory: true,
+                    filter: { user_type: 'POPULAR_INVESTOR' }
+                },
+                'asset_prices': {
+                    lookback: 0,
+                    mandatory: true
+                }
+            },
+            
+            dependencies: [],
+            type: 'per-entity',
+            ttlDays: 30,
+            
+            // =========================================================================
+            // STORAGE CONFIGURATION
+            // =========================================================================
+            // Controls where computation results are persisted.
+            // BigQuery is always enabled unless explicitly set to false.
+            // Firestore is opt-in for frontend-facing, user-centric data.
+            // =========================================================================
+            storage: {
+                // BigQuery: always enabled by default (for analytics, dependency resolution)
+                bigquery: true,
+                
+                // Firestore: user-centric storage for real-time frontend access
+                firestore: {
+                    enabled: true,
+                    // Path template - {entityId} replaced with user ID, {date} with computation date
+                    // This stores each user's portfolio summary in their user document
+                    path: '/users/{entityId}/computations/portfolio_summary',
+                    
+                    // merge: false = overwrite entire document (default)
+                    // merge: true  = merge with existing fields
+                    merge: false,
+                    
+                    // Include metadata (_computedAt, _computationDate, _codeHash)
+                    includeMetadata: true
+                }
+            }
+        };
+    }
+    
+    static getSchema() {
+        return {
+            type: 'object',
+            properties: {
+                userId: { type: 'string' },
+                date: { type: 'string' },
+                totalValue: { type: 'number' },
+                totalInvested: { type: 'number' },
+                profitLoss: { type: 'number' },
+                profitLossPercent: { type: 'number' },
+                positionCount: { type: 'number' },
+                winRatio: { type: 'number' },
+                topPositions: { type: 'array' }
+            },
+            required: ['userId', 'date', 'totalValue']
+        };
+    }
+    
+    static getWeight() {
+        return 1.5;
+    }
+    
+    /**
+     * Process a single user's portfolio.
+     * 
+     * NOTE: This is a "simple recipe" - it uses injected rules for all
+     * business logic. The computation just orchestrates the rules.
+     * 
+     * Benefits:
+     * - Rules are the single source of truth
+     * - When rules change, this computation re-runs automatically
+     * - Easy to understand what calculations are being done
+     * - Easy to test rules in isolation
+     */
+    async process(context) {
+        const { date, entityId, data, rules } = context;
+        
+        const portfolio = data['portfolio_snapshots'];
+        const prices = data['asset_prices'];
+        
+        // No data = no result
+        if (!portfolio) {
+            this.log('DEBUG', `No portfolio for user ${entityId}`);
+            return;
+        }
+        
+        // =====================================================================
+        // USE INJECTED RULES - No inline business logic!
+        // =====================================================================
+        
+        // Extract positions using portfolio rules
+        const positions = rules.portfolio.extractPositions(portfolio);
+        
+        if (!positions || positions.length === 0) {
+            this.setResult(entityId, this._emptyResult(entityId, date));
+            return;
+        }
+        
+        // Calculate portfolio metrics using portfolio rules
+        const totalValue = rules.portfolio.calculateTotalValue(positions);
+        const totalInvested = rules.portfolio.calculateTotalInvested(positions);
+        const profitLossPercent = rules.portfolio.calculateWeightedProfitPercent(positions);
+        const winRatio = rules.portfolio.calculateWinRatio(positions);
+        const topPositions = rules.portfolio.getTopPositions(positions, 5);
+        
+        // Use metrics rules for rounding
+        const profitLoss = rules.metrics.round(totalValue - totalInvested, 2);
+        
+        // Build result
+        this.setResult(entityId, {
+            userId: entityId,
+            date,
+            totalValue: rules.metrics.round(totalValue, 2),
+            totalInvested: rules.metrics.round(totalInvested, 2),
+            profitLoss,
+            profitLossPercent: rules.metrics.round(profitLossPercent, 2),
+            positionCount: positions.length,
+            winRatio: rules.metrics.round(winRatio, 4),
+            topPositions: topPositions.map(pos => ({
+                instrumentId: rules.portfolio.getInstrumentId(pos),
+                value: rules.metrics.round(rules.portfolio.getValue(pos), 2),
+                percentOfPortfolio: totalValue > 0 
+                    ? rules.metrics.round((rules.portfolio.getValue(pos) / totalValue) * 100, 2)
+                    : 0
+            }))
+        });
+    }
+    
+    _emptyResult(entityId, date) {
+        return {
+            userId: entityId,
+            date,
+            totalValue: 0,
+            totalInvested: 0,
+            profitLoss: 0,
+            profitLossPercent: 0,
+            positionCount: 0,
+            winRatio: 0,
+            topPositions: []
+        };
+    }
+}
+
+module.exports = UserPortfolioSummary;