Update app.py

app.py

@@ -1,72 +1,1108 @@
 """
-main.py — Gradio interface with integrated ML probability filter.
+main.py — OKX Quant Engine v4
+Adaptive Meta-Decision Engine
 
 Pipeline:
-    OHLCV Data
-        │
-        ▼
-    Rule Engine (regime + volume + scoring + veto)
-        │
-        ├─► Vetoed → skip (no ML call, save compute)
-        │
-        └─► Approved by rules
-                │
-                ▼
-            ML Filter (LightGBM / HGBM probability)
-                │
-                ├─► prob < threshold → FILTERED (shown as ML_REJECT)
-                │
-                └─► prob >= threshold → Risk Engine → Final setup
-                            │
-                            ▼
-                        Ranked output with ML prob overlay
+
+    OHLCV
+       │
+       ▼
+    RULE ENGINE
+       │
+       ├── VETO
+       │
+       ▼
+    ML PROBABILITY FILTER
+       │
+       ▼
+    ADAPTIVE META ENGINE
+       │
+       ├── Trend persistence
+       ├── Momentum alignment
+       ├── Noise / entropy
+       ├── Regime stability
+       ├── Signal freshness
+       ├── Historical directional hit-rate
+       ├── Monte Carlo robustness
+       └── Uncertainty penalty
+       │
+       ▼
+    RISK ENGINE
+       │
+       ▼
+    RANKED SETUPS
+
+Research use only.
 """
 
