aiden-shared-calculations-unified 1.0.11 → 1.0.13

package/calculations/behavioural/asset_crowd_flow.js

@@ -0,0 +1,151 @@
+const { loadAllPriceData, getDailyPriceChange } = require('../../utils/price_data_provider');
+const { loadInstrumentMappings } = require('../../utils/sector_mapping_provider');
+
+/**
+ * @fileoverview Calculates "Net Crowd Flow" for each asset.
+ *
+ * This isolates the change in an asset's average portfolio percentage
+ * that is *not* explained by the asset's own price movement.
+ *
+ * Net Crowd Flow = (Actual % Change) - (Expected % Change from Price Move)
+ *
+ * A positive value means the crowd actively bought (flowed into) the asset.
+ * A negative value means the crowd actively sold (flowed out of) the asset.
+ */
+class AssetCrowdFlow {
+    constructor() {
+        this.asset_values = {}; // Stores { day1_value_sum: 0, day2_value_sum: 0 }
+        this.user_count = 0;
+        this.priceMap = null;
+        this.mappings = null;
+        this.dates = {}; // To store { today: '...', yesterday: '...' }
+    }
+
+    /**
+     * Helper to safely initialize an asset entry.
+     */
+    _initAsset(instrumentId) {
+        if (!this.asset_values[instrumentId]) {
+            this.asset_values[instrumentId] = {
+                day1_value_sum: 0,
+                day2_value_sum: 0
+            };
+        }
+    }
+
+    /**
+     * Helper to sum the 'Value' field from an AggregatedPositions array.
+     */
+    _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;
+            }
+        }
+        return valueMap;
+    }
+
+    process(todayPortfolio, yesterdayPortfolio, userId, context) {
+        // This is a historical calculation, requires both days
+        if (!todayPortfolio || !yesterdayPortfolio || !todayPortfolio.AggregatedPositions || !yesterdayPortfolio.AggregatedPositions) {
+            return;
+        }
+
+        // Capture dates from context on the first run
+        if (!this.dates.today && context.todayDateStr && context.yesterdayDateStr) {
+            this.dates.today = context.todayDateStr;
+            this.dates.yesterday = context.yesterdayDateStr;
+        }
+        
+        const yesterdayValues = this._sumAssetValue(yesterdayPortfolio.AggregatedPositions);
+        const todayValues = this._sumAssetValue(todayPortfolio.AggregatedPositions);
+        
+        // Use a set of all unique instruments held across both days
+        const allInstrumentIds = new Set([
+            ...Object.keys(yesterdayValues),
+            ...Object.keys(todayValues)
+        ]);
+
+        for (const instrumentId of allInstrumentIds) {
+            this._initAsset(instrumentId);
+            this.asset_values[instrumentId].day1_value_sum += (yesterdayValues[instrumentId] || 0);
+            this.asset_values[instrumentId].day2_value_sum += (todayValues[instrumentId] || 0);
+        }
+
+        this.user_count++;
+    }
+
+    async getResult() {
+        if (this.user_count === 0 || !this.dates.today) {
+            return {}; // No users processed or dates not found
+        }
+
+        // Load dependencies (prices and mappings) in parallel
+        if (!this.priceMap || !this.mappings) {
+            const [priceData, mappingData] = await Promise.all([
+                loadAllPriceData(),
+                loadInstrumentMappings()
+            ]);
+            this.priceMap = priceData;
+            this.mappings = mappingData;
+        }
+        
+        const finalResults = {};
+        const todayStr = this.dates.today;
+        const yesterdayStr = this.dates.yesterday;
+
+        for (const instrumentId in this.asset_values) {
+            const ticker = this.mappings.instrumentToTicker[instrumentId] || `id_${instrumentId}`;
+            
+            // 1. Calculate average % values
+            const avg_day1_value = this.asset_values[instrumentId].day1_value_sum / this.user_count;
+            const avg_day2_value = this.asset_values[instrumentId].day2_value_sum / this.user_count;
+            
+            // 2. Get the actual price change
+            const priceChangePct = getDailyPriceChange(instrumentId, yesterdayStr, todayStr, this.priceMap);
+
+            if (priceChangePct === null) {
+                // Cannot calculate if price data is missing for either day
+                finalResults[ticker] = {
+                    net_crowd_flow_pct: 0,
+                    error: "Missing price data for calculation."
+                };
+                continue;
+            }
+
+            // 3. Calculate the expected value (the "price-move" effect)
+            // We use avg_day1_value as the base. The cash flow proxy calculation
+            // uses (avg_value - avg_invested) because it's solving for a different unknown.
+            // Here, we are solving for flow *relative to the asset itself*.
+            const expected_day2_value = avg_day1_value * (1 + priceChangePct);
+
+            // 4. Find the signal (the "crowd-flow" effect)
+            const net_crowd_flow_pct = avg_day2_value - expected_day2_value;
+
+            finalResults[ticker] = {
+                net_crowd_flow_pct: net_crowd_flow_pct,
+                avg_value_day1_pct: avg_day1_value,
+                avg_value_day2_pct: avg_day2_value,
+                expected_value_day2_pct: expected_day2_value,
+                price_change_pct: priceChangePct,
+                user_sample_size: this.user_count
+            };
+        }
+        
+        return finalResults;
+    }
+
+    reset() {
+        this.asset_values = {};
+        this.user_count = 0;
+        this.priceMap = null;
+        this.mappings = null;
+        this.dates = {};
+    }
+}
+
+module.exports = AssetCrowdFlow;

