aiden-shared-calculations-unified 1.0.64 → 1.0.65

package/calculations/behavioural/historical/gain_response.js

@@ -1,57 +1,136 @@
 /**
- * Analyzes user behavior after a position experiences a >10% gain.
+ * @fileoverview Calculation (Pass 2) for gain response.
+ *
+ * This metric answers: "How do users behave when a position has a
+ * gain of over 10%?"
+ *
+ * It checks all positions from yesterday that were in >10% profit
+ * and tracks whether the user:
+ * 1. Held (position still open today, same size)
+ * 2. Closed (position no longer open today)
+ * 3. Reduced (position still open, but Invested % is smaller)
  */
 class GainResponse {
     constructor() {
-        this.gain_events = {
-            held_position: 0,
-            closed_position: 0,
-            reduced_position: 0 // e.g., took partial profit
+        this.actions = {
+            held: 0,
+            closed: 0,
+            reduced: 0
         };
+        this.total_in_gain = 0;
     }
 
-    process(todayPortfolio, yesterdayPortfolio, userId) {
-        if (!yesterdayPortfolio || !todayPortfolio) {
-            return; // Need both days for comparison
+    /**
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
+     */
+    static getSchema() {
+        return {
+            "type": "object",
+            "description": "Analyzes user behavior in response to a >10% position gain.",
+            "properties": {
+                "total_positions_in_gain": {
+                    "type": "number",
+                    "description": "Total positions from yesterday that were in >10% gain."
+                },
+                "action_held_pct": {
+                    "type": "number",
+                    "description": "Percentage of gain positions that were held."
+                },
+                "action_closed_pct": {
+                    "type": "number",
+                    "description": "Percentage of gain positions that were closed (profit-taking)."
+                },
+                "action_reduced_pct": {
+                    "type": "number",
+                    "description": "Percentage of gain positions that were reduced (scaling out)."
+                },
+                "raw_counts": {
+                    "type": "object",
+                    "properties": {
+                        "held": { "type": "number" },
+                        "closed": { "type": "number" },
+                        "reduced": { "type": "number" }
+                    },
+                    "required": ["held", "closed", "reduced"]
+                }
+            },
+            "required": ["total_positions_in_gain", "action_held_pct", "action_closed_pct", "action_reduced_pct", "raw_counts"]
+        };
+    }
+
+    _getPortfolioMap(portfolio) {
+        // We MUST use PositionID to track specific trades
+        const positions = portfolio?.AggregatedPositions || portfolio?.PublicPositions;
+        if (!positions || !Array.isArray(positions)) {
+            return new Map();
+        }
+        // Map<PositionID, { pnl: number, invested: number }>
+        return new Map(positions.map(p => [p.PositionID, {
+            pnl: (p.NetProfit || 0) / (p.InvestedAmount || p.Amount || 1), // PNL as %
+            invested: p.InvestedAmount || p.Amount || 0
+        }]));
+    }
+
+    process(todayPortfolio, yesterdayPortfolio) {
+        if (!todayPortfolio || !yesterdayPortfolio) {
+            return;
         }
 
-        const yPositions = yesterdayPortfolio.AggregatedPositions || yesterdayPortfolio.PublicPositions;
-        const tPositions = todayPortfolio.AggregatedPositions || todayPortfolio.PublicPositions;
+        const yPosMap = this._getPortfolioMap(yesterdayPortfolio);
+        const tPosMap = this._getPortfolioMap(todayPortfolio);
 
-        if (!yPositions || !Array.isArray(yPositions) || !tPositions || !Array.isArray(tPositions)) {
+        if (yPosMap.size === 0) {
             return;
         }
 
-        // Use PositionID if available (as in original file), fallback to InstrumentID
-        const todayPositions = new Map(tPositions.map(p => [p.PositionID || p.InstrumentID, p]));
-
-        for (const yPos of yPositions) {
-            // FIX: Use the NetProfit field, which is already a percentage.
-            // Your data sample (e.g., 23.5) shows the threshold should be 10.0.
-            const gainPercent = yPos.NetProfit || 0;
-            const yPosId = yPos.PositionID || yPos.InstrumentID;
-
-            // Check if this position was in a >10% gain yesterday
-            if (gainPercent > 10.0) {
-                const todayPos = todayPositions.get(yPosId);
-
-                if (!todayPos) {
-                    // Position was closed (took full profit)
-                    this.gain_events.closed_position++;
-                } else if (todayPos.Invested < yPos.Invested) {
-                    // FIX: Use 'Invested' (percentage) to check for reduction
-                    // User reduced the position (took partial profit)
-                    this.gain_events.reduced_position++;
+        for (const [yPosId, yPosData] of yPosMap.entries()) {
+            // Check if position was in >10% gain
+            if (yPosData.pnl > 0.10) {
+                this.total_in_gain++;
+
+                // Now, check what happened today
+                if (!tPosMap.has(yPosId)) {
+                    // 1. Position was closed (Profit Taking)
+                    this.actions.closed++;
                 } else {
-                    // Position was held (or added to)
-                    this.gain_events.held_position++;
+                    const tPosData = tPosMap.get(yPosId);
+                    // 2. Position was reduced (check for > 1% reduction to avoid noise)
+                    if (tPosData.invested < (yPosData.invested * 0.99)) {
+                        this.actions.reduced++;
+                    } else {
+                        // 3. Position was held
+                        this.actions.held++;
+                    }
                 }
             }
         }
     }
 
     getResult() {
-        return this.gain_events;
+        const total = this.total_in_gain;
+        if (total === 0) {
+            return {
+                total_positions_in_gain: 0,
+                action_held_pct: 0,
+                action_closed_pct: 0,
+                action_reduced_pct: 0,
+                raw_counts: this.actions
+            };
+        }
+
+        return {
+            total_positions_in_gain: total,
+            action_held_pct: (this.actions.held / total) * 100,
+            action_closed_pct: (this.actions.closed / total) * 100,
+            action_reduced_pct: (this.actions.reduced / total) * 100,
+            raw_counts: this.actions
+        };
+    }
+
+    reset() {
+        this.actions = { held: 0, closed: 0, reduced: 0 };
+        this.total_in_gain = 0;
     }
 }
 

package/calculations/behavioural/historical/historical_performance_aggregator.js

@@ -1,69 +1,84 @@
 /**
- * @fileoverview Pass 1: Aggregates each user's historical performance
- * from the root history data feed.
+ * @fileoverview Calculation (Pass 2) for aggregating user performance.
+ *
+ * This class processes each user's daily P&L and aggregates it into
+ * buckets for statistical analysis. It collects all individual P&Ls
+ * to build a distribution.
+ *
+ * This is a foundational calculation needed by many Pass 3 metrics.
  */
 class HistoricalPerformanceAggregator {
     constructor() {
-        this.allUserStats = {};
+        // Stores the 7-day weighted P&L for every user.
+        this.userPnlHistory = [];
     }
 
     /**
-     * @param {object} todayPortfolio - Not used, but part of signature.
-     * @param {object} yesterdayPortfolio - Not used.
-     * @param {string} userId - The user's ID.
-     * @param {object} context - Shared context data.
-     * @param {null} todayInsights - Not used.
-     * @param {null} yesterdayInsights - Not used.
-     * @param {null} todaySocialPostInsights - Not used.
-     * @param {null} yesterdaySocialPostInsights - Not used.
-     * @param {object} todayHistoryData - The full map of { [userId]: history }
-     * @param {null} yesterdayHistoryData - Not used.
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
      */
-    async process(
-        todayPortfolio, yesterdayPortfolio, userId, context, 
-        todayInsights, yesterdayInsights, 
-        todaySocialPostInsights, yesterdaySocialPostInsights,
-        todayHistoryData, yesterdayHistoryData
-    ) {
-        // This calc only runs if the history data was successfully loaded
-        if (!todayHistoryData || !userId) {
-            return;
-        }
+    static getSchema() {
+        return {
+            "type": "object",
+            "description": "Aggregates historical P&L from 'user_profitability_tracker' for all users to build a performance distribution.",
+            "properties": {
+                "user_pnl_distribution": {
+                    "type": "array",
+                    "description": "An array of 7-day weighted average P&L values, one for each user.",
+                    "items": { "type": "number" }
+                },
+                "user_count": {
+                    "type": "number",
+                    "description": "Total number of users processed."
+                }
+            },
+            "required": ["user_pnl_distribution", "user_count"]
+        };
+    }
 
-        const userHistory = todayHistoryData[userId];
+    /**
+     * Statically declare dependencies.
+     */
+    static getDependencies() {
+        return ['user_profitability_tracker'];
+    }
 
-        // 'all' is the object where instrumentId === -1
-        if (!userHistory || !userHistory.all) {
-            return;
-        }
+    /**
+     * process() is a no-op. All logic is in getResult().
+     * This calculation doesn't process portfolios; it processes
+     * the *result* of another calculation.
+     */
+    process() {
+        // No-op
+    }
 
-        const stats = userHistory.all;
+    /**
+     * Aggregates results from the dependency.
+     */
+    getResult(fetchedDependencies) {
+        const profitabilityData = fetchedDependencies['user_profitability_tracker'];
         
-        // Ignore users who are only mirroring
-        if (stats.isMirror === true) {
-            return;
-        }
-
-        // We only care about users with a meaningful trade history
-        if (!stats.totalTrades || stats.totalTrades < 10) {
-            return;
+        if (!profitabilityData || !profitabilityData.user_details) {
+            return {
+                user_pnl_distribution: [],
+                user_count: 0
+            };
         }
+        
+        // Extract the 7-day weighted P&L for all users
+        const pnlDistribution = Object.values(profitabilityData.user_details)
+            .map(details => details.weighted_avg_pnl_7d)
+            // Filter out any null/undefined/NaN values
+            .filter(pnl => typeof pnl === 'number' && !isNaN(pnl));
 
-        this.allUserStats[userId] = {
-            winRatio: stats.winRatio,
-            avgProfitPct: stats.avgProfitPct,
-            avgLossPct: stats.avgLossPct,
-            totalTrades: stats.totalTrades,
-            avgHoldingTime: stats.avgHoldingTimeInMinutes
+        return {
+            user_pnl_distribution: pnlDistribution,
+            user_count: pnlDistribution.length
         };
     }
 
-    async getResult() {
-        return this.allUserStats;
-    }
-
     reset() {
-        this.allUserStats = {};
+        this.userPnlHistory = [];
     }
 }
 

package/calculations/behavioural/historical/in_loss_asset_crowd_flow.js

@@ -1,99 +1,195 @@
-const { loadAllPriceData, getDailyPriceChange } = require('../../../utils/price_data_provider');
-const { loadInstrumentMappings } = require('../../../utils/sector_mapping_provider');
-
 /**
- * @fileoverview Calculates "Net Crowd Flow" for each asset, BUT
- * *only* for the cohort of users who are currently IN LOSS
- * on their positions for that asset.
+ * @fileoverview Calculation (Pass 3) for "In Loss" cohort asset flow.
+ *
+ * This metric calculates the "Net Crowd Flow Percentage" for each asset,
+ * but *only* for the cohort of users who are currently *at a loss*
+ * on that specific asset.
+ *
+ * This helps identify if losers are capitulating or doubling down.
+ *
+ * This calculation *depends* on 'asset_pnl_status' to identify the cohort.
  */
+const { loadInstrumentMappings } = require('../../../utils/sector_mapping_provider');
+
 class InLossAssetCrowdFlow {
     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 = {};
+        this.inLossCohorts = null; // Map<ticker, Set<userId>>
+    }
+
+    /**
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
+     */
+    static getSchema() {
+        return {
+            "type": "object",
+            "description": "Calculates net capital flow % (price-adjusted) per asset, but only for the cohort of users currently in loss on that asset.",
+            "patternProperties": {
+                // Ticker
+                "^.*$": {
+                    "type": "object",
+                    "description": "Net flow metrics for a specific asset ticker from its 'in loss' cohort.",
+                    "properties": {
+                        "net_flow_percentage": {
+                            "type": "number",
+                            "description": "Net capital flow % from the 'in loss' cohort, adjusted for price changes."
+                        },
+                        "total_invested_today": { "type": "number" },
+                        "total_invested_yesterday": { "type": "number" },
+                        "cohort_size": { "type": "number" }
+                    },
+                    "required": ["net_flow_percentage", "total_invested_today", "total_invested_yesterday", "cohort_size"]
+                }
+            },
+            "additionalProperties": {
+                "type": "object",
+                "properties": {
+                    "net_flow_percentage": { "type": "number" },
+                    "total_invested_today": { "type": "number" },
+                    "total_invested_yesterday": { "type": "number" },
+                    "cohort_size": { "type": "number" }
+                }
+            }
+        };
+    }
+
+    /**
+     * Statically declare dependencies.
+     */
+    static getDependencies() {
+        return ['asset_pnl_status'];
+    }
+
+    _getPortfolioPositions(portfolio) {
+        return portfolio?.PublicPositions || portfolio?.AggregatedPositions;
     }
 
     _initAsset(instrumentId) {
-        if (!this.asset_values[instrumentId]) {
-            this.asset_values[instrumentId] = { day1_value_sum: 0, day2_value_sum: 0 };
+        if (!this.assetData.has(instrumentId)) {
+            this.assetData.set(instrumentId, {
+                total_invested_yesterday: 0,
+                total_invested_today: 0,
+                price_change_yesterday: 0,
+                cohort: new Set()
+            });
         }
     }
 
-    process(todayPortfolio, yesterdayPortfolio, userId, context) {
-        if (!todayPortfolio || !yesterdayPortfolio || !todayPortfolio.AggregatedPositions || !yesterdayPortfolio.AggregatedPositions) {
-            return;
+    /**
+     * Helper to get the cohort data from the dependency.
+     */
+    _getInLossCohorts(fetchedDependencies) {
+        if (this.inLossCohorts) {
+            return this.inLossCohorts;
+        }
+        
+        const pnlStatusData = fetchedDependencies['asset_pnl_status'];
+        if (!pnlStatusData) {
+            return new Map();
+        }
+
+        // Re-structure the data for efficient lookup
+        // Map<ticker, Set<userId>>
+        this.inLossCohorts = new Map();
+        for (const [ticker, data] of Object.entries(pnlStatusData)) {
+            const userSet = new Set(data.users_in_loss.map(u => u.userId));
+            this.inLossCohorts.set(ticker, userSet);
         }
+        return this.inLossCohorts;
+    }
 
-        if (!this.dates.today && context.todayDateStr && context.yesterdayDateStr) {
-            this.dates.today = context.todayDateStr;
-            this.dates.yesterday = context.yesterdayDateStr;
+    process(todayPortfolio, yesterdayPortfolio, userId, context, todayInsights, yesterdayInsights, fetchedDependencies) {
+        if (!todayPortfolio || !yesterdayPortfolio) {
+            return;
         }
 
-        const yesterdayPositions = new Map(yesterdayPortfolio.AggregatedPositions.map(p => [p.InstrumentID, p]));
-        const todayPositions = new Map(todayPortfolio.AggregatedPositions.map(p => [p.InstrumentID, p]));
+        if (!this.mappings) {
+            // Context contains the mappings loaded in Pass 1
+            this.mappings = context.mappings;
+        }
         
-        const allInstrumentIds = new Set([
-            ...yesterdayPositions.keys(),
-            ...todayPositions.keys()
-        ]);
+        const cohorts = this._getInLossCohorts(fetchedDependencies);
+        if (cohorts.size === 0) {
+            return; // No dependency data
+        }
+
+        const yPos = this._getPortfolioPositions(yesterdayPortfolio);
+        const tPos = this._getPortfolioPositions(todayPortfolio);
+
+        const yPosMap = new Map(yPos?.map(p => [p.InstrumentID, p]) || []);
+        const tPosMap = new Map(tPos?.map(p => [p.InstrumentID, p]) || []);
+
+        const allInstrumentIds = new Set([...yPosMap.keys(), ...tPosMap.keys()]);
 
         for (const instrumentId of allInstrumentIds) {
-            const yPos = yesterdayPositions.get(instrumentId);
-            const tPos = todayPositions.get(instrumentId);
+            if (!instrumentId) continue;
             
-            // --- COHORT LOGIC ---
-            // Only aggregate if the user is in LOSS on this asset.
-            const tNetProfit = tPos?.NetProfit || 0;
-            if (tNetProfit >= 0) { // Note: >= 0 (includes zero profit)
-                continue; // Skip this asset for this user
-            }
-            // --- END COHORT LOGIC ---
+            const ticker = this.mappings.instrumentToTicker[instrumentId] || `id_${instrumentId}`;
+            const cohort = cohorts.get(ticker);
 
+            // This user is not in the "in loss" cohort for this asset, skip.
+            if (!cohort || !cohort.has(userId)) {
+                continue;
+            }
+            
+            // User *is* in the cohort, process their data
             this._initAsset(instrumentId);
-            this.asset_values[instrumentId].day1_value_sum += (yPos?.Value || 0);
-            this.asset_values[instrumentId].day2_value_sum += (tPos?.Value || 0);
+            const asset = this.assetData.get(instrumentId);
+            asset.cohort.add(userId); // Track cohort size
+
+            const yP = yPosMap.get(instrumentId);
+            const tP = tPosMap.get(instrumentId);
+
+            const yInvested = yP?.InvestedAmount || yP?.Amount || 0;
+            const tInvested = tP?.InvestedAmount || tP?.Amount || 0;
+
+            if (yInvested > 0) {
+                asset.total_invested_yesterday += yInvested;
+                const yPriceChange = (yP?.PipsRate || 0) / (yP?.OpenRate || 1);
+                asset.price_change_yesterday += yPriceChange * yInvested;
+            }
+            if (tInvested > 0) {
+                asset.total_invested_today += tInvested;
+            }
         }
-        this.user_count++;
     }
 
     async getResult() {
-        if (this.user_count === 0 || !this.dates.today) return {};
-        if (!this.priceMap || !this.mappings) {
-            const [priceData, mappingData] = await Promise.all([
-                loadAllPriceData(),
-                loadInstrumentMappings()
-            ]);
-            this.priceMap = priceData;
-            this.mappings = mappingData;
+        if (!this.mappings) {
+            this.mappings = await loadInstrumentMappings();
         }
-        
-        const finalResults = {};
-        const todayStr = this.dates.today;
-        const yesterdayStr = this.dates.yesterday;
 
-        for (const instrumentId in this.asset_values) {
+        const result = {};
+
+        for (const [instrumentId, data] of this.assetData.entries()) {
             const ticker = this.mappings.instrumentToTicker[instrumentId] || `id_${instrumentId}`;
-            
-            const avg_day1_value = this.asset_values[instrumentId].day1_value_sum / this.user_count;
-            const avg_day2_value = this.asset_values[instrumentId].day2_value_sum / this.user_count;
-            const priceChangePct = getDailyPriceChange(instrumentId, yesterdayStr, todayStr, this.priceMap);
 
-            if (priceChangePct === null) continue;
+            const { total_invested_yesterday, total_invested_today, price_change_yesterday, cohort } = data;
 
-            const expected_day2_value = avg_day1_value * (1 + priceChangePct);
-            const net_crowd_flow_pct = avg_day2_value - expected_day2_value;
+            if (total_invested_yesterday > 0) {
+                const avg_price_change_pct = price_change_yesterday / total_invested_yesterday;
+                const price_contribution = total_invested_yesterday * avg_price_change_pct;
+                const flow_contribution = total_invested_today - (total_invested_yesterday + price_contribution);
+                const net_flow_percentage = (flow_contribution / total_invested_yesterday) * 100;
 
-            finalResults[ticker] = {
-                net_crowd_flow_pct: net_crowd_flow_pct,
-                avg_value_day1_pct: avg_day1_value,
-                avg_value_day2_pct: avg_day2_value
-            };
+                result[ticker] = {
+                    net_flow_percentage: net_flow_percentage,
+                    total_invested_today: total_invested_today,
+                    total_invested_yesterday: total_invested_yesterday,
+                    cohort_size: cohort.size
+                };
+            }
         }
-        return finalResults;
+        return result;
     }
 
-    reset() { /*...reset all properties...*/ }
+    reset() {
+        this.assetData.clear();
+        this.mappings = null;
+        this.inLossCohorts = null;
+    }
 }
+
 module.exports = InLossAssetCrowdFlow;