-import logging
-import sys
-import time
-from typing import List, Optional, Dict, Any
+import logging
+import sys
+import time
+import math
+from typing import List, Optional, Dict, Any, Tuple
+
+import numpy as np
+import pandas as pd
+import gradio as gr
+
+from config import (
+    DEFAULT_SYMBOLS,
+    TOP_N_DEFAULT,
+    DEFAULT_ACCOUNT_EQUITY,
+    TIMEFRAME,
+    CANDLE_LIMIT,
+)
+
+from data_fetcher import (
+    fetch_multiple,
+    fetch_instruments,
+)
+
+from regime import detect_regime
+from volume_analysis import analyze_volume
+from risk_engine import evaluate_risk
+from veto import apply_veto
+from scorer import (
+    compute_structure_score,
+    score_token,
+    rank_tokens,
+    format_score_bar,
+    quality_tier,
+)
+from feature_builder import (
+    build_feature_dict,
+    validate_features,
+)
+from ml_filter import TradeFilter
+
+
+# ============================================================================
+# LOGGING
+# ============================================================================
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+    stream=sys.stdout,
+)
+
+logger = logging.getLogger("main")
+
+
+# ============================================================================
+# GLOBAL ML MODEL
+# ============================================================================
+
+_TRADE_FILTER: Optional[TradeFilter] = TradeFilter.load_or_none()
+
+
+# ============================================================================
+# CONSTANTS
+# ============================================================================
+
+_TREND_ICON = {
+    "bullish": "▲",
+    "ranging": "◆",
+    "bearish": "▼",
+}
+
+_BREAK_LABEL = {
+    1: "↑UP",
+    -1: "↓DN",
+    0: " — ",
+}
+
+_DIR_LABEL = {
+    1: "LONG",
+    -1: "SHORT",
+    0: "NONE",
+}
+
+
+# ============================================================================
+# AMDE CONFIGURATION
+# ============================================================================
+
+AMDE_CONFIG = {
+    # Final meta score threshold
+    "meta_threshold": 0.64,
+
+    # Hard rejection threshold
+    "hard_threshold": 0.42,
+
+    # Historical analysis
+    "history_bars": 180,
+
+    # Forward bars used for directional outcome estimation
+    "forward_bars": 5,
+
+    # Monte Carlo iterations
+    "mc_iterations": 2500,
+
+    # Bootstrap sample size
+    "mc_sample_size": 100,
+
+    # Maximum noise allowed
+    "max_noise": 0.78,
+
+    # Minimum historical observations
+    "min_history": 30,
+
+    # Signal freshness
+    "freshness_half_life": 12,
+
+    # Meta weights
+    "weights": {
+        "rule": 0.20,
+        "ml": 0.22,
+        "trend": 0.12,
+        "momentum": 0.10,
+        "stability": 0.10,
+        "freshness": 0.06,
+        "history": 0.08,
+        "monte_carlo": 0.07,
+        "noise": 0.05,
+    },
+}
+
+
+# ============================================================================
+# BASIC HELPERS
+# ============================================================================
+
+def safe_float(x, default=0.0):
+    try:
+        value = float(x)
+        if math.isfinite(value):
+            return value
+    except Exception:
+        pass
+    return default
+
+
+def clamp(x: float, lo: float = 0.0, hi: float = 1.0) -> float:
+    return max(lo, min(hi, safe_float(x)))
+
+
+def sigmoid(x: float) -> float:
+    x = np.clip(x, -40, 40)
+    return float(1.0 / (1.0 + np.exp(-x)))
+
+
+def normalize_signed(x: float, scale: float = 1.0) -> float:
+    """
+    Converts arbitrary signed value into 0..1.
+    """
+    if scale == 0:
+        return 0.5
+
+    return clamp(0.5 + 0.5 * np.tanh(x / scale))
+
+
+# ============================================================================
+# DIRECTION
+# ============================================================================
+
+def infer_direction(
+    trend: str,
+    breakout: int,
+) -> int:
+
+    if trend == "bullish" or breakout == 1:
+        return 1
+
+    if trend == "bearish" or breakout == -1:
+        return -1
+
+    return 0
+
+
+# ============================================================================
+# DATA PREPARATION
+# ============================================================================
+
+def prepare_close_series(df: pd.DataFrame) -> pd.Series:
+
+    if "close" not in df.columns:
+        return pd.Series(dtype=float)
+
+    s = pd.to_numeric(
+        df["close"],
+        errors="coerce",
+    ).dropna()
+
+    return s
+
+
+def prepare_returns(df: pd.DataFrame) -> pd.Series:
+
+    close = prepare_close_series(df)
+
+    if len(close) < 3:
+        return pd.Series(dtype=float)
+
+    ret = close.pct_change().replace(
+        [np.inf, -np.inf],
+        np.nan,
+    ).dropna()
+
+    return ret
+
+
+# ============================================================================
+# TREND PERSISTENCE
+# ============================================================================
+
+def calculate_trend_persistence(
+    df: pd.DataFrame,
+    direction: int,
+    lookback: int = 40,
+) -> float:
+
+    close = prepare_close_series(df)
+
+    if len(close) < 10 or direction == 0:
+        return 0.5
+
+    close = close.iloc[-lookback:]
+
+    returns = close.pct_change().dropna()
+
+    if len(returns) < 5:
+        return 0.5
+
+    signed = returns * direction
+
+    positive_fraction = float(
+        (signed > 0).mean()
+    )
+
+    cumulative_direction = float(
+        np.sign(
+            signed.sum()
+        )
+    )
+
+    persistence = positive_fraction
+
+    if cumulative_direction > 0:
+        persistence += 0.10
+    elif cumulative_direction < 0:
+        persistence -= 0.10
+
+    return clamp(persistence)
+
+
+# ============================================================================
+# MOMENTUM ALIGNMENT
+# ============================================================================
+
+def calculate_momentum_alignment(
+    df: pd.DataFrame,
+    direction: int,
+) -> float:
+
+    close = prepare_close_series(df)
+
+    if len(close) < 30 or direction == 0:
+        return 0.5
+
+    windows = [5, 10, 20]
+
+    values = []
+
+    for w in windows:
+
+        if len(close) <= w:
+            continue
+
+        change = (
+            close.iloc[-1] /
+            close.iloc[-w - 1] -
+            1.0
+        )
+
+        signed_change = change * direction
+
+        # ±3% normalized through sigmoid
+        score = sigmoid(
+            signed_change / 0.03
+        )
+
+        values.append(score)
+
+    if not values:
+        return 0.5
+
+    return clamp(
+        float(np.mean(values))
+    )
+
+
+# ============================================================================
+# ENTROPY / NOISE
+# ============================================================================
+
+def calculate_market_entropy(
+    df: pd.DataFrame,
+    lookback: int = 60,
+) -> float:
+
+    returns = prepare_returns(df)
+
+    if len(returns) < 20:
+        return 0.5
+
+    returns = returns.iloc[-lookback:]
+
+    signs = np.sign(returns)
+
+    up = float((signs > 0).mean())
+    down = float((signs < 0).mean())
+    flat = float((signs == 0).mean())
+
+    probs = [
+        up,
+        down,
+        flat,
+    ]
+
+    entropy = 0.0
+
+    for p in probs:
+
+        if p > 0:
+            entropy -= p * math.log(
+                p,
+                3,
+            )
+
+    return clamp(entropy)
+
+
+def calculate_noise_score(
+    df: pd.DataFrame,
+) -> float:
+
+    """
+    0 = clean directional market
+    1 = noisy / random market
+    """
+
+    returns = prepare_returns(df)
+
+    if len(returns) < 20:
+        return 0.5
+
+    returns = returns.iloc[-80:]
+
+    # Sign autocorrelation
+    signs = np.sign(returns)
+
+    if len(signs) > 5:
+        autocorr = safe_float(
+            pd.Series(signs).autocorr(),
+            0.0,
+        )
+    else:
+        autocorr = 0.0
+
+    # Alternation rate
+    alternations = (
+        signs.iloc[1:].values !=
+        signs.iloc[:-1].values
+    )
+
+    alternation_rate = float(
+        np.mean(alternations)
+    )
+
+    entropy = calculate_market_entropy(
+        df
+    )
+
+    # Higher alternation + entropy = more noise
+    noise = (
+        0.35 * alternation_rate +
+        0.40 * entropy +
+        0.25 * (0.5 - autocorr)
+    )
+
+    return clamp(noise)
+
+
+# ============================================================================
+# REGIME STABILITY
+# ============================================================================
+
+def calculate_regime_stability(
+    df: pd.DataFrame,
+    direction: int,
+) -> float:
+
+    close = prepare_close_series(df)
+
+    if len(close) < 40:
+        return 0.5
+
+    returns = close.pct_change().dropna()
+
+    if len(returns) < 30:
+        return 0.5
+
+    recent = returns.iloc[-30:]
+
+    directional = (
+        recent * direction
+    )
+
+    mean_move = safe_float(
+        directional.mean()
+    )
+
+    volatility = safe_float(
+        recent.std(),
+        1e-9,
+    )
+
+    if volatility <= 1e-9:
+        return 0.5
+
+    signal_to_noise = (
+        mean_move / volatility
+    )
+
+    base = sigmoid(
+        signal_to_noise * 4.0
+    )
+
+    # Compare recent volatility with older volatility
+    old = returns.iloc[-80:-30]
+
+    if len(old) >= 10:
+
+        old_vol = safe_float(
+            old.std(),
+            volatility,
+        )
+
+        vol_ratio = (
+            volatility /
+            max(old_vol, 1e-9)
+        )
+
+        # Extreme volatility expansion reduces stability
+        if vol_ratio > 2.5:
+            base *= 0.75
+
+    return clamp(base)
+
+
+# ============================================================================
+# SIGNAL FRESHNESS
+# ============================================================================
+
+def calculate_signal_freshness(
+    df: pd.DataFrame,
+    direction: int,
+    lookback: int = 30,
+) -> float:
+
+    if direction == 0:
+        return 0.5
+
+    close = prepare_close_series(df)
+
+    if len(close) < lookback + 2:
+        return 0.5
+
+    returns = close.pct_change().dropna()
+
+    recent = returns.iloc[-lookback:]
+
+    signed = recent * direction
+
+    # Locate latest strong directional candle
+    threshold = (
+        signed.std() *
+        0.75
+    )
+
+    candidates = np.where(
+        signed.values > threshold
+    )[0]
+
+    if len(candidates) == 0:
+        return 0.5
+
+    bars_since = (
+        len(signed) -
+        1 -
+        candidates[-1]
+    )
+
+    half_life = AMDE_CONFIG[
+        "freshness_half_life"
+    ]
+
+    freshness = math.exp(
+        -bars_since /
+        max(half_life, 1)
+    )
+
+    return clamp(freshness)
+
+
+# ============================================================================
+# HISTORICAL DIRECTIONAL HIT RATE
+# ============================================================================
+
+def calculate_historical_edge(
+    df: pd.DataFrame,
+    direction: int,
+    forward_bars: int = 5,
+    lookback: int = 180,
+) -> Tuple[float, int]:
+
+    close = prepare_close_series(df)
+
+    if direction == 0:
+        return 0.5, 0
+
+    if len(close) < (
+        forward_bars + 30
+    ):
+        return 0.5, 0
+
+    close = close.iloc[
+        -lookback:
+    ]
+
+    values = close.values
+
+    outcomes = []
+
+    for i in range(
+        0,
+        len(values) - forward_bars,
+    ):
+
+        current = values[i]
+        future = values[
+            i + forward_bars
+        ]
+
+        if current <= 0:
+            continue
+
+        move = (
+            future / current -
+            1.0
+        )
+
+        signed_move = (
+            move * direction
+        )
+
+        if signed_move > 0:
+            outcomes.append(1)
+        else:
+            outcomes.append(0)
+
+    if len(outcomes) < AMDE_CONFIG[
+        "min_history"
+    ]:
+        return 0.5, len(outcomes)
+
+    hit_rate = float(
+        np.mean(outcomes)
+    )
+
+    return clamp(hit_rate), len(outcomes)
+
+
+# ============================================================================
+# MONTE CARLO ROBUSTNESS
+# ============================================================================
+
+def monte_carlo_robustness(
+    hit_rate: float,
+    iterations: int = 2500,
+    sample_size: int = 100,
+    rr: float = 2.0,
+    seed: Optional[int] = None,
+) -> Dict[str, float]:
+
+    """
+    Bootstrap/Monte-Carlo robustness.
+
+    Each synthetic trade:
+        win  -> +RR
+        loss -> -1
+
+    This is NOT a future-price predictor.
+    It measures how stable a given hit-rate
+    would be under random sequencing.
+    """
+
+    hit_rate = clamp(
+        hit_rate,
+        0.01,
+        0.99,
+    )
+
+    rng = np.random.default_rng(seed)
+
+    samples = rng.random(
+        (
+            iterations,
+            sample_size,
+        )
+    ) < hit_rate
+
+    pnl = (
+        samples * rr -
+        (~samples) * 1.0
+    )
+
+    final_pnl = pnl.sum(
+        axis=1
+    )
+
+    probability_positive = float(
+        np.mean(final_pnl > 0)
+    )
+
+    median_pnl = float(
+        np.median(final_pnl)
+    )
+
+    worst_5 = float(
+        np.percentile(
+            final_pnl,
+            5,
+        )
+    )
+
+    # Max drawdown distribution
+    cumulative = np.cumsum(
+        pnl,
+        axis=1,
+    )
+
+    running_max = np.maximum.accumulate(
+        cumulative,
+        axis=1,
+    )
+
+    drawdown = (
+        running_max -
+        cumulative
+    )
+
+    max_dd = np.max(
+        drawdown,
+        axis=1,
+    )
+
+    median_dd = float(
+        np.median(max_dd)
+    )
+
+    # Robustness:
+    # positive-ending probability
+    # + downside resilience
+    positive_component = (
+        probability_positive
+    )
+
+    downside_component = sigmoid(
+        -worst_5 / max(
+            sample_size * 0.20,
+            1,
+        )
+    )
+
+    robustness = (
+        0.70 *
+        positive_component +
+        0.30 *
+        (1.0 - downside_component)
+    )
+
+    return {
+        "robustness": clamp(
+            robustness
+        ),
+        "prob_positive": probability_positive,
+        "median_pnl_r": median_pnl,
+        "worst_5pct_pnl_r": worst_5,
+        "median_max_dd_r": median_dd,
+    }
+
+
+# ============================================================================
+# ML PROBABILITY NORMALIZATION
+# ============================================================================
+
+def calculate_ml_component(
+    ml_prob: Optional[float],
+    threshold: Optional[float],
+) -> float:
+
+    if ml_prob is None:
+        return 0.50
+
+    p = clamp(ml_prob)
+
+    if threshold is None:
+        return p
+
+    threshold = clamp(
+        threshold,
+        0.01,
+        0.99,
+    )
+
+    # Center the probability relative to model threshold.
+    # Does NOT exaggerate the raw probability.
+    spread = max(
+        1.0 - threshold,
+        threshold,
+        0.05,
+    )
+
+    relative = (
+        p - threshold
+    ) / spread
+
+    return clamp(
+        0.5 +
+        0.5 * np.tanh(relative)
+    )
+
+
+# ============================================================================
+# RULE SCORE COMPONENT
+# ============================================================================
+
+def calculate_rule_quality(
+    scores: Dict[str, Any],
+) -> float:
+
+    values = [
+        safe_float(
+            scores.get(
+                "regime_score",
+                0.5,
+            )
+        ),
+        safe_float(
+            scores.get(
+                "volume_score",
+                0.5,
+            )
+        ),
+        safe_float(
+            scores.get(
+                "structure_score",
+                0.5,
+            )
+        ),
+        safe_float(
+            scores.get(
+                "confidence_score",
+                0.5,
+            )
+        ),
+    ]
+
+    values = [
+        clamp(v)
+        for v in values
+    ]
+
+    return clamp(
+        np.mean(values)
+    )
+
+
+# ============================================================================
+# ADAPTIVE META ENGINE
+# ============================================================================
+
+def calculate_meta_engine(
+    df: pd.DataFrame,
+    direction: int,
+    scores: Dict[str, Any],
+    ml_prob: Optional[float],
+    ml_threshold: Optional[float],
+    rr: float = 2.0,
+) -> Dict[str, Any]:
+
+    trend_persistence = (
+        calculate_trend_persistence(
+            df,
+            direction,
+        )
+    )
+
+    momentum_alignment = (
+        calculate_momentum_alignment(
+            df,
+            direction,
+        )
+    )
+
+    noise = calculate_noise_score(
+        df
+    )
+
+    stability = calculate_regime_stability(
+        df,
+        direction,
+    )
+
+    freshness = calculate_signal_freshness(
+        df,
+        direction,
+    )
+
+    history_edge, history_n = (
+        calculate_historical_edge(
+            df,
+            direction,
+            forward_bars=AMDE_CONFIG[
+                "forward_bars"
+            ],
+            lookback=AMDE_CONFIG[
+                "history_bars"
+            ],
+        )
+    )
+
+    mc = monte_carlo_robustness(
+        hit_rate=history_edge,
+        iterations=AMDE_CONFIG[
+            "mc_iterations"
+        ],
+        sample_size=AMDE_CONFIG[
+            "mc_sample_size"
+        ],
+        rr=rr,
+    )
+
+    rule_quality = (
+        calculate_rule_quality(
+            scores
+        )
+    )
+
+    ml_component = (
+        calculate_ml_component(
+            ml_prob,
+            ml_threshold,
+        )
+    )
+
+    # Noise becomes a positive score:
+    # clean market -> close to 1
+    noise_component = (
+        1.0 - noise
+    )
+
+    weights = AMDE_CONFIG[
+        "weights"
+    ]
+
+    raw_meta = (
+        weights["rule"] *
+        rule_quality +
+
+        weights["ml"] *
+        ml_component +
+
+        weights["trend"] *
+        trend_persistence +
+
+        weights["momentum"] *
+        momentum_alignment +
+
+        weights["stability"] *
+        stability +
+
+        weights["freshness"] *
+        freshness +
+
+        weights["history"] *
+        history_edge +
+
+        weights["monte_carlo"] *
+        mc["robustness"] +
+
+        weights["noise"] *
+        noise_component
+    )
+
+    # --------------------------------------------------------------
+    # Uncertainty penalty
+    # --------------------------------------------------------------
+
+    uncertainty = (
+        0.35 * abs(
+            ml_component -
+            history_edge
+        ) +
+
+        0.25 * noise +
+
+        0.20 * (
+            1.0 -
+            stability
+        ) +
+
+        0.20 * (
+            1.0 -
+            freshness
+        )
+    )
+
+    meta_score = (
+        raw_meta *
+        (
+            1.0 -
+            0.20 * uncertainty
+        )
+    )
+
+    # --------------------------------------------------------------
+    # Hard rejection conditions
+    # --------------------------------------------------------------
+
+    hard_reject_reasons = []
+
+    if noise >= AMDE_CONFIG[
+        "max_noise"
+    ]:
+        hard_reject_reasons.append(
+            "HIGH_NOISE"
+        )
+
+    if stability < 0.20:
+        hard_reject_reasons.append(
+            "UNSTABLE_REGIME"
+        )
+
+    if (
+        history_n >= AMDE_CONFIG[
+            "min_history"
+        ]
+        and history_edge < 0.35
+    ):
+        hard_reject_reasons.append(
+            "WEAK_HISTORICAL_EDGE"
+        )
+
+    if meta_score < AMDE_CONFIG[
+        "hard_threshold"
+    ]:
+        hard_reject_reasons.append(
+            "LOW_META_SCORE"
+        )
+
+    hard_rejected = (
+        len(hard_reject_reasons) > 0
+    )
+
+    approved = (
+        not hard_rejected
+        and
+        meta_score >= AMDE_CONFIG[
+            "meta_threshold"
+        ]
+    )
+
+    # --------------------------------------------------------------
+    # Confidence
+    # --------------------------------------------------------------
+
+    confidence = (
+        0.35 * meta_score +
+        0.20 * trend_persistence +
+        0.15 * stability +
+        0.15 * history_edge +
+        0.15 * mc["robustness"]
+    )
+
+    confidence = clamp(
+        confidence
+    )
+
+    return {
+        "meta_score": meta_score,
+
+        "approved": approved,
+
+        "hard_rejected": hard_rejected,
+
+        "hard_reject_reasons":
+            hard_reject_reasons,
 
-import gradio as gr
+        "confidence": confidence,
 
-from config import (
-    DEFAULT_SYMBOLS,
-    TOP_N_DEFAULT,
-    DEFAULT_ACCOUNT_EQUITY,
-    TIMEFRAME,
-    CANDLE_LIMIT,
-)
-from data_fetcher import fetch_multiple, fetch_instruments
-from regime import detect_regime
-from volume_analysis import analyze_volume
-from risk_engine import evaluate_risk
-from veto import apply_veto, veto_summary
-from scorer import compute_structure_score, score_token, rank_tokens, format_score_bar, quality_tier
-from feature_builder import build_feature_dict, validate_features
-from ml_filter import TradeFilter
+        "rule_quality":
+            rule_quality,
 
-logging.basicConfig(
-    level=logging.INFO,
-    format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
-    stream=sys.stdout,
-)
-logger = logging.getLogger("main")
+        "ml_component":
+            ml_component,
 
-# Load ML filter once at startup (None if not yet trained)
-_TRADE_FILTER: Optional[TradeFilter] = TradeFilter.load_or_none()
+        "trend_persistence":
+            trend_persistence,
 
-_TREND_ICON  = {"bullish": "▲", "ranging": "◆", "bearish": "▼"}
-_BREAK_LABEL = {1: "↑UP", -1: "↓DN", 0: " — "}
-_DIR_LABEL   = {1: "LONG", -1: "SHORT", 0: "NONE"}
+        "momentum_alignment":
+            momentum_alignment,
 
+        "noise":
+            noise,
 
-def infer_direction(trend: str, breakout: int) -> int:
-    if trend == "bullish" or breakout == 1:
-        return 1
-    if trend == "bearish" or breakout == -1:
-        return -1
-    return 0
+        "noise_component":
+            noise_component,
+
+        "regime_stability":
+            stability,
+
+        "signal_freshness":
+            freshness,
+
+        "historical_edge":
+            history_edge,
+
+        "historical_samples":
+            history_n,
+
+        "uncertainty":
+            uncertainty,
 
+        "mc_robustness":
+            mc["robustness"],
+
+        "mc_prob_positive":
+            mc["prob_positive"],
+
+        "mc_median_pnl_r":
+            mc["median_pnl_r"],
+
+        "mc_worst_5pct_pnl_r":
+            mc["worst_5pct_pnl_r"],
+
+        "mc_median_max_dd_r":
+            mc["median_max_dd_r"],
+    }
+
+
+# ============================================================================
+# SINGLE SYMBOL ANALYSIS
+# ============================================================================
 
 def analyze_single(
     symbol: str,
@@ -76,209 +1112,767 @@ def analyze_single(
     equity_drawdown_pct: float = 0.0,
     use_ml: bool = True,
 ) -> Dict[str, Any]:
-    # ── RULE ENGINE ───────────────────────────────────────────────────────────
-    regime_data  = detect_regime(df)
-    volume_data  = analyze_volume(df, atr_series=regime_data["atr_series"])
-    structure_sc = compute_structure_score(regime_data)
-    direction    = infer_direction(regime_data["trend"], volume_data["breakout"])
-    vetoed, veto_reason = apply_veto(regime_data, volume_data, structure_sc, direction=direction)
-    scores = score_token(regime_data, volume_data, vetoed)
-
-    # ── ML FILTER ─────────────────────────────────���───────────────────────────
-    ml_prob       = None
-    ml_approved   = None
+
+    # ================================================================
+    # RULE ENGINE
+    # ================================================================
+
+    regime_data = detect_regime(
+        df
+    )
+
+    volume_data = analyze_volume(
+        df,
+        atr_series=regime_data[
+            "atr_series"
+        ],
+    )
+
+    structure_sc = (
+        compute_structure_score(
+            regime_data
+        )
+    )
+
+    direction = infer_direction(
+        regime_data["trend"],
+        volume_data["breakout"],
+    )
+
+    vetoed, veto_reason = apply_veto(
+        regime_data,
+        volume_data,
+        structure_sc,
+        direction=direction,
+    )
+
+    scores = score_token(
+        regime_data,
+        volume_data,
+        vetoed,
+    )
+
+    # ================================================================
+    # ML FILTER
+    # ================================================================
+
+    ml_prob = None
+    ml_approved = None
     ml_reject_reason = ""
 
-    if use_ml and _TRADE_FILTER is not None and not vetoed:
+    if (
+        use_ml
+        and
+        _TRADE_FILTER is not None
+        and
+        not vetoed
+    ):
+
         try:
-            feat = build_feature_dict(regime_data, volume_data, scores)
+
+            feat = build_feature_dict(
+                regime_data,
+                volume_data,
+                scores,
+            )
+
             if validate_features(feat):
-                result = _TRADE_FILTER.predict(regime_data, volume_data, scores)
-                ml_prob     = result.probability
+
+                result = (
+                    _TRADE_FILTER.predict(
+                        regime_data,
+                        volume_data,
+                        scores,
+                    )
+                )
+
+                ml_prob = result.probability
                 ml_approved = result.approved
-                ml_reject_reason = result.reject_reason
+                ml_reject_reason = (
+                    result.reject_reason
+                )
+
             else:
-                ml_approved = None  # pass through if features invalid
+
+                ml_approved = None
+
         except Exception as e:
-            logger.warning(f"{symbol}: ML filter error: {e}")
+
+            logger.warning(
+                f"{symbol}: ML filter error: {e}"
+            )
+
             ml_approved = None
 
-    # ── RISK ENGINE ───────────────────────────────────────────────────────────
-    # Only compute full risk if not vetoed by rules AND not rejected by ML
+    # ================================================================
+    # ADAPTIVE META ENGINE
+    # ================================================================
+
+    ml_threshold = None
+
+    if _TRADE_FILTER is not None:
+        ml_threshold = (
+            _TRADE_FILTER.threshold
+        )
+
+    meta = calculate_meta_engine(
+        df=df,
+        direction=direction,
+        scores=scores,
+        ml_prob=ml_prob,
+        ml_threshold=ml_threshold,
+    )
+
+    # ================================================================
+    # FINAL DECISION
+    # ================================================================
+
+    ml_pass = (
+        ml_approved is None
+        or
+        ml_approved
+    )
+
     final_approved = (
-        not vetoed and
-        (ml_approved is None or ml_approved)
-    )
-
-    risk_data = evaluate_risk(
-        close=float(df["close"].iloc[-1]),
-        atr=regime_data["atr"],
-        atr_pct=regime_data["atr_pct"],
-        regime_score=regime_data["regime_score"],
-        vol_ratio=regime_data["vol_ratio"],
-        volume_score=volume_data["volume_score"],
-        regime_confidence=regime_data["regime_confidence"],
-        vol_compressed=regime_data["vol_compressed"],
-        consec_losses=consec_losses,
-        equity_drawdown_pct=equity_drawdown_pct,
-        account_equity=account_equity,
-    ) if final_approved else {}
+        not vetoed
+        and
+        ml_pass
+        and
+        meta["approved"]
+    )
+
+    # ================================================================
+    # RISK ENGINE
+    # ================================================================
+
+    risk_data = {}
+
+    if final_approved:
+
+        risk_data = evaluate_risk(
+            close=float(
+                df["close"].iloc[-1]
+            ),
+
+            atr=regime_data[
+                "atr"
+            ],
+
+            atr_pct=regime_data[
+                "atr_pct"
+            ],
+
+            regime_score=regime_data[
+                "regime_score"
+            ],
+
+            vol_ratio=regime_data[
+                "vol_ratio"
+            ],
+
+            volume_score=volume_data[
+                "volume_score"
+            ],
+
+            regime_confidence=
+                regime_data[
+                    "regime_confidence"
+                ],
+
+            vol_compressed=
+                regime_data[
+                    "vol_compressed"
+                ],
+
+            consec_losses=
+                consec_losses,
+
+            equity_drawdown_pct=
+                equity_drawdown_pct,
+
+            account_equity=
+                account_equity,
+        )
+
+    # ================================================================
+    # RESULT
+    # ================================================================
 
     return {
-        "symbol":             symbol,
-        "close":              float(df["close"].iloc[-1]),
-        "trend":              regime_data["trend"],
-        "adx":                regime_data["adx"],
-        "di_plus":            regime_data["di_plus"],
-        "di_minus":           regime_data["di_minus"],
-        "vol_ratio":          regime_data["vol_ratio"],
-        "vol_compressed":     regime_data["vol_compressed"],
-        "vol_expanding_from_base": regime_data["vol_expanding_from_base"],
-        "vol_expanding":      regime_data["vol_expanding"],
-        "dist_atr":           regime_data["dist_atr"],
-        "price_extended":     regime_data["price_extended_long"] or regime_data["price_extended_short"],
-        "regime_confidence":  regime_data["regime_confidence"],
-        "spike":              volume_data["spike"],
-        "climax":             volume_data["climax"],
-        "absorption":         volume_data["absorption"],
-        "failed_breakout":    volume_data["failed_breakout"],
-        "recent_failed":      volume_data["recent_failed_count"],
-        "breakout":           volume_data["breakout"],
-        "obv_slope":          volume_data["obv_slope_norm"],
-        "delta_sign":         volume_data["delta_sign"],
-        "direction":          direction,
-        "rule_vetoed":        vetoed,
-        "veto_reason":        veto_reason,
-        "ml_prob":            ml_prob,
-        "ml_approved":        ml_approved,
-        "ml_reject_reason":   ml_reject_reason,
-        "final_approved":     final_approved,
-        "regime_score":       scores["regime_score"],
-        "volume_score":       scores["volume_score"],
-        "structure_score":    scores["structure_score"],
-        "confidence_score":   scores["confidence_score"],
-        "total_score":        scores["total_score"],
-        "risk":               risk_data,
+
+        "symbol":
+            symbol,
+
+        "close":
+            float(
+                df["close"].iloc[-1]
+            ),
+
+        "trend":
+            regime_data["trend"],
+
+        "adx":
+            regime_data["adx"],
+
+        "di_plus":
+            regime_data["di_plus"],
+
+        "di_minus":
+            regime_data["di_minus"],
+
+        "vol_ratio":
+            regime_data["vol_ratio"],
+
+        "vol_compressed":
+            regime_data["vol_compressed"],
+
+        "vol_expanding_from_base":
+            regime_data[
+                "vol_expanding_from_base"
+            ],
+
+        "vol_expanding":
+            regime_data[
+                "vol_expanding"
+            ],
+
+        "dist_atr":
+            regime_data["dist_atr"],
+
+        "price_extended":
+            (
+                regime_data[
+                    "price_extended_long"
+                ]
+                or
+                regime_data[
+                    "price_extended_short"
+                ]
+            ),
+
+        "regime_confidence":
+            regime_data[
+                "regime_confidence"
+            ],
+
+        "spike":
+            volume_data["spike"],
+
+        "climax":
+            volume_data["climax"],
+
+        "absorption":
+            volume_data["absorption"],
+
+        "failed_breakout":
+            volume_data["failed_breakout"],
+
+        "recent_failed":
+            volume_data[
+                "recent_failed_count"
+            ],
+
+        "breakout":
+            volume_data["breakout"],
+
+        "obv_slope":
+            volume_data[
+                "obv_slope_norm"
+            ],
+
+        "delta_sign":
+            volume_data["delta_sign"],
+
+        "direction":
+            direction,
+
+        "rule_vetoed":
+            vetoed,
+
+        "veto_reason":
+            veto_reason,
+
+        "ml_prob":
+            ml_prob,
+
+        "ml_approved":
+            ml_approved,
+
+        "ml_reject_reason":
+            ml_reject_reason,
+
+        "final_approved":
+            final_approved,
+
+        "regime_score":
+            scores["regime_score"],
+
+        "volume_score":
+            scores["volume_score"],
+
+        "structure_score":
+            scores["structure_score"],
+
+        "confidence_score":
+            scores["confidence_score"],
+
+        "total_score":
+            scores["total_score"],
+
+        "meta":
+            meta,
+
+        "risk":
+            risk_data,
     }
 
 
