Clean initial commit for HF Space

.gitignore

@@ -0,0 +1,58 @@
+# Local environments
+.venv/
+venv/
+env/
+ml/
+
+# Python cache/build artifacts
+__pycache__/
+*.py[cod]
+*$py.class
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+build/
+dist/
+*.egg-info/
+
+# Streamlit/local secrets
+.env
+.env.*
+.streamlit/secrets.toml
+
+# Jupyter and notebooks not needed by the Space runtime
+.ipynb_checkpoints/
+*.ipynb
+
+# Raw or regenerated data artifacts
+*.zip
+*.parquet
+*.pkl
+*.h5
+*.db
+eth_usd_*.csv
+dune_*.csv
+binance_data/
+2026-01_03/
+
+# Keep the small feature files used by the Streamlit app
+*.csv
+!data/
+!data/external_market_features.csv
+!data/whale_exchange_flow_features.csv
+
+# Logs and temporary outputs
+*.log
+logs/
+tmp/
+temp/
+output/
+catboost_info/
+
+# OS/editor files
+.DS_Store
+Thumbs.db
+*.Zone.Identifier
+*Zone.Identifier
+.vscode/
+.idea/

README.md

@@ -0,0 +1,18 @@
+---
+title: ETH USD Predictor
+emoji: 📈
+colorFrom: orange
+colorTo: blue
+sdk: streamlit
+sdk_version: 1.49.0
+app_file: app/streamlit_app.py
+pinned: false
+---
+
+# ETH V5 8h Paper-Trading Signal
+
+Streamlit dashboard for the ETH V5 8-hour paper-trading classifier.
+
+The app fetches recent ETH/USDT hourly bars, joins the saved external-market features, builds the same live feature set used by the notebook export, and displays the current paper-trading action.
+
+This is an experiment/paper-trading tool, not financial advice.

app.py

@@ -0,0 +1,7 @@
+"""Compatibility entrypoint for Streamlit hosts that expect app.py at repo root."""
+from pathlib import Path
+import runpy
+
+
+APP_PATH = Path(__file__).resolve().parent / "app" / "streamlit_app.py"
+runpy.run_path(str(APP_PATH), run_name="__main__")

requirements.txt

@@ -0,0 +1,12 @@
+streamlit==1.49.0
+pandas
+numpy
+polars
+pyarrow
+ccxt
+joblib
+huggingface_hub
+lightgbm
+scikit-learn
+ta
+pyTelegramBotAPI

src/backtest_utils.py

@@ -0,0 +1,48 @@
+"""Dual filter utilities — matches cleaned notebook implementation"""
+import numpy as np
+
+def dual_filter_backtest(preds, actuals, vols, ret30d, cost=0.0030, K=1.0,
+                         vol_floor_pct=0.75, ret30d_thresh=0.05, extra_edge=0.0):
+    """Exact dual filter logic from notebook"""
+    vols = np.asarray(vols, dtype=float)
+    ret30d = np.asarray(ret30d, dtype=float)
+    finite_vols = vols[np.isfinite(vols)]
+    vol_floor = np.nanpercentile(finite_vols, vol_floor_pct) if len(finite_vols) else np.nan
+    
+    trade_mask = (
+        np.isfinite(vols) &
+        np.isfinite(ret30d) &
+        (np.abs(ret30d) > ret30d_thresh) &
+        (vols > vol_floor)
+    )
+    
+    preds = np.asarray(preds, dtype=float)
+    actuals = np.asarray(actuals, dtype=float)
+    valid = np.isfinite(preds) & np.isfinite(actuals) & trade_mask
+    strong_signal = np.abs(preds) > (K * cost + extra_edge)
+    pos = np.where(valid & strong_signal, np.sign(preds), 0.0)
+    
+    # Reuse notebook backtest result logic
+    changes = np.abs(np.diff(pos, prepend=0.0))
+    gross = pos * actuals
+    net = gross - changes * cost
+    eq = np.cumprod(1.0 + net) if len(net) else np.array([1.0])
+    n_trades = int(np.sum(changes > 0))
+    active = pos != 0
+    
+    sharpe = np.mean(net) / np.std(net) * np.sqrt(365) if np.std(net) > 0 else 0.0
+    running_max = np.maximum.accumulate(eq)
+    max_dd = np.min((eq - running_max) / running_max) if len(eq) > 0 else 0.0
+    wr = np.mean(gross[active] > 0) if active.sum() else 0.0
+    
+    return {
+        "sharpe": float(sharpe),
+        "cum_return": float(eq[-1] - 1),
+        "max_dd": float(max_dd),
+        "wr": float(wr),
+        "n_trades": n_trades,
+        "pct_active": float(active.mean()),
+        "eq": eq,
+        "net": net,
+        "pos": pos,
+    }

