aiden-shared-calculations-unified 1.0.76 → 1.0.78

package/calculations/{sectors/total_short_per_sector.js → core/total-short-per-sector.js}

@@ -13,6 +13,28 @@ class TotalShortPerSector {
         this.mappings = null;
     }
 
+    // --- NEW ---
+    /**
+     * Statically defines all metadata for the manifest builder.
+     */
+    static getMetadata() {
+        return {
+            type: 'standard',
+            rootDataDependencies: ['portfolio'],
+            isHistorical: false,
+            userType: 'all',
+            category: 'core_sentiment'
+        };
+    }
+
+    // --- NEW ---
+    /**
+     * Statically declare dependencies.
+     */
+    static getDependencies() {
+        return [];
+    }
+
     /**
      * Defines the output schema for this calculation.
      * @returns {object} JSON Schema object

package/calculations/{sanity/users_processed.js → core/users-processed.js}

@@ -7,6 +7,28 @@ class UsersProcessed {
         this.userCount = 0;
     }
 
+    // --- NEW ---
+    /**
+     * Statically defines all metadata for the manifest builder.
+     */
+    static getMetadata() {
+        return {
+            type: 'standard',
+            rootDataDependencies: ['portfolio'], // Needs at least one doc to run
+            isHistorical: false,
+            userType: 'all',
+            category: 'core_sanity' // Based on Computation_documentation.md
+        };
+    }
+
+    // --- NEW ---
+    /**
+     * Statically declare dependencies.
+     */
+    static getDependencies() {
+        return [];
+    }
+
     /**
      * Defines the output schema for this calculation.
      * @returns {object} JSON Schema object

package/calculations/gauss/cohort-capital-flow.js

@@ -0,0 +1,217 @@
+/**
+ * @fileoverview GAUSS Product Line (Pass 3)
+ *
+ * This 'standard' calculation streams all user portfolios, tags
+ * each user with their "Gauss" cohort (from Pass 2), and calculates
+ * the price-adjusted capital flow for each cohort, per asset.
+ *
+ * This is the primary input for the final Pass 4 signal.
+ */
+const { loadInstrumentMappings } = require('../../utils/sector_mapping_provider');
+
+
+class CohortCapitalFlow {
+    constructor() {
+        // We will store: { [cohortName]: Map<instrumentId, { flow_data... }> }
+        this.cohortFlows = new Map();
+        // This will be a lookup map: { [userId]: "cohortName" }
+        this.cohortMap = new Map();
+        this.mappings = null;
+        this.dependenciesLoaded = false;
+    }
+
+    /**
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
+     */
+    static getSchema() {
+        const flowSchema = {
+            "type": "object",
+            "properties": {
+                "net_flow_percentage": { "type": "number" },
+                "net_flow_contribution": { "type": "number" }
+            },
+            "required": ["net_flow_percentage", "net_flow_contribution"]
+        };
+        
+        const cohortSchema = {
+            "type": "object",
+            "description": "Price-adjusted capital flow for all assets for a specific cohort.",
+            "patternProperties": { "^.*$": flowSchema }, // Ticker
+            "additionalProperties": flowSchema
+        };
+
+        return {
+            "type": "object",
+            "description": "Contains a map of cohort names to their asset flow data.",
+            "patternProperties": {
+                "^.*$": cohortSchema // Cohort Name
+            },
+            "additionalProperties": cohortSchema
+        };
+    }
+
+    /**
+     * Statically defines all metadata for the manifest builder.
+     */
+    static getMetadata() {
+        return {
+            type: 'standard',
+            rootDataDependencies: ['portfolio'],
+            isHistorical: true, // Needs T-1 portfolio for flow
+            userType: 'all',
+            category: 'gauss'
+        };
+    }
+
+    /**
+     * Statically declare dependencies.
+     */
+    static getDependencies() {
+        return [
+            'cohort-definer' // from gauss (Pass 2)
+        ];
+    }
+
+    _getPortfolioPositions(portfolio) {
+        // We MUST use AggregatedPositions for this to get 'Invested' (portfolio percentage)
+        return portfolio?.AggregatedPositions;
+    }
+
+    _initFlowData(cohortName, instrumentId) {
+        if (!this.cohortFlows.has(cohortName)) {
+            this.cohortFlows.set(cohortName, new Map());
+        }
+        if (!this.cohortFlows.get(cohortName).has(instrumentId)) {
+            this.cohortFlows.get(cohortName).set(instrumentId, {
+                total_invested_yesterday: 0,
+                total_invested_today: 0,
+                price_change_yesterday: 0, // This is a weighted sum
+            });
+        }
+    }
+    
+    /**
+     * Loads dependencies into memory on the first process() call.
+     */
+    _loadDependencies(fetchedDependencies) {
+        if (this.dependenciesLoaded) return;
+        
+        const cohortData = fetchedDependencies['cohort-definer'];
+        if (cohortData) {
+            for (const [cohortName, userIds] of Object.entries(cohortData)) {
+                for (const userId of userIds) {
+                    this.cohortMap.set(userId, cohortName);
+                }
+            }
+        }
+        this.dependenciesLoaded = true;
+    }
+
+    process(todayPortfolio, yesterdayPortfolio, userId, context, todayInsights, yesterdayInsights, fetchedDependencies) {
+        this._loadDependencies(fetchedDependencies);
+        
+        if (!this.mappings) {
+            this.mappings = context.mappings;
+        }
+
+        const cohortName = this.cohortMap.get(userId);
+        if (!cohortName) {
+            return; // This user is not in one of our defined cohorts, skip.
+        }
+        
+        if (!todayPortfolio || !yesterdayPortfolio) {
+            return;
+        }
+
+        const yPos = this._getPortfolioPositions(yesterdayPortfolio);
+        const tPos = this._getPortfolioPositions(todayPortfolio);
+
+        // We must have AggregatedPositions for both days to do this calculation
+        if (!yPos || !tPos) {
+            return;
+        }
+
+        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()]);
+
+        for (const instrumentId of allInstrumentIds) {
+            if (!instrumentId) continue;
+            
+            this._initFlowData(cohortName, instrumentId);
+            const asset = this.cohortFlows.get(cohortName).get(instrumentId);
+            
+            const yP = yPosMap.get(instrumentId);
+            const tP = tPosMap.get(instrumentId);
+            
+            // 'Invested' is the portfolio percentage (e.g., 5.0 = 5%)
+            const yInvested = yP?.Invested || 0; 
+            const tInvested = tP?.Invested || 0;
+
+            if (yInvested > 0) {
+                asset.total_invested_yesterday += yInvested;
+                // 'NetProfit' here is actually the 1-day P&L *as a percentage* (e.g., 0.1 for +10%)
+                const yPriceChange = (yP?.NetProfit || 0); 
+                asset.price_change_yesterday += yPriceChange * yInvested; // Weighted sum
+            }
+            if (tInvested > 0) {
+                asset.total_invested_today += tInvested;
+            }
+        }
+    }
+
+    async getResult() {
+        if (!this.mappings) {
+            this.mappings = await loadInstrumentMappings();
+        }
+
+        const finalResult = {};
+
+        for (const [cohortName, assetMap] of this.cohortFlows.entries()) {
+            const cohortAssets = {};
+            for (const [instrumentId, data] of assetMap.entries()) {
+                const ticker = this.mappings.instrumentToTicker[instrumentId];
+                if (!ticker) continue;
+                
+                const { total_invested_yesterday, total_invested_today, price_change_yesterday } = data;
+                
+                if (total_invested_yesterday > 0) {
+                    // 1. Find the weighted average price change for this cohort/asset
+                    // e.g., (0.1 * 5.0 + 0.05 * 2.0) / (5.0 + 2.0)
+                    const avg_price_change_pct = price_change_yesterday / total_invested_yesterday;
+                    
+                    // 2. Estimate yesterday's value *after* price change
+                    // (This is what the value *would be* if no one bought or sold)
+                    const price_adjusted_yesterday_value = total_invested_yesterday * (1 + avg_price_change_pct);
+
+                    // 3. The difference between today's value and the price-adjusted
+                    // value is the *net capital flow*.
+                    const flow_contribution = total_invested_today - price_adjusted_yesterday_value;
+
+                    // 4. Normalize the flow as a percentage of yesterday's capital
+                    const net_flow_percentage = (flow_contribution / total_invested_yesterday) * 100;
+                    
+                    if (isFinite(net_flow_percentage) && isFinite(flow_contribution)) {
+                        cohortAssets[ticker] = {
+                            net_flow_percentage: net_flow_percentage,
+                            net_flow_contribution: flow_contribution // This is the %-point flow
+                        };
+                    }
+                }
+            }
+            finalResult[cohortName] = { assets: cohortAssets };
+        }
+        // Output is compact and not sharded
+        return finalResult;
+    }
+
+    reset() {
+        this.cohortFlows.clear();
+        this.cohortMap.clear();
+        this.mappings = null;
+        this.dependenciesLoaded = false;
+    }
+}
+
+module.exports = CohortCapitalFlow;

