aiden-shared-calculations-unified 1.0.46 → 1.0.48

package/calculations/meta/smart_dumb_divergence_index_v2.js

@@ -0,0 +1,127 @@
+/**
+ * @fileoverview Meta-calculation (Pass 4) that correlates the asset/sector flow
+ * of the "Smart Cohort" vs. the "Dumb Cohort" to find divergence signals.
+ *
+ * --- META REFACTOR (v2) ---
+ * This calculation is now stateless. It declares its dependencies and
+ * expects them to be passed to its `process` method.
+ */
+
+class SmartDumbDivergenceIndex {
+
+    /**
+     * (NEW) Statically declare dependencies.
+     */
+    static getDependencies() {
+        return ['positive-expectancy-cohort-flow', 'negative-expectancy-cohort-flow'];
+    }
+
+    constructor() {
+        // Minimum net flow (as a percentage) to be considered a signal
+        this.FLOW_THRESHOLD = 0.005; // Formerly 0.5
+    }
+
+    /**
+     * 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).
+     * @param {object} config The computation system configuration.
+     * @param {object} fetchedDependencies In-memory results from previous passes.
+     * e.g., { 'smart-cohort-flow': ..., 'dumb-cohort-flow': ... }
+     * @returns {Promise<object|null>} The analysis result or null.
+     */
+    async process(dateStr, dependencies, config, fetchedDependencies) {
+    const { logger } = dependencies;
+
+        // 1. Get dependencies from the new argument
+        const smartData = fetchedDependencies['positive-expectancy-cohort-flow'];
+        const dumbData = fetchedDependencies['negative-expectancy-cohort-flow'];
+        
+        // 2. Handle missing dependencies
+        if (!smartData || !dumbData) {
+            logger.log('WARN', `[SmartDumbDivergence] Missing cohort flow data dependency for ${dateStr}. Skipping.`);
+            return null;
+        }
+        
+        const results = {
+            assets: {},
+            sectors: {}
+        };
+        
+        const smartAssetFlow = smartData.asset_flow;
+        const dumbAssetFlow = dumbData.asset_flow;
+        const smartSectorFlow = smartData.sector_rotation;
+        const dumbSectorFlow = dumbData.sector_rotation;
+
+        if (!smartAssetFlow || !dumbAssetFlow || !smartSectorFlow || !dumbSectorFlow) {
+             logger.log('WARN', `[SmartDumbDivergence] Dependency data for ${dateStr} is incomplete (missing asset_flow or sector_rotation). Skipping.`);
+            return null;
+        }
+
+        // 3. 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
+                };
+            }
+        }
+        
+        // 4. Correlate Sectors
+        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-predictive-regime-state.js

