aiden-shared-calculations-unified 1.0.63 → 1.0.65

package/calculations/pnl/profitability_skew_per_stock.js

@@ -1,38 +1,83 @@
 /**
- * @fileoverview Calculates the magnitude of profitable vs. unprofitable positions for each stock,
- * providing insight into the skew of returns.
+ * @fileoverview Calculation (Pass 1) for profitability skew.
+ *
+_ This metric answers: "For each stock, what is the sum and
+ * count of *profits* and *losses*?"
+ *
+ * This helps determine if returns are skewed (e.g., many small
+ * wins and a few huge losses).
  */
 const { loadInstrumentMappings } = require('../../utils/sector_mapping_provider');
 
 class ProfitabilitySkewPerStock {
     constructor() {
-        this.skewData = {};
+        // { [instrumentId]: { profit_sum: 0, profit_count: 0, loss_sum: 0, loss_count: 0 } }
+        this.assets = new Map();
         this.mappings = null;
     }
 
-    process(portfolioData, yesterdayPortfolio, userId, context) {
-        const positions = portfolioData.AggregatedPositions || portfolioData.PublicPositions;
-        if (!positions) return;
-
-        for (const position of positions) {
-            const instrumentId = position.InstrumentID;
-            const netProfit = position.NetProfit;
-
-            if (!this.skewData[instrumentId]) {
-                this.skewData[instrumentId] = {
-                    profit_sum: 0,
-                    loss_sum: 0,
-                    profitable_count: 0,
-                    unprofitable_count: 0
-                };
-            }
+    /**
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
+     */
+    static getSchema() {
+        const tickerSchema = {
+            "type": "object",
+            "description": "P&L skew metrics for a specific asset.",
+            "properties": {
+                "profit_sum": { "type": "number" },
+                "profit_count": { "type": "number" },
+                "loss_sum": { "type": "number" },
+                "loss_count": { "type": "number" },
+                "skew_ratio": {
+                    "type": ["number", "null"],
+                    "description": "Ratio of (Average Profit / Average Loss). Null if no losses."
+                }
+            },
+            "required": ["profit_sum", "profit_count", "loss_sum", "loss_count", "skew_ratio"]
+        };
+
+        return {
+            "type": "object",
+            "description": "Calculates the skew of returns (avg profit vs. avg loss) for each asset.",
+            "patternProperties": {
+                "^.*$": tickerSchema // Ticker
+            },
+            "additionalProperties": tickerSchema
+        };
+    }
+
+    _initAsset(instrumentId) {
+        if (!this.assets.has(instrumentId)) {
+            this.assets.set(instrumentId, {
+                profit_sum: 0,
+                profit_count: 0,
+                loss_sum: 0, // Will be negative
+                loss_count: 0
+            });
+        }
+    }
 
-            if (netProfit > 0) {
-                this.skewData[instrumentId].profit_sum += netProfit;
-                this.skewData[instrumentId].profitable_count++;
-            } else if (netProfit < 0) {
-                this.skewData[instrumentId].loss_sum += netProfit; // Keep it negative to sum up losses
-                this.skewData[instrumentId].unprofitable_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);
+            const pnl = pos.NetProfit || 0;
+
+            if (pnl > 0) {
+                assetData.profit_sum += pnl;
+                assetData.profit_count++;
+            } else if (pnl < 0) {
+                assetData.loss_sum += pnl;
+                assetData.loss_count++;
             }
         }
     }
@@ -41,17 +86,27 @@ class ProfitabilitySkewPerStock {
         if (!this.mappings) {
             this.mappings = await loadInstrumentMappings();
         }
+
         const result = {};
-        for (const instrumentId in this.skewData) {
-            const ticker = this.mappings.instrumentToTicker[instrumentId] || instrumentId.toString();
-            result[ticker] = this.skewData[instrumentId];
+        for (const [instrumentId, data] of this.assets.entries()) {
+            const ticker = this.mappings.instrumentToTicker[instrumentId] || `id_${instrumentId}`;
+            
+            const avgProfit = (data.profit_count > 0) ? (data.profit_sum / data.profit_count) : 0;
+            const avgLoss = (data.loss_count > 0) ? (Math.abs(data.loss_sum) / data.loss_count) : 0;
+
+            result[ticker] = {
+                profit_sum: data.profit_sum,
+                profit_count: data.profit_count,
+                loss_sum: data.loss_sum,
+                loss_count: data.loss_count,
+                skew_ratio: (avgLoss > 0) ? (avgProfit / avgLoss) : null
+            };
         }
-        if (Object.keys(result).length === 0) return {};
-        return { profitability_skew_by_asset: result };
+        return result;
     }
 
     reset() {
-        this.skewData = {};
+        this.assets.clear();
         this.mappings = null;
     }
 }

package/calculations/pnl/profitable_and_unprofitable_status.js

@@ -1,65 +1,65 @@
 /**
- * @fileoverview Counts the number of users whose overall portfolio is in profit vs. loss for the current day.
+ * @fileoverview Calculation (Pass 1) for overall profitable status.
+ *
+ * This metric answers: "How many users have an *overall portfolio*
+ * in profit versus in loss today?"
  */
-
-class DailyUserPnlStatus {
+class ProfitableAndUnprofitableStatus {
     constructor() {
-        // Initialize counters
-        this.profitableUsers = 0;
-        this.unprofitableUsers = 0;
+        this.total_in_profit = 0;
+        this.total_in_loss = 0;
     }
 
     /**
-     * Processes a single user's portfolio for the current day.
-     * @param {object} todayPortfolio - The portfolio data for the current day.
-     * @param {object} yesterdayPortfolio - Not used in this calculation.
-     * @param {string} userId - The user's ID.
-     * @param {object} context - Shared context data (not used here).
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
      */
-    process(todayPortfolio, yesterdayPortfolio, userId, context) {
-        // Prefer AggregatedPositions as it typically contains NetProfit
-        const positions = todayPortfolio?.AggregatedPositions || todayPortfolio?.PublicPositions;
-
-        // Ensure we have portfolio data and positions
-        if (!positions || !Array.isArray(positions) || positions.length === 0) {
-            return; // Skip if no positions data for the user today
-        }
-
-        // Calculate the sum of NetProfit across all positions for the user
-        let totalUserPnl = 0;
-        for (const position of positions) {
-            // Ensure NetProfit exists and is a number, default to 0 otherwise
-            totalUserPnl += (typeof position.NetProfit === 'number' ? position.NetProfit : 0);
-        }
+    static getSchema() {
+        return {
+            "type": "object",
+            "description": "Tracks the count of users whose *overall portfolio* is in profit vs. in loss.",
+            "properties": {
+                "total_in_profit": {
+                    "type": "number",
+                    "description": "Count of users with a total portfolio P&L > 0."
+                },
+                "total_in_loss": {
+                    "type": "number",
+                    "description": "Count of users with a total portfolio P&L < 0."
+                },
+                "profit_ratio_pct": {
+                    "type": "number",
+                    "description": "Percentage of users in profit (In Profit / Total)."
+                }
+            },
+            "required": ["total_in_profit", "total_in_loss", "profit_ratio_pct"]
+        };
+    }
 
-        // Increment the appropriate counter based on the total P/L
-        if (totalUserPnl > 0) {
-            this.profitableUsers++;
-        } else if (totalUserPnl < 0) {
-            this.unprofitableUsers++;
+    process(portfolioData) {
+        // Use the P&L from the summary, which is for the *day*
+        const dailyPnl = portfolioData.Summary?.NetProfit || 0;
+        
+        if (dailyPnl > 0) {
+            this.total_in_profit++;
+        } else if (dailyPnl < 0) {
+            this.total_in_loss++;
         }
-        // Users with exactly zero P/L are ignored
     }
 
-    /**
-     * Returns the final aggregated counts.
-     * @returns {object} Object containing the counts of profitable and unprofitable users.
-     */
     getResult() {
-        // Return the raw counts
+        const total = this.total_in_profit + this.total_in_loss;
         return {
-            profitable_user_count: this.profitableUsers,
-            unprofitable_user_count: this.unprofitableUsers
+            total_in_profit: this.total_in_profit,
+            total_in_loss: this.total_in_loss,
+            profit_ratio_pct: (total > 0) ? (this.total_in_profit / total) * 100 : 0
         };
     }
 
-    /**
-     * Resets the internal counters for the next processing run.
-     */
     reset() {
-        this.profitableUsers = 0;
-        this.unprofitableUsers = 0;
+        this.total_in_profit = 0;
+        this.total_in_loss = 0;
     }
 }
 
-module.exports = DailyUserPnlStatus;
+module.exports = ProfitableAndUnprofitableStatus;

package/calculations/sanity/users_processed.js

@@ -7,12 +7,35 @@ class UsersProcessed {
         this.userCount = 0;
     }
 
+    /**
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
+     */
+    static getSchema() {
+        return {
+            "type": "object",
+            "description": "A simple counter for the total number of users processed.",
+            "properties": {
+                "rawTotalUsersProcessed": {
+                    "type": "number",
+                    "description": "The total count of users processed by the computation system."
+                }
+            },
+            "required": ["rawTotalUsersProcessed"]
+        };
+    }
+
     process(portfolioData, yesterdayPortfolio, userId, context) {
         this.userCount++;
     }
 
     getResult() {
-        if (this.userCount === 0) return {};
+        if (this.userCount === 0) {
+            // Even if 0, we should return the defined schema shape
+            return {
+                rawTotalUsersProcessed: 0
+            };
+        }
         // FIX: Rename the key to use the 'raw' prefix for correct aggregation.
         return {
             rawTotalUsersProcessed: this.userCount

package/calculations/sectors/historical/diversification_pnl.js

@@ -1,76 +1,138 @@
-// CORRECTED PATH: ../utils/ instead of ../../utils/
-const { getInstrumentSectorMap } = require('../../../utils/sector_mapping_provider');
-
 /**
- * Aggregates P/L by the number of unique sectors a user is invested in.
+ * @fileoverview Calculation (Pass 2) for P&L by diversification.
+ *
+ * This metric answers: "What is the average daily P&L for users,
+ * bucketed by the number of *unique sectors* they are invested in?"
  */
+const { loadInstrumentMappings } = require('../../../utils/sector_mapping_provider');
+
 class DiversificationPnl {
     constructor() {
-        this.pnl_by_sector_count = {};
-        this.sectorMapping = null;
-    }
-
-    _initBucket(count) {
-        if (!this.pnl_by_sector_count[count]) {
-            this.pnl_by_sector_count[count] = { pnl_sum: 0, count: 0 };
-        }
+        // { [bucket]: { pnl_sum: 0, user_count: 0 } }
+        this.buckets = {
+            '1': { pnl_sum: 0, user_count: 0 },
+            '2-3': { pnl_sum: 0, user_count: 0 },
+            '4-5': { pnl_sum: 0, user_count: 0 },
+            '6-10': { pnl_sum: 0, user_count: 0 },
+            '11+': { pnl_sum: 0, user_count: 0 },
+        };
+        this.mappings = null;
     }
 
     /**
-     * FIX: Helper function to calculate total P&L from positions
-     * @param {object} portfolio
-     * @returns {number|null}
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
      */
-    _calculateTotalPnl(portfolio) {
-        const positions = portfolio?.AggregatedPositions || portfolio?.PublicPositions;
-        if (positions && Array.isArray(positions)) {
-            // Sum all NetProfit fields, defaulting to 0 if a position has no NetProfit
-            return positions.reduce((sum, pos) => sum + (pos.NetProfit || 0), 0);
-        }
+    static getSchema() {
+        const bucketSchema = {
+            "type": "object",
+            "description": "Aggregated P&L metrics for a sector diversification bucket.",
+            "properties": {
+                "average_daily_pnl": {
+                    "type": "number",
+                    "description": "The average daily P&L for users in this bucket."
+                },
+                "user_count": {
+                    "type": "number",
+                    "description": "The number of users in this bucket."
+                },
+                "pnl_sum": {
+                    "type": "number",
+                    "description": "The sum of all P&L for users in this bucket."
+                }
+            },
+            "required": ["average_daily_pnl", "user_count", "pnl_sum"]
+        };
+        
+        return {
+            "type": "object",
+            "description": "Average daily P&L bucketed by the number of unique sectors a user is invested in.",
+            "properties": {
+                "1": bucketSchema,
+                "2-3": bucketSchema,
+                "4-5": bucketSchema,
+                "6-10": bucketSchema,
+                "11+": bucketSchema
+            },
+            "required": ["1", "2-3", "4-5", "6-10", "11+"]
+        };
+    }
+
+    _getBucket(count) {
+        if (count === 1) return '1';
+        if (count >= 2 && count <= 3) return '2-3';
+        if (count >= 4 && count <= 5) return '4-5';
+        if (count >= 6 && count <= 10) return '6-10';
+        if (count >= 11) return '11+';
         return null;
     }
 
-    async process(todayPortfolio, yesterdayPortfolio, userId) { // Added async
-        // FIX: Only need todayPortfolio for this logic
+    process(todayPortfolio, yesterdayPortfolio, userId, context) {
+        // This calculation only needs today's portfolio state
         if (!todayPortfolio) {
             return;
         }
-         
-        if(!this.sectorMapping) {
-            this.sectorMapping = await getInstrumentSectorMap();
+        
+        if (!this.mappings) {
+            // Context contains the mappings loaded in Pass 1
+            this.mappings = context.mappings;
         }
 
         const positions = todayPortfolio.AggregatedPositions || todayPortfolio.PublicPositions;
-
-        if (!positions || !Array.isArray(positions)) {
+        if (!positions || !Array.isArray(positions) || !this.mappings) {
             return;
         }
-
+        
+        // Find unique sectors for this user
         const uniqueSectors = new Set();
-        for (const position of positions) {
-            const sector = this.sectorMapping[position.InstrumentID] || 'Other';
-            uniqueSectors.add(sector);
+        for (const pos of positions) {
+            const instrumentId = pos.InstrumentID;
+            if (instrumentId) {
+                const sector = this.mappings.instrumentToSector[instrumentId] || 'Other';
+                uniqueSectors.add(sector);
+            }
         }
-
+        
         const sectorCount = uniqueSectors.size;
         if (sectorCount === 0) {
             return;
         }
 
-        // FIX: Calculate dailyPnl by summing NetProfit from all positions
-        const dailyPnl = this._calculateTotalPnl(todayPortfolio);
-
-        if (dailyPnl === null) {
-            return; // Cannot calculate P&L for this user
+        const bucketKey = this._getBucket(sectorCount);
+        if (!bucketKey) {
+            return;
         }
 
-        this._initBucket(sectorCount);
-        this.pnl_by_sector_count[sectorCount].pnl_sum += dailyPnl;
-        this.pnl_by_sector_count[sectorCount].count++;
+        // Use the P&L from the summary, which is for the *day*
+        const dailyPnl = todayPortfolio.Summary?.NetProfit || 0;
+        
+        const bucket = this.buckets[bucketKey];
+        bucket.pnl_sum += dailyPnl;
+        bucket.user_count++;
     }
 
     getResult() {
-        return this.pnl_by_sector_count;
+        const result = {};
+        for (const key in this.buckets) {
+            const bucket = this.buckets[key];
+            result[key] = {
+                average_daily_pnl: (bucket.user_count > 0) ? (bucket.pnl_sum / bucket.user_count) : 0,
+                user_count: bucket.user_count,
+                pnl_sum: bucket.pnl_sum
+            };
+        }
+        return result;
+    }
+
+    reset() {
+        this.buckets = {
+            '1': { pnl_sum: 0, user_count: 0 },
+            '2-3': { pnl_sum: 0, user_count: 0 },
+            '4-5': { pnl_sum: 0, user_count: 0 },
+            '6-10': { pnl_sum: 0, user_count: 0 },
+            '11+': { pnl_sum: 0, user_count: 0 },
+        };
+        this.mappings = null;
     }
 }
 

package/calculations/sectors/historical/sector_rotation.js

@@ -1,68 +1,117 @@
 /**
- * @fileoverview Analyzes sector rotation by comparing investment amounts between two days.
+ * @fileoverview Calculation (Pass 2) for sector rotation.
+ *
+ * This metric answers: "What is the net change in investment
+ * (as a portfolio percentage) for each sector today?"
+ *
+ * This measures which sectors the crowd is rotating into or out of.
  */
-// CORRECTED PATH: ../utils/ instead of ../../utils/
-const { getInstrumentSectorMap } = require('../../../utils/sector_mapping_provider');
+const { loadInstrumentMappings } = require('../../../utils/sector_mapping_provider');
 
 class SectorRotation {
-    // ... (rest of the code is unchanged) ...
     constructor() {
-        this.todaySectorInvestment = {};
-        this.yesterdaySectorInvestment = {};
-        this.sectorMap = null;
+        // We will store { [sector]: { y_invested_sum: 0, t_invested_sum: 0 } }
+        this.sectors = new Map();
+        this.mappings = null;
     }
 
-    async process(todayPortfolio, yesterdayPortfolio, userId) {
-        if (!this.sectorMap) {
-            this.sectorMap = await getInstrumentSectorMap();
-        }
+    /**
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
+     */
+    static getSchema() {
+        const sectorSchema = {
+            "type": "object",
+            "description": "Net change in portfolio allocation for a specific sector.",
+            "properties": {
+                "net_change_pct": {
+                    "type": "number",
+                    "description": "The net change in percentage allocation (Today Sum - Yesterday Sum)."
+                },
+                "y_total_invested_pct": {
+                    "type": "number",
+                    "description": "Total portfolio percentage invested in this sector yesterday."
+                },
+                "t_total_invested_pct": {
+                    "type": "number",
+                    "description": "Total portfolio percentage invested in this sector today."
+                }
+            },
+            "required": ["net_change_pct", "y_total_invested_pct", "t_total_invested_pct"]
+        };
+        
+        return {
+            "type": "object",
+            "description": "Calculates the net rotation of portfolio percentage allocation between sectors.",
+            "patternProperties": {
+                "^.*$": sectorSchema // Sector name
+            },
+            "additionalProperties": sectorSchema
+        };
+    }
 
-        if (todayPortfolio) {
-            this.accumulateSectorInvestment(todayPortfolio, this.todaySectorInvestment);
-        }
-        if (yesterdayPortfolio) {
-            this.accumulateSectorInvestment(yesterdayPortfolio, this.yesterdaySectorInvestment);
+    _initSector(sector) {
+        if (!this.sectors.has(sector)) {
+            this.sectors.set(sector, {
+                y_invested_sum: 0,
+                t_invested_sum: 0
+            });
         }
     }
 
-    accumulateSectorInvestment(portfolio, target) {
-        // Use AggregatedPositions, as PublicPositions don't have Invested amount
-        if (portfolio && portfolio.AggregatedPositions) {
-            for (const pos of portfolio.AggregatedPositions) {
-                 // Check if sectorMap is loaded before accessing it
-                 if (!this.sectorMap) {
-                     console.warn('Sector map not loaded in accumulateSectorInvestment');
-                     continue; // or handle appropriately
-                 }
-                const sector = this.sectorMap[pos.InstrumentID] || 'N/A';
-                if (!target[sector]) {
-                    target[sector] = 0;
-                }
-                // Use Invested amount if available, otherwise fallback might be needed
-                target[sector] += (pos.Invested || pos.Amount || 0); // Added fallback
+    _sumSectorAllocations(portfolio, mapKey) {
+        const positions = portfolio?.AggregatedPositions; // Must use Aggregated for 'Invested' %
+        if (!positions || !Array.isArray(positions) || !this.mappings) {
+            return;
+        }
+
+        for (const pos of positions) {
+            const instrumentId = pos.InstrumentID;
+            if (instrumentId) {
+                const sector = this.mappings.instrumentToSector[instrumentId] || 'Other';
+                this._initSector(sector);
+                
+                const investedPct = pos.InvestedAmount || pos.Invested || 0;
+                this.sectors.get(sector)[mapKey] += investedPct;
             }
         }
-         // Optional: Handle PublicPositions if needed, though they lack 'Invested'
-         else if (portfolio && portfolio.PublicPositions) {
-             // Logic to handle PublicPositions if necessary, e.g., using 'Amount'
-             // console.warn("Using PublicPositions for sector rotation, 'Invested' amount missing.");
-         }
     }
 
+    process(todayPortfolio, yesterdayPortfolio, userId, context) {
+        if (!todayPortfolio || !yesterdayPortfolio) {
+            return;
+        }
 
-    getResult() {
-        const sectorRotationData = {};
-        const allSectors = new Set([...Object.keys(this.todaySectorInvestment), ...Object.keys(this.yesterdaySectorInvestment)]);
+        if (!this.mappings) {
+            // Context contains the mappings loaded in Pass 1
+            this.mappings = context.mappings;
+        }
+        
+        this._sumSectorAllocations(yesterdayPortfolio, 'y_invested_sum');
+        this._sumSectorAllocations(todayPortfolio, 't_invested_sum');
+    }
 
-        for (const sector of allSectors) {
-            const todayAmount = this.todaySectorInvestment[sector] || 0;
-            const yesterdayAmount = this.yesterdaySectorInvestment[sector] || 0;
-            sectorRotationData[sector] = todayAmount - yesterdayAmount;
+    getResult() {
+        const result = {};
+        for (const [sector, data] of this.sectors.entries()) {
+            const netChange = data.t_invested_sum - data.y_invested_sum;
+            
+            // Only report sectors that had some activity
+            if (data.t_invested_sum > 0 || data.y_invested_sum > 0) {
+                result[sector] = {
+                    net_change_pct: netChange,
+                    y_total_invested_pct: data.y_invested_sum,
+                    t_total_invested_pct: data.t_invested_sum
+                };
+            }
         }
+        return result;
+    }
 
-        return { sector_rotation: sectorRotationData };
+    reset() {
+        this.sectors.clear();
+        this.mappings = null;
     }
 }
 
-
 module.exports = SectorRotation;