aiden-shared-calculations-unified 1.0.71 → 1.0.73

package/calculations/pnl/pnl_distribution_per_stock.js

@@ -7,6 +7,13 @@
  * REFACTOR: This calculation now aggregates the distribution into
  * predefined buckets on the server-side, returning a chart-ready
  * histogram object instead of raw arrays.
+ *
+ * --- FIX: 2025-11-12 ---
+ * This calculation is a dependency for crowd_sharpe_ratio_proxy,
+ * which requires sum, sumSq, and count for variance calculations.
+ * This file has been updated to provide *both* the histogram
+ * and a 'stats' object containing these required values.
+ * ---------------------
  */
 const { loadInstrumentMappings } = require('../../utils/sector_mapping_provider');
 
@@ -31,28 +38,48 @@ class PnlDistributionPerStock {
     /**
      * Defines the output schema for this calculation.
      * REFACTOR: Schema now describes the server-calculated histogram.
-     * @returns {object} JSON Schema object
+     *
+     * --- FIX: 2025-11-12 ---
+     * Added 'stats' object to the schema to support downstream
+     * meta-calculations like crowd_sharpe_ratio_proxy.
      */
     static getSchema() {
         const bucketSchema = {
             "type": "object",
-            "description": "Histogram of P&L distribution for a single asset.",
+            "description": "Histogram and stats of P&L distribution for a single asset.",
             "properties": {
-                "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" }
+                "histogram": {
+                    "type": "object",
+                    "description": "Histogram of P&L distribution.",
+                    "properties": {
+                        "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": ["total_positions"]
+                },
+                "stats": {
+                    "type": "object",
+                    "description": "Raw statistics needed for variance/Sharpe calculations.",
+                    "properties": {
+                        "sum": { "type": "number", "description": "Sum of all P&L percentages" },
+                        "sumSq": { "type": "number", "description": "Sum of all squared P&L percentages" },
+                        "count": { "type": "number", "description": "Total count of positions" }
+                    },
+                    "required": ["sum", "sumSq", "count"]
+                }
             },
-            "required": ["total_positions"]
+            "required": ["histogram", "stats"]
         };
 
         return {
             "type": "object",
-            "description": "Calculates a histogram of P&L percentage distribution for all open positions, per asset.",
+            "description": "Calculates a histogram and raw stats of P&L percentage distribution for all open positions, per asset.",
             "patternProperties": {
                 "^.*$": bucketSchema // Ticker
             },
@@ -90,6 +117,9 @@ class PnlDistributionPerStock {
     /**
      * REFACTOR: This method now calculates the distribution on the server.
      * It transforms the raw P&L arrays into histogram bucket counts.
+     *
+     * --- FIX: 2025-11-12 ---
+     * Also calculates and returns sum, sumSq, and count.
      */
     async getResult() {
         if (!this.mappings) {
@@ -100,6 +130,11 @@ class PnlDistributionPerStock {
 
         for (const [instrumentId, pnlValues] of this.pnlMap.entries()) {
             const ticker = this.mappings.instrumentToTicker[instrumentId] || `id_${instrumentId}`;
+            const count = pnlValues.length;
+
+            if (count === 0) {
+                continue;
+            }
 
             // 1. Initialize the histogram object for this ticker
             const histogram = {
@@ -110,11 +145,20 @@ class PnlDistributionPerStock {
                 gain_medium: 0,
                 gain_heavy: 0,
                 gain_extreme: 0,
-                total_positions: pnlValues.length
+                total_positions: count
             };
 
-            // 2. Process all P&L values into the buckets
+            // --- FIX: Initialize stats ---
+            let sum = 0;
+            let sumSq = 0;
+
+            // 2. Process all P&L values into buckets and calculate stats
             for (const pnl of pnlValues) {
+                // --- FIX: Add to stats ---
+                sum += pnl;
+                sumSq += (pnl * pnl);
+
+                // Add to histogram
                 for (const bucket of BUCKETS) {
                     if (pnl >= bucket.min && pnl < bucket.max) {
                         histogram[bucket.label]++;
@@ -122,9 +166,19 @@ class PnlDistributionPerStock {
                     }
                 }
             }
+            
+            // --- FIX: Create stats object ---
+            const stats = {
+                sum: sum,
+                sumSq: sumSq,
+                count: count
+            };
 
-            // 3. Add the aggregated histogram to the final result
-            result[ticker] = histogram;
+            // 3. Add the aggregated histogram and stats to the final result
+            result[ticker] = {
+                histogram: histogram,
+                stats: stats
+            };
         }
         return result;
     }

package/calculations/sentiment/gem_platform-conviction-divergence.js

@@ -0,0 +1,141 @@
+/**
+ * @fileoverview Calculation (Pass 1) for platform conviction divergence.
+ *
+ * This metric answers: "Is our 20,000-user sample more bullish or bearish
+ * on an asset than the entire eToro platform?"
+ *
+ * It compares the long/short ratio of our sample (from 'portfolio' data)
+ * against the platform-wide 'buy'/'sell' % (from 'insights' data).
+ */
+const { loadInstrumentMappings } = require('../../utils/sector_mapping_provider');
+
+class PlatformConvictionDivergence {
+    constructor() {
+        // { [instrumentId]: { long: 0, short: 0 } }
+        this.sampledCounts = new Map();
+        this.mappings = null;
+        this.todayInsightsData = null;
+    }
+
+    /**
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
+     */
+    static getSchema() {
+        const tickerSchema = {
+            "type": "object",
+            "properties": {
+                "platform_long_pct": {
+                    "type": "number",
+                    "description": "Percentage of holders on the entire platform who are long."
+                },
+                "sampled_long_pct": {
+                    "type": ["number", "null"],
+                    "description": "Percentage of holders in our sample who are long. Null if no sample."
+                },
+                "divergence": {
+                    "type": ["number", "null"],
+                    "description": "The difference (Sampled % - Platform %). Positive means our sample is more bullish."
+                }
+            },
+            "required": ["platform_long_pct", "sampled_long_pct", "divergence"]
+        };
+        
+        return {
+            "type": "object",
+            "description": "Calculates the divergence between the sample's long/short ratio and the platform's.",
+            "patternProperties": {
+                "^.*$": tickerSchema // Ticker
+            },
+            "additionalProperties": tickerSchema
+        };
+    }
+
+    /**
+     * This is a Pass 1 calculation and has no dependencies.
+     */
+    static getDependencies() {
+        return [];
+    }
+
+    _initAsset(instrumentId) {
+        if (!this.sampledCounts.has(instrumentId)) {
+            this.sampledCounts.set(instrumentId, { long: 0, short: 0 });
+        }
+    }
+
+    process(portfolioData, yesterdayPortfolio, userId, context, todayInsights) {
+        // Capture insights data on the first user processed
+        if (!this.todayInsightsData && todayInsights) {
+            this.todayInsightsData = todayInsights;
+        }
+
+        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.sampledCounts.get(instrumentId);
+
+            if (pos.IsBuy) {
+                assetData.long++;
+            } else {
+                assetData.short++;
+            }
+        }
+    }
+
+    async getResult() {
+        if (!this.mappings) {
+            this.mappings = await loadInstrumentMappings();
+        }
+
+        const result = {};
+        const insights = this.todayInsightsData?.insights;
+
+        if (!insights || !Array.isArray(insights)) {
+            return {}; // No platform data to compare against
+        }
+
+        for (const instrument of insights) {
+            const instrumentId = instrument.instrumentId;
+            const ticker = this.mappings.instrumentToTicker[instrumentId];
+            if (!ticker) continue;
+            
+            const platform_long_pct = instrument.buy || 0; // e.g., 51
+            
+            const sampledData = this.sampledCounts.get(instrumentId);
+            const sampled_long = sampledData?.long || 0;
+            const sampled_short = sampledData?.short || 0;
+            const totalSampled = sampled_long + sampled_short;
+
+            let sampled_long_pct = null;
+            let divergence = null;
+
+            if (totalSampled > 0) {
+                sampled_long_pct = (sampled_long / totalSampled) * 100;
+                divergence = sampled_long_pct - platform_long_pct;
+            }
+
+            result[ticker] = {
+                platform_long_pct: platform_long_pct,
+                sampled_long_pct: sampled_long_pct,
+                divergence: divergence
+            };
+        }
+        return result;
+    }
+
+    reset() {
+        this.sampledCounts.clear();
+        this.mappings = null;
+        this.todayInsightsData = null;
+    }
+}
+
+module.exports = PlatformConvictionDivergence;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aiden-shared-calculations-unified",
-  "version": "1.0.71",
+  "version": "1.0.73",
   "description": "Shared calculation modules for the BullTrackers Computation System.",
   "main": "index.js",
   "files": [
@@ -24,7 +24,8 @@
     "@google-cloud/firestore": "^7.11.3",
     "sharedsetup": "latest",
     "require-all": "^3.0.0",
-    "dotenv": "latest"
+    "dotenv": "latest",
+    "viz.js": "^2.1.2"
   },
   "devDependencies": {
     "bulltracker-deployer": "file:../bulltracker-deployer"