+# ============================================================================
+# ML STATUS
+# ============================================================================
+
 def _ml_status(d: Dict) -> str:
+
     if _TRADE_FILTER is None:
         return "NO_MODEL"
+
     if d["rule_vetoed"]:
         return "RULE_VET"
+
     if d["ml_prob"] is None:
-        return "ML_ERR  "
-    prob_str = f"{d['ml_prob']:.3f}"
-    return f"✓{prob_str}" if d["ml_approved"] else f"✗{prob_str}"
+        return "ML_ERR"
+
+    prob_str = (
+        f"{d['ml_prob']:.3f}"
+    )
+
+    if d["ml_approved"]:
+        return f"✓{prob_str}"
+
+    return f"✗{prob_str}"
+
+
+# ============================================================================
+# META STATUS
+# ============================================================================
+
+def _meta_status(
+    d: Dict,
+) -> str:
 
+    meta = d["meta"]
+
+    score = meta[
+        "meta_score"
+    ]
+
+    if meta["hard_rejected"]:
+        return f"✗{score:.3f}"
+
+    if meta["approved"]:
+        return f"✓{score:.3f}"
+
+    return f"~{score:.3f}"
+
+
+# ============================================================================
+# RANKED TABLE
+# ============================================================================
+
+def build_ranked_table(
+    ranked: list,
+    top_n: int,
+) -> str:
 
