aiden-shared-calculations-unified 1.0.71 → 1.0.73

package/calculations/meta/gem_cohort-momentum-state.js

@@ -0,0 +1,110 @@
+/**
+ * @fileoverview Calculation (Pass 3) for cohort momentum state.
+ *
+ * This metric answers: "Are the 'Skilled' and 'Unskilled' cohorts
+ * trend-following or acting as contrarians?"
+ *
+ * It multiplies cohort flow by price momentum.
+ * - High positive score = Buying into a rally (FOMO)
+ * - High negative score = Buying into a dip, or Selling into a rally
+ *
+ * It *depends* on Pass 2 cohort flows and Pass 1 price momentum.
+ */
+class CohortMomentumState {
+    constructor() {
+        // No per-user processing
+    }
+
+    /**
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
+     */
+    static getSchema() {
+        const tickerSchema = {
+            "type": "object",
+            "properties": {
+                "skilled_momentum_score": {
+                    "type": "number",
+                    "description": "Skilled Flow % * 20d Momentum %. High positive = trend-following."
+                },
+                "unskilled_momentum_score": {
+                    "type": "number",
+                    "description": "Unskilled Flow % * 20d Momentum %. High positive = trend-following (FOMO)."
+                },
+                "skilled_flow_pct": { "type": "number" },
+                "unskilled_flow_pct": { "type": "number" },
+                "momentum_20d_pct": { "type": ["number", "null"] }
+            },
+            "required": ["skilled_momentum_score", "unskilled_momentum_score"]
+        };
+
+        return {
+            "type": "object",
+            "description": "Calculates a momentum-following score for Skilled and Unskilled cohorts.",
+            "patternProperties": {
+                "^.*$": tickerSchema // Ticker
+            },
+            "additionalProperties": tickerSchema
+        };
+    }
+
+    /**
+     * Statically declare dependencies.
+     */
+    static getDependencies() {
+        return [
+            'gem_skilled-cohort-flow',       // Pass 2
+            'gem_unskilled-cohort-flow',     // Pass 2
+            'gem_instrument-price-momentum'  // Pass 1
+        ];
+    }
+
+    process() {
+        // No-op
+    }
+
+    /**
+     * This is a 'meta' calculation.
+     * @param {object} fetchedDependencies - Results from previous passes.
+     */
+    getResult(fetchedDependencies) {
+        const skilledFlowData = fetchedDependencies['skilled-cohort-flow']?.assets;
+        const unskilledFlowData = fetchedDependencies['unskilled-cohort-flow']?.assets;
+        const momentumData = fetchedDependencies['instrument-price-momentum'];
+
+        if (!skilledFlowData || !unskilledFlowData || !momentumData) {
+            return {};
+        }
+
+        const result = {};
+        const allTickers = new Set([
+            ...Object.keys(skilledFlowData),
+            ...Object.keys(unskilledFlowData)
+        ]);
+
+        for (const ticker of allTickers) {
+            const sFlow = skilledFlowData[ticker]?.net_flow_percentage || 0;
+            const uFlow = unskilledFlowData[ticker]?.net_flow_percentage || 0;
+            const mom = momentumData[ticker]?.momentum_20d_pct || 0;
+
+            const skilled_momentum_score = sFlow * mom;
+            const unskilled_momentum_score = uFlow * mom;
+            
+            result[ticker] = {
+                skilled_momentum_score: skilled_momentum_score,
+                unskilled_momentum_score: unskilled_momentum_score,
+                skilled_flow_pct: sFlow,
+                unskilled_flow_pct: uFlow,
+                momentum_20d_pct: mom
+            };
+        }
+        
+        return result;
+    }
+
+    reset() {
+        // No state
+    }
+}
+
+module.exports = CohortMomentumState;

package/calculations/meta/gem_instrument-price-momentum.js

