checkpoint/python_version/README.md

# ML-3m-trader

[![Python](https://img.shields.io/badge/Python-3.9%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![LightGBM](https://img.shields.io/badge/LightGBM-4.0%2B-9ACD32?logo=microsoft&logoColor=white)](https://lightgbm.readthedocs.io/)
[![MetaTrader5](https://img.shields.io/badge/MetaTrader5-Data%20Feed-0078D4)](https://www.metatrader5.com/)

Machine learning trading system for **XAUUSDc** (Gold) on the **3-minute timeframe**. Uses a LightGBM multi-class classifier to predict trade signals (Buy, Sell, Hold, Do Nothing) with a vectorized backtesting engine that enforces 1:1 risk-reward, realistic slippage, and spread-based trade filtering.

---

## Overview

ML-3m-trader is an end-to-end pipeline that connects to MetaTrader 5 to fetch one year of historical 3-minute OHLCV data, engineers a comprehensive set of technical features, labels each bar by simulating potential trade outcomes, trains a gradient-boosted classifier, and evaluates performance through a walk-forward backtest with full risk management.

---

## Features

- **Data Acquisition**: Direct connection to MetaTrader 5 for live historical data
- **Technical Indicators**: SMA, Double Moving Average (crossover), VROC, Synthetic VIX (realized volatility proxy), Momentum Strength Index, ADX, cyclical time encoding
- **Labeling Engine**: Forward-looking trade simulation with ATR-based stop-loss, 1:1 risk-reward resolution, and spread filtering
- **LightGBM Classifier**: Multi-class (4-class) gradient boosting with balanced class weights, chronological train/test split, and early stopping
- **Backtesting Engine**: Walk-forward execution with position sizing by balance, random slippage (0-2 units), spread filter enforcement, and full trade logging
- **Performance Metrics**: Win rate, average win/loss percentage, Sharpe ratio, Sortino ratio, Calmar ratio, max drawdown, profit factor, expectancy, intraday PnL statistics

---

## Architecture

```
main.py            CLI entry point with subcommands
  |
  +-- data_fetcher.py    MetaTrader 5 data download and CSV persistence
  +-- features.py        Vectorized technical indicator computation
  +-- labeler.py         Supervised label generation via trade simulation
  +-- model.py           LightGBM training, prediction, and persistence
  +-- backtester.py      Walk-forward backtesting with risk management
  +-- metrics.py         Performance evaluation and report generation
  +-- config.py          Central configuration constants
```

---

## Quick Start

**1. Set up the environment**

```
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
```

**2. Fetch data (MT5 must be open and logged in)**

```
python main.py fetch
```

**3. Train the model**

```
python main.py train
```

**4. Run the backtest**

```
python main.py backtest
```

**5. Or run the full pipeline in one command**

```
python main.py run
```

---

## Commands

| Command | Description |
|---------|-------------|
| `python main.py fetch` | Download 1 year of 3-minute bars from MetaTrader 5 |
| `python main.py train` | Compute features, generate labels, train LightGBM model |
| `python main.py backtest` | Walk-forward backtest on held-out test set with metrics |
| `python main.py evaluate` | Re-display the saved performance report |
| `python main.py predict` | Show latest class probabilities |
| `python main.py run` | Full pipeline: fetch, train, backtest |

---

## Configuration

All parameters are centralized in `config.py`. See [GUIDE.md](GUIDE.md) for the complete reference table.

Key defaults:
- **Symbol**: XAUUSDc
- **Timeframe**: 3 minutes
- **Risk per trade**: 2% of balance
- **Risk-reward ratio**: 1:1
- **Slippage**: Random 0-2 units
- **Spread filter**: Skip trades where stop-loss distance is less than spread multiplied by 10
- **Train/test split**: 80/20 chronological

---

## Output

| Path | Content |
|------|---------|
| `data/raw_xauusdc_m3.csv` | Raw OHLCV data |
| `data/featured_data.csv` | Feature-engineered dataset with labels |
| `models/lgbm_model.pkl` | Trained LightGBM model |
| `results/report.txt` | Backtest performance report |
| `results/trades.csv` | Individual trade log |

---

## Requirements

- Python 3.9+
- MetaTrader 5 (Windows only, installed and logged in)
- See [requirements.txt](requirements.txt) for pip dependencies

---

## License

[MIT License](LICENSE) -- Rembrant Oyangoren Albeos, 2026