aiden-shared-calculations-unified 1.0.95 → 1.0.97

package/calculations/legacy/cash-flow-liquidation.js

@@ -1,146 +0,0 @@
-/**
- * @fileoverview Calculation (Pass 3) for cash flow liquidation.
- *
- * This metric answers: "Following a net withdrawal event, what percentage
- * of that withdrawal was funded by selling *today*, and which assets
- * are being liquidated the most?"
- *
- * It *depends* on 'crowd-cash-flow-proxy' (to know if it's a
- * withdrawal day) and 'asset_crowd_flow' (to see where flow went).
- */
-class CashFlowLiquidation {
-    constructor() {
-        // No per-user processing
-    }
-
-    /**
-     * Defines the output schema for this calculation.
-     * @returns {object} JSON Schema object
-     */
-    static getSchema() {
-        const assetFlowSchema = {
-            "type": "object",
-            "properties": {
-                "ticker": { "type": "string" },
-                "net_flow_contribution": { "type": "number" },
-                "percent_of_total_outflow": { "type": "number" }
-            },
-            "required": ["ticker", "net_flow_contribution", "percent_of_total_outflow"]
-        };
-
-        return {
-            "type": "object",
-            "description": "On net withdrawal days, tracks % of withdrawal funded by selling and which assets were sold.",
-            "properties": {
-                "is_net_withdrawal_day": {
-                    "type": "boolean",
-                    "description": "True if today was a net withdrawal day."
-                },
-                "net_cash_flow_proxy": {
-                    "type": "number",
-                    "description": "The total estimated net cash flow (negative)."
-                },
-                "total_net_capital_flow": {
-                    "type": "number",
-                    "description": "The sum of all *negative* net capital flows from assets (total liquidation)."
-                },
-                "funding_percentage": {
-                    "type": ["number", "null"],
-                    "description": "Percentage of net cash flow funded by selling (Total Net Flow / Net Cash Flow). Null if no cash flow."
-                },
-                "top_outflow_assets": {
-                    "type": "array",
-                    "description": "Top 5 assets being liquidated.",
-                    "items": assetFlowSchema
-                },
-                "asset_flow_details": {
-                    "type": "array",
-                    "description": "Full list of all assets and their outflows.",
-                    "items": assetFlowSchema
-                }
-            },
-            "required": ["is_net_withdrawal_day", "net_cash_flow_proxy", "total_net_capital_flow", "funding_percentage", "top_outflow_assets", "asset_flow_details"]
-        };
-    }
-
-    /**
-     * Statically declare dependencies.
-     */
-    static getDependencies() {
-        return [
-            'crowd-cash-flow-proxy', // Pass 2
-            'asset_crowd_flow'       // Pass 2
-        ];
-    }
-
-    process() {
-        // No-op
-    }
-
-    getResult(fetchedDependencies) {
-        const cashFlowData = fetchedDependencies['crowd-cash-flow-proxy'];
-        const assetFlowData = fetchedDependencies['asset_crowd_flow'];
-
-        const defaults = {
-            is_net_withdrawal_day: false,
-            net_cash_flow_proxy: 0,
-            total_net_capital_flow: 0,
-            funding_percentage: null,
-            top_outflow_assets: [],
-            asset_flow_details: []
-        };
-
-        if (!cashFlowData || !assetFlowData || cashFlowData.net_cash_flow_proxy >= 0) {
-            // Not a net withdrawal day
-            return defaults;
-        }
-
-        const netCashFlow = cashFlowData.net_cash_flow_proxy; // This is a negative number
-        let totalNetOutflow = 0;
-        const allFlows = [];
-
-        for (const [ticker, data] of Object.entries(assetFlowData)) {
-            // We only care about *negative* flow (liquidation)
-            if (data.net_flow_contribution < 0) {
-                totalNetOutflow += data.net_flow_contribution; // Summing negative numbers
-                allFlows.push({
-                    ticker: ticker,
-                    net_flow_contribution: data.net_flow_contribution
-                });
-            }
-        }
-
-        if (totalNetOutflow === 0) {
-            // Net withdrawal day, but no negative flow detected
-            return {
-                ...defaults,
-                is_net_withdrawal_day: true,
-                net_cash_flow_proxy: netCashFlow,
-                funding_percentage: 0
-            };
-        }
-        
-        // Calculate percent_of_total_outflow for each
-        const asset_flow_details = allFlows.map(flow => ({
-            ...flow,
-            // (Negative / Negative) * 100 = Positive %
-            percent_of_total_outflow: (flow.net_flow_contribution / totalNetOutflow) * 100
-        })).sort((a, b) => a.net_flow_contribution - b.net_flow_contribution); // Sort ascending (most negative first)
-
-        return {
-            is_net_withdrawal_day: true,
-            net_cash_flow_proxy: netCashFlow,
-            total_net_capital_flow: totalNetOutflow,
-            // (Negative / Negative) * 100 = Positive %
-            funding_percentage: (netCashFlow < 0) ? (totalNetOutflow / netCashFlow) * 100 : null,
-            top_outflow_assets: asset_flow_details.slice(0, 5),
-            asset_flow_details: asset_flow_details
-        };
-    }
-
-    reset() {
-        // No state
-    }
-}
-
-module.exports = CashFlowLiquidation;

