aiden-shared-calculations-unified 1.0.16 → 1.0.18

package/calculations/meta/profit_cohort_divergence.js

@@ -0,0 +1,92 @@
+/**
+ * @fileoverview Meta-calculation (Pass 3) that correlates the asset flow
+ * of the "In Profit" cohort vs. the "In Loss" cohort to find
+ * powerful divergence signals (e.g., profit-taking, capitulation).
+ */
+
+class ProfitCohortDivergence {
+    constructor() {
+        this.flowThreshold = 0.5; // Min abs flow % to be considered a signal
+    }
+
+    /**
+     * @param {string} dateStr The date to run the analysis for (e.g., "2025-10-31").
+     * @param {object} dependencies The shared dependencies (db, logger).
+     * @param {object} config The computation system configuration.
+     * @returns {Promise<object|null>} The analysis result or null.
+     */
+    async process(dateStr, dependencies, config) {
+        const { db, logger } = dependencies;
+        const collection = config.resultsCollection;
+        const resultsSub = config.resultsSubcollection || 'results';
+        const compsSub = config.computationsSubcollection || 'computations';
+
+        // 1. Define dependencies
+        const refsToGet = [
+            {
+                key: 'profit_flow',
+                ref: db.collection(collection).doc(dateStr).collection(resultsSub).doc('behavioural').collection(compsSub).doc('in-profit-asset-crowd-flow')
+            },
+            {
+                key: 'loss_flow',
+                ref: db.collection(collection).doc(dateStr).collection(resultsSub).doc('behavioural').collection(compsSub).doc('in-loss-asset-crowd-flow')
+            }
+        ];
+
+        // 2. Fetch
+        const snapshots = await db.getAll(...refsToGet.map(r => r.ref));
+        const profitFlowData = snapshots[0].exists ? snapshots[0].data() : null;
+        const lossFlowData = snapshots[1].exists ? snapshots[1].data() : null;
+
+        // 3. Handle "day-delay"
+        if (!profitFlowData || !lossFlowData) {
+            logger.log('WARN', `[ProfitCohortDivergence] Missing cohort flow data for ${dateStr}. Allowing backfill.`);
+            return null; // Let backfill handle it
+        }
+
+        const results = {};
+        const allTickers = new Set([...Object.keys(profitFlowData), ...Object.keys(lossFlowData)]);
+
+        // 4. Correlate
+        for (const ticker of allTickers) {
+            const profitFlow = profitFlowData[ticker]?.net_crowd_flow_pct || 0;
+            const lossFlow = lossFlowData[ticker]?.net_crowd_flow_pct || 0;
+
+            const profitSells = profitFlow <= -this.flowThreshold;
+            const profitBuys = profitFlow >= this.flowThreshold;
+            const lossSells = lossFlow <= -this.flowThreshold;
+            const lossBuys = lossFlow >= this.flowThreshold;
+
+            let status = 'No Divergence';
+            let detail = 'Both cohorts are acting similarly or flow is insignificant.';
+
+            if (profitSells && lossBuys) {
+                status = 'Profit Taking';
+                detail = 'The "in-profit" cohort is selling to the "in-loss" cohort, who are averaging down.';
+            } else if (profitBuys && lossSells) {
+                status = 'Capitulation';
+                detail = 'The "in-loss" cohort is panic-selling, and the "in-profit" cohort is buying the dip.';
+            } else if (profitBuys && lossBuys) {
+                status = 'High Conviction Buy';
+                detail = 'All cohorts are net-buying.';
+            } else if (profitSells && lossSells) {
+                status = 'High Conviction Sell';
+                detail = 'All cohorts are net-selling.';
+            }
+
+            results[ticker] = {
+                status: status,
+                detail: detail,
+                profit_cohort_flow: profitFlow,
+                loss_cohort_flow: lossFlow
+            };
+        }
+
+        return results;
+    }
+
+    async getResult() { return null; }
+    reset() {}
+}
+
+module.exports = ProfitCohortDivergence;

package/calculations/meta/smart-dumb-divergence-index.js