src/config.py

@@ -0,0 +1,30 @@
+"""Configuration constants — 100% aligned with latest cleaned V5 notebook"""
+from pathlib import Path
+
+# V5 Strategy Parameters (from notebook)
+HORIZON_HOURS = 8
+MODEL_STEP_HOURS = 8
+COST_V5 = 0.0030
+BRT = 0.05                    # 30d return threshold
+BVF = 0.75                    # volume/volatility percentile floor
+BK5 = 1.0                     # base K multiplier
+REGIME_ROUTING = True
+REGIME_SPLIT_THRESH = 0.05
+
+# Model settings
+MODEL_TASK = "classification"
+CLASSIFICATION_EDGE_SCALE = 0.006
+
+# Paths
+BASE_DIR = Path(__file__).parent.parent
+MODEL_PATH = BASE_DIR / "model_export" / "v5_lgbm_24h_dualfilter.joblib"
+
+# Data & Exchange
+SYMBOL = "ETH/USDT"
+TIMEFRAME = "1h"              # We fetch hourly, then resample to 8h inside features
+EXCHANGE = "binance"
+
+# Hugging Face (change to your username/repo)
+HF_REPO_ID = "yourusername/eth-v5-model"   # ← update this
+
+print("✅ V5 Config loaded (latest notebook version)")

src/data_fetch.py

@@ -0,0 +1,27 @@
+"""Fetch latest hourly ETH data via CCXT — ready for V5 feature pipeline"""
+import ccxt # type: ignore
+import pandas as pd
+from datetime import datetime
+from src.config import SYMBOL, TIMEFRAME
+
+def fetch_latest_data(limit: int = 2000) -> pd.DataFrame:
+    """Returns hourly OHLCV + placeholder on-chain columns (exactly as notebook)"""
+    exchange = ccxt.binance({'enableRateLimit': True})
+    
+    print(f"📡 Fetching latest {TIMEFRAME} ETH data from Binance...")
+    ohlcv = exchange.fetch_ohlcv(SYMBOL, timeframe=TIMEFRAME, limit=limit)
+    
+    df = pd.DataFrame(ohlcv, columns=['timestamp', 'open', 'high', 'low', 'close', 'volume'])
+    df['timestamp'] = pd.to_datetime(df['timestamp'], unit='ms')
+    df = df.set_index('timestamp').sort_index()
+    df['return'] = df['close'].pct_change().fillna(0.0)
+    
+    # Placeholder on-chain (same scaling as original dataset)
+    df['tx_count'] = df['volume'] * 1.5
+    df['active_senders'] = df['volume'] * 0.8
+    df['active_receivers'] = df['volume'] * 0.7
+    df['total_eth_transferred'] = df['volume'] * 1.2
+    df['total_gas_used'] = df['volume'] * 0.9
+    
+    print(f"✅ Fetched {len(df)} hourly bars (up to {df.index[-1]})")
+    return df

src/features.py

