aiden-shared-calculations-unified 1.0.67 → 1.0.69

package/calculations/{speculators → behavioural/historical}/holding_duration_per_asset.js

@@ -1,14 +1,18 @@
 /**
- * @fileoverview Calculation (Pass 1) for speculator metric.
+ * @fileoverview Calculation (Pass 1) for user behaviour.
  *
- * This metric answers: "What is the average holding duration
- * (in hours) for open speculator positions, grouped by asset?"
+ * REFACTOR: This metric now answers: "What is the average holding duration
+ * (in hours) for *closed* positions, averaged across all users, grouped by asset?"
+ *
+ * This calculation now uses the 'history' data source, not 'portfolio'.
  */
-const { loadInstrumentMappings } = require('../../utils/sector_mapping_provider');
+const { loadInstrumentMappings } = require('../../../utils/sector_mapping_provider');
 
 class HoldingDurationPerAsset {
     constructor() {
         // { [instrumentId]: { sum_hours: 0, count: 0 } }
+        // 'sum_hours' will be the sum of user-level averages
+        // 'count' will be the number of users who traded that asset
         this.assets = new Map();
         this.mappings = null;
     }
@@ -23,11 +27,11 @@ class HoldingDurationPerAsset {
             "properties": {
                 "avg_duration_hours": {
                     "type": "number",
-                    "description": "Average holding duration in hours."
+                    "description": "Average holding duration in hours (averaged across all users)."
                 },
                 "count": {
                     "type": "number",
-                    "description": "Count of positions used in average."
+                    "description": "Count of users used in average."
                 }
             },
             "required": ["avg_duration_hours", "count"]
@@ -35,7 +39,7 @@ class HoldingDurationPerAsset {
 
         return {
             "type": "object",
-            "description": "Calculates the average holding duration (in hours) for open speculator positions per asset.",
+            "description": "Calculates the average holding duration (in hours) for closed positions per asset, averaged across all users.",
             "patternProperties": {
                 "^.*$": tickerSchema // Ticker
             },
@@ -48,40 +52,40 @@ class HoldingDurationPerAsset {
             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)) {
+    /**
+     * Process data from the 'history' root data source.
+     * @param {object} rootData - The root data object from the runner.
+     * @param {string} userId - The user ID.
+     */
+    process(rootData, userId) {
+        // 1. Get the history data
+        const historyData = rootData.history;
+        if (!historyData || !Array.isArray(historyData.assets)) {
             return;
         }
 
-        for (const pos of positions) {
-            const instrumentId = pos.InstrumentID;
-            if (!instrumentId) continue;
-            
-            this._initAsset(instrumentId);
+        // 2. Iterate over the aggregated assets in the history doc
+        for (const asset of historyData.assets) {
+            const instrumentId = asset.instrumentId;
+
+            // Skip the "all" aggregate entry
+            if (!instrumentId || instrumentId === -1) {
+                continue;
+            }
             
-            const duration = this._getHoldingDurationHours(pos.OpenDateTime);
+            const durationMinutes = asset.avgHoldingTimeInMinutes;
             
-            if (duration > 0) {
+            if (typeof durationMinutes === 'number' && durationMinutes > 0) {
+                this._initAsset(instrumentId);
+                
                 const assetData = this.assets.get(instrumentId);
-                assetData.sum_hours += duration;
+                
+                // Convert minutes to hours and add to the sum
+                assetData.sum_hours += (durationMinutes / 60);
+                
+                // Increment count (this now counts *users* who have
+                // an average for this asset, not individual positions)
                 assetData.count++;
             }
         }
@@ -98,6 +102,7 @@ class HoldingDurationPerAsset {
             
             if (data.count > 0) {
                 result[ticker] = {
+                    // Calculate the final average (avg of avgs)
                     avg_duration_hours: data.sum_hours / data.count,
                     count: data.count
                 };

package/calculations/behavioural/overall_holding_duration.js

@@ -0,0 +1,79 @@
+/**
+ * @fileoverview Calculation (Pass 1) for user behaviour.
+ *
+ * This metric answers: "What is the average holding duration (in hours)
+ * for *closed* positions, averaged across all users?"
+ *
+ * It uses the 'history' data source's 'all' object.
+ */
+class AverageHoldingDurationOverall {
+    constructor() {
+        // Stores all the user-level average durations
+        this.durationsHours = [];
+    }
+
+    /**
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
+     */
+    static getSchema() {
+        return {
+            "type": "object",
+            "description": "Calculates the platform-wide average holding duration (in hours) for closed positions.",
+            "properties": {
+                "average_duration_hours": {
+                    "type": "number",
+                    "description": "The average holding duration in hours, averaged across all users."
+                },
+                "user_count": {
+                    "type": "number",
+                    "description": "The number of users included in the average."
+                }
+            },
+            "required": ["average_duration_hours", "user_count"]
+        };
+    }
+
+    /**
+     * Process data from the 'history' root data source.
+     * @param {object} rootData - The root data object from the runner.
+     * @param {string} userId - The user ID.
+     */
+    process(rootData, userId) {
+        // 1. Get the history data
+        const historyData = rootData.history;
+        if (!historyData || !historyData.all) {
+            return;
+        }
+
+        // 2. Get the user's overall average holding time
+        const durationMinutes = historyData.all.avgHoldingTimeInMinutes;
+
+        if (typeof durationMinutes === 'number' && durationMinutes > 0) {
+            this.durationsHours.push(durationMinutes / 60);
+        }
+    }
+
+    getResult() {
+        const count = this.durationsHours.length;
+        if (count === 0) {
+            return {
+                average_duration_hours: 0,
+                user_count: 0
+            };
+        }
+
+        const sum = this.durationsHours.reduce((a, b) => a + b, 0);
+        
+        return {
+            average_duration_hours: sum / count,
+            user_count: count
+        };
+    }
+
+    reset() {
+        this.durationsHours = [];
+    }
+}
+
+module.exports = AverageHoldingDurationOverall;

package/calculations/insights/daily_buy_sell_sentiment_count.js

@@ -1,16 +1,11 @@
 /**
  * @fileoverview Calculation (Pass 1) for daily buy/sell sentiment.
  *
- * This metric tracks the total number of 'buy' (long) vs 'sell' (short)
- * positions held across all instruments.
- *
- * This provides a raw, global sentiment reading.
+ * REFACTOR: This is now a 'type: "meta"' calculation. It runs ONCE.
+ * It reads the pre-aggregated 'insights' data source and sums the
+ * 'buy' and 'sell' counts from all instruments.
  */
 class DailyBuySellSentimentCount {
-    constructor() {
-        this.buyPositions = 0;
-        this.sellPositions = 0;
-    }
 
     /**
      * Defines the output schema for this calculation.
@@ -38,34 +33,49 @@ class DailyBuySellSentimentCount {
         };
     }
 
-    process(portfolioData) {
-        const positions = portfolioData.PublicPositions || portfolioData.AggregatedPositions;
-        if (!positions || !Array.isArray(positions)) {
-            return;
+    /**
+     * This is a 'meta' calculation. It runs once.
+     * @param {string} dateStr - The date string 'YYYY-MM-DD'.
+     * @param {object} rootData - The root data object. We expect rootData.insights.
+     * @param {object} dependencies - The shared dependencies (e.g., logger).
+     * @returns {object} The calculation result.
+     */
+    process(dateStr, rootData, dependencies) {
+        let totalBuyPositions = 0;
+        let totalSellPositions = 0;
+
+        // rootData.insights contains the document from /daily_instrument_insights/
+        const insightsDoc = rootData.insights;
+
+        if (!insightsDoc || !Array.isArray(insightsDoc.insights)) {
+            dependencies.logger.log('WARN', `[daily-buy-sell-sentiment-count] No 'insights' data found for ${dateStr}.`);
+            return {
+                totalBuyPositions: 0,
+                totalSellPositions: 0,
+                sentimentRatio: null
+            };
         }
 
-        for (const pos of positions) {
-            if (pos.IsBuy) {
-                this.buyPositions++;
-            } else {
-                this.sellPositions++;
+        // Iterate over the pre-aggregated array
+        for (const instrument of insightsDoc.insights) {
+            // The doc has pre-aggregated 'buy' and 'sell' counts
+            if (typeof instrument.buy === 'number') {
+                totalBuyPositions += instrument.buy;
+            }
+            if (typeof instrument.sell === 'number') {
+                totalSellPositions += instrument.sell;
             }
         }
-    }
 
-    getResult() {
         return {
-            totalBuyPositions: this.buyPositions,
-            totalSellPositions: this.sellPositions,
+            totalBuyPositions: totalBuyPositions,
+            totalSellPositions: totalSellPositions,
             // Calculate ratio: Buy / Sell
-            sentimentRatio: (this.sellPositions > 0) ? (this.buyPositions / this.sellPositions) : null
+            sentimentRatio: (totalSellPositions > 0) ? (totalBuyPositions / totalSellPositions) : null
         };
     }
 
-    reset() {
-        this.buyPositions = 0;
-        this.sellPositions = 0;
-    }
+    // No constructor, getResult(), or reset() methods are needed for 'meta' calcs
 }
 
 module.exports = DailyBuySellSentimentCount;

package/calculations/insights/daily_ownership_per_sector.js

@@ -0,0 +1,87 @@
+/**
+ * @fileoverview Calculation (Pass 1) for daily ownership per sector.
+ *
+ * This is a 'type: "meta"' calculation. It runs ONCE.
+ * It reads the pre-aggregated 'insights' data source (/daily_instrument_insights/)
+ * and uses the sector mapping provider to aggregate the total number
+ * of owners for each sector.
+ */
+const { loadInstrumentMappings } = require('../../utils/sector_mapping_provider');
+
+class DailyOwnershipPerSector {
+
+    /**
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
+     */
+    static getSchema() {
+        const sectorSchema = {
+            "type": "object",
+            "description": "Aggregated ownership for a single sector.",
+            "properties": {
+                "total_owners": {
+                    "type": "number",
+                    "description": "The total number of unique owners for all assets in this sector."
+                }
+            },
+            "required": ["total_owners"]
+        };
+
+        return {
+            "type": "object",
+            "description": "Calculates the total unique owners per sector based on the 'insights' data source.",
+            "patternProperties": {
+                "^.*$": sectorSchema // Matches any string key (sector name)
+            },
+            "additionalProperties": sectorSchema
+        };
+    }
+
+    /**
+     * This is a 'meta' calculation. It runs once.
+     * @param {string} dateStr - The date string 'YYYY-MM-DD'.
+     * @param {object} rootData - The root data object. We expect rootData.insights.
+     * @param {object} dependencies - The shared dependencies (e.g., logger).
+     * @returns {Promise<object>} The calculation result.
+     */
+    async process(dateStr, rootData, dependencies) {
+        // { [sectorName]: { total_owners: 0 } }
+        const sectorOwners = new Map();
+        
+        // 1. Load mappings
+        const mappings = await loadInstrumentMappings();
+
+        // 2. Get the insights document
+        const insightsDoc = rootData.insights;
+        if (!insightsDoc || !Array.isArray(insightsDoc.insights)) {
+            dependencies.logger.log('WARN', `[daily-ownership-per-sector] No 'insights' data found for ${dateStr}.`);
+            return {};
+        }
+
+        // 3. Iterate over the pre-aggregated array
+        for (const instrument of insightsDoc.insights) {
+            const instrumentId = instrument.instrumentId;
+            const totalOwners = instrument.total; // 'total' is the owner count
+
+            if (!instrumentId || typeof totalOwners !== 'number' || totalOwners === 0) {
+                continue;
+            }
+
+            // Find the sector for this instrument
+            const sectorName = mappings.instrumentToSectorName[instrumentId] || 'N/A';
+
+            // Initialize if new
+            if (!sectorOwners.has(sectorName)) {
+                sectorOwners.set(sectorName, { total_owners: 0 });
+            }
+
+            // Add this instrument's owners to the sector's total
+            sectorOwners.get(sectorName).total_owners += totalOwners;
+        }
+
+        // Convert Map to plain object for Firestore
+        return Object.fromEntries(sectorOwners);
+    }
+}
+
+module.exports = DailyOwnershipPerSector;

package/calculations/insights/daily_total_positions_held.js

@@ -1,16 +1,12 @@
 /**
  * @fileoverview Calculation (Pass 1) for total positions held.
  *
- * This is a simple counter that calculates the total number of positions
- * held across all users and all instruments today.
- *
- * It provides a measure of overall market participation.
+ * REFACTOR: This is now a 'type: "meta"' calculation. It runs ONCE.
+ * It reads the pre-aggregated 'insights' data source and sums the
+ * 'total' field from all instruments to get the platform-wide total.
  */
 class DailyTotalPositionsHeld {
-    constructor() {
-        this.totalPositions = 0;
-    }
-
+    
     /**
      * Defines the output schema for this calculation.
      * @returns {object} JSON Schema object
@@ -29,22 +25,37 @@ class DailyTotalPositionsHeld {
         };
     }
 
-    process(portfolioData) {
-        const positions = portfolioData.PublicPositions || portfolioData.AggregatedPositions;
-        if (positions && Array.isArray(positions)) {
-            this.totalPositions += positions.length;
+    /**
+     * This is a 'meta' calculation. It runs once.
+     * @param {string} dateStr - The date string 'YYYY-MM-DD'.
+     * @param {object} rootData - The root data object. We expect rootData.insights.
+     * @param {object} dependencies - The shared dependencies (e.g., logger).
+     * @returns {object} The calculation result.
+     */
+    process(dateStr, rootData, dependencies) {
+        let totalPositions = 0;
+        
+        // rootData.insights contains the document from /daily_instrument_insights/
+        const insightsDoc = rootData.insights;
+        
+        if (!insightsDoc || !Array.isArray(insightsDoc.insights)) {
+            dependencies.logger.log('WARN', `[daily-total-positions-held] No 'insights' data found for ${dateStr}.`);
+            return { totalPositions: 0 };
         }
-    }
 
-    getResult() {
+        for (const instrument of insightsDoc.insights) {
+            // The 'total' field from the doc is the total # of positions for that instrument
+            if (typeof instrument.total === 'number') {
+                totalPositions += instrument.total;
+            }
+        }
+        
         return {
-            totalPositions: this.totalPositions
+            totalPositions: totalPositions
         };
     }
-
-    reset() {
-        this.totalPositions = 0;
-    }
+    
+    // No getResult() or reset() methods are needed for a 'meta' calculation
 }
 
 module.exports = DailyTotalPositionsHeld;

package/calculations/insights/historical/daily_ownership_delta.js

@@ -1,20 +1,17 @@
 /**
- * @fileoverview Calculation (Pass 2) for daily ownership delta.
+ * @fileoverview Calculation (Pass 1) for daily ownership delta.
  *
  * This metric calculates the daily change in the total number of *owners*
  * (unique users) for each instrument.
  *
- * This measures the broadening or narrowing of an asset's holder base.
+ * REFACTOR: This is now a 'type: "meta"' and 'isHistorical: true' calculation.
+ * It runs ONCE, loads today's and yesterday's pre-aggregated 'insights' docs,
+ * and calculates the delta based on the 'total' field.
  */
 const { loadInstrumentMappings } = require('../../../utils/sector_mapping_provider');
 
 class DailyOwnershipDelta {
-    constructor() {
-        // We will store { [instrumentId]: { owners_yesterday: Set(), owners_today: Set() } }
-        this.assetOwnership = new Map();
-        this.mappings = null;
-    }
-
+    
     /**
      * Defines the output schema for this calculation.
      * @returns {object} JSON Schema object
@@ -54,55 +51,49 @@ class DailyOwnershipDelta {
         };
     }
 
-    _initAsset(instrumentId) {
-        if (!this.assetOwnership.has(instrumentId)) {
-            this.assetOwnership.set(instrumentId, {
-                owners_yesterday: new Set(),
-                owners_today: new Set()
-            });
-        }
-    }
-
-    _getInstrumentIds(portfolio) {
-        const positions = portfolio?.AggregatedPositions || portfolio?.PublicPositions;
-        if (!positions || !Array.isArray(positions)) {
-            return new Set();
-        }
-        return new Set(positions.map(p => p.InstrumentID).filter(Boolean));
-    }
-
-    process(todayPortfolio, yesterdayPortfolio, userId) {
-        if (!todayPortfolio || !yesterdayPortfolio) {
-            return;
-        }
-
-        const yIds = this._getInstrumentIds(yesterdayPortfolio);
-        const tIds = this._getInstrumentIds(todayPortfolio);
-
-        // Add user to yesterday's owner sets
-        for (const yId of yIds) {
-            this._initAsset(yId);
-            this.assetOwnership.get(yId).owners_yesterday.add(userId);
-        }
-
-        // Add user to today's owner sets
-        for (const tId of tIds) {
-            this._initAsset(tId);
-            this.assetOwnership.get(tId).owners_today.add(userId);
+    /**
+     * This is a 'meta' and 'historical' calculation. It runs once.
+     * @param {string} dateStr - The date string 'YYYY-MM-DD'.
+     * @param {object} todayRootData - Root data for today. We expect todayRootData.insights.
+     * @param {object} yesterdayRootData - Root data for yesterday. We expect yesterdayRootData.insights.
+     * @returns {Promise<object>} The calculation result.
+     */
+    async process(dateStr, todayRootData, yesterdayRootData) {
+        const mappings = await loadInstrumentMappings();
+        
+        const todayOwners = new Map();
+        const yesterdayOwners = new Map();
+        const allInstrumentIds = new Set();
+        
+        // 1. Process today's insights doc
+        const todayDoc = todayRootData.insights;
+        if (todayDoc && Array.isArray(todayDoc.insights)) {
+            for (const instrument of todayDoc.insights) {
+                const id = instrument.instrumentId;
+                const totalOwners = instrument.total || 0; // 'total' is the owner count
+                todayOwners.set(id, totalOwners);
+                allInstrumentIds.add(id);
+            }
         }
-    }
-
-    async getResult() {
-        if (!this.mappings) {
-            this.mappings = await loadInstrumentMappings();
+        
+        // 2. Process yesterday's insights doc
+        const yesterdayDoc = yesterdayRootData.insights;
+        if (yesterdayDoc && Array.isArray(yesterdayDoc.insights)) {
+            for (const instrument of yesterdayDoc.insights) {
+                const id = instrument.instrumentId;
+                const totalOwners = instrument.total || 0; // 'total' is the owner count
+                yesterdayOwners.set(id, totalOwners);
+                allInstrumentIds.add(id);
+            }
         }
-
+        
+        // 3. Calculate deltas
         const result = {};
-        for (const [instrumentId, data] of this.assetOwnership.entries()) {
-            const ticker = this.mappings.instrumentToTicker[instrumentId] || `id_${instrumentId}`;
+        for (const instrumentId of allInstrumentIds) {
+            const ticker = mappings.instrumentToTicker[instrumentId] || `id_${instrumentId}`;
             
-            const yOwners = data.owners_yesterday.size;
-            const tOwners = data.owners_today.size;
+            const tOwners = todayOwners.get(instrumentId) || 0;
+            const yOwners = yesterdayOwners.get(instrumentId) || 0;
             
             if (yOwners > 0 || tOwners > 0) {
                 result[ticker] = {
@@ -113,13 +104,11 @@ class DailyOwnershipDelta {
                 };
             }
         }
+        
         return result;
     }
 
-    reset() {
-        this.assetOwnership.clear();
-        this.mappings = null;
-    }
+    // No getResult() or reset() methods are needed
 }
 
 module.exports = DailyOwnershipDelta;

package/calculations/meta/positive_expectancy_cohort_flow.js

@@ -7,7 +7,7 @@
  * This calculation *depends* on 'user_expectancy_score'
  * to identify the cohort.
  */
-const { loadInstrumentMappings } = require('../../../utils/sector_mapping_provider');
+const { loadInstrumentMappings } = require('../../utils/sector_mapping_provider');
 
 class PositiveExpectancyCohortFlow {
     constructor() {

package/calculations/pnl/overall_profitability_ratio.js

@@ -0,0 +1,71 @@
+/**
+ * @fileoverview Calculation (Pass 1) for P&L.
+ *
+ * This metric provides the *overall* platform-wide profitability ratio
+ * (total profitable positions / total unprofitable positions)
+ * across all users and all open positions.
+ */
+class ProfitabilityRatioOverall {
+    constructor() {
+        this.profitable = 0;
+        this.unprofitable = 0;
+    }
+
+    /**
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
+     */
+    static getSchema() {
+        return {
+            "type": "object",
+            "description": "Calculates the overall profitability ratio (profitable/unprofitable positions) for the entire platform.",
+            "properties": {
+                "overall_ratio": {
+                    "type": ["number", "null"],
+                    "description": "Ratio of profitable to unprofitable positions (profitable / unprofitable). Null if 0 unprofitable."
+                },
+                "total_profitable": {
+                    "type": "number",
+                    "description": "Total count of all profitable positions."
+                },
+                "total_unprofitable": {
+                    "type": "number",
+                    "description": "Total count of all unprofitable positions."
+                }
+            },
+            "required": ["overall_ratio", "total_profitable", "total_unprofitable"]
+        };
+    }
+
+    process(portfolioData) {
+        const positions = portfolioData.PublicPositions || portfolioData.AggregatedPositions;
+        if (!positions || !Array.isArray(positions)) {
+            return;
+        }
+
+        for (const pos of positions) {
+            const pnl = pos.NetProfit;
+
+            if (pnl > 0) {
+                this.profitable++;
+            } else if (pnl < 0) {
+                this.unprofitable++;
+            }
+        }
+    }
+
+    getResult() {
+        return {
+            overall_ratio: (this.unprofitable > 0) ? (this.profitable / this.unprofitable) : null,
+            total_profitable: this.profitable,
+            total_unprofitable: this.unprofitable
+        };
+    }
+
+    reset() {
+        this.profitable = 0;
+        this.unprofitable = 0;
+    }
+}
+
+module.exports = ProfitabilityRatioOverall;