aiden-shared-calculations-unified 1.0.76 → 1.0.77

package/calculations/helix/herd-consensus-score.js

@@ -0,0 +1,152 @@
+/**
+ * @fileoverview HELIX Product Line (Pass 3)
+ *
+ * This metric answers: "What is the 'Herd Consensus Score' for
+ * each asset?"
+ *
+ * It blends sentiment from three different views of the herd:
+ * 1. The entire Platform (from gem/platform-conviction-divergence)
+ * 2. Our 20k User Sample (from core/sentiment-per-stock)
+ * 3. Social Media (from core/social-sentiment-aggregation)
+ *
+ * The score is normalized from -10 (Extreme Bearish Consensus)
+ * to +10 (Extreme Bullish Consensus).
+ */
+class HerdConsensusScore {
+
+    /**
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
+     */
+    static getSchema() {
+        const tickerSchema = {
+            "type": "object",
+            "properties": {
+                "consensus_score": {
+                    "type": "number",
+                    "description": "Blended score (-10 to +10) of platform, sample, and social sentiment."
+                },
+                "platform_sentiment": { "type": "number" },
+                "sample_sentiment": { "type": "number" },
+                "social_sentiment": { "type": "number" }
+            },
+            "required": ["consensus_score"]
+        };
+        
+        return {
+            "type": "object",
+            "description": "Calculates a blended 'Herd Consensus Score' (-10 to +10) per asset.",
+            "patternProperties": {
+                "^.*$": tickerSchema // Ticker
+            },
+            "additionalProperties": tickerSchema
+        };
+    }
+
+    /**
+     * Statically defines all metadata for the manifest builder.
+     */
+    static getMetadata() {
+        return {
+            type: 'meta',
+            rootDataDependencies: [],
+            isHistorical: false,
+            userType: 'n/a',
+            category: 'helix'
+        };
+    }
+
+    /**
+     * Statically declare dependencies.
+     */
+    static getDependencies() {
+        return [
+            // This is the only source of *per-ticker* platform sentiment
+            'platform-conviction-divergence', // from gem
+            'sentiment-per-stock',             // from core
+            'social-sentiment-aggregation'     // from core
+        ];
+    }
+    
+    /**
+     * Normalizes a 0-100 value (like platform_long_pct) to -1.0 to +1.0
+     */
+    _normalizePercent(v) {
+        if (v === null || v === undefined) return 0;
+        const score = (v - 50) / 50; // 50 -> 0, 100 -> 1, 0 -> -1
+        return Math.max(-1, Math.min(1, score));
+    }
+
+    /**
+     * Normalizes a net percent value (-100 to 100) to -1.0 to +1.0
+     */
+    _normalizeNetPercent(v) {
+        if (v === null || v === undefined) return 0;
+        const score = v / 100;
+        return Math.max(-1, Math.min(1, score));
+    }
+    
+    /**
+     * Normalizes a ratio (0 to Inf) to -1.0 to +1.0
+     * 1.0 -> 0.0 (Neutral)
+     * 0.5 -> -1.0 (Bearish)
+     * 2.0 -> +1.0 (Bullish)
+     */
+    _normalizeRatio(v) {
+        if (v === null || v === undefined || v <= 0) return -1.0;
+        const score = Math.log2(v); // log2(1)=0, log2(0.5)=-1, log2(2)=1
+        return Math.max(-1, Math.min(1, score));
+    }
+
+    /**
+     * This is a 'meta' calculation. It runs once.
+     */
+    async process(dateStr, dependencies, config, fetchedDependencies) {
+        const { logger } = dependencies;
+        
+        const platformData = fetchedDependencies['platform-conviction-divergence'];
+        const sampleData = fetchedDependencies['sentiment-per-stock'];
+        const socialData = fetchedDependencies['social-sentiment-aggregation']?.per_ticker;
+
+        if (!platformData || !sampleData || !socialData) {
+            logger.log('WARN', `[helix/herd-consensus-score] Missing dependencies for ${dateStr}. Skipping.`);
+            return {};
+        }
+
+        const allTickers = new Set([
+            ...Object.keys(platformData),
+            ...Object.keys(sampleData),
+            ...Object.keys(socialData)
+        ]);
+        
+        const result = {};
+
+        for (const ticker of allTickers) {
+            // 1. Platform Sentiment (0-100) -> -1 to +1
+            const plat_long_pct = platformData[ticker]?.platform_long_pct;
+            const s_plat = this._normalizePercent(plat_long_pct);
+            
+            // 2. Sample Sentiment (Ratio) -> -1 to +1
+            const sample_ratio = sampleData[ticker]?.sentiment_ratio;
+            const s_samp = this._normalizeRatio(sample_ratio);
+            
+            // 3. Social Sentiment (-100 to 100) -> -1 to +1
+            const social_pct = socialData[ticker]?.net_sentiment_pct;
+            const s_soc = this._normalizeNetPercent(social_pct);
+
+            // Blend scores (equal weight) and scale to -10 to +10
+            const consensus_score = ((s_plat + s_samp + s_soc) / 3) * 10;
+            
+            result[ticker] = {
+                consensus_score: consensus_score,
+                platform_sentiment: s_plat,
+                sample_sentiment: s_samp,
+                social_sentiment: s_soc
+            };
+        }
+        
+        return result;
+    }
+}
+
+module.exports = HerdConsensusScore;

