aiden-shared-calculations-unified 1.0.64 → 1.0.65

package/README.MD

@@ -21,7 +21,7 @@ Contains the core calculation logic, organized into subdirectories representing
 
 * **Calculation Class Structure:** Each `.js` file defines a class responsible for a specific metric. Every class **must** implement:
     * `constructor()`: Initializes any internal state needed for aggregation.
-    * `process(portfolioData, userId, context)` OR `process(todayPortfolio, yesterdayPortfolio, userId)`: Processes a single user's data. The signature depends on whether the calculation requires historical comparison. `context` provides shared data like mappings.
+    * `process(portfolioData, userId, context)` OR `process(todayPortfolio, yesterdayPortfolio, userId, context)`: Processes a single user's data. The signature depends on whether the calculation requires historical comparison. `context` provides shared data like mappings.
     * `getResult()`: Returns the final, calculated result for the aggregation period. **Crucially, this method must perform any final averaging (e.g., sum/count) itself.** It should return the final value or object ready for storage, not raw components.
     * `reset()`: (Optional but recommended) Resets the internal state, often used by the calling system between processing batches or days.
 

package/calculations/activity/historical/activity_by_pnl_status.js

@@ -15,6 +15,39 @@ class ActivityByPnlStatus {
         };
     }
 
+    /**
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
+     */
+    static getSchema() {
+        return {
+            "type": "object",
+            "description": "Measures profit-taking vs. capitulation by analyzing the P&L of closed positions.",
+            "properties": {
+                "profit_taking_rate_pct": {
+                    "type": "number",
+                    "description": "The percentage of profitable positions (from yesterday) that were closed today."
+                },
+                "capitulation_rate_pct": {
+                    "type": "number",
+                    "description": "The percentage of losing positions (from yesterday) that were closed today."
+                },
+                "raw_counts": {
+                    "type": "object",
+                    "description": "Raw counts used to calculate the rates.",
+                    "properties": {
+                        "profit_positions_closed": { "type": "number" },
+                        "loss_positions_closed": { "type": "number" },
+                        "total_profit_positions_available": { "type": "number" },
+                        "total_loss_positions_available": { "type": "number" }
+                    },
+                    "required": ["profit_positions_closed", "loss_positions_closed", "total_profit_positions_available", "total_loss_positions_available"]
+                }
+            },
+            "required": ["profit_taking_rate_pct", "capitulation_rate_pct", "raw_counts"]
+        };
+    }
+
     _getPortfolioMap(portfolio) {
         // We MUST use PositionID here to track specific trades, not just the asset
         const positions = portfolio?.AggregatedPositions || portfolio?.PublicPositions;

package/calculations/activity/historical/daily_asset_activity.js

@@ -11,6 +11,48 @@ class DailyAssetActivity {
         this.mappings = null;
     }
 
+    /**
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
+     */
+    static getSchema() {
+        return {
+            "type": "object",
+            "description": "Tracks the net flow of unique users opening or closing positions per asset.",
+            "patternProperties": {
+                // This matches any string key (which will be a ticker)
+                "^.*$": {
+                    "type": "object",
+                    "description": "User flow metrics for a specific asset ticker.",
+                    "properties": {
+                        "opened_by_user_count": {
+                            "type": "number",
+                            "description": "Count of unique users who opened a position in this asset."
+                        },
+                        "closed_by_user_count": {
+                            "type": "number",
+                            "description": "Count of unique users who closed their position in this asset."
+                        },
+                        "net_user_flow": {
+                            "type": "number",
+                            "description": "Net change in users (opened - closed)."
+                        }
+                    },
+                    "required": ["opened_by_user_count", "closed_by_user_count", "net_user_flow"]
+                }
+            },
+            // Use 'additionalProperties' as a fallback for patternProperties
+            "additionalProperties": {
+                "type": "object",
+                "properties": {
+                    "opened_by_user_count": { "type": "number" },
+                    "closed_by_user_count": { "type": "number" },
+                    "net_user_flow": { "type": "number" }
+                }
+            }
+        };
+    }
+
     _initAsset(instrumentId) {
         if (!this.assetActivity.has(instrumentId)) {
             this.assetActivity.set(instrumentId, {

package/calculations/activity/historical/daily_user_activity_tracker.js

@@ -17,6 +17,43 @@ class DailyUserActivityTracker {
         };
     }
 
+    /**
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
+     */
+    static getSchema() {
+        return {
+            "type": "object",
+            "description": "Tracks the count of daily active users based on portfolio changes.",
+            "properties": {
+                "rawActiveUserCount": {
+                    "type": "number",
+                    "description": "The total count of unique users who were active today (opened, closed, or reallocated)."
+                },
+                "activityBreakdown": {
+                    "type": "object",
+                    "description": "A breakdown of the first activity event type recorded for active users.",
+                    "properties": {
+                        "new_position": {
+                            "type": "number",
+                            "description": "Count of users whose first detected activity was opening a new position."
+                        },
+                        "closed_position": {
+                            "type": "number",
+                            "description": "Count of users whose first detected activity was closing an existing position."
+                        },
+                        "reallocation": {
+                            "type": "number",
+                            "description": "Count of users whose first detected activity was reallocating an existing position."
+                        }
+                    },
+                    "required": ["new_position", "closed_position", "reallocation"]
+                }
+            },
+            "required": ["rawActiveUserCount", "activityBreakdown"]
+        };
+    }
+
     /**
      * Helper to get a simplified map of positions for comparison.
      * @param {object} portfolio - A user's full portfolio object.

package/calculations/activity/historical/speculator_adjustment_activity.js

@@ -11,6 +11,32 @@ class SpeculatorAdjustmentActivity {
         this.tsl_toggled_users = new Set();
     }
 
+    /**
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
+     */
+    static getSchema() {
+        return {
+            "type": "object",
+            "description": "Tracks unique speculators who 'tinkered' with open trades by adjusting SL, TP, or TSL.",
+            "properties": {
+                "unique_users_adjusted_sl": {
+                    "type": "number",
+                    "description": "Count of unique speculators who adjusted a Stop Loss on at least one position."
+                },
+                "unique_users_adjusted_tp": {
+                    "type": "number",
+                    "description": "Count of unique speculators who adjusted a Take Profit on at least one position."
+                },
+                "unique_users_toggled_tsl": {
+                    "type": "number",
+                    "description": "Count of unique speculators who enabled or disabled a Trailing Stop Loss on at least one position."
+                }
+            },
+            "required": ["unique_users_adjusted_sl", "unique_users_adjusted_tp", "unique_users_toggled_tsl"]
+        };
+    }
+
     _getPublicPositionsMap(portfolio) {
         const positions = portfolio?.PublicPositions;
         if (!positions || !Array.isArray(positions)) {

package/calculations/asset_metrics/asset_position_size.js

@@ -9,6 +9,42 @@ class AssetPositionSize {
         this.mappings = null;
     }
 
+    /**
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
+     */
+    static getSchema() {
+        return {
+            "type": "object",
+            "description": "Calculates the average position size (as a portfolio percentage) and holder count for each asset.",
+            "patternProperties": {
+                // This matches any string key (which will be a ticker)
+                "^.*$": {
+                    "type": "object",
+                    "description": "Metrics for a specific asset ticker.",
+                    "properties": {
+                        "average_position_size": {
+                            "type": "number",
+                            "description": "The average portfolio percentage allocated to this asset by users who hold it."
+                        },
+                        "position_count": {
+                            "type": "number",
+                            "description": "The total number of positions held in this asset across the user sample."
+                        }
+                    },
+                    "required": ["average_position_size", "position_count"]
+                }
+            },
+            "additionalProperties": {
+                "type": "object",
+                "properties": {
+                    "average_position_size": { "type": "number" },
+                    "position_count": { "type": "number" }
+                }
+            }
+        };
+    }
+
     process(portfolioData, yesterdayPortfolio, userId, context, todayInsights, yesterdayInsights) {
         const positions = portfolioData.AggregatedPositions || portfolioData.PublicPositions;
         if (!positions || !Array.isArray(positions)) return;

package/calculations/backtests/strategy-performance.js

@@ -23,6 +23,47 @@ class StrategyPerformance {
         return ['smart-dumb-divergence-index', 'profit-cohort-divergence'];
     }
 
+    /**
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
+     */
+    static getSchema() {
+        return {
+            "type": ["object", "null"],
+            "description": "Result of a full historical backtest of a trading strategy. Returns null if simulation fails.",
+            "properties": {
+                "strategyName": {
+                    "type": "string",
+                    "description": "The name of the simulated strategy."
+                },
+                "inceptionDate": {
+                    "type": "string",
+                    "description": "The first date a signal was found, marking the start of the backtest."
+                },
+                "endDate": {
+                    "type": "string",
+                    "description": "The final date of the backtest simulation."
+                },
+                "finalPortfolioValue": {
+                    "type": "number",
+                    "description": "The final equity value of the portfolio at the end of the simulation."
+                },
+                "totalReturnPercent": {
+                    "type": "number",
+                    "description": "The total percentage return of the strategy from inception to end date."
+                }
+            },
+            // "required" is not needed at the top level since the whole object can be null.
+            // If the object is *not* null, we can imply these fields are required.
+            "if": {
+                "type": "object"
+            },
+            "then": {
+                "required": ["strategyName", "inceptionDate", "endDate", "finalPortfolioValue", "totalReturnPercent"]
+            }
+        };
+    }
+
     constructor() {
         this.INITIAL_CASH = 100000;
         this.TRADE_SIZE_USD = 5000;

package/calculations/behavioural/historical/asset_crowd_flow.js

@@ -1,165 +1,162 @@
-const { loadAllPriceData, getDailyPriceChange } = require('../../../utils/price_data_provider');
-const { loadInstrumentMappings } = require('../../../utils/sector_mapping_provider');
-
 /**
- * @fileoverview Calculates "Net Crowd Flow" for each asset.
- *
- * This isolates the change in an asset's average portfolio percentage
- * that is *not* explained by the asset's own price movement.
+ * @fileoverview Calculation (Pass 2) for asset crowd flow.
  *
- * Net Crowd Flow = (Actual % Change) - (Expected % Change from Price Move)
+ * This metric calculates the "Net Crowd Flow Percentage" for each asset.
+ * It's defined as the net percentage of the crowd's capital flowing in or out
+ * of an asset, *adjusted for the asset's own price movement*.
  *
- * A positive value means the crowd actively bought (flowed into) the asset.
- * A negative value means the crowd actively sold (flowed out of) the asset.
+ * This isolates true buying/selling pressure from simple value changes.
  */
+const { loadInstrumentMappings } = require('../../../utils/sector_mapping_provider');
+
 class AssetCrowdFlow {
     constructor() {
-        this.asset_values = {}; // Stores { day1_value_sum: 0, day2_value_sum: 0 }
-        this.user_count = 0;
-        this.priceMap = null;
+        this.assetData = new Map();
         this.mappings = null;
-        this.dates = {}; // To store { today: '...', yesterday: '...' }
     }
 
     /**
-     * Helper to safely initialize an asset entry.
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
      */
-    _initAsset(instrumentId) {
-        if (!this.asset_values[instrumentId]) {
-            this.asset_values[instrumentId] = {
-                day1_value_sum: 0,
-                day2_value_sum: 0
-            };
-        }
-    }
-
-    /**
-     * Helper to sum the 'Value' field from an AggregatedPositions array.
-     */
-    _sumAssetValue(positions) {
-        const valueMap = {};
-        if (!positions || !Array.isArray(positions)) {
-            return valueMap;
-        }
-        for (const pos of positions) {
-            if (pos && pos.InstrumentID && pos.Value) {
-                valueMap[pos.InstrumentID] = (valueMap[pos.InstrumentID] || 0) + pos.Value;
+    static getSchema() {
+        return {
+            "type": "object",
+            "description": "Calculates the net capital flow % per asset, adjusted for price movements.",
+            "patternProperties": {
+                // Ticker
+                "^.*$": {
+                    "type": "object",
+                    "description": "Net crowd flow metrics for a specific asset ticker.",
+                    "properties": {
+                        "net_flow_percentage": {
+                            "type": "number",
+                            "description": "Net capital flow (buying/selling) as a percentage of total holdings, adjusted for price changes."
+                        },
+                        "total_invested_today": {
+                            "type": "number",
+                            "description": "Total USD value invested in this asset today by the sample."
+                        },
+                        "total_invested_yesterday": {
+                            "type": "number",
+                            "description": "Total USD value invested in this asset yesterday by the sample."
+                        },
+                        "price_change_contribution": {
+                            "type": "number",
+                            "description": "The portion of the value change attributable to the asset's price movement."
+                        },
+                        "net_flow_contribution": {
+                            "type": "number",
+                            "description": "The portion of the value change attributable to net buying or selling."
+                        }
+                    },
+                    "required": ["net_flow_percentage", "total_invested_today", "total_invested_yesterday"]
+                }
+            },
+            "additionalProperties": {
+                "type": "object",
+                "properties": {
+                    "net_flow_percentage": { "type": "number" },
+                    "total_invested_today": { "type": "number" },
+                    "total_invested_yesterday": { "type": "number" },
+                    "price_change_contribution": { "type": "number" },
+                    "net_flow_contribution": { "type": "number" }
+                }
             }
-        }
-        return valueMap;
+        };
     }
 
-    process(todayPortfolio, yesterdayPortfolio, userId, context) {
-        // This is a historical calculation, requires both days
-        if (!todayPortfolio || !yesterdayPortfolio || !todayPortfolio.AggregatedPositions || !yesterdayPortfolio.AggregatedPositions) {
-            return;
-        }
-
-        // Capture dates from context on the first run
-        if (!this.dates.today && context.todayDateStr && context.yesterdayDateStr) {
-            this.dates.today = context.todayDateStr;
-            this.dates.yesterday = context.yesterdayDateStr;
-        }
-        
-        const yesterdayValues = this._sumAssetValue(yesterdayPortfolio.AggregatedPositions);
-        const todayValues = this._sumAssetValue(todayPortfolio.AggregatedPositions);
-        
-        // Use a set of all unique instruments held across both days
-        const allInstrumentIds = new Set([
-            ...Object.keys(yesterdayValues),
-            ...Object.keys(todayValues)
-        ]);
+    _getPortfolioPositions(portfolio) {
+        return portfolio?.PublicPositions || portfolio?.AggregatedPositions;
+    }
 
-        for (const instrumentId of allInstrumentIds) {
-            this._initAsset(instrumentId);
-            this.asset_values[instrumentId].day1_value_sum += (yesterdayValues[instrumentId] || 0);
-            this.asset_values[instrumentId].day2_value_sum += (todayValues[instrumentId] || 0);
+    _initAsset(instrumentId) {
+        if (!this.assetData.has(instrumentId)) {
+            this.assetData.set(instrumentId, {
+                total_invested_yesterday: 0,
+                total_invested_today: 0,
+                price_change_yesterday: 0, // Used to calculate weighted avg price change
+            });
         }
-
-        this.user_count++;
     }
 
-    async getResult() {
-        if (this.user_count === 0 || !this.dates.today) {
-            console.warn('[AssetCrowdFlow] No users processed or dates missing.');
-            return null; // <--- Returns null if no users
+    process(todayPortfolio, yesterdayPortfolio) {
+        if (!todayPortfolio || !yesterdayPortfolio) {
+            return;
         }
 
-        // Load priceMap and mappings if not loaded
-        if (!this.priceMap || !this.mappings) {
-            try {
-                const [priceData, mappingData] = await Promise.all([
-                    loadAllPriceData(),
-                    loadInstrumentMappings()
-                ]);
-                this.priceMap = priceData;
-                this.mappings = mappingData;
-
-                if (!this.priceMap || Object.keys(this.priceMap).length === 0) {
-                    console.error('[AssetCrowdFlow] CRITICAL: Price map is empty or failed to load. Aborting calculation to allow backfill.');
-                    return null; // Return null to trigger backfill
-                }
+        const yPos = this._getPortfolioPositions(yesterdayPortfolio);
+        const tPos = this._getPortfolioPositions(todayPortfolio);
 
-            } catch (err) {
-                console.error('[AssetCrowdFlow] Failed to load dependencies:', err);
-                return null; // <--- Return null on error
-            }
-        }
+        const yPosMap = new Map(yPos?.map(p => [p.InstrumentID, p]) || []);
+        const tPosMap = new Map(tPos?.map(p => [p.InstrumentID, p]) || []);
 
-        const finalResults = {};
-        const todayStr = this.dates.today;
-        const yesterdayStr = this.dates.yesterday;
+        const allInstrumentIds = new Set([...yPosMap.keys(), ...tPosMap.keys()]);
 
-        for (const rawInstrumentId in this.asset_values) {
-            const instrumentId = String(rawInstrumentId); // normalize
-            const ticker = this.mappings.instrumentToTicker?.[instrumentId] || `id_${instrumentId}`;
+        for (const instrumentId of allInstrumentIds) {
+            if (!instrumentId) continue;
+            
+            this._initAsset(instrumentId);
+            const asset = this.assetData.get(instrumentId);
 
-            const avg_day1_value = this.asset_values[rawInstrumentId].day1_value_sum / this.user_count;
-            const avg_day2_value = this.asset_values[rawInstrumentId].day2_value_sum / this.user_count;
+            const yP = yPosMap.get(instrumentId);
+            const tP = tPosMap.get(instrumentId);
 
-            // --- THIS IS THE FIX YOU APPLIED ---
-            const priceChangePct = getDailyPriceChange(instrumentId, yesterdayStr, todayStr, this.priceMap);
-            // --- END FIX ---
+            const yInvested = yP?.InvestedAmount || yP?.Amount || 0;
+            const tInvested = tP?.InvestedAmount || tP?.Amount || 0;
 
-            if (priceChangePct === null) {
-                // If price is missing, we simply skip this ticker.
-                // It will not be in the final output.
-                continue;
+            if (yInvested > 0) {
+                asset.total_invested_yesterday += yInvested;
+                // Get price change from *yesterday's* portfolio
+                const yPriceChange = (yP?.PipsRate || 0) / (yP?.OpenRate || 1); // PipsRate holds 1-day change
+                asset.price_change_yesterday += yPriceChange * yInvested; // Weighted sum
+            }
+            if (tInvested > 0) {
+                asset.total_invested_today += tInvested;
             }
-
-            // --- THIS IS THE LOGIC THAT IS BROKEN IN YOUR FILE ---
-            // Calculate expected day2 value from price movement
-            const expected_day2_value = avg_day1_value * (1 + priceChangePct);
-
-            // Net crowd flow = actual minus expected
-            const net_crowd_flow_pct = avg_day2_value - expected_day2_value;
-
-            finalResults[ticker] = {
-                net_crowd_flow_pct,
-                avg_value_day1_pct: avg_day1_value, // <-- Note: I've also fixed the key name here
-                avg_value_day2_pct: avg_day2_value, // <-- Note: I've also fixed the key name here
-                expected_day2_value,
-                price_change_pct: priceChangePct,
-                user_sample_size: this.user_count
-            };
-            // --- END BROKEN LOGIC ---
         }
+    }
 
-        if (Object.keys(finalResults).length === 0) {
-            console.warn(`[AssetCrowdFlow] No results generated for ${this.dates.today}. This likely means all price data was missing. Returning null for backfill.`);
-            return null; // <--- Returns null if all tickers failed
+    async getResult() {
+        if (!this.mappings) {
+            this.mappings = await loadInstrumentMappings();
         }
 
-        return finalResults;
+        const result = {};
+
+        for (const [instrumentId, data] of this.assetData.entries()) {
+            const ticker = this.mappings.instrumentToTicker[instrumentId] || `id_${instrumentId}`;
+
+            const { total_invested_yesterday, total_invested_today, price_change_yesterday } = data;
+
+            if (total_invested_yesterday > 0) {
+                // Calculate the weighted average price change %
+                const avg_price_change_pct = price_change_yesterday / total_invested_yesterday;
+                
+                // Estimate the value change *due to price*
+                const price_contribution = total_invested_yesterday * avg_price_change_pct;
+                
+                // Estimate the value change *due to net flow* (buy/sell)
+                const flow_contribution = total_invested_today - (total_invested_yesterday + price_contribution);
+
+                // Calculate Net Flow as a percentage of yesterday's holdings
+                const net_flow_percentage = (flow_contribution / total_invested_yesterday) * 100;
+
+                result[ticker] = {
+                    net_flow_percentage: net_flow_percentage,
+                    total_invested_today: total_invested_today,
+                    total_invested_yesterday: total_invested_yesterday,
+                    price_change_contribution: price_contribution,
+                    net_flow_contribution: flow_contribution
+                };
+            }
+        }
+        return result;
     }
 
-
     reset() {
-        this.asset_values = {};
-        this.user_count = 0;
-        this.priceMap = null;
+        this.assetData.clear();
         this.mappings = null;
-        this.dates = {};
     }
 }