aiden-shared-calculations-unified 1.0.76 → 1.0.77

package/calculations/pyro/squeeze-potential.js

@@ -0,0 +1,158 @@
+/**
+ * @fileoverview PYRO Product Line (Pass 3)
+ *
+ * This metric answers: "For each asset, what is the 'Squeeze Potential'
+ * for both longs and shorts?"
+ *
+ * It identifies "trapped" speculators by looking at:
+ * 1. How many are in the "danger zone" (close to their SL).
+ * 2. Which direction the price is moving (momentum).
+ *
+ * A high "short squeeze" score means many shorts are in danger
+ * AND the price is moving *against* them (i.e., momentum is positive).
+ */
+class SqueezePotential {
+
+    /**
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
+     */
+    static getSchema() {
+        const tickerSchema = {
+            "type": "object",
+            "properties": {
+                "short_squeeze_score": {
+                    "type": "number",
+                    "description": "Score (0-10) indicating potential for a short squeeze."
+                },
+                "long_squeeze_score": {
+                    "type": "number",
+                    "description": "Score (0-10) indicating potential for a long squeeze (capitulation)."
+                },
+                "momentum_20d_pct": {
+                    "type": "number",
+                    "description": "The 20-day price momentum used in the calculation."
+                }
+            },
+            "required": ["short_squeeze_score", "long_squeeze_score", "momentum_20d_pct"]
+        };
+        
+        return {
+            "type": "object",
+            "description": "Calculates a squeeze potential score for longs and shorts.",
+            "patternProperties": {
+                "^.*$": tickerSchema // Ticker
+            },
+            "additionalProperties": tickerSchema
+        };
+    }
+
+    /**
+     * Statically defines all metadata for the manifest builder.
+     */
+    static getMetadata() {
+        return {
+            type: 'meta',
+            rootDataDependencies: [],
+            isHistorical: false,
+            userType: 'n/a',
+            category: 'pyro'
+        };
+    }
+
+    /**
+     * Statically declare dependencies.
+     */
+    static getDependencies() {
+        return [
+            'speculator-danger-zone', // from core
+            'speculator-asset-sentiment', // from core
+            'instrument-price-momentum-20d' // from core
+        ];
+    }
+    
+    /**
+     * Simple min-max normalization, clamped 0-1.
+     */
+    _normalize(value, min, max) {
+        const normalized = (value - min) / (max - min);
+        return Math.max(0, Math.min(1, normalized));
+    }
+
+    /**
+     * This is a 'meta' calculation. It runs once.
+     * @param {string} dateStr - The date string 'YYYY-MM-DD'.
+     * @param {object} dependencies - The shared dependencies (e.g., logger).
+     * @param {object} config - The computation system configuration.
+     * @param {object} fetchedDependencies - Results from previous passes.
+     * @returns {Promise<object>} The calculation result.
+     */
+    async process(dateStr, dependencies, config, fetchedDependencies) {
+        const { logger } = dependencies;
+        
+        const dangerData = fetchedDependencies['speculator-danger-zone'];
+        const sentimentData = fetchedDependencies['speculator-asset-sentiment'];
+        const momentumData = fetchedDependencies['instrument-price-momentum-20d'];
+
+        if (!dangerData || !sentimentData || !momentumData) {
+            logger.log('WARN', `[pyro/squeeze-potential] Missing core dependencies for ${dateStr}. Skipping.`);
+            return {};
+        }
+
+        const allTickers = new Set([
+            ...Object.keys(dangerData),
+            ...Object.keys(sentimentData),
+            ...Object.keys(momentumData)
+        ]);
+        
+        const result = {};
+
+        for (const ticker of allTickers) {
+            const danger = dangerData[ticker];
+            const sentiment = sentimentData[ticker];
+            const momentum = momentumData[ticker];
+            
+            // If any core data is missing for this ticker, skip it
+            if (!danger || !sentiment || !momentum) {
+                continue;
+            }
+
+            const mom_pct = momentum.momentum_20d_pct || 0;
+            const short_danger_pct = danger.short_danger_pct || 0;
+            const long_danger_pct = danger.long_danger_pct || 0;
+
+            let short_squeeze_score = 0;
+            let long_squeeze_score = 0;
+
+            // Calculate Short Squeeze:
+            // Needs positive momentum (price rising) and shorts in danger.
+            if (mom_pct > 0 && sentiment.short.count > 0) {
+                // Normalize momentum (e.g., 0-20%) and danger (0-100%)
+                const norm_mom = this._normalize(mom_pct, 0, 20);
+                const norm_danger = this._normalize(short_danger_pct, 0, 100);
+                // Combine and scale to 0-10
+                short_squeeze_score = (norm_mom * 0.5 + norm_danger * 0.5) * 10;
+            }
+            
+            // Calculate Long Squeeze:
+            // Needs negative momentum (price falling) and longs in danger.
+            if (mom_pct < 0 && sentiment.long.count > 0) {
+                // Normalize momentum (e.g., 0 to -20%) and danger (0-100%)
+                const norm_mom = this._normalize(Math.abs(mom_pct), 0, 20);
+                const norm_danger = this._normalize(long_danger_pct, 0, 100);
+                // Combine and scale to 0-10
+                long_squeeze_score = (norm_mom * 0.5 + norm_danger * 0.5) * 10;
+            }
+            
+            result[ticker] = {
+                short_squeeze_score: short_squeeze_score,
+                long_squeeze_score: long_squeeze_score,
+                momentum_20d_pct: mom_pct
+            };
+        }
+        
+        return result;
+    }
+}
+
+module.exports = SqueezePotential;

