feat: Markov + HMM market state analysis

hmm.py

@@ -0,0 +1,272 @@
+"""Hidden Markov Model — hmm.py
+
+Probabilistic state inference: maps observable market signals
+(price returns, volume ratio, RSI) onto hidden states (BULL, BEAR, RANGING)
+using pre-calibrated emission distributions.
+
+No ML training required — emission parameters are hand-calibrated from
+crypto market behaviour (conservative, not curve-fitted).
+
+All computations use CLOSED candles only (no lookahead bias).
+
+Functions:
+  compute_observables(df)         → (ret, vol_ratio, rsi) on last closed candle
+  emission_prob(state, obs)       → P(observables | hidden_state)
+  infer_state(df)                 → (state, confidence_0_to_1, state_probs, reasons)
+  hmm_analyze(src, symbol)        → full HMM dict (cached 30 min)
+"""
+from __future__ import annotations
+import math, time
+from markov import ALL_STATES, State, _mk_cache
+
+# ─── Cache: share with markov.py TTL ─────────────────────────────────────────
+_hmm_cache: dict = {}
+HMM_TTL = 1800   # 30 minutes
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# EMISSION PARAMETERS
+# Each state has a Gaussian(mean, std) for each observable:
+#   ret      = 1-hour close-to-close return (percent)
+#   vol_ratio= recent 5-bar volume / 20-bar avg volume
+#   rsi      = RSI(14) value 0–100
+#
+# These are calibrated for crypto perp markets on 1h timeframe.
+# Bull: positive returns, elevated volume, RSI 50–70
+# Bear: negative returns, elevated volume, RSI 30–50
+# Ranging: near-zero returns, low volume, RSI near 50
+# ─────────────────────────────────────────────────────────────────────────────
+
+EMISSION_PARAMS: dict[str, dict[str, tuple[float, float]]] = {
+    #               (mean,  std)   — Gaussian parameters
+    "BULL": {
+        "ret":       ( 0.35,  0.60),   # +0.35% avg return per hour, std 0.60%
+        "vol_ratio": ( 1.25,  0.45),   # Volume 25% above avg
+        "rsi":       (62.0,   10.0),   # RSI typically 55–75
+    },
+    "BEAR": {
+        "ret":       (-0.35,  0.60),   # negative returns
+        "vol_ratio": ( 1.20,  0.45),   # elevated (panic selling)
+        "rsi":       (38.0,   10.0),   # RSI 25–50
+    },
+    "RANGING": {
+        "ret":       ( 0.00,  0.30),   # near-zero returns, tight range
+        "vol_ratio": ( 0.80,  0.30),   # below-avg volume (no conviction)
+        "rsi":       (50.0,    8.0),   # RSI near 50
+    },
+}
+
+# Prior probabilities (uniform; adjust if you have regime priors)
+STATE_PRIOR: dict[str, float] = {"BULL": 1/3, "BEAR": 1/3, "RANGING": 1/3}
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# HELPERS
+# ─────────────────────────────────────────────────────────────────────────────
+
+def _gaussian_pdf(x: float, mu: float, sigma: float) -> float:
+    """Gaussian probability density (unnormalized is fine — we normalize later)."""
+    if sigma <= 0:
+        return 1.0
+    z = (x - mu) / sigma
+    return math.exp(-0.5 * z * z)   # omit 1/(sigma√2π) — cancels in normalization
+
+
+def _ema_val(arr, span: int) -> float:
+    """Compute final EMA value from array."""
+    k = 2.0 / (span + 1)
+    val = arr[0]
+    for v in arr[1:]:
+        val = val * (1 - k) + v * k
+    return val
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# PUBLIC: compute_observables
+# ─────────────────────────────────────────────────────────────────────────────
+
+def compute_observables(df) -> tuple[float, float, float]:
+    """Extract (ret_pct, vol_ratio, rsi14) from last CLOSED candle.
+
+    Uses iloc[-2] as last confirmed closed candle (iloc[-1] = live/open candle).
+    Returns (ret_pct, vol_ratio, rsi14).
+    """
+    closes = df["close"].values
+    vols   = df["volume"].values if "volume" in df.columns else [1.0] * len(df)
+
+    # Last CLOSED candle = index -2
+    if len(closes) < 16:
+        return 0.0, 1.0, 50.0
+
+    idx = len(closes) - 2   # last confirmed
+
+    # ── 1h return on last closed candle ─────────────────────���────────────────
+    prev_close = float(closes[idx - 1])
+    curr_close = float(closes[idx])
+    ret_pct = ((curr_close - prev_close) / prev_close * 100.0) if prev_close > 0 else 0.0
+
+    # ── Volume ratio ─────────────────────────────────────────────────────────
+    vol_window = vols[max(0, idx-19):idx+1]   # up to 20 bars
+    if len(vol_window) >= 5:
+        vol_avg    = sum(vol_window) / len(vol_window)
+        vol_recent = sum(vol_window[-5:]) / 5
+        vol_ratio  = vol_recent / vol_avg if vol_avg > 0 else 1.0
+    else:
+        vol_ratio = 1.0
+
+    # ── RSI(14) on closed candles ─────────────────────────────────────────────
+    c = [float(v) for v in closes[:idx+1]]
+    rsi_len = 14
+    if len(c) >= rsi_len + 1:
+        deltas = [c[i] - c[i-1] for i in range(1, len(c))]
+        gains  = [max(d, 0) for d in deltas[-rsi_len:]]
+        losses = [max(-d, 0) for d in deltas[-rsi_len:]]
+        ag = sum(gains)  / rsi_len
+        al = sum(losses) / rsi_len
+        if al == 0:
+            rsi = 100.0
+        elif ag == 0:
+            rsi = 0.0
+        else:
+            rsi = 100.0 - 100.0 / (1.0 + ag / al)
+    else:
+        rsi = 50.0
+
+    return round(ret_pct, 4), round(vol_ratio, 4), round(rsi, 2)
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# PUBLIC: emission_prob
+# ─────────────────────────────────────────────────────────────────────────────
+
+def emission_prob(state: str, obs: tuple[float, float, float]) -> float:
+    """P(observables | state) — product of independent Gaussian PDFs.
+
+    obs = (ret_pct, vol_ratio, rsi14)
+    Returns unnormalized likelihood (positive float; higher = more likely).
+    """
+    params = EMISSION_PARAMS.get(state)
+    if not params:
+        return 1.0
+
+    ret_pct, vol_ratio, rsi = obs
+
+    p_ret = _gaussian_pdf(ret_pct,   *params["ret"])
+    p_vol = _gaussian_pdf(vol_ratio, *params["vol_ratio"])
+    p_rsi = _gaussian_pdf(rsi,       *params["rsi"])
+
+    # Product of independent likelihoods
+    return p_ret * p_vol * p_rsi
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# PUBLIC: infer_state — Bayesian update: posterior ∝ prior × likelihood
+# ─────────────────────────────────────────────────────────────────────────────
+
+def infer_state(df) -> tuple[State, float, dict[str, float], list[str]]:
+    """Infer hidden market state from observables via Bayes' theorem.
+
+    P(state | obs) ∝ P(obs | state) × P(state)
+
+    Returns:
+      (state, confidence_0_to_1, state_probabilities_dict, reasons)
+    """
+    obs = compute_observables(df)
+    ret_pct, vol_ratio, rsi = obs
+
+    reasons = [
+        f"1h return: {ret_pct:+.2f}%",
+        f"Volume ratio: {vol_ratio:.2f}× 20-bar avg",
+        f"RSI(14): {rsi:.1f}",
+    ]
+
+    # Compute posterior for each state
+    posteriors: dict[str, float] = {}
+    for state in ALL_STATES:
+        likelihood = emission_prob(state, obs)
+        prior      = STATE_PRIOR.get(state, 1/3)
+        posteriors[state] = likelihood * prior
+
+    # Normalize
+    total = sum(posteriors.values())
+    if total <= 0:
+        probs = {s: 1/3 for s in ALL_STATES}
+    else:
+        probs = {s: round(posteriors[s] / total, 4) for s in ALL_STATES}
+
+    # Best state
+    best_state = max(probs, key=probs.get)
+    confidence = probs[best_state]
+
+    # Human-readable interpretation
+    conf_label = "high" if confidence >= 0.65 else "moderate" if confidence >= 0.45 else "low"
+    reasons.append(
+        f"HMM infers {best_state} with {confidence:.0%} confidence ({conf_label})"
+    )
+
+    # Add runner-up if close
+    sorted_states = sorted(probs, key=probs.get, reverse=True)
+    runner_up = sorted_states[1]
+    if probs[runner_up] >= 0.25:
+        reasons.append(f"Alternative: {runner_up} ({probs[runner_up]:.0%}) — mixed signal")
+
+    return best_state, round(confidence, 3), probs, reasons
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# PUBLIC: hmm_analyze — entry point, cached per symbol
+# ─────────────────────────────────────────────────────────────────────────────
+
+def hmm_analyze(src, symbol: str) -> dict:
+    """Full HMM analysis for one symbol — fetches 1h klines, runs infer_state.
+
+    Cached for HMM_TTL seconds per symbol.
+    Returns:
+      {
+        symbol, state, confidence,
+        state_probs: {BULL: float, BEAR: float, RANGING: float},
+        observables: {ret_pct, vol_ratio, rsi},
+        reasons, lookahead_safe, ts
+      }
+    """
+    cached = _hmm_cache.get(symbol)
+    if cached and time.time() - cached["ts"] < HMM_TTL:
+        return cached["result"]
+
+    try:
+        df = src.klines(symbol, "1h")
+        state, conf, probs, reasons = infer_state(df)
+        obs = compute_observables(df)
+
+        result = {
+            "symbol":      symbol,
+            "state":       state,
+            "confidence":  conf,
+            "state_probs": probs,
+            "observables": {
+                "ret_pct":   obs[0],
+                "vol_ratio": obs[1],
+                "rsi":       obs[2],
+            },
+            "reasons":        reasons,
+            "lookahead_safe": True,
+            "ts":             time.time(),
+        }
+
+        _hmm_cache[symbol] = {"result": result, "ts": time.time()}
+        return result
+
+    except Exception as e:
+        err = {
+            "symbol":      symbol,
+            "state":       "RANGING",
+            "confidence":  0.33,
+            "state_probs": {s: 1/3 for s in ALL_STATES},
+            "observables": {"ret_pct": 0.0, "vol_ratio": 1.0, "rsi": 50.0},
+            "reasons":     [f"Error: {str(e)[:80]}"],
+            "lookahead_safe": True,
+            "error":       str(e)[:80],
+            "ts":          time.time(),
+        }
+        _hmm_cache[symbol] = {"result": err, "ts": time.time()}
+        return err

