aiden-shared-calculations-unified 1.0.64 → 1.0.65

package/calculations/meta/social-predictive-regime-state.js

@@ -1,181 +1,102 @@
 /**
- * @fileoverview NEW CALCULATION (PASS 4 - META)
- * This is the "Quant Regime Engine" or "Master Switch."
+ * @fileoverview Calculation (Pass 5) for social predictive regime.
  *
- * It determines if the entire class of "social-to-price" signals
- * is currently effective ("ON") or not ("OFF").
+ * This metric answers: "Are we in a 'social-driven' or 'flow-driven'
+ * market regime?"
  *
- * 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.
+ * It *depends* on 'social_flow_correlation' (Pass 4) to make
+ * a determination.
  */
-
-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));
+class SocialPredictiveRegimeState {
+    constructor() {
+        // No per-user processing
     }
-    return ema;
-}
 
+    /**
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
+     */
+    static getSchema() {
+        return {
+            "type": "object",
+            "description": "Determines if the market is in a 'social-driven' or 'flow-driven' regime based on correlation.",
+            "properties": {
+                "regime": {
+                    "type": "string",
+                    "enum": ["Social-Driven", "Flow-Driven", "Decoupled", "Unknown"],
+                    "description": "The current market regime."
+                },
+                "average_correlation": {
+                    "type": "number",
+                    "description": "The average correlation value across all assets from 'social_flow_correlation'."
+                },
+                "correlated_assets_count": {
+                    "type": "number",
+                    "description": "Number of assets with a strong positive correlation."
+                },
+                "decoupled_assets_count": {
+                    "type": "number",
+                    "description": "Number of assets with a weak or negative correlation."
+                }
+            },
+            "required": ["regime", "average_correlation", "correlated_assets_count", "decoupled_assets_count"]
+        };
+    }
 
-class SocialPredictiveRegimeState {
-
+    /**
+     * Statically declare dependencies.
+     */
     static getDependencies() {
-        // Depends on the *daily output* from Pass 3
-        return ['social-topic-predictive-potential'];
+        return [
+            'social_flow_correlation' // Pass 4
+        ];
     }
 
-    constructor() {}
+    process() {
+        // No-op
+    }
 
-    /**
-     * @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;
+    getResult(fetchedDependencies) {
+        const correlationData = fetchedDependencies['social_flow_correlation'];
 
-        // 2. Calculate Today's "Predictive Breadth"
-        let totalTopicsAnalyzed = 0;
-        let totalPredictiveTopics = 0;
+        const defaults = {
+            regime: "Unknown",
+            average_correlation: 0,
+            correlated_assets_count: 0,
+            decoupled_assets_count: 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++;
-                    }
-                }
-            }
+        if (!correlationData) {
+            return defaults;
         }
         
-        const todayBreadth = (totalTopicsAnalyzed > 0)
-            ? (totalPredictiveTopics / totalTopicsAnalyzed)
-            : 0; // 0% breadth if no topics found
+        const correlations = Object.values(correlationData).map(d => d.correlation_30d).filter(c => c !== null);
+        if (correlations.length === 0) {
+            return defaults;
+        }
 
-        // 3. Load State, Update, and Save (all in one transaction)
+        const avgCorrelation = correlations.reduce((a, b) => a + b, 0) / correlations.length;
+        const correlatedCount = correlations.filter(c => c > 0.5).length;
+        const decoupledCount = correlations.filter(c => c <= 0.5).length;
         
-        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
+        let regime = "Decoupled";
+        if (avgCorrelation > 0.5 && correlatedCount > decoupledCount) {
+            regime = "Social-Driven";
+        } else if (avgCorrelation < 0.2) {
+            regime = "Flow-Driven"; // Social is not predictive, flow is
         }
 
-        // 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
+            regime: regime,
+            average_correlation: avgCorrelation,
+            correlated_assets_count: correlatedCount,
+            decoupled_assets_count: decoupledCount
         };
     }
 
-    async getResult() { return null; } // Logic is in process()
-    reset() {}
+    reset() {
+        // No state
+    }
 }
 
 module.exports = SocialPredictiveRegimeState;

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

@@ -1,153 +1,100 @@
 /**
- * @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.
+ * @fileoverview Calculation (Pass 5) for social topic driver index.
+ *
+ * This metric answers: "Which social media topics are driving
+ * the most asset price movement or capital flow?"
+ *
+ * It *depends* on 'social-topic-predictive-potential' (Pass 5).
  */
-
-// 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;
+        // No per-user processing
     }
 
     /**
-     * Helper to load price/mapping data on the first run.
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
      */