-def build_ranked_table(ranked: list, top_n: int) -> str:
     hdr = (
-        f"{'#':>3}  {'Symbol':<14}  {'Score':>7}  {'Tier':>4}  "
-        f"{'Regime':>6}  {'Vol':>6}  {'S':>5}  {'C':>5}  "
-        f"{'Trend':>7}  {'ADX':>5}  {'VR':>5}  "
-        f"{'ML':>8}  {'Status'}\n"
+        f"{'#':>3}  "
+        f"{'Symbol':<14}  "
+        f"{'Score':>7}  "
+        f"{'Tier':>4}  "
+        f"{'Meta':>7}  "
+        f"{'MC':>6}  "
+        f"{'Noise':>6}  "
+        f"{'Stab':>6}  "
+        f"{'Fresh':>6}  "
+        f"{'Trend':>7}  "
+        f"{'ADX':>5}  "
+        f"{'VR':>5}  "
+        f"{'ML':>8}  "
+        f"{'Status'}\n"
+    )
+
+    sep = "─" * 130 + "\n"
+
+    rows = (
+        hdr +
+        sep
     )
-    sep  = "─" * 105 + "\n"
-    rows = hdr + sep
 
-    for rank, (sym, d) in enumerate(ranked[:top_n], 1):
-        icon   = _TREND_ICON.get(d["trend"], "?")
-        tier   = quality_tier(d["total_score"])
-        ml_str = _ml_status(d)
+    for rank, (
+        sym,
+        d,
+    ) in enumerate(
+        ranked[:top_n],
+        1,
+    ):
+
+        icon = _TREND_ICON.get(
+            d["trend"],
+            "?",
+        )
+
+        tier = quality_tier(
+            d["total_score"]
+        )
+
+        ml_str = _ml_status(
+            d
+        )
+
+        meta = d["meta"]
+
+        meta_str = (
+            f"{meta['meta_score']:.3f}"
+        )
+
+        mc_str = (
+            f"{meta['mc_robustness']:.3f}"
+        )
+
+        noise_str = (
+            f"{meta['noise']:.3f}"
+        )
+
+        stab_str = (
+            f"{meta['regime_stability']:.3f}"
+        )
+
+        fresh_str = (
+            f"{meta['signal_freshness']:.3f}"
+        )
 
         if d["rule_vetoed"]:
-            status = "RULE_VET"
+
+            status = (
+                "RULE_VET"
+            )
+
         elif not d["final_approved"]:
-            status = "ML_FILT "
+
+            if meta["hard_rejected"]:
+                status = "META_VET"
+            else:
+                status = "FILTERED"
+
         else:
-            status = "OK      "
+
+            status = "OK"
 
         rows += (
-            f"{rank:>3}  {sym:<14}  {d['total_score']:>7.4f}  {tier:>4}  "
-            f"{d['regime_score']:>6.3f}  {d['volume_score']:>6.3f}  "
-            f"{d['structure_score']:>5.3f}  {d['confidence_score']:>5.3f}  "
-            f"{icon} {d['trend']:<5}  {d['adx']:>5.1f}  {d['vol_ratio']:>5.2f}  "
-            f"{ml_str:>8}  {status}\n"
+            f"{rank:>3}  "
+            f"{sym:<14}  "
+            f"{d['total_score']:>7.4f}  "
+            f"{tier:>4}  "
+            f"{meta_str:>7}  "
+            f"{mc_str:>6}  "
+            f"{noise_str:>6}  "
+            f"{stab_str:>6}  "
+            f"{fresh_str:>6}  "
+            f"{icon} "
+            f"{d['trend']:<5}  "
+            f"{d['adx']:>5.1f}  "
+            f"{d['vol_ratio']:>5.2f}  "
+            f"{ml_str:>8}  "
+            f"{status}\n"
         )
+
     return rows
 
 
-def build_best_detail(data: Dict[str, Any]) -> str:
-    r = data.get("risk", {})
-    sym = data["symbol"]
-    icon = _TREND_ICON.get(data["trend"], "?")
+# ============================================================================
+# BEST DETAIL
+# ============================================================================
+
+def build_best_detail(
+    data: Dict[str, Any],
+) -> str:
+
+    r = data.get(
+        "risk",
+        {},
+    )
+
+    meta = data[
+        "meta"
+    ]
+
+    sym = data[
+        "symbol"
+    ]
+
+    icon = _TREND_ICON.get(
+        data["trend"],
+        "?",
+    )
+
+    # --------------------------------------------------------------
+    # Volume state
+    # --------------------------------------------------------------
 
     vol_state = []
-    if data["vol_compressed"]:          vol_state.append("COMPRESSED")
-    if data["vol_expanding_from_base"]: vol_state.append("EXPANDING FROM BASE ✓")
-    if data["vol_expanding"] and not data["vol_expanding_from_base"]:
-        vol_state.append("EXPANDING (no base)")
-    vol_state_str = " | ".join(vol_state) or "NORMAL"
+
+    if data[
+        "vol_compressed"
+    ]:
+        vol_state.append(
+            "COMPRESSED"
+        )
+
+    if data[
+        "vol_expanding_from_base"
+    ]:
+        vol_state.append(
+            "EXPANDING FROM BASE ✓"
+        )
+
+    if (
+        data["vol_expanding"]
+        and
+        not data[
+            "vol_expanding_from_base"
+        ]
+    ):
+        vol_state.append(
+            "EXPANDING (no base)"
+        )
+
+    vol_state_str = (
+        " | ".join(
+            vol_state
+        )
+        or
+        "NORMAL"
+    )
+
+    # --------------------------------------------------------------
+    # ML section
+    # --------------------------------------------------------------
 
     ml_section = ""
+
     if _TRADE_FILTER is not None:
-        prob_str = f"{data['ml_prob']:.4f}" if data["ml_prob"] is not None else "N/A"
-        thresh_str = f"{_TRADE_FILTER.threshold:.4f}"
-        decision = "APPROVED ✓" if data["ml_approved"] else "FILTERED ✗"
+
+        prob_str = (
+            f"{data['ml_prob']:.4f}"
+            if data["ml_prob"]
+            is not None
+            else "N/A"
+        )
+
+        thresh_str = (
+            f"{_TRADE_FILTER.threshold:.4f}"
+        )
+
+        decision = (
+            "APPROVED ✓"
+            if data[
+                "ml_approved"
+            ]
+            else
+            "FILTERED ✗"
+        )
+
         ml_section = (
-            f"\n  ── ML PROBABILITY FILTER ─────────────────────────\n"
+            "\n"
+            "  ── ML PROBABILITY FILTER ───────────────\n"
             f"  P(win):          {prob_str}\n"
             f"  Threshold:       {thresh_str}\n"
             f"  ML Decision:     {decision}\n"
         )
 
+    # --------------------------------------------------------------
+    # AMDE section
+    # --------------------------------------------------------------
+
+    meta_section = (
+        "\n"
+        "  ── ADAPTIVE META-DECISION ENGINE ────────\n"
+        f"  META SCORE:       {meta['meta_score']:.4f}\n"
+        f"  META CONFIDENCE:  {meta['confidence']:.4f}\n"
+        f"  Trend Persistence:{meta['trend_persistence']:.4f}\n"
+        f"  Momentum Align:   {meta['momentum_alignment']:.4f}\n"
+        f"  Regime Stability: {meta['regime_stability']:.4f}\n"
+        f"  Signal Freshness: {meta['signal_freshness']:.4f}\n"
+        f"  Noise:            {meta['noise']:.4f}\n"
+        f"  Uncertainty:      {meta['uncertainty']:.4f}\n"
+        f"  Historical Edge:  {meta['historical_edge']:.4f}\n"
+        f"  History Samples:  {meta['historical_samples']}\n"
+        f"  MC Robustness:    {meta['mc_robustness']:.4f}\n"
+        f"  MC P(positive):   {meta['mc_prob_positive']:.4f}\n"
+        f"  MC Median PnL:    {meta['mc_median_pnl_r']:.2f}R\n"
+        f"  MC Worst 5%:      {meta['mc_worst_5pct_pnl_r']:.2f}R\n"
+        f"  MC Median MaxDD:  {meta['mc_median_max_dd_r']:.2f}R\n"
+    )
+
+    if meta[
+        "hard_reject_reasons"
+    ]:
+
+        meta_section += (
+            "  Meta Veto:        "
+            +
+            ", ".join(
+                meta[
+                    "hard_reject_reasons"
+                ]
+            )
+            +
+            "\n"
+        )
+
+    # --------------------------------------------------------------
+    # Risk
+    # --------------------------------------------------------------
+
     risk_section = ""
+
     if r:
+
         risk_section = (
-            f"\n  ── RISK PARAMETERS ────────────────────────────────\n"
+            "\n"
+            "  ── RISK PARAMETERS ──────────────────────\n"
             f"  Entry:           {r.get('entry_price', 0):.8f}\n"
-            f"  ATR:             {r.get('atr', 0):.8f}  ({r.get('atr_pct', 0):.3f}%)\n"
+            f"  ATR:             {r.get('atr', 0):.8f} "
+            f"({r.get('atr_pct', 0):.3f}%)\n"
             f"  Stop Mult:       {r.get('stop_mult', 0):.1f}x ATR\n"
-            f"  LONG  → Stop: {r.get('stop_long', 0):.8f}  Target: {r.get('target_long', 0):.8f}\n"
-            f"  SHORT → Stop: {r.get('stop_short', 0):.8f}  Target: {r.get('target_short', 0):.8f}\n"
+            f"  LONG  → Stop:    {r.get('stop_long', 0):.8f} "
+            f"Target: {r.get('target_long', 0):.8f}\n"
+            f"  SHORT → Stop:    {r.get('stop_short', 0):.8f} "
+            f"Target: {r.get('target_short', 0):.8f}\n"
             f"  R:R Ratio:       1 : {r.get('rr_ratio', 2):.1f}\n"
             f"  Risk Fraction:   {r.get('risk_fraction', 0):.4f}%\n"
             f"  $ At Risk:       ${r.get('dollar_at_risk', 0):.2f}\n"
             f"  Position Size:   ${r.get('position_notional', 0):.2f} notional\n"
             f"  Leverage (est):  {r.get('leverage_implied', 0):.2f}x\n"
             f"  Consec. Losses:  {r.get('consec_losses', 0)}\n"
-            f"  Sizing Halted:   {'YES ⛔' if r.get('sizing_halted') else 'no'}\n"
+            f"  Sizing Halted:   "
+            f"{'YES ⛔' if r.get('sizing_halted') else 'no'}\n"
         )
 
-    lines = [
-        "═" * 64,
-        f"  BEST APPROVED SETUP: {sym}  [{_DIR_LABEL.get(data['direction'], '?')}]",
-        "═" * 64,
-        f"  Trend:            {icon} {data['trend'].upper()}",
-        f"  ADX:              {data['adx']:.1f}  (DI+ {data['di_plus']:.1f} / DI- {data['di_minus']:.1f})",
-        f"  Vol State:        {vol_state_str}",
-        f"  Dist from Mean:   {data['dist_atr']:.2f} ATR",
-        f"  Regime Confidence:{data['regime_confidence']:.3f}",
-        "",
-        "  ── SCORES ──────────────────────────────────────────",
-        f"  Regime:     {format_score_bar(data['regime_score'])}",
-        f"  Volume:     {format_score_bar(data['volume_score'])}",
-        f"  Structure:  {format_score_bar(data['structure_score'])}",
-        f"  Confidence: {format_score_bar(data['confidence_score'])}",
-        f"  TOTAL:      {format_score_bar(data['total_score'])}",
-    ]
-    lines.append(ml_section)
-    lines.append(risk_section)
-    lines.append("═" * 64)
-    return "\n".join(lines)
+    # --------------------------------------------------------------
+    # Final
+    # --------------------------------------------------------------
+
+    lines = [
+
+        "═" * 68,
+
+        f"  BEST APPROVED SETUP: "
+        f"{sym} "
+        f"[{_DIR_LABEL.get(data['direction'], '?')}]",
+
+        "═" * 68,
+
+        f"  Trend:            "
+        f"{icon} "
+        f"{data['trend'].upper()}",
+
+        f"  ADX:              "
+        f"{data['adx']:.1f} "
+        f"(DI+ {data['di_plus']:.1f} / "
+        f"DI- {data['di_minus']:.1f})",
+
+        f"  Vol State:        "
+        f"{vol_state_str}",
+
+        f"  Dist from Mean:   "
+        f"{data['dist_atr']:.2f} ATR",
+
+        f"  Regime Confidence:"
+        f"{data['regime_confidence']:.3f}",
+
+        "",
+
+        "  ── SCORES ──────────────────────────────────────────",
+
+        f"  Regime:     "
+        f"{format_score_bar(data['regime_score'])}",
+
+        f"  Volume:     "
+        f"{format_score_bar(data['volume_score'])}",
+
+        f"  Structure:  "
+        f"{format_score_bar(data['structure_score'])}",
+
+        f"  Confidence: "
+        f"{format_score_bar(data['confidence_score'])}",
+
+        f"  TOTAL:      "
+        f"{format_score_bar(data['total_score'])}",
+
+    ]
+
+    lines.append(
+        ml_section
+    )
+
+    lines.append(
+        meta_section
+    )
+
+    lines.append(
+        risk_section
+    )
+
+    lines.append(
+        "═" * 68
+    )
+
+    return "\n".join(
+        lines
+    )
+
 
+# ============================================================================
+# SYMBOL PARSER
+# ============================================================================
+
+def parse_symbols(
+    raw: str,
+) -> List[str]:
 
-def parse_symbols(raw: str) -> List[str]:
     out = []
-    for tok in raw.replace(",", " ").replace("\n", " ").split():
+
+    for tok in (
+        raw
+        .replace(",", " ")
+        .replace("\n", " ")
+        .split()
+    ):
+
         tok = tok.strip().upper()
