bulltrackers-module 1.0.172 → 1.0.174

package/functions/computation-system/layers/math_primitives.js

@@ -11,7 +11,7 @@ const SCHEMAS = {
     USER_TYPES: { NORMAL: 'normal', SPECULATOR: 'speculator' }
 };
 
-class DataExtractor {
+class DataExtractor { // For generic access of data types
     // ========================================================================
     // 1. COLLECTION ACCESSORS
     // ========================================================================
@@ -22,10 +22,10 @@ class DataExtractor {
      * - Speculator: Uses 'PublicPositions' (Individual Trades)
      */
     static getPositions(portfolio, userType) {
-        if (!portfolio) return [];
+        if (!portfolio) return []; // Handle empty portfolio
         
-        if (userType === SCHEMAS.USER_TYPES.SPECULATOR) {
-            return portfolio.PublicPositions || [];
+        if (userType === SCHEMAS.USER_TYPES.SPECULATOR) { 
+            return portfolio.PublicPositions || []; // SPECULATOR SCHEMA
         }
         
         // Default to Normal User Schema
@@ -40,7 +40,7 @@ class DataExtractor {
      * Extract standardized Instrument ID.
      */
     static getInstrumentId(position) {
-        if (!position) return null;
+        if (!position) return null; // Handle empty position data
         // Handle string or number variations safely
         return position.InstrumentID || position.instrumentId || null;
     }
@@ -51,7 +51,7 @@ class DataExtractor {
      * - Normal: Generates Composite Key (InstrumentID_Direction) since they lack unique Trade IDs.
      */
     static getPositionId(position) {
-        if (!position) return null;
+        if (!position) return null; // Handle empty position data
         
         // 1. Try Explicit ID (Speculators)
         if (position.PositionID) return String(position.PositionID);
@@ -59,7 +59,7 @@ class DataExtractor {
 
         // 2. Fallback to Composite Key (Normal Users)
         const instId = this.getInstrumentId(position);
-        const dir = this.getDirection(position);
+        const dir    = this.getDirection(position);
         if (instId) return `${instId}_${dir}`;
 
         return null;
@@ -73,7 +73,7 @@ class DataExtractor {
      * Extract Net Profit %.
      * Schema: 'NetProfit' is the percentage profit relative to invested capital.
      */
-    static getNetProfit(position) {
+    static getNetProfit(position) { 
         return position ? (position.NetProfit || 0) : 0;
     }
 
@@ -83,7 +83,7 @@ class DataExtractor {
      * - Normal: 'Invested' is % of initial capital.
      * - Speculator: 'Invested' (or 'Amount' in some contexts) is % of initial capital.
      */
-    static getPositionWeight(position, userType) {
+    static getPositionWeight(position, userType) { // Agnostic on user type, unused.
         if (!position) return 0;
         
         // Both schemas use 'Invested' to represent the allocation percentage.
@@ -95,8 +95,23 @@ class DataExtractor {
      * Extract Current Equity Value %.
      * Schema: 'Value' is the current value as a % of total portfolio equity.
      */
-    static getPositionValuePct(position) {
-        return position ? (position.Value || 0) : 0;
+    static getPositionValuePct(position) {            // TODO - VERIFY THIS WORKS FOR SPECULATORS,
+        return position ? (position.Value || 0) : 0; //  IS VALUE ACTUALLY THE VALUE OF POSITION AS A % OF TOTAL PORTFOLIO EQUITY? IS IT THE SAME FOR NORMAL USERS?
+    }
+
+    /**
+     * --- NEW PRIMITIVE ---
+     * Derives the approximate Entry Price of a position based on Current Price and Net Profit %.
+     * Formula: Entry = Current / (1 + (NetProfit / 100))
+     * @param {number} currentPrice - The current market price of the asset.
+     * @param {number} netProfitPct - The Net Profit percentage (e.g., -20.5).
+     * @returns {number} Estimated Entry Price.
+     */
+    static deriveEntryPrice(currentPrice, netProfitPct) {
+        if (!currentPrice || currentPrice <= 0) return 0;
+        // Avoid division by zero if P&L is -100% (unlikely but possible in crypto/options)
+        if (netProfitPct <= -100) return Number.MAX_SAFE_INTEGER; // Effectively infinite entry price (lost everything)
+        return currentPrice / (1 + (netProfitPct / 100.0));
     }
 
     // ========================================================================
@@ -109,12 +124,13 @@ class DataExtractor {
     static getPortfolioDailyPnl(portfolio, userType) {
         if (!portfolio) return 0;
         
-        // 1. Speculator (Explicit 'NetProfit' field on root)
-        if (userType === SCHEMAS.USER_TYPES.SPECULATOR) {
-            return portfolio.NetProfit || 0;
+        // 1. Speculator (Explicit 'NetProfit' field on root) ---> TODO : THIS IS FLAWED,
+        if (userType === SCHEMAS.USER_TYPES.SPECULATOR) {       //  SPECULATOR DATA DOES NOT CONTAIN THE ENTIRE PORTFOLIO DATA FOR THAT USER, IT CONTAINS A SNAPSHOT OF THE USERS' SPECIFIC ASSET WE REQUESTED FROM THE TASK ENGINE
+                                                                // You cannot ever infer the entire speculator portfolio daily / weekly / monthly or any time period value based on the data we have for speculators
+            return portfolio.NetProfit || 0;                    // Data for speculators only works when we are looking at the ticker-specific data, or the trade history data which is agnostic on user type
         }
         
-        // 2. Normal (Aggregated Calculation)
+        // 2. Normal (Aggregated Calculation) ---> TODO : VERIFY THIS LOGIC, IT SHOULD BE OK
         // Logic: Sum(Value - Invested) across the 'InstrumentType' breakdown
         // This gives the net performance change for the day relative to the portfolio.
         if (portfolio.AggregatedPositionsByInstrumentTypeID) {
@@ -138,27 +154,36 @@ class DataExtractor {
     }
 
     static getLeverage(position) {
-        return position ? (position.Leverage || 1) : 1;
+        return position ? (position.Leverage || 1) : 1; // Default 1 IF NOT FOUND
     }
 
     static getOpenRate(position) {
-        return position ? (position.OpenRate || 0) : 0;
+        return position ? (position.OpenRate || 0) : 0; // Default 0 IF NOT FOUND
     }
 
     static getCurrentRate(position) {
-        return position ? (position.CurrentRate || 0) : 0;
+        return position ? (position.CurrentRate || 0) : 0; // Default 0 IF NOT FOUND
     }
 
     static getStopLossRate(position) {
-        return position ? (position.StopLossRate || 0) : 0;
-    }
+        const rate = position ? (position.StopLossRate || 0) : 0; 
+        // Fix for eToro bug: SL disabled positions can return 0.01 or similar small values.
+        // If the rate is positive but extremely small (<= 0.01), treat as 0 (disabled).
+        if (rate > 0 && rate <= 0.01) return 0; // Normalizes bug value to 0
+        if (rate < 0) return 0;
+        return rate;
+    }                                                       
 
     static getTakeProfitRate(position) {
-        return position ? (position.TakeProfitRate || 0) : 0;
+        const rate = position ? (position.TakeProfitRate || 0) : 0;
+        // Fix for eToro bug: TP disabled positions can return INF or small values.
+        // If the rate is positive but extremely small (<= 0.01), treat as 0 (disabled).
+        if (rate > 0 && rate <= 0.01) return 0; // Normalizes bug value to 0
+        return rate;
     }
 
     static getHasTSL(position) {
-        return position ? (position.HasTrailingStopLoss === true) : false;
+        return position ? (position.HasTrailingStopLoss === true) : false; // Default false IF NOT FOUND
     }
 
     /**
@@ -166,11 +191,76 @@ class DataExtractor {
      * Used for bagholder calculations.
      */
     static getOpenDateTime(position) {
-        if (!position || !position.OpenDateTime) return null;
+        if (!position || !position.OpenDateTime) return null;        
         return new Date(position.OpenDateTime);
     }
 }
 
+/**
+ * --- NEW CLASS: priceExtractor ---
+ * Handles schema-aware extraction of asset price history.
+ * Mitigates typo risk by centralizing access to context.prices.
+ */
+class priceExtractor {
+    /**
+     * Retrieves the sorted price history for a specific instrument.
+     * @param {object} pricesContext - The global context.prices object.
+     * @param {string|number} tickerOrId - The Ticker or InstrumentID to fetch.
+     * @returns {Array<{date: string, price: number}>} Sorted array of price objects.
+     */
+    static getHistory(pricesContext, tickerOrId) {
+        if (!pricesContext || !pricesContext.history) return [];
+        
+        // The history map is keyed by InstrumentID (e.g., "10000")
+        // We iterate to find the entry matching the request (by ID or Ticker)
+        // Optimization: If input is ID, direct lookup. If ticker, search.
+        
+        let assetData = pricesContext.history[tickerOrId];
+        
+        // Fallback: If direct lookup failed, maybe it's a ticker symbol?
+        if (!assetData) {
+            const id = Object.keys(pricesContext.history).find(key => {
+                const data = pricesContext.history[key];
+                return data.ticker === tickerOrId;
+            });
+            if (id) assetData = pricesContext.history[id];
+        }
+
+        if (!assetData || !assetData.prices) return [];
+
+        // Convert Map<Date, Price> to Array<{date, price}> and sort
+        const priceMap = assetData.prices;
+        const sortedDates = Object.keys(priceMap).sort((a, b) => a.localeCompare(b));
+        
+        return sortedDates.map(date => ({
+            date: date,
+            price: priceMap[date]
+        })).filter(item => item.price > 0);
+    }
+
+    /**
+     * Returns all available assets with their histories.
+     * Useful for computations iterating over the entire market.
+     * @param {object} pricesContext - The global context.prices object.
+     * @returns {Map<string, Array<{date: string, price: number}>>} Map<Ticker, HistoryArray>
+     */
+    static getAllHistories(pricesContext) {
+        if (!pricesContext || !pricesContext.history) return new Map();
+        
+        const results = new Map();
+        for (const [id, data] of Object.entries(pricesContext.history)) {
+            const ticker = data.ticker || id;
+            // Reuse the single-asset logic for consistency, though slightly less efficient
+            // than inlining the sort. For safety/DRY, we reuse.
+            const history = this.getHistory(pricesContext, id);
+            if (history.length > 0) {
+                results.set(ticker, history);
+            }
+        }
+        return results;
+    }
+}
+
 class HistoryExtractor {
     // --- Schema Accessor (NEW) ---
     /**
@@ -187,23 +277,23 @@ class HistoryExtractor {
         return historyDoc.assets;
     }
 
-    static getInstrumentId(asset) {
+    static getInstrumentId(asset) { 
         return asset ? asset.instrumentId : null;
     }
 
-    static getAvgHoldingTimeMinutes(asset) {
+    static getAvgHoldingTimeMinutes(asset) { // Note, in minutes, we could convert values here into hours or days but we leave as-is for now.
         return asset ? (asset.avgHoldingTimeInMinutes || 0) : 0;
     }
 
-    static getSummary(historyDoc) {
+    static getSummary(historyDoc) { // This returns the top-level summary of trade history
         const all = historyDoc?.all;
         if (!all) return null;
 
-        return {
-            totalTrades: all.totalTrades || 0,
-            winRatio: all.winRatio || 0,
-            avgProfitPct: all.avgProfitPct || 0,
-            avgLossPct: all.avgLossPct || 0,
+        return { // The all object contains instrumentid of -1 value, we do not include this, it's a junk backend-eToro placeholder.
+            totalTrades:             all.totalTrades             || 0,
+            winRatio:                all.winRatio                || 0,
+            avgProfitPct:            all.avgProfitPct            || 0,
+            avgLossPct:              all.avgLossPct              || 0,
             avgHoldingTimeInMinutes: all.avgHoldingTimeInMinutes || 0
         };
     }
@@ -242,7 +332,7 @@ class SignalPrimitives {
      * Hyperbolic Tangent Normalization.
      * Maps inputs to a strict -Scale to +Scale range.
      */
-    static normalizeTanh(value, scale = 10, sensitivity = 10.0) {
+    static normalizeTanh(value, scale = 10, sensitivity = 10.0) { // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/tanh
         if (value === 0) return 0;
         return Math.tanh(value / sensitivity) * scale;
     }
@@ -250,7 +340,7 @@ class SignalPrimitives {
     /**
      * Standard Z-Score normalization.
      */
-    static normalizeZScore(value, mean, stdDev) {
+    static normalizeZScore(value, mean, stdDev) { // https://gist.github.com/Restuta/5cbf1d186f17febe5e899febb63e1b86
         if (!stdDev || stdDev === 0) return 0;
         return (value - mean) / stdDev;
     }
@@ -261,6 +351,18 @@ class SignalPrimitives {
     static divergence(valueA, valueB) {
         return (valueA || 0) - (valueB || 0);
     }
+
+    static getPreviousState(previousComputed, calcName, ticker, fieldName = null) { // This is used for either fetching computations listed in getdependencies() OR self-history
+        if (!previousComputed || !previousComputed[calcName]) return null;          // Using this for self-history DOES NOT cause a circular dependency because we assign a special rule in orchestration_helpers
+                                                                                    // Which handles the self-reference, see 2. SMART SELF-FETCH in orchestration_helpers
+        const tickerData = previousComputed[calcName][ticker];
+        if (!tickerData) return null;
+
+        if (fieldName) {
+             return tickerData[fieldName];
+        }
+        return tickerData; // Return whole object (useful for _state)
+    }
 }
 
 class MathPrimitives {
@@ -288,6 +390,146 @@ class MathPrimitives {
     static bucketBinary(value, threshold = 0) {
         return value > threshold ? 'winner' : 'loser';
     }
+
+    /**
+     * Calculates the probability of an asset hitting a specific price barrier (Stop Loss/Take Profit)
+     * within a given timeframe using the First Passage Time of Geometric Brownian Motion.
+     * * Formula: P(T < t) = Φ((b - vt) / σ√t) + exp(2vb/σ²) * Φ((b + vt) / σ√t)
+     * Where: 
+     * b = ln(Barrier/Price)
+     * v = drift - 0.5 * volatility^2
+     * * @param {number} currentPrice - The current price of the asset
+     * @param {number} barrierPrice - The target price (SL or TP)
+     * @param {number} volatility - Annualized volatility (e.g., 0.40 for 40%)
+     * @param {number} days - Number of days to forecast (e.g., 3)
+     * @param {number} drift - (Optional) Annualized drift. Default 0 (Risk Neutral).
+     * @returns {number} Probability (0.0 to 1.0)
+     */
+    static calculateHitProbability(currentPrice, barrierPrice, volatility, days, drift = 0) { // https://www.ma.ic.ac.uk/~bin06/M3A22/m3f22chVII.pdf
+        if (currentPrice <= 0 || barrierPrice <= 0 || volatility <= 0 || days <= 0) return 0;
+
+        const t = days / 365.0; // Convert days to years
+        const sigma = volatility;
+        const mu = drift;
+        
+        // The barrier in log-space
+        const b = Math.log(barrierPrice / currentPrice);
+        
+        // Adjusted drift (nu)
+        const nu = mu - 0.5 * Math.pow(sigma, 2);
+
+        const sqrtT = Math.sqrt(t);
+        const sigmaSqrtT = sigma * sqrtT;
+
+        // Helper for Standard Normal CDF (Φ)
+        const normCDF = (x) => {
+            const t = 1 / (1 + 0.2316419 * Math.abs(x));
+            const d = 0.3989423 * Math.exp(-x * x / 2);
+            const prob = d * t * (0.3193815 + t * (-0.3565638 + t * (1.781478 + t * (-1.821256 + t * 1.330274))));
+            return x > 0 ? 1 - prob : prob;
+        };
+
+        // Standard First Passage Time Formula parts
+        const term1 = (b - nu * t) / sigmaSqrtT;
+        const term2 = (2 * nu * b) / (sigma * sigma);
+        const term3 = (b + nu * t) / sigmaSqrtT;
+
+        // If barrier is below price (Stop Loss for Long), b is negative.
+        // If barrier is above price (Take Profit for Long), we flip the logic essentially,
+        // but the formula works for the distance. 
+        // However, for strict GBM hitting time, we usually treat 'b' as the distance.
+        // For this implementation, we check direction relative to barrier.
+        
+        // If we are already at or past the barrier, probability is 100%
+        if ((currentPrice > barrierPrice && barrierPrice > currentPrice) || 
+            (currentPrice < barrierPrice && barrierPrice < currentPrice)) {
+             return 1.0;
+        }
+
+        // Calculate Probability
+        // Note: If nu is 0, the second term simplifies significantly, but we keep full form.
+        const probability = normCDF(( -Math.abs(b) - nu * t ) / sigmaSqrtT) + 
+                            Math.exp((2 * nu * Math.abs(b)) / (sigma * sigma)) * normCDF(( -Math.abs(b) + nu * t ) / sigmaSqrtT);
+
+        return Math.min(Math.max(probability, 0), 1);
+    }
+
+    /**
+     * --- NEW PRIMITIVE ---
+     * Simulates future price paths using Geometric Brownian Motion (Monte Carlo).
+     * Used for testing portfolio resilience against potential market moves.
+     * @param {number} currentPrice - S0
+     * @param {number} volatility - Annualized volatility (sigma)
+     * @param {number} days - Time horizon in days (t)
+     * @param {number} simulations - Number of paths to generate (e.g., 1000)
+     * @param {number} drift - Annualized drift (mu), default 0
+     * @returns {Float32Array} Array of simulated end prices
+     */
+    static simulateGBM(currentPrice, volatility, days, simulations = 1000, drift = 0) {
+        if (currentPrice <= 0 || volatility <= 0 || days <= 0) return new Float32Array(0);
+        
+        const t = days / 365.0;
+        const sigma = volatility;
+        const mu = drift;
+        const driftTerm = (mu - 0.5 * sigma * sigma) * t;
+        const volTerm = sigma * Math.sqrt(t);
+        
+        // Use Float32Array for memory efficiency with large simulation counts
+        const results = new Float32Array(simulations);
+        
+        for (let i = 0; i < simulations; i++) {
+            // Box-Muller transform for efficient standard normal distribution generation
+            const u1 = Math.random();
+            const u2 = Math.random();
+            const z = Math.sqrt(-2.0 * Math.log(u1)) * Math.cos(2.0 * Math.PI * u2);
+            
+            // GBM Formula: St = S0 * exp((mu - 0.5*sigma^2)t + sigma*Wt)
+            results[i] = currentPrice * Math.exp(driftTerm + volTerm * z);
+        }
+        return results;
+    }
+
+    /**
+     * --- NEW PRIMITIVE ---
+     * Simulates "Population Breakdown" (Capitulation) Risk.
+     * Correlates simulated price drops with user pain thresholds.
+     * @param {Float32Array} pricePaths - Array of simulated prices (from simulateGBM).
+     * @param {Array<{entryPrice: number, thresholdPct: number}>} userProfiles - Array of user states.
+     * @returns {number} Expected % of population that capitulates (0.0 - 1.0).
+     */
+    static simulatePopulationBreakdown(pricePaths, userProfiles) {
+        if (!pricePaths.length || !userProfiles.length) return 0;
+        
+        let totalBreakdownEvents = 0;
+        const totalSims = pricePaths.length;
+        const totalUsers = userProfiles.length;
+
+        // For each simulated future price scenario...
+        for (let i = 0; i < totalSims; i++) {
+            const simPrice = pricePaths[i];
+            let capitulatedUsersInScenario = 0;
+
+            // ...check every user to see if they survive
+            for (let j = 0; j < totalUsers; j++) {
+                const user = userProfiles[j];
+                // Calculate hypothetical P&L for this user in this scenario
+                // P&L% = (CurrentValue - EntryValue) / EntryValue
+                const hypotheticalPnL = ((simPrice - user.entryPrice) / user.entryPrice) * 100;
+                
+                // If hypothetical P&L is worse (lower) than their historical pain threshold, they capitulate.
+                // Note: thresholdPct is typically negative (e.g., -15.0)
+                if (hypotheticalPnL < user.thresholdPct) {
+                    capitulatedUsersInScenario++;
+                }
+            }
+            
+            // Add the % of users who broke in this scenario to the accumulator
+            totalBreakdownEvents += (capitulatedUsersInScenario / totalUsers);
+        }
+        
+        // Return the average capitulation rate across all simulations
+        return totalBreakdownEvents / totalSims;
+    }
 }
 
 class Aggregators {
@@ -295,11 +537,11 @@ class Aggregators {
      * Helper to bucket users by P&L Status.
      * Used by legacy systems or specific aggregators.
      */
-    static bucketUsersByPnlPerAsset(usersData, tickerMap) {
+    static bucketUsersByPnlPerAsset(usersData, tickerMap) { // https://www.geeksforgeeks.org/javascript/bucket-sort-visualization-using-javascript/
         const buckets = new Map();
         for (const [userId, portfolio] of Object.entries(usersData)) {
-            // Auto-detect type if not provided (Legacy compatibility)
-            const userType = portfolio.PublicPositions ? SCHEMAS.USER_TYPES.SPECULATOR : SCHEMAS.USER_TYPES.NORMAL;
+            // Auto-detect type if not provided (Legacy compatibility) TODO : We do not need legacy compatability, legacy computations do not run.
+            const userType  = portfolio.PublicPositions ? SCHEMAS.USER_TYPES.SPECULATOR : SCHEMAS.USER_TYPES.NORMAL;
             const positions = DataExtractor.getPositions(portfolio, userType);
             
             for (const pos of positions) {
@@ -319,12 +561,42 @@ class Aggregators {
         }
         return Object.fromEntries(buckets);
     }
+
+    /**
+     * --- NEW PRIMITIVE ---
+     * Calculates Weighted Sentiment (Avg P&L) for a set of positions.
+     * Solves "Dirty Data" / Variable N issue by weighting by investment size.
+     * @param {Array} positions - Array of raw position objects.
+     * @returns {number} Weighted Average NetProfit %.
+     */
+    static getWeightedSentiment(positions) {
+        if (!positions || positions.length === 0) return 0;
+
+        let totalWeightedPnL = 0;
+        let totalWeight = 0;
+
+        for (const pos of positions) {
+            // Use DataExtractor to be safe and schema-agnostic
+            const pnl = DataExtractor.getNetProfit(pos);
+            const weight = DataExtractor.getPositionWeight(pos); // 'Invested' or 'Amount'
+
+            if (weight > 0) {
+                totalWeightedPnL += (pnl * weight);
+                totalWeight += weight;
+            }
+        }
+
+        if (totalWeight === 0) return 0;
+        return totalWeightedPnL / totalWeight;
+    }
 }
 
+// Validation layer -- Used to validate the data incoming 
 class Validators {
     static validatePortfolio(portfolio, userType) {
         if (!portfolio) return { valid: false, errors: ['Portfolio is null'] };
         
+        // Handle both types of schema
         if (userType === SCHEMAS.USER_TYPES.SPECULATOR) {
              if (!portfolio.PublicPositions) return { valid: false, errors: ['Missing PublicPositions'] };
         } else {
@@ -335,12 +607,141 @@ class Validators {
     }
 }
 
-module.exports = { 
-    SCHEMAS, 
-    DataExtractor, 
-    HistoryExtractor, 
-    MathPrimitives, 
-    Aggregators, 
-    Validators, 
-    SignalPrimitives 
+class TimeSeries {
+    /**
+     * Updates a Rolling Mean and Variance using Welford's Online Algorithm (EMA variant). // https://jonisalonen.com/2013/deriving-welfords-method-for-computing-variance/
+     * @param {number} value - New data point.
+     * @param {Object} state - { mean: number, variance: number }
+     * @param {number} alpha - Decay factor (e.g., 0.1 for ~20 days).
+     */
+    static updateEMAState(value, state, alpha = 0.1) {
+        const mean = state ? (state.mean || 0) : 0;
+        const variance = state ? (state.variance || 1) : 1; // Default variance 1 to avoid div/0
+
+        if (value === undefined || value === null || isNaN(value)) {
+            return { mean, variance };
+        }
+
+        // EMA Update for Mean
+        const diff = value - mean;
+        const newMean = mean + (alpha * diff);
+
+        // EMA Update for Variance
+        const newVariance = (1 - alpha) * (variance + (alpha * diff * diff));
+
+        return { mean: newMean, variance: newVariance };
+    }
+
+    /**
+     * Calculates Pearson Correlation between two arrays. https://gist.github.com/matt-west/6500993
+     */
+    static pearsonCorrelation(x, y) {
+        if (!x || !y || x.length !== y.length || x.length === 0) return 0;
+        
+        const n = x.length;
+        // Simple sums
+        let sumX = 0, sumY = 0, sumXY = 0, sumX2 = 0, sumY2 = 0;
+
+        for (let i = 0; i < n; i++) {
+            sumX += x[i];
+            sumY += y[i];
+            sumXY += x[i] * y[i];
+            sumX2 += x[i] * x[i];
+            sumY2 += y[i] * y[i];
+        }
+
+        const numerator = (n * sumXY) - (sumX * sumY);
+        const denominator = Math.sqrt(((n * sumX2) - (sumX * sumX)) * ((n * sumY2) - (sumY * sumY)));
+
+        return (denominator === 0) ? 0 : numerator / denominator;
+    }
+}
+
+
+class DistributionAnalytics {
+    /**
+     * Gaussian Kernel Density Estimation (KDE)
+     * Converts discrete price points into a continuous probability density curve.
+     * Optimized for memory: accepts pre-binned data.
+     * @param {Array<{value: number, weight: number}>} data - Points or Bins.
+     * @param {number} bandwidth - Smoothing factor (h).
+     * @param {number} steps - Resolution of the output curve.
+     */
+    static computeKDE(data, bandwidth, steps = 60) {
+        if (!data || data.length === 0) return [];
+
+        let min = Infinity, max = -Infinity;
+        for (const p of data) {
+            if (p.value < min) min = p.value;
+            if (p.value > max) max = p.value;
+        }
+        
+        // Pad range to capture tails
+        min -= bandwidth * 3;
+        max += bandwidth * 3;
+        const stepSize = (max - min) / steps;
+        const curve = [];
+
+        for (let i = 0; i <= steps; i++) {
+            const x = min + (i * stepSize);
+            let density = 0;
+            // Vectorized-like summation https://cvw.cac.cornell.edu/vector/intro/how-vector-works#:~:text=Vectorization%20is%20a%20process%20by,performance%20increases%20obtained%20by%20vectorization.
+            for (const p of data) {
+                const diff = (x - p.value);
+                // Optimization: Skip calculation for points too far away (> 3 std devs)
+                if (Math.abs(diff) > bandwidth * 3) continue;
+                
+                const u = diff / bandwidth;
+                const k = 0.39894228 * Math.exp(-0.5 * u * u); // Standard Normal PDF
+                density += (p.weight * k) / bandwidth;
+            }
+            if (density > 0) curve.push({ price: x, density });
+        }
+        return curve;
+    }
+
+    static integrateProfile(curve, startPrice, endPrice) {
+        let sum = 0;
+        for (let i = 0; i < curve.length - 1; i++) {
+            const p1 = curve[i];
+            const p2 = curve[i+1];
+            if (p1.price >= startPrice && p2.price <= endPrice) {
+                // Trapezoidal Rule https://www.khanacademy.org/math/ap-calculus-ab/ab-integration-new/ab-6-2/a/understanding-the-trapezoid-rule
+                sum += (p2.price - p1.price) * ((p1.density + p2.density) / 2);
+            }
+        }
+        return sum;
+    }
+
+    static linearRegression(xValues, yValues) { // https://hazlo.medium.com/linear-regression-from-scratch-in-js-first-foray-into-ml-for-web-developers-867cfcae8fde
+        const n = xValues.length;
+        if (n !== yValues.length || n < 2) return { slope: 0, r2: 0 };
+        
+        let sumX = 0, sumY = 0, sumXY = 0, sumXX = 0, sumYY = 0;
+        for (let i = 0; i < n; i++) {
+            sumX += xValues[i];
+            sumY += yValues[i];
+            sumXY += xValues[i] * yValues[i];
+            sumXX += xValues[i] * xValues[i];
+            sumYY += yValues[i] * yValues[i];
+        }
+        
+        const slope = (n * sumXY - sumX * sumY) / (n * sumXX - sumX * sumX);
+        return { slope, n };
+    }
+}
+
+
+// This block is dynamically generated. Do not edit manually.
+module.exports = {
+    Aggregators,
+    DataExtractor,
+    DistributionAnalytics,
+    HistoryExtractor,
+    MathPrimitives,
+    SCHEMAS,
+    SignalPrimitives,
+    TimeSeries,
+    Validators,
+    priceExtractor
 };

package/index.js

@@ -36,7 +36,7 @@ const { build: buildManifestFunc } = require('./functions/computation-system/hel
 const computationSystem = { runComputationPass       : require('./functions/computation-system/helpers/computation_pass_runner')    .runComputationPass,    
                             dataLoader               : require('./functions/computation-system/utils/data_loader'),
                             computationUtils         : require('./functions/computation-system/utils/utils'),
-                            buildManifest            : buildManifestFunc // <--- NEW PIPE EXPORT
+                            buildManifest            : buildManifestFunc 
                         };
 
                             // API

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bulltrackers-module",
-  "version": "1.0.172",
+  "version": "1.0.174",
   "description": "Helper Functions for Bulltrackers.",
   "main": "index.js",
   "files": [