package/calculations/legacy/crowd-cash-flow-proxy.js

@@ -1,128 +0,0 @@
-/**
- * @fileoverview Calculation (Pass 2) for crowd cash flow proxy.
- *
- * This metric estimates the net cash flow (deposits vs. withdrawals)
- * of the crowd by analyzing changes in 'Invested' vs. 'Cash' balances
- * in user portfolios.
- *
- * It's a proxy because it doesn't see real bank transactions, but
- * infers from the total portfolio value vs. the invested amount.
- */
-class CrowdCashFlowProxy {
-    constructor() {
-        this.total_portfolio_value_yesterday = 0;
-        this.total_invested_yesterday = 0;
-        
-        this.total_portfolio_value_today = 0;
-        this.total_invested_today = 0;
-    }
-
-    /**
-     * Defines the output schema for this calculation.
-     * @returns {object} JSON Schema object
-     */
-    static getSchema() {
-        return {
-            "type": "object",
-            "description": "Estimates net cash flow (deposits/withdrawals) by comparing changes in total portfolio value vs. invested capital.",
-            "properties": {
-                "total_portfolio_value_yesterday": {
-                    "type": "number",
-                    "description": "Sum of all users' total portfolio values from yesterday."
-                },
-                "total_invested_yesterday": {
-                    "type": "number",
-                    "description": "Sum of all users' invested capital from yesterday."
-                },
-                "total_portfolio_value_today": {
-                    "type": "number",
-                    "description": "Sum of all users' total portfolio values from today."
-                },
-                "total_invested_today": {
-                    "type": "number",
-                    "description": "Sum of all users' invested capital from today."
-                },
-                "total_pnl_contribution": {
-                    "type": "number",
-                    "description": "The estimated change in portfolio value attributable to P&L."
-                },
-                "net_cash_flow_proxy": {
-                    "type": "number",
-                    "description": "The estimated net cash flow (Deposits - Withdrawals). Positive indicates net deposits."
-                },
-                "net_cash_flow_proxy_pct": {
-                    "type": "number",
-                    "description": "The net cash flow proxy as a percentage of yesterday's total portfolio value."
-                }
-            },
-            "required": [
-                "total_portfolio_value_yesterday", "total_invested_yesterday",
-                "total_portfolio_value_today", "total_invested_today",
-                "total_pnl_contribution", "net_cash_flow_proxy", "net_cash_flow_proxy_pct"
-            ]
-        };
-    }
-
-    _getPortfolioValues(portfolio) {
-        if (!portfolio || !portfolio.Summary) {
-            return { portfolioValue: 0, invested: 0 };
-        }
-        
-        // Total value (Invested + Cash)
-        const portfolioValue = portfolio.Summary.PortfolioValue || 0;
-        // Total invested in positions
-        const invested = portfolio.Summary.Invested || 0;
-        
-        return { portfolioValue, invested };
-    }
-
-    process(todayPortfolio, yesterdayPortfolio) {
-        if (!todayPortfolio || !yesterdayPortfolio) {
-            return;
-        }
-
-        const yValues = this._getPortfolioValues(yesterdayPortfolio);
-        const tValues = this._getPortfolioValues(todayPortfolio);
-
-        this.total_portfolio_value_yesterday += yValues.portfolioValue;
-        this.total_invested_yesterday += yValues.invested;
-
-        this.total_portfolio_value_today += tValues.portfolioValue;
-        this.total_invested_today += tValues.invested;
-    }
-
-    getResult() {
-        // P&L is the change in *invested* value, not total value
-        const totalPnl = this.total_invested_today - this.total_invested_yesterday;
-
-        // The change in total value is (P&L + Net Cash Flow)
-        // So, Net Cash Flow = (Total Value Change) - P&L
-        const totalValueChange = this.total_portfolio_value_today - this.total_portfolio_value_yesterday;
-        
-        const netCashFlowProxy = totalValueChange - totalPnl;
-        
-        const netCashFlowProxyPct = (this.total_portfolio_value_yesterday > 0)
-            ? (netCashFlowProxy / this.total_portfolio_value_yesterday) * 100
-            : 0;
-
-        return {
-            total_portfolio_value_yesterday: this.total_portfolio_value_yesterday,
-            total_invested_yesterday: this.total_invested_yesterday,
-            total_portfolio_value_today: this.total_portfolio_value_today,
-            total_invested_today: this.total_invested_today,
-            
-            total_pnl_contribution: totalPnl,
-            net_cash_flow_proxy: netCashFlowProxy,
-            net_cash_flow_proxy_pct: netCashFlowProxyPct
-        };
-    }
-
-    reset() {
-        this.total_portfolio_value_yesterday = 0;
-        this.total_invested_yesterday = 0;
-        this.total_portfolio_value_today = 0;
-        this.total_invested_today = 0;
-    }
-}
-
-module.exports = CrowdCashFlowProxy;