@@ -0,0 +1,115 @@
+/**
+ * @fileoverview Calculation (Pass 1 - Meta) for 20-day price momentum.
+ *
+ * This metric answers: "What is the 20-day percentage price change for
+ * every instrument?"
+ *
+ * It is a 'meta' calculation that runs once, loads all price data,
+ * and provides a reusable momentum signal for downstream passes.
+ */
+const { loadAllPriceData } = require('../../utils/price_data_provider');
+
+class InstrumentPriceMomentum {
+
+    /**
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
+     */
+    static getSchema() {
+        const tickerSchema = {
+            "type": "object",
+            "properties": {
+                "momentum_20d_pct": {
+                    "type": ["number", "null"],
+                    "description": "The 20-day rolling price change percentage."
+                }
+            },
+            "required": ["momentum_20d_pct"]
+        };
+        
+        return {
+            "type": "object",
+            "description": "Calculates the 20-day price momentum for all instruments.",
+            "patternProperties": {
+                "^.*$": tickerSchema // Ticker
+            },
+            "additionalProperties": tickerSchema
+        };
+    }
+
+    /**
+     * This is a Pass 1 calculation and has no dependencies.
+     */
+    static getDependencies() {
+        return [];
+    }
+    
+    // Helper to get date string N days ago
+    _getDateStr(baseDateStr, daysOffset) {
+        const date = new Date(baseDateStr + 'T00:00:00Z');
+        date.setUTCDate(date.getUTCDate() + daysOffset);
+        return date.toISOString().slice(0, 10);
+    }
+    
+    // Helper to find the last available price on or before a date
+    _findPrice(priceHistory, dateStr, maxLookback = 5) {
+        if (!priceHistory) return null;
+        let checkDate = new Date(dateStr + 'T00:00:00Z');
+        for (let i = 0; i < maxLookback; i++) {
+            const checkDateStr = checkDate.toISOString().slice(0, 10);
+            const price = priceHistory[checkDateStr];
+            if (price !== undefined && price !== null && price > 0) {
+                return price;
+            }
+            checkDate.setUTCDate(checkDate.getUTCDate() - 1);
+        }
+        return null;
+    }
+
+    /**
+     * This is a 'meta' calculation. It runs once.
+     * @param {string} dateStr - The date string 'YYYY-MM-DD'.
+     * @param {object} dependencies - The shared dependencies (e.g., logger, calculationUtils).
+     * @param {object} config - The computation system configuration.
+     * @param {object} fetchedDependencies - (Unused)
+     * @returns {Promise<object>} The calculation result.
+     */
+    async process(dateStr, dependencies, config, fetchedDependencies) {
+        const { logger, calculationUtils, mappings } = dependencies;
+        
+        // Load all price data and mappings
+        const priceMap = await loadAllPriceData();
+        const tickerMap = await calculationUtils.loadInstrumentMappings();
+        
+        if (!priceMap || !tickerMap || !tickerMap.instrumentToTicker) {
+            logger.log('ERROR', '[instrument-price-momentum] Failed to load priceMap or mappings.');
+            return {};
+        }
+
+        const dateStrT20 = this._getDateStr(dateStr, -20);
+        const result = {};
+
+        for (const instrumentId in priceMap) {
+            const instrumentPrices = priceMap[instrumentId];
+            const ticker = tickerMap.instrumentToTicker[instrumentId];
+            
+            if (!ticker) continue; // Skip if we can't map ID to ticker
+
+            const priceT = this._findPrice(instrumentPrices, dateStr);
+            const priceT20 = this._findPrice(instrumentPrices, dateStrT20);
+
+            let momentum = null;
+            if (priceT && priceT20 && priceT20 > 0) {
+                momentum = ((priceT - priceT20) / priceT20) * 100; // As percentage
+            }
+
+            result[ticker] = {
+                momentum_20d_pct: momentum
+            };
+        }
+        
+        return result;
+    }
+}
+
+module.exports = InstrumentPriceMomentum;

package/calculations/meta/gem_skilled-unskilled-divergence.js

