aiden-shared-calculations-unified 1.0.64 → 1.0.66

package/calculations/pnl/historical/profitability_migration.js

@@ -1,58 +1,104 @@
 /**
- * @fileoverview Calculates the migration of users between profitability states.
+ * @fileoverview Calculation (Pass 2) for profitability migration.
+ *
+ * This metric answers: "How many users migrated between
+ * profitable and unprofitable states today?"
+ *
+ * It tracks the "churn" between P&L states.
  */
-
 class ProfitabilityMigration {
     constructor() {
-        this.profitableToUnprofitable = 0;
-        this.unprofitableToProfitable = 0;
-        this.remainedProfitable = 0;
-        this.remainedUnprofitable = 0;
+        this.to_profit_count = 0;
+        this.to_loss_count = 0;
+        this.remained_profit_count = 0;
+        this.remained_loss_count = 0;
+        this.total_processed = 0;
     }
 
-    process(todayPortfolio, yesterdayPortfolio, userId) {
-        if (!todayPortfolio || !yesterdayPortfolio) {
-            return;
-        }
+    /**
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
+     */
+    static getSchema() {
+        return {
+            "type": "object",
+            "description": "Tracks the migration of users between profitable and unprofitable states day-over-day.",
+            "properties": {
+                "to_profit_count": {
+                    "type": "number",
+                    "description": "Count of users who were in loss yesterday and are in profit today."
+                },
+                "to_loss_count": {
+                    "type": "number",
+                    "description": "Count of users who were in profit yesterday and are in loss today."
+                },
+                "remained_profit_count": {
+                    "type": "number",
+                    "description": "Count of users who were in profit yesterday and today."
+                },
+                "remained_loss_count": {
+                    "type": "number",
+                    "description": "Count of users who were in loss yesterday and today."
+                },
+                "total_processed": {
+                    "type": "number",
+                    "description": "Total users who had a P&L status on both days."
+                }
+            },
+            "required": ["to_profit_count", "to_loss_count", "remained_profit_count", "remained_loss_count", "total_processed"]
+        };
+    }
 
-        const todayProfit = this.calculateTotalPnl(todayPortfolio);
-        const yesterdayProfit = this.calculateTotalPnl(yesterdayPortfolio);
+    _getPnlState(portfolio) {
+        // This checks *overall portfolio* P&L for the day
+        const dailyPnl = portfolio?.Summary?.NetProfit || 0;
+        if (dailyPnl > 0) return 'profit';
+        if (dailyPnl < 0) return 'loss';
+        return 'neutral';
+    }
 
-        if (todayProfit === null || yesterdayProfit === null) {
+    process(todayPortfolio, yesterdayPortfolio) {
+        if (!todayPortfolio || !yesterdayPortfolio) {
             return;
         }
 
-        const wasProfitable = yesterdayProfit > 0;
-        const isProfitable = todayProfit > 0;
-
-        if (wasProfitable && !isProfitable) {
-            this.profitableToUnprofitable++;
-        } else if (!wasProfitable && isProfitable) {
-            this.unprofitableToProfitable++;
-        } else if (wasProfitable && isProfitable) {
-            this.remainedProfitable++;
-        } else {
-            this.remainedUnprofitable++;
+        const yState = this._getPnlState(yesterdayPortfolio);
+        const tState = this._getPnlState(todayPortfolio);
+
+        if (yState === 'neutral' || tState === 'neutral') {
+            return; // Only track transitions between profit/loss
         }
-    }
+        
+        this.total_processed++;
 
-    calculateTotalPnl(portfolio) {
-        if (portfolio && portfolio.AggregatedPositions) {
-            return portfolio.AggregatedPositions.reduce((sum, pos) => sum + pos.NetProfit, 0);
-        } else if (portfolio && portfolio.PublicPositions) {
-            return portfolio.PublicPositions.reduce((sum, pos) => sum + pos.NetProfit, 0);
+        if (yState === 'profit' && tState === 'profit') {
+            this.remained_profit_count++;
+        } else if (yState === 'loss' && tState === 'loss') {
+            this.remained_loss_count++;
+        } else if (yState === 'loss' && tState === 'profit') {
+            this.to_profit_count++;
+        } else if (yState === 'profit' && tState === 'loss') {
+            this.to_loss_count++;
         }
-        return null;
     }
 
     getResult() {
         return {
-            profitable_to_unprofitable: this.profitableToUnprofitable,
-            unprofitable_to_profitable: this.unprofitableToProfitable,
-            remained_profitable: this.remainedProfitable,
-            remained_unprofitable: this.remainedUnprofitable,
+            to_profit_count: this.to_profit_count,
+            to_loss_count: this.to_loss_count,
+            remained_profit_count: this.remained_profit_count,
+            remained_loss_count: this.remained_loss_count,
+            total_processed: this.total_processed
         };
     }
+
+    reset() {
+        this.to_profit_count = 0;
+        this.to_loss_count = 0;
+        this.remained_profit_count = 0;
+        this.remained_loss_count = 0;
+        this.total_processed = 0;
+    }
 }
 
 module.exports = ProfitabilityMigration;

package/calculations/pnl/historical/user_profitability_tracker.js

@@ -1,128 +1,131 @@
 /**
- * @fileoverview Tracks user profitability over a 7-day rolling window.
- * This version shards the output AND calculates the user's *weighted average daily PNL (as a decimal %)*.
+ * @fileoverview Calculation (Pass 2) for user profitability tracker.
+ *
+ * This metric answers: "What is each user's weighted average
+ * daily P&L, and what is their 7-day rolling profitability history?"
+ *
+ * This is a foundational calculation for identifying 'smart' and
+ * 'dumb' cohorts in later passes.
+ *
+ * It is *stateful* and requires reading the *previous day's*
+ * result of *this same calculation* from Firestore.
  */
-
-const { Firestore } = require('@google-cloud/firestore');
-const firestore = new Firestore();
-
-const NUM_SHARDS = 50;
-
 class UserProfitabilityTracker {
     constructor() {
-        // This will store { userId: { weightedPnlSum: 0, totalInvested: 0 } }
-        this.dailyData = {}; 
+        // Map<userId, { weighted_avg_pnl_7d, profitable_days_7d, pnl_history_7d: [] }>
+        this.userHistory = new Map();
     }
 
     /**
-     * Calculates the weighted PNL for the day.
-     * NetProfit is a decimal % return (e.g., 0.03)
-     * Invested is a decimal % weight (e.g., 0.05)
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
      */
-    calculateWeightedDailyPnl(portfolio) {
-        if (!portfolio || !portfolio.AggregatedPositions || portfolio.AggregatedPositions.length === 0) {
-            return { weightedPnl: 0, totalInvested: 0 };
-        }
-
-        let weightedPnlSum = 0;
-        let totalInvested = 0;
-
-        for (const pos of portfolio.AggregatedPositions) {
-            // Use NetProfit (the % return)
-            const netProfit = ('NetProfit' in pos) ? pos.NetProfit : (pos.ProfitAndLoss || 0); 
-            
-            // --- START FIX ---
-            // "Normal" user portfolios use the 'Invested' field for portfolio percentage.
-            // 'InvestedAmount' and 'Amount' are different fields.
-            const invested = pos.Invested || 0; 
-            // --- END FIX ---
-
-            if (invested > 0) {
-                weightedPnlSum += netProfit * invested;
-                totalInvested += invested;
-            }
-        }
+    static getSchema() {
+        const userDetailSchema = {
+            "type": "object",
+            "properties": {
+                "weighted_avg_pnl_7d": {
+                    "type": "number",
+                    "description": "Weighted average P&L over the last 7 days (recent days weighted more)."
+                },
+                "profitable_days_7d": {
+                    "type": "number",
+                    "description": "Count of profitable days in the last 7 days."
+                },
+                "pnl_history_7d": {
+                    "type": "array",
+                    "description": "List of the last 7 days' P&L values.",
+                    "items": { "type": "number" }
+                }
+            },
+            "required": ["weighted_avg_pnl_7d", "profitable_days_7d", "pnl_history_7d"]
+        };
 
-        return { weightedPnlSum, totalInvested };
+        return {
+            "type": "object",
+            "description": "Tracks 7-day rolling profitability for each user; used to define cohorts.",
+            "properties": {
+                "ranked_users": {
+                    "type": "array",
+                    "description": "List of all users, sorted ascending by their 7-day weighted average P&L.",
+                    "items": {
+                        "type": "object",
+                        "properties": {
+                            "userId": { "type": "string" },
+                            "weighted_avg_pnl_7d": { "type": "number" }
+                        },
+                        "required": ["userId", "weighted_avg_pnl_7d"]
+                    }
+                },
+                "user_details": {
+                    "type": "object",
+                    "description": "A map of user IDs to their detailed profitability data.",
+                    "patternProperties": {
+                        "^.*$": userDetailSchema // UserID
+                    },
+                    "additionalProperties": userDetailSchema
+                }
+            },
+            "required": ["ranked_users", "user_details"]
+        };
     }
 
-    process(todayPortfolio, yesterdayPortfolio, userId) {
-        if (!todayPortfolio) return;
-
-        const { weightedPnlSum, totalInvested } = this.calculateWeightedDailyPnl(todayPortfolio);
-
-        if (totalInvested > 0) {
-            this.dailyData[userId] = { weightedPnlSum, totalInvested };
+    _calculateWeightedAverage(history) {
+        const weights = [0.25, 0.20, 0.15, 0.12, 0.10, 0.08, 0.10]; // Example weights (sum to 1.0)
+        let weightedSum = 0;
+        
+        for (let i = 0; i < history.length; i++) {
+            // Apply weights in reverse (most recent gets highest weight)
+            weightedSum += history[i] * (weights[i] || 0);
         }
+        return weightedSum;
     }
 
-    async getResult() {
-        // --- START MODIFICATION ---
-        // If no data was processed (e.g., no portfolios found for the day),
-        // return null to allow the backfill to retry.
-        if (Object.keys(this.dailyData).length === 0) {
-            console.warn('[UserProfitabilityTracker] No daily data was processed. Returning null for backfill.');
-            return null;
-        }
-        // --- END MODIFICATION ---
-
-        const today = new Date().toISOString().slice(0, 10);
-        const results = {}; // For sharded history
-        const dailyPnlMap = {}; // For the new profile calc
-
-        // Prepare sharded data structure
-        for (let i = 0; i < NUM_SHARDS; i++) {
-            results[`user_profitability_shard_${i}`] = {};
-        }
-
-        // ... (Fetch existing shards logic, same as your file) ...
-        const shardPromises = [];
-        for (let i = 0; i < NUM_SHARDS; i++) {
-            const docRef = firestore.collection('historical_insights').doc(`user_profitability_shard_${i}`);
-            shardPromises.push(docRef.get());
-        }
-        const shardSnapshots = await Promise.all(shardPromises);
-        const existingData = shardSnapshots.map(snap => (snap.exists ? snap.data() : {}) || {});
-
-
-        for (const userId in this.dailyData) {
-            const { weightedPnlSum, totalInvested } = this.dailyData[userId];
-
-            // Calculate the final weighted average % return for the day
-            // We cap totalInvested at 1.0 (100%) in case of data issues
-            const totalWeight = Math.min(1.0, totalInvested);
-            const dailyAvgPnl = (totalWeight > 0) ? (weightedPnlSum / totalWeight) : 0;
-
-            // Store this for the profile calc dependency
-            dailyPnlMap[userId] = dailyAvgPnl;
-
-            // --- Now, update the sharded history ---
-            const shardIndex = parseInt(userId, 10) % NUM_SHARDS;
+    process(todayPortfolio, yesterdayPortfolio, userId, context, todayInsights, yesterdayInsights, fetchedDependencies) {
+        // 1. Get this user's history from *yesterday's* run of this metric
+        // This data is pre-loaded into context by the computation system
+        const yHistoryData = context.yesterdaysDependencyData['user_profitability_tracker'];
+        const userHistory = yHistoryData?.user_details?.[userId]?.pnl_history_7d || [];
+
+        // 2. Get today's P&L
+        const todayPnl = todayPortfolio?.Summary?.NetProfit || 0;
+
+        // 3. Create new 7-day history
+        const newHistory = [todayPnl, ...userHistory].slice(0, 7);
+        
+        // 4. Calculate new metrics
+        const weightedAvg = this._calculateWeightedAverage(newHistory);
+        const profitableDays = newHistory.filter(pnl => pnl > 0).length;
+
+        // 5. Store for getResult()
+        this.userHistory.set(userId, {
+            weighted_avg_pnl_7d: weightedAvg,
+            profitable_days_7d: profitableDays,
+            pnl_history_7d: newHistory
+        });
+    }
 
-            // --- START FIX for userHistory.push error ---
-            // The existing data is an object like { history: [...] }, not the array itself.
-            const userHistory = (existingData[shardIndex][userId] && existingData[shardIndex][userId].history) 
-                ? existingData[shardIndex][userId].history 
-                : [];
-            // --- END FIX ---
-            
-            // Store the decimal % pnl in the history
-            userHistory.push({ date: today, pnl: dailyAvgPnl });
-            
-            const shardKey = `user_profitability_shard_${shardIndex}`;
-            if (!results[shardKey]) results[shardKey] = {};
-            results[shardKey][userId] = { history: userHistory.slice(-7) };
-        }
+    getResult() {
+        const user_details = Object.fromEntries(this.userHistory);
+        
+        // Create the ranked list for cohorts
+        const ranked_users = Array.from(this.userHistory.entries())
+            .map(([userId, data]) => ({
+                userId: userId,
+                weighted_avg_pnl_7d: data.weighted_avg_pnl_7d
+            }))
+            // Sort ascending (lowest P&L first)
+            .sort((a, b) => a.weighted_avg_pnl_7d - b.weighted_avg_pnl_7d);
 
         return {
-            sharded_user_profitability: results,
-            daily_pnl_map: dailyPnlMap // <-- This now correctly outputs the weighted avg % PNL
+            ranked_users: ranked_users,
+            user_details: user_details
         };
     }
 
     reset() {
-        this.dailyData = {};
+        this.userHistory.clear();
     }
 }
 
-module.exports = UserProfitabilityTracker;
+module.exports = UserProfitabilityTracker;

package/calculations/pnl/pnl_distribution_per_stock.js

@@ -1,65 +1,85 @@
 /**
- * @fileoverview Aggregates P&L data points for statistical analysis.
- * This calculation is a dependency for the 'Crowd Sharpe Ratio Proxy'.
- * It gathers the sum, sum of squares, and count of P&L for each stock.
+ * @fileoverview Calculation (Pass 1) for P&L distribution.
+ *
+ * This metric answers: "What are the sum, sum of squares, and
+ * count of P&L for each stock?"
+ *
+ * This is a foundational calculation used by other metrics
+ * (like 'crowd_sharpe_ratio_proxy') to calculate variance
+ * and standard deviation.
  */
-const { loadInstrumentMappings } = require('../../utils/sector_mapping_provider');
-
+// No mappings needed here, as the consumer (e.g., Sharpe Ratio)
+// will handle the mapping. This class just aggregates by ID.
 class PnlDistributionPerStock {
     constructor() {
-        this.distributionData = {}; // { [instrumentId]: { pnl_sum: 0, pnl_sum_sq: 0, position_count: 0 } }
-        this.mappings = null;
+        // We will store { [instrumentId]: { sum: 0, sumSq: 0, count: 0 } }
+        this.assets = {};
     }
 
-    process(portfolioData, yesterdayPortfolio, userId, context) {
-        const positions = portfolioData.AggregatedPositions || portfolioData.PublicPositions;
-        if (!positions) {
-            return;
-        }
-
-        for (const position of positions) {
-            const instrumentId = position.InstrumentID;
-            // Use NetProfit (which is the P&L value)
-            const netProfit = position.NetProfit; 
-
-            // Ensure netProfit is a valid number
-            if (instrumentId && typeof netProfit === 'number' && isFinite(netProfit)) {
-                if (!this.distributionData[instrumentId]) {
-                    this.distributionData[instrumentId] = {
-                        pnl_sum: 0,
-                        pnl_sum_sq: 0, // Sum of squares
-                        position_count: 0
-                    };
+    /**
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
+     */
+    static getSchema() {
+        const distSchema = {
+            "type": "object",
+            "description": "Raw statistical components for P&L on a single asset.",
+            "properties": {
+                "sum": {
+                    "type": "number",
+                    "description": "Sum of P&L values."
+                },
+                "sumSq": {
+                    "type": "number",
+                    "description": "Sum of squared P&L values (for variance calculation)."
+                },
+                "count": {
+                    "type": "number",
+                    "description": "Count of positions."
                 }
+            },
+            "required": ["sum", "sumSq", "count"]
+        };
 
-                this.distributionData[instrumentId].pnl_sum += netProfit;
-                this.distributionData[instrumentId].pnl_sum_sq += (netProfit * netProfit); // Add the square
-                this.distributionData[instrumentId].position_count++;
-            }
-        }
+        return {
+            "type": "object",
+            "description": "Collects P&L distribution components (sum, sumSq, count) per asset, keyed by InstrumentID.",
+            "patternProperties": {
+                "^[0-9]+$": distSchema // InstrumentID (numeric string)
+            },
+            "additionalProperties": distSchema
+        };
     }
 
-    async getResult() {
-        if (!this.mappings) {
-            this.mappings = await loadInstrumentMappings();
+    process(portfolioData) {
+        const positions = portfolioData.PublicPositions || portfolioData.AggregatedPositions;
+        if (!positions || !Array.isArray(positions)) {
+            return;
         }
 
-        const result = {};
-        for (const instrumentId in this.distributionData) {
-            const ticker = this.mappings.instrumentToTicker[instrumentId] || instrumentId.toString();
-            result[ticker] = this.distributionData[instrumentId];
+        for (const pos of positions) {
+            const instrumentId = pos.InstrumentID;
+            if (!instrumentId) continue;
+            
+            if (!this.assets[instrumentId]) {
+                this.assets[instrumentId] = { sum: 0, sumSq: 0, count: 0 };
+            }
+            
+            const pnl = pos.NetProfit || 0;
+            
+            this.assets[instrumentId].sum += pnl;
+            this.assets[instrumentId].sumSq += (pnl * pnl);
+            this.assets[instrumentId].count++;
         }
+    }
 
-        if (Object.keys(result).length === 0) return {};
-        
-        return { 
-            pnl_distribution_by_asset: result 
-        };
+    getResult() {
+        // Return the raw aggregated data, keyed by instrumentId
+        return this.assets;
     }
 
     reset() {
-        this.distributionData = {};
-        this.mappings = null;
+        this.assets = {};
     }
 }
 

package/calculations/pnl/profitability_ratio_per_stock.js

@@ -1,30 +1,80 @@
 /**
- * @fileoverview Calculates the ratio of profitable vs. unprofitable positions for each stock.
+ * @fileoverview Calculation (Pass 1) for profitability ratio per stock.
+ *
+ * This metric answers: "For each stock, what is the count of
+ * profitable versus unprofitable positions?"
  */
 const { loadInstrumentMappings } = require('../../utils/sector_mapping_provider');
 
 class ProfitabilityRatioPerStock {
     constructor() {
-        this.profitabilityData = {};
+        // We will store { [instrumentId]: { profitable: 0, unprofitable: 0 } }
+        this.assets = new Map();
         this.mappings = null;
     }
 
-    process(portfolioData, yesterdayPortfolio, userId, context) {
-        const positions = portfolioData.AggregatedPositions || portfolioData.PublicPositions;
-        if (!positions) return;
+    /**
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
+     */
+    static getSchema() {
+        const tickerSchema = {
+            "type": "object",
+            "description": "Profit/loss position counts for a specific asset.",
+            "properties": {
+                "profitable_count": {
+                    "type": "number",
+                    "description": "Count of positions in profit."
+                },
+                "unprofitable_count": {
+                    "type": "number",
+                    "description": "Count of positions in loss."
+                },
+                "ratio": {
+                    "type": ["number", "null"],
+                    "description": "Ratio of profitable to unprofitable (Profit / Loss). Null if no losing positions."
+                }
+            },
+            "required": ["profitable_count", "unprofitable_count", "ratio"]
+        };
 
-        for (const position of positions) {
-            const instrumentId = position.InstrumentID;
-            const netProfit = position.NetProfit;
+        return {
+            "type": "object",
+            "description": "Calculates the count of profitable vs. unprofitable positions for each asset.",
+            "patternProperties": {
+                "^.*$": tickerSchema // Ticker
+            },
+            "additionalProperties": tickerSchema
+        };
+    }
 
-            if (!this.profitabilityData[instrumentId]) {
-                this.profitabilityData[instrumentId] = { profitable: 0, unprofitable: 0 };
-            }
+    _initAsset(instrumentId) {
+        if (!this.assets.has(instrumentId)) {
+            this.assets.set(instrumentId, {
+                profitable: 0,
+                unprofitable: 0
+            });
+        }
+    }
 
-            if (netProfit > 0) {
-                this.profitabilityData[instrumentId].profitable++;
-            } else if (netProfit < 0) {
-                this.profitabilityData[instrumentId].unprofitable++;
+    process(portfolioData) {
+        const positions = portfolioData.PublicPositions || portfolioData.AggregatedPositions;
+        if (!positions || !Array.isArray(positions)) {
+            return;
+        }
+
+        for (const pos of positions) {
+            const instrumentId = pos.InstrumentID;
+            if (!instrumentId) continue;
+            
+            this._initAsset(instrumentId);
+            const assetData = this.assets.get(instrumentId);
+            const pnl = pos.NetProfit || 0;
+
+            if (pnl > 0) {
+                assetData.profitable++;
+            } else if (pnl < 0) {
+                assetData.unprofitable++;
             }
         }
     }
@@ -33,17 +83,24 @@ class ProfitabilityRatioPerStock {
         if (!this.mappings) {
             this.mappings = await loadInstrumentMappings();
         }
+
         const result = {};
-        for (const instrumentId in this.profitabilityData) {
-            const ticker = this.mappings.instrumentToTicker[instrumentId] || instrumentId.toString();
-            result[ticker] = this.profitabilityData[instrumentId];
+        for (const [instrumentId, data] of this.assets.entries()) {
+            const ticker = this.mappings.instrumentToTicker[instrumentId] || `id_${instrumentId}`;
+            
+            if (data.profitable > 0 || data.unprofitable > 0) {
+                result[ticker] = {
+                    profitable_count: data.profitable,
+                    unprofitable_count: data.unprofitable,
+                    ratio: (data.unprofitable > 0) ? (data.profitable / data.unprofitable) : null
+                };
+            }
         }
-        if (Object.keys(result).length === 0) return {};
-        return { profitability_by_asset: result };
+        return result;
     }
 
     reset() {
-        this.profitabilityData = {};
+        this.assets.clear();
         this.mappings = null;
     }
 }