package/calculations/legacy/crowd_conviction_score.js

@@ -1,261 +0,0 @@
-/**
- * @fileoverview Calculation (Pass 2) for crowd conviction.
- *
- * This metric answers: "What is the 'Crowd Conviction Score'
- * for each instrument?"
- *
- * It's based on factors like:
- * 1. Holding Duration (longer = more conviction)
- * 2. P&L % (positive = more conviction)
- * 3. Risk/Reward Ratio (higher = more conviction)
- * 4. Leverage (lower = more conviction)
- *
- * 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');
-
-class CrowdConvictionScore {
-    constructor() {
-        // { [instrumentId]: { metrics: [], history: [] } }
-        this.assetData = new Map();
-        this.mappings = null;
-    }
-
-    /**
-     * Defines the output schema for this calculation.
-     * @returns {object} JSON Schema object
-     */
-    static getSchema() {
-        const historyItemSchema = {
-            "type": "object",
-            "properties": {
-                "avg_holding_duration": { "type": "number" },
-                "avg_pnl": { "type": "number" },
-                "avg_rr": { "type": "number" },
-                "avg_leverage": { "type": "number" }
-            },
-            "required": ["avg_holding_duration", "avg_pnl", "avg_rr", "avg_leverage"]
-        };
-
-        const tickerSchema = {
-            "type": "object",
-            "description": "Crowd conviction score and its components for a specific asset.",
-            "properties": {
-                "conviction_score": {
-                    "type": "number",
-                    "description": "Final conviction score (0-100), based on 30-day rolling averages."
-                },
-                "roll_avg_holding_duration": {
-                    "type": "number",
-                    "description": "30-day rolling average of holding duration (hours)."
-                },
-                "roll_avg_pnl": {
-                    "type": "number",
-                    "description": "30-day rolling average of P&L percentage."
-                },
-                "roll_avg_rr": {
-                    "type": "number",
-                    "description": "30-day rolling average of risk/reward ratio."
-                },
-                "roll_avg_leverage": {
-                    "type": "number",
-                    "description": "30-day rolling average of leverage."
-                },
-                "avg_holding_duration": {
-                    "type": "number",
-                    "description": "Today's average holding duration."
-                },
-                "avg_pnl": {
-                    "type": "number",
-                    "description": "Today's average P&L percentage."
-                },
-                "avg_rr": {
-                    "type": "number",
-                    "description": "Today's average risk/reward ratio."
-                },
-                "avg_leverage": {
-                    "type": "number",
-                    "description": "Today's average leverage."
-                },
-                "history": {
-                    "type": "array",
-                    "description": "30-day history of daily average metrics.",
-                    "items": historyItemSchema
-                }
-            },
-            "required": [
-                "conviction_score", "roll_avg_holding_duration", "roll_avg_pnl", 
-                "roll_avg_rr", "roll_avg_leverage", "avg_holding_duration", 
-                "avg_pnl", "avg_rr", "avg_leverage", "history"
-            ]
-        };
-
-        return {
-            "type": "object",
-            "description": "Calculates a 30-day rolling 'Crowd Conviction Score' (0-100) for each asset.",
-            "patternProperties": {
-                "^.*$": tickerSchema // Ticker
-            },
-            "additionalProperties": tickerSchema
-        };
-    }
-
-    _initAsset(instrumentId) {
-        if (!this.assetData.has(instrumentId)) {
-            // metrics: Stores *today's* raw values before averaging
-            // history: Stores *yesterday's* 30-day history
-            this.assetData.set(instrumentId, {
-                metrics: [],
-                history: []
-            });
-        }
-    }
-    
-    _getHoldingDurationHours(openDateStr) {
-        if (!openDateStr) return 0;
-        try {
-            const openDate = new Date(openDateStr);
-            const diffMs = new Date().getTime() - openDate.getTime();
-            return diffMs / (1000 * 60 * 60);
-        } catch (e) {
-            return 0;
-        }
-    }
-    
-    // Simple min-max normalization helper
-    _normalize(value, min, max) {
-        if (max === min) return 0.5; // Avoid division by zero
-        const normalized = (value - min) / (max - min);
-        return Math.max(0, Math.min(1, normalized)); // Clamp between 0 and 1
-    }
-
-    process(portfolioData, yesterdayPortfolio, userId, context) {
-        // This score is based on speculator actions
-        if (portfolioData?.context?.userType !== 'speculator') {
-            return;
-        }
-        
-        // 1. Get this metric's history from yesterday (pre-loaded)
-        if (this.assetData.size === 0) { // Only run once
-             const yHistoryData = context.yesterdaysDependencyData['crowd_conviction_score'];
-             if (yHistoryData) {
-                 if (!this.mappings) {
-                     // We need mappings to convert *yesterday's* tickers back to IDs
-                     this.mappings = context.mappings;
-                 }
-                 for (const [ticker, data] of Object.entries(yHistoryData)) {
-                     const instrumentId = this.mappings.tickerToInstrument[ticker];
-                     if (instrumentId) {
-                         this._initAsset(instrumentId);
-                         this.assetData.get(instrumentId).history = data.history || [];
-                     }
-                 }
-             }
-        }
-
-        const positions = portfolioData.PublicPositions;
-        if (!positions || !Array.isArray(positions)) {
-            return;
-        }
-
-        for (const pos of positions) {
-            const instrumentId = pos.InstrumentID;
-            if (!instrumentId) continue;
-            
-            this._initAsset(instrumentId);
-            
-            const pnl_percent = (pos.NetProfit || 0) / (pos.Amount || 1);
-            const holding_duration = this._getHoldingDurationHours(pos.OpenDateTime);
-            const leverage = pos.Leverage || 1;
-            
-            const sl_rate = pos.StopLossRate || 0;
-            const tp_rate = pos.TakeProfitRate || 0;
-            const open_rate = pos.OpenRate || 1;
-            
-            let rr_ratio = 0;
-            if (sl_rate > 0 && tp_rate > 0) {
-                const risk = Math.abs(open_rate - sl_rate);
-                const reward = Math.abs(tp_rate - open_rate);
-                if (risk > 0) {
-                    rr_ratio = reward / risk;
-                }
-            }
-            
-            this.assetData.get(instrumentId).metrics.push({
-                holding_duration,
-                pnl_percent,
-                rr_ratio,
-                leverage
-            });
-        }
-    }
-
-    async getResult() {
-        if (!this.mappings) {
-            this.mappings = await loadInstrumentMappings();
-        }
-
-        const result = {};
-        for (const [instrumentId, data] of this.assetData.entries()) {
-            const ticker = this.mappings.instrumentToTicker[instrumentId] || `id_${instrumentId}`;
-            const metrics = data.metrics;
-            const yHistory = data.history; // Yesterday's 30-day history
-
-            if (metrics.length === 0) continue;
-
-            // 1. Calculate today's averages
-            const count = metrics.length;
-            const avg_holding_duration = metrics.reduce((s, m) => s + m.holding_duration, 0) / count;
-            const avg_pnl = metrics.reduce((s, m) => s + m.pnl_percent, 0) / count;
-            const avg_rr = metrics.reduce((s, m) => s + m.rr_ratio, 0) / count;
-            const avg_leverage = metrics.reduce((s, m) => s + m.leverage, 0) / count;
-            
-            const todayMetrics = { avg_holding_duration, avg_pnl, avg_rr, avg_leverage };
-
-            // 2. Create new 30-day history
-            const newHistory = [todayMetrics, ...yHistory].slice(0, 30);
-            
-            // 3. Calculate 30-day rolling averages
-            const historyCount = newHistory.length;
-            const roll_avg_duration = newHistory.reduce((s, m) => s + m.avg_holding_duration, 0) / historyCount;
-            const roll_avg_pnl = newHistory.reduce((s, m) => s + m.avg_pnl, 0) / historyCount;
-            const roll_avg_rr = newHistory.reduce((s, m) => s + m.avg_rr, 0) / historyCount;
-            const roll_avg_leverage = newHistory.reduce((s, m) => s + m.avg_leverage, 0) / historyCount;
-            
-            // 4. Calculate Conviction Score (example normalization)
-            // (Assumes a 0-1 range for normalization, then scales to 0-100)
-            const norm_duration = this._normalize(roll_avg_duration, 0, 240); // 0-10 days
-            const norm_pnl = this._normalize(roll_avg_pnl, -0.5, 0.5);       // -50% to +50%
-            const norm_rr = this._normalize(roll_avg_rr, 0, 3);            // 0 to 3 R:R
-            const norm_leverage = 1 - this._normalize(roll_avg_leverage, 1, 10); // 1x to 10x (inverted)
-
-            // Combine scores (equal weight for this example)
-            const score_pct = (norm_duration + norm_pnl + norm_rr + norm_leverage) / 4;
-            
-            result[ticker] = {
-                conviction_score: score_pct * 100, // Final score 0-100
-                roll_avg_holding_duration,
-                roll_avg_pnl,
-                roll_avg_rr,
-                roll_avg_leverage,
-                
-                // Also include today's raw averages
-                avg_holding_duration,
-                avg_pnl,
-                avg_rr,
-                avg_leverage,
-                
-                history: newHistory
-            };
-        }
-        return result;
-    }
-
-    reset() {
-        this.assetData.clear();
-        this.mappings = null;
-    }
-}
-
-module.exports = CrowdConvictionScore;

