feat: implement ETHUSDT adaptive threshold classifier 15m strategy (closes #215)

ideas/idea-012-ethusdt-adaptive-threshold-classifier-15m.md

@@ -41,4 +41,4 @@ ETHUSDT may show repeatable behavior when adaptive threshold classifier conditio
 
 This idea is intentionally Markdown-only. A future template can add `strategy.py`, `quant.config.json`, and a focused README once PPE results justify turning the idea into executable code.
 
-Closes #23
+Closes #215

templates/ethusdt-adaptive-threshold-classifier-15m/README.md

@@ -0,0 +1,55 @@
+# ETHUSDT Adaptive threshold classifier 15m
+
+This strategy implements an adaptive threshold classifier approach for ETHUSDT on 15-minute candles using LightGBM.
+
+## Overview
+
+- **Pair**: ETHUSDT
+- **Timeframe**: 15m
+- **Model**: LightGBM with feature engineering focused on adaptive threshold classification
+- **Goal**: Dynamically adjust classification thresholds based on recent volatility and market conditions
+
+## Features Engineered
+
+1. **Basic returns**: 1, 2, 4, 8, 16, 32 period returns
+2. **ATR-based features** (enhanced from original):
+   - ATR percentage (ATR/price)
+   - ATR expansion ratio (short-term/long-term ATR)
+   - Realized volatility at different timeframes
+   - Volatility regime indicator
+   - Volume z-score
+   - EMA crossovers (9/34 and 21/89)
+3. **Adaptive threshold features**:
+   - Dynamic threshold (2× ATR percentage)
+   - Volatility percentile ranking
+4. **Momentum features**:
+   - RSI (Relative Strength Index)
+   - Price position in recent 20-period range
+   - Volume-price correlation
+5. **Distance from EMAs** (from idea): 20, 50, and 200 period EMAs
+6. **Prior swing high and swing low distance** (from idea)
+7. **Volume features**: Z-score and ratio to moving average
+8. **Rolling volatility percentile** (from idea): Fast/slow volatility ratio, volatility percentile
+
+## Configuration
+
+See `quant.config.json` for hyperparameters:
+- `lookback`: 100 candles for prediction
+- `horizon`: 3 candles forward for labeling (45 minutes for 15m timeframe)
+- `threshold`: 0.003 (base threshold, adapted dynamically)
+- `min_confidence`: 0.50 minimum probability for signal generation
+
+## Usage
+
+This template follows the PyP Quant Mode contract:
+```python
+def train(data, config):
+    return model, metrics
+
+def predict(model, market_data, config):
+    return {"signal": "UP|DOWN|HOLD", "confidence": 0.0, "metadata": {}}
+```
+
+## Disclaimer
+
+Educational template only. Not financial advice. Past performance does not guarantee future results.

templates/ethusdt-adaptive-threshold-classifier-15m/quant.config.json

@@ -0,0 +1,30 @@
+{
+  "pair": "ETHUSDT",
+  "timeframe": "15m",
+  "model_family": "LightGBM",
+  "runtime_target": "edge",
+  "artifact_format": "weights_bundle",
+  "parameters": {
+    "lookback": 100,
+    "horizon": 3,
+    "threshold": 0.003,
+    "min_confidence": 0.5
+  },
+  "training_requirements": [
+    "numpy",
+    "pandas",
+    "scikit-learn",
+    "lightgbm",
+    "joblib"
+  ],
+  "inference_requirements": [
+    "numpy",
+    "pandas",
+    "scikit-learn",
+    "lightgbm",
+    "joblib"
+  ],
+  "symbol": "ETHUSDT",
+  "description": "ETHUSDT adaptive threshold classifier strategy using LightGBM",
+  "disclaimer": "Educational template only. Not financial advice."
+}

templates/ethusdt-adaptive-threshold-classifier-15m/strategy.py

@@ -0,0 +1,130 @@
+import numpy as np
+import pandas as pd
+from lightgbm import LGBMClassifier
+from sklearn.pipeline import Pipeline
+from sklearn.preprocessing import StandardScaler
+
+
+SYMBOL = "ETHUSDT"
+MODEL_NAME = "ethusdt-adaptive-threshold-classifier-15m"
+
+
+def _normalise(data):
+    df = data.copy()
+    df.columns = [str(c).lower() for c in df.columns]
+    if "volume" not in df.columns:
+        df["volume"] = 1.0
+    for col in ["open", "high", "low", "close", "volume"]:
+        df[col] = pd.to_numeric(df[col], errors="coerce")
+    return df.dropna().reset_index(drop=True)
+
+
+def _atr(df, n=14):
+    h, l, c = df["high"], df["low"], df["close"]
+    tr = pd.concat([(h - l), (h - c.shift()).abs(), (l - c.shift()).abs()], axis=1).max(axis=1)
+    return tr.ewm(span=n, adjust=False).mean()
+
+
+def _features(df):
+    c = df["close"]
+    v = df["volume"]
+    h = df["high"]
+    l = df["low"]
+    ret = c.pct_change()
+    f = pd.DataFrame(index=df.index)
+    
+    # Basic returns
+    for n in [1, 2, 4, 8, 16, 32]:
+        f[f"ret{n}"] = c.pct_change(n)
+    
+    # ATR-based features (from original)
+    f["atr_pct"] = _atr(df, 14) / c
+    f["atr_expansion"] = (_atr(df, 8) / (_atr(df, 50) + 1e-9)).clip(0, 5)
+    f["rv_12"] = ret.rolling(12).std()
+    f["rv_48"] = ret.rolling(48).std()
+    f["vol_regime"] = f["rv_12"] / (f["rv_48"] + 1e-9)
+    f["volume_z"] = (v - v.rolling(48).mean()) / (v.rolling(48).std() + 1e-9)
+    f["ema_9_34"] = (c.ewm(span=9, adjust=False).mean() - c.ewm(span=34, adjust=False).mean()) / c
+    f["ema_21_89"] = (c.ewm(span=21, adjust=False).mean() - c.ewm(span=89, adjust=False).mean()) / c
+    
+    # Adaptive threshold features
+    # Dynamic threshold based on recent volatility
+    f["adaptive_threshold"] = f["atr_pct"] * 2.0  # 2x ATR as threshold
+    f["volatility_percentile"] = f["atr_pct"].rolling(100).apply(
+        lambda x: pd.Series(x).rank(pct=True).iloc[-1] if len(x) > 0 else 0.5, raw=False)
+    
+    # Momentum features
+    f["rsi"] = 100 - (100 / (1 + ret.rolling(14).apply(
+        lambda x: x[x > 0].sum() / (-x[x < 0].sum() + 1e-9))))
+    
+    # Price position in recent range
+    f["price_position"] = (c - l.rolling(20).min()) / (h.rolling(20).max() - l.rolling(20).min()).replace(0, np.nan)
+    
+    # Volume-price correlation
+    f["volume_price_corr"] = ret.rolling(20).corr(v.pct_change())
+    
+    return f.replace([np.inf, -np.inf], np.nan).dropna()
+
+
+def _labels(close, index, horizon, threshold):
+    fwd = close.pct_change(horizon).shift(-horizon)
+    y = pd.Series(1, index=close.index)
+    y[fwd > threshold] = 2
+    y[fwd < -threshold] = 0
+    return y.reindex(index).fillna(1).astype(int)
+
+
+def train(data, config):
+    params = config.get("parameters", {})
+    horizon = int(params.get("horizon", 3))  # 3 candles = 45 minutes for 15m timeframe
+    threshold = float(params.get("threshold", 0.003))  # Base threshold, will be adapted
+    df = _normalise(data)
+    feat = _features(df)
+    y = _labels(df["close"], feat.index, horizon, threshold)
+    
+    model = Pipeline([
+        ("scaler", StandardScaler()),
+        ("clf", LGBMClassifier(n_estimators=300, learning_rate=0.05, max_depth=6, random_state=42, verbose=-1))
+    ])
+    model.fit(feat.values, y.values)
+    
+    metrics = {
+        "training_bars": int(len(feat)),
+        "feature_count": int(feat.shape[1]),
+        "buy_signals": int((model.predict(feat.values) == 2).sum()),
+        "sell_signals": int((model.predict(feat.values) == 0).sum()),
+        "hold_signals": int((model.predict(feat.values) == 1).sum()),
+    }
+    return {"model": model, "features": list(feat.columns), "symbol": SYMBOL}, metrics
+
+
+def predict(model, market_data, config):
+    params = config.get("parameters", {})
+    lookback = int(params.get("lookback", 100))
+    min_conf = float(params.get("min_confidence", 0.5))
+    candles = market_data.get("candles", [])
+    
+    if len(candles) < lookback:
+        return {"signal": "HOLD", "confidence": 0.0, "metadata": {"reason": "not_enough_candles", "model": MODEL_NAME}}
+    
+    df = _normalise(pd.DataFrame(candles, columns=["open", "high", "low", "close", "volume"]))
+    feat = _features(df).tail(1)
+    
+    if feat.empty:
+        return {"signal": "HOLD", "confidence": 0.0, "metadata": {"reason": "no_features", "model": MODEL_NAME}}
+    
+    prob = model["model"].predict_proba(feat.values)[0]
+    klass = int(np.argmax(prob))
+    conf = float(np.max(prob))
+    signal = {0: "DOWN", 1: "HOLD", 2: "UP"}[klass]
+    
+    if conf < min_conf:
+        signal = "HOLD"
+    
+    return {"signal": signal, "confidence": round(conf, 4), "metadata": {
+        "p_sell": round(float(prob[0]), 4), 
+        "p_hold": round(float(prob[1]), 4), 
+        "p_buy": round(float(prob[2]), 4), 
+        "model": MODEL_NAME, 
+        "symbol": SYMBOL
+    }}