package/calculations/meta/cash-flow-deployment.js

@@ -0,0 +1,145 @@
+const { FieldValue } = require('@google-cloud/firestore');
+
+/**
+ * @fileoverview A "meta-calculation" that analyzes the results of
+ * 'crowd-cash-flow-proxy' and 'asset-crowd-flow' to correlate
+ * deposit events with subsequent asset purchases.
+ */
+class CashFlowDeployment {
+    constructor() {
+        // This calculation is stateless for `process()`, but `getResult()` is not used.
+        // All logic happens in `process()` which returns the result directly.
+        this.lookbackDays = 7; // How many days to look back for a signal
+        this.correlationWindow = 3; // How many days after the signal to track deployment
+        this.depositSignalThreshold = -1.0; // A -1.0% proxy value is a strong deposit signal
+    }
+
+    /**
+     * Helper to get a YYYY-MM-DD string for N days ago.
+     */
+    _getDateStr(baseDate, daysAgo) {
+        const date = new Date(baseDate + 'T00:00:00Z');
+        date.setUTCDate(date.getUTCDate() - daysAgo);
+        return date.toISOString().slice(0, 10);
+    }
+
+    /**
+     * Fetches a single calculation result from Firestore.
+     */
+    async _fetchCalc(db, collection, dateStr, category, computation) {
+        try {
+            const docRef = db.collection(collection).doc(dateStr)
+                             .collection('results').doc(category)
+                             .collection('computations').doc(computation);
+            const doc = await docRef.get();
+            if (!doc.exists) return null;
+            return doc.data();
+        } catch (e) {
+            return null;
+        }
+    }
+
+    /**
+     * This special `process` method is called by the computation orchestrator *after*
+     * all user-data-based calculations are complete.
+     *
+     * @param {string} dateStr - The "current" day being processed (e.g., "2025-10-30").
+     * @param {object} dependencies - The master dependencies object containing { db, logger }.
+     * @param {object} config - The computation system config.
+     * @returns {Promise<object|null>} The final result object for this day, or null.
+     */
+    async process(dateStr, dependencies, config) {
+        const { db, logger } = dependencies;
+        const collection = config.resultsCollection;
+        
+        let depositSignal = null;
+        let depositSignalDay = null;
+
+        // 1. Look back for a deposit signal
+        for (let i = 1; i <= this.lookbackDays; i++) {
+            const checkDate = this._getDateStr(dateStr, i);
+            const flowData = await this._fetchCalc(db, collection, checkDate, 'capital_flow', 'crowd-cash-flow-proxy');
+            
+            if (flowData && flowData.cash_flow_effect_proxy < this.depositSignalThreshold) {
+                depositSignal = flowData;
+                depositSignalDay = checkDate;
+                break; // Found the most recent strong signal
+            }
+        }
+
+        // If no signal was found in the lookback window, stop.
+        if (!depositSignal) {
+            return {
+                status: 'no_signal_found',
+                lookback_days: this.lookbackDays,
+                signal_threshold: this.depositSignalThreshold
+            };
+        }
+
+        // 2. A signal was found. Now, track the "spend" in the following days.
+        const daysSinceSignal = (new Date(dateStr) - new Date(depositSignalDay)) / (1000 * 60 * 60 * 24);
+
+        // Only run this analysis for the N days *after* the signal
+        if (daysSinceSignal <= 0 || daysSinceSignal > this.correlationWindow) {
+            return {
+                status: 'outside_correlation_window',
+                signal_day: depositSignalDay,
+                days_since_signal: daysSinceSignal
+            };
+        }
+
+        // 3. We are INSIDE the correlation window. Let's analyze the deployment.
+        const [cashFlowData, assetFlowData] = await Promise.all([
+            this._fetchCalc(db, collection, dateStr, 'capital_flow', 'crowd-cash-flow-proxy'),
+            this._fetchCalc(db, collection, dateStr, 'behavioural', 'asset-crowd-flow')
+        ]);
+
+        if (!cashFlowData || !assetFlowData) {
+            logger.log('WARN', `[CashFlowDeployment] Missing dependency data for ${dateStr}. Skipping.`);
+            return null; // Missing data, can't run
+        }
+
+        // This is the "spend" (net move from cash to assets) on this day
+        const netSpendPct = cashFlowData.components?.trading_effect || 0;
+        
+        // This is the total deposit signal
+        const netDepositPct = Math.abs(depositSignal.cash_flow_effect_proxy);
+
+        // Filter asset flow to find the top 10 "buys"
+        const topBuys = Object.entries(assetFlowData)
+            .filter(([ticker, data]) => data.net_crowd_flow_pct > 0)
+            .sort(([, a], [, b]) => b.net_crowd_flow_pct - a.net_crowd_flow_pct)
+            .slice(0, 10)
+            .map(([ticker, data]) => ({
+                ticker: ticker,
+                net_flow_pct: data.net_crowd_flow_pct
+            }));
+
+        // 4. Return the final result
+        return {
+            status: 'analysis_complete',
+            analysis_date: dateStr,
+            signal_date: depositSignalDay,
+            days_since_signal: daysSinceSignal,
+            signal_deposit_proxy_pct: netDepositPct,
+            day_net_spend_pct: netSpendPct,
+            // Calculate what percentage of the *total* deposit was spent *today*
+            pct_of_deposit_deployed_today: (netSpendPct / netDepositPct) * 100,
+            top_deployment_assets: topBuys
+        };
+    }
+
+    /**
+     * This calculation is stateless per-run, so getResult is not used.
+     * The orchestrator will call `process` and commit the result directly.
+     */
+    async getResult() {
+        return null;
+    }
+
+    reset() {
+        // Nothing to reset, as state is not carried
+    }
+}
+
+module.exports = CashFlowDeployment;

