aiden-shared-calculations-unified 1.0.83 → 1.0.84

package/calculations/gem/quant-skill-alpha-signal.js

@@ -1,63 +1,18 @@
 /**
- * @fileoverview Calculation (Pass 4) for the "Quant-Skill Alpha Signal".
+ * @fileoverview GEM Product Line (Pass 4)
  *
- * This metric synthesizes multiple Pass 1, 2, and 3 signals into a
- * single, actionable "raw score" for each asset. It is designed to
- * be the final, tradable signal from this computation branch.
- *
- * It weights:
- * 1. Skilled/Unskilled Divergence (Pass 3)
- * 2. Unskilled "FOMO" (from Cohort Momentum, Pass 3)
- * 3. Platform vs. Sample Divergence (Pass 1)
- * 4. Social Media Sentiment (Pass 1)
+ * This is the final, stateless signal generator for the GEM line.
+ * It answers: "Are skilled users buying into *positive* momentum
+ * while unskilled users are buying into *negative* momentum?"
  */
 class QuantSkillAlphaSignal {
+
+    // --- STANDARD 2: ADDED ---
     constructor() {
-        // Define the weights for the model.
-        // These would be optimized via backtesting.
-        this.W_DIVERGENCE = 0.40; // Skilled vs Unskilled
-        this.W_FOMO = 0.30;       // Unskilled Momentum (faded)
-        this.W_PLATFORM = 0.15;   // Sample vs Platform
-        this.W_SOCIAL = 0.15;   // Social Sentiment
+        this.result = {};
     }
 
-    /**
-     * Defines the output schema for this calculation.
-     * @returns {object} JSON Schema object
-     */
-    static getSchema() {
-        const tickerSchema = {
-            "type": "object",
-            "properties": {
-                "raw_alpha_score": {
-                    "type": "number",
-                    "description": "The final weighted signal score. > 0 is bullish, < 0 is bearish."
-                },
-                "signal_status": {
-                    "type": "string",
-                    "description": "A human-readable signal (e.g., 'Strong Buy', 'Neutral')."
-                },
-                "component_divergence_score": { "type": "number" },
-                "component_unskilled_fomo_score": { "type": "number" },
-                "component_platform_divergence_score": { "type": "number" },
-                "component_social_sentiment_score": { "type": "number" }
-            },
-            "required": ["raw_alpha_score", "signal_status"]
-        };
-
-        return {
-            "type": "object",
-            "description": "A final, weighted alpha signal combining skill divergence, momentum, and sentiment.",
-            "patternProperties": {
-                "^.*$": tickerSchema // Ticker
-            },
-            "additionalProperties": tickerSchema
-        };
-    }
-    
-    /**
-     * Statically defines all metadata for the manifest builder.
-     */
+    /** Statically defines metadata */
     static getMetadata() {
         return {
             type: 'meta',
@@ -68,102 +23,131 @@ class QuantSkillAlphaSignal {
         };
     }
 
-    /**
-     * Statically declare dependencies.
-     */
+    /** Statically declare dependencies */
     static getDependencies() {
         return [
-            // Internal 'gem' dependencies (normalized)
-            'skilled-unskilled-divergence',
-            'cohort-momentum-state',
-            'platform-conviction-divergence',
-            
-            // Dependencies on 'core' product line (normalized)
-            'social-sentiment-aggregation'
+            'skilled-unskilled-divergence',  // from gem (Pass 3)
+            'cohort-momentum-state',       // from gem (Pass 2)
+            'instrument-price-momentum-20d'// from core (Pass 1)
         ];
     }
 
-    process() {
-        // No-op
+    /**
+     * Defines the output schema for this calculation.
+     */
+    static getSchema() {
+        const tickerSchema = {
+            "type": "object",
+            "properties": {
+                "signal": { "type": "string", "enum": ["Strong Buy", "Buy", "Neutral", "Sell", "Strong Sell"] },
+                "gem_score": { "type": "number" },
+                "components": {
+                    "type": "object",
+                    "properties": {
+                        "flow_divergence": { "type": "number" },
+                        "momentum_divergence": { "type": "number" },
+                        "asset_momentum": { "type": "number" }
+                    }
+                }
+            },
+            "required": ["signal", "gem_score", "components"]
+        };
+        
+        return {
+            "type": "object",
+            "description": "Generates a final skill-based alpha signal.",
+            "patternProperties": { "^.*$": tickerSchema },
+            "additionalProperties": tickerSchema
+        };
+    }
+    
+    _normalize(score) {
+        return Math.tanh(score / 5.0) * 10;
     }
 
     /**
-     * This is a 'meta' calculation.
-     * @param {object} fetchedDependencies - Results from previous passes.
+     * This is a 'meta' calculation. It runs once.
      */
-    getResult(fetchedDependencies) {
-        // FIX: Use normalized dependency names
-        const divergenceData = fetchedDependencies['skilled-unskilled-divergence']?.assets;
-        const momentumData = fetchedDependencies['cohort-momentum-state'];
-        const platformData = fetchedDependencies['platform-conviction-divergence'];
-        const socialData = fetchedDependencies['social-sentiment-aggregation']?.per_ticker;
+    // --- STANDARD 1: UPDATED SIGNATURE (added rootData) ---
+    async process(dateStr, rootData, dependencies, config, fetchedDependencies) {
+        const { logger, calculationUtils } = dependencies;
+        
+        const flowDivergence = fetchedDependencies['skilled-unskilled-divergence'];
+        const momentumExposure = fetchedDependencies['cohort-momentum-state'];
+        const assetMomentum = fetchedDependencies['instrument-price-momentum-20d'];
 
-        if (!divergenceData || !momentumData || !platformData || !socialData) {
-            return {}; // Missing one or more key dependencies
+        if (!flowDivergence || !momentumExposure || !assetMomentum) {
+            logger.log('WARN', `[gem/quant-skill-alpha-signal] Missing dependencies for ${dateStr}.`);
+            // --- STANDARD 2: DO NOT RETURN ---
+            this.result = {};
+            return;
         }
 
+        const skilledMomentum = momentumExposure.skilled?.average_momentum_exposure_pct || 0;
+        const unskilledMomentum = momentumExposure.unskilled?.average_momentum_exposure_pct || 0;
+        const momentumDivergence = skilledMomentum - unskilledMomentum;
+
         const result = {};
-        const allTickers = new Set([
-            ...Object.keys(divergenceData),
-            ...Object.keys(momentumData),
-            ...Object.keys(platformData),
-            ...Object.keys(socialData)
-        ]);
+        const allTickers = Object.keys(flowDivergence);
 
         for (const ticker of allTickers) {
-            // 1. Get Divergence Signal (Buy = +1, Sell = -1)
-            const divStatus = divergenceData[ticker]?.status;
-            const divScore = divStatus === 'Capitulation' ? 1.0 : (divStatus === 'Euphoria' ? -1.0 : 0);
-            
-            // 2. Get Unskilled FOMO Signal (We fade this, so we use -1)
-            // 'unskilled_momentum_score' is high positive when they buy a rally
-            const fomoScore = momentumData[ticker]?.unskilled_momentum_score || 0;
+            const flowData = flowDivergence[ticker];
+            const assetMom = assetMomentum[ticker]?.momentum_20d_pct || 0;
 
-            // 3. Get Platform Divergence Signal
-            // 'divergence' is positive when our sample is more bullish than the platform
-            const platformScore = platformData[ticker]?.divergence || 0;
+            // 1. Flow Divergence (Skilled buying, Unskilled selling)
+            const flowScore = flowData.flow_divergence_score; // e.g., +1.5
             
-            // 4. Get Social Sentiment Signal
-            // 'net_sentiment_pct' is positive when social is bullish
-            const socialScore = socialData[ticker]?.net_sentiment_pct || 0;
-
-            // Normalize scores to a similar range (approx -100 to 100)
-            // (This is a simple normalization; a z-score would be more robust)
-            const s_div = divScore * 100.0;
-            const s_fomo = -1 * fomoScore; // Fading the signal
-            const s_plat = platformScore; // Already 0-100
-            const s_soc = socialScore;  // Already 0-100
-
-            // Calculate final weighted score
-            const raw_alpha_score = 
-                (s_div * this.W_DIVERGENCE) +
-                (s_fomo * this.W_FOMO) +
-                (s_plat * this.W_PLATFORM) +
-                (s_soc * this.W_SOCIAL);
+            // 2. Momentum Divergence (Skilled buying high-mom, Unskilled buying low-mom)
+            const momScore = momentumDivergence; // e.g., +20.0
+            
+            // 3. Asset Momentum (Is the asset *actually* in an uptrend?)
+            const assetScore = assetMom; // e.g., +15.0
 
-            // Determine human-readable status
-            let status = 'Neutral';
-            if (raw_alpha_score > 30) status = 'Strong Buy';
-            else if (raw_alpha_score > 10) status = 'Buy';
-            else if (raw_alpha_score < -30) status = 'Strong Sell';
-            else if (raw_alpha_score < -10) status = 'Sell';
+            // --- Signal Logic ---
+            // We want all three to be positive.
+            // 1. Skilled are buying, Unskilled are selling (flowScore > 0)
+            // 2. Skilled are buying *more* momentum than Unskilled (momScore > 0)
+            // 3. The asset itself has positive momentum (assetScore > 0)
+            
+            // If skilled are buying *and* they are buying into strength, that's a good sign.
+            // We combine flow and momentum divergence.
+            const divergenceFactor = (flowScore > 0 && momScore > 0) ? (flowScore * momScore) : 0;
+            
+            // The final score is the divergence, *validated* by the asset's own momentum.
+            // We scale flowScore (small) and momScore (large) to be comparable
+            const scaledFlow = flowScore * 10; // (e.g., 1.5 -> 15)
+            const finalScore = (scaledFlow + momScore + assetScore) / 3.0;
+            
+            const gem_score = this._normalize(finalScore);
+            let signal = "Neutral";
+            if (gem_score > 7.0) signal = "Strong Buy";
+            else if (gem_score > 2.5) signal = "Buy";
+            else if (gem_score < -7.0) signal = "Strong Sell";
+            else if (gem_score < -2.5) signal = "Sell";
 
             result[ticker] = {
-                raw_alpha_score: raw_alpha_score,
-                signal_status: status,
-                component_divergence_score: s_div,
-                component_unskilled_fomo_score: s_fomo,
-                component_platform_divergence_score: s_plat,
-                component_social_sentiment_score: s_soc
+                signal: signal,
+                gem_score: gem_score,
+                components: {
+                    flow_divergence: flowScore,
+                    momentum_divergence: momScore,
+                    asset_momentum: assetScore
+                }
             };
         }
         
-        return result;
+        // --- STANDARD 2: SET STATE, DO NOT RETURN ---
+        this.result = result;
     }
 
+    // --- STANDARD 2: ADDED ---
+    async getResult(fetchedDependencies) {
+        return this.result;
+    }
+
+    // --- STANDARD 2: ADDED ---
     reset() {
-        // No state
+        this.result = {};
     }
 }
-
 module.exports = QuantSkillAlphaSignal;