@@ -0,0 +1,128 @@
+/**
+ * @fileoverview Meta-calculation (Pass 3) that correlates the asset/sector flow
+ * of the "Smart Cohort" vs. the "Dumb Cohort" to find divergence signals.
+ *
+ * This identifies:
+ * 1. "Capitulation": Smart cohort is buying what the dumb cohort is panic-selling.
+ * 2. "Euphoria": Smart cohort is selling what the dumb cohort is FOMO-buying.
+ */
+
+class SmartDumbDivergenceIndex {
+    constructor() {
+        // Minimum net flow (as a percentage) to be considered a signal
+        this.FLOW_THRESHOLD = 0.5;
+    }
+
+    /**
+     * @param {string} dateStr The date to run the analysis for (e.g., "2025-10-31").
+     * @param {object} dependencies The shared dependencies (db, logger).
+     * @param {object} config The computation system configuration.
+     * @returns {Promise<object|null>} The analysis result or null.
+     */
+    async process(dateStr, dependencies, config) {
+        const { db, logger } = dependencies;
+        const collection = config.resultsCollection;
+        const resultsSub = config.resultsSubcollection || 'results';
+        const compsSub = config.computationsSubcollection || 'computations';
+
+        // 1. Define dependencies
+        const refsToGet = [
+            {
+                key: 'smart_flow',
+                ref: db.collection(collection).doc(dateStr).collection(resultsSub).doc('behavioural').collection(compsSub).doc('smart-cohort-flow')
+            },
+            {
+                key: 'dumb_flow',
+                ref: db.collection(collection).doc(dateStr).collection(resultsSub).doc('behavioural').collection(compsSub).doc('dumb-cohort-flow')
+            }
+        ];
+
+        // 2. Fetch
+        const snapshots = await db.getAll(...refsToGet.map(r => r.ref));
+        const smartData = snapshots[0].exists ? snapshots[0].data() : null;
+        const dumbData = snapshots[1].exists ? snapshots[1].data() : null;
+
+        // 3. Handle "day-delay"
+        if (!smartData || !dumbData) {
+            logger.log('WARN', `[SmartDumbDivergence] Missing cohort flow data for ${dateStr}. Allowing backfill.`);
+            return null; // Let backfill handle it
+        }
+        
+        const results = {
+            assets: {},
+            sectors: {}
+        };
+        
+        const smartAssetFlow = smartData.asset_flow || {};
+        const dumbAssetFlow = dumbData.asset_flow || {};
+        const smartSectorFlow = smartData.sector_rotation || {};
+        const dumbSectorFlow = dumbData.sector_rotation || {};
+
+        // 4. Correlate Assets
+        const allTickers = new Set([...Object.keys(smartAssetFlow), ...Object.keys(dumbAssetFlow)]);
+        for (const ticker of allTickers) {
+            const sFlow = smartAssetFlow[ticker]?.net_crowd_flow_pct || 0;
+            const dFlow = dumbAssetFlow[ticker]?.net_crowd_flow_pct || 0;
+
+            const smartBuys = sFlow >= this.FLOW_THRESHOLD;
+            const smartSells = sFlow <= -this.FLOW_THRESHOLD;
+            const dumbBuys = dFlow >= this.FLOW_THRESHOLD;
+            const dumbSells = dFlow <= -this.FLOW_THRESHOLD;
+
+            let status = 'No_Divergence';
+            let detail = 'Cohorts are aligned or flow is insignificant.';
+
+            if (smartBuys && dumbSells) {
+                status = 'Capitulation';
+                detail = 'Smart cohort is buying the dip from the panic-selling dumb cohort.';
+            } else if (smartSells && dumbBuys) {
+                status = 'Euphoria';
+                detail = 'Smart cohort is selling into the FOMO-buying dumb cohort.';
+            } else if (smartBuys && dumbBuys) {
+                status = 'Aligned_Buy';
+            } else if (smartSells && dumbSells) {
+                status = 'Aligned_Sell';
+            }
+
+            if (status !== 'No_Divergence') {
+                results.assets[ticker] = {
+                    status: status,
+                    detail: detail,
+                    smart_cohort_flow_pct: sFlow,
+                    dumb_cohort_flow_pct: dFlow
+                };
+            }
+        }
+        
+        // 5. Correlate Sectors (Note: flow is total $, not %)
+        // We can just check for opposing signs
+        const allSectors = new Set([...Object.keys(smartSectorFlow), ...Object.keys(dumbSectorFlow)]);
+         for (const sector of allSectors) {
+             const sFlow = smartSectorFlow[sector] || 0;
+             const dFlow = dumbSectorFlow[sector] || 0;
+
+             let status = 'No_Divergence';
+             
+             if (sFlow > 0 && dFlow < 0) {
+                 status = 'Capitulation';
+             } else if (sFlow < 0 && dFlow > 0) {
+                 status = 'Euphoria';
+             }
+
+            if (status !== 'No_Divergence') {
+                 results.sectors[sector] = {
+                    status: status,
+                    smart_cohort_flow_usd: sFlow,
+                    dumb_cohort_flow_usd: dFlow
+                };
+            }
+         }
+
+        return results;
+    }
+
+    async getResult() { return null; }
+    reset() {}
+}
+
+module.exports = SmartDumbDivergenceIndex;

