aiden-shared-calculations-unified 1.0.95 → 1.0.96

package/calculations/legacy/position_count_pnl.js

@@ -1,120 +0,0 @@
-/**
- * @fileoverview Calculation (Pass 2) for P&L by position count.
- *
- * This metric answers: "What is the average daily P&L for users,
- * bucketed by the number of positions they hold?"
- *
- * This helps determine if holding more positions (diversifying)
- * correlates with better or worse P&L.
- */
-class PositionCountPnl {
-    constructor() {
-        // We will store { [count_bucket]: { pnl_sum: 0, user_count: 0 } }
-        this.buckets = {
-            '1': { pnl_sum: 0, user_count: 0 },
-            '2-5': { pnl_sum: 0, user_count: 0 },
-            '6-10': { pnl_sum: 0, user_count: 0 },
-            '11-20': { pnl_sum: 0, user_count: 0 },
-            '21+': { pnl_sum: 0, user_count: 0 },
-        };
-    }
-
-    /**
-     * Defines the output schema for this calculation.
-     * @returns {object} JSON Schema object
-     */
-    static getSchema() {
-        const bucketSchema = {
-            "type": "object",
-            "description": "Aggregated P&L metrics for a position count bucket.",
-            "properties": {
-                "average_daily_pnl": {
-                    "type": "number",
-                    "description": "The average daily P&L for users in this bucket."
-                },
-                "user_count": {
-                    "type": "number",
-                    "description": "The number of users in this bucket."
-                },
-                "pnl_sum": {
-                    "type": "number",
-                    "description": "The sum of all P&L for users in this bucket."
-                }
-            },
-            "required": ["average_daily_pnl", "user_count", "pnl_sum"]
-        };
-        
-        return {
-            "type": "object",
-            "description": "Average daily P&L bucketed by the number of positions a user holds.",
-            "properties": {
-                "1": bucketSchema,
-                "2-5": bucketSchema,
-                "6-10": bucketSchema,
-                "11-20": bucketSchema,
-                "21+": bucketSchema
-            },
-            "required": ["1", "2-5", "6-10", "11-20", "21+"]
-        };
-    }
-
-    _getBucket(count) {
-        if (count === 1) return '1';
-        if (count >= 2 && count <= 5) return '2-5';
-        if (count >= 6 && count <= 10) return '6-10';
-        if (count >= 11 && count <= 20) return '11-20';
-        if (count >= 21) return '21+';
-        return null;
-    }
-
-    process(todayPortfolio, yesterdayPortfolio) {
-        // This calculation only needs today's portfolio state
-        if (!todayPortfolio) {
-            return;
-        }
-
-        const positions = todayPortfolio.AggregatedPositions || todayPortfolio.PublicPositions;
-        const positionCount = Array.isArray(positions) ? positions.length : 0;
-        
-        if (positionCount === 0) {
-            return;
-        }
-
-        const bucketKey = this._getBucket(positionCount);
-        if (!bucketKey) {
-            return;
-        }
-
-        // Use the P&L from the summary, which is for the *day*
-        const dailyPnl = todayPortfolio.Summary?.NetProfit || 0;
-        
-        const bucket = this.buckets[bucketKey];
-        bucket.pnl_sum += dailyPnl;
-        bucket.user_count++;
-    }
-
-    getResult() {
-        const result = {};
-        for (const key in this.buckets) {
-            const bucket = this.buckets[key];
-            result[key] = {
-                average_daily_pnl: (bucket.user_count > 0) ? (bucket.pnl_sum / bucket.user_count) : 0,
-                user_count: bucket.user_count,
-                pnl_sum: bucket.pnl_sum
-            };
-        }
-        return result;
-    }
-
-    reset() {
-        this.buckets = {
-            '1': { pnl_sum: 0, user_count: 0 },
-            '2-5': { pnl_sum: 0, user_count: 0 },
-            '6-10': { pnl_sum: 0, user_count: 0 },
-            '11-20': { pnl_sum: 0, user_count: 0 },
-            '21+': { pnl_sum: 0, user_count: 0 },
-        };
-    }
-}
-
-module.exports = PositionCountPnl;

