@vizzor/cli 0.13.0 → 0.14.5

package/chronovisor-engine/src/models/lstm_predictor.py

@@ -0,0 +1,143 @@
+"""LSTM time-series predictor for price direction.
+
+Input: 100-candle windows with 8 per-candle features (close, rsi, macdHist,
+       bbPercentB, atr, obv, funding, fearGreed) → shape (1, 100, 8)
+Output: price direction probability over 1h/4h/1d horizons
+
+Trained on historical klines from PostgreSQL via training/train_lstm.py.
+"""
+
+import os
+from pathlib import Path
+
+import numpy as np
+
+MODEL_DIR = Path(os.getenv("MODEL_DIR", "models"))
+
+# Per-candle features expected by the LSTM: 8 features per timestep.
+# The training pipeline (train_lstm.py) creates sequences with these columns.
+PER_CANDLE_FEATURES = ["close", "rsi", "macdHist", "bbPercentB", "atr", "obv", "funding", "fearGreed"]
+NUM_FEATURES = len(PER_CANDLE_FEATURES)
+SEQUENCE_LENGTH = 100
+
+
+class LSTMPredictor:
+    def __init__(self):
+        self.version = "0.2.0"
+        self.is_loaded = False
+        self.last_trained: str | None = None
+        self.accuracy: float | None = None
+        self.model = None
+        self._scaler = None
+
+    def load(self):
+        """Load trained LSTM model from disk, or initialize with heuristic fallback."""
+        model_path = MODEL_DIR / "lstm_predictor.pt"
+        scaler_path = MODEL_DIR / "lstm_predictor_scaler.joblib"
+        if model_path.exists():
+            try:
+                import torch
+
+                self.model = torch.load(model_path, weights_only=True)
+                self.is_loaded = True
+                self.last_trained = str(model_path.stat().st_mtime)
+                # Load fitted scaler if available
+                if scaler_path.exists():
+                    try:
+                        import joblib
+                        self._scaler = joblib.load(scaler_path)
+                    except Exception:
+                        self._scaler = None
+            except Exception:
+                self._init_heuristic()
+        else:
+            self._init_heuristic()
+
+    def _init_heuristic(self):
+        """Fallback: use a simple heuristic until trained model is available."""
+        self.is_loaded = True
+        self.version = "0.2.0-heuristic"
+
+    def predict(self, ohlcv_window: list[dict], indicators: dict) -> dict:
+        """Predict price direction from OHLCV + indicators.
+
+        Returns:
+            dict with keys: direction, probability, model
+        """
+        if self.model is not None:
+            return self._predict_model(ohlcv_window, indicators)
+        return self._predict_heuristic(indicators)
+
+    def _predict_model(self, ohlcv_window: list[dict], indicators: dict) -> dict:
+        """Run inference through trained LSTM model.
+
+        Restructures input to proper (1, T, F) shape where T=100 timesteps
+        and F=8 per-candle features, instead of the incorrect (1, 1, N) shape
+        that treated all features as a single timestep.
+        """
+        import torch
+
+        candles = ohlcv_window[-SEQUENCE_LENGTH:]
+
+        # Build per-candle feature matrix: shape (T, F)
+        # Each candle gets its own feature vector from available OHLCV + indicators
+        feature_matrix = []
+        for candle in candles:
+            row = [
+                float(candle.get("close", 0)),
+                float(candle.get("rsi", indicators.get("rsi", 50))),
+                float(candle.get("macdHist", indicators.get("macdHistogram", 0))),
+                float(candle.get("bbPercentB", indicators.get("bollingerPercentB", 0.5))),
+                float(candle.get("atr", indicators.get("atr", 0))),
+                float(candle.get("obv", indicators.get("obv", 0))),
+                float(candle.get("funding", indicators.get("fundingRate", 0))),
+                float(candle.get("fearGreed", indicators.get("fearGreed", 50))),
+            ]
+            feature_matrix.append(row)
+
+        # Pad if fewer than SEQUENCE_LENGTH candles (repeat first candle)
+        while len(feature_matrix) < SEQUENCE_LENGTH:
+            feature_matrix.insert(0, feature_matrix[0])
+
+        arr = np.array(feature_matrix, dtype=np.float32)  # (100, 8)
+
+        # Apply fitted scaler if available (normalize per-feature)
+        if self._scaler is not None:
+            arr = self._scaler.transform(arr)
+
+        # Shape: (1, T=100, F=8) — proper LSTM input
+        tensor = torch.tensor(arr, dtype=torch.float32).unsqueeze(0)
+
+        with torch.no_grad():
+            output = self.model(tensor)
+            probs = torch.softmax(output, dim=-1).squeeze().numpy()
+
+        directions = ["up", "sideways", "down"]
+        idx = int(np.argmax(probs))
+
+        return {
+            "direction": directions[idx],
+            "probability": float(probs[idx]),
+            "model": f"lstm-predictor-{self.version}",
+        }
+
+    def _predict_heuristic(self, indicators: dict) -> dict:
+        """Simple heuristic based on RSI + MACD until model is trained."""
+        rsi = indicators.get("rsi", 50)
+        macd_hist = indicators.get("macdHistogram", 0)
+
+        score = 0.0
+        if rsi < 30:
+            score += 0.3
+        elif rsi > 70:
+            score -= 0.3
+        if macd_hist > 0:
+            score += 0.2
+        elif macd_hist < 0:
+            score -= 0.2
+
+        if score > 0.1:
+            return {"direction": "up", "probability": 0.5 + score, "model": "lstm-heuristic"}
+        elif score < -0.1:
+            return {"direction": "down", "probability": 0.5 + abs(score), "model": "lstm-heuristic"}
+        return {"direction": "sideways", "probability": 0.5, "model": "lstm-heuristic"}

