eval repo README with validation results

README.md

@@ -0,0 +1,86 @@
+---
+tags: [ml-intern, crypto, finance, backtesting, evaluation]
+---
+
+# crypto-quant-eval
+
+[![Built with ML Intern](https://huggingface.co/datasets/huggingface/badges/resolve/main/built-with-ml-intern-sm.svg)](https://hf.co/chat?mode=ml-intern)
+
+Institutional-grade evaluation harness for crypto quant trading strategies.
+The companion dataset lives at [Avi-L/crypto-quant-eval-data](https://huggingface.co/datasets/Avi-L/crypto-quant-eval-data).
+
+## What this eval measures
+
+A strategy "passes" only if it survives all of:
+
+| Check | Where | Rule |
+|---|---|---|
+| No lookahead (purge + embargo) | `crypto_eval/cv.py` | label window `[t, t+h]` must never overlap a test block; embargo >= horizon (8h = one funding interval) enforced |
+| Leakage audit | `crypto_eval/cv.py` | independent per-segment audit of every CPCV fold; run fails loudly on violation |
+| Fee-aware PnL | `crypto_eval/costs.py` | 5 bps taker / 2 bps maker (Binance VIP0), funding accrued at 8h ticks |
+| Slippage | `crypto_eval/costs.py` | square-root impact `k*sqrt(notional/ADV)`, 2 bps floor |
+| Deflated Sharpe (DSR) | `crypto_eval/stats.py` | accept only if DSR > 0.95 |
+| Probability of Backtest Overfitting (PBO) | `crypto_eval/stats.py` | accept only if PBO <= 0.5 |
+| Min Track Record Length | `crypto_eval/stats.py` | how long the track record must be before SR is significant |
+
+Splitting uses CPCV (N=6 blocks, K=2 held out → 15 combinations) via
+[`purgedcv`](https://pypi.org/project/purgedcv/) 0.1.11, following
+López de Prado, *Advances in Financial Machine Learning* (Wiley 2018),
+ch. 7 (purged K-fold + embargo) and ch. 11–12 (DSR, PBO, MinBTL).
+
+## Quickstart
+
+```bash
+pip install -r requirements.txt
+python run_eval.py --data /path/to/curated --symbol BTCUSDT --freq 1h \
+    --strategy funding_carry
+```
+
+`--data` is a directory containing the dataset repo's parquet files
+(`bars_BTCUSDT_1h.parquet`, `funding_BTCUSDT.parquet`, `manifest.json`).
+Strategies are functions `(bars, funding) -> positions`; add yours to
+`crypto_eval/strategies.py`. Decision-time discipline is enforced
+structurally: a bar starting at `t` closes at `t+freq`, so signals use
+`shift_bars` (last closed bar at `t-1`); the engine and audit catch peeking.
+
+## Validation results (2026-10-23)
+
+Run on real curated data: BTCUSDT 1h, 59,654 bars (2020-01 → 2026-10),
+5,295 funding ticks, $1M initial capital, CPCV N=6/K=2, horizon=embargo=8h.
+Full JSON in `results/`.
+
+| Strategy | Net PnL | Fees | Slippage | Funding | Mean SR (ann.) | PBO | DSR/PSR mean | Verdict |
+|---|---|---|---|---|---|---|---|---|
+| `funding_carry` | **-$69,773** | $2,856 | $95,031 | +$5,940 | -0.93 | 0.214 | 0.141 | **REJECT** |
+| `ma_crossover` | **-$1,522,405** | $29,208 | $1,508,181 | -$3,469 | -4.95 | 0.014 | 0.000 | **REJECT** |
+
+Both demo strategies are deliberately naive, and the harness correctly
+rejects them: the carry trade's funding income (+$5.9k) is swamped by
+slippage ($95k), and the MA crossover's $1.5M of turnover cost destroys
+the strategy outright. A gross-return backtest would have flattered both.
+
+Note on the DSR column: per-combination values are PSR (n_trials=1 within
+a combination); DSR applies when multiple strategy configurations are
+compared — `eval_trial_set` computes it with the across-trial SR variance.
+
+## Validation performed
+
+- Synthetic-data smoke: 20k GBM bars, both strategies, numeric DSR/PBO (`synth_gen.py`)
+- Leakage test: `--embargo 0` with horizon 8 raises `ValueError` (guard in `make_cpcv`)
+- Sanity: zero-position strategy produces exactly 0.0 net PnL; any turnover produces strictly positive fees + slippage
+- No-lookahead audit passes on all 15 CPCV combinations, both real and synthetic data
+
+## Known gaps
+
+- ETH enters via funding only; ETH spot 1m (HaianCao/Binance-Public-OHLCV,
+  34.6 GB) was not ingested
+- On-chain metrics are daily (coinmetrics-community), no usable HF on-chain repo exists
+- PBO uses n_splits=8 (70 combos) rather than 16 (12,870) — the latter is
+  prohibitively slow on CPU with purge/embargo enabled
+- Cross-venue funding divergence ([Chainticks/funding-divergence](https://huggingface.co/datasets/Chainticks/funding-divergence)) is verified
+  as a source but not yet wired into the harness
+
+## References
+
+- López de Prado, *Advances in Financial Machine Learning*, Wiley 2018 (ch. 7, 11, 12)
+- [`purgedcv`](https://pypi.org/project/purgedcv/) — MIT-licensed implementation of the splitting and statistics used here