QuantForge is a modular quantitative research framework focused on macro-conditioned trading systems across equities, FX, metals, and crypto. It features a live 24/7 paper-trading engine with a web dashboard and robust walk-forward validation infrastructure.
This is a research and paper-trading system — not a production trading bot.
The paper-trading engine runs continuously with the following allocation across 6 assets and 5 distinct driver clusters:
| Asset | Ticker | Label | Cluster | Alloc | Key Features |
|---|---|---|---|---|---|
| BTC | BTC-USD |
tb20 | momentum_crypto | 20% | rate_diff, 2y_yield_delta_63, btc_mom_63, btc_vs_spy_63 |
| GC=F | GC=F |
fwd60 | real_asset | 20% | real_yield_delta_63, breakeven_delta_63, dxy_mom_63, gc_mom_63 |
| EURAUD | EURAUD=X |
tb20 | eur_cross | 22% | rate_diff, dxy_mom_21, vix_ma21, euraud_mom_21 |
| NZDJPY | NZDJPY=X |
tb20 | carry_fx | 15% | vix_ma21, vix_delta_5, us_jp_10y_spread, nzdjpy_mom_21 |
| CADJPY | CADJPY=X |
fwd60 | oil_carry | 13% | ca_jp_spread_mom_5, ca_jp_spread_mom_21, cadjpy_mom_21, vix_ma21 |
| USDCAD | USDCAD=X |
tb20 | usd_macro | 10% | rate_diff, dxy_mom_21, vix_ma21, usdcad_mom_21 |
./monitor_allDashboard: http://127.0.0.1:5000
- Engine refresh: every 30 minutes
- UI refresh: every 30 seconds
- Yahoo Finance resilience: exponential backoff (5s/15s/45s) + parquet cache fallback
- Portfolio summary (Total Value, Return, Unrealized P&L, Trade Count)
- Per-asset signal cards with confidence meters, position details, and P&L
- Session-scoped execution log (auto-cleaned on restart)
- Performance metrics (Profit Factor, Win Rate, Sharpe, Mean Confidence)
- Validity & Halt condition monitors
- Regime status and advisory bar
Primary validated assets across 6 asset classes using walk-forward validation. Two label architectures are deployed: tb20 (triple-barrier, 20-bar timeout) for mean-reverting/short-term assets, and fwd60 (60-day forward return) for macro-trend assets. See ADR-015.
- Type: XGBoost multiclass classifier (BUY / NEUTRAL / SELL)
- Parameters: 300 trees, max depth 2, learning rate 0.02
- Labeling: Triple-barrier (pt_sl=2.0, vertical barrier=20 bars) for tb20 assets; 60-day forward return classification for fwd60 assets
- Sizing: Volatility-scaled positions
- Validation: Rolling walk-forward (5yr train / 1yr test / 1yr step)
| Asset | Label | Windows | Avg PF | Avg Sharpe | Pos Windows | Cumulative Return |
|---|---|---|---|---|---|---|
| CADJPY | fwd60 | 6/6 | 1.47 | 1.07 | 88% | +34.9% |
| GC=F | fwd60 | 6/6 | 1.37 | 1.02 | 75% | +96.3% |
| EURAUD | tb20 | 6/8 | 2.52 | 0.82 | 75% | — |
| NZDJPY | tb20 | 5/8 | 1.16 | 0.69 | 62% | — |
| USDCAD | tb20 | 5/8 | 1.24 | 0.61 | 62% | — |
| BTC | tb20 | 4/8 | 1.04 | 0.09 | 50% | — |
See ADR-015 for fwd60 methodology and ADR-016 for GC=F validation. See ADR-017 for inference integrity.
| Module | Description |
|---|---|
| HybridRegimeEnsemble | Global XGBoost backbone (depth=2, 100 trees) with regime-specific expert heads (TREND/RANGE/VOLATILE) and protected macro head (0.45 blend) |
| MacroExpertHead | Asset-specific XGBoost (depth=2) with protected weight 0.45 — prevents price features drowning macro signal |
| RegimeClassifier | TREND/RANGE/VOLATILE/NEUTRAL — operates as risk/participation controller |
| DriverAtlas | Asset-to-feature-cluster routing: carry_fx, yield_equity, momentum_crypto, positioning |
| ValidityStateMachine | GREEN/YELLOW/RED capital allocation with PSI-gated hysteresis |
| WalkForwardEngine | 5yr rolling train, 1yr OOS test, bootstrap p<0.05 deployment gate |
| Component | Description |
|---|---|
| AssetEngine | Per-asset XGBoost (depth=2, 300 trees, lr=0.02), 4 macro features, tb20 or fwd60 label routing |
| PaperTradingEngine | Orchestrates 6 assets, volatility-scaled sizing, halt conditions, P&L tracking |
| Dashboard (stdlib http.server) | Real-time web UI with portfolio summary, signal cards, session-scoped log, performance metrics |
- Simplicity wins: 4-feature model consistently outperforms complex ensembles in walk-forward tests
- Asset-specific driver features are mandatory: generic macro features fail on 28/30 assets tested; pair-specific features (VIX + bilateral yield spread for NZDJPY) flipped 0/7 → 5/7 positive windows
- Genuine diversification across 6 driver clusters: 6-asset portfolio spans momentum_crypto, real_asset, eur_cross, carry_fx, oil_carry, and usd_macro with max |r| < 0.40
- Feature interference is a real failure mode: macro features drowned by 25 price features until protected weight architecture separated them
- Macro features describe environment, not price response: yield_slope and real_yield_10y removed from XLF model because they stayed bearish through 2023–2024 rally; 2y_yield_delta_63 (direction, not level) was the fix
- EURUSD blocked at daily frequency: 8 years walk-forward showed 1.65% CAGR; requires COT positioning data
flowchart TD
A1[yfinance OHLCV] --> F
A2[FRED macro series] --> F
A3[Parquet cache] --> F
F[Driver atlas — asset-specific feature sets]
F --> |carry_fx| N1[NZDJPY: VIX + bilateral yield spread]
F --> |real_asset| N2[GC=F: real yield + breakeven + DXY]
F --> |momentum_crypto| N3[BTC: mom_63 + rate diff]
F --> |eur_cross| N4[EURAUD: rate diff + DXY + VIX]
F --> |oil_carry| N5[CADJPY: CA-JP spread + VIX]
F --> |usd_macro| N6[USDCAD: rate diff + DXY + VIX]
N1 & N2 & N3 & N4 & N5 & N6 --> L{tb20 vs fwd60}
L --> |tb20| TB[Triple barrier\npt_sl=2.0 · 20-bar timeout]
L --> |fwd60| FW[60-day forward return\n±2% threshold]
TB & FW --> M1[Regime classifier\nTREND/RANGE/VOLATILE/NEUTRAL]
TB & FW --> M2[Bootstrap deployment gate\np<0.20 for fwd60 · p<0.10 for tb20]
TB & FW --> M3[Walk-forward engine\n5yr train · 1yr test]
M1 & M2 & M3 --> S[Signal generator\nprob threshold 0.45]
S --> R[Risk engine\nvol-scaled sizing · halt conditions · prob_drift]
R --> P1[BTC 20%\nhalt DD −15%]
R --> P2[GC=F 20%\nhalt DD −8%]
R --> P3[EURAUD 22%\nhalt DD −8%]
R --> P4[NZDJPY 15%\nhalt DD −6%]
R --> P5[CADJPY 13%\nhalt DD −8%]
R --> P6[USDCAD 10%\nhalt DD −8%]
P1 & P2 & P3 & P4 & P5 & P6 --> Mon[Monitoring\nvalidity state machine · drift · dashboard]
QuantForge/
├── paper_trading/ # Live engine + stdlib HTTP dashboard
│ ├── serve.py # stdlib HTTP server
│ ├── engine.py # Paper trading engine
│ ├── monitor.py # Entry point (data → signal → trade loop)
│ ├── frontend/ # Dashboard UI (index.html, script.js, style.css)
│ └── models/ # 6 serialised XGBoost model pickles
├── scripts/ # Training & validation runners
│ ├── walk_forward_all.py
│ ├── train_all_assets.py
│ ├── gc_walk_forward.py
│ └── ...
├── equity/ # Walk-forward research scripts
├── archive/ # Retired model source code
├── backtests/ # Walk-forward engine, metrics, simulations
├── models/ # Research models
│ ├── regime/ # Regime classifier
│ ├── ensemble/ # Model router
│ ├── mean_reversion/ # RSI + Bollinger for RANGE
│ ├── trend/ # Trend-following models
│ ├── volatility/ # Volatility models
│ ├── macro_expert_head.py
│ └── hybrid_ensemble.py
├── features/ # Feature engineering pipeline (base, pair, regime, COT, interaction, structural, trend, volatility)
├── labels/ # Triple-barrier & meta-labeling
├── signals/ # Signal filtering, thresholding, generation
├── risk/ # Position sizing, drawdown controls, exposure limits
├── monitoring/ # Validity state machine, drift detection, dashboard backend, MLflow, weekly reports
├── data/
│ ├── loaders/ # yfinance, FRED, COT downloaders
│ ├── raw/ # Raw OHLCV parquet files
│ ├── processed/ # Feature-engineered datasets & walk-forward results
│ ├── live/ # Runtime engine state, equity history, logs, yfinance cache
│ └── weekly_pipeline.py
├── diagnostics/ # Model audits, sweeps, SHAP analysis, isolation tests
├── portfolio/ # HRP allocator, risk parity, correlation clusters
├── execution/ # Broker interface, order manager, portfolio sync
├── configs/ # YAML configs (paper trading, forex) + driver atlas
├── tests/ # Pytest test suite (7 test files)
├── docs/ # Project documentation, runbook, system overview
│ └── adr/ # Architecture Decision Records (ADR-000 through ADR-017)
├── adr/ # Additional ADRs (ADR-011 known issues)
├── notebooks/ # (placeholder — no notebooks yet)
├── .github/
│ └── workflows/ # CI pipeline (py_compile lint + pytest)
├── quantforge/ # Package root (version, logging)
├── main.py # Minimal entry point
├── monitor_all # Launch script (paper trading)
├── Makefile # Dev targets (install, test, lint, run, clean)
├── pyproject.toml # Project metadata & deps
└── requirements.txt # Pinned dependencies
Project documentation and architecture decisions live alongside the code:
| Path | Description |
|---|---|
docs/ |
Project documentation — guides, references, deep-dives |
docs/adr/ |
Architecture Decision Records — key design decisions and their rationale (ADR-000 through ADR-017) |
adr/ |
Supplementary ADRs — known issues and deferred decisions |
ADR entries follow the standard Michael Nygard template and are numbered sequentially.
git clone git@github.com:manuelhorvey/QuantForge.git
cd QuantForge
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install pytest pytest-cov # dev dependencies
export PYTHONPATH=$PYTHONPATH:.# Train models for all 30 assets
python scripts/train_all_assets.py
# Run walk-forward validation
python scripts/walk_forward_all.py
# Run tests
make test
# Start live paper trading + dashboard
./monitor_all- Live broker integration (Alpaca / Interactive Brokers) — interface stubs exist
- Realistic slippage & spread modeling
- Enhance drift detection & auto-retraining triggers
- Deploy
HybridRegimeEnsembleto paper trading (or decide to keep simple XGBoost) - AUDJPY re-evaluation post-November — model trained, deferred pending correlation analysis
- Real-time WebSocket dashboard
- Multi-timeframe signal fusion
- Meta-labeling layer
- EURUSD/GBPUSD with COT data pipeline
Assets pending validation: ETH-USD (momentum_crypto cluster), XLU/XLRE (yield_equity cluster). AUDJPY (model trained, deferred post-November — r=0.87 with NZDJPY).
Blocked pending data acquisition: EURUSD, GBPUSD (need CFTC COT weekly positioning data).
- Paper trading only (no real capital at risk)
- Weekend data staleness for equities/FX
- No live broker execution — interface stubs exist (Alpaca/IBKR) but untested
- EURUSD and GBPUSD blocked — requires COT positioning data
- Model validity depends on PSI distribution stability
- Paper trading uses simple 4-feature XGBoost per asset; research ensemble (
HybridRegimeEnsemble) not yet deployed - Yahoo Finance data can be rate-limited; engine mitigates with exponential backoff (5s/15s/45s) + parquet cache fallback
This project is for research and educational purposes only. It is not financial advice. Trading involves substantial risk of loss. Past performance does not guarantee future results.
MktOwl
Focus: Macro-driven systematic trading • Walk-forward validation • Production-grade research engineering
Contributions, issues, and suggestions are welcome.