package/chronovisor-engine/src/models/microstructure_specialist.py

@@ -0,0 +1,65 @@
+"""Short-horizon microstructure specialist for 1m-15m direction calls."""
+
+import os
+from pathlib import Path
+
+import joblib
+import numpy as np
+
+MODEL_DIR = Path(os.getenv("MODEL_DIR", "models"))
+
+
+class MicrostructureSpecialist:
+    FEATURE_KEYS = [
+        "return_1",
+        "volume_ratio",
+        "range_pct",
+        "wick_imbalance",
+        "trade_intensity",
+        "price_vs_sma20",
+        "volatility_5",
+    ]
+
+    def __init__(self) -> None:
+        self.version = "0.1.0"
+        self.is_loaded = False
+        self.last_trained: str | None = None
+        self.accuracy: float | None = None
+        self.model = None
+
+    def load(self) -> None:
+        path = MODEL_DIR / "microstructure_specialist.joblib"
+        try:
+            data = joblib.load(path)
+            self.model = data["model"]
+            self.last_trained = data.get("trained_at")
+            self.accuracy = data.get("accuracy")
+            self.is_loaded = True
+        except Exception:
+            self.model = None
+            self.is_loaded = True
+
+    def predict(self, features: dict) -> dict:
+        if self.model is None:
+            score = float(features.get("return_1", 0.0)) * 0.8 + (
+                float(features.get("volume_ratio", 1.0)) - 1.0
+            ) * 0.2
+            direction = "up" if score > 0.15 else "down" if score < -0.15 else "sideways"
+            probability = min(0.7, 0.5 + abs(score) / 5)
+            return {
+                "direction": direction,
+                "probability": round(probability, 4),
+                "confidence": round(probability * 100, 2),
+                "model": "heuristic-microstructure",
+            }
+
+        x = np.array([[features.get(k, 0.0) for k in self.FEATURE_KEYS]], dtype=np.float32)
+        proba = self.model.predict_proba(x)[0]
+        idx = int(np.argmax(proba))
+        direction = {0: "down", 1: "sideways", 2: "up"}.get(idx, "sideways")
+        return {
+            "direction": direction,
+            "probability": round(float(proba[idx]), 4),
+            "confidence": round(float(proba[idx]) * 100, 2),
+            "model": "microstructure_specialist",
+        }