@@ -0,0 +1,181 @@
+/**
+ * @fileoverview NEW CALCULATION (PASS 4 - META)
+ * This is the "Quant Regime Engine" or "Master Switch."
+ *
+ * It determines if the entire class of "social-to-price" signals
+ * is currently effective ("ON") or not ("OFF").
+ *
+ * It is a STATEFUL, ROLLING calculation.
+ * 1. It consumes the 'daily_topic_signals' from Pass 3 for the current day.
+ * 2. It reads its *own* rolling history of past "breadth" metrics
+ * from a single document in Firestore ('social_prediction_regime_state/history').
+ * 3. It calculates the "predictive breadth" for the current day:
+ * (What % of all topics analyzed had a Predictive Potential > threshold?)
+ * 4. It appends this new breadth metric to its history.
+ * 5. It calculates a short-term and long-term EMA of this breadth metric.
+ * 6. It uses the EMA crossover to determine the `regime_state`.
+ * 7. It returns its updated state AND the daily regime signal.
+ */
+
+const { FieldValue } = require('@google-cloud/firestore');
+
+// --- CONFIGURATION ---
+// The single doc where this calc stores its rolling history
+const STATE_DOC_PATH = 'social_prediction_regime_state/history'; 
+const ROLLING_HISTORY_DAYS = 90; // History for EMAs
+const EMA_SHORT_PERIOD = 3;  // 3-day EMA
+const EMA_LONG_PERIOD = 14; // 14-day EMA
+// How far apart the EMAs must be to declare a firm regime
+const REGIME_THRESHOLD = 0.02; // e.g., 2% difference
+// The Predictive Potential (from Pass 3) threshold to be counted
+const PP_THRESHOLD = 0.5; 
+
+// --- STATS HELPER ---
+/**
+ * Calculates a simple Exponential Moving Average (EMA) from an array of values.
+ * @param {number[]} data - Array of numbers (oldest to newest).
+ * @param {number} period - The EMA period.
+ * @returns {number|null} The final EMA value, or null if not enough data.
+ */
+function _calculateEMA(data, period) {
+    if (data.length < period) {
+        return null;
+    }
+    const k = 2 / (period + 1); // Smoothing factor
+    let ema = data[0]; // Start with the first value
+    for (let i = 1; i < data.length; i++) {
+        ema = (data[i] * k) + (ema * (1 - k));
+    }
+    return ema;
+}
+
+
+class SocialPredictiveRegimeState {
+
+    static getDependencies() {
+        // Depends on the *daily output* from Pass 3
+        return ['social-topic-predictive-potential'];
+    }
+
+    constructor() {}
+
+    /**
+     * @param {string} dateStr The date to run the analysis for (e.g., "2025-11-06").
+     * @param {object} dependencies The shared dependencies (db, logger).
+     * @param {object} config The computation system configuration.
+     * @param {object} fetchedDependencies In-memory results from Pass 3.
+     * @returns {Promise<object|null>} The analysis result or null.
+     */
+    async process(dateStr, dependencies, config, fetchedDependencies) {
+        const { db, logger } = dependencies;
+        
+        // 1. Get Pass 3 Dependency
+        const pass3_output = fetchedDependencies['social-topic-predictive-potential'];
+        if (!pass3_output || !pass3_output.daily_topic_signals) {
+            logger.log('WARN', `[SocialRegime] Missing or empty dependency 'social-topic-predictive-potential' for ${dateStr}. Skipping.`);
+            return null;
+        }
+        const daily_signals = pass3_output.daily_topic_signals;
+
+        // 2. Calculate Today's "Predictive Breadth"
+        let totalTopicsAnalyzed = 0;
+        let totalPredictiveTopics = 0;
+
+        for (const ticker in daily_signals) {
+            const allTopics = [
+                ...(daily_signals[ticker].topPredictiveBullishTopics || []),
+                ...(daily_signals[ticker].topPredictiveBearishTopics || [])
+            ];
+            
+            for (const topic of allTopics) {
+                totalTopicsAnalyzed++;
+                // Check if this topic is "predictive"
+                if (topic.predictivePotential > PP_THRESHOLD) {
+                    // Check if it has at least one stable window
+                    const hasStableWindow = Object.values(topic.correlations).some(
+                        corr => corr.samples >= MIN_SAMPLE_COUNT && Math.abs(corr.value) > CORR_THRESHOLD
+                    );
+                    if (hasStableWindow) {
+                        totalPredictiveTopics++;
+                    }
+                }
+            }
+        }
+        
+        const todayBreadth = (totalTopicsAnalyzed > 0)
+            ? (totalPredictiveTopics / totalTopicsAnalyzed)
+            : 0; // 0% breadth if no topics found
+
+        // 3. Load State, Update, and Save (all in one transaction)
+        
+        let dailyOutput = {}; // The daily signal for the API
+        let stateToSave = {}; // The new state to save back to Firestore
+
+        try {
+            await db.runTransaction(async (transaction) => {
+                const docRef = db.doc(STATE_DOC_PATH);
+                const doc = await transaction.get(docRef);
+                
+                // 4a. Load and update history
+                const history = doc.exists ? (doc.data().history || []) : [];
+                history.push({ date: dateStr, breadth: todayBreadth });
+                
+                // 4b. Prune history
+                const prunedHistory = history.slice(-ROLLING_HISTORY_DAYS);
+                
+                // 4c. Calculate EMAs
+                const breadthValues = prunedHistory.map(h => h.breadth);
+                const emaShort = _calculateEMA(breadthValues, EMA_SHORT_PERIOD);
+                const emaLong = _calculateEMA(breadthValues, EMA_LONG_PERIOD);
+
+                // 4d. Determine Regime State
+                let regimeState = "TRANSITIONING";
+                if (emaShort !== null && emaLong !== null) {
+                    const diff = emaShort - emaLong;
+                    if (diff > REGIME_THRESHOLD) {
+                        regimeState = "ON";
+                    } else if (diff < -REGIME_THRESHOLD) {
+                        regimeState = "OFF";
+                    }
+                }
+                
+                // 4e. Prepare data to save and return
+                stateToSave = { 
+                    history: prunedHistory,
+                    lastUpdated: FieldValue.serverTimestamp()
+                };
+                
+                dailyOutput = {
+                    social_predictive_regime_strength: emaShort, // The "fast" signal
+                    regime_state: regimeState,
+                    components: {
+                        today_breadth_pct: todayBreadth,
+                        ema_short: emaShort,
+                        ema_long: emaLong,
+                        threshold: REGIME_THRESHOLD
+                    }
+                };
+                
+                // 4f. Save state back to Firestore
+                transaction.set(docRef, stateToSave);
+            });
+            
+        } catch (error) {
+            logger.log('ERROR', `[SocialRegime] Transaction failed for ${dateStr}`, { err: error.message });
+            return null; // Don't return partial data
+        }
+
+        // 5. Return both state (for sharding) and daily signal (for API)
+        return {
+            // This key name must be unique
+            sharded_regime_state: { [STATE_DOC_PATH]: stateToSave }, 
+            // This is the daily result for unified_insights
+            daily_regime_signal: dailyOutput
+        };
+    }
+
+    async getResult() { return null; } // Logic is in process()
+    reset() {}
+}
+
+module.exports = SocialPredictiveRegimeState;