package/calculations/gauss/cohort-definer.js

@@ -0,0 +1,211 @@
+/**
+ * @fileoverview GAUSS Product Line (Pass 2)
+ *
+ * This 'standard' calculation re-streams all users, filters for
+ * the "Smart" and "Dumb" cohorts (from Pass 1), and then calculates
+ * their full 4D "Trader DNA".
+ *
+ * It then buckets these users into our final, named sub-cohorts
+ * (e.g., "Smart Investors", "FOMO Chasers").
+ */
+const { loadInstrumentMappings } = require('../../utils/sector_mapping_provider');
+
+class CohortDefiner {
+    constructor() {
+        // We will store the full DNA for our filtered cohorts
+        this.smartVectors = []; // [ { userId, skill, time, fomo, bagholder }, ... ]
+        this.dumbVectors = [];  // [ { userId, skill, time, fomo, bagholder }, ... ]
+
+        this.momentumData = null;
+        this.mappings = null;
+        this.cohortIdSets = null; // { smart: Set, dumb: Set }
+    }
+
+    /** Statically defines metadata */
+    static getMetadata() {
+        return {
+            type: 'standard',
+            rootDataDependencies: ['portfolio', 'history'],
+            isHistorical: true,
+            userType: 'all',
+            category: 'gauss'
+        };
+    }
+
+    /** Statically declare dependencies */
+    static getDependencies() {
+        return [
+            'daily-dna-filter',              // from gauss (Pass 1)
+            'instrument-price-momentum-20d'  // from core (Pass 1)
+        ];
+    }
+
+    /**
+     * Defines the output schema for this calculation.
+     */
+    static getSchema() {
+        const cohortSchema = {
+            "type": "array",
+            "description": "A list of User IDs belonging to this cohort.",
+            "items": { "type": "string" }
+        };
+        
+        return {
+            "type": "object",
+            "description": "A map of named cohorts to the list of user IDs in each.",
+            "properties": {
+                "smart_investors": cohortSchema,
+                "smart_scalpers": cohortSchema,
+                "fomo_chasers": cohortSchema,
+                "patient_losers": cohortSchema,
+                "fomo_bagholders": cohortSchema
+            },
+            "additionalProperties": cohortSchema
+        };
+    }
+    
+    /**
+     * Loads dependencies into memory on the first process() call.
+     */
+    _loadDependencies(fetchedDependencies) {
+        if (this.cohortIdSets) return; // Run once
+        
+        const dnaFilterData = fetchedDependencies['daily-dna-filter'];
+        this.momentumData = fetchedDependencies['instrument-price-momentum-20d'];
+        
+        this.cohortIdSets = {
+            smart: new Set(dnaFilterData?.smart_cohort_ids || []),
+            dumb: new Set(dnaFilterData?.dumb_cohort_ids || [])
+        };
+    }
+
+    _getFomoScore(todayPortfolio, yesterdayPortfolio) {
+        if (!this.mappings) return 0;
+        const yIds = new Set((yesterdayPortfolio?.AggregatedPositions || []).map(p => p.InstrumentID));
+        const newPositions = (todayPortfolio?.AggregatedPositions || []).filter(p => p.InstrumentID && !yIds.has(p.InstrumentID));
+        if (newPositions.length === 0) return 0;
+
+        let fomoSum = 0;
+        let count = 0;
+        for (const pos of newPositions) {
+            const ticker = this.mappings.instrumentToTicker[pos.InstrumentID];
+            if (ticker && this.momentumData[ticker]) {
+                fomoSum += this.momentumData[ticker].momentum_20d_pct || 0;
+                count++;
+            }
+        }
+        return (count > 0) ? fomoSum / count : 0;
+    }
+
+    _getBagholderScore(todayPortfolio) {
+        const openPositions = todayPortfolio?.AggregatedPositions || [];
+        if (openPositions.length === 0) return 0;
+
+        let durationSum = 0;
+        let count = 0;
+        const now = new Date();
+
+        for (const pos of openPositions) {
+            // 'NetProfit' is a % P&L, e.g., -0.20 for -20%
+            if (pos.NetProfit < -0.20) {
+                try {
+                    const openDate = new Date(pos.OpenDateTime);
+                    const durationMs = now.getTime() - openDate.getTime();
+                    const durationDays = durationMs / (1000 * 60 * 60 * 24);
+                    if (isFinite(durationDays)) {
+                        durationSum += durationDays;
+                        count++;
+                    }
+                } catch (e) { /* ignore invalid date */ }
+            }
+        }
+        return (count > 0) ? durationSum / count : 0;
+    }
+
+    process(todayPortfolio, yesterdayPortfolio, userId, context, todayInsights, yesterdayInsights, fetchedDependencies) {
+        this._loadDependencies(fetchedDependencies);
+        if (!this.mappings) {
+            this.mappings = context.mappings;
+        }
+
+        const isSmart = this.cohortIdSets.smart.has(userId);
+        const isDumb = this.cohortIdSets.dumb.has(userId);
+
+        if (!isSmart && !isDumb) {
+            return; // Not in our extreme cohorts
+        }
+
+        // --- Re-calculate full DNA for this filtered user ---
+        
+        // 1. Get Long-Term (Stable) Traits
+        const history = todayPortfolio?.history?.all;
+        if (!history) return;
+        
+        const winRate = (history.winRatio || 0) / 100.0;
+        const lossRate = 1.0 - winRate;
+        const avgWin = history.avgProfitPct || 0;
+        const avgLoss = Math.abs(history.avgLossPct || 0);
+        const lt_skill = (winRate * avgWin) - (lossRate * avgLoss);
+        const lt_time = history.avgHoldingTimeInMinutes || 0;
+
+        // 2. Get Short-Term (Noisy) Traits
+        const st_fomo = this._getFomoScore(todayPortfolio, yesterdayPortfolio);
+        const st_bagholder = this._getBagholderScore(todayPortfolio);
+
+        const vector = { userId, skill: lt_skill, time: lt_time, fomo: st_fomo, bagholder: st_bagholder };
+
+        if (isSmart) {
+            this.smartVectors.push(vector);
+        } else if (isDumb) {
+            this.dumbVectors.push(vector);
+        }
+    }
+
+    _getMedian(vectors, key) {
+        if (vectors.length === 0) return 0;
+        const sorted = vectors.map(v => v[key]).sort((a, b) => a - b);
+        const mid = Math.floor(sorted.length / 2);
+        return sorted[mid];
+    }
+
+    getResult() {
+        const cohorts = {};
+
+        // 1. Process Smart Cohort
+        const smart_median_time = this._getMedian(this.smartVectors, 'time');
+        cohorts['smart_investors'] = this.smartVectors
+            .filter(u => u.time >= smart_median_time)
+            .map(u => u.userId);
+        cohorts['smart_scalpers'] = this.smartVectors
+            .filter(u => u.time < smart_median_time)
+            .map(u => u.userId);
+            
+        // 2. Process Dumb Cohort
+        const dumb_median_fomo = this._getMedian(this.dumbVectors, 'fomo');
+        const dumb_median_bag = this._getMedian(this.dumbVectors, 'bagholder');
+
+        cohorts['fomo_chasers'] = this.dumbVectors
+            .filter(u => u.fomo >= dumb_median_fomo && u.bagholder < dumb_median_bag)
+            .map(u => u.userId);
+        
+        cohorts['patient_losers'] = this.dumbVectors
+            .filter(u => u.fomo < dumb_median_fomo && u.bagholder >= dumb_median_bag)
+            .map(u => u.userId);
+
+        cohorts['fomo_bagholders'] = this.dumbVectors
+            .filter(u => u.fomo >= dumb_median_fomo && u.bagholder >= dumb_median_bag)
+            .map(u => u.userId);
+
+        // Output is a compact map of cohort_name -> [userIds]
+        return cohorts;
+    }
+    
+    reset() {
+        this.smartVectors = [];
+        this.dumbVectors = [];
+        this.momentumData = null;
+        this.mappings = null;
+        this.cohortIdSets = null;
+    }
+}
+module.exports = CohortDefiner;