@@ -0,0 +1,60 @@
+"""Full V5 Feature Engineering — mirrors cleaned notebook Part A (pandas version)"""
+import pandas as pd
+import numpy as np
+from ta.momentum import RSIIndicator # type: ignore
+from ta.trend import MACD # type: ignore
+
+def add_v5_features(df: pd.DataFrame) -> tuple[pd.DataFrame, list]:
+    df = df.copy()
+    if not isinstance(df.index, pd.DatetimeIndex):
+        df = df.set_index('timestamp').sort_index()
+
+    c, h, l, v, o = df['close'], df['high'], df['low'], df['volume'], df['open']
+
+    # === Core V5 blocks from notebook ===
+    for lag in [1, 2, 4, 6, 12, 24, 48, 168]:
+        df[f'return_{lag}h'] = c.pct_change(lag)
+
+    df['candle_body_ratio'] = (c - o) / (h - l + 1e-10)
+    df['range_pct'] = (h - l) / (c + 1e-10)
+    df['close_location_value'] = (c - l) / (h - l + 1e-10)
+
+    for w in [4, 12, 24, 48, 168]:
+        df[f'sma_{w}h'] = c.rolling(w).mean()
+        df[f'vol_{w}h'] = c.rolling(w).std()
+        df[f'vol_avg_{w}h'] = v.rolling(w).mean()
+        df[f'price_vs_sma_{w}h'] = c / df[f'sma_{w}h'] - 1
+
+    for period in [6, 14, 24]:
+        df[f'rsi_{period}h'] = RSIIndicator(c, window=period).rsi()
+
+    macd = MACD(c, window_slow=26, window_fast=12, window_sign=9)
+    df['macd_h'] = macd.macd()
+    df['macd_signal_h'] = macd.macd_signal()
+    df['macd_hist_h'] = macd.macd_diff()
+
+    df['vol_ratio_24h'] = v / (v.rolling(24).mean() + 1e-10)
+    df['vol_ratio_168h'] = v / (v.rolling(168).mean() + 1e-10)
+
+    # On-chain momentum
+    for col in ['tx_count', 'active_senders', 'active_receivers', 'total_eth_transferred', 'total_gas_used']:
+        if col in df.columns:
+            df[f'{col}_change_24h'] = df[col] / (df[col].shift(24) + 1e-10) - 1
+            df[f'{col}_ma24h'] = df[col].rolling(24).mean()
+
+    # Cyclical
+    df['hour_sin'] = np.sin(2 * np.pi * df.index.hour / 24) # type: ignore
+    df['hour_cos'] = np.cos(2 * np.pi * df.index.hour / 24) # type: ignore
+    df['dow_sin'] = np.sin(2 * np.pi * df.index.dayofweek / 7) # type: ignore
+    df['dow_cos'] = np.cos(2 * np.pi * df.index.dayofweek / 7) # type: ignore
+
+    # 30d regime features (used by filter & routing)
+    df['ret_30d'] = c.pct_change(30*24)          # ≈30d on 1h bars
+    df['vol_30d'] = df['return'].rolling(30*24).std()
+
+    df = df.dropna()
+    feature_cols = [col for col in df.columns if col not in 
+                    {'open','high','low','close','volume','timestamp'}]
+
+    print(f"✅ Built {len(feature_cols)} V5 features (matches notebook Part A)")
+    return df, feature_cols

src/inference_features.py

