aiden-shared-calculations-unified 1.0.64 → 1.0.66

package/calculations/speculators/historical/risk_appetite_change.js

@@ -1,55 +1,112 @@
 /**
- * @fileoverview Calculates the change in risk appetite for speculators based on stop-loss distance.
+ * @fileoverview Calculation (Pass 2) 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.
  */
-
 class RiskAppetiteChange {
     constructor() {
-        this.totalYesterdaySLDistance = 0;
-        this.totalTodaySLDistance = 0;
-        this.userCount = 0;
+        // Stores *today's* raw values
+        this.sl_distances = [];
+        // Stores *yesterday's* 30-day history
+        this.history = [];
+    }
+
+    /**
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
+     */
+    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" }
+                }
+            },
+            "required": ["risk_appetite_score", "daily_change_pct", "avg_sl_distance_30d", "history_30d"]
+        };
     }
 
-    process(todayPortfolio, yesterdayPortfolio, userId) {
-        if (!todayPortfolio || !yesterdayPortfolio || !todayPortfolio.PublicPositions || !yesterdayPortfolio.PublicPositions) {
+    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 || [];
+             }
+        }
+        
+        if (todayPortfolio?.context?.userType !== 'speculator') {
             return;
         }
-
-        const yesterdayAvgDistance = this.calculateAverageSLDistance(yesterdayPortfolio.PublicPositions);
-        const todayAvgDistance = this.calculateAverageSLDistance(todayPortfolio.PublicPositions);
-
-        if (yesterdayAvgDistance !== null && todayAvgDistance !== null) {
-            this.totalYesterdaySLDistance += yesterdayAvgDistance;
-            this.totalTodaySLDistance += todayAvgDistance;
-            this.userCount++;
+        
+        const positions = todayPortfolio.PublicPositions;
+        if (!positions || !Array.isArray(positions)) {
+            return;
         }
-    }
 
-    calculateAverageSLDistance(positions) {
-        let totalDistance = 0;
-        let count = 0;
         for (const pos of positions) {
-            if (pos.StopLossRate > 0.0001 && pos.OpenRate > 0) {
-                const distance = pos.IsBuy ? pos.OpenRate - pos.StopLossRate : pos.StopLossRate - pos.OpenRate;
-                if (distance > 0) {
-                    totalDistance += (distance / pos.OpenRate) * 100;
-                    count++;
-                }
+            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);
             }
         }
-        return count > 0 ? totalDistance / count : null;
     }
 
     getResult() {
-        if (this.userCount === 0) return {};
-        const avgYesterday = this.totalYesterdaySLDistance / this.userCount;
-        const avgToday = this.totalTodaySLDistance / this.userCount;
+        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 {
-            average_stop_loss_distance_yesterday: avgYesterday,
-            average_stop_loss_distance_today: avgToday,
-            change_in_risk_appetite: avgToday - avgYesterday,
+            risk_appetite_score: today_avg_dist, // Today's score
+            daily_change_pct: daily_change,
+            avg_sl_distance_30d: avg_30d,
+            history_30d: newHistory
         };
     }
+
+    reset() {
+        this.sl_distances = [];
+        this.history = [];
+    }
 }
 
 module.exports = RiskAppetiteChange;

package/calculations/speculators/historical/tsl_effectiveness.js

