aiden-shared-calculations-unified 1.0.68 → 1.0.69

package/calculations/pnl/pnl_distribution_per_stock.js

@@ -1,56 +1,71 @@
 /**
- * @fileoverview Calculation (Pass 1) for P&L distribution.
+ * @fileoverview Calculation (Pass 1) for P&L distribution per stock.
  *
- * This metric answers: "What are the sum, sum of squares, and
- * count of P&L for each stock?"
+ * This metric tracks the distribution of P&L percentages for all open
+ * positions, grouped by instrument.
  *
- * This is a foundational calculation used by other metrics
- * (like 'crowd_sharpe_ratio_proxy') to calculate variance
- * and standard deviation.
+ * REFACTOR: This calculation now aggregates the distribution into
+ * predefined buckets on the server-side, returning a chart-ready
+ * histogram object instead of raw arrays.
  */
-// No mappings needed here, as the consumer (e.g., Sharpe Ratio)
-// will handle the mapping. This class just aggregates by ID.
+const { loadInstrumentMappings } = require('../../utils/sector_mapping_provider');
+
+// Define the P&L percentage buckets for the histogram
+const BUCKETS = [
+    { label: 'loss_heavy', min: -Infinity, max: -50 },  // > 50% loss
+    { label: 'loss_medium', min: -50, max: -25 },      // 25% to 50% loss
+    { label: 'loss_light', min: -25, max: 0 },        // 0% to 25% loss
+    { label: 'gain_light', min: 0, max: 25 },         // 0% to 25% gain
+    { label: 'gain_medium', min: 25, max: 50 },        // 25% to 50% gain
+    { label: 'gain_heavy', min: 50, max: 100 },       // 50% to 100% gain
+    { label: 'gain_extreme', min: 100, max: Infinity } // > 100% gain
+];
+
 class PnlDistributionPerStock {
     constructor() {
-        // We will store { [instrumentId]: { sum: 0, sumSq: 0, count: 0 } }
-        this.assets = {};
+        // We will store { [instrumentId]: [pnlPercent1, pnlPercent2, ...] }
+        this.pnlMap = new Map();
+        this.mappings = null;
     }
 
     /**
      * Defines the output schema for this calculation.
+     * REFACTOR: Schema now describes the server-calculated histogram.
      * @returns {object} JSON Schema object
      */
     static getSchema() {
-        const distSchema = {
+        const bucketSchema = {
             "type": "object",
-            "description": "Raw statistical components for P&L on a single asset.",
+            "description": "Histogram of P&L distribution for 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."
-                }
+                "loss_heavy": { "type": "number", "description": "Count of positions with > 50% loss" },
+                "loss_medium": { "type": "number", "description": "Count of positions with 25-50% loss" },
+                "loss_light": { "type": "number", "description": "Count of positions with 0-25% loss" },
+                "gain_light": { "type": "number", "description": "Count of positions with 0-25% gain" },
+                "gain_medium": { "type": "number", "description": "Count of positions with 25-50% gain" },
+                "gain_heavy": { "type": "number", "description": "Count of positions with 50-100% gain" },
+                "gain_extreme": { "type": "number", "description": "Count of positions with > 100% gain" },
+                "total_positions": { "type": "number", "description": "Total positions counted" }
             },
-            "required": ["sum", "sumSq", "count"]
+            "required": ["total_positions"]
         };
 
         return {
             "type": "object",
-            "description": "Collects P&L distribution components (sum, sumSq, count) per asset, keyed by InstrumentID.",
+            "description": "Calculates a histogram of P&L percentage distribution for all open positions, per asset.",
             "patternProperties": {
-                "^[0-9]+$": distSchema // InstrumentID (numeric string)
+                "^.*$": bucketSchema // Ticker
             },
-            "additionalProperties": distSchema
+            "additionalProperties": bucketSchema
         };
     }
 