package/calculations/legacy/crowd_sharpe_ratio_proxy.js

@@ -1,137 +0,0 @@
-/**
- * @fileoverview Calculation (Pass 2) for crowd sharpe ratio proxy.
- *
- * This metric answers: "What is the crowd's risk-adjusted return
- * (Sharpe Ratio proxy) for each asset?"
- *
- * It uses the distribution of P&L from 'pnl_distribution_per_stock'
- * to calculate variance (risk).
- *
- * --- FIX: 2025-11-12 ---
- * Refactored this file to be a "meta" calculation.
- * 1. Removed constructor, getResult, reset, and the no-op 'process'.
- * 2. Added the required `async process(dStr, deps, config, fetchedDeps)` method.
- * 3. Moved all logic into `process`.
- * 4. Updated logic to read from `fetchedDeps['pnl_distribution_per_stock']`.
- * 5. Updated data access to read from the new `data.stats` object
- * provided by the fixed dependency.
- */
-const { loadInstrumentMappings } = require('../../utils/sector_mapping_provider');
-
-class CrowdSharpeRatioProxy {
-    /**
-     * Defines the output schema for this calculation.
-     * @returns {object} JSON Schema object
-     */
-    static getSchema() {
-        const tickerSchema = {
-            "type": "object",
-            "description": "Sharpe Ratio proxy metrics for a specific asset.",
-            "properties": {
-                "sharpe_ratio_proxy": {
-                    "type": "number",
-                    "description": "Risk-adjusted return proxy (Mean P&L / StdDev P&L). Assumes risk-free rate is 0."
-                },
-                "average_pnl": { "type": "number" },
-                "std_dev_pnl": { "type": "number" },
-                "variance_pnl": { "type": "number" },
-                "position_count": { "type": "number" }
-            },
-            "required": ["sharpe_ratio_proxy", "average_pnl", "std_dev_pnl", "position_count"]
-        };
-
-        return {
-            "type": "object",
-            "description": "Calculates a risk-adjusted return (Sharpe Ratio proxy) for each asset based on P&L distribution.",
-            "patternProperties": {
-                "^.*$": tickerSchema // Matches any string key (ticker)
-            },
-            "additionalProperties": tickerSchema
-        };
-    }
-
-    /**
-     * Statically declare dependencies.
-     */
-    static getDependencies() {
-        return [
-            'pnl_distribution_per_stock' // Pass 1
-        ];
-    }
-
-    /**
-     * --- FIX: This is the new main execution method for meta-calcs ---
-     * It receives all dependencies from the orchestrator.
-     */
-    async process(dateStr, dependencies, config, fetchedDependencies) {
-        // --- FIX: Load dependency data from the argument ---
-        const pnlDistData = fetchedDependencies['pnl_distribution_per_stock'];
-        
-        if (!pnlDistData) {
-            dependencies.logger.log('WARN', `[crowd_sharpe_ratio_proxy] Missing dependency 'pnl_distribution_per_stock' for ${dateStr}. Skipping.`);
-            return {};
-        }
-        
-        // --- FIX: Load mappings inside the process method ---
-        const mappings = await loadInstrumentMappings();
-        if (!mappings || !mappings.instrumentToTicker) {
-            dependencies.logger.log('ERROR', `[crowd_sharpe_ratio_proxy] Failed to load instrument mappings.`);
-            return {};
-        }
-
-        const result = {};
-
-        for (const [ticker, data] of Object.entries(pnlDistData)) {
-            
-            // --- FIX: Read from the new 'stats' sub-object ---
-            if (!data.stats) {
-                continue; // Skip if data is malformed
-            }
-            
-            const { sum, sumSq, count } = data.stats;
-            
-            if (count < 2) {
-                continue; // Need at least 2 data points for variance
-            }
-
-            // Calculate Mean (Average P&L)
-            const mean = sum / count;
-            
-            // Calculate Variance
-            // Var(X) = E[X^2] - (E[X])^2
-            const meanSq = sumSq / count;
-            const variance = meanSq - (mean * mean);
-            
-            // Handle potential float precision errors
-            if (variance < 0) {
-                continue;
-            }
-
-            // Calculate Standard Deviation (Risk)
-            const stdDev = Math.sqrt(variance);
-
-            if (stdDev === 0) {
-                continue; // No risk, Sharpe ratio is infinite/undefined
-            }
-
-            // Calculate Sharpe Ratio Proxy (assuming risk-free rate = 0)
-            // Sharpe = Mean(Return) / StdDev(Return)
-            const sharpeProxy = mean / stdDev;
-            
-            // --- FIX: Data is already keyed by ticker, no mapping needed ---
-            // const ticker = this.mappings.instrumentToTicker[instrumentId] || `id_${instrumentId}`;
-
-            result[ticker] = {
-                sharpe_ratio_proxy: sharpeProxy,
-                average_pnl: mean,
-                std_dev_pnl: stdDev,
-                variance_pnl: variance,
-                position_count: count
-            };
-        }
-        
-        return result;
-    }
-}
-
-module.exports = CrowdSharpeRatioProxy;