ahad-quant/README.md

# AHAD QUANT

**ML + RL Forex trading system** — ensemble machine learning models, a reinforcement learning (PPO) decision layer, and a live MetaTrader 5 bridge, deployed with a documented demo track record.

> ⚠️ **Disclaimer:** All performance numbers below come from a **demo / paper-trading account** (JustMarkets-Demo, simulated execution). They are not a live, real-money track record. Trading carries significant risk of loss; past backtest or demo performance does not guarantee future results.

---

## Origin & Attribution

AHAD QUANT started as a fork of **[DeepAlpha](https://github.com/stefanoviana/deepalpha)** (MIT License), an open-source crypto trading bot for Bybit/Binance. Several core modules — feature engineering, exchange adapter pattern, risk manager, model architectures (LightGBM/XGBoost ensemble, TFT, TransformerGRU), regime detection, pump scanner — originate from that project and were adapted rather than written from scratch.

**What this fork adds on top of the original:**

| Addition | Description |
|---|---|
| **Reinforcement learning layer** | Full PPO agent (`rl_agent.py`, `rl_env.py`, `rl_train.py`, `rl_reward.py`, `experience_buffer.py`, `online_learner.py`) — absent from the original, which was ML-only |
| **MetaTrader 5 bridge** | Python ↔ MT5 bridge (`mt5_bridge.py`) for live Forex execution — the original was crypto-exchange-only (ccxt/Bybit/Binance) |
| **Forex migration** | Full migration from crypto pairs to 25 Forex pairs, new data sourcing (OANDA / yfinance / MT5) |
| **Web UI dashboard** | `web_ui.py` — a FastAPI-based live dashboard, in addition to the original's basic Streamlit dashboard |
| **DCA & Grid bots** | `dca_bot.py`, `grid_bot.py` — additional strategy modules |
| **Ensemble unification layer** | `unified_brain.py`, `ensemble_core.py`, `train_unified.py`, `export_unified.py` — synchronizes the ML ensemble and RL agent into one decision pipeline |
| **Auto-retraining & monitoring** | `auto_retrain.py`, `daily_local_retrain.py`, `performance_monitor.py`, `backtest.py` |
| **Model training** | All models retrained from scratch on proprietary Forex datasets via Google Colab GPU — the trained weights are original, even where the model architecture code is inherited |
| **Live deployment & track record** | Deployed and run live on a demo account for 137+ days with the metrics documented below |

This LICENSE retains the original copyright notice as required by the MIT license, with an additional notice for the modifications and additions described above.

---

## Track Record (Demo Account)

JustMarkets-Demo, USD, Hedge account — 137 days live (Feb 7 – Jun 25, 2026):

| Metric | Value |
|---|---|
| Trades | 4,542 |
| Win Rate | 79.3% |
| Profit Factor | 33.98 |
| Sharpe Ratio (annualized) | 9.10 |
| Max Drawdown | 14.0% |
| Avg Win / Avg Loss | $39.38 / -$4.57 |
| Top pairs | BTCUSD.m, XAUUSD.m, BTCEUR.m, EURUSD.m, USDCAD.m |

> Earlier "stable phase" testing (since June 4, $100 start) surfaced a configuration bug — max trade count and max margin usage were not capped — which produced a 35.9% drawdown over one volatile week. That cap is now enforced in `risk_manager.py` (`MAX_MARGIN_USAGE`, `MAX_POSITIONS`).

---

## Architecture

```
                    ┌─────────────────────────┐
 Market Data ──────▶│   Feature Engineering    │
 (OANDA/MT5/yf)     │      (features.py)        │
                    └────────────┬─────────────┘
                                 ▼
                    ┌─────────────────────────┐
                    │   ML Ensemble            │
                    │  LightGBM + XGBoost      │
                    │  + TFT + TransformerGRU  │
                    └────────────┬─────────────┘
                                 ▼
                    ┌─────────────────────────┐
                    │   RL Agent (PPO)         │◀── trained via
                    │   filters / overrides    │    rl_train.py
                    │   ML signal              │
                    └────────────┬─────────────┘
                                 ▼
                    ┌─────────────────────────┐
                    │   Risk Manager           │
                    │   sizing, SL/TP, limits  │
                    └────────────┬─────────────┘
                                 ▼
                    ┌─────────────────────────┐
                    │   MT5 Bridge             │──▶ Live execution
                    │   (mt5_bridge.py)        │    on MetaTrader 5
                    └─────────────────────────┘
                                 │
                    ┌────────────┴─────────────┐
                    │   Web UI (FastAPI)        │
                    │   live monitoring         │
                    └─────────────────────────┘
```

---

## Tech Stack

- **ML:** LightGBM, XGBoost, scikit-learn, PyTorch (TFT, TransformerGRU)
- **RL:** Stable-Baselines3 (PPO), Gymnasium
- **Execution:** MetaTrader 5 bridge, OANDA v20 REST API, ccxt (multi-broker)
- **Backend:** FastAPI, Python 3.10+
- **Training:** Google Colab (GPU) — see `AHAD_QUANT_Colab_Training.ipynb`

---

## Quick Start

```bash
git clone https://github.com/AhadQuant/ahad-quant.git
cd ahad-quant
pip install -r requirements.txt
cp .env.example .env        # fill in your broker credentials
python download_data.py     # download historical Forex data
python train.py             # train the ML ensemble
python ahad_quant.py        # start trading (paper mode by default)
```

Paper mode (no real money, no broker needed):
```bash
PAPER_MODE=true python ahad_quant.py
```

**Windows:** double-click `START_AHAD_QUANT.bat`

---

## Project Structure

```
ahad_quant.py              # Main bot entry point
config.py                  # Centralized configuration
features.py                # Feature engineering pipeline
risk_manager.py            # Position sizing, SL/TP, circuit breaker

rl_agent.py / rl_env.py    # RL (PPO) layer
rl_train.py / rl_reward.py
experience_buffer.py
online_learner.py

mt5_bridge.py              # MetaTrader 5 execution bridge
exchange_adapter.py        # Multi-broker adapter (OANDA, MT5, ccxt)
web_ui.py                  # FastAPI live dashboard
dashboard.py                # Secondary Streamlit dashboard

tft_model.py                # Temporal Fusion Transformer
transformer_gru_model.py    # TransformerGRU model
gnn_model.py                 # Graph neural network model
regime_detector.py           # HMM market regime detection
ensemble_core.py / unified_brain.py   # ML+RL unification layer

train.py / train_unified.py / download_data.py / backtest.py
auto_retrain.py / daily_local_retrain.py / performance_monitor.py

dca_bot.py / grid_bot.py     # Additional strategy modules
pump_scanner.py / liquidation_levels.py / order_flow_analyzer.py

AHAD_QUANT_Colab_Training.ipynb   # GPU training pipeline (Colab)
```

---

## License

MIT — see [LICENSE](LICENSE). This project is a fork of [DeepAlpha](https://github.com/stefanoviana/deepalpha) (MIT); see the **Origin & Attribution** section above.