package/calculations/meta/social-topic-driver-index.js

@@ -0,0 +1,153 @@
+/**
+ * @fileoverview NEW CALCULATION (PASS 2 - META)
+ * This is the advanced signal calculation. It consumes the
+ * 'social-topic-sentiment-matrix' from Pass 1, loads the
+ * daily price change for each asset, and then determines
+ * the primary bullish and bearish topics driving the conversation.
+ */
+
+// We need calculation utils to load price and mapping data
+const { loadAllPriceData, getDailyPriceChange } = require('../../utils/price_data_provider');
+const { loadInstrumentMappings } = require('../../utils/sector_mapping_provider');
+
+class SocialTopicDriverIndex {
+
+    /**
+     * Statically declare dependencies.
+     * This will run in Pass 2, after the matrix is built.
+     */
+    static getDependencies() {
+        return ['social-topic-sentiment-matrix'];
+    }
+
+    constructor() {
+        this.priceMap = null;
+        this.tickerToIdMap = null; // For { "AAPL" -> 123 }
+        this.dependenciesLoaded = false;
+    }
+
+    /**
+     * Helper to load price/mapping data on the first run.
+     */
+    async _loadDependencies(calculationUtils) {
+        if (this.dependenciesLoaded) return;
+        
+        const [priceData, mappings] = await Promise.all([
+            calculationUtils.loadAllPriceData(),
+            calculationUtils.loadInstrumentMappings()
+        ]);
+        
+        this.priceMap = priceData;
+        
+        // Create the Ticker -> InstrumentID map
+        this.tickerToIdMap = {};
+        if (mappings && mappings.instrumentToTicker) {
+            for (const [id, ticker] of Object.entries(mappings.instrumentToTicker)) {
+                this.tickerToIdMap[ticker] = id;
+            }
+        }
+        
+        this.dependenciesLoaded = true;
+    }
+
+    /**
+     * Helper to get the previous day's date string.
+     */
+    _getYesterday(dateStr) {
+        const date = new Date(dateStr + 'T00:00:00Z');
+        date.setUTCDate(date.getUTCDate() - 1);
+        return date.toISOString().slice(0, 10);
+    }
+
+    /**
+     * @param {string} dateStr The date to run the analysis for (e.g., "2025-11-05").
+     * @param {object} dependencies The shared dependencies (db, logger, calculationUtils).
+     * @param {object} config The computation system configuration.
+     * @param {object} fetchedDependencies In-memory results from Pass 1.
+     * e.g., { 'social-topic-sentiment-matrix': { "AAPL": { ... } } }
+     * @returns {Promise<object|null>} The analysis result or null.
+     */
+    async process(dateStr, dependencies, config, fetchedDependencies) {
+        const { logger, calculationUtils } = dependencies;
+
+        // 1. Load dependencies
+        await this._loadDependencies(calculationUtils);
+        const matrix = fetchedDependencies['social-topic-sentiment-matrix'];
+
+        if (!matrix || Object.keys(matrix).length === 0) {
+            logger.log('WARN', `[SocialTopicDriverIndex] Missing or empty dependency 'social-topic-sentiment-matrix' for ${dateStr}. Skipping.`);
+            return null;
+        }
+
+        if (!this.priceMap || !this.tickerToIdMap) {
+            logger.log('ERROR', `[SocialTopicDriverIndex] Price map or Ticker map failed to load. Aborting.`);
+            return null;
+        }
+
+        const yesterdayStr = this._getYesterday(dateStr); // e.g., "2025-11-04"
+        const finalResults = {};
+
+        // 2. Correlate for each ticker
+        for (const ticker in matrix) {
+            const topicData = matrix[ticker];
+            const instrumentId = this.tickerToIdMap[ticker];
+
+            if (!instrumentId) {
+                logger.log('TRACE', `[SocialTopicDriverIndex] Skipping ${ticker}, no instrumentId found.`);
+                continue;
+            }
+
+            // 3. Get Price Change
+            // This correctly uses the resilient _findPreviousAvailablePrice helper
+            const priceChangePct = getDailyPriceChange(instrumentId, yesterdayStr, dateStr, this.priceMap);
+
+            if (priceChangePct === null) {
+                logger.log('TRACE', `[SocialTopicDriverIndex] Skipping ${ticker}, no price data found for ${dateStr}.`);
+                continue; // Skip if we can't get price data
+            }
+
+            // 4. Analyze topics for this ticker
+            const topicDrivers = [];
+            for (const topic in topicData) {
+                const data = topicData[topic];
+                const totalSentientPosts = data.bullishPosts + data.bearishPosts;
+                
+                let sentimentScore = 0;
+                if (totalSentientPosts > 0) {
+                    sentimentScore = (data.bullishPosts - data.bearishPosts) / totalSentientPosts;
+                }
+
+                topicDrivers.push({
+                    topic: topic,
+                    sentimentScore: sentimentScore, // -1 (Bearish) to +1 (Bullish)
+                    convictionScore: data.convictionScore,
+                    totalPosts: data.totalPosts,
+                    bullishPosts: data.bullishPosts,
+                    bearishPosts: data.bearishPosts
+                });
+            }
+
+            // 5. Find top drivers by conviction
+            // Sort by most conviction (likes/comments)
+            topicDrivers.sort((a, b) => b.convictionScore - a.convictionScore);
+            
+            // Find the most-discussed bullish and bearish topics
+            const topBullishDriver = topicDrivers.find(d => d.sentimentScore > 0.1) || null;
+            const topBearishDriver = topicDrivers.find(d => d.sentimentScore < -0.1) || null;
+
+            finalResults[ticker] = {
+                priceChangePct: priceChangePct,
+                topBullishDriver: topBullishDriver,
+                topBearishDriver: topBearishDriver,
+                allDrivers: topicDrivers // Store all for potential future analysis
+            };
+        }
+
+        return finalResults;
+    }
+
+    async getResult() { return null; } // This is a meta-calc, logic is in process()
+    reset() {}
+}
+
+module.exports = SocialTopicDriverIndex;