markov.py

@@ -0,0 +1,390 @@
+"""Markov Chain Market State Analysis — markov.py
+
+Classifies the current market into BULL / BEAR / RANGING using 3 objective
+criteria (EMA alignment, RSI zone, volume ratio) on CLOSED candles only.
+No lookahead bias: all computations use iloc[:-1] or iloc[-2] as 'current'.
+
+Functions:
+  classify_state(df)            → (state_str, confidence_0_to_1, reasons)
+  build_transition_matrix(df)   → {from_state: {to_state: prob, ...}, ...}
+  forecast_states(state, matrix, days) → {day: {state: prob, ...}, ...}
+  persistence_score(matrix, state)     → float 0.0–1.0
+  analyze_symbol(src, symbol)          → full analysis dict
+
+States: "BULL", "BEAR", "RANGING"
+"""
+from __future__ import annotations
+import math, time
+from typing import Literal
+
+# ─── State type ──────────────────────────────────────────────────────────────
+State = Literal["BULL", "BEAR", "RANGING"]
+ALL_STATES: list[State] = ["BULL", "BEAR", "RANGING"]
+
+# ─── Cache: 30-min TTL per symbol ────────────────────────────────────────────
+_mk_cache: dict = {}
+MK_TTL = 1800   # 30 minutes — matrix is stable; no need to re-compute every scan
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# CORE: Classify a single candle/row into a state
+# Uses only CLOSED data — no lookahead. Call on df.iloc[:-1] for live candle.
+# ─────────────────────────────────────────────────────────────────────────────
+
+def _classify_row(close_series, vol_series, idx: int, lookback: int = 50) -> State:
+    """Classify state at index `idx` using data UP TO idx (inclusive).
+    Requires at least `lookback` rows before idx."""
+    start = max(0, idx - lookback + 1)
+    closes = close_series.iloc[start:idx + 1]
+    vols   = vol_series.iloc[start:idx + 1]
+
+    if len(closes) < 20:
+        return "RANGING"
+
+    c = closes.values
+
+    # ── EMA alignment ────────────────────────────────────────────────────────
+    # Fast EMA(20) vs Slow EMA(50)
+    def _ema(arr, span):
+        k = 2.0 / (span + 1)
+        result = [arr[0]]
+        for v in arr[1:]:
+            result.append(result[-1] * (1 - k) + v * k)
+        return result
+
+    if len(c) >= 50:
+        e20 = _ema(c, 20)[-1]
+        e50 = _ema(c, 50)[-1]
+        ema_bull = e20 > e50 * 1.001   # 0.1% buffer to avoid noise
+        ema_bear = e20 < e50 * 0.999
+    elif len(c) >= 20:
+        e20 = _ema(c, 20)[-1]
+        e10 = _ema(c, 10)[-1]
+        ema_bull = e10 > e20 * 1.001
+        ema_bear = e10 < e20 * 0.999
+    else:
+        ema_bull = ema_bear = False
+
+    # ── RSI(14) zone ─────────────────────────────────────────────────────────
+    rsi_len = min(14, len(c) - 1)
+    if rsi_len >= 2:
+        deltas = [c[i] - c[i-1] for i in range(1, len(c))]
+        gains  = [max(d, 0) for d in deltas[-rsi_len:]]
+        losses = [max(-d, 0) for d in deltas[-rsi_len:]]
+        avg_g  = sum(gains) / rsi_len
+        avg_l  = sum(losses) / rsi_len
+        if avg_l == 0:
+            rsi = 100.0
+        elif avg_g == 0:
+            rsi = 0.0
+        else:
+            rs  = avg_g / avg_l
+            rsi = 100.0 - (100.0 / (1.0 + rs))
+    else:
+        rsi = 50.0
+
+    rsi_bull = rsi >= 55
+    rsi_bear = rsi <= 45
+
+    # ── Volume ratio (recent 5 vs 20-bar avg) ─────────────────────────────────
+    if len(vols) >= 20:
+        vol_avg = float(vols.iloc[-20:].mean())
+        vol_recent = float(vols.iloc[-5:].mean()) if len(vols) >= 5 else vol_avg
+        vol_ratio = vol_recent / vol_avg if vol_avg > 0 else 1.0
+    else:
+        vol_ratio = 1.0
+
+    # Volume above average strengthens the directional signal
+    vol_confirms = vol_ratio >= 1.10   # 10% above avg = confirming
+
+    # ── Vote: majority rule across 3 criteria ─────────────────────────────────
+    bull_votes = sum([ema_bull, rsi_bull, (vol_confirms and ema_bull)])
+    bear_votes = sum([ema_bear, rsi_bear, (vol_confirms and ema_bear)])
+
+    if bull_votes >= 2:
+        return "BULL"
+    elif bear_votes >= 2:
+        return "BEAR"
+    else:
+        return "RANGING"
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# PUBLIC: classify_state — current market state + confidence
+# ─────────────────────────────────────────────────────────────────────────────
+
+def classify_state(df) -> tuple[State, float, list[str]]:
+    """Classify current market state from a klines DataFrame.
+
+    Uses only closed candles (iloc[:-1] = last confirmed candle).
+    Returns (state, confidence_0_to_1, reasons).
+    """
+    reasons = []
+
+    if df is None or len(df) < 22:
+        return "RANGING", 0.40, ["Insufficient data"]
+
+    # Use last CLOSED candle = iloc[-2] for live; for building matrix use all
+    closes = df["close"]
+    vols   = df["volume"] if "volume" in df.columns else df.get("vol", df["close"] * 0)
+
+    # ── EMA alignment on full history (closed candles only = iloc[:-1]) ──────
+    idx = len(closes) - 2   # last confirmed closed candle
+    c   = closes.values[:idx+1]
+
+    def _ema_arr(arr, span):
+        k = 2.0 / (span + 1)
+        result = [arr[0]]
+        for v in arr[1:]:
+            result.append(result[-1] * (1 - k) + v * k)
+        return result
+
+    e20 = _ema_arr(c, 20)[-1] if len(c) >= 20 else c[-1]
+    e50 = _ema_arr(c, 50)[-1] if len(c) >= 50 else e20
+
+    ema_bull = e20 > e50 * 1.001
+    ema_bear = e20 < e50 * 0.999
+
+    if ema_bull:
+        reasons.append(f"EMA20 ({e20:.4g}) > EMA50 ({e50:.4g}) — bullish alignment")
+    elif ema_bear:
+        reasons.append(f"EMA20 ({e20:.4g}) < EMA50 ({e50:.4g}) — bearish alignment")
+    else:
+        reasons.append(f"EMA20 ≈ EMA50 — no trend")
+
+    # ── RSI(14) ──────────────────────────────────────────────────────────────
+    rsi_len = 14
+    deltas = [float(c[i]) - float(c[i-1]) for i in range(1, len(c))]
+    gains  = [max(d, 0) for d in deltas[-rsi_len:]]
+    losses = [max(-d, 0) for d in deltas[-rsi_len:]]
+    avg_g  = sum(gains) / rsi_len
+    avg_l  = sum(losses) / rsi_len
+    if avg_l == 0:
+        rsi = 100.0
+    elif avg_g == 0:
+        rsi = 0.0
+    else:
+        rsi = 100.0 - 100.0 / (1.0 + avg_g / avg_l)
+
+    rsi_bull = rsi >= 55
+    rsi_bear = rsi <= 45
+    reasons.append(f"RSI14 = {rsi:.1f} ({'bullish' if rsi_bull else 'bearish' if rsi_bear else 'neutral'})")
+
+    # ── Volume ratio ─────────────────────────────────────────────────────────
+    vol_vals = vols.values[:idx+1]
+    if len(vol_vals) >= 20:
+        vol_avg    = sum(vol_vals[-20:]) / 20
+        vol_recent = sum(vol_vals[-5:]) / 5 if len(vol_vals) >= 5 else vol_avg
+        vol_ratio  = vol_recent / vol_avg if vol_avg > 0 else 1.0
+    else:
+        vol_ratio = 1.0
+    vol_up = vol_ratio >= 1.10
+    reasons.append(f"Volume ratio {vol_ratio:.2f}× 20-bar avg ({'elevated' if vol_up else 'normal/low'})")
+
+    # ── State + confidence ────────────────────────────────────────────────────
+    bull_score = sum([ema_bull, rsi_bull, (vol_up and ema_bull)])
+    bear_score = sum([ema_bear, rsi_bear, (vol_up and ema_bear)])
+
+    if bull_score >= 2:
+        state = "BULL"
+        # Confidence: how strongly all signals agree
+        confidence = 0.50 + 0.15 * bull_score   # 2→0.80, 3→0.95
+    elif bear_score >= 2:
+        state = "BEAR"
+        confidence = 0.50 + 0.15 * bear_score
+    else:
+        state = "RANGING"
+        # Lower confidence when signals are mixed, higher when cleanly flat
+        mix = abs(bull_score - bear_score)
+        confidence = 0.55 if mix == 0 else 0.48
+
+    confidence = round(min(0.95, max(0.35, confidence)), 2)
+    return state, confidence, reasons
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# PUBLIC: build_transition_matrix — empirical from 500 candles
+# ─────────────────────────────────────────────────────────────────────────────
+
+def build_transition_matrix(df, lookback: int = 500) -> dict[str, dict[str, float]]:
+    """Walk through last `lookback` closed candles, classify each, count transitions.
+
+    Returns:
+      {
+        "BULL":    {"BULL": 0.78, "BEAR": 0.08, "RANGING": 0.14},
+        "BEAR":    {"BULL": 0.09, "BEAR": 0.76, "RANGING": 0.15},
+        "RANGING": {"BULL": 0.28, "BEAR": 0.27, "RANGING": 0.45},
+      }
+    """
+    closes = df["close"]
+    vols   = df["volume"] if "volume" in df.columns else df.get("vol", df["close"] * 0)
+
+    n = len(closes)
+    # We need at least 50 rows to meaningfully classify; cap lookback
+    start = max(50, n - lookback)
+    end   = n - 1   # exclude live (open) candle
+
+    # Classify each candle
+    labels: list[State] = []
+    for i in range(start, end):
+        labels.append(_classify_row(closes, vols, i))
+
+    # Count transitions
+    counts: dict[str, dict[str, int]] = {
+        s: {t: 0 for t in ALL_STATES} for s in ALL_STATES
+    }
+    for i in range(len(labels) - 1):
+        counts[labels[i]][labels[i+1]] += 1
+
+    # Normalize rows
+    matrix: dict[str, dict[str, float]] = {}
+    for state in ALL_STATES:
+        total = sum(counts[state].values())
+        if total == 0:
+            # No observations: uniform prior
+            matrix[state] = {s: 1/3 for s in ALL_STATES}
+        else:
+            matrix[state] = {s: round(counts[state][s] / total, 4) for s in ALL_STATES}
+
+    return matrix
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# PUBLIC: forecast_states — matrix exponentiation for multi-day forecast
+# ─────────────────────────────────────────────────────────────────────────────
+
+def _mat_multiply(A: dict, B: dict) -> dict:
+    """Multiply two 3×3 dicts-of-dicts."""
+    result = {s: {t: 0.0 for t in ALL_STATES} for s in ALL_STATES}
+    for i in ALL_STATES:
+        for k in ALL_STATES:
+            for j in ALL_STATES:
+                result[i][j] += A[i][k] * B[k][j]
+    return result
+
+
+def _mat_pow(M: dict, n: int) -> dict:
+    """Raise transition matrix M to the nth power."""
+    if n <= 0:
+        # Identity
+        return {s: {t: (1.0 if s == t else 0.0) for t in ALL_STATES} for s in ALL_STATES}
+    if n == 1:
+        return {s: dict(M[s]) for s in ALL_STATES}
+    half = _mat_pow(M, n // 2)
+    result = _mat_multiply(half, half)
+    if n % 2 == 1:
+        result = _mat_multiply(result, M)
+    return result
+
+
+def forecast_states(
+    current_state: State,
+    matrix: dict[str, dict[str, float]],
+    days: list[int] = None,
+    candles_per_day: int = 24,   # 1h candles → 24 per day
+) -> dict[int, dict[str, float]]:
+    """Forecast probability distribution over states for each horizon.
+
+    Args:
+      current_state:    Current state ("BULL", "BEAR", "RANGING")
+      matrix:           Transition matrix from build_transition_matrix()
+      days:             List of forecast horizons in days [1, 3, 7]
+      candles_per_day:  Number of 1h candles per day (24 for 1h bars)
+
+    Returns:
+      {1: {"BULL": 0.74, "BEAR": 0.14, "RANGING": 0.12},
+       3: {"BULL": 0.58, ...},
+       7: {"BULL": 0.45, ...}}
+    """
+    if days is None:
+        days = [1, 3, 7]
+
+    result = {}
+    for d in days:
+        steps = d * candles_per_day
+        Mn = _mat_pow(matrix, steps)
+        row = Mn[current_state]
+        result[d] = {s: round(row[s], 3) for s in ALL_STATES}
+
+    return result
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# PUBLIC: persistence_score — how sticky is the current state?
+# ─────────────────────────────────────────────────────────────────────────────
+
+def persistence_score(matrix: dict[str, dict[str, float]], state: State) -> float:
+    """Self-transition probability = P(state → same state).
+
+    Returns 0.0–1.0. High = state tends to persist.
+    """
+    return round(matrix.get(state, {}).get(state, 0.5), 4)
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# PUBLIC: analyze_symbol — full Markov analysis for one symbol
+# ─────────────────────────────────────────────────────────────────────────────
+
+def analyze_symbol(src, symbol: str) -> dict:
+    """Fetch 1h klines and run full Markov analysis.
+
+    Cached for MK_TTL seconds per symbol.
+    Returns:
+      {
+        symbol, state, confidence, reasons,
+        matrix, forecast, persistence,
+        candles_used, ts
+      }
+    """
+    cached = _mk_cache.get(symbol)
+    if cached and time.time() - cached["ts"] < MK_TTL:
+        return cached["result"]
+
+    try:
+        df = src.klines(symbol, "1h")
+
+        state, conf, reasons = classify_state(df)
+        matrix = build_transition_matrix(df, lookback=500)
+        forecast = forecast_states(state, matrix, days=[1, 3, 7])
+        persist  = persistence_score(matrix, state)
+
+        result = {
+            "symbol":      symbol,
+            "state":       state,
+            "confidence":  conf,
+            "reasons":     reasons,
+            "matrix":      matrix,
+            "forecast": {
+                "1d": forecast[1],
+                "3d": forecast[3],
+                "7d": forecast[7],
+            },
+            "persistence":    persist,
+            "candles_used":   min(len(df), 500),
+            "lookahead_safe": True,   # badge for frontend: closed candles only
+            "ts":             time.time(),
+        }
+
+        _mk_cache[symbol] = {"result": result, "ts": time.time()}
+        return result
+
+    except Exception as e:
+        err = {
+            "symbol":     symbol,
+            "state":      "RANGING",
+            "confidence": 0.40,
+            "reasons":    [f"Error: {str(e)[:80]}"],
+            "matrix":     {s: {t: 1/3 for t in ALL_STATES} for s in ALL_STATES},
+            "forecast":   {
+                "1d": {s: 1/3 for s in ALL_STATES},
+                "3d": {s: 1/3 for s in ALL_STATES},
+                "7d": {s: 1/3 for s in ALL_STATES},
+            },
+            "persistence":    0.50,
+            "candles_used":   0,
+            "lookahead_safe": True,
+            "error":          str(e)[:80],
+            "ts":             time.time(),
+        }
+        _mk_cache[symbol] = {"result": err, "ts": time.time()}
+        return err

scorer.py

@@ -11,6 +11,14 @@ from exchange import pick_source, INTERVAL_MS
 from catalyst import score_catalyst as _catalyst_score
 import time
 
+# Markov + HMM — imported lazily to avoid startup errors if not yet installed
+try:
+    from markov import analyze_symbol as _markov_analyze
+    from hmm import hmm_analyze as _hmm_analyze
+    _MARKOV_AVAILABLE = True
+except ImportError:
+    _MARKOV_AVAILABLE = False
+
 
 TIMEFRAMES = ["1h", "15m", "5m"]
 KLINE_LIMIT = 500
@@ -417,6 +425,11 @@ def _estimate_duration(tf_data: dict, levels: dict) -> dict:
     }
 
 