@@ -1,75 +1,85 @@
 /**
- * Compares the average P/L of speculator users who use TSL
- * vs. those who do not.
+ * @fileoverview Calculation (Pass 2) for TSL effectiveness.
+ *
+ * This metric answers: "What is the difference in average
+ * P&L between speculators who use a Trailing Stop Loss (TSL)
+ * versus those who do not?"
  */
 class TslEffectiveness {
     constructor() {
-        this.tsl_group = { pnl_sum: 0, count: 0 };
-        this.nontsl_group = { pnl_sum: 0, count: 0 };
+        this.with_tsl = { pnl_sum: 0, count: 0 };
+        this.without_tsl = { pnl_sum: 0, count: 0 };
     }
 
     /**
-     * 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) {
-        // Speculators use PublicPositions
-        const positions = 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);
-        }
-        return null;
+    static getSchema() {
+        return {
+            "type": "object",
+            "description": "Compares the average P&L of speculators who use TSL vs. those who do not.",
+            "properties": {
+                "with_tsl_avg_pnl": {
+                    "type": "number",
+                    "description": "Average P&L for positions with TSL enabled."
+                },
+                "without_tsl_avg_pnl": {
+                    "type": "number",
+                    "description": "Average P&L for positions without TSL enabled."
+                },
+                "effectiveness_delta": {
+                    "type": "number",
+                    "description": "The difference in P&L (With TSL - Without TSL)."
+                },
+                "with_tsl_count": { "type": "number" },
+                "without_tsl_count": { "type": "number" }
+            },
+            "required": ["with_tsl_avg_pnl", "without_tsl_avg_pnl", "effectiveness_delta", "with_tsl_count", "without_tsl_count"]
+        };
     }
 
     process(todayPortfolio, yesterdayPortfolio, userId) {
-        // Check if user is a speculator and we have today's data
-        // FIX: yesterdayPortfolio is not needed for this logic, only today's P&L
-        if (todayPortfolio?.context?.userType !== 'speculator' || !todayPortfolio) {
+        // This calculation is only for speculators
+        if (todayPortfolio?.context?.userType !== 'speculator') {
             return;
         }
         
         const positions = todayPortfolio.PublicPositions;
-        
         if (!positions || !Array.isArray(positions)) {
-            return; 
+            return;
         }
 
-        // FIX: Calculate dailyPnl by summing NetProfit from all positions
-        const dailyPnl = this._calculateTotalPnl(todayPortfolio);
-
-        if (dailyPnl === null) {
-            return; // Cannot calculate P&L
-        }
-        
-        const usesTSL = positions.some(p => p.IsTslEnabled);
-
-        if (usesTSL) {
-            this.tsl_group.pnl_sum += dailyPnl;
-            this.tsl_group.count++;
-        } else {
-            this.nontsl_group.pnl_sum += dailyPnl;
-            this.nontsl_group.count++;
+        for (const pos of positions) {
+            const pnl = pos.NetProfit || 0;
+            
+            if (pos.IsTslEnabled) {
+                this.with_tsl.pnl_sum += pnl;
+                this.with_tsl.count++;
+            } else {
+                this.without_tsl.pnl_sum += pnl;
+                this.without_tsl.count++;
+            }
         }
     }
 
     getResult() {
-        // Return final calculated averages
-        const tsl_avg_pnl = (this.tsl_group.count > 0) ? this.tsl_group.pnl_sum / this.tsl_group.count : 0;
-        const nontsl_avg_pnl = (this.nontsl_group.count > 0) ? this.nontsl_group.pnl_sum / this.nontsl_group.count : 0;
-
+        const with_avg = (this.with_tsl.count > 0) ? (this.with_tsl.pnl_sum / this.with_tsl.count) : 0;
+        const without_avg = (this.without_tsl.count > 0) ? (this.without_tsl.pnl_sum / this.without_tsl.count) : 0;
+        
         return {
-            tsl_users: {
-                avg_pnl: tsl_avg_pnl,
-                count: this.tsl_group.count
-            },
-            nontsl_users: {
-                avg_pnl: nontsl_avg_pnl,
-                count: this.nontsl_group.count
-            }
+            with_tsl_avg_pnl: with_avg,
+            without_tsl_avg_pnl: without_avg,
+            effectiveness_delta: with_avg - without_avg,
+            with_tsl_count: this.with_tsl.count,
+            without_tsl_count: this.without_tsl.count
         };
     }
+
+    reset() {
+        this.with_tsl = { pnl_sum: 0, count: 0 };
+        this.without_tsl = { pnl_sum: 0, count: 0 };
+    }
 }
 
 module.exports = TslEffectiveness;

package/calculations/speculators/holding_duration_per_asset.js

@@ -1,27 +1,88 @@
 /**
- * @fileoverview Calculates the average holding duration of open speculator positions.
+ * @fileoverview Calculation (Pass 1) for speculator metric.
+ *
+ * This metric answers: "What is the average holding duration
+ * (in hours) for open speculator positions, grouped by asset?"
  */
 const { loadInstrumentMappings } = require('../../utils/sector_mapping_provider');
 
 class HoldingDurationPerAsset {
     constructor() {
-        this.durationData = {};
+        // { [instrumentId]: { sum_hours: 0, count: 0 } }
+        this.assets = new Map();
         this.mappings = null;
     }
 
-    process(portfolioData, yesterdayPortfolio, userId, context) {
-        if (portfolioData && portfolioData.PublicPositions) {
-            const now = new Date();
-            for (const position of portfolioData.PublicPositions) {
-                const instrumentId = position.InstrumentID;
-                const openTime = new Date(position.OpenDateTime);
-                const durationHours = (now - openTime) / (1000 * 60 * 60);
-
-                if (!this.durationData[instrumentId]) {
-                    this.durationData[instrumentId] = { duration_sum_hours: 0, count: 0 };
+    /**
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
+     */
+    static getSchema() {
+        const tickerSchema = {
+            "type": "object",
+            "properties": {
+                "avg_duration_hours": {
+                    "type": "number",
+                    "description": "Average holding duration in hours."
+                },
+                "count": {
+                    "type": "number",
+                    "description": "Count of positions used in average."
                 }
-                this.durationData[instrumentId].duration_sum_hours += durationHours;
-                this.durationData[instrumentId].count++;
+            },
+            "required": ["avg_duration_hours", "count"]
+        };
+
+        return {
+            "type": "object",
+            "description": "Calculates the average holding duration (in hours) for open speculator positions per asset.",
+            "patternProperties": {
+                "^.*$": tickerSchema // Ticker
+            },
+            "additionalProperties": tickerSchema
+        };
+    }
+
+    _initAsset(instrumentId) {
+        if (!this.assets.has(instrumentId)) {
+            this.assets.set(instrumentId, { sum_hours: 0, count: 0 });
+        }
+    }
+    
+    _getHoldingDurationHours(openDateStr) {
+        if (!openDateStr) return 0;
+        try {
+            const openDate = new Date(openDateStr);
+            // Get difference from 'now' (or the snapshot time)
+            const diffMs = new Date().getTime() - openDate.getTime();
+            return diffMs / (1000 * 60 * 60); // Convert ms to hours
+        } catch (e) {
+            return 0;
+        }
+    }
+
+    process(portfolioData) {
+        if (portfolioData?.context?.userType !== 'speculator') {
+            return;
+        }
+        
+        const positions = portfolioData.PublicPositions;
+        if (!positions || !Array.isArray(positions)) {
+            return;
+        }
+
+        for (const pos of positions) {
+            const instrumentId = pos.InstrumentID;
+            if (!instrumentId) continue;
+            
+            this._initAsset(instrumentId);
+            
+            const duration = this._getHoldingDurationHours(pos.OpenDateTime);
+            
+            if (duration > 0) {
+                const assetData = this.assets.get(instrumentId);
+                assetData.sum_hours += duration;
+                assetData.count++;
             }
         }
     }
@@ -30,26 +91,25 @@ class HoldingDurationPerAsset {
         if (!this.mappings) {
             this.mappings = await loadInstrumentMappings();
         }
-        const result = {};
-        for (const instrumentId in this.durationData) {
-            const ticker = this.mappings.instrumentToTicker[instrumentId] || instrumentId.toString();
-            const data = this.durationData[instrumentId];
 
-            // REFACTOR: Perform the final calculation directly.
+        const result = {};
+        for (const [instrumentId, data] of this.assets.entries()) {
+            const ticker = this.mappings.instrumentToTicker[instrumentId] || `id_${instrumentId}`;
+            
             if (data.count > 0) {
                 result[ticker] = {
-                    average_duration_hours: data.duration_sum_hours / data.count
+                    avg_duration_hours: data.sum_hours / data.count,
+                    count: data.count
                 };
             }
         }
-        
         return result;
     }
 
     reset() {
-        this.durationData = {};
+        this.assets.clear();
         this.mappings = null;
     }
 }
 
-module.exports = HoldingDurationPerAsset;
+module.exports = HoldingDurationPerAsset;

package/calculations/speculators/leverage_per_asset.js

@@ -1,25 +1,76 @@
 /**
- * @fileoverview Calculates leverage usage per instrument for speculators.
+ * @fileoverview Calculation (Pass 1) for speculator metric.
+ *
+ * This metric answers: "For each asset, what is the
+ * distribution of leverage levels used by speculators?"
  */
 const { loadInstrumentMappings } = require('../../utils/sector_mapping_provider');
 
 class LeveragePerAsset {
     constructor() {
-        this.leverageData = {};
+        // { [instrumentId]: { [leverage]: count } }
+        this.assets = new Map();
         this.mappings = null;
     }
 
-    process(portfolioData, yesterdayPortfolio, userId, context) {
-        if (portfolioData && portfolioData.PublicPositions) {
-            for (const position of portfolioData.PublicPositions) {
-                const instrumentId = position.InstrumentID;
-                const leverage = position.Leverage;
-
-                if (!this.leverageData[instrumentId]) {
-                    this.leverageData[instrumentId] = {};
+    /**
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
+     */
+    static getSchema() {
+        const leverageSchema = {
+            "type": "object",
+            "description": "Distribution of leverage levels for this asset.",
+            "patternProperties": {
+                // Leverage level, e.g., "1x", "5x"
+                "^[0-9]+x$": {
+                    "type": "number",
+                    "description": "Count of positions at this leverage."
                 }
-                this.leverageData[instrumentId][leverage] = (this.leverageData[instrumentId][leverage] || 0) + 1;
+            },
+            "additionalProperties": { "type": "number" }
+        };
+
+        return {
+            "type": "object",
+            "description": "Calculates the distribution of leverage levels used by speculators for each asset.",
+            "patternProperties": {
+                "^.*$": leverageSchema // Ticker
+            },
+            "additionalProperties": leverageSchema
+        };
+    }
+
+    _initAsset(instrumentId) {
+        if (!this.assets.has(instrumentId)) {
+            this.assets.set(instrumentId, {});
+        }
+    }
+
+    process(portfolioData) {
+        if (portfolioData?.context?.userType !== 'speculator') {
+            return;
+        }
+        
+        const positions = portfolioData.PublicPositions;
+        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 leverage = pos.Leverage || 1;
+            const key = `${leverage}x`;
+            
+            if (!assetData[key]) {
+                assetData[key] = 0;
             }
+            assetData[key]++;
         }
     }
 
@@ -27,19 +78,17 @@ class LeveragePerAsset {
         if (!this.mappings) {
             this.mappings = await loadInstrumentMappings();
         }
+
         const result = {};
-        for (const instrumentId in this.leverageData) {
-            const ticker = this.mappings.instrumentToTicker[instrumentId] || instrumentId.toString();
-            result[ticker] = this.leverageData[instrumentId];
+        for (const [instrumentId, data] of this.assets.entries()) {
+            const ticker = this.mappings.instrumentToTicker[instrumentId] || `id_${instrumentId}`;
+            result[ticker] = data;
         }
-        if (Object.keys(result).length === 0) return {};
-        return {
-            leverage_per_asset: result
-        };
+        return result;
     }
 
     reset() {
-        this.leverageData = {};
+        this.assets.clear();
         this.mappings = null;
     }
 }

package/calculations/speculators/leverage_per_sector.js

@@ -1,44 +1,105 @@
-const { getInstrumentSectorMap } = require('../../utils/sector_mapping_provider');
-
 /**
- * @fileoverview Calculates leverage usage per sector for speculators.
+ * @fileoverview Calculation (Pass 1) for speculator metric.
+ *
+ * This metric answers: "For each sector, what is the
+ * distribution of leverage levels used by speculators?"
  */
+const { loadInstrumentMappings } = require('../../utils/sector_mapping_provider');
 
 class LeveragePerSector {
     constructor() {
-        this.positions = [];
+        // { [sector]: { [leverage]: count } }
+        this.sectors = new Map();
+        this.mappings = null;
     }
 
-    process(portfolioData, yesterdayPortfolio, userId, context) {
-        if (portfolioData && portfolioData.PublicPositions) {
-            this.positions.push(...portfolioData.PublicPositions);
-        }
-    }
+    /**
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
+     */
+    static getSchema() {
+        const leverageSchema = {
+            "type": "object",
+            "description": "Distribution of leverage levels for this sector.",
+            "patternProperties": {
+                // Leverage level, e.g., "1x", "5x", "inf"
+                "^[0-9inf]+x$": {
+                    "type": "number",
+                    "description": "Count of positions at this leverage."
+                }
+            },
+            "additionalProperties": { "type": "number" }
+        };
 
-    async getResult() {
-        if (this.positions.length === 0) return {};
+        return {
+            "type": "object",
+            "description": "Calculates the distribution of leverage levels used by speculators for each sector.",
+            "patternProperties": {
+                "^.*$": leverageSchema // Sector
+            },
+            "additionalProperties": leverageSchema
+        };
+    }
 
-        const sectorMap = await getInstrumentSectorMap();
-        const leverageData = {};
+    _initSector(sector) {
+        if (!this.sectors.has(sector)) {
+            this.sectors.set(sector, {
+                '1x': 0,
+                '2x': 0,
+                '5x': 0,
+                '10x': 0,
+                'inf': 0 // For other leverages
+            });
+        }
+    }
+    
+    _getLeverageBucket(leverage) {
+        switch (leverage) {
+            case 1: return '1x';
+            case 2: return '2x';
+            case 5: return '5x';
+            case 10: return '10x';
+            default: return 'inf';
+        }
+    }
 
-        for (const position of this.positions) {
-            const instrumentId = position.InstrumentID;
-            const sector = sectorMap[instrumentId] || 'N/A';
-            const leverage = position.Leverage;
+    process(portfolioData, yesterdayPortfolio, userId, context) {
+        if (portfolioData?.context?.userType !== 'speculator') {
+            return;
+        }
+        
+        if (!this.mappings) {
+            this.mappings = context.mappings;
+        }
+        
+        const positions = portfolioData.PublicPositions;
+        if (!positions || !Array.isArray(positions) || !this.mappings) {
+            return;
+        }
 
-            if (!leverageData[sector]) {
-                leverageData[sector] = {};
-            }
-            leverageData[sector][leverage] = (leverageData[sector][leverage] || 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);
+            
+            const leverage = pos.Leverage || 1;
+            const key = this._getLeverageBucket(leverage);
+            
+            sectorData[key]++;
         }
+    }
 
-        return {
-            leverage_per_sector: leverageData
-        };
+    async getResult() {
+        // Convert Map to plain object
+        return Object.fromEntries(this.sectors);
     }
 
     reset() {
-        this.positions = [];
+        this.sectors.clear();
+        this.mappings = null;
     }
 }