package/calculations/pyro/volatility-signal.js

@@ -0,0 +1,133 @@
+/**
+ * @fileoverview PYRO Product Line (Pass 4)
+ *
+ * This metric answers: "What is the final PYRO volatility signal?"
+ *
+ * It combines the 'Squeeze Potential' (trapped traders) with the
+ * 'Risk Appetite' (conviction).
+ *
+ * A high score means many traders are trapped AND the rest of
+ * the speculator cohort is highly confident/leveraged,
+ * creating a perfect storm for a sharp move.
+ */
+class VolatilitySignal {
+
+    /**
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
+     */
+    static getSchema() {
+        const tickerSchema = {
+            "type": "object",
+            "properties": {
+                "signal": {
+                    "type": "string",
+                    "enum": ["High Short Squeeze Potential", "High Long Squeeze Potential", "Short Squeeze Watch", "Long Squeeze Watch", "Stable"]
+                },
+                "pyro_score": {
+                    "type": "number",
+                    "description": "Final signal score (-10 to +10). Positive = Short Squeeze, Negative = Long Squeeze."
+                },
+                "risk_appetite": {
+                    "type": "number",
+                    "description": "The risk-appetite-index score (0-10)."
+                }
+            },
+            "required": ["signal", "pyro_score", "risk_appetite"]
+        };
+        
+        return {
+            "type": "object",
+            "description": "Calculates the final PYRO volatility/squeeze signal.",
+            "patternProperties": {
+                "^.*$": tickerSchema // Ticker
+            },
+            "additionalProperties": tickerSchema
+        };
+    }
+
+    /**
+     * Statically defines all metadata for the manifest builder.
+     */
+    static getMetadata() {
+        return {
+            type: 'meta',
+            rootDataDependencies: [],
+            isHistorical: false,
+            userType: 'n/a',
+            category: 'pyro'
+        };
+    }
+
+    /**
+     * Statically declare dependencies.
+     */
+    static getDependencies() {
+        return [
+            'risk-appetite-index', // from pyro (Pass 2)
+            'squeeze-potential'    // from pyro (Pass 3)
+        ];
+    }
+
+    /**
+     * This is a 'meta' calculation. It runs once.
+     * @param {string} dateStr - The date string 'YYYY-MM-DD'.
+     * @param {object} dependencies - The shared dependencies (e.g., logger).
+     * @param {object} config - The computation system configuration.
+     * @param {object} fetchedDependencies - Results from previous passes.
+     * @returns {Promise<object>} The calculation result.
+     */
+    async process(dateStr, dependencies, config, fetchedDependencies) {
+        const { logger } = dependencies;
+        
+        const appetiteData = fetchedDependencies['risk-appetite-index'];
+        const squeezeData = fetchedDependencies['squeeze-potential'];
+
+        if (!appetiteData || !squeezeData) {
+            logger.log('WARN', `[pyro/volatility-signal] Missing dependencies for ${dateStr}. Skipping.`);
+            return {};
+        }
+
+        const allTickers = new Set([
+            ...Object.keys(appetiteData),
+            ...Object.keys(squeezeData)
+        ]);
+        
+        const result = {};
+        const HIGH_THRESHOLD = 7.0; // Min score for "High"
+        const MED_THRESHOLD = 3.0;  // Min score for "Watch"
+
+        for (const ticker of allTickers) {
+            const appetite = appetiteData[ticker]?.risk_appetite_score || 0;
+            const short_squeeze = squeezeData[ticker]?.short_squeeze_score || 0;
+            const long_squeeze = squeezeData[ticker]?.long_squeeze_score || 0;
+            
+            // The final score is the difference.
+            // Positive = Short Squeeze risk
+            // Negative = Long Squeeze risk
+            const pyro_score = short_squeeze - long_squeeze;
+            
+            let signal = "Stable";
+
+            if (pyro_score > HIGH_THRESHOLD && appetite > HIGH_THRESHOLD) {
+                signal = "High Short Squeeze Potential";
+            } else if (pyro_score < -HIGH_THRESHOLD && appetite > HIGH_THRESHOLD) {
+                signal = "High Long Squeeze Potential";
+            } else if (pyro_score > MED_THRESHOLD) {
+                signal = "Short Squeeze Watch";
+            } else if (pyro_score < -MED_THRESHOLD) {
+                signal = "Long Squeeze Watch";
+            }
+            
+            result[ticker] = {
+                signal: signal,
+                pyro_score: pyro_score,
+                risk_appetite: appetite
+            };
+        }
+        
+        return result;
+    }
+}
+
+module.exports = VolatilitySignal;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aiden-shared-calculations-unified",
-  "version": "1.0.76",
+  "version": "1.0.77",
   "description": "Shared calculation modules for the BullTrackers Computation System.",
   "main": "index.js",
   "files": [

package/calculations/socialPosts/gem_social_sentiment_aggregation.js

@@ -1,146 +0,0 @@
-/**
- * @fileoverview Social Calculation (Pass 1)
- *
- * This metric answers: "What is the aggregated social media
- * sentiment (bullish, bearish, neutral) globally and
- * for each ticker?"
- * 
- * THIS IS THE GEM ITERATION, PRACITCALLY IDENTICAL TO SOCIAL SENTIMENT AGGREGATION ORIGINAL, BUT DUPLICATED FOR CLARITY OF THE GEM PRODUCT LINE
- */
-class GemSocialSentimentAggregation {
-    constructor() {
-        this.global = {
-            bullish: 0,
-            bearish: 0,
-            neutral: 0
-        };
-        // { [ticker]: { bullish: 0, bearish: 0, neutral: 0 } }
-        this.perTicker = new Map();
-    }
-
-    /**
-     * Defines the output schema for this calculation.
-     * @returns {object} JSON Schema object
-     */
-    static getSchema() {
-        const sentimentSchema = {
-            "type": "object",
-            "properties": {
-                "bullish": { "type": "number" },
-                "bearish": { "type": "number" },
-                "neutral": { "type": "number" },
-                "total_posts": { "type": "number" },
-                "net_sentiment": { "type": "number" },
-                "net_sentiment_pct": { "type": "number" }
-            },
-            "required": ["bullish", "bearish", "neutral", "total_posts", "net_sentiment", "net_sentiment_pct"]
-        };
-
-        return {
-            "type": "object",
-            "description": "Aggregates social sentiment (bullish, bearish) globally and per ticker.",
-            "properties": {
-                "global_sentiment": {
-                    ...sentimentSchema,
-                    "description": "Aggregated sentiment across all posts."
-                },
-                "per_ticker": {
-                    "type": "object",
-                    "description": "Aggregated sentiment broken down by asset ticker.",
-                    "patternProperties": {
-                        "^.*$": {
-                            ...sentimentSchema,
-                            "description": "Aggregated sentiment for a specific ticker."
-                        } // Ticker
-                    },
-                    "additionalProperties": sentimentSchema
-                }
-            },
-            "required": ["global_sentiment", "per_ticker"]
-        };
-    }
-
-    _initTicker(ticker) {
-        if (!this.perTicker.has(ticker)) {
-            this.perTicker.set(ticker, {
-                bullish: 0,
-                bearish: 0,
-                neutral: 0
-            });
-        }
-    }
-
-    /**
-     * @param {string} dateStr - Today's date.
-     * @param {object} dependencies - db, logger.
-     * @param {object} config - Computation config.
-     * @param {object} fetchedDependencies - (UNUSED) In-memory results.
-     */
-    async process(dateStr, dependencies, config, fetchedDependencies) {
-        const { calculationUtils } = dependencies;
-        const todaySocialPosts = await calculationUtils.loadSocialData(dateStr); 
-
-        for (const post of todaySocialPosts) {
-            const sentiment = post.sentiment || 'neutral'; // 'bullish', 'bearish', 'neutral'
-            
-            // 1. Aggregate global sentiment
-            if (sentiment === 'bullish') {
-                this.global.bullish++;
-            } else if (sentiment === 'bearish') {
-                this.global.bearish++;
-            } else {
-                this.global.neutral++;
-            }
-            
-            // 2. Aggregate per-ticker sentiment
-            const tickers = post.tickers || [];
-            for (const ticker of tickers) {
-                this._initTicker(ticker);
-                const data = this.perTicker.get(ticker);
-                
-                if (sentiment === 'bullish') {
-                    data.bullish++;
-                } else if (sentiment === 'bearish') {
-                    data.bearish++;
-                } else {
-                    data.neutral++;
-                }
-            }
-        }
-    }
-    
-    _calculateSentiment(data) {
-        const total = data.bullish + data.bearish + data.neutral;
-        const net = data.bullish - data.bearish;
-        return {
-            ...data,
-            total_posts: total,
-            net_sentiment: net,
-            // Net sentiment as a percentage of *all* posts (bullish, bearish, neutral)
-            net_sentiment_pct: (total > 0) ? (net / total) * 100 : 0
-        };
-    }
-
-    async getResult() {
-        // Calculate stats for global
-        const global_sentiment = this._calculateSentiment(this.global);
-        
-        // Calculate stats for per-ticker
-        const per_ticker = {};
-        for (const [ticker, data] of this.perTicker.entries()) {
-            per_ticker[ticker] = this._calculateSentiment(data);
-        }
-        
-        return {
-            global_sentiment,
-            per_ticker
-        };
-    }
-
-    reset() {
-        this.global = { bullish: 0, bearish: 0, neutral: 0 };
-        this.perTicker.clear();
-    }
-}
-
-module.exports = GemSocialSentimentAggregation;