+def direction_to_state(direction: str) -> str:
+    """Map trade direction to expected market state."""
+    return "BULL" if direction == "long" else "BEAR" if direction == "short" else "RANGING"
+
+
 def _narrative(symbol, direction, confidence, struct_notes, vol_notes,
                pos_notes, tf_data) -> str:
     m15 = tf_data.get("15m", {})
@@ -499,12 +512,55 @@ def score_symbol(src, symbol: str,
                                  atr_pct, sizing)
     duration = _estimate_duration(tf_data, levels)
 
+    # ── Markov + HMM state analysis ──────────────────────────────────────
+    markov_data = None
+    hmm_data    = None
+    if _MARKOV_AVAILABLE:
+        try:
+            markov_data = _markov_analyze(src, symbol)
+            time.sleep(0.05)
+        except Exception:
+            pass
+        try:
+            hmm_data = _hmm_analyze(src, symbol)
+        except Exception:
+            pass
+
+    # ── State confidence gate: if HMM confidence < 60%, apply rank penalty ─
+    # Low-confidence state → market is ambiguous → penalise the overall score
+    hmm_state       = hmm_data.get("state", "RANGING")   if hmm_data else "RANGING"
+    hmm_confidence  = hmm_data.get("confidence", 0.5)    if hmm_data else 0.5
+    markov_state    = markov_data.get("state", "RANGING") if markov_data else "RANGING"
+    markov_conf     = markov_data.get("confidence", 0.5)  if markov_data else 0.5
+    persistence     = markov_data.get("persistence", 0.5) if markov_data else 0.5
+    forecast        = markov_data.get("forecast", {})     if markov_data else {}
+
+    # States must agree with trade direction; penalise if conflicting
+    state_aligned = True
+    if direction == "long"  and hmm_state == "BEAR":   state_aligned = False
+    if direction == "short" and hmm_state == "BULL":   state_aligned = False
+
+    # Confidence modifier: ranges from -1.5 to +1.0 on the 10-point scale
+    if hmm_confidence < 0.45:
+        state_modifier = -1.5   # very uncertain — penalise hard
+    elif hmm_confidence < 0.60:
+        state_modifier = -0.5   # moderate uncertainty
+    elif not state_aligned:
+        state_modifier = -1.0   # state opposes trade direction
+    elif hmm_state == direction_to_state(direction) and hmm_confidence >= 0.70:
+        state_modifier = +1.0   # state strongly confirms direction
+    else:
+        state_modifier = 0.0
+
+    confidence_adjusted = round(max(0.0, min(10.0, confidence + state_modifier)), 1)
+
     return {
         "symbol": symbol,
         "tv_symbol": src.tv_symbol(symbol),
         "direction": direction,
-        "confidence": confidence,
-        "narrative": _narrative(symbol, direction, confidence,
+        "confidence": confidence_adjusted,
+        "confidence_raw": confidence,
+        "narrative": _narrative(symbol, direction, confidence_adjusted,
                                 n_struct, n_vol, n_pos, tf_data),
         "close": close,
         "levels": levels,
@@ -520,6 +576,27 @@ def score_symbol(src, symbol: str,
         "leverage": leverage,
         # ── Duration estimate ──
         "duration": duration,
+        # ── Market State (Markov + HMM) ──
+        "market_state": {
+            "markov": {
+                "state":       markov_state,
+                "confidence":  markov_conf,
+                "persistence": persistence,
+                "forecast":    forecast,
+                "reasons":     markov_data.get("reasons", [])    if markov_data else [],
+                "lookahead_safe": True,
+            } if markov_data else None,
+            "hmm": {
+                "state":       hmm_state,
+                "confidence":  hmm_confidence,
+                "state_probs": hmm_data.get("state_probs", {})   if hmm_data else {},
+                "observables": hmm_data.get("observables", {})   if hmm_data else {},
+                "reasons":     hmm_data.get("reasons", [])       if hmm_data else [],
+                "lookahead_safe": True,
+            } if hmm_data else None,
+            "aligned_with_trade": state_aligned,
+            "state_modifier":     state_modifier,
+        },
         "evidence": {
             "structure": {"score": round(s_struct * 10, 1), "notes": n_struct},
             "volume":    {"score": round(s_vol * 10, 1),    "notes": n_vol},

signals.py

@@ -17,6 +17,14 @@ import math, statistics, time
 from indicators import analyze_timeframe, ema, rma, atr as calc_atr, swing_pivots
 from catalyst import fetch_fear_greed, fetch_coin_news
 
+# Markov + HMM optional — gracefully skip if unavailable
+try:
+    from markov import analyze_symbol as _markov_analyze
+    from hmm import hmm_analyze as _hmm_analyze
+    _MK_AVAILABLE = True
+except ImportError:
+    _MK_AVAILABLE = False
+
 # ── Cache: signal results per symbol, 5 min TTL ──────────────────────────────
 _sig_cache: dict = {}   # {symbol: {"result": dict, "ts": float}}
 SIG_TTL = 300
@@ -232,11 +240,80 @@ def _detect_news_spike(symbol: str) -> tuple[int, str, list[str]]:
 # MAIN ENTRY — scan one symbol
 # ─────────────────────────────────────────────────────────────────────────────
 
+# ─────────────────────────────────────────────────────────────────────────────
+# DETECTOR 5 — STATE TRANSITION SPIKE (Markov + HMM)
+# Fires when HMM confidence is high AND Markov transition probability
+# from current state to ANOTHER state in 1 day is elevated (>30%)
+# ─────────────────────────────────────────────────────────────────────────────
+
+def _detect_state_transition(src, symbol: str) -> tuple[int, str, list[str]]:
+    """Score 0–3. Returns (score, direction, reasons).
+
+    Uses Markov matrix to spot: will the current regime likely flip soon?
+    High transition prob → anticipate the coming move direction.
+    """
+    if not _MK_AVAILABLE:
+        return 0, "neutral", []
+
+    reasons = []
+    score = 0
+    direction = "neutral"
+
+    try:
+        mk = _markov_analyze(src, symbol)
+        hmm = _hmm_analyze(src, symbol)
+
+        state   = mk.get("state", "RANGING")
+        persist = mk.get("persistence", 0.5)
+        conf    = hmm.get("confidence", 0.5)
+        forecast_1d = mk.get("forecast", {}).get("1d", {})
+
+        if not forecast_1d:
+            return 0, "neutral", []
+
+        # High HMM confidence + low persistence = regime change imminent
+        if conf >= 0.65 and persist < 0.60:
+            score += 1
+            reasons.append(
+                f"State persistence {persist:.0%} — {state} regime showing cracks"
+            )
+
+        # Check if a different state has rising 1d probability
+        sorted_states = sorted(forecast_1d, key=forecast_1d.get, reverse=True)
+        top_state = sorted_states[0]
+        second_state = sorted_states[1]
+
+        # If the current state is NOT the most probable 1d state → transition likely
+        if top_state != state and forecast_1d[top_state] >= 0.45:
+            score += 1
+            reasons.append(
+                f"Markov 1d forecast: {top_state} {forecast_1d[top_state]:.0%} "
+                f"(currently {state}) — transition probable"
+            )
+            direction = "long" if top_state == "BULL" else "short" if top_state == "BEAR" else "neutral"
+
+        # Very high confidence of transitioning out
+        if state != "BULL" and forecast_1d.get("BULL", 0) >= 0.50:
+            score += 1
+            direction = "long"
+            reasons.append(f"BULL state probability {forecast_1d['BULL']:.0%} in 24h — momentum shift")
+        elif state != "BEAR" and forecast_1d.get("BEAR", 0) >= 0.50:
+            score += 1
+            direction = "short"
+            reasons.append(f"BEAR state probability {forecast_1d['BEAR']:.0%} in 24h — breakdown risk")
+
+    except Exception:
+        pass
+
+    return min(score, 3), direction, reasons
+
+
 MOVE_LABELS = {
-    "breakout":     "Breakout",
-    "acceleration": "Trend Acceleration",
-    "reversal":     "Reversal",
-    "news":         "News Spike",
+    "breakout":          "Breakout",
+    "acceleration":      "Trend Acceleration",
+    "reversal":          "Reversal",
+    "news":              "News Spike",
+    "state_transition":  "Regime Change",
 }
 
 def scan_symbol(src, symbol: str, secondary=None) -> dict | None:
@@ -286,9 +363,30 @@ def scan_symbol(src, symbol: str, secondary=None) -> dict | None:
         s_acc, d_acc, r_acc = _detect_acceleration(tf_data, funding)
         s_rev, d_rev, r_rev = _detect_reversal(df_1h, tf_data)
         s_news,d_news,r_news= _detect_news_spike(symbol)
+        s_st,  d_st,  r_st  = _detect_state_transition(src, symbol)
+
+        total_score   = s_bo + s_acc + s_rev + s_news + s_st
+        detectors_hit = sum(1 for s in (s_bo, s_acc, s_rev, s_news, s_st) if s > 0)
 
-        total_score   = s_bo + s_acc + s_rev + s_news
-        detectors_hit = sum(1 for s in (s_bo, s_acc, s_rev, s_news) if s > 0)
+        # ── HMM confidence boost: high-confidence state confirmation adds 1pt ─
+        hmm_boost = 0
+        hmm_state_info = None
+        if _MK_AVAILABLE:
+            try:
+                hmm_out = _hmm_analyze(src, symbol)
+                hmm_conf = hmm_out.get("confidence", 0.5)
+                hmm_state_txt = hmm_out.get("state", "RANGING")
+                if hmm_conf >= 0.70:
+                    hmm_boost = 1
+                    hmm_state_info = {
+                        "state":      hmm_state_txt,
+                        "confidence": hmm_conf,
+                        "state_probs": hmm_out.get("state_probs", {}),
+                    }
+                    r_st = r_st + [f"HMM confidence {hmm_conf:.0%} — {hmm_state_txt} state confirmed"]
+            except Exception:
+                pass
+        total_score += hmm_boost
 
         # ── Fire threshold: score ≥ 6 AND ≥ 2 detectors ──────────────────
         if total_score < 6 or detectors_hit < 2:
@@ -297,7 +395,7 @@ def scan_symbol(src, symbol: str, secondary=None) -> dict | None:
 
         # ── Determine dominant direction ──────────────────────────────────
         dir_votes: dict[str, int] = {}
-        for d, s in [(d_bo, s_bo), (d_acc, s_acc), (d_rev, s_rev), (d_news, s_news)]:
+        for d, s in [(d_bo, s_bo), (d_acc, s_acc), (d_rev, s_rev), (d_news, s_news), (d_st, s_st)]:
             if d != "neutral" and s > 0:
                 dir_votes[d] = dir_votes.get(d, 0) + s
         direction = max(dir_votes, key=dir_votes.get) if dir_votes else "neutral"
@@ -308,9 +406,10 @@ def scan_symbol(src, symbol: str, secondary=None) -> dict | None:
         if s_acc  > 0: move_types.append("acceleration")
         if s_rev  > 0: move_types.append("reversal")
         if s_news > 0: move_types.append("news")
+        if s_st   > 0: move_types.append("state_transition")
 
         # ── All reasons combined ──────────────────────────────────────────
-        all_reasons = r_bo + r_acc + r_rev + r_news
+        all_reasons = r_bo + r_acc + r_rev + r_news + r_st
 
         m15_data = tf_data.get("15m", {})
         close    = m15_data.get("close", 0)
@@ -330,14 +429,16 @@ def scan_symbol(src, symbol: str, secondary=None) -> dict | None:
             "move_types":  move_types,
             "urgency":     urgency,
             "total_score": total_score,
-            "max_score":   12,
+            "max_score":   16,   # 5 detectors × 3 + 1 HMM boost
             "detectors": {
-                "breakout":     {"score": s_bo,   "reasons": r_bo},
-                "acceleration": {"score": s_acc,  "reasons": r_acc},
-                "reversal":     {"score": s_rev,  "reasons": r_rev},
-                "news":         {"score": s_news, "reasons": r_news},
+                "breakout":         {"score": s_bo,   "reasons": r_bo},
+                "acceleration":     {"score": s_acc,  "reasons": r_acc},
+                "reversal":         {"score": s_rev,  "reasons": r_rev},
+                "news":             {"score": s_news, "reasons": r_news},
+                "state_transition": {"score": s_st,   "reasons": r_st},
             },
-            "reasons":   all_reasons,
+            "hmm_state":  hmm_state_info,
+            "reasons":    all_reasons,
             "close":     close,
             "rsi14":     m15_data.get("rsi14"),
             "atr_pct":   m15_data.get("atr_pct"),

static/index.html

@@ -1022,6 +1022,71 @@ nav {
 .dur-lbl { font-size:9px; font-weight:800; letter-spacing:0.7px; text-transform:uppercase; color:var(--t3); margin-bottom:1px; }
 .dur-val { font-size:15px; font-weight:700; font-family:var(--font-display); color:var(--t1); line-height:1.2; }
 
+/* ── Market State strip (Markov + HMM) ── */
+.state-strip {
+  background:rgba(255,255,255,0.55); border:1px solid rgba(0,0,0,0.06);
+  border-radius:12px; padding:9px 12px; margin-bottom:10px;
+}
+.state-strip-top {
+  display:flex; align-items:center; gap:8px; margin-bottom:6px;
+}
+.state-lbl { font-size:9px; font-weight:800; letter-spacing:0.7px; text-transform:uppercase; color:var(--t3); flex:1; }
+.state-trust {
+  font-size:9px; font-weight:700; color:var(--teal); background:var(--teal3);
+  border:1px solid rgba(13,148,136,0.18); border-radius:5px; padding:2px 6px;
+  letter-spacing:0.3px;
+}
+.state-badges { display:flex; gap:6px; align-items:center; flex-wrap:wrap; }
+.state-badge {
+  display:inline-flex; align-items:center; gap:4px;
+  font-size:12px; font-weight:800; padding:3px 10px; border-radius:8px;
+  letter-spacing:-0.2px; font-family:var(--font-display);
+}
+.state-badge.BULL    { color:var(--profit); background:rgba(209,250,229,0.7); border:1px solid rgba(5,150,105,0.2); }
+.state-badge.BEAR    { color:var(--loss);   background:rgba(254,226,226,0.7); border:1px solid rgba(220,38,38,0.2); }
+.state-badge.RANGING { color:var(--warn);   background:rgba(254,243,199,0.7); border:1px solid rgba(217,119,6,0.2); }
+.state-conf { font-size:10px; font-weight:600; color:var(--t3); }
+.state-conflict { font-size:10px; font-weight:600; color:var(--loss); margin-top:3px; }
+
+/* ── Forecast row inside state strip ── */
+.forecast-row {
+  display:flex; gap:8px; margin-top:8px;
+}
+.fc-cell {
+  flex:1; background:rgba(0,0,0,0.03); border-radius:8px; padding:5px 6px; text-align:center;
+}
+.fc-horizon { font-size:9px; font-weight:800; letter-spacing:0.5px; text-transform:uppercase; color:var(--t3); margin-bottom:3px; }
+.fc-bars { display:flex; flex-direction:column; gap:2px; }
+.fc-bar-row { display:flex; align-items:center; gap:3px; }
+.fc-bar-lbl { font-size:8px; font-weight:700; color:var(--t3); width:16px; text-align:right; }
+.fc-bar-track { flex:1; height:5px; background:rgba(0,0,0,0.06); border-radius:3px; overflow:hidden; }
+.fc-bar-fill { height:100%; border-radius:3px; transition:width 0.8s var(--ease); }
+.fc-bar-fill.BULL { background:var(--profit2); }
+.fc-bar-fill.BEAR { background:var(--loss2); }
+.fc-bar-fill.RANGING { background:var(--warn2); }
+.fc-bar-pct { font-size:8px; font-weight:700; color:var(--t2); width:22px; font-variant-numeric:tabular-nums; }
+
+/* ── State filter toggle ── */
+.state-filter-bar {
+  display:flex; align-items:center; gap:8px; margin-bottom:12px;
+  padding:8px 12px; background:rgba(255,255,255,0.6); border:1px solid rgba(0,0,0,0.06);
+  border-radius:12px; backdrop-filter:blur(8px);
+}
+.state-filter-lbl { font-size:10px; font-weight:800; letter-spacing:0.6px; text-transform:uppercase; color:var(--t3); }
+.state-filter-toggle {
+  display:inline-flex; align-items:center; gap:5px;
+  background:rgba(255,255,255,0.9); border:1px solid rgba(0,0,0,0.07);
+  border-radius:8px; padding:4px 10px;
+  font-size:11px; font-weight:700; color:var(--t2); cursor:pointer;
+  transition:all 0.2s;
+}
+.state-filter-toggle.active {
+  background:var(--teal3); border-color:rgba(13,148,136,0.3); color:var(--teal);
+}
+
+/* Signal type badge for state_transition */
+.sig-type-badge.state_transition { background:rgba(109,40,217,0.12); color:var(--purple2); }
+
 /* ── Actions ── */
 .card-acts { display:flex; gap:7px; margin-top:16px; }
 .ca {
@@ -1318,6 +1383,13 @@ nav {
     <div class="empty-p">Hit Scan Market to surface top trade setups</div>
   </div>
 
+  <div id="state-filter-bar" class="state-filter-bar" style="display:none">
+    <span class="state-filter-lbl">🧠 State Filter</span>
+    <button id="state-filter-toggle" class="state-filter-toggle" title="Only show cards where HMM state confidence ≥ 60%">
+      Show all states
+    </button>
+  </div>
+
   <div id="grid"></div>
 </section>
 
@@ -1548,6 +1620,24 @@ async function tickPrices() {
 function startLiveTicker() { clearInterval(liveTickerTimer); liveTickerTimer=setInterval(tickPrices,5000); }
 function stopLiveTicker()  { clearInterval(liveTickerTimer); liveCards.clear(); }
 
+/* ═══ State filter toggle ═══ */
+const _stateToggle = $('state-filter-toggle');
+if (_stateToggle) {
+  _stateToggle.addEventListener('click', () => {
+    const isActive = _stateToggle.classList.toggle('active');
+    _stateToggle.textContent = isActive
+      ? '✓ HMM confidence ≥ 60% only'
+      : 'Show all states';
+    // Re-run scan to apply filter (grid already cleared each scan, so trigger new scan)
+    // Just show a note — user needs to re-scan for filter to take effect
+    if (isActive) {
+      _stateToggle.title = 'Filter active — hit Scan Market to apply';
+    } else {
+      _stateToggle.title = 'Only show cards where HMM state confidence ≥ 60%';
+    }
+  });
+}
+
 /* ═══ Scan buttons ═══ */
 $('scan-btn').addEventListener('click', runScan);
 $('hero-cta').addEventListener('click', ()=>{
@@ -1590,6 +1680,12 @@ async function runScan() {
     if(!data.cards.length) { empty.style.display='flex'; return; }
 
     const maxHours=+($('max-hours')?.value||0);
+    const stateFilterOn = $('state-filter-toggle')?.classList.contains('active') || false;
+
+    // Show state filter bar now that we have data
+    const sfBar = $('state-filter-bar');
+    if (sfBar) sfBar.style.display = 'flex';
+
     let visibleCount=0;
     data.cards.forEach((c,i)=>{
       // Max hours filter — hide cards whose min estimate exceeds the filter
@@ -1598,6 +1694,11 @@ async function runScan() {
         // If we have a duration estimate and it exceeds the filter, skip
         if(durMax!=null && durMax>maxHours) return;
       }
+      // State confidence filter — only show cards where HMM confidence >= 60%
+      if(stateFilterOn){
+        const hmmConf = c.market_state?.hmm?.confidence || 0;
+        if(hmmConf > 0 && hmmConf < 0.60) return;
+      }
       visibleCount++;
       const el=buildCard(c,account,risk);
       el.style.animationDelay=(i*60)+'ms';
@@ -1637,6 +1738,7 @@ function buildCard(c, account, risk) {
   const ev=c.evidence||{}, tf=c.timeframes||{};
   const ri=c.rank_info||{};
   const prob=c.probability||{}, lev=c.leverage||{}, dur=c.duration||{};
+  const ms=c.market_state||{};
 
   const sym=c.symbol||'';
   const hasDash=sym.includes('-');
@@ -1754,6 +1856,57 @@ function buildCard(c, account, risk) {
     </div>
   </div>`:'';
 
+  // ── Market State block (Markov + HMM) ──
+  let stateHTML = '';
+  const mkData = ms.markov, hmmData = ms.hmm;
+  if (mkData || hmmData) {
+    const bestState = hmmData?.state || mkData?.state || 'RANGING';
+    const bestConf  = hmmData?.confidence || mkData?.confidence || 0.5;
+    const confPctState = Math.round(bestConf * 100);
+    const aligned = ms.aligned_with_trade !== false;
+    const conflictNote = !aligned
+      ? `<div class="state-conflict">⚠ State conflicts with trade direction — lower conviction</div>` : '';
+
+    // Markov + HMM badges
+    let badges = '';
+    if (hmmData) badges += `<span class="state-badge ${hmmData.state}" title="HMM: probabilistic inference">HMM · ${hmmData.state} <span class="state-conf">${Math.round(hmmData.confidence*100)}%</span></span>`;
+    if (mkData)  badges += `<span class="state-badge ${mkData.state}" title="Markov: state + transition matrix">MK · ${mkData.state} <span class="state-conf">${Math.round(mkData.confidence*100)}%</span></span>`;
+
+    // Forecast bars for 1d, 3d, 7d
+    let forecastHTML = '';
+    const forecast = mkData?.forecast || {};
+    if (Object.keys(forecast).length > 0) {
+      const horizons = [['1d','1 Day'], ['3d','3 Day'], ['7d','7 Day']];
+      forecastHTML = `<div class="forecast-row">` + horizons.map(([key, label]) => {
+        const f = forecast[key] || {};
+        return `<div class="fc-cell">
+          <div class="fc-horizon">${label}</div>
+          <div class="fc-bars">
+            ${['BULL','BEAR','RANGING'].map(s => {
+              const pct = Math.round((f[s]||0)*100);
+              return `<div class="fc-bar-row">
+                <span class="fc-bar-lbl">${s[0]}</span>
+                <div class="fc-bar-track"><div class="fc-bar-fill ${s}" style="width:${pct}%"></div></div>
+                <span class="fc-bar-pct">${pct}%</span>
+              </div>`;
+            }).join('')}
+          </div>
+        </div>`;
+      }).join('') + `</div>`;
+    }
+
+    stateHTML = `
+    <div class="state-strip" data-state="${bestState}" data-conf="${bestConf}">
+      <div class="state-strip-top">
+        <span class="state-lbl">🧠 Market State (Markov + HMM)</span>
+        <span class="state-trust">✓ No lookahead bias</span>
+      </div>
+      <div class="state-badges">${badges}</div>
+      ${conflictNote}
+      ${forecastHTML}
+    </div>`;
+  }
+
   let narr=(c.narrative||'');
   if(narr.length>210) narr=narr.slice(0,207)+'…';
 
@@ -1819,7 +1972,7 @@ function buildCard(c, account, risk) {
       <div class="sz-item"><div class="sz-lbl">Notional</div><div class="sz-val">${fu(sz.notional)}</div></div>
     </div>
 
-    ${probHTML}${levHTML}${durHTML}
+    ${probHTML}${levHTML}${durHTML}${stateHTML}
     ${narr?`<div class="narr">${narr}</div>`:''}
     <div class="rule"></div>
 
@@ -1870,7 +2023,8 @@ function buildCard(c, account, risk) {
 
 /* ═══ Signal cards ═══ */
 const MOVE_LABELS = {
-  breakout:'Breakout', acceleration:'Trend Accel.', reversal:'Reversal', news:'News Spike'
+  breakout:'Breakout', acceleration:'Trend Accel.', reversal:'Reversal',
+  news:'News Spike', state_transition:'Regime Change'
 };
 
 function buildSignalCard(a) {
@@ -1896,12 +2050,18 @@ function buildSignalCard(a) {
     return `<div class="sig-reason ${cls}">${r}</div>`;
   }).join('');
 
+  // HMM state badge in signal card
+  const hmmSig = a.hmm_state;
+  const hmmBadge = hmmSig
+    ? `<span class="state-badge ${hmmSig.state}" style="font-size:10px;padding:2px 7px;margin-left:4px">HMM·${hmmSig.state} ${Math.round(hmmSig.confidence*100)}%</span>`
+    : '';
+
   const el = document.createElement('div');
   el.className = `sig-card urgency-${urgency}`;
   el.innerHTML = `
     <div class="sig-header">
       <div>
-        <div class="sig-sym">${base}<span class="q">${quote}</span></div>
+        <div class="sig-sym">${base}<span class="q">${quote}</span>${hmmBadge}</div>
         <div style="font-size:10px;color:var(--t3);margin-top:2px;font-weight:600">${urgencyLabel}</div>
       </div>
       <span class="sig-dir ${dir}">${dir==='long'?'▲ LONG':dir==='short'?'▼ SHORT':'— WATCH'}</span>