package/calculations/legacy/positive_expectancy_cohort_flow.js

@@ -1,232 +0,0 @@
-/**
- * @fileoverview Calculation (Pass 4) for positive expectancy cohort flow.
- *
- * This metric calculates the "Net Crowd Flow Percentage" for the
- * "Positive Expectancy Cohort" (users with a high expectancy score).
- *
- * This calculation *depends* on 'user_expectancy_score'
- * to identify the cohort.
- */
-const { loadInstrumentMappings } = require('../../utils/sector_mapping_provider');
-
-class PositiveExpectancyCohortFlow {
-    constructor() {
-        this.assetData = new Map();
-        this.sectorData = new Map();
-        this.mappings = null;
-        this.posExpCohortUserIds = null;
-    }
-
-    /**
-     * Defines the output schema for this calculation.
-     * @returns {object} JSON Schema object
-     */
-    static getSchema() {
-        const flowSchema = {
-            "type": "object",
-            "properties": {
-                "net_flow_percentage": { "type": "number" },
-                "total_invested_today": { "type": "number" },
-                "total_invested_yesterday": { "type": "number" }
-            },
-            "required": ["net_flow_percentage", "total_invested_today", "total_invested_yesterday"]
-        };
-
-        return {
-            "type": "object",
-            "description": "Calculates net capital flow % (price-adjusted) for the 'Positive Expectancy' cohort (score > 0.5), aggregated by asset and sector.",
-            "properties": {
-                "cohort_size": {
-                    "type": "number",
-                    "description": "The number of users identified as being in the Positive Expectancy Cohort."
-                },
-                "assets": {
-                    "type": "object",
-                    "description": "Price-adjusted net flow per asset.",
-                    "patternProperties": { "^.*$": flowSchema }, // Ticker
-                    "additionalProperties": flowSchema
-                },
-                "sectors": {
-                    "type": "object",
-                    "description": "Price-adjusted net flow per sector.",
-                    "patternProperties": { "^.*$": flowSchema }, // Sector
-                    "additionalProperties": flowSchema
-                }
-            },
-            "required": ["cohort_size", "assets", "sectors"]
-        };
-    }
-
-    /**
-     * Statically declare dependencies.
-     */
-    static getDependencies() {
-        return ['user_expectancy_score']; // Pass 3
-    }
-
-    _getPortfolioPositions(portfolio) {
-        return portfolio?.PublicPositions || portfolio?.AggregatedPositions;
-    }
-
-    _initAsset(instrumentId) {
-        if (!this.assetData.has(instrumentId)) {
-            this.assetData.set(instrumentId, {
-                total_invested_yesterday: 0,
-                total_invested_today: 0,
-                price_change_yesterday: 0,
-            });
-        }
-    }
-    
-    _initSector(sector) {
-        if (!this.sectorData.has(sector)) {
-            this.sectorData.set(sector, {
-                total_invested_yesterday: 0,
-                total_invested_today: 0,
-                price_change_yesterday: 0,
-            });
-        }
-    }
-
-    _getPosExpCohort(fetchedDependencies) {
-        if (this.posExpCohortUserIds) {
-            return this.posExpCohortUserIds;
-        }
-        
-        const expectancyData = fetchedDependencies['user_expectancy_score'];
-        if (!expectancyData) {
-            return new Set();
-        }
-
-        this.posExpCohortUserIds = new Set();
-        for (const [userId, data] of Object.entries(expectancyData)) {
-            // Definition: Expectancy score > 0.5
-            if (data.expectancy_score > 0.5) {
-                this.posExpCohortUserIds.add(userId);
-            }
-        }
-        return this.posExpCohortUserIds;
-    }
-
-    process(todayPortfolio, yesterdayPortfolio, userId, context, todayInsights, yesterdayInsights, fetchedDependencies) {
-        const cohort = this._getPosExpCohort(fetchedDependencies);
-        
-        if (!cohort.has(userId)) {
-            return;
-        }
-
-        if (!todayPortfolio || !yesterdayPortfolio) {
-            return;
-        }
-
-        const yPos = this._getPortfolioPositions(yesterdayPortfolio);
-        const tPos = this._getPortfolioPositions(todayPortfolio);
-
-        const yPosMap = new Map(yPos?.map(p => [p.InstrumentID, p]) || []);
-        const tPosMap = new Map(tPos?.map(p => [p.InstrumentID, p]) || []);
-
-        const allInstrumentIds = new Set([...yPosMap.keys(), ...tPosMap.keys()]);
-        
-        if (!this.mappings) {
-            this.mappings = context.mappings;
-        }
-
-        for (const instrumentId of allInstrumentIds) {
-            if (!instrumentId) continue;
-            
-            this._initAsset(instrumentId);
-            const asset = this.assetData.get(instrumentId);
-
-            const yP = yPosMap.get(instrumentId);
-            const tP = tPosMap.get(instrumentId);
-
-            const yInvested = yP?.InvestedAmount || yP?.Amount || 0;
-            const tInvested = tP?.InvestedAmount || tP?.Amount || 0;
-            
-            const sector = this.mappings.instrumentToSector[instrumentId] || 'Other';
-            this._initSector(sector);
-            const sectorAsset = this.sectorData.get(sector);
-
-            if (yInvested > 0) {
-                const yPriceChange = (yP?.PipsRate || 0) / (yP?.OpenRate || 1);
-                
-                asset.total_invested_yesterday += yInvested;
-                asset.price_change_yesterday += yPriceChange * yInvested;
-                
-                sectorAsset.total_invested_yesterday += yInvested;
-                sectorAsset.price_change_yesterday += yPriceChange * yInvested;
-            }
-            if (tInvested > 0) {
-                asset.total_invested_today += tInvested;
-                sectorAsset.total_invested_today += tInvested;
-            }
-        }
-    }
-    
-    _calculateFlow(dataMap) {
-        const result = {};
-        for (const [key, data] of dataMap.entries()) {
-            const { total_invested_yesterday, total_invested_today, price_change_yesterday } = data;
-            
-            if (total_invested_yesterday > 0) {
-                const avg_price_change_pct = price_change_yesterday / total_invested_yesterday;
-                const price_contribution = total_invested_yesterday * avg_price_change_pct;
-                const flow_contribution = total_invested_today - (total_invested_yesterday + price_contribution);
-                const net_flow_percentage = (flow_contribution / total_invested_yesterday) * 100;
-                
-                result[key] = {
-                    net_flow_percentage: net_flow_percentage,
-                    total_invested_today: total_invested_today,
-                    total_invested_yesterday: total_invested_yesterday
-                };
-            }
-        }
-        return result;
-    }
-
-    async getResult(fetchedDependencies) {
-        if (!this.mappings) {
-            this.mappings = await loadInstrumentMappings();
-        }
-        
-        const cohort = this._getPosExpCohort(fetchedDependencies);
-
-        // 1. Calculate Asset Flow
-        const assetResult = {};
-        for (const [instrumentId, data] of this.assetData.entries()) {
-            const ticker = this.mappings.instrumentToTicker[instrumentId] || `id_${instrumentId}`;
-            const { total_invested_yesterday, total_invested_today, price_change_yesterday } = data;
-            
-            if (total_invested_yesterday > 0) {
-                const avg_price_change_pct = price_change_yesterday / total_invested_yesterday;
-                const price_contribution = total_invested_yesterday * avg_price_change_pct;
-                const flow_contribution = total_invested_today - (total_invested_yesterday + price_contribution);
-                const net_flow_percentage = (flow_contribution / total_invested_yesterday) * 100;
-                
-                assetResult[ticker] = {
-                    net_flow_percentage: net_flow_percentage,
-                    total_invested_today: total_invested_today,
-                    total_invested_yesterday: total_invested_yesterday
-                };
-            }
-        }
-        
-        // 2. Calculate Sector Flow
-        const sectorResult = this._calculateFlow(this.sectorData);
-
-        return {
-            cohort_size: cohort.size,
-            assets: assetResult,
-            sectors: sectorResult
-        };
-    }
-
-    reset() {
-        this.assetData.clear();
-        this.sectorData.clear();
-        this.mappings = null;
-        this.posExpCohortUserIds = null;
-    }
-}
-
-module.exports = PositiveExpectancyCohortFlow;