-        if tok:
-            out.append(tok if "-" in tok else f"{tok}-USDT")
-    return out or DEFAULT_SYMBOLS
+
+        if not tok:
+            continue
+
+        out.append(
+            tok
+            if "-" in tok
+            else
+            f"{tok}-USDT"
+        )
+
+    return (
+        out
+        or
+        DEFAULT_SYMBOLS
+    )
 
 
+# ============================================================================
+# RUN ANALYSIS
+# ============================================================================
+
 def run_analysis(
     symbols_input: str,
     equity: float,
@@ -287,195 +1881,764 @@ def run_analysis(
     top_n: int,
     use_live: bool,
     use_ml: bool,
-    progress=gr.Progress(track_tqdm=False),
+    progress=gr.Progress(
+        track_tqdm=False
+    ),
 ) -> str:
+
     t0 = time.time()
+
     lines = []
 
-    ml_status_str = "ACTIVE" if (_TRADE_FILTER is not None and use_ml) else (
-        "DISABLED" if not use_ml else "NOT TRAINED (run train.py)"
+    # ================================================================
+    # HEADER
+    # ================================================================
+
+    ml_status_str = (
+        "ACTIVE"
+        if (
+            _TRADE_FILTER
+            is not None
+            and
+            use_ml
+        )
+        else
+        (
+            "DISABLED"
+            if not use_ml
+            else
+            "NOT TRAINED"
+        )
     )
 
     lines += [
-        "━" * 68,
-        "  OKX QUANTITATIVE ANALYSIS ENGINE  v3",
+
+        "━" * 78,
+
+        "  OKX QUANTITATIVE ANALYSIS ENGINE v4",
+
+        "  Adaptive Meta-Decision Engine",
+
         f"  ML Filter: {ml_status_str}",
-        "━" * 68,
+
+        "━" * 78,
+
     ]
 
-    if _TRADE_FILTER is not None and use_ml:
-        lines.append(f"  ML threshold: {_TRADE_FILTER.threshold:.4f}  |  Stats: {_TRADE_FILTER.stats()}")
+    # ================================================================
+    # ML INFORMATION
+    # ================================================================
+
+    if (
+        _TRADE_FILTER
+        is not None
+        and
+        use_ml
+    ):
+
+        lines.append(
+            f"  ML threshold: "
+            f"{_TRADE_FILTER.threshold:.4f}"
+            f" | Stats: "
+            f"{_TRADE_FILTER.stats()}"
+        )
+
+    # ================================================================
+    # SYMBOLS
+    # ================================================================
 
     if use_live:
-        lines.append("⟳  Fetching live OKX instrument list...")
-        symbols = fetch_instruments("SPOT") or DEFAULT_SYMBOLS
-        lines.append(f"✓  {len(symbols)} live USDT instruments")
+
+        lines.append(
+            "⟳ Fetching live OKX instrument list..."
+        )
+
+        symbols = (
+            fetch_instruments(
+                "SPOT"
+            )
+            or
+            DEFAULT_SYMBOLS
+        )
+
+        lines.append(
+            f"✓ {len(symbols)} live USDT instruments"
+        )
+
     else:
-        symbols = parse_symbols(symbols_input)
-        lines.append(f"✓  {len(symbols)} symbol(s)")
+
+        symbols = parse_symbols(
+            symbols_input
+        )
+
+        lines.append(
+            f"✓ {len(symbols)} symbol(s)"
+        )
+
+    # ================================================================
+    # PARAMETERS
+    # ================================================================
 
     lines.append(
-        f"   Equity: ${equity:,.0f}  |  Losses: {int(consec_losses)}"
-        f"  |  DD: {drawdown_pct:.1f}%  |  TF: {TIMEFRAME}"
+
+        f"   Equity: ${equity:,.0f}"
+        f" | Losses: {int(consec_losses)}"
+        f" | DD: {drawdown_pct:.1f}%"
+        f" | TF: {TIMEFRAME}"
+
     )
+
     lines.append("")
 
-    total = len(symbols)
+    total = len(
+        symbols
+    )
+
+    # ================================================================
+    # FETCH
+    # ================================================================
 
-    def prog_cb(i, t, sym):
-        progress(i / t, desc=f"Fetching {sym} ({i}/{t})")
+    def prog_cb(
+        i,
+        t,
+        sym,
+    ):
+
+        progress(
+            i / max(t, 1),
+            desc=(
+                f"Fetching "
+                f"{sym} "
+                f"({i}/{t})"
+            ),
+        )
+
+    ohlcv_map = fetch_multiple(
+        symbols,
+        min_bars=50,
+        progress_callback=prog_cb,
+    )
+
+    lines.append(
+        f"✓ Fetched "
+        f"{len(ohlcv_map)}/{total}"
+    )
 
-    ohlcv_map = fetch_multiple(symbols, min_bars=50, progress_callback=prog_cb)
-    lines.append(f"✓  Fetched {len(ohlcv_map)}/{total}")
     lines.append("")
 
-    all_results: Dict[str, Any] = {}
+    # ================================================================
+    # ANALYZE
+    # ================================================================
+
+    all_results: Dict[
+        str,
+        Any
+    ] = {}
+
     errors = []
 
-    for sym, df in ohlcv_map.items():
+    for sym, df in (
+        ohlcv_map.items()
+    ):
+
         try:
-            all_results[sym] = analyze_single(
-                sym, df,
-                account_equity=equity,
-                consec_losses=int(consec_losses),
-                equity_drawdown_pct=drawdown_pct / 100.0,
-                use_ml=use_ml,
+
+            all_results[sym] = (
+                analyze_single(
+                    sym,
+                    df,
+                    account_equity=
+                        equity,
+                    consec_losses=
+                        int(
+                            consec_losses
+                        ),
+                    equity_drawdown_pct=
+                        drawdown_pct /
+                        100.0,
+                    use_ml=
+                        use_ml,
+                )
             )
+
         except Exception as exc:
-            logger.error(f"{sym}: {exc}", exc_info=True)
-            errors.append(sym)
+
+            logger.error(
+                f"{sym}: {exc}",
+                exc_info=True,
+            )
+
+            errors.append(
+                sym
+            )
+
+    # ================================================================
+    # ERRORS
+    # ================================================================
 
     if errors:
-        lines.append(f"⚠  Errors: {', '.join(errors)}")
 
-    ranked = rank_tokens(all_results)
+        lines.append(
+            f"⚠ Errors: "
+            f"{', '.join(errors)}"
+        )
+
+    # ================================================================
+    # RANK
+    # ================================================================
+
+    ranked = rank_tokens(
+        all_results
+    )
+
+    rule_vetoed_n = sum(
+        1
+        for _,
+        d in ranked
+        if d["rule_vetoed"]
+    )
+
+    ml_filtered_n = sum(
+        1
+        for _,
+        d in ranked
+        if (
+            not d["rule_vetoed"]
+            and
+            not d["final_approved"]
+            and
+            not d["meta"][
+                "hard_rejected"
+            ]
+        )
+    )
+
+    meta_filtered_n = sum(
+        1
+        for _,
+        d in ranked
+        if (
+            not d["rule_vetoed"]
+            and
+            d["meta"][
+                "hard_rejected"
+            ]
+        )
+    )
+
+    approved_n = sum(
+        1
+        for _,
+        d in ranked
+        if d["final_approved"]
+    )
 
-    rule_vetoed_n = sum(1 for _, d in ranked if d["rule_vetoed"])
-    ml_filtered_n = sum(1 for _, d in ranked if not d["rule_vetoed"] and not d["final_approved"])
-    approved_n    = sum(1 for _, d in ranked if d["final_approved"])
+    # ================================================================
+    # SUMMARY
+    # ================================================================
 
     lines += [
-        f"  {len(all_results)} analyzed  |  {approved_n} approved  |  "
-        f"{rule_vetoed_n} rule-vetoed  |  {ml_filtered_n} ML-filtered",
+
+        f"  {len(all_results)} analyzed"
+        f" | {approved_n} approved"
+        f" | {rule_vetoed_n} rule-vetoed"
+        f" | {ml_filtered_n} ML-filtered"
+        f" | {meta_filtered_n} meta-vetoed",
+
+        "",
+
+        "  ADAPTIVE META ENGINE",
+
+        f"  Threshold: "
+        f"{AMDE_CONFIG['meta_threshold']:.3f}",
+
+        f"  Hard threshold: "
+        f"{AMDE_CONFIG['hard_threshold']:.3f}",
+
+        f"  MC iterations: "
+        f"{AMDE_CONFIG['mc_iterations']}",
+
         "",
+
         "  RANKED SETUPS",
-        "─" * 105,
-        build_ranked_table(ranked, int(top_n)),
+
+        "─" * 130,
+
+        build_ranked_table(
+            ranked,
+            int(top_n),
+        ),
+
+    ]
+
+    # ================================================================
+    # BEST APPROVED
+    # ================================================================
+
+    final_approved = [
+        (s, d)
+        for s, d in ranked
+        if d["final_approved"]
     ]
 
-    final_approved = [(s, d) for s, d in ranked if d["final_approved"]]
     if final_approved:
-        best_sym, best_data = final_approved[0]
-        lines += ["", build_best_detail(best_data)]
+
+        best_sym, best_data = (
+            final_approved[0]
+        )
+
+        lines += [
+            "",
+            build_best_detail(
+                best_data
+            ),
+        ]
+
     else:
+
+        lines += [
+
+            "",
+
+            "  ⚠ No fully approved setups.",
+
+            "     Possible causes:",
+
+            "     • unfavorable market regime",
+
+            "     • ML rejection",
+
+            "     • high market noise",
+
+            "     • unstable regime",
+
+            "     • weak historical directional edge",
+
+            "     • low Monte Carlo robustness",
+
+            "     • meta score below threshold",
+
+        ]
+
+    # ================================================================
+    # SESSION STATS
+    # ================================================================
+
+    if (
+        _TRADE_FILTER
+        is not None
+        and
+        use_ml
+    ):
+
         lines += [
             "",
-            "  ⚠  No fully approved setups.",
-            "     Possible causes: market regime unfavorable, ML model not trained,",
-            "     or all signals vetoed by rule engine.",
+            f"  ML session stats: "
+            f"{_TRADE_FILTER.stats()}",
         ]
 
-    if _TRADE_FILTER is not None and use_ml:
-        lines += ["", f"  ML session stats: {_TRADE_FILTER.stats()}"]
+    # ================================================================
+    # FOOTER
+    # ================================================================
+
+    lines += [
+
+        "",
+
+        f"  ✓ Complete in "
+        f"{time.time() - t0:.1f}s",
+
+        "━" * 78,
+
+    ]
+
+    return "\n".join(
+        lines
+    )
 
-    lines += ["", f"  ✓  Complete in {time.time() - t0:.1f}s", "━" * 68]
-    return "\n".join(lines)
 
+# ============================================================================
+# GRADIO APP
+# ============================================================================
 
 def build_app() -> gr.Blocks:
+
     with gr.Blocks(
-        title="OKX Quant Engine v3",
+
+        title=
+            "OKX Quant Engine v4",
+
         theme=gr.themes.Base(
+
             primary_hue="slate",
+
             neutral_hue="zinc",
-            font=[gr.themes.GoogleFont("JetBrains Mono"), "monospace"],
+
+            font=[
+                gr.themes.GoogleFont(
+                    "JetBrains Mono"
+                ),
+                "monospace",
+            ],
         ),
+
         css="""
-        body, .gradio-container {
+
+        body,
+        .gradio-container {
             background: #060a10 !important;
-            font-family: 'JetBrains Mono', monospace !important;
-            max-width: 1280px !important;
+            font-family:
+                'JetBrains Mono',
+                monospace !important;
+            max-width: 1400px !important;
         }
+
         .gr-button-primary {
-            background: linear-gradient(90deg, #1a6bff, #0044cc) !important;
+            background:
+                linear-gradient(
+                    90deg,
+                    #1a6bff,
+                    #0044cc
+                ) !important;
+
             border: none !important;
+
             font-weight: 700 !important;
-            letter-spacing: 0.06em !important;
+
+            letter-spacing:
+                0.06em !important;
         }
+
         #output_box textarea {
-            font-family: 'JetBrains Mono', monospace !important;
-            font-size: 12px !important;
-            line-height: 1.55 !important;
-            background: #0a0e18 !important;
-            color: #b0c4de !important;
-            border: 1px solid #182030 !important;
-            min-height: 740px !important;
+
+            font-family:
+                'JetBrains Mono',
+                monospace !important;
+
+            font-size:
+                12px !important;
+
+            line-height:
+                1.55 !important;
+
+            background:
+                #0a0e18 !important;
+
+            color:
+                #b0c4de !important;
+
+            border:
+                1px solid #182030 !important;
+
+            min-height:
+                800px !important;
+        }
+
+        label {
+
+            color:
+                #4a6080 !important;
+
+            font-size:
+                11px !important;
+
+            text-transform:
+                uppercase !important;
+
+            letter-spacing:
+                0.09em !important;
+        }
+
+        h1,
+        h2 {
+
+            color:
+                #c0d4f0 !important;
+
+            font-family:
+                'JetBrains Mono',
+                monospace !important;
+        }
+
+        p {
+
+            color:
+                #384858 !important;
+
+            font-size:
+                12px !important;
+        }
+
+        .gr-panel {
+
+            background:
+                #0c1020 !important;
+
+            border:
+                1px solid #182030 !important;
         }
-        label { color: #4a6080 !important; font-size: 11px !important; text-transform: uppercase !important; letter-spacing: 0.09em !important; }
-        h1, h2 { color: #c0d4f0 !important; font-family: 'JetBrains Mono', monospace !important; }
-        p { color: #384858 !important; font-size: 12px !important; }
-        .gr-panel { background: #0c1020 !important; border: 1px solid #182030 !important; }
-        """,
+
+        """
+
     ) as app:
-        gr.Markdown("# ◈ OKX QUANT ENGINE  v3")
+
+        # ============================================================
+        # HEADER
+        # ============================================================
+
+        gr.Markdown(
+            "# ◈ OKX QUANT ENGINE v4"
+        )
+
         gr.Markdown(
-            "ADX · absorption detection · volatility compression · "
-            "fake breakout filter · **LightGBM probability layer** · adaptive risk"
+            "ADX · absorption detection · "
+            "volatility compression · "
+            "fake breakout filter · "
+            "ML probability · "
+            "**Adaptive Meta-Decision Engine** · "
+            "Monte Carlo robustness · "
+            "adaptive risk"
         )
 
+        # ============================================================
+        # INPUTS
+        # ============================================================
+
         with gr.Row():
-            with gr.Column(scale=2):
+
+            with gr.Column(
+                scale=2
+            ):
+
                 symbols_box = gr.Textbox(
-                    label="Symbols  (comma / newline — blank = defaults)",
-                    placeholder="BTC-USDT, ETH-USDT, SOL-USDT ...",
-                    lines=4, value="",
+
+                    label=
+                        "Symbols "
+                        "(comma / newline)",
+
+                    placeholder=
+                        "BTC-USDT, ETH-USDT, SOL-USDT ...",
+
+                    lines=4,
+
+                    value="",
                 )
-            with gr.Column(scale=1):
+
+            with gr.Column(
+                scale=1
+            ):
+
                 equity_slider = gr.Slider(
-                    label="Account Equity  ($)",
-                    minimum=100, maximum=1_000_000, step=500,
-                    value=DEFAULT_ACCOUNT_EQUITY,
+
+                    label=
+                        "Account Equity ($)",
+
+                    minimum=100,
+
+                    maximum=1_000_000,
+
+                    step=500,
+
+                    value=
+                        DEFAULT_ACCOUNT_EQUITY,
                 )
+
                 top_n_slider = gr.Slider(
-                    label="Top N  to Display",
-                    minimum=5, maximum=100, step=5, value=TOP_N_DEFAULT,
+
+                    label=
+                        "Top N to Display",
+
+                    minimum=5,
+
+                    maximum=100,
+
+                    step=5,
+
+                    value=
+                        TOP_N_DEFAULT,
+                )
+
+            with gr.Column(
+                scale=1
+            ):
+
+                consec_loss = gr.Slider(
+
+                    label=
+                        "Consecutive Losses",
+
+                    minimum=0,
+
+                    maximum=10,
+
+                    step=1,
+
+                    value=0,
+                )
+
+                drawdown = gr.Slider(
+
+                    label=
+                        "Drawdown from Peak (%)",
+
+                    minimum=0.0,
+
+                    maximum=30.0,
+
+                    step=0.5,
+
+                    value=0.0,
+                )
+
+                live_check = gr.Checkbox(
+
+                    label=
+                        "Fetch live OKX instruments",
+
+                    value=False,
                 )
-            with gr.Column(scale=1):
-                consec_loss = gr.Slider(label="Consecutive Losses", minimum=0, maximum=10, step=1, value=0)
-                drawdown    = gr.Slider(label="Drawdown from Peak  (%)", minimum=0.0, maximum=30.0, step=0.5, value=0.0)
-                live_check  = gr.Checkbox(label="Fetch live OKX instruments  (100+)", value=False)
-                ml_check    = gr.Checkbox(
-                    label=f"Enable ML Filter  (model: {'LOADED' if _TRADE_FILTER else 'NOT TRAINED'})",
-                    value=_TRADE_FILTER is not None,
+
+                ml_check = gr.Checkbox(
+
+                    label=(
+                        "Enable ML Filter "
+                        "(model: "
+                        f"{'LOADED' if _TRADE_FILTER else 'NOT TRAINED'})"
+                    ),
+
+                    value=(
+                        _TRADE_FILTER
+                        is not None
+                    ),
                 )
 
-        run_btn = gr.Button("▶  RUN ANALYSIS", variant="primary", size="lg")
+        # ============================================================
+        # AMDE SETTINGS DISPLAY
+        # ============================================================
+
+        gr.Markdown(
+            f"""
+### ⚡ Adaptive Meta Engine
+
+**Meta threshold:** `{AMDE_CONFIG['meta_threshold']:.2f}`  
+**Hard veto:** `{AMDE_CONFIG['hard_threshold']:.2f}`  
+**Historical window:** `{AMDE_CONFIG['history_bars']}` candles  
+**Monte Carlo:** `{AMDE_CONFIG['mc_iterations']:,}` simulations  
+**Forward horizon:** `{AMDE_CONFIG['forward_bars']}` candles
+
+The engine combines rule quality, ML probability,
+trend persistence, momentum, regime stability,
+signal freshness, historical directional edge,
+market noise and Monte Carlo robustness.
+"""
+        )
+
+        # ============================================================
+        # BUTTON
+        # ============================================================
+
+        run_btn = gr.Button(
+            "▶ RUN ADAPTIVE ANALYSIS",
+            variant="primary",
+            size="lg",
+        )
+
+        # ============================================================
+        # OUTPUT
+        # ============================================================
+
         output_box = gr.Textbox(
-            label="Analysis Output",
-            lines=50, max_lines=150,
+
+            label=
+                "Analysis Output",
+
+            lines=55,
+
+            max_lines=180,
+
             interactive=False,
-            elem_id="output_box",
+
+            elem_id=
+                "output_box",
         )
 
+        # ============================================================
+        # ACTION
+        # ============================================================
+
         run_btn.click(
+
             fn=run_analysis,
-            inputs=[symbols_box, equity_slider, consec_loss, drawdown, top_n_slider, live_check, ml_check],
-            outputs=output_box,
+
+            inputs=[
+                symbols_box,
+                equity_slider,
+                consec_loss,
+                drawdown,
+                top_n_slider,
+                live_check,
+                ml_check,
+            ],
+
+            outputs=
+                output_box,
         )
 
+        # ============================================================
+        # FOOTER
+        # ============================================================
+
         gr.Markdown(
-            "**Research use only. Not financial advice.**  "
-            "Train the ML filter: `python train.py --use-defaults`  |  "
-            "Re-optimize threshold: `python threshold_optimizer.py`"
+            """
+**Research use only. Not financial advice.**
+
+Train ML:
+`python train.py --use-defaults`
+
+Optimize ML threshold:
+`python threshold_optimizer.py`
+
+AMDE performs statistical robustness analysis;
+it does not guarantee future returns or a particular win rate.
+"""
         )
 
     return app
 
 
+# ============================================================================
+# MAIN
+# ============================================================================
+
 if __name__ == "__main__":
+
     import argparse
+
     parser = argparse.ArgumentParser()
-    parser.add_argument("--port", type=int, default=7860)
-    parser.add_argument("--share", action="store_true")
-    a = parser.parse_args()
-    build_app().launch(server_name="0.0.0.0", server_port=a.port, share=a.share, show_error=True)
+
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=7860,
+    )
+
+    parser.add_argument(
+        "--share",
+        action="store_true",
+    )
+
+    args = parser.parse_args()
+
+    build_app().launch(
+
+        server_name=
+            "0.0.0.0",
+
+        server_port=
+            args.port,
+
+        share=
+            args.share,
+
+        show_error=True,
+    )