package/index.js

@@ -13,6 +13,7 @@ const path = require('path');
 // --- Utils (Manually Exported) ---
 const firestoreUtils = require('./utils/firestore_utils');
 const mappingProvider = require('./utils/sector_mapping_provider');
+const priceProvider = require('./utils/price_data_provider'); // <-- ADD THIS
 
 // --- Calculations (Dynamically Loaded) ---
 const calculations = requireAll({
@@ -26,6 +27,7 @@ module.exports = {
     calculations,
     utils: {
         ...firestoreUtils,
-        ...mappingProvider
+        ...mappingProvider,
+        ...priceProvider // <-- ADD THIS
     }
 };

package/package.json

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

package/utils/price_data_provider.js

@@ -0,0 +1,103 @@
+const { Firestore } = require('@google-cloud/firestore');
+const firestore = new Firestore();
+
+// Config
+const PRICE_COLLECTION = 'asset_prices';
+const CACHE_DURATION_MS = 3600000; // 1 hour
+
+// Cache
+let cache = {
+  timestamp: null,
+  priceMap: null, // Will be { instrumentId: { "YYYY-MM-DD": price, ... } }
+};
+
+// In-progress fetch promise
+let fetchPromise = null;
+
+/**
+ * Loads all sharded price data from the `asset_prices` collection.
+ * This is a heavy operation and should be cached.
+ */
+async function loadAllPriceData() {
+  const now = Date.now();
+  if (cache.timestamp && (now - cache.timestamp < CACHE_DURATION_MS)) {
+    return cache.priceMap;
+  }
+
+  if (fetchPromise) {
+    return fetchPromise;
+  }
+
+  fetchPromise = (async () => {
+    console.log('Fetching and caching all asset price data...');
+    const masterPriceMap = {};
+    
+    try {
+      const snapshot = await firestore.collection(PRICE_COLLECTION).get();
+      
+      if (snapshot.empty) {
+        throw new Error(`Price collection '${PRICE_COLLECTION}' is empty.`);
+      }
+
+      // Loop through each shard document (e.g., "shard_0", "shard_1")
+      snapshot.forEach(doc => {
+        const shardData = doc.data();
+        
+        // Loop through each instrumentId in the shard
+        for (const instrumentId in shardData) {
+          // Check if it's a valid instrument entry
+          if (shardData[instrumentId] && shardData[instrumentId].prices) {
+            masterPriceMap[instrumentId] = shardData[instrumentId].prices;
+          }
+        }
+      });
+
+      cache = {
+        timestamp: now,
+        priceMap: masterPriceMap,
+      };
+      
+      console.log(`Successfully cached prices for ${Object.keys(masterPriceMap).length} instruments.`);
+      return masterPriceMap;
+
+    } catch (err) {
+      console.error('CRITICAL: Error loading price data:', err);
+      // On error, return an empty map but don't cache, so a future call can retry.
+      return {};
+    } finally {
+      // Clear the promise so the next call (if cache is stale) triggers a new fetch
+      fetchPromise = null;
+    }
+  })();
+
+  return fetchPromise;
+}
+
+/**
+ * A helper to safely get the price change percentage between two dates.
+ * @param {string} instrumentId - The instrument ID.
+ * @param {string} yesterdayStr - YYYY-MM-DD date string for yesterday.
+ * @param {string} todayStr - YYYY-MM-DD date string for today.
+ * @param {object} priceMap - The master price map from loadAllPriceData().
+ * @returns {number|null} The percentage change (e.g., 0.10 for +10%), or null if data is missing.
+ */
+function getDailyPriceChange(instrumentId, yesterdayStr, todayStr, priceMap) {
+    if (!priceMap || !priceMap[instrumentId]) {
+        return null; // No price data for this instrument
+    }
+    
+    const priceDay1 = priceMap[instrumentId][yesterdayStr];
+    const priceDay2 = priceMap[instrumentId][todayStr];
+
+    if (priceDay1 && priceDay2 && priceDay1 > 0) {
+        return (priceDay2 - priceDay1) / priceDay1;
+    }
+    
+    return null; // Missing one or both dates, or division by zero
+}
+
+
+module.exports = {
+    loadAllPriceData,
+    getDailyPriceChange
+};