package/calculations/legacy/profit_cohort_divergence.js

@@ -1,115 +0,0 @@
-/**
- * @fileoverview Calculation (Pass 4) for profit cohort divergence.
- *
- * This metric answers: "What divergence signals can be found by
- * comparing the net asset flow of the 'in-profit' cohort vs.
- * the 'in-loss' cohort?"
- *
- * e.g.,
- * - Profit cohort selling, Loss cohort holding = "Profit Taking"
- * - Profit cohort holding, Loss cohort selling = "Capitulation"
- * - Both buying = "Confirmation"
- * - Both selling = "Exodus"
- *
- * It *depends* on 'in_profit_asset_crowd_flow' and
- * 'in_loss_asset_crowd_flow'.
- */
-class ProfitCohortDivergence {
-    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": ["Profit Taking", "Capitulation", "Confirmation (Buy)", "Confirmation (Sell)", "Divergence (Profit Buy / Loss Sell)", "Divergence (Profit Sell / Loss Buy)", "Neutral"]
-                },
-                "profit_cohort_flow_pct": { "type": "number" },
-                "loss_cohort_flow_pct": { "type": "number" }
-            },
-            "required": ["status", "profit_cohort_flow_pct", "loss_cohort_flow_pct"]
-        };
-
-        return {
-            "type": "object",
-            "description": "Generates divergence signals by comparing net flow of 'in-profit' vs. 'in-loss' cohorts.",
-            "patternProperties": {
-                "^.*$": signalSchema // Ticker
-            },
-            "additionalProperties": signalSchema
-        };
-    }
-
-    /**
-     * Statically declare dependencies.
-     */
-    static getDependencies() {
-        return [
-            'in_profit_asset_crowd_flow', // Pass 3
-            'in_loss_asset_crowd_flow'    // Pass 3
-        ];
-    }
-
-    process() {
-        // No-op
-    }
-
-    getResult(fetchedDependencies) {
-        const profitFlowData = fetchedDependencies['in_profit_asset_crowd_flow'];
-        const lossFlowData = fetchedDependencies['in_loss_asset_crowd_flow'];
-
-        if (!profitFlowData || !lossFlowData) {
-            return {};
-        }
-
-        const allTickers = new Set([...Object.keys(profitFlowData), ...Object.keys(lossFlowData)]);
-        const result = {};
-        const THRESHOLD = 1; // Min flow % to be considered 'active'
-
-        for (const ticker of allTickers) {
-            const pFlow = profitFlowData[ticker]?.net_flow_percentage || 0;
-            const lFlow = lossFlowData[ticker]?.net_flow_percentage || 0;
-
-            let status = 'Neutral';
-
-            if (pFlow > THRESHOLD && lFlow > THRESHOLD) {
-                status = 'Confirmation (Buy)';
-            } else if (pFlow < -THRESHOLD && lFlow < -THRESHOLD) {
-                status = 'Confirmation (Sell)';
-            } else if (pFlow > THRESHOLD && Math.abs(lFlow) < THRESHOLD) {
-                status = 'Divergence (Profit Buy / Loss Sell)'; // Profit cohort buying, loss cohort holding
-            } else if (pFlow < -THRESHOLD && Math.abs(lFlow) < THRESHOLD) {
-                status = 'Profit Taking';
-            } else if (Math.abs(pFlow) < THRESHOLD && lFlow < -THRESHOLD) {
-                status = 'Capitulation';
-            } else if (Math.abs(pFlow) < THRESHOLD && lFlow > THRESHOLD) {
-                status = 'Divergence (Profit Sell / Loss Buy)'; // Loss cohort buying, profit cohort holding
-            } else if (pFlow > THRESHOLD && lFlow < -THRESHOLD) {
-                status = 'Divergence (Profit Buy / Loss Sell)';
-            } else if (pFlow < -THRESHOLD && lFlow > THRESHOLD) {
-                status = 'Divergence (Profit Sell / Loss Buy)';
-            }
-
-            result[ticker] = {
-                status: status,
-                profit_cohort_flow_pct: pFlow,
-                loss_cohort_flow_pct: lFlow
-            };
-        }
-        
-        return result;
-    }
-
-    reset() {
-        // No state
-    }
-}
-
-module.exports = ProfitCohortDivergence;

