aiden-shared-calculations-unified 1.0.64 → 1.0.65

package/calculations/meta/negative_expectancy_cohort_flow.js

@@ -1,224 +1,232 @@
 /**
- * @fileoverview Calculates "Net Crowd Flow" and "Sector Rotation"
- * *only* for the "Dumb Cohort" (Bottom 20% of Investor Scores).
+ * @fileoverview Calculation (Pass 4) for negative expectancy cohort flow.
  *
- * --- META REFACTOR (v2) ---
- * This calculation is `type: "meta"` and expects its dependencies
- * (the user-investment-profile results) to be fetched by the pass runner.
- * It then streams root portfolio data.
+ * This metric calculates the "Net Crowd Flow Percentage" for the
+ * "Negative Expectancy Cohort" (users with a low expectancy score).
+ *
+ * This calculation *depends* on 'user_expectancy_score'
+ * to identify the cohort.
  */
+const { loadInstrumentMappings } = require('../../../utils/sector_mapping_provider');
 
-const { Firestore } = require('@google-cloud/firestore');
-const firestore = new Firestore();
-const { loadAllPriceData, getDailyPriceChange } = require('../../utils/price_data_provider');
-const { loadInstrumentMappings, getInstrumentSectorMap } = require('../../utils/sector_mapping_provider');
-// NOTE: Corrected relative path for data_loader
-const { loadDataByRefs, getPortfolioPartRefs, loadFullDayMap } = require('../../../bulltrackers-module/functions/computation-system/utils/data_loader');
-
-const COHORT_PERCENTILE = 0.2; // Bottom 20%
-const PROFILE_CALC_ID = 'user-investment-profile'; // The calc to read IS scores from
-
-class DumbCohortFlow {
+class NegativeExpectancyCohortFlow {
+    constructor() {
+        this.assetData = new Map();
+        this.sectorData = new Map();
+        this.mappings = null;
+        this.negExpCohortUserIds = null;
+    }
 
     /**
-     * (NEW) Statically declare dependencies.
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
      */
-    static getDependencies() {
-        return ['user_expectancy_score'];
-    }
+    static getSchema() {
+        const flowSchema = {
+            "type": "object",
+            "properties": {
+                "net_flow_percentage": { "type": "number" },
+                "total_invested_today": { "type": "number" },
+                "total_invested_yesterday": { "type": "number" }
+            },
+            "required": ["net_flow_percentage", "total_invested_today", "total_invested_yesterday"]
+        };
 
-    constructor() {
-        // Meta-calc, no constructor state needed
+        return {
+            "type": "object",
+            "description": "Calculates net capital flow % (price-adjusted) for the 'Negative Expectancy' cohort (score < 0.2), aggregated by asset and sector.",
+            "properties": {
+                "cohort_size": {
+                    "type": "number",
+                    "description": "The number of users identified as being in the Negative Expectancy Cohort."
+                },
+                "assets": {
+                    "type": "object",
+                    "description": "Price-adjusted net flow per asset.",
+                    "patternProperties": { "^.*$": flowSchema }, // Ticker
+                    "additionalProperties": flowSchema
+                },
+                "sectors": {
+                    "type": "object",
+                    "description": "Price-adjusted net flow per sector.",
+                    "patternProperties": { "^.*$": flowSchema }, // Sector
+                    "additionalProperties": flowSchema
+                }
+            },
+            "required": ["cohort_size", "assets", "sectors"]
+        };
     }
 
     /**
-     * Loads the Investor Scores from the fetched dependency.
+     * Statically declare dependencies.
      */
-    _loadCohort(logger, fetchedDependencies) {
-    logger.log('INFO', '[NegativeExpectancyCohortFlow] Loading Expectancy Scores from fetched dependency...');
-
-    const profileData = fetchedDependencies['user-expectancy-score'];
-
-    if (!profileData || Object.keys(profileData).length === 0) {
-        logger.log('WARN', `[NegativeExpectancyCohortFlow] Cannot find dependency 'user-expectancy-score'. Cohort will not be built.`);
-        return null;
+    static getDependencies() {
+        return ['user_expectancy_score']; // Pass 3
     }
 
-    const allScores = Object.entries(profileData).map(([userId, data]) => ({ 
-        userId, 
-        score: data.expectancy_score 
-    }));
-
-    allScores.sort((a, b) => a.score - b.score);
-
-    // Find the 20th percentile (Bottom 20%)
-    const thresholdIndex = Math.floor(allScores.length * 0.20);
-    const thresholdScore = allScores[thresholdIndex]?.score || 0;
-
-    // Filter for users with a *negative expectancy score* AND are in the bottom 20%
-    const cohortIds = new Set(
-        allScores.filter(s => s.score <= thresholdScore && s.score < 0) 
-                 .map(s => s.userId)
-    );
-
-    logger.log('INFO', `[NegativeExpectancyCohortFlow] Cohort built. ${cohortIds.size} users at or below ${thresholdScore.toFixed(2)} (20th percentile) and < 0.`);
-    return cohortIds;
+    _getPortfolioPositions(portfolio) {
+        return portfolio?.PublicPositions || portfolio?.AggregatedPositions;
     }
 
-    // --- Asset Flow Helpers (unchanged) ---
-    _initAsset(asset_values, instrumentId) {
-        if (!asset_values[instrumentId]) {
-            asset_values[instrumentId] = { day1_value_sum: 0, day2_value_sum: 0 };
+    _initAsset(instrumentId) {
+        if (!this.assetData.has(instrumentId)) {
+            this.assetData.set(instrumentId, {
+                total_invested_yesterday: 0,
+                total_invested_today: 0,
+                price_change_yesterday: 0,
+            });
         }
     }
-    _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;
-            }
+    
+    _initSector(sector) {
+        if (!this.sectorData.has(sector)) {
+            this.sectorData.set(sector, {
+                total_invested_yesterday: 0,
+                total_invested_today: 0,
+                price_change_yesterday: 0,
+            });
         }
-        return valueMap;
     }
-    _accumulateSectorInvestment(portfolio, target, sectorMap) {
-        if (portfolio && portfolio.AggregatedPositions) {
-            for (const pos of portfolio.AggregatedPositions) {
-                const sector = sectorMap[pos.InstrumentID] || 'N/A';
-                target[sector] = (target[sector] || 0) + (pos.Invested || pos.Amount || 0);
+
+    _getNegExpCohort(fetchedDependencies) {
+        if (this.negExpCohortUserIds) {
+            return this.negExpCohortUserIds;
+        }
+        
+        const expectancyData = fetchedDependencies['user_expectancy_score'];
+        if (!expectancyData) {
+            return new Set();
+        }
+
+        this.negExpCohortUserIds = new Set();
+        for (const [userId, data] of Object.entries(expectancyData)) {
+            // Definition: Expectancy score < 0.2
+            if (data.expectancy_score < 0.2) {
+                this.negExpCohortUserIds.add(userId);
             }
         }
+        return this.negExpCohortUserIds;
     }
 
-    /**
-     * REFACTORED PROCESS METHOD
-     * @param {string} dateStr The date to run the analysis for (e.g., "2025-10-31").
-     * @param {object} dependencies The shared dependencies (db, logger, rootData, etc.).
-     * @param {object} config The computation system configuration.
-     * @param {object} fetchedDependencies In-memory results from previous passes.
-     * @returns {Promise<object|null>} The analysis result or null.
-     */
-    async process(dateStr, dependencies, config, fetchedDependencies) {
-        const { logger, db, rootData, calculationUtils } = dependencies;
-        const { portfolioRefs } = rootData;
-        logger.log('INFO', '[DumbCohortFlow] Starting meta-process...');
+    process(todayPortfolio, yesterdayPortfolio, userId, context, todayInsights, yesterdayInsights, fetchedDependencies) {
+        const cohort = this._getNegExpCohort(fetchedDependencies);
         
-        // 1. Load Cohort from in-memory dependency
-        const dumbCohortIds = this._loadCohort(logger, fetchedDependencies);
-        if (!dumbCohortIds) {
-            return null; // Dependency failed
+        if (!cohort.has(userId)) {
+            return;
         }
 
-        // 2. Load external dependencies (prices, sectors)
-        const [priceMap, mappings, sectorMap] = await Promise.all([
-            loadAllPriceData(),
-            loadInstrumentMappings(),
-            getInstrumentSectorMap()
-        ]);
-        if (!priceMap || !mappings || !sectorMap || Object.keys(priceMap).length === 0) {
-            logger.log('ERROR', '[DumbCohortFlow] Failed to load critical price/mapping/sector data. Aborting.');
-            return null;
+        if (!todayPortfolio || !yesterdayPortfolio) {
+            return;
         }
 
-        // 3. Load "yesterday's" portfolio data for comparison
-        const yesterdayDate = new Date(dateStr + 'T00:00:00Z');
-        yesterdayDate.setUTCDate(yesterdayDate.getUTCDate() - 1);
-        const yesterdayStr = yesterdayDate.toISOString().slice(0, 10);
-        const yesterdayRefs = await getPortfolioPartRefs(config, dependencies, yesterdayStr);
-        const yesterdayPortfolios = await loadFullDayMap(config, dependencies, yesterdayRefs);
-        logger.log('INFO', `[DumbCohortFlow] Loaded ${yesterdayRefs.length} part refs for yesterday.`);
-
-        // 4. Stream "today's" portfolio data and process
-        const asset_values = {};
-        const todaySectorInvestment = {};
-        const yesterdaySectorInvestment = {};
-        let user_count = 0;
-
-        const batchSize = config.partRefBatchSize || 10;
-        for (let i = 0; i < portfolioRefs.length; i += batchSize) {
-            const batchRefs = portfolioRefs.slice(i, i + batchSize);
-            const todayPortfoliosChunk = await loadDataByRefs(config, dependencies, batchRefs);
-
-            for (const uid in todayPortfoliosChunk) {
-                
-                if (!dumbCohortIds.has(uid)) continue; // --- Filter user ---
-                
-                const pToday = todayPortfoliosChunk[uid];
-                const pYesterday = yesterdayPortfolios[uid];
-                
-                if (!pToday || !pYesterday || !pToday.AggregatedPositions || !pYesterday.AggregatedPositions) {
-                    continue;
-                }
-                
-                // 4a. RUN ASSET FLOW LOGIC
-                const yesterdayValues = this._sumAssetValue(pYesterday.AggregatedPositions);
-                const todayValues = this._sumAssetValue(pToday.AggregatedPositions);
-                const allInstrumentIds = new Set([...Object.keys(yesterdayValues), ...Object.keys(todayValues)]);
-                
-                for (const instrumentId of allInstrumentIds) {
-                    this._initAsset(asset_values, instrumentId);
-                    asset_values[instrumentId].day1_value_sum += (yesterdayValues[instrumentId] || 0);
-                    asset_values[instrumentId].day2_value_sum += (todayValues[instrumentId] || 0);
-                }
+        const yPos = this._getPortfolioPositions(yesterdayPortfolio);
+        const tPos = this._getPortfolioPositions(todayPortfolio);
 
-                // 4b. RUN SECTOR ROTATION LOGIC
-                this._accumulateSectorInvestment(pToday, todaySectorInvestment, sectorMap);
-                this._accumulateSectorInvestment(pYesterday, yesterdaySectorInvestment, sectorMap);
-                user_count++;
-            }
-        }
-        
-        logger.log('INFO', `[DumbCohortFlow] Processed ${user_count} users in cohort.`);
+        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()]);
         
-        // --- 5. GETRESULT LOGIC ---
-        if (user_count === 0) {
-            logger.warn('[DumbCohortFlow] No users processed for dumb cohort. Returning null.');
-            return null;
+        if (!this.mappings) {
+            this.mappings = context.mappings;
         }
 
-        // 5a. Calculate Asset Flow
-        const finalAssetFlow = {};
-        for (const instrumentId in asset_values) {
-            const ticker = mappings.instrumentToTicker[instrumentId] || `id_${instrumentId}`;
-            const avg_day1_value = asset_values[instrumentId].day1_value_sum / user_count;
-            const avg_day2_value = asset_values[instrumentId].day2_value_sum / user_count;
-            const priceChangePct = getDailyPriceChange(instrumentId, yesterdayStr, dateStr, priceMap);
+        for (const instrumentId of allInstrumentIds) {
+            if (!instrumentId) continue;
+            
+            this._initAsset(instrumentId);
+            const asset = this.assetData.get(instrumentId);
 
-            if (priceChangePct === null) continue;
+            const yP = yPosMap.get(instrumentId);
+            const tP = tPosMap.get(instrumentId);
 
-            const expected_day2_value = avg_day1_value * (1 + priceChangePct);
-            const net_crowd_flow_pct = avg_day2_value - expected_day2_value;
+            const yInvested = yP?.InvestedAmount || yP?.Amount || 0;
+            const tInvested = tP?.InvestedAmount || tP?.Amount || 0;
+            
+            const sector = this.mappings.instrumentToSector[instrumentId] || 'Other';
+            this._initSector(sector);
+            const sectorAsset = this.sectorData.get(sector);
 
-            finalAssetFlow[ticker] = {
-                net_crowd_flow_pct: net_crowd_flow_pct,
-                avg_value_day1_pct: avg_day1_value,
-                avg_value_day2_pct: avg_day2_value
-            };
+            if (yInvested > 0) {
+                const yPriceChange = (yP?.PipsRate || 0) / (yP?.OpenRate || 1);
+                
+                asset.total_invested_yesterday += yInvested;
+                asset.price_change_yesterday += yPriceChange * yInvested;
+                
+                sectorAsset.total_invested_yesterday += yInvested;
+                sectorAsset.price_change_yesterday += yPriceChange * yInvested;
+            }
+            if (tInvested > 0) {
+                asset.total_invested_today += tInvested;
+                sectorAsset.total_invested_today += tInvested;
+            }
         }
-        
-        // 5b. Calculate Sector Rotation
-        const finalSectorRotation = {};
-        const allSectors = new Set([...Object.keys(todaySectorInvestment), ...Object.keys(yesterdaySectorInvestment)]);
-        for (const sector of allSectors) {
-            const todayAmount = todaySectorInvestment[sector] || 0;
-            const yesterdayAmount = yesterdaySectorInvestment[sector] || 0;
-            finalSectorRotation[sector] = todayAmount - yesterdayAmount;
+    }
+    
+    _calculateFlow(dataMap) {
+        const result = {};
+        for (const [key, data] of dataMap.entries()) {
+            const { total_invested_yesterday, total_invested_today, price_change_yesterday } = data;
+            
+            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;
+                
+                result[key] = {
+                    net_flow_percentage: net_flow_percentage,
+                    total_invested_today: total_invested_today,
+                    total_invested_yesterday: total_invested_yesterday
+                };
+            }
         }
+        return result;
+    }
 
-        if (Object.keys(finalAssetFlow).length === 0) {
-            logger.warn('[DumbCohortFlow] No asset flow calculated (likely all price data missing). Returning null.');
-            return null;
+    async getResult(fetchedDependencies) {
+        if (!this.mappings) {
+            this.mappings = await loadInstrumentMappings();
         }
+        
+        const cohort = this._getNegExpCohort(fetchedDependencies);
+
+        // 1. Calculate Asset Flow
+        const assetResult = {};
+        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) {
+                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;
+                
+                assetResult[ticker] = {
+                    net_flow_percentage: net_flow_percentage,
+                    total_invested_today: total_invested_today,
+                    total_invested_yesterday: total_invested_yesterday
+                };
+            }
+        }
+        
+        // 2. Calculate Sector Flow
+        const sectorResult = this._calculateFlow(this.sectorData);
 
         return {
-            asset_flow: finalAssetFlow,
-            sector_rotation: finalSectorRotation,
-            user_sample_size: user_count
+            cohort_size: cohort.size,
+            assets: assetResult,
+            sectors: sectorResult
         };
     }
 
-    async getResult() { return null; }
-    reset() { }
+    reset() {
+        this.assetData.clear();
+        this.sectorData.clear();
+        this.mappings = null;
+        this.negExpCohortUserIds = null;
+    }
 }
 
-module.exports = DumbCohortFlow;
+module.exports = NegativeExpectancyCohortFlow;