aiden-shared-calculations-unified 1.0.64 → 1.0.65

package/calculations/capital_flow/historical/deposit_withdrawal_percentage.js

@@ -1,118 +1,125 @@
 /**
- * @fileoverview Estimates a proxy for net crowd cash flow (Deposits vs. Withdrawals)
- * by aggregating portfolio percentage changes across all users.
+ * @fileoverview Calculation (Pass 2) for deposit/withdrawal percentage.
  *
- * This calculation is based on the formula:
- * Total_Change = P/L_Effect + Trading_Effect + Cash_Flow_Effect
+ * This metric estimates the net cash flow (deposits vs. withdrawals)
+ * by analyzing changes in portfolio percentages.
  *
- * Where:
- * - Total_Change = avg_value_day2 - avg_value_day1
- * - P/L_Effect = avg_value_day1 - avg_invested_day1
- * - Trading_Effect = avg_invested_day2 - avg_invested_day1
+ * It's a proxy based on the assumption that changes in the *sum* of
+ * position percentages not accounted for by P&L represent new cash.
  *
- * We solve for Cash_Flow_Effect, which serves as our proxy.
- * A negative value indicates a net DEPOSIT (denominator grew, shrinking all %s).
- * A positive value indicates a net WITHDRAWAL (denominator shrank, inflating all %s).
+ * (DEPRECIATED by crowd-cash-flow-proxy, but kept for reference)
  */