@@ -0,0 +1,291 @@
+"""Live V5 feature builder aligned with the cleaned notebook Part A."""
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+import polars as pl
+
+EXTERNAL_MARKET_PATHS = [
+    Path("data/external_market_features.csv"),
+    Path("data/external_market_features.parquet"),
+    Path("data/whale_exchange_flow_features.csv"),
+]
+
+
+def _parse_timestamp_column(frame: pl.DataFrame, timestamp_col: str = "timestamp") -> pl.DataFrame:
+    dtype = frame.schema.get(timestamp_col)
+    if dtype == pl.Datetime:
+        return frame.with_columns(pl.col(timestamp_col).dt.cast_time_unit("us").alias(timestamp_col))
+    return frame.with_columns(
+        pl.col(timestamp_col).cast(pl.Utf8).str.to_datetime(strict=False).alias(timestamp_col)
+    ).drop_nulls(timestamp_col)
+
+
+def load_external_market_features(paths=EXTERNAL_MARKET_PATHS, timestamp_col: str = "timestamp") -> pl.DataFrame | None:
+    frames = []
+    for raw_path in paths:
+        path = Path(raw_path)
+        if not path.exists():
+            continue
+        if path.suffix.lower() == ".parquet":
+            frame = pl.read_parquet(path)
+        else:
+            frame = pl.read_csv(path, try_parse_dates=False, infer_schema_length=10000)
+        if timestamp_col not in frame.columns:
+            continue
+        frame = _parse_timestamp_column(frame, timestamp_col).sort(timestamp_col)
+        numeric_cols = [
+            col for col, dtype in zip(frame.columns, frame.dtypes)
+            if col != timestamp_col and dtype.is_numeric()
+        ]
+        if not numeric_cols:
+            continue
+        renamed = {col: f"ext_{col}" if not col.startswith("ext_") else col for col in numeric_cols}
+        frames.append(frame.select([timestamp_col, *numeric_cols]).rename(renamed))
+
+    if not frames:
+        return None
+
+    out = frames[0]
+    for frame in frames[1:]:
+        out = out.join_asof(frame, on=timestamp_col, strategy="backward")
+    return out.sort(timestamp_col)
+
+
+def add_external_feature_transforms(frame: pl.DataFrame, external_cols: list[str]) -> tuple[pl.DataFrame, list[str]]:
+    engineered = []
+    for col in external_cols:
+        for lag in [1, 4, 8, 24]:
+            frame = frame.with_columns(pl.col(col).shift(lag).alias(f"{col}_lag_{lag}h"))
+            engineered.append(f"{col}_lag_{lag}h")
+        frame = frame.with_columns([
+            (pl.col(col) - pl.col(col).rolling_mean(24)).alias(f"{col}_dev_24h"),
+            (pl.col(col) / (pl.col(col).rolling_mean(168) + 1e-10) - 1).alias(f"{col}_vs_168h"),
+            pl.col(col).diff().rolling_mean(8).alias(f"{col}_flow_8h"),
+        ])
+        engineered.extend([f"{col}_dev_24h", f"{col}_vs_168h", f"{col}_flow_8h"])
+    return frame, engineered
+
+
+def _to_hourly_polars(df_raw: pd.DataFrame) -> pl.DataFrame:
+    df = df_raw.copy()
+    if "timestamp" not in df.columns:
+        if isinstance(df.index, pd.DatetimeIndex):
+            df = df.reset_index().rename(columns={df.index.name or "index": "timestamp"})
+        else:
+            raise ValueError("df_raw must have a timestamp column or DatetimeIndex")
+    df["timestamp"] = pd.to_datetime(df["timestamp"])
+
+    for col, scale in {
+        "tx_count": 1.5,
+        "active_senders": 0.8,
+        "active_receivers": 0.7,
+        "total_eth_transferred": 1.2,
+        "total_gas_used": 0.9,
+    }.items():
+        if col not in df.columns:
+            df[col] = df["volume"] * scale
+
+    frame = pl.from_pandas(df).with_columns(
+        pl.col("timestamp").dt.cast_time_unit("us").alias("timestamp")
+    ).sort("timestamp")
+    diffs = frame["timestamp"].diff().drop_nulls()
+    is_hourly = len(diffs) > 0 and diffs.dt.total_minutes().median() >= 55
+    if is_hourly:
+        return frame.select([
+            "timestamp", "open", "high", "low", "close", "volume",
+            "tx_count", "active_senders", "active_receivers",
+            "total_eth_transferred", "total_gas_used",
+        ])
+
+    return frame.group_by_dynamic("timestamp", every="1h").agg([
+        pl.col("open").first().alias("open"),
+        pl.col("high").max().alias("high"),
+        pl.col("low").min().alias("low"),
+        pl.col("close").last().alias("close"),
+        pl.col("volume").sum().alias("volume"),
+        pl.col("tx_count").first().alias("tx_count"),
+        pl.col("active_senders").first().alias("active_senders"),
+        pl.col("active_receivers").first().alias("active_receivers"),
+        pl.col("total_eth_transferred").first().alias("total_eth_transferred"),
+        pl.col("total_gas_used").first().alias("total_gas_used"),
+        pl.col("close").count().alias("tick_count_1h"),
+    ]).filter(pl.col("tick_count_1h") >= 30).drop("tick_count_1h").sort("timestamp")
+
+
+def build_live_v5_features(df_raw: pd.DataFrame) -> tuple[pd.DataFrame, list[str]]:
+    df_h5 = _to_hourly_polars(df_raw)
+
+    external_features = load_external_market_features()
+    external_feature_cols: list[str] = []
+    if external_features is not None:
+        df_h5 = df_h5.join_asof(external_features, on="timestamp", strategy="backward")
+        external_feature_cols = [col for col in external_features.columns if col != "timestamp"]
+        df_h5 = df_h5.with_columns([
+            pl.col(col).fill_null(strategy="forward").fill_null(0.0).alias(col)
+            for col in external_feature_cols
+        ])
+        df_h5, external_engineered_cols = add_external_feature_transforms(df_h5, external_feature_cols)
+        df_h5 = df_h5.with_columns([
+            pl.col(col).fill_null(strategy="forward").fill_null(0.0).alias(col)
+            for col in external_engineered_cols
+        ])
+        external_feature_cols = external_feature_cols + external_engineered_cols
+
+    c, h, l, v, o = pl.col("close"), pl.col("high"), pl.col("low"), pl.col("volume"), pl.col("open")
+
+    for lag in [1, 2, 4, 6, 12, 24, 48, 168]:
+        df_h5 = df_h5.with_columns((c / c.shift(lag) - 1).alias(f"return_{lag}h"))
+
+    df_h5 = df_h5.with_columns([
+        ((c - o) / (h - l + 1e-10)).alias("candle_body_ratio"),
+        ((h - l) / (c + 1e-10)).alias("range_pct"),
+        ((c - l) / (h - l + 1e-10)).alias("close_location_value"),
+        ((h - c.shift(1)) / (c.shift(1) + 1e-10)).alias("gap_high"),
+        ((l - c.shift(1)) / (c.shift(1) + 1e-10)).alias("gap_low"),
+    ])
+
+    for w in [4, 12, 24, 48, 168]:
+        df_h5 = df_h5.with_columns([
+            c.rolling_mean(w).alias(f"sma_{w}h"),
+            c.rolling_std(w).alias(f"vol_{w}h"),
+            v.rolling_mean(w).alias(f"vol_avg_{w}h"),
+            (h - l).rolling_mean(w).alias(f"range_avg_{w}h"),
+            (c / c.rolling_mean(w) - 1).alias(f"price_vs_sma_{w}h"),
+        ])
+
+    for period in [6, 14, 24]:
+        delta = c.diff()
+        gain = delta.clip(lower_bound=0).rolling_mean(period)
+        loss = (-delta.clip(upper_bound=0)).rolling_mean(period)
+        df_h5 = df_h5.with_columns((100 - 100 / (1 + gain / (loss + 1e-10))).alias(f"rsi_{period}h"))
+
+    ema12 = c.ewm_mean(span=12)
+    ema26 = c.ewm_mean(span=26)
+    macd = ema12 - ema26
+    macd_signal = macd.ewm_mean(span=9)
+    df_h5 = df_h5.with_columns([
+        macd.alias("macd_h"),
+        macd_signal.alias("macd_signal_h"),
+        (macd - macd_signal).alias("macd_hist_h"),
+    ])
+
+    df_h5 = df_h5.with_columns([
+        (v / (v.rolling_mean(24) + 1e-10)).alias("vol_ratio_24h"),
+        (v / (v.rolling_mean(168) + 1e-10)).alias("vol_ratio_168h"),
+        v.rolling_std(24).alias("vol_volatility_24h"),
+        (v * (c - c.shift(1)).sign()).rolling_sum(24).alias("obv_24h"),
+    ])
+
+    bb_mid = c.rolling_mean(24)
+    bb_std = c.rolling_std(24)
+    df_h5 = df_h5.with_columns([
+        ((c - bb_mid) / (bb_std + 1e-10)).alias("bb_zscore_24h"),
+        (bb_std / (bb_mid + 1e-10)).alias("bb_width_24h"),
+    ])
+
+    for col in ["tx_count", "active_senders", "active_receivers", "total_eth_transferred", "total_gas_used"]:
+        df_h5 = df_h5.with_columns([
+            (pl.col(col) / (pl.col(col).shift(24) + 1e-10) - 1).alias(f"{col}_change_24h"),
+            pl.col(col).rolling_mean(24).alias(f"{col}_ma24h"),
+            pl.col(col).rolling_mean(168).alias(f"{col}_ma168h"),
+        ])
+
+    for col in ["tx_count", "active_senders", "total_eth_transferred"]:
+        df_h5 = df_h5.with_columns(
+            (pl.col(f"{col}_ma24h") / (pl.col(f"{col}_ma168h") + 1e-10) - 1).alias(f"{col}_momentum")
+        )
+
+    df_h5 = df_h5.with_columns([
+        (2 * np.pi * pl.col("timestamp").dt.hour() / 24).sin().alias("hour_sin"),
+        (2 * np.pi * pl.col("timestamp").dt.hour() / 24).cos().alias("hour_cos"),
+        (2 * np.pi * pl.col("timestamp").dt.weekday() / 7).sin().alias("dow_sin"),
+        (2 * np.pi * pl.col("timestamp").dt.weekday() / 7).cos().alias("dow_cos"),
+    ])
+
+    for lag in [1, 2, 3, 4, 6, 12]:
+        df_h5 = df_h5.with_columns([
+            (c / c.shift(1) - 1).shift(lag).alias(f"ret_lag_{lag}"),
+            pl.col("range_pct").shift(lag).alias(f"range_lag_{lag}"),
+        ])
+
+    hr_ret = c / c.shift(1) - 1
+    vol_short = hr_ret.rolling_std(window_size=24)
+    vol_long = hr_ret.rolling_std(window_size=720)
+    df_h5 = df_h5.with_columns([
+        (vol_short / (vol_long + 1e-10)).alias("vol_regime_ratio"),
+        vol_long.alias("vol_30d"),
+        (vol_short - vol_long).alias("vol_shift"),
+    ])
+
+    obv = (v * (c - c.shift(1)).sign()).cum_sum()
+    obv_slope_24 = obv - obv.shift(24)
+    price_slope_24 = c - c.shift(24)
+    df_h5 = df_h5.with_columns([
+        obv_slope_24.alias("obv_slope_24h"),
+        (obv_slope_24.sign() - price_slope_24.sign()).alias("vol_price_divergence"),
+    ])
+
+    avg_xfer = pl.col("total_eth_transferred") / (pl.col("active_senders") + 1e-10)
+    df_h5 = df_h5.with_columns([
+        avg_xfer.alias("avg_transfer_size"),
+        (avg_xfer / (avg_xfer.shift(24) + 1e-10) - 1).alias("transfer_size_change_24h"),
+        (avg_xfer.rolling_mean(24) / (avg_xfer.rolling_mean(168) + 1e-10) - 1).alias("transfer_size_momentum"),
+    ])
+
+    gpv = pl.col("total_gas_used") / (v + 1e-10)
+    df_h5 = df_h5.with_columns([
+        gpv.alias("gas_per_volume"),
+        gpv.rolling_mean(24).alias("gas_per_volume_ma24h"),
+        (gpv / (gpv.shift(24) + 1e-10) - 1).alias("gas_per_volume_change_24h"),
+    ])
+
+    ret_4h = c / c.shift(4) - 1
+    ret_48h = c / c.shift(48) - 1
+    ret_168h = c / c.shift(168) - 1
+    df_h5 = df_h5.with_columns([
+        (ret_4h - ret_48h).alias("momentum_divergence_4_48"),
+        (ret_48h - ret_168h).alias("momentum_divergence_48_168"),
+        (ret_4h.sign() - ret_168h.sign()).alias("trend_alignment"),
+        vol_short.rolling_std(window_size=48).alias("vol_of_vol_48h"),
+    ])
+
+    for period in [6, 14, 24]:
+        df_h5 = df_h5.with_columns(
+            (pl.col(f"rsi_{period}h") * pl.col("vol_ratio_24h")).alias(f"rsi{period}_x_vol")
+        )
+
+    df_h5 = df_h5.with_columns([
+        (pl.col("active_senders") / (pl.col("active_senders").shift(24) + 1e-10) - 1).alias("senders_mom_24h"),
+        (pl.col("active_senders").rolling_mean(24) / (pl.col("active_senders").rolling_mean(72) + 1e-10) - 1)
+            .alias("senders_mom_24_vs_72"),
+        pl.col("active_senders").diff().rolling_mean(24).alias("senders_accel_24h"),
+    ])
+
+    df_h5 = df_h5.with_columns([
+        vol_short.alias("vol_24h_filter"),
+        (c / c.shift(720) - 1).alias("ret_30d_filter"),
+    ])
+
+    vol_arr = df_h5["vol_24h_filter"].to_numpy()
+    ratio_arr = (df_h5["vol_24h_filter"] / (df_h5["vol_30d"] + 1e-10)).to_numpy()
+    finite_vol = vol_arr[np.isfinite(vol_arr)]
+    vol_p25 = np.nanpercentile(finite_vol, 25) if len(finite_vol) else np.nan
+    vol_p75 = np.nanpercentile(finite_vol, 75) if len(finite_vol) else np.nan
+
+    df_h5 = df_h5.with_columns([
+        pl.Series("vol_regime_low", (vol_arr < vol_p25).astype(np.float64)),
+        pl.Series("vol_regime_high", (vol_arr > vol_p75).astype(np.float64)),
+        pl.Series("vol_regime_expanding", (ratio_arr > 1.2).astype(np.float64)),
+        pl.Series("vol_regime_compressing", (ratio_arr < 0.8).astype(np.float64)),
+    ])
+
+    exclude = {
+        "timestamp", "open", "high", "low", "close", "volume",
+        "tx_count", "active_senders", "active_receivers",
+        "total_eth_transferred", "total_gas_used",
+        "vol_24h_filter", "ret_30d_filter",
+    }
+    feature_cols = [col for col in df_h5.columns if col not in exclude and not col.startswith("target_ret_")]
+    df_feat = df_h5.drop_nulls().to_pandas()
+    return df_feat, feature_cols