@@ -0,0 +1,139 @@
+/**
+ * @fileoverview Calculation (Pass 3) for skilled-unskilled divergence.
+ *
+ * This metric answers: "What divergence signals (e.g., capitulation,
+ * euphoria) can be found by comparing the net asset and sector flow
+ * of the 'Skilled Cohort' vs. the 'Unskilled Cohort'?"
+ *
+ * It *depends* on 'skilled-cohort-flow' and 'unskilled-cohort-flow'.
+ */
+class SkilledUnskilledDivergence {
+    constructor() {
+        // No per-user processing
+    }
+
+    /**
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
+     */
+    static getSchema() {
+        const signalSchema = {
+            "type": "object",
+            "properties": {
+                "status": {
+                    "type": "string",
+                    "enum": ["Capitulation", "Euphoria", "Confirmation (Buy)", "Confirmation (Sell)", "Divergence (Skilled Buy)", "Divergence (Skilled Sell)", "Neutral"]
+                },
+                "skilled_flow_pct": { "type": "number" },
+                "unskilled_flow_pct": { "type": "number" }
+            },
+            "required": ["status", "skilled_flow_pct", "unskilled_flow_pct"]
+        };
+
+        return {
+            "type": "object",
+            "description": "Generates divergence signals by comparing net flow of 'Skilled' vs. 'Unskilled' cohorts, by asset and sector.",
+            "properties": {
+                "assets": {
+                    "type": "object",
+                    "description": "Divergence signals per asset.",
+                    "patternProperties": { "^.*$": signalSchema }, // Ticker
+                    "additionalProperties": signalSchema
+                },
+                "sectors": {
+                    "type": "object",
+                    "description": "Divergence signals per sector.",
+                    "patternProperties": { "^.*$": signalSchema }, // Sector
+                    "additionalProperties": signalSchema
+                }
+            },
+            "required": ["assets", "sectors"]
+        };
+    }
+
+    /**
+     * Statically declare dependencies.
+     */
+    static getDependencies() {
+        return [
+            'gem_skilled-cohort-flow', // Pass 2
+            'gem_unskilled-cohort-flow'   // Pass 2
+        ];
+    }
+
+    process() {
+        // No-op
+    }
+    
+    _calculateDivergence(skilledFlow, unskilledFlow) {
+        const result = {};
+        if (!skilledFlow || !unskilledFlow) {
+            return result;
+        }
+        
+        const allKeys = new Set([...Object.keys(skilledFlow), ...Object.keys(unskilledFlow)]);
+        const THRESHOLD = 1.0; // Min flow % to register as a signal
+
+        for (const key of allKeys) {
+            const sFlow = skilledFlow[key]?.net_flow_percentage || 0;
+            const dFlow = unskilledFlow[key]?.net_flow_percentage || 0;
+
+            let status = 'Neutral';
+
+            // Both buying
+            if (sFlow > THRESHOLD && dFlow > THRESHOLD) {
+                status = 'Confirmation (Buy)';
+            }
+            // Both selling
+            else if (sFlow < -THRESHOLD && dFlow < -THRESHOLD) {
+                status = 'Confirmation (Sell)';
+            }
+            // Skilled buying, Unskilled selling
+            else if (sFlow > THRESHOLD && dFlow < -THRESHOLD) {
+                status = 'Capitulation'; // Skilled buying the dip from unskilled
+            }
+            // Skilled selling, Unskilled buying
+            else if (sFlow < -THRESHOLD && dFlow > THRESHOLD) {
+                status = 'Euphoria'; // Skilled selling into unskilled fomo
+            }
+            // Skilled buying, Unskilled neutral
+            else if (sFlow > THRESHOLD && Math.abs(dFlow) < THRESHOLD) {
+                status = 'Divergence (Skilled Buy)';
+            }
+            // Skilled selling, Unskilled neutral
+            else if (sFlow < -THRESHOLD && Math.abs(dFlow) < THRESHOLD) {
+                status = 'Divergence (Skilled Sell)';
+            }
+            
+            result[key] = {
+                status: status,
+                skilled_flow_pct: sFlow,
+                unskilled_flow_pct: dFlow
+            };
+        }
+        return result;
+    }
+
+    /**
+     * This is a 'meta' calculation.
+     * @param {object} fetchedDependencies - Results from Pass 2.
+     */
+    getResult(fetchedDependencies) {
+        const skilledFlowData = fetchedDependencies['skilled-cohort-flow'];
+        const unskilledFlowData = fetchedDependencies['unskilled-cohort-flow'];
+
+        const assetResult = this._calculateDivergence(skilledFlowData?.assets, unskilledFlowData?.assets);
+        const sectorResult = this._calculateDivergence(skilledFlowData?.sectors, unskilledFlowData?.sectors);
+
+        return {
+            assets: assetResult,
+            sectors: sectorResult
+        };
+    }
+
+    reset() {
+        // No state
+    }
+}
+
+module.exports = SkilledUnskilledDivergence;

