aiden-shared-calculations-unified 1.0.63 → 1.0.65

package/calculations/speculators/risk_reward_ratio_per_asset.js

@@ -1,33 +1,88 @@
 /**
- * @fileoverview Calculates the average risk-reward ratio per asset from speculator positions.
+ * @fileoverview Calculation (Pass 1) for speculator metric.
+ *
+ * This metric answers: "What is the average Risk/Reward
+ * ratio (based on SL/TP) for speculator positions on each asset?"
  */
 const { loadInstrumentMappings } = require('../../utils/sector_mapping_provider');
 
 class RiskRewardRatioPerAsset {
     constructor() {
-        this.rrData = {};
+        // { [instrumentId]: { sum_rr: 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) {
-                if (position.TakeProfitRate > 0 && position.StopLossRate > 0) {
-                    const instrumentId = position.InstrumentID;
-                    const openRate = position.OpenRate;
-                    const potentialReward = Math.abs(position.TakeProfitRate - openRate);
-                    const potentialRisk = Math.abs(openRate - position.StopLossRate);
-
-                    if (potentialRisk > 0) {
-                        const ratio = potentialReward / potentialRisk;
-                        if (!this.rrData[instrumentId]) {
-                            this.rrData[instrumentId] = { ratio_sum: 0, count: 0 };
-                        }
-                        this.rrData[instrumentId].ratio_sum += ratio;
-                        this.rrData[instrumentId].count++;
-                    }
+    /**
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
+     */
+    static getSchema() {
+        const tickerSchema = {
+            "type": "object",
+            "properties": {
+                "avg_rr_ratio": {
+                    "type": "number",
+                    "description": "Average Risk/Reward ratio (Reward / Risk)."
+                },
+                "count": {
+                    "type": "number",
+                    "description": "Count of positions with both SL and TP set."
                 }
+            },
+            "required": ["avg_rr_ratio", "count"]
+        };
+
+        return {
+            "type": "object",
+            "description": "Calculates the average Risk/Reward ratio from SL/TP settings for each asset.",
+            "patternProperties": {
+                "^.*$": tickerSchema // Ticker
+            },
+            "additionalProperties": tickerSchema
+        };
+    }
+
+    _initAsset(instrumentId) {
+        if (!this.assets.has(instrumentId)) {
+            this.assets.set(instrumentId, { sum_rr: 0, count: 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;
+            const sl_rate = pos.StopLossRate || 0;
+            const tp_rate = pos.TakeProfitRate || 0;
+            const open_rate = pos.OpenRate || 0;
+            
+            // Need all three to calculate R/R
+            if (!instrumentId || sl_rate === 0 || tp_rate === 0 || open_rate === 0) {
+                continue;
+            }
+            
+            const risk = Math.abs(open_rate - sl_rate);
+            const reward = Math.abs(tp_rate - open_rate);
+            
+            if (risk === 0) {
+                continue; // Cannot divide by zero
             }
+            
+            const rr_ratio = reward / risk;
+            
+            this._initAsset(instrumentId);
+            const assetData = this.assets.get(instrumentId);
+            assetData.sum_rr += rr_ratio;
+            assetData.count++;
         }
     }
 
@@ -35,26 +90,25 @@ class RiskRewardRatioPerAsset {
         if (!this.mappings) {
             this.mappings = await loadInstrumentMappings();
         }
-        const result = {};
-        for (const instrumentId in this.rrData) {
-            const ticker = this.mappings.instrumentToTicker[instrumentId] || instrumentId.toString();
-            const data = this.rrData[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_ratio: data.ratio_sum / data.count
+                    avg_rr_ratio: data.sum_rr / data.count,
+                    count: data.count
                 };
             }
         }
-
         return result;
     }
 
     reset() {
-        this.rrData = {};
+        this.assets.clear();
         this.mappings = null;
     }
 }
 
-module.exports = RiskRewardRatioPerAsset;
+module.exports = RiskRewardRatioPerAsset;

package/calculations/speculators/speculator_asset_sentiment.js

@@ -1,48 +1,110 @@
 /**
- * Aggregates and calculates average P/L, leverage, SL, and TP data for longs vs. shorts
- * on a per-asset basis for speculators.
+ * @fileoverview Calculation (Pass 1) for speculator metric.
+ *
+ * This metric answers: "For each asset, what are the average
+ * P&L, leverage, SL rate, and TP rate for *long* and *short*
+ * speculator positions?"
  */
 const { loadInstrumentMappings } = require('../../utils/sector_mapping_provider');
 
 class SpeculatorAssetSentiment {
     constructor() {
-        this.assets = {};
+        // { [instrumentId]: { long: {...}, short: {...} } }
+        this.assets = new Map();
         this.mappings = null;
     }
 
+    /**
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
+     */
+    static getSchema() {
+        const sentimentDetailSchema = {
+            "type": "object",
+            "properties": {
+                "avg_pnl_pct": { "type": "number" },
+                "avg_leverage": { "type": "number" },
+                "sl_rate_pct": { "type": "number" },
+                "tp_rate_pct": { "type": "number" },
+                "count": { "type": "number" }
+            },
+            "required": ["avg_pnl_pct", "avg_leverage", "sl_rate_pct", "tp_rate_pct", "count"]
+        };
+
+        const tickerSchema = {
+            "type": "object",
+            "properties": {
+                "long": sentimentDetailSchema,
+                "short": sentimentDetailSchema
+            },
+            "required": ["long", "short"]
+        };
+
+        return {
+            "type": "object",
+            "description": "Aggregates P&L, leverage, and SL/TP usage for speculators, split by long/short positions per asset.",
+            "patternProperties": {
+                "^.*$": tickerSchema // Ticker
+            },
+            "additionalProperties": tickerSchema
+        };
+    }
+
     _initAsset(instrumentId) {
-        if (!this.assets[instrumentId]) {
-            this.assets[instrumentId] = {
-                long: { count: 0, pnl_sum: 0, leverage_sum: 0, sl_rate_sum: 0, tp_rate_sum: 0 },
-                short: { count: 0, pnl_sum: 0, leverage_sum: 0, sl_rate_sum: 0, tp_rate_sum: 0 }
-            };
+        if (!this.assets.has(instrumentId)) {
+            const createSide = () => ({
+                pnl_sum: 0,
+                leverage_sum: 0,
+                sl_set_count: 0,
+                tp_set_count: 0,
+                count: 0
+            });
+            this.assets.set(instrumentId, {
+                long: createSide(),
+                short: createSide()
+            });
         }
     }
 
-    process(portfolioData, yesterdayPortfolio, userId, context) {
+    process(portfolioData) {
+        if (portfolioData?.context?.userType !== 'speculator') {
+            return;
+        }
+        
         const positions = portfolioData.PublicPositions;
-        if (!positions || !Array.isArray(positions)) return;
+        if (!positions || !Array.isArray(positions)) {
+            return;
+        }
 
-        for (const position of positions) {
-            const instrumentId = position.InstrumentID;
+        for (const pos of positions) {
+            const instrumentId = pos.InstrumentID;
             if (!instrumentId) continue;
-
+            
             this._initAsset(instrumentId);
-
-            const direction = position.IsBuy ? 'long' : 'short';
-            const stats = this.assets[instrumentId][direction];
-
-            stats.count++;
-            stats.pnl_sum += position.NetProfit;
-            stats.leverage_sum += position.Leverage;
-
-            if (position.StopLossRate && position.StopLossRate > 0) {
-                stats.sl_rate_sum += position.StopLossRate;
-            }
-            if (position.TakeProfitRate && position.TakeProfitRate > 0) {
-                stats.tp_rate_sum += position.TakeProfitRate;
-            }
+            const sideData = pos.IsBuy ? this.assets.get(instrumentId).long : this.assets.get(instrumentId).short;
+            
+            const pnl_percent = (pos.NetProfit || 0) / (pos.Amount || 1);
+            
+            sideData.pnl_sum += pnl_percent;
+            sideData.leverage_sum += pos.Leverage || 1;
+            if (pos.StopLossRate) sideData.sl_set_count++;
+            if (pos.TakeProfitRate) sideData.tp_set_count++;
+            sideData.count++;
+        }
+    }
+    
+    _calculateAverages(data) {
+        const count = data.count;
+        if (count === 0) {
+            return { avg_pnl_pct: 0, avg_leverage: 0, sl_rate_pct: 0, tp_rate_pct: 0, count: 0 };
         }
+        return {
+            avg_pnl_pct: data.pnl_sum / count,
+            avg_leverage: data.leverage_sum / count,
+            sl_rate_pct: (data.sl_set_count / count) * 100,
+            tp_rate_pct: (data.tp_set_count / count) * 100,
+            count: count
+        };
     }
 
     async getResult() {
@@ -50,32 +112,22 @@ class SpeculatorAssetSentiment {
             this.mappings = await loadInstrumentMappings();
         }
 
-        const finalResult = {};
-
-        for (const instrumentId in this.assets) {
-            const ticker = this.mappings.instrumentToTicker[instrumentId] || instrumentId.toString();
-            finalResult[ticker] = {};
-
-            for (const direction in this.assets[instrumentId]) {
-                const stats = this.assets[instrumentId][direction];
-                // REFACTOR: Perform final calculations.
-                finalResult[ticker][direction] = {
-                    count: stats.count,
-                    average_pnl: stats.count > 0 ? stats.pnl_sum / stats.count : 0,
-                    average_leverage: stats.count > 0 ? stats.leverage_sum / stats.count : 0,
-                    average_sl_rate: stats.count > 0 ? stats.sl_rate_sum / stats.count : 0,
-                    average_tp_rate: stats.count > 0 ? stats.tp_rate_sum / stats.count : 0,
-                };
-            }
+        const result = {};
+        for (const [instrumentId, data] of this.assets.entries()) {
+            const ticker = this.mappings.instrumentToTicker[instrumentId] || `id_${instrumentId}`;
+            
+            result[ticker] = {
+                long: this._calculateAverages(data.long),
+                short: this._calculateAverages(data.short)
+            };
         }
-        
-        return finalResult;
+        return result;
     }
 
     reset() {
-        this.assets = {};
+        this.assets.clear();
         this.mappings = null;
     }
 }
 
-module.exports = SpeculatorAssetSentiment;
+module.exports = SpeculatorAssetSentiment;

package/calculations/speculators/speculator_danger_zone.js

@@ -1,57 +1,125 @@
 /**
- * Counts speculator positions that are close to their stop loss ("Danger Zone").
- * This example defines "close" as within 5% of the current rate.
+ * @fileoverview Calculation (Pass 1) for speculator metric.
+ *
+ * This metric answers: "For each asset, how many long and
+ * short speculator positions are within 5% of their stop loss?"
  */
+const { loadInstrumentMappings } = require('../../utils/sector_mapping_provider');
+
 class SpeculatorDangerZone {
     constructor() {
-        this.danger_zone = {};
+        // { [instrumentId]: { long_in_danger: 0, short_in_danger: 0, long_total: 0, short_total: 0 } }
+        this.assets = new Map();
+        this.mappings = null;
     }
 
-    _initAsset(ticker) {
-        if (!this.danger_zone[ticker]) {
-            this.danger_zone[ticker] = { long_danger_count: 0, short_danger_count: 0 };
-        }
+    /**
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
+     */
+    static getSchema() {
+        const tickerSchema = {
+            "type": "object",
+            "properties": {
+                "long_in_danger": { "type": "number" },
+                "short_in_danger": { "type": "number" },
+                "long_total": { "type": "number" },
+                "short_total": { "type": "number" },
+                "long_danger_pct": {
+                    "type": "number",
+                    "description": "Percentage of long positions in the danger zone."
+                },
+                "short_danger_pct": {
+                    "type": "number",
+                    "description": "Percentage of short positions in the danger zone."
+                }
+            },
+            "required": ["long_in_danger", "short_in_danger", "long_total", "short_total", "long_danger_pct", "short_danger_pct"]
+        };
+
+        return {
+            "type": "object",
+            "description": "Tracks speculator positions within 5% of their Stop Loss.",
+            "patternProperties": {
+                "^.*$": tickerSchema // Ticker
+            },
+            "additionalProperties": tickerSchema
+        };
     }
 
-    process(portfolioData, yesterdayPortfolio, userId, context) {
-        const { instrumentMappings } = context;
+    _initAsset(instrumentId) {
+        if (!this.assets.has(instrumentId)) {
+            this.assets.set(instrumentId, {
+                long_in_danger: 0,
+                short_in_danger: 0,
+                long_total: 0,
+                short_total: 0
+            });
+        }
+    }
 
-        // FIX: Use the correct PublicPositions property for speculators
+    process(portfolioData) {
+        if (portfolioData?.context?.userType !== 'speculator') {
+            return;
+        }
+        
         const positions = portfolioData.PublicPositions;
-        if (!positions || !Array.isArray(positions)) return;
+        if (!positions || !Array.isArray(positions)) {
+            return;
+        }
 
-        for (const position of positions) {
-            // Ensure position has a valid stop loss and rate
-            if (!position.StopLossRate || position.StopLossRate <= 0 || !position.CurrentRate) {
+        for (const pos of positions) {
+            const instrumentId = pos.InstrumentID;
+            const sl_rate = pos.StopLossRate || 0;
+            const current_price = pos.LastCloseRate || 0;
+            
+            if (!instrumentId || sl_rate === 0 || current_price === 0) {
                 continue;
             }
+            
+            this._initAsset(instrumentId);
+            const assetData = this.assets.get(instrumentId);
+            
+            const distance = Math.abs(current_price - sl_rate);
+            const distance_pct = (distance / current_price);
+            
+            const isInDanger = distance_pct <= 0.05; // 5% danger zone
 
-            // FIX: Use the correct PascalCase InstrumentID
-            const ticker = instrumentMappings[position.InstrumentID];
-            if (!ticker) continue;
-
-            this._initAsset(ticker);
-
-            let distance_percent = 0;
-            // FIX: Use the correct PascalCase IsBuy
-            if (position.IsBuy) {
-                // Long position: Danger if SL is just below current rate
-                distance_percent = (position.CurrentRate - position.StopLossRate) / position.CurrentRate;
-                if (distance_percent > 0 && distance_percent < 0.05) {
-                    this.danger_zone[ticker].long_danger_count++;
+            if (pos.IsBuy) {
+                assetData.long_total++;
+                if (isInDanger) {
+                    assetData.long_in_danger++;
                 }
             } else {
-                // Short position: Danger if SL is just above current rate
-                distance_percent = (position.StopLossRate - position.CurrentRate) / position.CurrentRate;
-                if (distance_percent > 0 && distance_percent < 0.05) {
-                    this.danger_zone[ticker].short_danger_count++;
+                assetData.short_total++;
+                if (isInDanger) {
+                    assetData.short_in_danger++;
                 }
             }
         }
     }
 
-    getResult() {
-        return this.danger_zone;
+    async getResult() {
+        if (!this.mappings) {
+            this.mappings = await loadInstrumentMappings();
+        }
+
+        const result = {};
+        for (const [instrumentId, data] of this.assets.entries()) {
+            const ticker = this.mappings.instrumentToTicker[instrumentId] || `id_${instrumentId}`;
+            
+            result[ticker] = {
+                ...data,
+                long_danger_pct: (data.long_total > 0) ? (data.long_in_danger / data.long_total) * 100 : 0,
+                short_danger_pct: (data.short_total > 0) ? (data.short_in_danger / data.short_total) * 100 : 0
+            };
+        }
+        return result;
+    }
+
+    reset() {
+        this.assets.clear();
+        this.mappings = null;
     }
 }
 

package/calculations/speculators/stop_loss_distance_by_sector_short_long_breakdown.js

@@ -1,91 +1,118 @@
 /**
- * @fileoverview Calculates the average stop loss distance (percent and value)
- * for long and short positions, grouped by SECTOR.
+ * @fileoverview Calculation (Pass 1) for speculator metric.
+ *
+ * This metric answers: "For each sector, what is the
+ * average stop loss distance (in % and value) for
+ * long and short positions?"
  */
-const { getInstrumentSectorMap } = require('../../utils/sector_mapping_provider');
+const { loadInstrumentMappings } = require('../../utils/sector_mapping_provider');
 
-class StopLossDistanceBySector {
+class StopLossDistanceBySectorShortLongBreakdown {
     constructor() {
-        this.instrumentData = {};
-        this.instrumentToSector = null;
+        // { [sector]: { long_pct: [], long_val: [], short_pct: [], short_val: [] } }
+        this.sectors = new Map();
+        this.mappings = null;
     }
 
-    process(portfolioData, yesterdayPortfolio, userId, context) {
-        if (!portfolioData || !portfolioData.PublicPositions) return;
-
-        for (const position of portfolioData.PublicPositions) {
-            const { InstrumentID, Leverage, StopLossRate, CurrentRate, IsBuy } = position;
-            if (Leverage <= 1 || StopLossRate <= 0.0001 || CurrentRate <= 0) continue;
+    /**
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
+     */
+    static getSchema() {
+        const sectorSchema = {
+            "type": "object",
+            "properties": {
+                "long_avg_dist_pct": { "type": "number" },
+                "long_avg_dist_val": { "type": "number" },
+                "long_count": { "type": "number" },
+                "short_avg_dist_pct": { "type": "number" },
+                "short_avg_dist_val": { "type": "number" },
+                "short_count": { "type": "number" }
+            },
+            "required": ["long_avg_dist_pct", "long_avg_dist_val", "long_count", "short_avg_dist_pct", "short_avg_dist_val", "short_count"]
+        };
 
-            const distance_value = IsBuy ? CurrentRate - StopLossRate : StopLossRate - CurrentRate;
-            const distance_percent = (distance_value / CurrentRate) * 100;
+        return {
+            "type": "object",
+            "description": "Calculates avg SL distance (% and value) for long/short positions, grouped by sector.",
+            "patternProperties": {
+                "^.*$": sectorSchema // Sector
+            },
+            "additionalProperties": sectorSchema
+        };
+    }
 
-            if (distance_percent > 0) {
-                const posType = IsBuy ? 'long' : 'short';
-                if (!this.instrumentData[InstrumentID]) this.instrumentData[InstrumentID] = {};
-                if (!this.instrumentData[InstrumentID][posType]) {
-                    this.instrumentData[InstrumentID][posType] = {
-                        distance_percent_sum: 0,
-                        distance_value_sum: 0,
-                        count: 0
-                    };
-                }
-                const agg = this.instrumentData[InstrumentID][posType];
-                agg.distance_percent_sum += distance_percent;
-                agg.distance_value_sum += distance_value;
-                agg.count++;
-            }
+    _initSector(sector) {
+        if (!this.sectors.has(sector)) {
+            this.sectors.set(sector, {
+                long_pct: [], long_val: [], short_pct: [], short_val: []
+            });
         }
     }
+    
+    _avg(arr) {
+        if (arr.length === 0) return 0;
+        return arr.reduce((a, b) => a + b, 0) / arr.length;
+    }
 
-    async getResult() {
-        if (Object.keys(this.instrumentData).length === 0) return {};
-        if (!this.instrumentToSector) {
-            this.instrumentToSector = await getInstrumentSectorMap();
+    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;
         }
 
-        const sectorData = {};
-        for (const instrumentId in this.instrumentData) {
-            const sector = this.instrumentToSector[instrumentId] || 'N/A';
-            if (!sectorData[sector]) sectorData[sector] = {};
-
-            for (const posType in this.instrumentData[instrumentId]) {
-                if (!sectorData[sector][posType]) {
-                    sectorData[sector][posType] = {
-                        distance_percent_sum: 0,
-                        distance_value_sum: 0,
-                        count: 0
-                    };
-                }
-                const source = this.instrumentData[instrumentId][posType];
-                const target = sectorData[sector][posType];
-                target.distance_percent_sum += source.distance_percent_sum;
-                target.distance_value_sum += source.distance_value_sum;
-                target.count += source.count;
+        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;
+            }
+            
+            const sector = this.mappings.instrumentToSector[instrumentId] || 'Other';
+            this._initSector(sector);
+            const sectorData = this.sectors.get(sector);
+            
+            const distance_val = Math.abs(open_rate - sl_rate);
+            const distance_pct = (distance_val / open_rate) * 100;
+            
+            if (pos.IsBuy) {
+                sectorData.long_pct.push(distance_pct);
+                sectorData.long_val.push(distance_val);
+            } else {
+                sectorData.short_pct.push(distance_pct);
+                sectorData.short_val.push(distance_val);
             }
         }
+    }
 
+    async getResult() {
         const result = {};
-        for (const sector in sectorData) {
-            result[sector] = {};
-            for (const posType in sectorData[sector]) {
-                const data = sectorData[sector][posType];
-                // REFACTOR: Perform final calculation and return in standardized format.
-                if (data.count > 0) {
-                    result[sector][posType] = {
-                        average_distance_percent: data.distance_percent_sum / data.count,
-                        average_distance_value: data.distance_value_sum / data.count,
-                        count: data.count
-                    };
-                }
-            }
+        for (const [sector, data] of this.sectors.entries()) {
+            result[sector] = {
+                long_avg_dist_pct: this._avg(data.long_pct),
+                long_avg_dist_val: this._avg(data.long_val),
+                long_count: data.long_pct.length,
+                short_avg_dist_pct: this._avg(data.short_pct),
+                short_avg_dist_val: this._avg(data.short_val),
+                short_count: data.short_pct.length
+            };
         }
         return result;
     }
 
     reset() {
-        this.instrumentData = {};
+        this.sectors.clear();
+        this.mappings = null;
     }
 }
 
-module.exports = StopLossDistanceBySector;
+module.exports = StopLossDistanceBySectorShortLongBreakdown;