package/calculations/meta/social_flow_correlation.js

@@ -0,0 +1,123 @@
+/**
+ * @fileoverview Meta-calculation (Pass 3) to correlate daily social sentiment with
+ * the actual crowd asset flow. It identifies divergences between what the crowd
+ * says and what they do.
+ */
+
+class SocialFlowCorrelation {
+    constructor() {
+        // Define sensitivity thresholds
+        this.bullishSentimentThreshold = 70.0; // % ratio
+        this.bearishSentimentThreshold = 30.0; // % ratio
+        this.positiveFlowThreshold = 0.5; // net_crowd_flow_pct
+        this.negativeFlowThreshold = -0.5; // net_crowd_flow_pct
+    }
+
+    /**
+     * @param {string} dateStr The date to run the analysis for (e.g., "2025-10-31").
+     * @param {object} dependencies The shared dependencies (db, logger).
+     * @param {object} config The computation system configuration.
+     * @returns {Promise<object|null>} The analysis result or null.
+     */
+    async process(dateStr, dependencies, config) {
+        const { db, logger } = dependencies;
+        const collection = config.resultsCollection;
+
+        // 1. Define dependencies for the *same day*
+        const dependenciesToFetch = [
+            { category: 'socialPosts', computation: 'social_sentiment_aggregation' },
+            { category: 'behavioural', computation: 'asset_crowd_flow' }
+        ];
+
+        // 2. Build refs and fetch
+        const refs = dependenciesToFetch.map(d =>
+            db.collection(collection).doc(dateStr)
+                .collection('results').doc(d.category)
+                .collection('computations').doc(d.computation)
+        );
+
+        const snapshots = await db.getAll(...refs);
+
+        // 3. Check for data and handle the "day-delay"
+        const socialData = snapshots[0].exists ? snapshots[0].data() : null;
+        const flowData = snapshots[1].exists ? snapshots[1].data() : null;
+
+        if (!socialData || !flowData) {
+            logger.log('WARN', `[SocialFlowCorrelation] Missing dependency data for ${dateStr}. Allowing backfill.`);
+            // Return null. This stops execution and does not save an empty doc.
+            // The Pass 3 backfill will pick this up tomorrow.
+            return null;
+        }
+
+        // 4. If data exists, perform the correlation
+        const sentimentMap = socialData.tickerSentiment || {};
+        const correlationResults = {};
+
+        // Use all tickers from the flow data as the primary loop
+        for (const ticker in flowData) {
+            if (!flowData[ticker] || typeof flowData[ticker].net_crowd_flow_pct === 'undefined') {
+                continue;
+            }
+
+            const flow = flowData[ticker].net_crowd_flow_pct;
+            const sentiment = sentimentMap[ticker]?.sentimentRatio; // e.g., 85.0 or 22.5
+
+            if (typeof sentiment === 'undefined') {
+                // No sentiment found, just record flow
+                correlationResults[ticker] = {
+                    status: 'no_social_sentiment',
+                    net_crowd_flow_pct: flow
+                };
+                continue;
+            }
+
+            // --- The "Jaw-Drop" Logic ---
+            if (sentiment >= this.bullishSentimentThreshold && flow <= this.negativeFlowThreshold) {
+                // Crowd is very bullish but is actively selling
+                correlationResults[ticker] = {
+                    status: 'Bullish Divergence',
+                    detail: 'Crowd is publicly bullish but is net-selling the asset.',
+                    sentiment_ratio: sentiment,
+                    net_crowd_flow_pct: flow
+                };
+            } else if (sentiment <= this.bearishSentimentThreshold && flow >= this.positiveFlowThreshold) {
+                // Crowd is very bearish but is actively buying
+                correlationResults[ticker] = {
+                    status: 'Bearish Divergence',
+                    detail: 'Crowd is publicly bearish but is net-buying the asset.',
+                    sentiment_ratio: sentiment,
+                    net_crowd_flow_pct: flow
+                };
+            } else if (sentiment >= this.bullishSentimentThreshold && flow >= this.positiveFlowThreshold) {
+                // Crowd is bullish and is buying
+                correlationResults[ticker] = {
+                    status: 'High Conviction Buy',
+                    sentiment_ratio: sentiment,
+                    net_crowd_flow_pct: flow
+                };
+            } else if (sentiment <= this.bearishSentimentThreshold && flow <= this.negativeFlowThreshold) {
+                // Crowd is bearish and is selling
+                correlationResults[ticker] = {
+                    status: 'High Conviction Sell',
+                    sentiment_ratio: sentiment,
+                    net_crowd_flow_pct: flow
+                };
+            } else {
+                // No strong signal or divergence
+                correlationResults[ticker] = {
+                    status: 'No Clear Signal',
+                    sentiment_ratio: sentiment,
+                    net_crowd_flow_pct: flow
+                };
+            }
+        }
+
+        return correlationResults;
+    }
+
+    // Must exist for the meta-computation runner
+    async getResult() { return null; }
+    reset() {}
+}
+
+module.exports = SocialFlowCorrelation;