+    _initAsset(instrumentId) {
+        if (!this.pnlMap.has(instrumentId)) {
+            this.pnlMap.set(instrumentId, []);
+        }
+    }
+
     process(portfolioData) {
         const positions = portfolioData.PublicPositions || portfolioData.AggregatedPositions;
         if (!positions || !Array.isArray(positions)) {
@@ -59,27 +74,64 @@ class PnlDistributionPerStock {
 
         for (const pos of positions) {
             const instrumentId = pos.InstrumentID;
-            if (!instrumentId) continue;
+            const pnlPercent = pos.ProfitRate; // ProfitRate is P&L % (e.g., 0.5 = +50%)
             
-            if (!this.assets[instrumentId]) {
-                this.assets[instrumentId] = { sum: 0, sumSq: 0, count: 0 };
+            // Ensure we have valid data
+            if (!instrumentId || typeof pnlPercent !== 'number') {
+                continue;
             }
-            
-            const pnl = pos.NetProfit || 0;
-            
-            this.assets[instrumentId].sum += pnl;
-            this.assets[instrumentId].sumSq += (pnl * pnl);
-            this.assets[instrumentId].count++;
+
+            this._initAsset(instrumentId);
+            // Convert ProfitRate (0.5) to percentage (50)
+            this.pnlMap.get(instrumentId).push(pnlPercent * 100);
         }
     }
 
-    getResult() {
-        // Return the raw aggregated data, keyed by instrumentId
-        return this.assets;
+    /**
+     * REFACTOR: This method now calculates the distribution on the server.
+     * It transforms the raw P&L arrays into histogram bucket counts.
+     */
+    async getResult() {
+        if (!this.mappings) {
+            this.mappings = await loadInstrumentMappings();
+        }
+
+        const result = {};
+
+        for (const [instrumentId, pnlValues] of this.pnlMap.entries()) {
+            const ticker = this.mappings.instrumentToTicker[instrumentId] || `id_${instrumentId}`;
+
+            // 1. Initialize the histogram object for this ticker
+            const histogram = {
+                loss_heavy: 0,
+                loss_medium: 0,
+                loss_light: 0,
+                gain_light: 0,
+                gain_medium: 0,
+                gain_heavy: 0,
+                gain_extreme: 0,
+                total_positions: pnlValues.length
+            };
+
+            // 2. Process all P&L values into the buckets
+            for (const pnl of pnlValues) {
+                for (const bucket of BUCKETS) {
+                    if (pnl >= bucket.min && pnl < bucket.max) {
+                        histogram[bucket.label]++;
+                        break; // Move to the next P&L value
+                    }
+                }
+            }
+
+            // 3. Add the aggregated histogram to the final result
+            result[ticker] = histogram;
+        }
+        return result;
     }
 
     reset() {
-        this.assets = {};
+        this.pnlMap.clear();
+        this.mappings = null;
     }
 }
 

package/calculations/pnl/profitability_ratio_per_sector,js

@@ -0,0 +1,104 @@
+/**
+ * @fileoverview Calculation (Pass 1) for P&L.
+ *
+ * This metric provides the profitability ratio (profitable positions /
+ * unprofitable positions) for all open positions, grouped by sector.
+ */
+const { loadInstrumentMappings } = require('../../utils/sector_mapping_provider');
+
+class ProfitabilityRatioPerSector {
+    constructor() {
+        // We will store { [sectorName]: { profitable: 0, unprofitable: 0 } }
+        this.sectorMap = new Map();
+        this.mappings = null;
+    }
+
+    /**
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
+     */
+    static getSchema() {
+        const sectorSchema = {
+            "type": "object",
+            "properties": {
+                "ratio": {
+                    "type": ["number", "null"],
+                    "description": "Ratio of profitable to unprofitable positions (profitable / unprofitable). Null if 0 unprofitable."
+                },
+                "profitable_count": { "type": "number" },
+                "unprofitable_count": { "type": "number" }
+            },
+            "required": ["ratio", "profitable_count", "unprofitable_count"]
+        };
+
+        return {
+            "type": "object",
+            "description": "Calculates the profitability ratio (profitable/unprofitable positions) per sector.",
+            "patternProperties": {
+                "^.*$": sectorSchema // Sector Name
+            },
+            "additionalProperties": sectorSchema
+        };
+    }
+
+    _initSector(sectorName) {
+        if (!this.sectorMap.has(sectorName)) {
+            this.sectorMap.set(sectorName, { profitable: 0, unprofitable: 0 });
+        }
+    }
+
+    async process(portfolioData) {
+        if (!this.mappings) {
+            // Load mappings on first process call
+            this.mappings = await loadInstrumentMappings();
+        }
+
+        const positions = portfolioData.PublicPositions || portfolioData.AggregatedPositions;
+        if (!positions || !Array.isArray(positions)) {
+            return;
+        }
+
+        for (const pos of positions) {
+            const instrumentId = pos.InstrumentID;
+            const pnl = pos.NetProfit;
+
+            if (!instrumentId || typeof pnl !== 'number') {
+                continue;
+            }
+            
+            // Find sector name
+            const sectorName = this.mappings.instrumentToSectorName[instrumentId] || 'N/A';
+            this._initSector(sectorName);
+            const data = this.sectorMap.get(sectorName);
+
+            // Tally
+            if (pnl > 0) {
+                data.profitable++;
+            } else if (pnl < 0) {
+                data.unprofitable++;
+            }
+            // Note: pnl === 0 is neutral and not counted in the ratio
+        }
+    }
+
+    getResult() {
+        const result = {};
+        for (const [sectorName, data] of this.sectorMap.entries()) {
+            const { profitable, unprofitable } = data;
+            
+            result[sectorName] = {
+                ratio: (unprofitable > 0) ? (profitable / unprofitable) : null,
+                profitable_count: profitable,
+                unprofitable_count: unprofitable
+            };
+        }
+        return result;
+    }
+
+    reset() {
+        this.sectorMap.clear();
+        // Do not reset mappings, it's expensive to load
+    }
+}
+
+module.exports = ProfitabilityRatioPerSector;

package/calculations/sectors/historical/diversification_pnl.js

@@ -1,138 +1,114 @@
 /**
- * @fileoverview Calculation (Pass 2) for P&L by diversification.
+ * @fileoverview Calculation (Pass 1) for Diversification vs. P&L.
  *
- * This metric answers: "What is the average daily P&L for users,
- * bucketed by the number of *unique sectors* they are invested in?"
+ * This metric answers: "Is there a correlation between the number
+ * of sectors a user is invested in and their average P&L?"
+ *
+ * REFACTOR: This calculation now aggregates the results on the server,
+ * returning the average P&L per score, not raw data arrays.
  */
-const { loadInstrumentMappings } = require('../../../utils/sector_mapping_provider');
-
 class DiversificationPnl {
     constructor() {
-        // { [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;
+        // Stores { [score]: { pnlSum: 0, count: 0 } }
+        // The 'score' is the number of unique sectors
+        this.pnlByScore = new Map();
     }
 
     /**
      * Defines the output schema for this calculation.
+     * REFACTOR: Schema now describes the final aggregated result.
      * @returns {object} JSON Schema object
      */
     static getSchema() {
-        const bucketSchema = {
+        const scoreSchema = {
             "type": "object",
-            "description": "Aggregated P&L metrics for a sector diversification bucket.",
+            "description": "Aggregated P&L data for a specific diversification score.",
             "properties": {
-                "average_daily_pnl": {
+                "average_pnl": {
                     "type": "number",
-                    "description": "The average daily P&L for users in this bucket."
+                    "description": "The average P&L (in USD) for all users with this score."
                 },
                 "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."
+                    "description": "The number of users who had this diversification score."
                 }
             },
-            "required": ["average_daily_pnl", "user_count", "pnl_sum"]
+            "required": ["average_pnl", "user_count"]
         };
-        
+
         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
+            "description": "Calculates the average P&L correlated by diversification score (number of unique sectors).",
+            "patternProperties": {
+                "^[0-9]+$": scoreSchema // Key is the score (e.g., "1", "2")
             },
-            "required": ["1", "2-3", "4-5", "6-10", "11+"]
+            "additionalProperties": scoreSchema
         };
     }
 
-    _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;
+    _initScore(score) {
+        if (!this.pnlByScore.has(score)) {
+            this.pnlByScore.set(score, { pnlSum: 0, count: 0 });
+        }
     }
 
-    process(todayPortfolio, yesterdayPortfolio, userId, context) {
-        // This calculation only needs today's portfolio state
-        if (!todayPortfolio) {
+    /**
+     * @param {object} todayPortfolio
+     * @param {object} yesterdayPortfolio
+     */
+    process(todayPortfolio, yesterdayPortfolio) {
+        const tPositions = todayPortfolio.PublicPositions || todayPortfolio.AggregatedPositions;
+        if (!tPositions || !Array.isArray(tPositions) || tPositions.length === 0) {
             return;
         }
-        
-        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) || !this.mappings) {
-            return;
-        }
-        
-        // Find unique sectors for this user
-        const uniqueSectors = new Set();
-        for (const pos of positions) {
-            const instrumentId = pos.InstrumentID;
-            if (instrumentId) {
-                const sector = this.mappings.instrumentToSector[instrumentId] || 'Other';
-                uniqueSectors.add(sector);
+        const yPortfolio = yesterdayPortfolio.Portfolio;
+        if (!yPortfolio) return;
+
+        // 1. Calculate diversification score (count of unique sectors)
+        const sectors = new Set();
+        for (const pos of tPositions) {
+            if (pos.SectorID) {
+                sectors.add(pos.SectorID);
             }
         }
-        
-        const sectorCount = uniqueSectors.size;
-        if (sectorCount === 0) {
-            return;
-        }
+        const diversificationScore = sectors.size;
 
-        const bucketKey = this._getBucket(sectorCount);
-        if (!bucketKey) {
+        // Skip users with 0 positions/sectors
+        if (diversificationScore === 0) {
             return;
         }
-
-        // 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++;
+        // 2. Get total P&L from yesterday's snapshot
+        const pnl = yPortfolio.Equity - yPortfolio.EquityBase; // Total P&L in USD
+
+        // 3. Store P&L sum and count by score
+        this._initScore(diversificationScore);
+        const data = this.pnlByScore.get(diversificationScore);
+        data.pnlSum += pnl;
+        data.count++;
     }
 
+    /**
+     * REFACTOR: This method now calculates the final average P&L per score.
+     */
     getResult() {
         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
-            };
+
+        for (const [score, data] of this.pnlByScore.entries()) {
+            if (data.count > 0) {
+                result[score] = {
+                    average_pnl: data.pnlSum / data.count,
+                    user_count: data.count
+                };
+            }
         }
+        
         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;
+        this.pnlByScore.clear();
     }
 }
 

package/calculations/speculators/historical/risk_appetite_change.js

@@ -1,19 +1,15 @@
 /**
- * @fileoverview Calculation (Pass 2) for speculator metric.
+ * @fileoverview Calculation (Pass 1) for speculator metric.
  *
- * This metric answers: "What is the daily change in
- * speculators' risk appetite, as measured by the
- * average distance of their stop-loss orders?"
- *
- * This is a *stateful* calculation that computes a 30-day
- * rolling average.
+ * This metric tracks the change in a speculator's risk appetite by
+ * comparing the "risk" of their portfolio today vs. yesterday.
+ * Risk is defined as (TotalLeveragedInvestment / TotalInvestment).
  */
+
 class RiskAppetiteChange {
     constructor() {
-        // Stores *today's* raw values
-        this.sl_distances = [];
-        // Stores *yesterday's* 30-day history
-        this.history = [];
+        // We will store { [userId]: { risk_appetite_change: 0 } }
+        this.userRiskMap = new Map();
     }
 
     /**
@@ -23,89 +19,76 @@ class RiskAppetiteChange {
     static getSchema() {
         return {
             "type": "object",
-            "description": "Tracks the 30-day rolling average of speculator stop loss distance as a proxy for risk appetite.",
-            "properties": {
-                "risk_appetite_score": {
-                    "type": "number",
-                    "description": "Today's average SL distance %."
-                },
-                "daily_change_pct": {
-                    "type": "number",
-                    "description": "Percentage change from yesterday's average."
-                },
-                "avg_sl_distance_30d": {
-                    "type": "number",
-                    "description": "30-day rolling average of the SL distance."
-                },
-                "history_30d": {
-                    "type": "array",
-                    "description": "30-day history of daily average SL distance.",
-                    "items": { "type": "number" }
+            "description": "Tracks the daily change in risk appetite (leveraged investment / total investment) for each speculator.",
+            "patternProperties": {
+                "^[a-zA-Z0-9_]+$": { // Matches any user ID
+                    "type": "object",
+                    "properties": {
+                        "risk_appetite_change": {
+                            "type": "number",
+                            "description": "The percentage point change in risk appetite from yesterday to today."
+                        }
+                    },
+                    "required": ["risk_appetite_change"]
                 }
             },
-            "required": ["risk_appetite_score", "daily_change_pct", "avg_sl_distance_30d", "history_30d"]
+            "additionalProperties": false
         };
     }
 
-    process(todayPortfolio, yesterdayPortfolio, userId, context) {
-        // 1. Get this metric's history from yesterday (pre-loaded)
-        if (this.history.length === 0) { // Only run once
-             const yHistoryData = context.yesterdaysDependencyData['risk_appetite_change'];
-             if (yHistoryData) {
-                 this.history = yHistoryData.history_30d || [];
-             }
+    /**
+     * Helper to calculate the risk score from a portfolio snapshot.
+     * @param {object} portfolio - The portfolio snapshot.
+     * @returns {number} The risk score (0-100).
+     */
+    _calculateRisk(portfolio) {
+        const totalInvestment = portfolio?.TotalInvestment;
+        const totalLeveragedInvestment = portfolio?.TotalLeveragedInvestment;
+
+        if (!totalInvestment || totalInvestment === 0 || !totalLeveragedInvestment) {
+            return 0;
         }
         
-        if (todayPortfolio?.context?.userType !== 'speculator') {
+        // Return as a percentage
+        return (totalLeveragedInvestment / totalInvestment) * 100;
+    }
+
+    /**
+     * @param {object} todayPortfolio
+     * @param {object} yesterdayPortfolio
+     * @param {string} userId
+     */
+    process(todayPortfolio, yesterdayPortfolio, userId) {
+        // --- FIX ---
+        // Add null check to prevent crash on the first day of processing
+        if (!todayPortfolio || !yesterExamplePortfolio || !todayPortfolio.Portfolio || !yesterdayPortfolio.Portfolio) {
             return;
         }
+        // --- END FIX ---
         
-        const positions = todayPortfolio.PublicPositions;
-        if (!positions || !Array.isArray(positions)) {
-            return;
-        }
+        // 1. Get portfolio snapshots
+        const yPortfolio = yesterdayPortfolio.Portfolio;
+        const tPortfolio = todayPortfolio.Portfolio;
 
-        for (const pos of positions) {
-            const sl_rate = pos.StopLossRate || 0;
-            const open_rate = pos.OpenRate || 0;
-            
-            if (sl_rate > 0 && open_rate > 0) {
-                const distance = Math.abs(open_rate - sl_rate);
-                const distance_pct = (distance / open_rate);
-                this.sl_distances.push(distance_pct);
-            }
-        }
+        // 2. Calculate risk for both days
+        const yRisk = this._calculateRisk(yPortfolio);
+        const tRisk = this._calculateRisk(tPortfolio);
+
+        // 3. Calculate the change (in percentage points)
+        const change = tRisk - yRisk;
+
+        this.userRiskMap.set(userId, {
+            risk_appetite_change: change
+        });
     }
 
     getResult() {
-        const yHistory = this.history;
-        
-        let today_avg_dist = 0;
-        if (this.sl_distances.length > 0) {
-            today_avg_dist = (this.sl_distances.reduce((a, b) => a + b, 0) / this.sl_distances.length) * 100;
-        }
-
-        const newHistory = [today_avg_dist, ...yHistory].slice(0, 30);
-        
-        const yesterday_avg = yHistory[0] || 0;
-        const avg_30d = newHistory.reduce((a, b) => a + b, 0) / newHistory.length;
-        
-        let daily_change = 0;
-        if (yesterday_avg > 0) {
-            daily_change = ((today_avg_dist - yesterday_avg) / yesterday_avg) * 100;
-        }
-        
-        return {
-            risk_appetite_score: today_avg_dist, // Today's score
-            daily_change_pct: daily_change,
-            avg_sl_distance_30d: avg_30d,
-            history_30d: newHistory
-        };
+        // Convert Map to plain object for Firestore
+        return Object.fromEntries(this.userRiskMap);
     }
 
     reset() {
-        this.sl_distances = [];
-        this.history = [];
+        this.userRiskMap.clear();
     }
 }