package/calculations/legacy/profitability_migration.js

@@ -1,104 +0,0 @@
-/**
- * @fileoverview Calculation (Pass 2) for profitability migration.
- *
- * This metric answers: "How many users migrated between
- * profitable and unprofitable states today?"
- *
- * It tracks the "churn" between P&L states.
- */
-class ProfitabilityMigration {
-    constructor() {
-        this.to_profit_count = 0;
-        this.to_loss_count = 0;
-        this.remained_profit_count = 0;
-        this.remained_loss_count = 0;
-        this.total_processed = 0;
-    }
-
-    /**
-     * Defines the output schema for this calculation.
-     * @returns {object} JSON Schema object
-     */
-    static getSchema() {
-        return {
-            "type": "object",
-            "description": "Tracks the migration of users between profitable and unprofitable states day-over-day.",
-            "properties": {
-                "to_profit_count": {
-                    "type": "number",
-                    "description": "Count of users who were in loss yesterday and are in profit today."
-                },
-                "to_loss_count": {
-                    "type": "number",
-                    "description": "Count of users who were in profit yesterday and are in loss today."
-                },
-                "remained_profit_count": {
-                    "type": "number",
-                    "description": "Count of users who were in profit yesterday and today."
-                },
-                "remained_loss_count": {
-                    "type": "number",
-                    "description": "Count of users who were in loss yesterday and today."
-                },
-                "total_processed": {
-                    "type": "number",
-                    "description": "Total users who had a P&L status on both days."
-                }
-            },
-            "required": ["to_profit_count", "to_loss_count", "remained_profit_count", "remained_loss_count", "total_processed"]
-        };
-    }
-
-    _getPnlState(portfolio) {
-        // This checks *overall portfolio* P&L for the day
-        const dailyPnl = portfolio?.Summary?.NetProfit || 0;
-        if (dailyPnl > 0) return 'profit';
-        if (dailyPnl < 0) return 'loss';
-        return 'neutral';
-    }
-
-    process(todayPortfolio, yesterdayPortfolio) {
-        if (!todayPortfolio || !yesterdayPortfolio) {
-            return;
-        }
-
-        const yState = this._getPnlState(yesterdayPortfolio);
-        const tState = this._getPnlState(todayPortfolio);
-
-        if (yState === 'neutral' || tState === 'neutral') {
-            return; // Only track transitions between profit/loss
-        }
-        
-        this.total_processed++;
-
-        if (yState === 'profit' && tState === 'profit') {
-            this.remained_profit_count++;
-        } else if (yState === 'loss' && tState === 'loss') {
-            this.remained_loss_count++;
-        } else if (yState === 'loss' && tState === 'profit') {
-            this.to_profit_count++;
-        } else if (yState === 'profit' && tState === 'loss') {
-            this.to_loss_count++;
-        }
-    }
-
-    getResult() {
-        return {
-            to_profit_count: this.to_profit_count,
-            to_loss_count: this.to_loss_count,
-            remained_profit_count: this.remained_profit_count,
-            remained_loss_count: this.remained_loss_count,
-            total_processed: this.total_processed
-        };
-    }
-
-    reset() {
-        this.to_profit_count = 0;
-        this.to_loss_count = 0;
-        this.remained_profit_count = 0;
-        this.remained_loss_count = 0;
-        this.total_processed = 0;
-    }
-}
-
-module.exports = ProfitabilityMigration;