package/calculations/pnl/historical/user_profitability_tracker.js

@@ -1,47 +1,68 @@
 /**
  * @fileoverview Tracks user profitability over a 7-day rolling window.
- * This version shards the output to avoid Firestore's "too many index entries" error.
+ * This version shards the output AND calculates the user's *weighted average daily PNL (as a decimal %)*.
  */
 
 const { Firestore } = require('@google-cloud/firestore');
 const firestore = new Firestore();
 
-// Define a constant for the number of shards
 const NUM_SHARDS = 50;
 
 class UserProfitabilityTracker {
     constructor() {
-        this.dailyProfits = {};
+        // This will store { userId: { weightedPnlSum: 0, totalInvested: 0 } }
+        this.dailyData = {}; 
     }
 
-    process(todayPortfolio, yesterdayPortfolio, userId) {
-        if (!todayPortfolio) return;
+    /**
+     * Calculates the weighted PNL for the day.
+     * NetProfit is a decimal % return (e.g., 0.03)
+     * Invested is a decimal % weight (e.g., 0.05)
+     */
+    calculateWeightedDailyPnl(portfolio) {
+        if (!portfolio || !portfolio.AggregatedPositions || portfolio.AggregatedPositions.length === 0) {
+            return { weightedPnl: 0, totalInvested: 0 };
+        }
+
+        let weightedPnlSum = 0;
+        let totalInvested = 0;
 
-        const todayPnl = this.calculateTotalPnl(todayPortfolio);
-        if (todayPnl !== null) {
-            this.dailyProfits[userId] = todayPnl;
+        for (const pos of portfolio.AggregatedPositions) {
+            // Use NetProfit (the % return)
+            const netProfit = ('NetProfit' in pos) ? pos.NetProfit : (pos.ProfitAndLoss || 0); 
+            // Use InvestedAmount (the % portfolio weight)
+            const invested = pos.InvestedAmount || pos.Amount || 0; 
+
+            if (invested > 0) {
+                weightedPnlSum += netProfit * invested;
+                totalInvested += invested;
+            }
         }
+
+        return { weightedPnlSum, totalInvested };
     }
 
-    calculateTotalPnl(portfolio) {
-        if (portfolio && portfolio.AggregatedPositions) {
-            return portfolio.AggregatedPositions.reduce((sum, pos) => sum + pos.NetProfit, 0);
-        } else if (portfolio && portfolio.PublicPositions) {
-            return portfolio.PublicPositions.reduce((sum, pos) => sum + pos.NetProfit, 0);
+    process(todayPortfolio, yesterdayPortfolio, userId) {
+        if (!todayPortfolio) return;
+
+        const { weightedPnlSum, totalInvested } = this.calculateWeightedDailyPnl(todayPortfolio);
+
+        if (totalInvested > 0) {
+            this.dailyData[userId] = { weightedPnlSum, totalInvested };
         }
-        return null;
     }
 
     async getResult() {
         const today = new Date().toISOString().slice(0, 10);
-        const results = {};
+        const results = {}; // For sharded history
+        const dailyPnlMap = {}; // For the new profile calc
 
         // Prepare sharded data structure
         for (let i = 0; i < NUM_SHARDS; i++) {
             results[`user_profitability_shard_${i}`] = {};
         }
 
-        // Fetch all existing shards in parallel for efficiency
+        // ... (Fetch existing shards logic, same as your file) ...
         const shardPromises = [];
         for (let i = 0; i < NUM_SHARDS; i++) {
             const docRef = firestore.collection('historical_insights').doc(`user_profitability_shard_${i}`);
@@ -50,18 +71,38 @@ class UserProfitabilityTracker {
         const shardSnapshots = await Promise.all(shardPromises);
         const existingData = shardSnapshots.map(snap => (snap.exists ? snap.data().profits : {}));
 
-        // Process users and assign them to shards
-        for (const userId in this.dailyProfits) {
+
+        for (const userId in this.dailyData) {
+            const { weightedPnlSum, totalInvested } = this.dailyData[userId];
+
+            // Calculate the final weighted average % return for the day
+            // We cap totalInvested at 1.0 (100%) in case of data issues
+            const totalWeight = Math.min(1.0, totalInvested);
+            const dailyAvgPnl = (totalWeight > 0) ? (weightedPnlSum / totalWeight) : 0;
+
+            // Store this for the profile calc dependency
+            dailyPnlMap[userId] = dailyAvgPnl;
+
+            // --- Now, update the sharded history ---
             const shardIndex = parseInt(userId, 10) % NUM_SHARDS;
             const userHistory = existingData[shardIndex][userId] || [];
             
-            userHistory.push({ date: today, pnl: this.dailyProfits[userId] });
+            // Store the decimal % pnl in the history
+            userHistory.push({ date: today, pnl: dailyAvgPnl }); 
             
-            // Ensure we only keep the last 7 days of data
-            results[`user_profitability_shard_${shardIndex}`][userId] = userHistory.slice(-7);
+            const shardKey = `user_profitability_shard_${shardIndex}`;
+            if (!results[shardKey]) results[shardKey] = {};
+            results[shardKey][userId] = userHistory.slice(-7);
         }
 
-        return { sharded_user_profitability: results };
+        return {
+            sharded_user_profitability: results,
+            daily_pnl_map: dailyPnlMap // <-- This now correctly outputs the weighted avg % PNL
+        };
+    }
+
+    reset() {
+        this.dailyData = {};
     }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aiden-shared-calculations-unified",
-  "version": "1.0.16",
+  "version": "1.0.18",
   "description": "Shared calculation modules for the BullTrackers Computation System.",
   "main": "index.js",
   "files": [