package/chronovisor-engine/src/models/narrative_detector.py

@@ -0,0 +1,418 @@
+"""Narrative detection model using TF-IDF + topic clustering.
+
+Identifies trending crypto narratives from text corpora by matching against
+known narrative keyword clusters and scoring by frequency and context.
+"""
+
+import math
+import os
+import re
+from collections import Counter
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+MODEL_DIR = Path(os.getenv("MODEL_DIR", "models"))
+
+KNOWN_NARRATIVES = [
+    "ai_crypto",
+    "rwa",
+    "depin",
+    "meme",
+    "l2_scaling",
+    "restaking",
+    "defi_revival",
+    "gaming",
+    "regulation",
+    "btc_ecosystem",
+]
+
+# Keyword dictionaries per narrative — used for TF-IDF matching
+NARRATIVE_KEYWORDS: dict[str, list[str]] = {
+    "ai_crypto": [
+        "artificial intelligence",
+        "machine learning",
+        "ai agent",
+        "neural",
+        "llm",
+        "gpt",
+        "generative",
+        "ai token",
+        "ai crypto",
+        "compute",
+        "inference",
+        "training data",
+        "decentralized ai",
+        "ai blockchain",
+        "openai",
+        "anthropic",
+    ],
+    "rwa": [
+        "real world asset",
+        "rwa",
+        "tokenized",
+        "treasury",
+        "t-bill",
+        "bond",
+        "real estate",
+        "commodity",
+        "securitization",
+        "ondo",
+        "centrifuge",
+        "maple",
+        "clearpool",
+        "institutional",
+    ],
+    "depin": [
+        "depin",
+        "decentralized physical",
+        "iot",
+        "sensor",
+        "wireless",
+        "helium",
+        "hivemapper",
+        "render",
+        "filecoin",
+        "storage",
+        "compute network",
+        "physical infrastructure",
+        "hardware",
+    ],
+    "meme": [
+        "meme",
+        "memecoin",
+        "doge",
+        "shib",
+        "pepe",
+        "bonk",
+        "wif",
+        "community token",
+        "fair launch",
+        "pump fun",
+        "solana meme",
+        "based",
+        "moon",
+        "ape",
+        "degen",
+    ],
+    "l2_scaling": [
+        "layer 2",
+        "l2",
+        "rollup",
+        "optimistic",
+        "zk rollup",
+        "zero knowledge",
+        "arbitrum",
+        "optimism",
+        "base",
+        "zksync",
+        "starknet",
+        "scroll",
+        "polygon",
+        "scaling",
+        "throughput",
+        "tps",
+    ],
+    "restaking": [
+        "restaking",
+        "eigenlayer",
+        "liquid restaking",
+        "lrt",
+        "avs",
+        "actively validated",
+        "ether.fi",
+        "puffer",
+        "renzo",
+        "kelp",
+        "shared security",
+        "slashing",
+    ],
+    "defi_revival": [
+        "defi",
+        "decentralized finance",
+        "yield",
+        "lending",
+        "borrowing",
+        "dex",
+        "amm",
+        "liquidity",
+        "tvl",
+        "aave",
+        "uniswap",
+        "curve",
+        "maker",
+        "compound",
+        "perp",
+        "perpetual",
+    ],
+    "gaming": [
+        "gamefi",
+        "gaming",
+        "play to earn",
+        "p2e",
+        "nft game",
+        "metaverse",
+        "virtual world",
+        "axie",
+        "immutable",
+        "gala",
+        "illuvium",
+        "guild",
+        "esports",
+        "blockchain game",
+    ],
+    "regulation": [
+        "regulation",
+        "sec",
+        "cftc",
+        "compliance",
+        "etf",
+        "spot etf",
+        "bitcoin etf",
+        "legislation",
+        "framework",
+        "license",
+        "ban",
+        "legal",
+        "enforcement",
+        "stablecoin bill",
+        "mica",
+    ],
+    "btc_ecosystem": [
+        "bitcoin",
+        "btc",
+        "ordinals",
+        "inscription",
+        "brc-20",
+        "rune",
+        "runes",
+        "lightning",
+        "taproot",
+        "nostr",
+        "stacks",
+        "bitcoin l2",
+        "halving",
+        "satoshi",
+        "bitcoin defi",
+    ],
+}
+
+
+@dataclass
+class NarrativeResult:
+    """Result of narrative detection."""
+
+    narrative: str  # detected narrative label
+    confidence: float  # 0-1
+    related_tokens: list[str]  # tokens associated with this narrative
+    keywords: list[str]  # top keywords found
+    trend_direction: str  # 'emerging', 'peaking', 'fading'
+    mention_count: int
+
+
+class NarrativeDetectorModel:
+    """Narrative detection using TF-IDF keyword matching against known clusters.
+
+    Performs lightweight TF-IDF vectorization and scores each known narrative
+    based on keyword frequency and contextual signals in the input text corpus.
+    """
+
+    def __init__(self) -> None:
+        self.version = "0.1.0"
+        self.is_loaded = False
+        self.last_trained: str | None = None
+        self.accuracy: float | None = None
+        self.narratives = KNOWN_NARRATIVES
+        self.keywords = NARRATIVE_KEYWORDS
+
+    def load(self) -> None:
+        """Initialize model (keyword-based, always ready)."""
+        self.is_loaded = True
+
+    def detect(self, texts: list[str]) -> list[NarrativeResult]:
+        """Detect narratives from a corpus of texts.
+
+        Performs TF-IDF vectorization and matches against known narrative
+        keyword clusters. Returns results sorted by confidence descending.
+        """
+        if not texts:
+            return []
+
+        # Build document frequency across corpus
+        corpus_lower = [t.lower() for t in texts]
+        total_docs = len(corpus_lower)
+
+        # Compute TF-IDF scores per narrative
+        narrative_scores: dict[str, dict[str, float]] = {}
+
+        for narrative, kw_list in self.keywords.items():
+            matched_keywords: list[str] = []
+            total_tf_idf = 0.0
+            mention_count = 0
+
+            for keyword in kw_list:
+                # Document frequency: how many docs contain this keyword
+                df = sum(1 for doc in corpus_lower if keyword in doc)
+                if df == 0:
+                    continue
+
+                # IDF: log(N / df)
+                idf = math.log(total_docs / df) + 1.0
+
+                # TF: total occurrences across all docs
+                tf = sum(doc.count(keyword) for doc in corpus_lower)
+                mention_count += tf
+
+                tf_idf = (1 + math.log(tf)) * idf if tf > 0 else 0.0
+                total_tf_idf += tf_idf
+                matched_keywords.append(keyword)
+
+            if matched_keywords:
+                narrative_scores[narrative] = {
+                    "score": total_tf_idf,
+                    "mention_count": mention_count,
+                    "keywords": matched_keywords,
+                }
+
+        if not narrative_scores:
+            return []
+
+        # Normalize scores to 0-1 confidence range
+        max_score = max(s["score"] for s in narrative_scores.values())
+        if max_score == 0:
+            max_score = 1.0
+
+        results: list[NarrativeResult] = []
+        for narrative, data in narrative_scores.items():
+            raw_confidence = data["score"] / max_score
+            confidence = min(1.0, raw_confidence)
+            mention_count = int(data["mention_count"])
+
+            # Extract related token symbols from texts
+            related_tokens = self._extract_tokens(corpus_lower, narrative)
+
+            # Determine trend direction based on mention distribution
+            trend_direction = self._estimate_trend(corpus_lower, data["keywords"])
+
+            # Top keywords sorted by actual occurrence
+            kw_counts = [
+                (kw, sum(doc.count(kw) for doc in corpus_lower))
+                for kw in data["keywords"]
+            ]
+            kw_counts.sort(key=lambda x: x[1], reverse=True)
+            top_keywords = [kw for kw, _ in kw_counts[:5]]
+
+            results.append(
+                NarrativeResult(
+                    narrative=narrative,
+                    confidence=round(confidence, 4),
+                    related_tokens=related_tokens[:10],
+                    keywords=top_keywords,
+                    trend_direction=trend_direction,
+                    mention_count=mention_count,
+                )
+            )
+
+        results.sort(key=lambda r: r.confidence, reverse=True)
+        return results
+
+    def predict(self, features: dict) -> NarrativeResult:
+        """API-compatible prediction (takes {"texts": [...]}).
+
+        Returns the top narrative result.
+        """
+        texts = features.get("texts", [])
+        results = self.detect(texts)
+        if not results:
+            return NarrativeResult(
+                narrative="unknown",
+                confidence=0.0,
+                related_tokens=[],
+                keywords=[],
+                trend_direction="fading",
+                mention_count=0,
+            )
+        return results[0]
+
+    def get_trending_narratives(
+        self, texts: list[str], top_k: int = 5
+    ) -> list[NarrativeResult]:
+        """Get the top-k trending narratives from the text corpus."""
+        results = self.detect(texts)
+        return results[:top_k]
+
+    def _extract_tokens(self, docs: list[str], narrative: str) -> list[str]:
+        """Extract cryptocurrency token symbols mentioned alongside narrative keywords."""
+        # Common token symbol pattern: $SYMBOL or uppercase 2-5 letter words
+        token_pattern = re.compile(r"\$([A-Z]{2,10})\b|(?<!\w)([A-Z]{2,5})(?!\w)")
+        token_counts: Counter[str] = Counter()
+
+        narrative_kws = self.keywords.get(narrative, [])
+        for doc in docs:
+            # Only count tokens in docs that contain narrative keywords
+            has_narrative = any(kw in doc for kw in narrative_kws)
+            if not has_narrative:
+                continue
+            matches = token_pattern.findall(doc.upper())
+            for match in matches:
+                symbol = match[0] or match[1]
+                # Filter common English words that look like tickers
+                if symbol not in {
+                    "THE",
+                    "AND",
+                    "FOR",
+                    "WITH",
+                    "FROM",
+                    "THIS",
+                    "THAT",
+                    "HAS",
+                    "ARE",
+                    "WAS",
+                    "NOT",
+                    "BUT",
+                    "ALL",
+                    "CAN",
+                    "HAD",
+                    "HER",
+                    "ONE",
+                    "OUR",
+                    "OUT",
+                    "NEW",
+                }:
+                    token_counts[symbol] += 1
+
+        return [t for t, _ in token_counts.most_common(10)]
+
+    def _estimate_trend(self, docs: list[str], keywords: list[str]) -> str:
+        """Estimate whether a narrative is emerging, peaking, or fading.
+
+        Splits the document corpus into thirds (chronological order assumed)
+        and compares keyword density across segments.
+        """
+        if len(docs) < 3:
+            return "emerging"
+
+        third = max(1, len(docs) // 3)
+        early = docs[:third]
+        middle = docs[third : 2 * third]
+        late = docs[2 * third :]
+
+        def count_mentions(segment: list[str]) -> int:
+            return sum(
+                doc.count(kw) for doc in segment for kw in keywords
+            )
+
+        early_count = count_mentions(early)
+        middle_count = count_mentions(middle)
+        late_count = count_mentions(late)
+
+        # Normalize by segment size
+        early_density = early_count / max(1, len(early))
+        middle_density = middle_count / max(1, len(middle))
+        late_density = late_count / max(1, len(late))
+
+        if late_density > middle_density * 1.2 and late_density > early_density:
+            return "emerging"
+        if middle_density >= early_density and middle_density >= late_density:
+            return "peaking"
+        return "fading"