package/calculations/legacy/reallocation_increase_percentage.js

@@ -1,104 +0,0 @@
-/**
- * @fileoverview Calculation (Pass 2) for reallocation increase percentage.
- *
- * This metric answers: "On average, what was the total percentage
- * increase in allocation to *existing* positions today?"
- *
- * This measures "doubling down" or adding to winners/losers.
- */
-class ReallocationIncreasePercentage {
-    constructor() {
-        this.total_reallocation_increase_pct = 0;
-        this.users_with_reallocations = 0;
-    }
-
-    /**
-     * Defines the output schema for this calculation.
-     * @returns {object} JSON Schema object
-     */
-    static getSchema() {
-        return {
-            "type": "object",
-            "description": "Calculates the average portfolio percentage *added* to *existing* positions today.",
-            "properties": {
-                "average_reallocation_increase_pct": {
-                    "type": "number",
-                    "description": "The average percentage of a portfolio added to existing positions, for users who reallocated."
-                },
-                "total_reallocation_increase_pct_sum": {
-                    "type": "number",
-                    "description": "The sum of all reallocation increase percentages."
-                },
-                "user_count_with_reallocations": {
-                    "type": "number",
-                    "description": "The count of users who added to at least one existing position."
-                }
-            },
-            "required": ["average_reallocation_increase_pct", "total_reallocation_increase_pct_sum", "user_count_with_reallocations"]
-        };
-    }
-
-    _getPortfolioPositionMap(portfolio) {
-        // We MUST use AggregatedPositions for the 'Invested' %
-        const positions = portfolio?.AggregatedPositions;
-        if (!positions || !Array.isArray(positions)) {
-            return new Map();
-        }
-        // Map<InstrumentID, { invested: number }>
-        return new Map(positions.map(p => [p.InstrumentID, {
-            invested: p.InvestedAmount || p.Invested || 0
-        }]));
-    }
-
-    process(todayPortfolio, yesterdayPortfolio) {
-        if (!todayPortfolio || !yesterdayPortfolio) {
-            return;
-        }
-
-        const yPosMap = this._getPortfolioPositionMap(yesterdayPortfolio);
-        const tPosMap = this._getPortfolioPositionMap(todayPortfolio);
-
-        if (tPosMap.size === 0 || yPosMap.size === 0) {
-            return; // No positions to compare
-        }
-
-        let userReallocationIncrease = 0;
-
-        for (const [tId, tPosData] of tPosMap.entries()) {
-            // Check if this position also existed yesterday
-            if (yPosMap.has(tId)) {
-                const yPosData = yPosMap.get(tId);
-                const increase = tPosData.invested - yPosData.invested;
-
-                // We only care about *increases*
-                if (increase > 0) {
-                    userReallocationIncrease += increase;
-                }
-            }
-        }
-
-        if (userReallocationIncrease > 0) {
-            this.total_reallocation_increase_pct += userReallocationIncrease;
-            this.users_with_reallocations++;
-        }
-    }
-
-    getResult() {
-        const avg_pct = (this.users_with_reallocations > 0)
-            ? (this.total_reallocation_increase_pct / this.users_with_reallocations)
-            : 0;
-
-        return {
-            average_reallocation_increase_pct: avg_pct,
-            total_reallocation_increase_pct_sum: this.total_reallocation_increase_pct,
-            user_count_with_reallocations: this.users_with_reallocations
-        };
-    }
-
-    reset() {
-        this.total_reallocation_increase_pct = 0;
-        this.users_with_reallocations = 0;
-    }
-}
-
-module.exports = ReallocationIncreasePercentage;