package/calculations/helix/winner-loser-flow.js

@@ -0,0 +1,206 @@
+/**
+ * @fileoverview HELIX Product Line (Pass 2)
+ *
+ * This metric answers: "For each asset, what is the net flow
+ * of *unique users* into the 'Winner' (in-profit) and 'Loser'
+ * (in-loss) cohorts?"
+ *
+ * e.g., "Today, 150 losers capitulated (closed) on AAPL,
+ * while 25 winners joined (opened)."
+ *
+ * This is a 'standard' calc because it must iterate over all
+ * users to compare their T-1 vs T portfolios.
+ */
+const { loadInstrumentMappings } = require('../../../utils/sector_mapping_provider');
+
+class WinnerLoserFlow {
+    constructor() {
+        // We will store { [ticker]: { winners_joined: 0, ... } }
+        this.assetFlows = new Map();
+        this.cohorts = null; // Caches cohort data
+        this.mappings = null; // Caches mappings
+    }
+
+    /**
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
+     */
+    static getSchema() {
+        const tickerSchema = {
+            "type": "object",
+            "properties": {
+                "net_winner_flow": {
+                    "type": "number",
+                    "description": "Net users joining the 'Winner' cohort (Joined - Left)."
+                },
+                "net_loser_flow": {
+                    "type": "number",
+                    "description": "Net users joining the 'Loser' cohort (Joined - Left)."
+                },
+                "raw_counts": {
+                    "type": "object",
+                    "properties": {
+                        "winners_joined": { "type": "number" },
+                        "winners_left": { "type": "number" },
+                        "losers_joined": { "type": "number" },
+                        "losers_left": { "type": "number" }
+                    }
+                }
+            },
+            "required": ["net_winner_flow", "net_loser_flow", "raw_counts"]
+        };
+        
+        return {
+            "type": "object",
+            "description": "Tracks the net flow of unique users into/out of the Winner (in-profit) and Loser (in-loss) cohorts per asset.",
+            "patternProperties": {
+                "^.*$": tickerSchema // Ticker
+            },
+            "additionalProperties": tickerSchema
+        };
+    }
+
+    /**
+     * Statically defines all metadata for the manifest builder.
+     */
+    static getMetadata() {
+        return {
+            type: 'standard',
+            rootDataDependencies: ['portfolio'],
+            isHistorical: true, // Needs T-1 portfolio
+            userType: 'all',
+            category: 'helix'
+        };
+    }
+
+    /**
+     * Statically declare dependencies.
+     */
+    static getDependencies() {
+        return [
+            'asset-pnl-status' // from core
+        ];
+    }
+
+    /**
+     * Helper to load cohort data from the dependency (runs once).
+     */
+    _loadCohorts(fetchedDependencies) {
+        if (this.cohorts) return;
+        
+        const pnlStatusData = fetchedDependencies['asset-pnl-status'];
+        if (!pnlStatusData) {
+            this.cohorts = { winnerMap: new Map(), loserMap: new Map() };
+            return;
+        }
+
+        const winnerMap = new Map();
+        const loserMap = new Map();
+        
+        for (const [ticker, data] of Object.entries(pnlStatusData)) {
+            // 'users_in_profit' and 'users_in_loss' are arrays of user IDs
+            winnerMap.set(ticker, new Set(data.users_in_profit || []));
+            loserMap.set(ticker, new Set(data.users_in_loss || []));
+        }
+        
+        this.cohorts = { winnerMap, loserMap };
+    }
+
+    /**
+     * Helper to get a user's holdings (Instrument IDs)
+     */
+    _getHoldings(portfolio) {
+        const positions = portfolio?.AggregatedPositions || portfolio?.PublicPositions;
+        if (!positions || !Array.isArray(positions)) {
+            return new Set();
+        }
+        return new Set(positions.map(p => p.InstrumentID).filter(Boolean));
+    }
+    
+    /**
+     * Initialize asset flow counters
+     */
+    _initAsset(ticker) {
+        if (!this.assetFlows.has(ticker)) {
+            this.assetFlows.set(ticker, {
+                winners_joined: 0,
+                winners_left: 0,
+                losers_joined: 0,
+                losers_left: 0
+            });
+        }
+    }
+
+    process(todayPortfolio, yesterdayPortfolio, userId, context, todayInsights, yesterdayInsights, fetchedDependencies) {
+        if (!todayPortfolio || !yesterdayPortfolio) {
+            return;
+        }
+
+        // Load mappings and cohort data on the first user
+        if (!this.mappings) {
+            this.mappings = context.mappings;
+        }
+        this._loadCohorts(fetchedDependencies);
+
+        const yHoldings = this._getHoldings(yesterdayPortfolio); // Set<InstrumentID>
+        const tHoldings = this._getHoldings(todayPortfolio); // Set<InstrumentID>
+
+        const allInstrumentIds = new Set([...yHoldings, ...tHoldings]);
+        if (allInstrumentIds.size === 0) {
+            return;
+        }
+
+        for (const instrumentId of allInstrumentIds) {
+            const ticker = this.mappings.instrumentToTicker[instrumentId];
+            if (!ticker) continue;
+            
+            const isWinner = this.cohorts.winnerMap.get(ticker)?.has(userId) || false;
+            const isLoser = this.cohorts.loserMap.get(ticker)?.has(userId) || false;
+            
+            // We only care about users who are *currently* in a cohort
+            if (!isWinner && !isLoser) {
+                continue;
+            }
+
+            const heldYesterday = yHoldings.has(instrumentId);
+            const holdsToday = tHoldings.has(instrumentId);
+
+            // Skip if no change in holding status
+            if (heldYesterday === holdsToday) {
+                continue;
+            }
+
+            this._initAsset(ticker);
+            const stats = this.assetFlows.get(ticker);
+
+            if (isWinner) {
+                if (holdsToday && !heldYesterday) stats.winners_joined++;
+                if (!holdsToday && heldYesterday) stats.winners_left++;
+            }
+            if (isLoser) {
+                if (holdsToday && !heldYesterday) stats.losers_joined++;
+                if (!holdsToday && heldYesterday) stats.losers_left++;
+            }
+        }
+    }
+
+    async getResult() {
+        const result = {};
+        for (const [ticker, data] of this.assetFlows.entries()) {
+            result[ticker] = {
+                net_winner_flow: data.winners_joined - data.winners_left,
+                net_loser_flow: data.losers_joined - data.losers_left,
+                raw_counts: data
+            };
+        }
+        return result;
+    }
+
+    reset() {
+        this.assetFlows.clear();
+        this.cohorts = null;
+        this.mappings = null;
+    }
+}
+
+module.exports = WinnerLoserFlow;