src/model.py

@@ -0,0 +1,81 @@
+"""Load calibrated V5 model + exact predict_return_signal from notebook"""
+import joblib
+from huggingface_hub import hf_hub_download # type: ignore
+import numpy as np
+import pandas as pd
+from src.config import MODEL_PATH, HF_REPO_ID
+from src.inference_features import build_live_v5_features
+
+def load_model():
+    if not HF_REPO_ID or HF_REPO_ID.startswith("yourusername/"):
+        model = joblib.load(MODEL_PATH)
+        print("Model loaded from local file")
+        return model
+
+    try:
+        path = hf_hub_download(repo_id=HF_REPO_ID, filename="v5_lgbm_24h_dualfilter.joblib")
+        model = joblib.load(path)
+        print("✅ Model loaded from Hugging Face Hub")
+    except Exception:
+        model = joblib.load(MODEL_PATH)
+        print("✅ Model loaded from local file")
+    return model
+
+def predict_return_signal(model, X):
+    """Exact function from latest notebook (handles calibrated classifier)"""
+    if isinstance(model, dict) and "model" in model:   # calibrated classifier
+        proba = model["model"].predict_proba(X)[:, 1]
+        calibrator = model.get("calibrator")
+        if calibrator is None:
+            return (proba - 0.5) * 2.0 * 0.006
+        # Apply calibrator
+        idx = np.searchsorted(calibrator["edges"][1:-1], proba, side="right")
+        return calibrator["values"][idx]
+    else:
+        return model.predict(X) # type: ignore
+
+
+def core_model(model):
+    return model.get("model") if isinstance(model, dict) and "model" in model else model
+
+
+def model_feature_cols(model) -> list[str] | None:
+    if isinstance(model, dict):
+        cols = model.get("feature_cols") or model.get("features")
+        if cols is not None:
+            return list(cols)
+    return None
+
+
+def build_live_matrix(df_raw: pd.DataFrame, model):
+    df_feat, feature_cols = build_live_v5_features(df_raw)
+    latest = df_feat.iloc[-1:].copy()
+    trained_feature_cols = model_feature_cols(model)
+    if trained_feature_cols is not None:
+        missing = [col for col in trained_feature_cols if col not in latest.columns]
+        if missing:
+            raise ValueError(f"Live data is missing {len(missing)} trained features, e.g. {missing[:10]}")
+        X = latest[trained_feature_cols]
+    else:
+        X = latest[feature_cols]
+    expected_features = getattr(core_model(model), "n_features_in_", None)
+    if expected_features is not None and X.shape[1] != expected_features:
+        raise ValueError(
+            f"Live feature count is {X.shape[1]}, but the model expects {expected_features}. "
+            "Re-export the notebook model as a dict containing feature_cols=feat_v5."
+        )
+    return df_feat, latest, X
+
+
+def classifier_positive_proba(model, X) -> float | None:
+    base_model = core_model(model)
+    if hasattr(base_model, "predict_proba"):
+        return float(base_model.predict_proba(X)[:, 1][0])
+    return None
+
+
+def predict_next_8h(df_raw: pd.DataFrame, model): # type: ignore
+    """Main inference entry point"""
+    _, _, X = build_live_matrix(df_raw, model)
+    pred = predict_return_signal(model, X)
+    return float(pred[0])

