aiden-shared-calculations-unified 1.0.86 → 1.0.88

package/calculations/helix/helix-contrarian-signal.js

@@ -1,49 +1,24 @@
 /**
  * @fileoverview HELIX Product Line (Pass 4)
- *
- * This is the final, stateless signal generator for the HELIX line.
- * It answers: "Are 'Winners' (in-profit) and 'Losers'
- * (in-loss) cohorts flowing in opposite directions?"
+ * REFACTORED: Uses context.math.signals and process(context).
  */
 class HelixContrarianSignal {
+    constructor() { this.result = {}; }
 
-    // --- STANDARD 2: ADDED ---
-    constructor() {
-        this.result = {};
-    }
-
-    /**
-     * Defines the output schema for this calculation.
-     */
     static getSchema() {
         const tickerSchema = {
             "type": "object",
             "properties": {
-                "signal": {
-                    "type": "string",
-                    "enum": ["Strong Contrarian", "Contrarian", "Neutral", "Consensus"]
-                },
-                "helix_score": {
-                    "type": "number",
-                    "description": "Divergence score (-10 to +10). Positive = Contrarian (Winners sell, Losers buy), Negative = Consensus (Both buy/sell)."
-                },
+                "signal": { "type": "string" },
+                "helix_score": { "type": "number" },
                 "winner_net_flow": { "type": "number" },
                 "loser_net_flow": { "type": "number" }
             },
-            "required": ["signal", "helix_score", "winner_net_flow", "loser_net_flow"]
-        };
-        
-        return {
-            "type": "object",
-            "description": "Generates a final contrarian signal based on Winner vs. Loser flow.",
-            "patternProperties": { "^.*$": tickerSchema },
-            "additionalProperties": tickerSchema
+            "required": ["signal", "helix_score"]
         };
+        return { "type": "object", "patternProperties": { "^.*$": tickerSchema } };
     }
 
-    /**
-     * Statically defines all metadata for the manifest builder.
-     */
     static getMetadata() {
         return {
             type: 'meta',
@@ -54,109 +29,40 @@ class HelixContrarianSignal {
         };
     }
 
-    /**
-     * Statically declare dependencies.
-     */
     static getDependencies() {
-        return [
-            'winner-loser-flow',     // from helix (Pass 2)
-            'herd-consensus-score'   // from helix (Pass 2)
-        ];
+        return ['winner-loser-flow', 'herd-consensus-score'];
     }
     
-    /**
-     * Simple tanh normalization. Scales any number to a -10 to +10 range.
-     */
-    _normalize(score) {
-        // Scale input score to tune sensitivity
-        // A score of 50 will be ~9.9 (strong signal)
-        // A score of 20 will be ~9.6
-        // A score of 10 will be ~7.6
-        return Math.tanh(score / 10.0) * 10;
-    }
-
-    /**
-     * This is a 'meta' calculation. It runs once.
-     */
-    // --- STANDARD 1: UPDATED SIGNATURE (added rootData) ---
-    async process(dateStr, rootData, dependencies, config, fetchedDependencies) {
-        const { logger } = dependencies;
+    process(context) {
+        const { computed, math } = context;
+        const { signals } = math;
         
-        const cohortFlows = fetchedDependencies['winner-loser-flow'];
-        const herdConviction = fetchedDependencies['herd-consensus-score'];
-
-        if (!cohortFlows || !herdConviction) {
-            logger.log('WARN', `[helix/helix-contrarian-signal] Missing dependencies for ${dateStr}.`);
-            // --- STANDARD 2: DO NOT RETURN ---
-            this.result = {};
-            return;
-        }
-
-        const allTickers = new Set([
-            ...Object.keys(cohortFlows),
-            ...Object.keys(herdConviction)
-        ]);
-
+        const tickers = signals.getUnionKeys(computed, ['winner-loser-flow', 'herd-consensus-score']);
         const result = {};
 
-        for (const ticker of allTickers) {
-            const flow = cohortFlows[ticker];
-            const conviction = herdConviction[ticker];
+        for (const ticker of tickers) {
+            const winner_flow = signals.getMetric(computed, 'winner-loser-flow', ticker, 'net_winner_flow');
+            const loser_flow = signals.getMetric(computed, 'herd-consensus-score', ticker, 'herd_conviction_score');
 
-            // 1. Get Winner Flow (using net_winner_flow)
-            const winner_flow = flow?.net_winner_flow || 0;
-            
-            // 2. Get Loser Flow (using herd_conviction_score)
-            // This is a proxy for "Loser Flow".
-            // If conviction > 0, losers are buying.
-            // If conviction < 0, losers are selling.
-            const loser_flow = conviction?.herd_conviction_score || 0;
-
-            // --- Signal Logic ---
-            // A contrarian signal (positive score) happens when:
-            // 1. Winners SELL (flow < 0) and Losers BUY (flow > 0)
-            //
-            // A consensus signal (negative score) happens when:
-            // 2. Winners BUY (flow > 0) and Losers BUY (flow > 0)
-            // 3. Winners SELL (flow < 0) and Losers SELL (flow < 0)
-            
-            // We can simplify this:
-            // Score = Loser Flow - Winner Flow
-            //
-            // Case 1: Loser (Buy, +50) - Winner (Sell, -20) = +70 (Strong Contrarian)
-            // Case 2: Loser (Buy, +50) - Winner (Buy, +20)  = +30 (Weak Contrarian)
-            // Case 3: Loser (Sell, -50) - Winner (Sell, -20) = -30 (Consensus)
-            // Case 4: Loser (Sell, -50) - Winner (Buy, +20)  = -70 (Strong Consensus)
-            
             const divergence = loser_flow - winner_flow;
-            const helix_score = this._normalize(divergence);
+            const helix_score = signals.normalizeTanh(divergence, 10, 10.0);
 
             let signal = "Neutral";
-            if (helix_score > 7.5) signal = "Strong Contrarian"; // Losers buying, Winners selling
+            if (helix_score > 7.5) signal = "Strong Contrarian";
             else if (helix_score > 2.5) signal = "Contrarian";
-            else if (helix_score < -2.5) signal = "Consensus"; // Both moving same way
+            else if (helix_score < -2.5) signal = "Consensus";
 
             result[ticker] = {
                 signal: signal,
                 helix_score: helix_score,
                 winner_net_flow: winner_flow,
-                loser_net_flow: loser_flow // Using conviction as flow proxy
+                loser_net_flow: loser_flow
             };
         }
-        
-        // --- STANDARD 2: SET STATE, DO NOT RETURN ---
         this.result = result;
     }
 
-    // --- STANDARD 2: ADDED ---
-    async getResult(fetchedDependencies) {
-        return this.result;
-    }
-
-    // --- STANDARD 2: ADDED ---
-    reset() {
-        this.result = {};
-    }
+    async getResult() { return this.result; }
+    reset() { this.result = {}; }
 }
-
 module.exports = HelixContrarianSignal;

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

@@ -1,179 +1,99 @@
 /**
  * @fileoverview HELIX Product Line (Pass 2)
- *
- * This metric answers: "For each asset, what is the
- * net 'conviction' (avg. position change) of the
- * 'Herd' (in-loss) cohort?"
+ * REFACTORED: Uses context.math.extract.
  */
-// --- STANDARD 0: REMOVED require('../../utils/sector_mapping_provider') ---
-
-
 class HerdConsensusScore {
     constructor() {
-        // { [instrumentId]: { ... } }
         this.assetConviction = new Map();
-        
-        // --- STANDARD 0: RENAMED ---
-        this.tickerMap = null; 
+        this.tickerMap = null;
     }
 
-    /**
-     * Defines the output schema for this calculation.
-     */
     static getSchema() {
         const tickerSchema = {
             "type": "object",
             "properties": {
-                "herd_conviction_score": {
-                    "type": "number",
-                    "description": "Avg. % change in position size for 'Loser' cohort. Positive = Buying the Dip, Negative = Capitulating."
-                },
+                "herd_conviction_score": { "type": "number" },
                 "user_count": { "type": "number" }
             },
             "required": ["herd_conviction_score", "user_count"]
         };
-        
-        return {
-            "type": "object",
-            "description": "Tracks the change in avg. position size for the 'Loser' (in-loss) cohort.",
-            "patternProperties": { "^.*$": tickerSchema },
-            "additionalProperties": tickerSchema
-        };
+        return { "type": "object", "patternProperties": { "^.*$": tickerSchema } };
     }
 
-    /**
-     * Statically defines all metadata for the manifest builder.
-     */
     static getMetadata() {
         return {
             type: 'standard',
             rootDataDependencies: ['portfolio'],
-            isHistorical: true, // Needs T-1 portfolio
+            isHistorical: true, 
             userType: 'all',
             category: 'helix'
         };
     }
 
-    /**
-     * Statically declare dependencies.
-     */
-    static getDependencies() {
-        return [];
-    }
+    static getDependencies() { return []; }
 
-    _getPortfolioPositions(portfolio) {
-        return portfolio?.AggregatedPositions || portfolio?.PublicPositions;
-    }
-    
     _initAsset(instrumentId) {
         if (!this.assetConviction.has(instrumentId)) {
             this.assetConviction.set(instrumentId, {
-                total_pos_size_yesterday: 0,
-                total_pos_size_today: 0,
-                user_count_yesterday: 0,
-                user_count_today: 0
+                total_pos_size_yesterday: 0, total_pos_size_today: 0,
+                user_count_yesterday: 0, user_count_today: 0
             });
         }
     }
 
-    process(todayPortfolio, yesterdayPortfolio, userId, context) {
-        if (!todayPortfolio) {
-            return;
-        }
-        
-        // --- STANDARD 0: FIXED ---
-        if (!this.tickerMap) {
-             this.tickerMap = context.instrumentToTicker;
-        }
+    process(context) {
+        const { user, mappings, math } = context;
+        const { extract } = math;
+        if (!this.tickerMap) this.tickerMap = mappings.instrumentToTicker;
 
-        const tPos = this._getPortfolioPositions(todayPortfolio);
-        if (!tPos) return;
+        const yPos = extract.getPositions(user.portfolio.yesterday, user.type);
+        const tPos = extract.getPositions(user.portfolio.today, user.type);
 
-        // --- Determine Cohort ---
-        // We *only* care about users who are *currently* in the
-        // 'Loser' cohort for any given asset.
-        const tPosMap = new Map(tPos.map(p => [p.InstrumentID, p]));
-        const yPosMap = new Map((this._getPortfolioPositions(yesterdayPortfolio) || []).map(p => [p.InstrumentID, p]));
+        const yPosMap = new Map(yPos.map(p => [extract.getInstrumentId(p), p]));
+        const tPosMap = new Map(tPos.map(p => [extract.getInstrumentId(p), p]));
         
-        const allInstrumentIds = new Set([...yPosMap.keys(), ...tPosMap.keys()]);
-        if (allInstrumentIds.size === 0) {
-            return;
-        }
-        
-        for (const instrumentId of allInstrumentIds) {
-            const tP = tPosMap.get(instrumentId);
-            const yP = yPosMap.get(instrumentId);
+        const allIds = new Set([...yPosMap.keys(), ...tPosMap.keys()]);
+
+        for (const instId of allIds) {
+            const tP = tPosMap.get(instId);
+            const yP = yPosMap.get(instId);
             
-            // --- Check Cohort Status (In-Loss) ---
-            const tPnl = tP?.NetProfit || 0;
-            const isLoser = tPnl < 0;
+            if (extract.getNetProfit(tP) >= 0) continue; // Only Losers (Herd)
             
-            // We only process conviction for assets this user
-            // is *currently* losing on.
-            if (!isLoser) {
-                continue;
-            }
-            
-            // --- This user is in the 'Herd' for this asset ---
-            this._initAsset(instrumentId);
-            const asset = this.assetConviction.get(instrumentId);
-
-            // ---
-            // FIX: The field 'PositionSizeInUnits' does not exist in schema.md.
-            // For Normal users, the field is 'Invested'.
-            // For Speculator users, the field is 'Amount'.
-            // This line now correctly checks for either.
-            // ---
-            const ySize = yP?.Invested || yP?.Amount || 0;
-            const tSize = tP?.Invested || tP?.Amount || 0;
+            this._initAsset(instId);
+            const asset = this.assetConviction.get(instId);
+            const yWeight = extract.getPositionWeight(yP, user.type);
+            const tWeight = extract.getPositionWeight(tP, user.type);
 
-            if (ySize > 0) {
-                asset.total_pos_size_yesterday += ySize;
+            if (yWeight > 0) {
+                asset.total_pos_size_yesterday += yWeight;
                 asset.user_count_yesterday++;
             }
-            if (tSize > 0) {
-                asset.total_pos_size_today += tSize;
+            if (tWeight > 0) {
+                asset.total_pos_size_today += tWeight;
                 asset.user_count_today++;
             }
         }
     }
 
     async getResult() {
-        // --- STANDARD 0: REMOVED forbidden data load ---
-
-        // Failsafe check
-        if (!this.tickerMap) {
-            return {}; // process() must run first
-        }
-
+        if (!this.tickerMap) return {};
         const result = {};
-        for (const [instrumentId, data] of this.assetConviction.entries()) {
-            // --- STANDARD 0: SIMPLIFIED ---
-            const ticker = this.tickerMap[instrumentId];
+        for (const [instId, data] of this.assetConviction.entries()) {
+            const ticker = this.tickerMap[instId];
             if (!ticker) continue;
 
-            const { 
-                total_pos_size_yesterday, total_pos_size_today,
-                user_count_yesterday, user_count_today
-            } = data;
-
-            let avg_position_change_pct = 0;
+            let avg_pos_change = 0;
+            if (data.user_count_yesterday > 0 && data.user_count_today > 0) {
+                const avg_y = data.total_pos_size_yesterday / data.user_count_yesterday;
+                const avg_t = data.total_pos_size_today / data.user_count_today;
+                if (avg_y > 0) avg_pos_change = ((avg_t - avg_y) / avg_y) * 100;
+            } else if (data.user_count_today > 0) avg_pos_change = Infinity;
 
-            if (user_count_yesterday > 0 && user_count_today > 0) {
-                const avg_pos_y = total_pos_size_yesterday / user_count_yesterday;
-                const avg_pos_t = total_pos_size_today / user_count_today;
-                if (avg_pos_y > 0) {
-                    avg_position_change_pct = ((avg_pos_t - avg_pos_y) / avg_pos_y) * 100;
-                }
-            } else if (user_count_today > 0) {
-                // Pure inflow, conviction is max
-                avg_position_change_pct = Infinity;
-            }
-
-            if (isFinite(avg_position_change_pct) && user_count_today > 0) {
+            if (isFinite(avg_pos_change) && data.user_count_today > 0) {
                 result[ticker] = {
-                    herd_conviction_score: avg_position_change_pct,
-                    user_count: user_count_today
+                    herd_conviction_score: avg_pos_change,
+                    user_count: data.user_count_today
                 };
             }
         }
@@ -182,9 +102,7 @@ class HerdConsensusScore {
 
     reset() {
         this.assetConviction.clear();
-        // --- STANDARD 0: RENAMED ---
         this.tickerMap = null;
     }
 }
-
 module.exports = HerdConsensusScore;

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

@@ -1,158 +1,78 @@
 /**
  * @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?"
- *
- * --- MODIFIED ---
- * Removed dependency on 'asset-pnl-status' to fix 1MiB limit.
- * This calculation now determines "winner/loser" status internally
- * by reading the user's portfolio P&L directly.
+ * REFACTORED: Uses context.math.extract.
  */
-// --- STANDARD 0: REMOVED require('../../utils/sector_mapping_provider') ---
-
-
 class WinnerLoserFlow {
     constructor() {
-        // We will store { [ticker]: { winners_joined: 0, ... } }
         this.assetFlows = new Map();
-        // --- STANDARD 0: RENAMED ---
-        this.tickerMap = 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
-        };
+        this.tickerMap = null;
     }
 
-    /**
-     * Statically defines all metadata for the manifest builder.
-     */
     static getMetadata() {
         return {
             type: 'standard',
             rootDataDependencies: ['portfolio'],
-            isHistorical: true, // Needs T-1 portfolio
+            isHistorical: true,
             userType: 'all',
             category: 'helix'
         };
     }
 
-    /**
-     * Statically declare dependencies.
-     */
-    static getDependencies() {
-        return [];
+    static getDependencies() { return []; }
+
+    static getSchema() {
+        const tickerSchema = {
+            "type": "object",
+            "properties": {
+                "net_winner_flow": { "type": "number" },
+                "net_loser_flow": { "type": "number" },
+                "raw_counts": { "type": "object" }
+            },
+            "required": ["net_winner_flow", "net_loser_flow", "raw_counts"]
+        };
+        return { "type": "object", "patternProperties": { "^.*$": tickerSchema } };
     }
 
-    /**
-     * Helper to get a user's holdings (Instrument IDs) AND their P&L.
-     * @returns {Map<InstrumentID, {pnl: number}>}
-     */
-    _getHoldingsWithPnl(portfolio) {
-        const positions = portfolio?.AggregatedPositions || portfolio?.PublicPositions;
-        if (!positions || !Array.isArray(positions)) {
-            return new Map();
-        }
+    _getHoldings(positions, extract) {
         const map = new Map();
         for (const pos of positions) {
-            if (pos.InstrumentID) {
-                map.set(pos.InstrumentID, { pnl: pos.NetProfit || 0 });
-            }
+            const id = extract.getInstrumentId(pos);
+            if (id) map.set(id, { pnl: extract.getNetProfit(pos) });
         }
         return map;
     }
     
-    /**
-     * 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
-            });
+            this.assetFlows.set(ticker, { winners_joined: 0, winners_left: 0, losers_joined: 0, losers_left: 0 });
         }
     }
 
-    process(todayPortfolio, yesterdayPortfolio, userId, context) {
-        if (!todayPortfolio || !yesterdayPortfolio) {
-            return;
-        }
+    process(context) {
+        const { user, mappings, math } = context;
+        const { extract } = math;
+        if (!this.tickerMap) this.tickerMap = mappings.instrumentToTicker;
 
-        // --- STANDARD 0: FIXED ---
-        if (!this.tickerMap) {
-             this.tickerMap = context.instrumentToTicker;
-        }
+        const yPos = extract.getPositions(user.portfolio.yesterday, user.type);
+        const tPos = extract.getPositions(user.portfolio.today, user.type);
         
-        if (!this.tickerMap) {
-            return; // Failsafe if context is missing map
-        }
+        const yHoldings = this._getHoldings(yPos, extract);
+        const tHoldings = this._getHoldings(tPos, extract);
 
-        const yHoldings = this._getHoldingsWithPnl(yesterdayPortfolio); // Map<InstID, {pnl}>
-        const tHoldings = this._getHoldingsWithPnl(todayPortfolio); // Map<InstID, {pnl}>
+        const allIds = new Set([...yHoldings.keys(), ...tHoldings.keys()]);
 
-        const allInstrumentIds = new Set([...yHoldings.keys(), ...tHoldings.keys()]);
-        if (allInstrumentIds.size === 0) {
-            return;
-        }
-
-        for (const instrumentId of allInstrumentIds) {
-            // --- STANDARD 0: FIXED ---
-            const ticker = this.tickerMap[instrumentId];
+        for (const instId of allIds) {
+            const ticker = this.tickerMap[instId];
             if (!ticker) continue;
             
-            const tPnl = tHoldings.get(instrumentId)?.pnl;
+            const tPnl = tHoldings.get(instId)?.pnl || 0;
             const isWinner = tPnl > 0;
             const isLoser = tPnl < 0;
-            
-            if (!isWinner && !isLoser) {
-                continue;
-            }
-
-            const heldYesterday = yHoldings.has(instrumentId);
-            const holdsToday = tHoldings.has(instrumentId);
+            if (!isWinner && !isLoser) continue;
 
-            if (heldYesterday === holdsToday) {
-                continue;
-            }
+            const heldYesterday = yHoldings.has(instId);
+            const holdsToday = tHoldings.has(instId);
+            if (heldYesterday === holdsToday) continue;
 
             this._initAsset(ticker);
             const stats = this.assetFlows.get(ticker);
@@ -182,9 +102,7 @@ class WinnerLoserFlow {
 
     reset() {
         this.assetFlows.clear();
-        // --- STANDARD 0: RENAMED ---
         this.tickerMap = null;
     }
 }
-
 module.exports = WinnerLoserFlow;