-    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;
+    static getSchema() {
+        const topicSchema = {
+            "type": "object",
+            "properties": {
+                "topic": { "type": "string" },
+                "driver_score": { "type": "number" },
+                "correlation_flow_30d": { "type": "number" },
+                "correlation_price_30d": { "type": "number" }
+            },
+            "required": ["topic", "driver_score"]
+        };
+
+        return {
+            "type": "object",
+            "description": "Ranks social media topics by their 'driver_score' (predictive potential for flow and price).",
+            "properties": {
+                "top_driving_topics": {
+                    "type": "array",
+                    "description": "Top 5 topics driving market activity.",
+                    "items": topicSchema
+                },
+                "all_topics": {
+                    "type": "array",
+                    "description": "Full list of all topics and their driver scores.",
+                    "items": topicSchema
+                }
+            },
+            "required": ["top_driving_topics", "all_topics"]
+        };
     }
 
     /**
-     * Helper to get the previous day's date string.
+     * Statically declare dependencies.
      */
-    _getYesterday(dateStr) {
-        const date = new Date(dateStr + 'T00:00:00Z');
-        date.setUTCDate(date.getUTCDate() - 1);
-        return date.toISOString().slice(0, 10);
+    static getDependencies() {
+        return [
+            'social-topic-predictive-potential' // Pass 5
+        ];
     }
 
-    /**
-     * @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'];
+    process() {
+        // No-op
+    }
 
-        if (!matrix || Object.keys(matrix).length === 0) {
-            logger.log('WARN', `[SocialTopicDriverIndex] Missing or empty dependency 'social-topic-sentiment-matrix' for ${dateStr}. Skipping.`);
-            return null;
-        }
+    getResult(fetchedDependencies) {
+        const potentialData = fetchedDependencies['social-topic-predictive-potential'];
+        
+        const defaults = {
+            top_driving_topics: [],
+            all_topics: []
+        };
 
-        if (!this.priceMap || !this.tickerToIdMap) {
-            logger.log('ERROR', `[SocialTopicDriverIndex] Price map or Ticker map failed to load. Aborting.`);
-            return null;
+        if (!potentialData) {
+            return defaults;
         }
 
-        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);
+        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);
             
-            // 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
-            };
+            allTopics.push({
+                topic: topic,
+                driver_score: score,
+                correlation_flow_30d: data.correlation_flow_30d,
+                correlation_price_30d: data.correlation_price_30d
+            });
         }
+        
+        allTopics.sort((a, b) => b.driver_score - a.driver_score);
 
-        return finalResults;
+        return {
+            top_driving_topics: allTopics.slice(0, 5),
+            all_topics: allTopics
+        };
     }
 
-    async getResult() { return null; } // This is a meta-calc, logic is in process()
-    reset() {}
+    reset() {
+        // No state
+    }
 }
 
 module.exports = SocialTopicDriverIndex;

package/calculations/meta/user_expectancy_score.js

@@ -1,54 +1,106 @@
 /**
- * @fileoverview Pass 2: Calculates the "Expectancy Score" for each user
- * based on their historical trading performance.
- * Expectancy = (WinRatio * AvgProfitPct) + (LossRatio * AvgLossPct)
+ * @fileoverview Calculation (Pass 3) for user expectancy score.
+ *
+ * This metric calculates a "trader expectancy score" for each user.
+ * Expectancy = (Win % * Avg Win Size) - (Loss % * Avg Loss Size)
+ *
+ * It *depends* on 'user_profitability_tracker' to get the
+ * historical win/loss data for each user.
  */
 class UserExpectancyScore {
+    constructor() {
+        // No per-user processing
+    }
+
+    /**
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
+     */
+    static getSchema() {
+        const userSchema = {
+            "type": "object",
+            "properties": {
+                "expectancy_score": {
+                    "type": "number",
+                    "description": "Trader expectancy score: (Win % * Avg Win) - (Loss % * Avg Loss). Measures P&L per trade."
+                },
+                "win_rate_pct": { "type": "number" },
+                "avg_win_pct": { "type": "number" },
+                "loss_rate_pct": { "type": "number" },
+                "avg_loss_pct": { "type": "number" },
+                "total_days_processed": { "type": "number" }
+            },
+            "required": ["expectancy_score", "win_rate_pct", "avg_win_pct", "loss_rate_pct", "avg_loss_pct"]
+        };
+
+        return {
+            "type": "object",
+            "description": "Calculates a 'trader expectancy score' for each user based on their 7-day P&L history.",
+            "patternProperties": {
+                "^.*$": userSchema // UserID
+            },
+            "additionalProperties": userSchema
+        };
+    }
 
+    /**
+     * Statically declare dependencies.
+     */
     static getDependencies() {
-        // Depends on our new Pass 1 calculation
-        return ['historical-performance-aggregator'];
+        return [
+            'user_profitability_tracker' // Pass 2
+        ];
     }
 
-    constructor() {}
+    process() {
+        // No-op
+    }
 
-    async process(dateStr, dependencies, config, fetchedDependencies) {
-        const { logger } = dependencies;
-        const performanceData = fetchedDependencies['historical-performance-aggregator'];
+    getResult(fetchedDependencies) {
+        const profitabilityData = fetchedDependencies['user_profitability_tracker']?.user_details;
 
-        if (!performanceData) {
-            logger.log('WARN', `[UserExpectancyScore] Missing dependency 'historical-performance-aggregator' for ${dateStr}. Skipping.`);
-            return null;
+        if (!profitabilityData) {
+            return {};
         }
 
-        const expectancyScores = {};
-
-        for (const userId in performanceData) {
-            const stats = performanceData[userId];
+        const result = {};
 
-            // Ensure we have all the data needed
-            if (typeof stats.winRatio !== 'number' || typeof stats.avgProfitPct !== 'number' || typeof stats.avgLossPct !== 'number') {
-                continue;
-            }
+        for (const [userId, data] of Object.entries(profitabilityData)) {
+            const history = data.pnl_history_7d || [];
+            if (history.length === 0) continue;
+            
+            const wins = history.filter(pnl => pnl > 0);
+            const losses = history.filter(pnl => pnl < 0);
+            const totalTrades = history.length;
 
-            const winRatio = stats.winRatio / 100.0;
-            const lossRatio = 1.0 - winRatio;
+            if (totalTrades === 0) continue;
 
-            // Expectancy formula
-            const expectancy = (winRatio * stats.avgProfitPct) + (lossRatio * stats.avgLossPct);
+            const winRate = (wins.length / totalTrades);
+            const lossRate = (losses.length / totalTrades);
 
-            expectancyScores[userId] = {
+            const avgWin = (wins.length > 0) ? (wins.reduce((a, b) => a + b, 0) / wins.length) : 0;
+            // AvgLoss should be a positive number
+            const avgLoss = (losses.length > 0) ? (Math.abs(losses.reduce((a, b) => a + b, 0)) / losses.length) : 0;
+            
+            // Expectancy = (Win % * Avg Win) - (Loss % * Avg Loss)
+            const expectancy = (winRate * avgWin) - (lossRate * avgLoss);
+            
+            result[userId] = {
                 expectancy_score: expectancy,
-                winRatio: stats.winRatio, // Pass through for debugging/filtering
-                totalTrades: stats.totalTrades
+                win_rate_pct: winRate * 100,
+                avg_win_pct: avgWin,
+                loss_rate_pct: lossRate * 100,
+                avg_loss_pct: avgLoss,
+                total_days_processed: totalTrades
             };
         }
-
-        return expectancyScores;
+        
+        return result;
     }
 
-    async getResult() { return null; }
-    reset() {}
+    reset() {
+        // No state
+    }
 }
 
 module.exports = UserExpectancyScore;