package/calculations/{behavioural/historical → legacy}/asset_crowd_flow.js

@@ -7,7 +7,7 @@
  *
  * This isolates true buying/selling pressure from simple value changes.
  */
-const { loadInstrumentMappings } = require('../../../utils/sector_mapping_provider');
+const { loadInstrumentMappings } = require('../../utils/sector_mapping_provider');
 
 class AssetCrowdFlow {
     constructor() {

package/calculations/{sentiment/historical → legacy}/crowd_conviction_score.js

@@ -13,7 +13,7 @@
  * This is a *stateful* calculation that computes a 30-day
  * rolling average of these metrics to build the score.
  */
-const { loadInstrumentMappings } = require('../../../utils/sector_mapping_provider');
+const { loadInstrumentMappings } = require('../../utils/sector_mapping_provider');
 
 class CrowdConvictionScore {
     constructor() {

package/calculations/{activity/historical → legacy}/daily_asset_activity.js

@@ -2,7 +2,7 @@
  * @fileoverview Tracks the flow of unique users opening or closing positions
  * on a per-asset basis. This measures the "focus" of the crowd's activity.
  */
-const { loadInstrumentMappings } = require('../../../utils/sector_mapping_provider');
+const { loadInstrumentMappings } = require('../../utils/sector_mapping_provider');
 
 class DailyAssetActivity {
     constructor() {

package/calculations/{behavioural/historical → legacy}/dumb-cohort-flow.js

@@ -7,7 +7,7 @@
  * This calculation *depends* on 'user_profitability_tracker'
  * to identify the cohort.
  */
-const { loadInstrumentMappings } = require('../../../utils/sector_mapping_provider');
+const { loadInstrumentMappings } = require('../../utils/sector_mapping_provider');
 
 class DumbCohortFlow {
     constructor() {

package/calculations/{behavioural/historical → legacy}/in_loss_asset_crowd_flow.js

@@ -9,7 +9,7 @@
  *
  * This calculation *depends* on 'asset_pnl_status' to identify the cohort.
  */
-const { loadInstrumentMappings } = require('../../../utils/sector_mapping_provider');
+const { loadInstrumentMappings } = require('../../utils/sector_mapping_provider');
 
 class InLossAssetCrowdFlow {
     constructor() {

package/calculations/{behavioural/historical → legacy}/in_profit_asset_crowd_flow.js

@@ -9,7 +9,7 @@
  *
  * This calculation *depends* on 'asset_pnl_status' to identify the cohort.
  */
-const { loadInstrumentMappings } = require('../../../utils/sector_mapping_provider');
+const { loadInstrumentMappings } = require('../../utils/sector_mapping_provider');
 
 class InProfitAssetCrowdFlow {
     constructor() {

package/calculations/{speculators/historical → legacy}/risk_appetite_change.js

@@ -61,9 +61,11 @@ class RiskAppetiteChange {
     process(todayPortfolio, yesterdayPortfolio, userId) {
         // --- FIX ---
         // Add null check to prevent crash on the first day of processing
-        if (!todayPortfolio || !yesterExamplePortfolio || !todayPortfolio.Portfolio || !yesterdayPortfolio.Portfolio) {
+        if (!todayPortfolio || !yesterdayPortfolio || !todayPortfolio.Portfolio || !yesterdayPortfolio.Portfolio) {
             return;
         }
+
+        
         // --- END FIX ---
         
         // 1. Get portfolio snapshots

package/calculations/{sectors/historical → legacy}/sector_rotation.js

@@ -6,7 +6,7 @@
  *
  * This measures which sectors the crowd is rotating into or out of.
  */
-const { loadInstrumentMappings } = require('../../../utils/sector_mapping_provider');
+const { loadInstrumentMappings } = require('../../utils/sector_mapping_provider');
 
 class SectorRotation {
     constructor() {

package/calculations/{behavioural/historical → legacy}/smart-cohort-flow.js

@@ -7,7 +7,7 @@
  * This calculation *depends* on 'user_profitability_tracker'
  * to identify the cohort.
  */
-const { loadInstrumentMappings } = require('../../../utils/sector_mapping_provider');
+const { loadInstrumentMappings } = require('../../utils/sector_mapping_provider');
 
 class SmartCohortFlow {
     constructor() {

package/calculations/{behavioural/historical → legacy}/smart_money_flow.js

@@ -8,7 +8,7 @@
  * This calculation *depends* on 'user_profitability_tracker'
  * to identify the cohort.
  */
-const { loadInstrumentMappings } = require('../../../utils/sector_mapping_provider');
+const { loadInstrumentMappings } = require('../../utils/sector_mapping_provider');
 
 class SmartMoneyFlow {
     constructor() {

package/calculations/{behavioural/historical → legacy}/user-investment-profile.js

@@ -10,8 +10,8 @@
 const { Firestore } = require('@google-cloud/firestore');
 const firestore = new Firestore();
 // NOTE: Corrected relative path for data_loader
-const { loadDataByRefs, getPortfolioPartRefs, loadFullDayMap } = require('../../../../bulltrackers-module/functions/computation-system/utils/data_loader');
-const { loadAllPriceData, getInstrumentSectorMap } = require('../../../utils/price_data_provider');
+const { loadDataByRefs, getPortfolioPartRefs, loadFullDayMap } = require('../../../bulltrackers-module/functions/computation-system/utils/data_loader');
+const { loadAllPriceData, getInstrumentSectorMap } = require('../../utils/price_data_provider');
 
 // Config
 const NUM_SHARDS = 50;

package/calculations/pyro/risk-appetite-index.js

@@ -0,0 +1,153 @@
+/**
+ * @fileoverview PYRO Product Line (Pass 2)
+ *
+ * This metric answers: "For each asset, what is the 'Risk-On'
+ * score from speculators?"
+ *
+ * It combines the average leverage being used with the
+ * average Risk/Reward ratio being set. A high score means
+ * speculators are confident: using high leverage *and*
+ * setting wide R/R targets.
+ */
+class RiskAppetiteIndex {
+
+    /**
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
+     */
+    static getSchema() {
+        const tickerSchema = {
+            "type": "object",
+            "properties": {
+                "risk_appetite_score": {
+                    "type": "number",
+                    "description": "Blended score (0-10) of leverage use and R/R conviction."
+                },
+                "avg_leverage": {
+                    "type": "number",
+                    "description": "Weighted average leverage used on this asset."
+                },
+                "avg_rr_ratio": {
+                    "type": "number",
+                    "description": "Average R/R ratio set on this asset."
+                }
+            },
+            "required": ["risk_appetite_score", "avg_leverage", "avg_rr_ratio"]
+        };
+        
+        return {
+            "type": "object",
+            "description": "Calculates a 'Risk-On' score for speculators per asset.",
+            "patternProperties": {
+                "^.*$": tickerSchema // Ticker
+            },
+            "additionalProperties": tickerSchema
+        };
+    }
+
+    /**
+     * Statically defines all metadata for the manifest builder.
+     */
+    static getMetadata() {
+        return {
+            type: 'meta',
+            rootDataDependencies: [],
+            isHistorical: false,
+            userType: 'n/a',
+            category: 'pyro'
+        };
+    }
+
+    /**
+     * Statically declare dependencies.
+     */
+    static getDependencies() {
+        return [
+            'speculator-leverage-per-asset', // from core
+            'speculator-risk-reward-ratio-per-asset' // from core
+        ];
+    }
+    
+    /**
+     * Helper to calculate weighted average leverage from buckets.
+     * e.g., { "1x": 10, "5x": 5 }
+     */
+    _calculateAvgLeverage(levBuckets) {
+        if (!levBuckets || typeof levBuckets !== 'object') {
+            return 1; // Default to 1x leverage
+        }
+        
+        let totalCount = 0;
+        let weightedSum = 0;
+        
+        for (const [key, count] of Object.entries(levBuckets)) {
+            const leverage = parseInt(key, 10); // "5x" -> 5
+            if (!isNaN(leverage) && count > 0) {
+                totalCount += count;
+                weightedSum += (leverage * count);
+            }
+        }
+        
+        if (totalCount === 0) {
+            return 1; // Default to 1x if no positions
+        }
+        return weightedSum / totalCount;
+    }
+    
+    /**
+     * Simple min-max normalization, clamped 0-1.
+     */
+    _normalize(value, min, max) {
+        const normalized = (value - min) / (max - min);
+        return Math.max(0, Math.min(1, normalized));
+    }
+
+    /**
+     * 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).
+     * @param {object} config - The computation system configuration.
+     * @param {object} fetchedDependencies - Results from Pass 1.
+     * @returns {Promise<object>} The calculation result.
+     */
+    async process(dateStr, dependencies, config, fetchedDependencies) {
+        const { logger } = dependencies;
+        
+        const leverageData = fetchedDependencies['speculator-leverage-per-asset'];
+        const rrData = fetchedDependencies['speculator-risk-reward-ratio-per-asset'];
+
+        if (!leverageData || !rrData) {
+            logger.log('WARN', `[pyro/risk-appetite-index] Missing core dependencies for ${dateStr}. Skipping.`);
+            return {};
+        }
+
+        const allTickers = new Set([
+            ...Object.keys(leverageData),
+            ...Object.keys(rrData)
+        ]);
+        
+        const result = {};
+
+        for (const ticker of allTickers) {
+            const avg_leverage = this._calculateAvgLeverage(leverageData[ticker]);
+            const avg_rr_ratio = rrData[ticker]?.avg_rr_ratio || 0;
+            
+            // Normalize: Leverage from 1x-10x, R/R from 0-5
+            const norm_lev = this._normalize(avg_leverage, 1, 10);
+            const norm_rr = this._normalize(avg_rr_ratio, 0, 5);
+            
+            // Combine scores and scale to 0-10
+            const risk_appetite_score = (norm_lev * 0.6 + norm_rr * 0.4) * 10;
+            
+            result[ticker] = {
+                risk_appetite_score: risk_appetite_score,
+                avg_leverage: avg_leverage,
+                avg_rr_ratio: avg_rr_ratio
+            };
+        }
+        
+        return result;
+    }
+}
+
+module.exports = RiskAppetiteIndex;