package/calculations/meta/quant-skill-alpha-signal.js

@@ -0,0 +1,152 @@
+/**
+ * @fileoverview Calculation (Pass 4) for the "Quant-Skill Alpha Signal".
+ *
+ * This metric synthesizes multiple Pass 1, 2, and 3 signals into a
+ * single, actionable "raw score" for each asset. It is designed to
+ * be the final, tradable signal from this computation branch.
+ *
+ * It weights:
+ * 1. Skilled/Unskilled Divergence (Pass 3)
+ * 2. Unskilled "FOMO" (from Cohort Momentum, Pass 3)
+ * 3. Platform vs. Sample Divergence (Pass 1)
+ * 4. Social Media Sentiment (Pass 1)
+ */
+class QuantSkillAlphaSignal {
+    constructor() {
+        // Define the weights for the model.
+        // These would be optimized via backtesting.
+        this.W_DIVERGENCE = 0.40; // Skilled vs Unskilled
+        this.W_FOMO = 0.30;       // Unskilled Momentum (faded)
+        this.W_PLATFORM = 0.15;   // Sample vs Platform
+        this.W_SOCIAL = 0.15;   // Social Sentiment
+    }
+
+    /**
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
+     */
+    static getSchema() {
+        const tickerSchema = {
+            "type": "object",
+            "properties": {
+                "raw_alpha_score": {
+                    "type": "number",
+                    "description": "The final weighted signal score. > 0 is bullish, < 0 is bearish."
+                },
+                "signal_status": {
+                    "type": "string",
+                    "description": "A human-readable signal (e.g., 'Strong Buy', 'Neutral')."
+                },
+                "component_divergence_score": { "type": "number" },
+                "component_unskilled_fomo_score": { "type": "number" },
+                "component_platform_divergence_score": { "type": "number" },
+                "component_social_sentiment_score": { "type": "number" }
+            },
+            "required": ["raw_alpha_score", "signal_status"]
+        };
+
+        return {
+            "type": "object",
+            "description": "A final, weighted alpha signal combining skill divergence, momentum, and sentiment.",
+            "patternProperties": {
+                "^.*$": tickerSchema // Ticker
+            },
+            "additionalProperties": tickerSchema
+        };
+    }
+
+    /**
+     * Statically declare dependencies.
+     */
+    static getDependencies() {
+        return [
+            'gem_skilled-unskilled-divergence',    // Pass 3
+            'gem_cohort-momentum-state',         // Pass 3
+            'gem_platform-conviction-divergence',  // Pass 1
+            'gem_social_sentiment_aggregation'     // Pass 1
+        ];
+    }
+
+    process() {
+        // No-op
+    }
+
+    /**
+     * This is a 'meta' calculation.
+     * @param {object} fetchedDependencies - Results from previous passes.
+     */
+    getResult(fetchedDependencies) {
+        const divergenceData = fetchedDependencies['skilled-unskilled-divergence']?.assets;
+        const momentumData = fetchedDependencies['cohort-momentum-state'];
+        const platformData = fetchedDependencies['platform-conviction-divergence'];
+        const socialData = fetchedDependencies['social_sentiment_aggregation']?.per_ticker;
+
+        if (!divergenceData || !momentumData || !platformData || !socialData) {
+            return {}; // Missing one or more key dependencies
+        }
+
+        const result = {};
+        const allTickers = new Set([
+            ...Object.keys(divergenceData),
+            ...Object.keys(momentumData),
+            ...Object.keys(platformData),
+            ...Object.keys(socialData)
+        ]);
+
+        for (const ticker of allTickers) {
+            // 1. Get Divergence Signal (Buy = +1, Sell = -1)
+            const divStatus = divergenceData[ticker]?.status;
+            const divScore = divStatus === 'Capitulation' ? 1.0 : (divStatus === 'Euphoria' ? -1.0 : 0);
+            
+            // 2. Get Unskilled FOMO Signal (We fade this, so we use -1)
+            // 'unskilled_momentum_score' is high positive when they buy a rally
+            const fomoScore = momentumData[ticker]?.unskilled_momentum_score || 0;
+
+            // 3. Get Platform Divergence Signal
+            // 'divergence' is positive when our sample is more bullish than the platform
+            const platformScore = platformData[ticker]?.divergence || 0;
+            
+            // 4. Get Social Sentiment Signal
+            // 'net_sentiment_pct' is positive when social is bullish
+            const socialScore = socialData[ticker]?.net_sentiment_pct || 0;
+
+            // Normalize scores to a similar range (approx -100 to 100)
+            // (This is a simple normalization; a z-score would be more robust)
+            const s_div = divScore * 100.0;
+            const s_fomo = -1 * fomoScore; // Fading the signal
+            const s_plat = platformScore; // Already 0-100
+            const s_soc = socialScore;  // Already 0-100
+
+            // Calculate final weighted score
+            const raw_alpha_score = 
+                (s_div * this.W_DIVERGENCE) +
+                (s_fomo * this.W_FOMO) +
+                (s_plat * this.W_PLATFORM) +
+                (s_soc * this.W_SOCIAL);
+
+            // Determine human-readable status
+            let status = 'Neutral';
+            if (raw_alpha_score > 30) status = 'Strong Buy';
+            else if (raw_alpha_score > 10) status = 'Buy';
+            else if (raw_alpha_score < -30) status = 'Strong Sell';
+            else if (raw_alpha_score < -10) status = 'Sell';
+
+            result[ticker] = {
+                raw_alpha_score: raw_alpha_score,
+                signal_status: status,
+                component_divergence_score: s_div,
+                component_unskilled_fomo_score: s_fomo,
+                component_platform_divergence_score: s_plat,
+                component_social_sentiment_score: s_soc
+            };
+        }
+        
+        return result;
+    }
+
+    reset() {
+        // No state
+    }
+}
+
+module.exports = QuantSkillAlphaSignal;

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

