aiden-shared-calculations-unified 1.0.63 → 1.0.65

package/calculations/pnl/asset_pnl_status.js

@@ -1,46 +1,135 @@
 /**
- * Counts the number of users in profit vs. loss for each asset (from our sample).
- * This data is used for extrapolation with the ground truth owner count.
+ * @fileoverview Calculation (Pass 1) for asset P&L status.
+ *
+ * This metric answers: "For each asset, how many users in our
+ * sample are in profit versus in loss?"
+ *
+ * This provides a crowd-wide P&L status for each instrument.
  */
+const { loadInstrumentMappings } = require('../../utils/sector_mapping_provider');
+
 class AssetPnlStatus {
     constructor() {
-        this.assets = {};
+        // We will store { [instrumentId]: { in_profit: Set(), in_loss: Set() } }
+        this.assets = new Map();
+        this.mappings = null;
+    }
+
+    /**
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
+     */
+    static getSchema() {
+        const userSchema = {
+            "type": "object",
+            "properties": {
+                "userId": { "type": "string" },
+                "pnl": { "type": "number" }
+            },
+            "required": ["userId", "pnl"]
+        };
+
+        const tickerSchema = {
+            "type": "object",
+            "description": "P&L status for a specific asset.",
+            "properties": {
+                "in_profit_count": {
+                    "type": "number",
+                    "description": "Count of users currently in profit on this asset."
+                },
+                "in_loss_count": {
+                    "type": "number",
+                    "description": "Count of users currently in loss on this asset."
+                },
+                "profit_ratio": {
+                    "type": "number",
+                    "description": "Percentage of users in profit (In Profit / Total)."
+                },
+                "users_in_profit": {
+                    "type": "array",
+                    "description": "List of users in profit.",
+                    "items": userSchema
+                },
+                "users_in_loss": {
+                    "type": "array",
+                    "description": "List of users in loss.",
+                    "items": userSchema
+                }
+            },
+            "required": ["in_profit_count", "in_loss_count", "profit_ratio", "users_in_profit", "users_in_loss"]
+        };
+
+        return {
+            "type": "object",
+            "description": "Tracks the number of users in profit vs. in loss for each asset.",
+            "patternProperties": {
+                "^.*$": tickerSchema // Ticker
+            },
+            "additionalProperties": tickerSchema
+        };
     }
 
-    _initAsset(ticker) {
-        if (!this.assets[ticker]) {
-            this.assets[ticker] = { profit_count: 0, loss_count: 0 };
+    _initAsset(instrumentId) {
+        if (!this.assets.has(instrumentId)) {
+            this.assets.set(instrumentId, {
+                in_profit: new Map(), // Map<userId, pnl>
+                in_loss: new Map()   // Map<userId, pnl>
+            });
         }
     }
-    
-    process(portfolioData, yesterdayPortfolio, userId, context, todayInsights, yesterdayInsights) {
-        const { instrumentMappings } = context;
-        const processedTickers = new Set(); // Ensure one user is only counted once per ticker
-
-        // FIX: Use the correct portfolio position properties
-        const positions = portfolioData.AggregatedPositions || portfolioData.PublicPositions;
-        if (!positions || !Array.isArray(positions)) return;
-
-        for (const position of positions) {
-            // FIX: Use the correct PascalCase InstrumentID
-            const ticker = instrumentMappings[position.InstrumentID];
-            if (!ticker || processedTickers.has(ticker)) continue;
-
-            this._initAsset(ticker);
-
-            // FIX: Use the correct PascalCase NetProfit
-            if (position.NetProfit > 0) {
-                this.assets[ticker].profit_count++;
-            } else {
-                this.assets[ticker].loss_count++;
+
+    process(portfolioData, yesterdayPortfolio, userId) {
+        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 asset = this.assets.get(instrumentId);
+            const pnl = pos.NetProfit || 0;
+
+            if (pnl > 0) {
+                asset.in_profit.set(userId, pnl);
+            } else if (pnl < 0) {
+                asset.in_loss.set(userId, pnl);
+            }
+        }
+    }
+
+    async getResult() {
+        if (!this.mappings) {
+            this.mappings = await loadInstrumentMappings();
+        }
+
+        const result = {};
+        for (const [instrumentId, data] of this.assets.entries()) {
+            const ticker = this.mappings.instrumentToTicker[instrumentId] || `id_${instrumentId}`;
+            
+            const profitCount = data.in_profit.size;
+            const lossCount = data.in_loss.size;
+            const total = profitCount + lossCount;
+            
+            if (total > 0) {
+                result[ticker] = {
+                    in_profit_count: profitCount,
+                    in_loss_count: lossCount,
+                    profit_ratio: (profitCount / total) * 100,
+                    // Convert Maps to arrays of objects for the final result
+                    users_in_profit: Array.from(data.in_profit, ([userId, pnl]) => ({ userId, pnl })),
+                    users_in_loss: Array.from(data.in_loss, ([userId, pnl]) => ({ userId, pnl }))
+                };
             }
-            processedTickers.add(ticker);
         }
+        return result;
     }
 
-    getResult() {
-        // Returns raw counts for frontend extrapolation
-        return this.assets;
+    reset() {
+        this.assets.clear();
+        this.mappings = null;
     }
 }
 

package/calculations/pnl/average_daily_pnl_all_users.js

@@ -1,48 +1,63 @@
 /**
- * @fileoverview Calculates the average PnL (NetProfit %) on a per-user basis, and then averages those user PnLs.
- * This metric answers: "What was the average daily PnL for the average user?"
+ * @fileoverview Calculation (Pass 1) for average daily P&L.
+ *
+ * This metric answers: "What was the average daily P&L
+ * for the average user?"
+ *
+ * This is a global health metric for the crowd.
  */
-
 class AverageDailyPnlAllUsers {
     constructor() {
-        this.totalOfUserAveragePnls = 0;
+        this.totalPnl = 0;
         this.userCount = 0;
     }
 
-    process(portfolioData, yesterdayPortfolio, userId, context) {
-        if (!portfolioData || !portfolioData.AggregatedPositions || portfolioData.AggregatedPositions.length === 0) {
-            return;
-        }
-
-        let userTotalPnl = 0;
-        const positionCount = portfolioData.AggregatedPositions.length;
-
-        for (const position of portfolioData.AggregatedPositions) {
-            userTotalPnl += position.NetProfit;
-        }
+    /**
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
+     */
+    static getSchema() {
+        return {
+            "type": "object",
+            "description": "Calculates the average daily P&L across all users.",
+            "properties": {
+                "average_daily_pnl": {
+                    "type": "number",
+                    "description": "The average daily P&L per user (Total P&L / User Count)."
+                },
+                "total_pnl": {
+                    "type": "number",
+                    "description": "The sum of all daily P&L from all users."
+                },
+                "user_count": {
+                    "type": "number",
+                    "description": "The total number of users processed."
+                }
+            },
+            "required": ["average_daily_pnl", "total_pnl", "user_count"]
+        };
+    }
 
-        const userAveragePnl = userTotalPnl / positionCount;
-        this.totalOfUserAveragePnls += userAveragePnl;
+    process(portfolioData) {
+        // Use the P&L from the summary, which is for the *day*
+        const dailyPnl = portfolioData.Summary?.NetProfit || 0;
+        
+        this.totalPnl += dailyPnl;
         this.userCount++;
     }
 
     getResult() {
-        if (this.userCount === 0) {
-            return {};
-        }
-
-        // REFACTOR: Perform the final calculation directly.
-        const average_daily_pnl = this.totalOfUserAveragePnls / this.userCount;
-
         return {
-            average_daily_pnl: average_daily_pnl
+            average_daily_pnl: (this.userCount > 0) ? (this.totalPnl / this.userCount) : 0,
+            total_pnl: this.totalPnl,
+            user_count: this.userCount
         };
     }
 
     reset() {
-        this.totalOfUserAveragePnls = 0;
+        this.totalPnl = 0;
         this.userCount = 0;
     }
 }
 
-module.exports = AverageDailyPnlAllUsers;
+module.exports = AverageDailyPnlAllUsers;

package/calculations/pnl/average_daily_pnl_per_sector.js

@@ -1,49 +1,107 @@
 /**
- * @fileoverview Calculates the average daily PnL (NetProfit %) for each sector.
- * This is a simple average, not weighted by position size.
+ * @fileoverview Calculation (Pass 1) for average daily P&L per sector.
+ *
+ * This metric answers: "What was the average daily P&L for each sector?"
+ *
+ * This helps identify which parts of the market the crowd
+ * is performing well or poorly in.
  */
-const { getInstrumentSectorMap } = require('../../utils/sector_mapping_provider');
+const { loadInstrumentMappings } = require('../../utils/sector_mapping_provider');
 
 class AverageDailyPnlPerSector {
     constructor() {
-        this.positions = [];
+        // We will store { [sector]: { pnl_sum: 0, user_count: 0 } }
+        this.sectors = new Map();
+        this.mappings = null;
     }
 
-    process(portfolioData, yesterdayPortfolio, userId, context) {
-        if (portfolioData && portfolioData.AggregatedPositions) {
-            this.positions.push(...portfolioData.AggregatedPositions);
-        }
+    /**
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
+     */
+    static getSchema() {
+        const sectorSchema = {
+            "type": "object",
+            "description": "P&L metrics for a specific sector.",
+            "properties": {
+                "average_pnl": {
+                    "type": "number",
+                    "description": "Average P&L for this sector (Sum / User Count)."
+                },
+                "pnl_sum": {
+                    "type": "number",
+                    "description": "Sum of all P&L for this sector."
+                },
+                "user_count": {
+                    "type": "number",
+                    "description": "Count of users with positions in this sector."
+                }
+            },
+            "required": ["average_pnl", "pnl_sum", "user_count"]
+        };
+
+        return {
+            "type": "object",
+            "description": "Calculates the average daily P&L per sector.",
+            "patternProperties": {
+                "^.*$": sectorSchema // Sector name
+            },
+            "additionalProperties": sectorSchema
+        };
     }
 
-    async getResult() {
-        if (this.positions.length === 0) return {};
+    _initSector(sector) {
+        if (!this.sectors.has(sector)) {
+            this.sectors.set(sector, {
+                pnl_sum: 0,
+                users: new Set() // Use Set to count unique users
+            });
+        }
+    }
 
-        const sectorPnlSum = {};
-        const positionCountBySector = {};
-        const sectorMap = await getInstrumentSectorMap();
+    process(portfolioData, yesterdayPortfolio, userId, context) {
+        // This calculation needs the sector mappings from Pass 1 context
+        if (!this.mappings) {
+            this.mappings = context.mappings;
+        }
 
-        for (const position of this.positions) {
-            const instrumentId = position.InstrumentID;
-            const sector = sectorMap[instrumentId] || 'N/A';
+        const positions = portfolioData.PublicPositions || portfolioData.AggregatedPositions;
+        if (!positions || !Array.isArray(positions) || !this.mappings) {
+            return;
+        }
 
-            sectorPnlSum[sector] = (sectorPnlSum[sector] || 0) + position.NetProfit;
-            positionCountBySector[sector] = (positionCountBySector[sector] || 0) + 1;
+        for (const pos of positions) {
+            const instrumentId = pos.InstrumentID;
+            if (!instrumentId) continue;
+            
+            const sector = this.mappings.instrumentToSector[instrumentId] || 'Other';
+            this._initSector(sector);
+            
+            const sectorData = this.sectors.get(sector);
+            sectorData.pnl_sum += pos.NetProfit || 0;
+            sectorData.users.add(userId);
         }
+    }
 
+    getResult() {
         const result = {};
-        for (const sector in sectorPnlSum) {
-            // REFACTOR: Calculate the final average directly.
-            result[sector] = {
-                average_pnl: sectorPnlSum[sector] / positionCountBySector[sector]
-            };
+        for (const [sector, data] of this.sectors.entries()) {
+            const userCount = data.users.size;
+            if (userCount > 0) {
+                result[sector] = {
+                    average_pnl: data.pnl_sum / userCount,
+                    pnl_sum: data.pnl_sum,
+                    user_count: userCount
+                };
+            }
         }
-
         return result;
     }
 
     reset() {
-        this.positions = [];
+        this.sectors.clear();
+        this.mappings = null;
     }
 }
 
-module.exports = AverageDailyPnlPerSector;
+module.exports = AverageDailyPnlPerSector;

package/calculations/pnl/average_daily_pnl_per_stock.js

@@ -1,34 +1,77 @@
 /**
- * @fileoverview Calculates the average daily PnL (NetProfit) for each individual stock.
- * This metric answers: "What was the average PnL for a position in this specific stock?"
+ * @fileoverview Calculation (Pass 1) for average daily P&L per stock.
+ *
+ * This metric answers: "What was the average daily P&L for a
+ * position in each specific stock?"
  */
 const { loadInstrumentMappings } = require('../../utils/sector_mapping_provider');
 
 class AverageDailyPnlPerStock {
     constructor() {
-        this.pnlData = {};
+        // We will store { [instrumentId]: { pnl_sum: 0, position_count: 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": "P&L metrics for a specific asset ticker.",
+            "properties": {
+                "average_pnl": {
+                    "type": "number",
+                    "description": "Average P&L per position (Sum / Count)."
+                },
+                "pnl_sum": {
+                    "type": "number",
+                    "description": "Sum of all P&L for this asset."
+                },
+                "position_count": {
+                    "type": "number",
+                    "description": "Count of positions in this asset."
+                }
+            },
+            "required": ["average_pnl", "pnl_sum", "position_count"]
+        };
 
-        for (const position of positions) {
-            const instrumentId = position.InstrumentID;
-            const netProfit = position.NetProfit;
+        return {
+            "type": "object",
+            "description": "Calculates the average daily P&L per stock/asset.",
+            "patternProperties": {
+                "^.*$": tickerSchema // Ticker
+            },
+            "additionalProperties": tickerSchema
+        };
+    }
 
-            if (!this.pnlData[instrumentId]) {
-                this.pnlData[instrumentId] = {
-                    pnl_sum: 0,
-                    position_count: 0
-                };
-            }
+    _initAsset(instrumentId) {
+        if (!this.assets.has(instrumentId)) {
+            this.assets.set(instrumentId, {
+                pnl_sum: 0,
+                position_count: 0
+            });
+        }
+    }
 
-            this.pnlData[instrumentId].pnl_sum += netProfit;
-            this.pnlData[instrumentId].position_count++;
+    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);
+            assetData.pnl_sum += pos.NetProfit || 0;
+            assetData.position_count++;
         }
     }
 
@@ -38,25 +81,24 @@ class AverageDailyPnlPerStock {
         }
 
         const result = {};
-        for (const instrumentId in this.pnlData) {
-            const ticker = this.mappings.instrumentToTicker[instrumentId] || instrumentId.toString();
-            const data = this.pnlData[instrumentId];
+        for (const [instrumentId, data] of this.assets.entries()) {
+            const ticker = this.mappings.instrumentToTicker[instrumentId] || `id_${instrumentId}`;
             
-            // REFACTOR: Perform the final calculation directly.
             if (data.position_count > 0) {
-                 result[ticker] = {
-                    average_daily_pnl: data.pnl_sum / data.position_count
-                 };
+                result[ticker] = {
+                    average_pnl: data.pnl_sum / data.position_count,
+                    pnl_sum: data.pnl_sum,
+                    position_count: data.position_count
+                };
             }
         }
-
         return result;
     }
 
     reset() {
-        this.pnlData = {};
+        this.assets.clear();
         this.mappings = null;
     }
 }
 
-module.exports = AverageDailyPnlPerStock;
+module.exports = AverageDailyPnlPerStock;

package/calculations/pnl/average_daily_position_pnl.js

@@ -1,40 +1,68 @@
 /**
- * @fileoverview Calculates the overall average PnL (NetProfit %) across every single position held by the crowd.
- * This gives a high-level view of whether the average position is in profit or loss.
+ * @fileoverview Calculation (Pass 1) for average P&L per position.
+ *
+ * This metric answers: "What was the average P&L across all
+ * individual positions held by the crowd today?"
+ *
+ * This is different from "average P&L per user" as a user
+ * can have multiple positions.
  */
-
 class AverageDailyPositionPnl {
     constructor() {
-        this.totalNetProfit = 0;
-        this.totalPositions = 0;
+        this.totalPnl = 0;
+        this.positionCount = 0;
     }
 
-    process(portfolioData, yesterdayPortfolio, userId, context) {
-        if (portfolioData && portfolioData.AggregatedPositions) {
-            for (const position of portfolioData.AggregatedPositions) {
-                this.totalNetProfit += position.NetProfit;
-                this.totalPositions++;
-            }
-        }
+    /**
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
+     */
+    static getSchema() {
+        return {
+            "type": "object",
+            "description": "Calculates the average daily P&L across all individual positions.",
+            "properties": {
+                "average_pnl": {
+                    "type": "number",
+                    "description": "The average daily P&L per position (Total P&L / Position Count)."
+                },
+                "total_pnl": {
+                    "type": "number",
+                    "description": "The sum of all daily P&L from all positions."
+                },
+                "position_count": {
+                    "type": "number",
+                    "description": "The total number of positions processed."
+                }
+            },
+            "required": ["average_pnl", "total_pnl", "position_count"]
+        };
     }
 
-    getResult() {
-        if (this.totalPositions === 0) {
-            return {};
+    process(portfolioData) {
+        const positions = portfolioData.PublicPositions || portfolioData.AggregatedPositions;
+        if (!positions || !Array.isArray(positions)) {
+            return;
         }
 
-        // REFACTOR: Perform the final calculation directly.
-        const average_daily_position_pnl = this.totalNetProfit / this.totalPositions;
+        for (const pos of positions) {
+            this.totalPnl += pos.NetProfit || 0;
+            this.positionCount++;
+        }
+    }
 
+    getResult() {
         return {
-            average_daily_position_pnl
+            average_pnl: (this.positionCount > 0) ? (this.totalPnl / this.positionCount) : 0,
+            total_pnl: this.totalPnl,
+            position_count: this.positionCount
         };
     }
 
     reset() {
-        this.totalNetProfit = 0;
-        this.totalPositions = 0;
+        this.totalPnl = 0;
+        this.positionCount = 0;
     }
 }
 
-module.exports = AverageDailyPositionPnl;
+module.exports = AverageDailyPositionPnl;