package/calculations/gauss/daily-dna-filter.js

@@ -0,0 +1,130 @@
+/**
+ * @fileoverview GAUSS Product Line (Pass 1)
+ *
+ * This metric is a *filter*. It processes all users and calculates
+ * their "Long-Term Skill" (Expectancy) from their 'history' doc.
+ *
+ * It then filters this list to *only* return the User IDs
+ * of the top 20% (Smart) and bottom 20% (Dumb) of users,
+ * solving the 1MB document limit for downstream processing.
+ */
+class DailyDnaFilter {
+    constructor() {
+        // We will store all users and their primary skill score
+        // [ [userId, skillScore], ... ]
+        this.allUserSkills = [];
+    }
+
+    /**
+     * Statically defines all metadata for the manifest builder.
+     */
+    static getMetadata() {
+        return {
+            type: 'standard',
+            // This calc only needs the 'history' doc,
+            // which is passed inside the portfolio object.
+            rootDataDependencies: ['history'],
+            isHistorical: false, // Reads today's history snapshot
+            userType: 'all',
+            category: 'gauss'
+        };
+    }
+
+    /**
+     * Statically declare dependencies.
+     */
+    static getDependencies() {
+        return []; // This is a Pass 1 calculation
+    }
+
+    /**
+     * Defines the output schema for this calculation.
+     */
+    static getSchema() {
+        return {
+            "type": "object",
+            "description": "Provides the User ID lists for the 'Smart' (top 20%) and 'Dumb' (bottom 20%) cohorts based on long-term Expectancy.",
+            "properties": {
+                "smart_cohort_ids": {
+                    "type": "array",
+                    "description": "List of user IDs in the top 20% 'Smart' cohort.",
+                    "items": { "type": "string" }
+                },
+                "dumb_cohort_ids": {
+                    "type": "array",
+                    "description": "List of user IDs in the bottom 20% 'Dumb' cohort.",
+                    "items": { "type": "string" }
+                },
+                "total_users_analyzed": { "type": "number" },
+                "cohort_size": { "type": "number" }
+            },
+            "required": ["smart_cohort_ids", "dumb_cohort_ids", "total_users_analyzed", "cohort_size"]
+        };
+    }
+
+
+    /**
+     * Processes a single user's daily data.
+     * @param {object} todayPortfolio - Today's portfolio snapshot.
+     * @param {object} yesterdayPortfolio - Yesterday's portfolio snapshot.
+     * @param {string} userId - The user's ID.
+     */
+    process(todayPortfolio, yesterdayPortfolio, userId) {
+        // 1. Get Long-Term (Stable) Traits from history
+        const history = todayPortfolio?.history?.all;
+        if (!history || !history.totalTrades || history.totalTrades < 20) {
+            return; // Not enough history for a reliable score
+        }
+        
+        const winRate = (history.winRatio || 0) / 100.0;
+        const lossRate = 1.0 - winRate;
+        const avgWin = history.avgProfitPct || 0;
+        // Use Math.abs because avgLossPct is stored as a negative number
+        const avgLoss = Math.abs(history.avgLossPct || 0); 
+        
+        // Expectancy = (Win % * Avg Win %) - (Loss % * Avg Loss %)
+        const lt_skill = (winRate * avgWin) - (lossRate * avgLoss);
+
+        if (!isFinite(lt_skill)) {
+            return; // Skip bad data (e.g., division by zero)
+        }
+
+        this.allUserSkills.push([userId, lt_skill]);
+    }
+
+    /**
+     * Returns the final filtered list of user IDs.
+     */
+    getResult() {
+        const totalUsers = this.allUserSkills.length;
+        if (totalUsers === 0) {
+            return { smart_cohort_ids: [], dumb_cohort_ids: [], total_users_analyzed: 0, cohort_size: 0 };
+        }
+
+        // Sort by Skill (Expectancy) in descending order (highest skill first)
+        this.allUserSkills.sort((a, b) => b[1] - a[1]);
+        
+        const cohortSize = Math.floor(totalUsers * 0.20); // Top/Bottom 20%
+        if (cohortSize === 0) {
+            return { smart_cohort_ids: [], dumb_cohort_ids: [], total_users_analyzed: totalUsers, cohort_size: 0 };
+        }
+
+        // Get the top 20% (smartest)
+        const smart_cohort_ids = this.allUserSkills.slice(0, cohortSize).map(u => u[0]);
+        // Get the bottom 20% (dumbest)
+        const dumb_cohort_ids = this.allUserSkills.slice(-cohortSize).map(u => u[0]);
+
+        // Output is now small and compact, solving the 1MB limit.
+        return {
+            smart_cohort_ids: smart_cohort_ids,
+            dumb_cohort_ids: dumb_cohort_ids,
+            total_users_analyzed: totalUsers,
+            cohort_size: cohortSize
+        };
+    }
+    
+    reset() {
+        this.allUserSkills = [];
+    }
+}
+module.exports = DailyDnaFilter;