-
-class CrowdCashFlowProxy {
+class DepositWithdrawalPercentage {
     constructor() {
-        this.total_invested_day1 = 0;
-        this.total_value_day1 = 0;
-        this.total_invested_day2 = 0;
-        this.total_value_day2 = 0;
+        this.invested_pct_yesterday_sum = 0;
+        this.invested_pct_today_sum = 0;
+        this.pnl_pct_today_sum = 0;
         this.user_count = 0;
     }
 
     /**
-     * Helper to sum a specific field from an AggregatedPositions array.
-     * @param {Array<object>} positions - The AggregatedPositions array.
-     * @param {string} field - The field to sum ('Invested' or 'Value').
-     * @returns {number} The total sum of that field.
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
      */
-    _sumPositions(positions, field) {
+    static getSchema() {
+        return {
+            "type": "object",
+            "description": "(DEPRECIATED) Estimates net cash flow by analyzing changes in portfolio position percentages.",
+            "properties": {
+                "estimated_net_flow_pct": {
+                    "type": "number",
+                    "description": "The estimated net cash flow (deposit/withdrawal) as an average percentage change across all users."
+                },
+                "user_count": {
+                    "type": "number",
+                    "description": "Number of users processed."
+                },
+                "debug": {
+                    "type": "object",
+                    "properties": {
+                        "invested_pct_yesterday_sum": { "type": "number" },
+                        "invested_pct_today_sum": { "type": "number" },
+                        "pnl_pct_today_sum": { "type": "number" }
+                    }
+                }
+            },
+            "required": ["estimated_net_flow_pct", "user_count"]
+        };
+    }
+
+    _getPortfolioSums(portfolio) {
+        const positions = portfolio?.AggregatedPositions;
         if (!positions || !Array.isArray(positions)) {
-            return 0;
+            return { investedPct: 0, pnlPct: 0 };
+        }
+        
+        let investedPct = 0;
+        let pnlPct = 0;
+        
+        for (const pos of positions) {
+            investedPct += pos.InvestedAmount || pos.Invested || 0;
+            pnlPct += (pos.NetProfit || 0) / 100; // Assuming NetProfit is in %
         }
-        return positions.reduce((sum, pos) => sum + (pos[field] || 0), 0);
+        
+        return { investedPct, pnlPct };
     }
 
-    process(todayPortfolio, yesterdayPortfolio, userId) {
-        // This calculation requires both days' data to compare
-        if (!todayPortfolio || !yesterdayPortfolio || !todayPortfolio.AggregatedPositions || !yesterdayPortfolio.AggregatedPositions) {
+    process(todayPortfolio, yesterdayPortfolio) {
+        if (!todayPortfolio || !yesterdayPortfolio) {
             return;
         }
 
-        const invested_day1 = this._sumPositions(yesterdayPortfolio.AggregatedPositions, 'Invested');
-        const value_day1 = this._sumPositions(yesterdayPortfolio.AggregatedPositions, 'Value');
-        const invested_day2 = this._sumPositions(todayPortfolio.AggregatedPositions, 'Invested');
-        const value_day2 = this._sumPositions(todayPortfolio.AggregatedPositions, 'Value');
-
-        // Only include users who have some form of positions
-        if (invested_day1 === 0 && invested_day2 === 0 && value_day1 === 0 && value_day2 === 0) {
-            return;
+        const ySums = this._getPortfolioSums(yesterdayPortfolio);
+        const tSums = this._getPortfolioSums(todayPortfolio);
+        
+        if (ySums.investedPct === 0 && tSums.investedPct === 0) {
+            return; // Skip users with no positions
         }
 
-        this.total_invested_day1 += invested_day1;
-        this.total_value_day1 += value_day1;
-        this.total_invested_day2 += invested_day2;
-        this.total_value_day2 += value_day2;
+        this.invested_pct_yesterday_sum += ySums.investedPct;
+        this.invested_pct_today_sum += tSums.investedPct;
+        this.pnl_pct_today_sum += tSums.pnlPct; // Use today's P&L
         this.user_count++;
     }
 
     getResult() {
         if (this.user_count === 0) {
-            return {}; // No users processed, return empty.
+            return { 
+                estimated_net_flow_pct: 0, 
+                user_count: 0,
+                debug: {
+                    invested_pct_yesterday_sum: 0,
+                    invested_pct_today_sum: 0,
+                    pnl_pct_today_sum: 0
+                }
+            };
         }
+        
+        // Avg % change in invested capital
+        const avg_invested_change = (this.invested_pct_today_sum - this.invested_pct_yesterday_sum) / this.user_count;
+        // Avg P&L
+        const avg_pnl = this.pnl_pct_today_sum / this.user_count;
 
-        // 1. Calculate the average portfolio for the crowd
-        const avg_invested_day1 = this.total_invested_day1 / this.user_count;
-        const avg_value_day1 = this.total_value_day1 / this.user_count;
-        const avg_invested_day2 = this.total_invested_day2 / this.user_count;
-        const avg_value_day2 = this.total_value_day2 / this.user_count;
-
-        // 2. Isolate the three effects
-        const total_value_change = avg_value_day2 - avg_value_day1;
-        const pl_effect = avg_value_day1 - avg_invested_day1;
-        const trading_effect = avg_invested_day2 - avg_invested_day1;
-
-        // 3. Solve for the Cash Flow Effect
-        // Total_Change = pl_effect + trading_effect + cash_flow_effect
-        const cash_flow_effect = total_value_change - pl_effect - trading_effect;
+        // The change not accounted for by P&L is the proxy flow
+        const net_flow_pct = avg_invested_change - avg_pnl;
 
         return {
-            // The final proxy value.
-            // A negative value signals a net DEPOSIT.
-            // A positive value signals a net WITHDRAWAL.
-            cash_flow_effect_proxy: cash_flow_effect,
-            
-            // Interpretation for the frontend
-            interpretation: "A negative value signals a net crowd deposit. A positive value signals a net crowd withdrawal.",
-            
-            // Debug components
-            components: {
-                total_value_change: total_value_change,
-                pl_effect: pl_effect,
-                trading_effect: trading_effect
-            },
-            // Debug averages
-            averages: {
-                avg_invested_day1: avg_invested_day1,
-                avg_value_day1: avg_value_day1,
-                avg_invested_day2: avg_invested_day2,
-                avg_value_day2: avg_value_day2
-            },
-            user_sample_size: this.user_count
+            estimated_net_flow_pct: net_flow_pct,
+            user_count: this.user_count,
+            debug: {
+                invested_pct_yesterday_sum: this.invested_pct_yesterday_sum,
+                invested_pct_today_sum: this.invested_pct_today_sum,
+                pnl_pct_today_sum: this.pnl_pct_today_sum
+            }
         };
     }
 
     reset() {
-        this.total_invested_day1 = 0;
-        this.total_value_day1 = 0;
-        this.total_invested_day2 = 0;
-        this.total_value_day2 = 0;
+        this.invested_pct_yesterday_sum = 0;
+        this.invested_pct_today_sum = 0;
+        this.pnl_pct_today_sum = 0;
         this.user_count = 0;
     }
 }
 
-module.exports = CrowdCashFlowProxy;
+module.exports = DepositWithdrawalPercentage;

package/calculations/capital_flow/historical/new_allocation_percentage.js

@@ -1,49 +1,98 @@
 /**
- * @fileoverview Calculates the average percentage of total portfolio value
- * newly allocated to assets not held on the previous day.
+ * @fileoverview Calculation (Pass 2) for new allocation percentage.
+ *
+ * This metric answers: "On average, what percentage of a user's
+ * portfolio was allocated to *new* positions today?"
+ *
+ * This measures the flow of capital into new ideas vs. existing ones.
  */
-
 class NewAllocationPercentage {
     constructor() {
-        this.accumulatedNewAllocationPercentage = 0;
-        this.userCount = 0;
+        this.total_new_allocation_pct = 0;
+        this.users_with_new_positions = 0;
+    }
+
+    /**
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
+     */
+    static getSchema() {
+        return {
+            "type": "object",
+            "description": "Calculates the average portfolio percentage allocated to *new* positions today.",
+            "properties": {
+                "average_new_allocation_pct": {
+                    "type": "number",
+                    "description": "The average percentage of a portfolio allocated to new positions, for users who opened new positions."
+                },
+                "total_new_allocation_pct_sum": {
+                    "type": "number",
+                    "description": "The sum of all new allocation percentages."
+                },
+                "user_count_with_new_positions": {
+                    "type": "number",
+                    "description": "The count of users who opened at least one new position."
+                }
+            },
+            "required": ["average_new_allocation_pct", "total_new_allocation_pct_sum", "user_count_with_new_positions"]
+        };
+    }
+
+    _getPortfolioPositionMap(portfolio) {
+        // We MUST use AggregatedPositions for the 'Invested' %
+        const positions = portfolio?.AggregatedPositions;
+        if (!positions || !Array.isArray(positions)) {
+            return new Map();
+        }
+        // Map<InstrumentID, { invested: number }>
+        return new Map(positions.map(p => [p.InstrumentID, {
+            invested: p.InvestedAmount || p.Invested || 0
+        }]));
     }
 
-    process(todayPortfolio, yesterdayPortfolio, userId) {
-        const todayPositions = todayPortfolio?.AggregatedPositions;
-        const yesterdayPositions = yesterdayPortfolio?.AggregatedPositions || [];
+    process(todayPortfolio, yesterdayPortfolio) {
+        if (!todayPortfolio || !yesterdayPortfolio) {
+            return;
+        }
+
+        const yPosMap = this._getPortfolioPositionMap(yesterdayPortfolio);
+        const tPosMap = this._getPortfolioPositionMap(todayPortfolio);
 
-        if (!todayPositions || todayPositions.length === 0) return;
+        if (tPosMap.size === 0) {
+            return; // No positions today
+        }
 
-        const yesterdayIds = new Set(yesterdayPositions.map(p => p.InstrumentID));
-        let userNewAllocation = 0;
+        let userNewAllocationPct = 0;
 
-        for (const pos of todayPositions) {
-            if (!yesterdayIds.has(pos.InstrumentID)) {
-                const invested = typeof pos.Invested === 'number' ? pos.Invested : 0;
-                userNewAllocation += invested;
+        for (const [tId, tPosData] of tPosMap.entries()) {
+            // Check if this position is new (in today but not yesterday)
+            if (!yPosMap.has(tId)) {
+                userNewAllocationPct += tPosData.invested;
             }
         }
 
-        // Guard against data rounding or eToro API drift
-        if (userNewAllocation > 100) userNewAllocation = 100;
-
-        this.accumulatedNewAllocationPercentage += userNewAllocation;
-        this.userCount++;
+        if (userNewAllocationPct > 0) {
+            this.total_new_allocation_pct += userNewAllocationPct;
+            this.users_with_new_positions++;
+        }
     }
 
     getResult() {
-        if (this.userCount === 0) return {};
+        const avg_pct = (this.users_with_new_positions > 0)
+            ? (this.total_new_allocation_pct / this.users_with_new_positions)
+            : 0;
+
         return {
-            average_new_allocation_percentage:
-                this.accumulatedNewAllocationPercentage / this.userCount
+            average_new_allocation_pct: avg_pct,
+            total_new_allocation_pct_sum: this.total_new_allocation_pct,
+            user_count_with_new_positions: this.users_with_new_positions
         };
     }
 
     reset() {
-        this.accumulatedNewAllocationPercentage = 0;
-        this.userCount = 0;
+        this.total_new_allocation_pct = 0;
+        this.users_with_new_positions = 0;
     }
 }
 
-module.exports = NewAllocationPercentage;
+module.exports = NewAllocationPercentage;

package/calculations/capital_flow/historical/reallocation_increase_percentage.js

@@ -1,62 +1,103 @@
 /**
- * @fileoverview Calculates the average percentage increase in allocation
- * specifically towards assets already held on the previous day.
+ * @fileoverview Calculation (Pass 2) for reallocation increase percentage.
+ *
+ * This metric answers: "On average, what was the total percentage
+ * increase in allocation to *existing* positions today?"
+ *
+ * This measures "doubling down" or adding to winners/losers.
  */
-
 class ReallocationIncreasePercentage {
     constructor() {
-        this.accumulatedIncreasePercentage = 0;
-        this.userCount = 0;
+        this.total_reallocation_increase_pct = 0;
+        this.users_with_reallocations = 0;
+    }
+
+    /**
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
+     */
+    static getSchema() {
+        return {
+            "type": "object",
+            "description": "Calculates the average portfolio percentage *added* to *existing* positions today.",
+            "properties": {
+                "average_reallocation_increase_pct": {
+                    "type": "number",
+                    "description": "The average percentage of a portfolio added to existing positions, for users who reallocated."
+                },
+                "total_reallocation_increase_pct_sum": {
+                    "type": "number",
+                    "description": "The sum of all reallocation increase percentages."
+                },
+                "user_count_with_reallocations": {
+                    "type": "number",
+                    "description": "The count of users who added to at least one existing position."
+                }
+            },
+            "required": ["average_reallocation_increase_pct", "total_reallocation_increase_pct_sum", "user_count_with_reallocations"]
+        };
     }
 
-    process(todayPortfolio, yesterdayPortfolio, userId) {
-        if (!todayPortfolio || !yesterdayPortfolio || !todayPortfolio.AggregatedPositions || !yesterdayPortfolio.AggregatedPositions) {
-            // Requires AggregatedPositions which contain the 'Invested' percentage
+    _getPortfolioPositionMap(portfolio) {
+        // We MUST use AggregatedPositions for the 'Invested' %
+        const positions = portfolio?.AggregatedPositions;
+        if (!positions || !Array.isArray(positions)) {
+            return new Map();
+        }
+        // Map<InstrumentID, { invested: number }>
+        return new Map(positions.map(p => [p.InstrumentID, {
+            invested: p.InvestedAmount || p.Invested || 0
+        }]));
+    }
+
+    process(todayPortfolio, yesterdayPortfolio) {
+        if (!todayPortfolio || !yesterdayPortfolio) {
             return;
         }
 
-        const yesterdayPositions = new Map(yesterdayPortfolio.AggregatedPositions.map(p => [p.InstrumentID, p]));
-        let userTotalIncreasePercentage = 0;
+        const yPosMap = this._getPortfolioPositionMap(yesterdayPortfolio);
+        const tPosMap = this._getPortfolioPositionMap(todayPortfolio);
 
-        for (const todayPos of todayPortfolio.AggregatedPositions) {
-            const yesterdayPos = yesterdayPositions.get(todayPos.InstrumentID);
+        if (tPosMap.size === 0 || yPosMap.size === 0) {
+            return; // No positions to compare
+        }
 
-            // Check if the asset was held yesterday
-            if (yesterdayPos) {
-                // Ensure 'Invested' property exists and is a number
-                const todayInvested = typeof todayPos.Invested === 'number' ? todayPos.Invested : 0;
-                const yesterdayInvested = typeof yesterdayPos.Invested === 'number' ? yesterdayPos.Invested : 0;
+        let userReallocationIncrease = 0;
 
-                const deltaInvested = todayInvested - yesterdayInvested;
+        for (const [tId, tPosData] of tPosMap.entries()) {
+            // Check if this position also existed yesterday
+            if (yPosMap.has(tId)) {
+                const yPosData = yPosMap.get(tId);
+                const increase = tPosData.invested - yPosData.invested;
 
-                // Accumulate only the increases
-                if (deltaInvested > 0) {
-                    userTotalIncreasePercentage += deltaInvested;
+                // We only care about *increases*
+                if (increase > 0) {
+                    userReallocationIncrease += increase;
                 }
             }
         }
 
-        // Only count users who had positions on both days for this metric
-        if (yesterdayPortfolio.AggregatedPositions.length > 0 && todayPortfolio.AggregatedPositions.length > 0) {
-           this.accumulatedIncreasePercentage += userTotalIncreasePercentage;
-           this.userCount++;
+        if (userReallocationIncrease > 0) {
+            this.total_reallocation_increase_pct += userReallocationIncrease;
+            this.users_with_reallocations++;
         }
     }
 
     getResult() {
-        if (this.userCount === 0) {
-            return {};
-        }
+        const avg_pct = (this.users_with_reallocations > 0)
+            ? (this.total_reallocation_increase_pct / this.users_with_reallocations)
+            : 0;
 
         return {
-             // Calculate the final average directly
-            average_reallocation_increase_percentage: this.accumulatedIncreasePercentage / this.userCount
+            average_reallocation_increase_pct: avg_pct,
+            total_reallocation_increase_pct_sum: this.total_reallocation_increase_pct,
+            user_count_with_reallocations: this.users_with_reallocations
         };
     }
 
     reset() {
-        this.accumulatedIncreasePercentage = 0;
-        this.userCount = 0;
+        this.total_reallocation_increase_pct = 0;
+        this.users_with_reallocations = 0;
     }
 }
 

package/calculations/insights/daily_buy_sell_sentiment_count.js

@@ -1,55 +1,70 @@
 /**
- * @fileoverview Calculates the total number of 'buy' vs 'sell' (short) positions across all instruments.
- * Uses the 'daily_instrument_insights' collection (truth of source).
+ * @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.
  */
-
 class DailyBuySellSentimentCount {
     constructor() {
-        this.totalBuyPositions = 0;
-        this.totalSellPositions = 0;
-        this.processedDay = false; // Flag to run logic only once per day
+        this.buyPositions = 0;
+        this.sellPositions = 0;
     }
 
-    // Only needs today's insights
-    async process(todayPortfolio, yesterdayPortfolio, userId, context, todayInsights, yesterdayInsights) {
-        if (this.processedDay) return;
-        this.processedDay = true;
+    /**
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
+     */
+    static getSchema() {
+        return {
+            "type": "object",
+            "description": "Total count of 'buy' (long) vs 'sell' (short) positions and the sentiment ratio.",
+            "properties": {
+                "totalBuyPositions": {
+                    "type": "number",
+                    "description": "Total count of all 'buy' (long) positions."
+                },
+                "totalSellPositions": {
+                    "type": "number",
+                    "description": "Total count of all 'sell' (short) positions."
+                },
+                "sentimentRatio": {
+                    "type": ["number", "null"],
+                    "description": "Ratio of buy to sell positions (buy/sell). Null if no sell positions."
+                }
+            },
+            "required": ["totalBuyPositions", "totalSellPositions", "sentimentRatio"]
+        };
+    }
 
-        if (!todayInsights || !todayInsights.insights) {
-            console.warn('[DailyBuySellSentimentCount] Missing insights data for today.');
+    process(portfolioData) {
+        const positions = portfolioData.PublicPositions || portfolioData.AggregatedPositions;
+        if (!positions || !Array.isArray(positions)) {
             return;
         }
 
-        for (const instrument of todayInsights.insights) {
-            const totalOwners = instrument.total || 0;
-            if (totalOwners > 0) {
-                const buyPercent = (instrument.buy || 0) / 100;
-                const sellPercent = (instrument.sell || 0) / 100; // 'sell' means short here
-
-                this.totalBuyPositions += (buyPercent * totalOwners);
-                this.totalSellPositions += (sellPercent * totalOwners);
+        for (const pos of positions) {
+            if (pos.IsBuy) {
+                this.buyPositions++;
+            } else {
+                this.sellPositions++;
             }
         }
     }
 
     getResult() {
-        // --- ADD THIS CHECK ---
-        if (!this.processedDay) {
-            console.warn('[DailyBuySellSentimentCount] getResult called but process never ran (missing insights). Returning null for backfill.');
-            return null;
-        }
-        // --- END ADD ---
-
         return {
-            total_buy_positions: Math.round(this.totalBuyPositions),
-            total_sell_positions: Math.round(this.totalSellPositions)
+            totalBuyPositions: this.buyPositions,
+            totalSellPositions: this.sellPositions,
+            // Calculate ratio: Buy / Sell
+            sentimentRatio: (this.sellPositions > 0) ? (this.buyPositions / this.sellPositions) : null
         };
     }
 
     reset() {
-        this.totalBuyPositions = 0;
-        this.totalSellPositions = 0;
-        this.processedDay = false;
+        this.buyPositions = 0;
+        this.sellPositions = 0;
     }
 }
 

package/calculations/insights/daily_total_positions_held.js

@@ -1,45 +1,49 @@
 /**
- * @fileoverview Calculates the total number of positions held across all instruments for the day.
- * Uses the 'daily_instrument_insights' collection (truth of source).
+ * @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.
  */
-
 class DailyTotalPositionsHeld {
     constructor() {
         this.totalPositions = 0;
-        this.processedDay = false; // Flag to run logic only once per day
     }
 
-    // Only needs today's insights
-    async process(todayPortfolio, yesterdayPortfolio, userId, context, todayInsights, yesterdayInsights) {
-        if (this.processedDay) return;
-        this.processedDay = true;
-
-        if (!todayInsights || !todayInsights.insights) {
-            console.warn('[DailyTotalPositionsHeld] Missing insights data for today.');
-            return;
-        }
+    /**
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
+     */
+    static getSchema() {
+        return {
+            "type": "object",
+            "description": "Calculates the total number of positions held across all users and instruments.",
+            "properties": {
+                "totalPositions": {
+                    "type": "number",
+                    "description": "The total aggregated count of all positions."
+                }
+            },
+            "required": ["totalPositions"]
+        };
+    }
 
-        for (const instrument of todayInsights.insights) {
-            this.totalPositions += (instrument.total || 0);
+    process(portfolioData) {
+        const positions = portfolioData.PublicPositions || portfolioData.AggregatedPositions;
+        if (positions && Array.isArray(positions)) {
+            this.totalPositions += positions.length;
         }
     }
 
     getResult() {
-        // --- ADD THIS CHECK ---
-        if (!this.processedDay) {
-            console.warn('[DailyTotalPositionsHeld] getResult called but process never ran (missing insights). Returning null for backfill.');
-            return null;
-        }
-        // --- END ADD ---
-
         return {
-            total_positions_held: this.totalPositions
+            totalPositions: this.totalPositions
         };
     }
 
     reset() {
         this.totalPositions = 0;
-        this.processedDay = false;
     }
 }