src/signal.py

@@ -0,0 +1,112 @@
+"""Paper-trading signal snapshot shared by Streamlit and Telegram."""
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+from src.config import BRT, BVF, COST_V5
+from src.data_fetch import fetch_latest_data
+from src.model import build_live_matrix, classifier_positive_proba, predict_return_signal
+
+
+def confidence_label(confidence: float | None) -> str:
+    if confidence is None:
+        return "n/a"
+    if confidence >= 0.50:
+        return "high"
+    if confidence >= 0.25:
+        return "medium"
+    return "low"
+
+
+def regime_label(ret_30d: float, vol_percentile: float) -> str:
+    trend = "bull" if ret_30d > BRT else "bear" if ret_30d < -BRT else "sideways"
+    vol = "high-vol" if vol_percentile >= BVF else "normal-vol"
+    return f"{trend}, {vol}"
+
+
+def build_signal_snapshot(model, limit: int = 2000, threshold: float = 0.006) -> dict:
+    df_raw = fetch_latest_data(limit=limit)
+    df_feat, latest, X = build_live_matrix(df_raw, model)
+
+    pred = float(predict_return_signal(model, X)[0])
+    proba_up = classifier_positive_proba(model, X)
+    confidence = abs(proba_up - 0.5) * 2.0 if proba_up is not None else None
+    signal_strength = abs(pred) / threshold if threshold > 0 else np.nan
+
+    row = latest.iloc[0]
+    ret_30d = float(row["ret_30d_filter"])
+    vol_24h = float(row["vol_24h_filter"])
+    vol_series = pd.to_numeric(df_feat["vol_24h_filter"], errors="coerce").dropna()
+    vol_percentile = float((vol_series <= vol_24h).mean()) if len(vol_series) else 0.0
+
+    trend_ok = abs(ret_30d) >= BRT
+    vol_ok = vol_percentile >= BVF
+    signal_ok = abs(pred) >= threshold
+    dual_filter_ok = trend_ok and vol_ok
+
+    if signal_ok and dual_filter_ok:
+        action = "LONG" if pred > 0 else "SHORT"
+    elif signal_ok:
+        action = "WATCH"
+    else:
+        action = "FLAT"
+
+    return {
+        "timestamp": df_raw.index[-1],
+        "price": float(df_raw["close"].iloc[-1]),
+        "pred": pred,
+        "proba_up": proba_up,
+        "confidence": confidence,
+        "confidence_label": confidence_label(confidence),
+        "signal_strength": signal_strength,
+        "threshold": threshold,
+        "net_edge": abs(pred) - COST_V5,
+        "ret_30d": ret_30d,
+        "vol_24h": vol_24h,
+        "vol_percentile": vol_percentile,
+        "trend_ok": trend_ok,
+        "vol_ok": vol_ok,
+        "dual_filter_ok": dual_filter_ok,
+        "signal_ok": signal_ok,
+        "action": action,
+        "direction": "up" if pred > 0 else "down" if pred < 0 else "flat",
+        "regime": regime_label(ret_30d, vol_percentile),
+        "df_raw": df_raw,
+        "df_feat": df_feat,
+    }
+
+
+def format_signal(snapshot: dict, include_header: bool = True) -> str:
+    proba = snapshot["proba_up"]
+    proba_text = "n/a" if proba is None else f"{proba:.1%} up / {1 - proba:.1%} down"
+    conf = snapshot["confidence"]
+    conf_text = "n/a" if conf is None else f"{conf:.1%} ({snapshot['confidence_label']})"
+
+    header = "<b>ETH V5 8h Paper Signal</b>\n" if include_header else ""
+    return (
+        f"{header}"
+        f"Action: <b>{snapshot['action']}</b>\n"
+        f"Expected 8h return: <b>{snapshot['pred']:+.2%}</b>\n"
+        f"Classifier probability: {proba_text}\n"
+        f"Probability confidence: {conf_text}\n"
+        f"Signal strength: {snapshot['signal_strength']:.2f}x threshold\n"
+        f"Net edge after cost: {snapshot['net_edge']:+.2%}\n"
+        f"Price: ${snapshot['price']:,.2f}\n"
+        f"Regime: {snapshot['regime']}\n"
+        f"30d return: {snapshot['ret_30d']:+.2%} "
+        f"({'pass' if snapshot['trend_ok'] else 'fail'})\n"
+        f"24h vol: {snapshot['vol_24h']:.2%}; "
+        f"vol percentile: {snapshot['vol_percentile']:.0%} "
+        f"({'pass' if snapshot['vol_ok'] else 'fail'})\n"
+        f"Signal threshold: {snapshot['threshold']:.2%}\n"
+        f"Time: {snapshot['timestamp']}"
+    )
+
+
+def plain_interpretation(snapshot: dict) -> str:
+    if snapshot["action"] in {"LONG", "SHORT"}:
+        return "Paper-trade candidate: model signal and both filters agree."
+    if snapshot["action"] == "WATCH":
+        return "Watch only: model magnitude is large enough, but the regime filters do not both pass."
+    return "Flat: expected move is below the paper-trading threshold."