aiden-shared-calculations-unified 1.0.63 → 1.0.65

package/calculations/speculators/distance_to_stop_loss_per_leverage.js

@@ -1,48 +1,89 @@
 /**
- * @fileoverview Calculates the average distance to the stop loss from the current price for
- * both long and short positions, grouped by asset and leverage level.
- * It ignores near-zero stop loss values.
+ * @fileoverview Calculation (Pass 1) for speculator metric.
+ *
+ * This metric answers: "For each asset and leverage level,
+ * what is the average percentage distance from the *current price*
+ * to the stop loss?"
  */
 const { loadInstrumentMappings } = require('../../utils/sector_mapping_provider');
 
 class DistanceToStopLossPerLeverage {
     constructor() {
-        this.stopLossData = {};
+        // { [instrumentId]: { [leverage]: { sum_dist: 0, count: 0 } } }
+        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;
-                const stopLossRate = position.StopLossRate;
-                const currentRate = position.CurrentRate;
-                const isBuy = position.IsBuy;
+    /**
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
+     */
+    static getSchema() {
+        const leverageSchema = {
+            "type": "object",
+            "description": "Average SL distance grouped by leverage.",
+            "patternProperties": {
+                // Leverage level, e.g., "1x", "5x", "10x"
+                "^[0-9]+x$": {
+                    "type": "number",
+                    "description": "The average percentage distance from current price to Stop Loss for this leverage level."
+                }
+            },
+            "additionalProperties": { "type": "number" }
+        };
 
-                if (stopLossRate > 0.0001 && currentRate > 0) {
-                    let distance;
+        return {
+            "type": "object",
+            "description": "Calculates avg % distance from current price to SL, bucketed by asset and leverage.",
+            "patternProperties": {
+                "^.*$": leverageSchema // Ticker
+            },
+            "additionalProperties": leverageSchema
+        };
+    }
 
-                    if (isBuy) {
-                        distance = currentRate - stopLossRate;
-                    } else {
-                        distance = stopLossRate - currentRate;
-                    }
-                    
-                    const distancePercent = (distance / currentRate) * 100;
+    _initLeverage(assetData, leverage) {
+        const key = `${leverage}x`;
+        if (!assetData[key]) {
+            assetData[key] = { sum_dist: 0, count: 0 };
+        }
+        return key;
+    }
 
-                    if (distancePercent > 0) {
-                        if (!this.stopLossData[instrumentId]) {
-                            this.stopLossData[instrumentId] = {};
-                        }
-                        if (!this.stopLossData[instrumentId][leverage]) {
-                            this.stopLossData[instrumentId][leverage] = { distance_sum_percent: 0, count: 0 };
-                        }
-                        this.stopLossData[instrumentId][leverage].distance_sum_percent += distancePercent;
-                        this.stopLossData[instrumentId][leverage].count++;
-                    }
-                }
+    process(portfolioData) {
+        // This calculation is only for speculators
+        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;
+            const sl_rate = pos.StopLossRate || 0;
+            const current_price = pos.LastCloseRate || 0; // Use last close as current price
+            
+            if (!instrumentId || sl_rate === 0 || current_price === 0) {
+                continue; // Skip positions without SL or price
+            }
+
+            if (!this.assets.has(instrumentId)) {
+                this.assets.set(instrumentId, {});
             }
+            const assetData = this.assets.get(instrumentId);
+            
+            const leverage = pos.Leverage || 1;
+            const key = this._initLeverage(assetData, leverage);
+            
+            // Calculate distance
+            const distance = Math.abs(current_price - sl_rate);
+            const distance_pct = (distance / current_price);
+            
+            assetData[key].sum_dist += distance_pct;
+            assetData[key].count++;
         }
     }
 
@@ -52,17 +93,15 @@ class DistanceToStopLossPerLeverage {
         }
 
         const result = {};
-        for (const instrumentId in this.stopLossData) {
-            const ticker = this.mappings.instrumentToTicker[instrumentId] || instrumentId.toString();
+        for (const [instrumentId, leverageData] of this.assets.entries()) {
+            const ticker = this.mappings.instrumentToTicker[instrumentId] || `id_${instrumentId}`;
             result[ticker] = {};
-            for (const leverage in this.stopLossData[instrumentId]) {
-                const data = this.stopLossData[instrumentId][leverage];
-                // REFACTOR: Perform final calculation directly.
+            
+            for (const leverageKey in leverageData) {
+                const data = leverageData[leverageKey];
                 if (data.count > 0) {
-                    result[ticker][leverage] = {
-                        average_distance_percent: data.distance_sum_percent / data.count,
-                        count: data.count
-                    };
+                    // Store the final average distance * 100 for percentage
+                    result[ticker][leverageKey] = (data.sum_dist / data.count) * 100;
                 }
             }
         }
@@ -70,9 +109,9 @@ class DistanceToStopLossPerLeverage {
     }
 
     reset() {
-        this.stopLossData = {};
+        this.assets.clear();
         this.mappings = null;
     }
 }
 
-module.exports = DistanceToStopLossPerLeverage;
+module.exports = DistanceToStopLossPerLeverage;

package/calculations/speculators/distance_to_tp_per_leverage.js

@@ -1,47 +1,88 @@
 /**
- * @fileoverview Calculates the average distance to the take profit from the current price for
- * both long and short positions, grouped by asset and leverage level.
- * It ignores positions where take profit is not set.
+ * @fileoverview Calculation (Pass 1) for speculator metric.
+ *
+ * This metric answers: "For each asset and leverage level,
+ * what is the average percentage distance from the *current price*
+ * to the take profit?"
  */
 const { loadInstrumentMappings } = require('../../utils/sector_mapping_provider');
 
 class DistanceToTakeProfitPerLeverage {
     constructor() {
-        this.takeProfitData = {};
+        // { [instrumentId]: { [leverage]: { sum_dist: 0, count: 0 } } }
+        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;
-                const takeProfitRate = position.TakeProfitRate;
-                const currentRate = position.CurrentRate;
-                const isBuy = position.IsBuy;
+    /**
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
+     */
+    static getSchema() {
+        const leverageSchema = {
+            "type": "object",
+            "description": "Average TP distance grouped by leverage.",
+            "patternProperties": {
+                // Leverage level, e.g., "1x", "5x", "10x"
+                "^[0-9]+x$": {
+                    "type": "number",
+                    "description": "The average percentage distance from current price to Take Profit for this leverage level."
+                }
+            },
+            "additionalProperties": { "type": "number" }
+        };
 
-                if (takeProfitRate > 0.0001 && currentRate > 0) {
-                    let distance;
-                    if (isBuy) {
-                        distance = takeProfitRate - currentRate;
-                    } else {
-                        distance = currentRate - takeProfitRate;
-                    }
+        return {
+            "type": "object",
+            "description": "Calculates avg % distance from current price to TP, bucketed by asset and leverage.",
+            "patternProperties": {
+                "^.*$": leverageSchema // Ticker
+            },
+            "additionalProperties": leverageSchema
+        };
+    }
 
-                    const distancePercent = (distance / currentRate) * 100;
+    _initLeverage(assetData, leverage) {
+        const key = `${leverage}x`;
+        if (!assetData[key]) {
+            assetData[key] = { sum_dist: 0, count: 0 };
+        }
+        return key;
+    }
 
-                    if (distancePercent > 0) {
-                        if (!this.takeProfitData[instrumentId]) {
-                            this.takeProfitData[instrumentId] = {};
-                        }
-                        if (!this.takeProfitData[instrumentId][leverage]) {
-                            this.takeProfitData[instrumentId][leverage] = { distance_sum_percent: 0, count: 0 };
-                        }
-                        this.takeProfitData[instrumentId][leverage].distance_sum_percent += distancePercent;
-                        this.takeProfitData[instrumentId][leverage].count++;
-                    }
-                }
+    process(portfolioData) {
+        // This calculation is only for speculators
+        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;
+            const tp_rate = pos.TakeProfitRate || 0;
+            const current_price = pos.LastCloseRate || 0;
+            
+            if (!instrumentId || tp_rate === 0 || current_price === 0) {
+                continue; // Skip positions without TP or price
             }
+
+            if (!this.assets.has(instrumentId)) {
+                this.assets.set(instrumentId, {});
+            }
+            const assetData = this.assets.get(instrumentId);
+            
+            const leverage = pos.Leverage || 1;
+            const key = this._initLeverage(assetData, leverage);
+            
+            const distance = Math.abs(tp_rate - current_price);
+            const distance_pct = (distance / current_price);
+            
+            assetData[key].sum_dist += distance_pct;
+            assetData[key].count++;
         }
     }
 
@@ -49,18 +90,16 @@ class DistanceToTakeProfitPerLeverage {
         if (!this.mappings) {
             this.mappings = await loadInstrumentMappings();
         }
+
         const result = {};
-        for (const instrumentId in this.takeProfitData) {
-            const ticker = this.mappings.instrumentToTicker[instrumentId] || instrumentId.toString();
+        for (const [instrumentId, leverageData] of this.assets.entries()) {
+            const ticker = this.mappings.instrumentToTicker[instrumentId] || `id_${instrumentId}`;
             result[ticker] = {};
-            for (const leverage in this.takeProfitData[instrumentId]) {
-                const data = this.takeProfitData[instrumentId][leverage];
-                // REFACTOR: Perform final calculation directly.
+            
+            for (const leverageKey in leverageData) {
+                const data = leverageData[leverageKey];
                 if (data.count > 0) {
-                    result[ticker][leverage] = {
-                        average_distance_percent: data.distance_sum_percent / data.count,
-                        count: data.count
-                    };
+                    result[ticker][leverageKey] = (data.sum_dist / data.count) * 100;
                 }
             }
         }
@@ -68,9 +107,9 @@ class DistanceToTakeProfitPerLeverage {
     }
 
     reset() {
-        this.takeProfitData = {};
+        this.assets.clear();
         this.mappings = null;
     }
 }
 
-module.exports = DistanceToTakeProfitPerLeverage;
+module.exports = DistanceToTakeProfitPerLeverage;

package/calculations/speculators/entry_distance_to_sl_per_leverage.js

@@ -1,48 +1,87 @@
 /**
- * @fileoverview Calculates the average percentage distance from the entry price (OpenRate)
- * to the stop loss rate for both long and short positions, grouped by asset and leverage level.
- * It ignores near-zero stop loss values, which signify no stop loss is set.
+ * @fileoverview Calculation (Pass 1) for speculator metric.
+ *
+ * This metric answers: "For each asset and leverage level,
+ * what is the average percentage distance from the *entry price*
+ * to the stop loss?" (This defines the intended risk).
  */
 const { loadInstrumentMappings } = require('../../utils/sector_mapping_provider');
 
-class EntryDistanceToStopLossPerLeverage {
+class EntryDistanceToSlPerLeverage {
     constructor() {
-        this.stopLossData = {};
+        // { [instrumentId]: { [leverage]: { sum_dist: 0, count: 0 } } }
+        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;
-                const stopLossRate = position.StopLossRate;
-                const openRate = position.OpenRate;
-                const isBuy = position.IsBuy;
+    /**
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
+     */
+    static getSchema() {
+        const leverageSchema = {
+            "type": "object",
+            "description": "Average entry-to-SL distance grouped by leverage.",
+            "patternProperties": {
+                // Leverage level, e.g., "1x", "5x", "10x"
+                "^[0-9]+x$": {
+                    "type": "number",
+                    "description": "The average percentage distance from entry price to Stop Loss for this leverage level."
+                }
+            },
+            "additionalProperties": { "type": "number" }
+        };
 
-                if (stopLossRate > 0.0001 && openRate > 0) {
-                    let distance;
-                    
-                    if (isBuy) {
-                        distance = openRate - stopLossRate;
-                    } else {
-                        distance = stopLossRate - openRate;
-                    }
+        return {
+            "type": "object",
+            "description": "Calculates avg % distance from entry price to SL, bucketed by asset and leverage.",
+            "patternProperties": {
+                "^.*$": leverageSchema // Ticker
+            },
+            "additionalProperties": leverageSchema
+        };
+    }
 
-                    const distancePercent = (distance / openRate) * 100;
+    _initLeverage(assetData, leverage) {
+        const key = `${leverage}x`;
+        if (!assetData[key]) {
+            assetData[key] = { sum_dist: 0, count: 0 };
+        }
+        return key;
+    }
 
-                    if (distancePercent > 0) {
-                        if (!this.stopLossData[instrumentId]) {
-                            this.stopLossData[instrumentId] = {};
-                        }
-                        if (!this.stopLossData[instrumentId][leverage]) {
-                            this.stopLossData[instrumentId][leverage] = { distance_sum_percent: 0, count: 0 };
-                        }
-                        this.stopLossData[instrumentId][leverage].distance_sum_percent += distancePercent;
-                        this.stopLossData[instrumentId][leverage].count++;
-                    }
-                }
+    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;
+            const sl_rate = pos.StopLossRate || 0;
+            const open_rate = pos.OpenRate || 0;
+            
+            if (!instrumentId || sl_rate === 0 || open_rate === 0) {
+                continue; // Skip positions without SL or open rate
+            }
+
+            if (!this.assets.has(instrumentId)) {
+                this.assets.set(instrumentId, {});
             }
+            const assetData = this.assets.get(instrumentId);
+            
+            const leverage = pos.Leverage || 1;
+            const key = this._initLeverage(assetData, leverage);
+            
+            const distance = Math.abs(open_rate - sl_rate);
+            const distance_pct = (distance / open_rate);
+            
+            assetData[key].sum_dist += distance_pct;
+            assetData[key].count++;
         }
     }
 
@@ -52,17 +91,14 @@ class EntryDistanceToStopLossPerLeverage {
         }
 
         const result = {};
-        for (const instrumentId in this.stopLossData) {
-            const ticker = this.mappings.instrumentToTicker[instrumentId] || instrumentId.toString();
+        for (const [instrumentId, leverageData] of this.assets.entries()) {
+            const ticker = this.mappings.instrumentToTicker[instrumentId] || `id_${instrumentId}`;
             result[ticker] = {};
-            for (const leverage in this.stopLossData[instrumentId]) {
-                const data = this.stopLossData[instrumentId][leverage];
-                // REFACTOR: Perform final calculation directly.
+            
+            for (const leverageKey in leverageData) {
+                const data = leverageData[leverageKey];
                 if (data.count > 0) {
-                    result[ticker][leverage] = {
-                        average_distance_percent: data.distance_sum_percent / data.count,
-                        count: data.count
-                    };
+                    result[ticker][leverageKey] = (data.sum_dist / data.count) * 100;
                 }
             }
         }
@@ -70,9 +106,9 @@ class EntryDistanceToStopLossPerLeverage {
     }
 
     reset() {
-        this.stopLossData = {};
+        this.assets.clear();
         this.mappings = null;
     }
 }
 
-module.exports = EntryDistanceToStopLossPerLeverage;
+module.exports = EntryDistanceToSlPerLeverage;

package/calculations/speculators/entry_distance_to_tp_per_leverage.js

@@ -1,48 +1,87 @@
 /**
- * @fileoverview Calculates the average percentage distance from the entry price (OpenRate)
- * to the take profit rate for both long and short positions, grouped by asset and leverage level.
- * It ignores positions where the take profit is not meaningfully set.
+ * @fileoverview Calculation (Pass 1) for speculator metric.
+ *
+ * This metric answers: "For each asset and leverage level,
+ * what is the average percentage distance from the *entry price*
+ * to the take profit?" (This defines the intended reward).
  */
 const { loadInstrumentMappings } = require('../../utils/sector_mapping_provider');
 
-class EntryDistanceToTakeProfitPerLeverage {
+class EntryDistanceToTpPerLeverage {
     constructor() {
-        this.takeProfitData = {};
+        // { [instrumentId]: { [leverage]: { sum_dist: 0, count: 0 } } }
+        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;
-                const takeProfitRate = position.TakeProfitRate;
-                const openRate = position.OpenRate;
-                const isBuy = position.IsBuy;
+    /**
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
+     */
+    static getSchema() {
+        const leverageSchema = {
+            "type": "object",
+            "description": "Average entry-to-TP distance grouped by leverage.",
+            "patternProperties": {
+                // Leverage level, e.g., "1x", "5x", "10x"
+                "^[0-9]+x$": {
+                    "type": "number",
+                    "description": "The average percentage distance from entry price to Take Profit for this leverage level."
+                }
+            },
+            "additionalProperties": { "type": "number" }
+        };
 
-                if (takeProfitRate > 0.0001 && openRate > 0) {
-                    let distance;
-                    
-                    if (isBuy) {
-                        distance = takeProfitRate - openRate;
-                    } else {
-                        distance = openRate - takeProfitRate;
-                    }
+        return {
+            "type": "object",
+            "description": "Calculates avg % distance from entry price to TP, bucketed by asset and leverage.",
+            "patternProperties": {
+                "^.*$": leverageSchema // Ticker
+            },
+            "additionalProperties": leverageSchema
+        };
+    }
 
-                    const distancePercent = (distance / openRate) * 100;
+    _initLeverage(assetData, leverage) {
+        const key = `${leverage}x`;
+        if (!assetData[key]) {
+            assetData[key] = { sum_dist: 0, count: 0 };
+        }
+        return key;
+    }
 
-                    if (distancePercent > 0) {
-                        if (!this.takeProfitData[instrumentId]) {
-                            this.takeProfitData[instrumentId] = {};
-                        }
-                        if (!this.takeProfitData[instrumentId][leverage]) {
-                            this.takeProfitData[instrumentId][leverage] = { distance_sum_percent: 0, count: 0 };
-                        }
-                        this.takeProfitData[instrumentId][leverage].distance_sum_percent += distancePercent;
-                        this.takeProfitData[instrumentId][leverage].count++;
-                    }
-                }
+    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;
+            const tp_rate = pos.TakeProfitRate || 0;
+            const open_rate = pos.OpenRate || 0;
+            
+            if (!instrumentId || tp_rate === 0 || open_rate === 0) {
+                continue; // Skip positions without TP or open rate
             }
+
+            if (!this.assets.has(instrumentId)) {
+                this.assets.set(instrumentId, {});
+            }
+            const assetData = this.assets.get(instrumentId);
+            
+            const leverage = pos.Leverage || 1;
+            const key = this._initLeverage(assetData, leverage);
+            
+            const distance = Math.abs(tp_rate - open_rate);
+            const distance_pct = (distance / open_rate);
+            
+            assetData[key].sum_dist += distance_pct;
+            assetData[key].count++;
         }
     }
 
@@ -50,18 +89,16 @@ class EntryDistanceToTakeProfitPerLeverage {
         if (!this.mappings) {
             this.mappings = await loadInstrumentMappings();
         }
+
         const result = {};
-        for (const instrumentId in this.takeProfitData) {
-            const ticker = this.mappings.instrumentToTicker[instrumentId] || instrumentId.toString();
+        for (const [instrumentId, leverageData] of this.assets.entries()) {
+            const ticker = this.mappings.instrumentToTicker[instrumentId] || `id_${instrumentId}`;
             result[ticker] = {};
-            for (const leverage in this.takeProfitData[instrumentId]) {
-                const data = this.takeProfitData[instrumentId][leverage];
-                // REFACTOR: Perform final calculation directly.
+            
+            for (const leverageKey in leverageData) {
+                const data = leverageData[leverageKey];
                 if (data.count > 0) {
-                    result[ticker][leverage] = {
-                        average_distance_percent: data.distance_sum_percent / data.count,
-                        count: data.count
-                    };
+                    result[ticker][leverageKey] = (data.sum_dist / data.count) * 100;
                 }
             }
         }
@@ -69,9 +106,9 @@ class EntryDistanceToTakeProfitPerLeverage {
     }
 
     reset() {
-        this.takeProfitData = {};
+        this.assets.clear();
         this.mappings = null;
     }
 }
 
-module.exports = EntryDistanceToTakeProfitPerLeverage;
+module.exports = EntryDistanceToTpPerLeverage;