@@ -21,8 +21,10 @@ class SocialTopicDriverIndex {
             "properties": {
                 "topic": { "type": "string" },
                 "driver_score": { "type": "number" },
-                "correlation_flow_30d": { "type": "number" },
-                "correlation_price_30d": { "type": "number" }
+                // These fields are from an older version but kept for schema
+                // compatibility. They will be null in the corrected logic.
+                "correlation_flow_30d": { "type": ["number", "null"] },
+                "correlation_price_30d": { "type": ["number", "null"] }
             },
             "required": ["topic", "driver_score"]
         };
@@ -48,6 +50,7 @@ class SocialTopicDriverIndex {
 
     /**
      * Statically declare dependencies.
+     * (This was already correct)
      */
     static getDependencies() {
         return [
@@ -59,6 +62,13 @@ class SocialTopicDriverIndex {
         // No-op
     }
 
+    /**
+     * --- LOGIC FIXED ---
+     * This function is rewritten to correctly consume the output of
+     * 'social-topic-predictive-potential'. It aggregates the
+     * 'predictivePotential' score for each topic across *all* tickers
+     * to create a global driver score.
+     */
     getResult(fetchedDependencies) {
         const potentialData = fetchedDependencies['social-topic-predictive-potential'];
         
@@ -67,23 +77,60 @@ class SocialTopicDriverIndex {
             all_topics: []
         };
 
-        if (!potentialData) {
+        // The dependency returns a nested object. We need 'daily_topic_signals'.
+        const dailyTopicSignals = potentialData?.daily_topic_signals;
+
+        if (!dailyTopicSignals || Object.keys(dailyTopicSignals).length === 0) {
             return defaults;
         }
 
+        // Use a Map to aggregate scores for each topic
+        const topicAggregator = new Map();
+
+        // Iterate over each TICKER (e.g., 'AAPL', 'TSLA') in the signals
+        for (const tickerData of Object.values(dailyTopicSignals)) {
+            
+            // Combine bullish and bearish topics for that ticker
+            const allTickerTopics = [
+                ...(tickerData.topPredictiveBullishTopics || []),
+                ...(tickerData.topPredictiveBearishTopics || [])
+            ];
+
+            // Iterate over the topics *for that ticker*
+            for (const topicData of allTickerTopics) {
+                const topicName = topicData.topic;
+                
+                // Use the 'predictivePotential' score calculated by the dependency
+                const score = topicData.predictivePotential || 0;
+
+                if (!topicAggregator.has(topicName)) {
+                    topicAggregator.set(topicName, { totalScore: 0, count: 0 });
+                }
+                
+                const agg = topicAggregator.get(topicName);
+                agg.totalScore += score;
+                agg.count += 1;
+            }
+        }
+        
         const allTopics = [];
-        for (const [topic, data] of Object.entries(potentialData)) {
-            // Create a "Driver Score" - prioritize flow correlation
-            const score = (data.correlation_flow_30d * 0.7) + (data.correlation_price_30d * 0.3);
+        // Now, create the final ranked list
+        for (const [topic, data] of topicAggregator.entries()) {
+            if (data.count === 0) continue;
+            
+            // Calculate the average driver score across all tickers
+            const avgScore = data.totalScore / data.count;
             
             allTopics.push({
                 topic: topic,
-                driver_score: score,
-                correlation_flow_30d: data.correlation_flow_30d,
-                correlation_price_30d: data.correlation_price_30d
+                driver_score: avgScore,
+                // Set old/incompatible fields to null to match schema
+                correlation_flow_30d: null, 
+                correlation_price_30d: null 
             });
         }
         
+        // Sort by the new, correct driver_score
         allTopics.sort((a, b) => b.driver_score - a.driver_score);
 
         return {

package/calculations/meta/social-topic-predictive-potential.js

@@ -152,7 +152,8 @@ function _findPriceForward(instrumentId, dateStr, priceMap) {
 class SocialTopicPredictivePotentialIndex {
 
     static getDependencies() {
-        return ['social-topic-driver-index'];
+        // --- FIX 1: Changed from 'social-topic-driver-index' to break the cycle ---
+        return ['social-topic-sentiment-matrix'];
     }
 
     constructor() {
@@ -195,10 +196,13 @@ class SocialTopicPredictivePotentialIndex {
         // pLimit is not in calculationUtils by default, so we'll use our own
         // If it were, we'd use: this.pLimit = calculationUtils.pLimit(MAX_CONCURRENT_TRANSACTIONS);
         await this._loadDependencies(calculationUtils);
-        const todaySignals = fetchedDependencies['social-topic-driver-index'];
+        
+        // --- FIX 2: Read from the correct dependency ---
+        const todaySignals = fetchedDependencies['social-topic-sentiment-matrix'];
 
         if (!todaySignals || Object.keys(todaySignals).length === 0) {
-            logger.log('WARN', `[SocialTopicPredictive] Missing or empty dependency 'social-topic-driver-index' for ${dateStr}. Skipping.`);
+            // --- FIX 2.1: Updated log message ---
+            logger.log('WARN', `[SocialTopicPredictive] Missing or empty dependency 'social-topic-sentiment-matrix' for ${dateStr}. Skipping.`);
             return null;
         }
 
@@ -264,6 +268,8 @@ class SocialTopicPredictivePotentialIndex {
                 this._updateForwardReturns(state, instrumentId, dateStr, todayPrice, this.priceMap);
 
                 // --- 4c. Add New Signals (Factored Helper) ---
+                // We assume 'todaySignal' (from social-topic-sentiment-matrix)
+                // has an 'allDrivers' property.
                 this._addNewSignals(state, todaySignal.allDrivers || [], dateStr);
 
                 // --- 4d. Recalculate Correlations (Factored Helper) ---