Upload 11 files

.gitignore

@@ -0,0 +1,32 @@
+# __pycache__/
+*.pyc
+*.pyo
+__pycache__/
+
+# Data and model artifacts
+data/
+models/
+results/
+
+# Virtual environment
+.venv/
+venv/
+env/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+Thumbs.db
+.DS_Store
+desktop.ini
+
+# Logs
+*.log
+*_savelog.txt
+
+# Jupyter
+.ipynb_checkpoints/

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rembrant Oyangoren Albeos
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ML-3m-trader_savelog.txt

@@ -0,0 +1,70 @@
+REPOSITORY TECH-STACK AUDIT: ML-3m-trader
+Path: c:\Users\User\Desktop\debugrem\ML-3m-trader
+
+FILE TYPE                         COUNT      LINES     SYNTAX       SIZE (KB)
+------------------------------------------------------------------------------
+(no extension)                      878       6854        775           239.2
+PNG Image (.png)                      2        817        141           103.0
+Plain Text (.txt)                    50       8577        129           467.0
+Markdown (.md)                        7       5610         37           369.2
+Python (.py)                         17       2788        915            90.5
+Lock File (.lock)                     4       5903       2780           145.7
+TOML (.toml)                          2         40         35             0.8
+CSV (.csv)                            5      31000          0         7,164.4
+Binary File (.bin)                    7      92337      19040         8,852.6
+Rust (.rs)                           22       3018        676           101.5
+JSON (.json)                        357        371         20           238.5
+TAG (.tag)                            1          4          0             0.2
+TIMESTAMP (.timestamp)              356        356          0            16.7
+Windows Executable (.exe)            92     182892      10388        40,423.0
+D (.d)                              311       5923         19         1,550.1
+PDB (.pdb)                          106     755976      74785       184,504.0
+DLL Library (.dll)                   16     213628       4299        28,980.5
+EXP (.exp)                           14         33          1            17.5
+Library (.lib)                       14        180          1            33.0
+RMETA (.rmeta)                      250    1241287      38355       249,115.4
+RLIB (.rlib)                        158     770933      21359       256,066.0
+CMake (.cmake)                       57       8261        111           269.8
+IN (.in)                             13        375        169            11.2
+C++ Header (.hpp)                   350      54615       9065         1,746.7
+APACHE (.apache)                      1        203          1            11.1
+BSD (.bsd)                            1         27          0             1.5
+GPL (.gpl)                            1        675          1            34.3
+LGPL (.lgpl)                          1        503          6            25.9
+MINPACK (.minpack)                    1         52          0             2.1
+MPL2 (.mpl2)                          1        374          0            16.3
+README (.readme)                      1         19          0             0.8
+C++ (.cpp)                          254      59704      11785         2,152.7
+CXXLIST (.cxxlist)                    1         29          8             1.4
+C Header (.h)                       545     236942      54202         9,192.8
+Shell Script (.sh)                   12        756        191            18.6
+C++ Header (.hh)                     58       7563        972           199.7
+C++ (.cxx)                            3        514         95            13.5
+MAIN (.main)                          1         13          9             0.1
+HTML (.html)                          5        153         20            19.5
+JavaScript (.js)                      2          3       8965           383.8
+Document Type Definition (.dtd)        1         31          0             1.8
+C++ (.cc)                             7       1337        149            44.9
+CU (.cu)                             15       4980        742           179.3
+C (.c)                               20       6619       2257           177.4
+Fortran (.f)                         51      37932       7492         1,295.2
+DAT (.dat)                            8        232          0             9.6
+DOX (.dox)                            2         42          3             1.2
+YAML (.yml)                           3        192         11             3.8
+BSL (.bsl)                            1         26          0             1.3
+reStructuredText (.rst)               4       4188        130           159.8
+MK (.mk)                              1         16          1             0.3
+XML (.xml)                            1          2          1             0.0
+Gradle (.gradle)                      1        108          5             3.1
+SUBLIME-SYNTAX (.sublime-syntax)        1       2062         15            70.6
+Config (.conf)                        1          3          1             0.0
+HU (.hu)                              1        162         37             5.3
+Common Lisp (.cl)                     3       2302        553           107.0
+I (.i)                                4        604         50            22.2
+Visual Studio Solution (.sln)         1         34         15             1.6
+VCXPROJ (.vcxproj)                    1        344        153            18.2
+FILTERS (.filters)                    1        330        111            12.4
+MQL5 Source (.mq5)                    1        451        119            18.1
+MQL Header (.mqh)                     1        145         22             3.9
+------------------------------------------------------------------------------
+TOTAL                              4107    3761450     271222       794,717.6

README.md

@@ -0,0 +1,158 @@
+---
+license: mit
+library_name: ml-trader
+tags:
+- trading
+- machine-learning
+- xauusd
+- gold
+- mt5
+- metatrader5
+- python
+- rust
+---
+
+# ML-3m-trader: XAUUSDc 3-Minute Timeframe ML Trading System
+
+An end-to-end proprietary machine learning pipeline for trading XAUUSDc (Gold) on the 3-minute timeframe. This system utilizes a high-performance architecture bridging Python for data processing and model orchestration with Rust for high-frequency execution components.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Python Count](https://img.shields.io/badge/Python-9_files-blue.svg)](https://www.python.org/)
+[![Rust Count](https://img.shields.io/badge/Rust-10_files-orange.svg)](https://www.rust-lang.org/)
+[![Total Size](https://img.shields.io/badge/Repo_Size-9462_KB-green.svg)](#techstack)
+[![Author](https://img.shields.io/badge/Author-Rembrant_Oyangoren_Albeos-blueviolet.svg)](https://huggingface.co/algorembrant)
+
+## Project Overview
+
+The ML-3m-trader repository provides a robust framework for automated trading, featuring a hybrid implementation designed for speed and reliability. The core logic involves sophisticated feature engineering and a classification-based approach to market decision-making. Read paper at [SSRN](https://ssrn.com/abstract=6143486) for brigde system framework.
+
+> [!NOTE]
+> **Confidentiality Notice**: The specific machine learning algorithms and proprietary trading strategies utilized in this system are currently private. The documentation focuses on infrastructure and architectural workflows.
+
+## Key Features
+
+- **Multi-Language Architecture**: Seamless integration between Python processing and Rust execution.
+- **Data Acquisition**: Automated 3-minute OHLCV data fetching.
+- **Proprietary Labeling**: Advanced market state labeling engine with built-in risk-reward and spread filtering.
+- **Vectorized Backtesting**: High-speed, realistic execution modeling accounting for slippage and spread.
+- **Comprehensive Metrics**: Detailed performance analysis including Sharpe, Sortino, and Profit Factor.
+
+## Output Preview
+
+The following visualizations illustrate the system's internal processing and performance evaluation.
+
+### Feature Processing Workflow
+![Feature Processing Workflow](feature_process.png)
+The diagram above details the data transformation pipeline from raw market indicators to model-ready features.
+
+### Performance Metrics
+![Performance Metrics](metrics.png)
+The image above showcases the standardized backtesting report generated after a full simulation run.
+
+## System Architecture
+
+```mermaid
+graph TD
+    A[MetaTrader 5] -->|OHLCV Data| B(Data Fetcher)
+    B --> C(Feature Engineering)
+    C --> D(Labeling Engine)
+    D --> E(ML Pipeline)
+    E --> F{Backtesting}
+    F -->|Performance| G(Metrics Report)
+    F -->|Execution| H[Live Trading Interface]
+    
+    subgraph "Hybrid Processing"
+    C
+    D
+    E
+    end
+```
+
+## Project Structure
+Detailed overview of all project components:
+
+```text
+ML-3m-trader/
+├── python_version/          
+│   ├── main.py
+│   ├── config.py
+│   ├── data_fetcher.py
+│   ├── diag_mt5.py
+│   ├── features.py
+│   ├── labeler.py
+│   ├── model.py
+│   ├── backtester.py
+│   ├── metrics.py
+│   └── README.md
+├── rust_ml_trader/         
+│   ├── src/
+│   │   ├── main.rs
+│   │   ├── backtester.rs
+│   │   ├── config.rs
+│   │   ├── data_fetcher.rs
+│   │   ├── features.rs
+│   │   ├── labeler.rs
+│   │   ├── metrics.rs
+│   │   ├── model.rs
+│   │   └── types.rs
+│   ├── .gitignore
+│   ├── Cargo.toml
+│   ├── GUIDE.md
+│   ├── LICENSE
+│   └── README.md
+├── SUM3API (local)/        
+│   ├── MQL5/
+│   │   ├── Experts/
+│   │   │   └── ZmqPublisher.mq5
+│   │   ├── Include/
+│   │   └── Libraries/
+│   └── Rustmt5-chart/
+├── feature_process.png
+├── LICENSE
+├── metrics.png
+├── requirements.txt
+├── STACKS.md               
+└── sractch.md
+```
+
+## Usage
+
+For detailed technical documentation, please refer to [STACKS.md](STACKS.md).
+
+### Quick Start (Python)
+
+1. Install dependencies:
+   ```bash
+   pip install -r requirements.txt
+   ```
+2. Run the full pipeline:
+   ```bash
+   python python_version/main.py run
+   ```
+
+### Quick Start (Rust)
+
+1. Build the project:
+   ```bash
+   cd rust_ml_trader
+   cargo build --release
+   ```
+2. Execute backtest:
+   ```bash
+   cargo run --release
+   ```
+
+## Citation
+
+If you use this repository in your research or project, please cite it as follows:
+
+```bibtex
+@misc{albeos2026ml3mtrader,
+  author = {Rembrant Oyangoren Albeos},
+  title = {ML-3m-trader: XAUUSDc 3-Minute Timeframe ML Trading System},
+  year = {2026},
+  publisher = {Hugging Face},
+  journal = {Hugging Face Repository},
+  howpublished = {\url{https://huggingface.co/algorembrant/ML-3m-trader}}
+}
+```

STACKS.md

@@ -0,0 +1,132 @@
+# STACKS.md
+
+## Description
+ML-3m-trader is a high-performance, multi-language trading framework designed for the XAUUSDc 3rd minute timeframe. It bridges the data processing and machine learning capabilities of Python with the safety and speed of Rust for execution components. The system integrates directly with MetaTrader 5 for real-time market data and historical auditing.
+
+## System Overview
+```mermaid
+graph TD
+    A[MetaTrader 5] -->|OHLCV Data| B(Data Fetcher)
+    B --> C(Feature Engineering)
+    C --> D(Labeling Engine)
+    D --> E(ML Pipeline)
+    E --> F{Backtesting}
+    F -->|Performance| G(Metrics Report)
+    F -->|Execution| H[Live Trading Interface]
+    
+    subgraph "Hybrid Processing"
+    C
+    D
+    E
+    end
+```
+
+## Project Structure
+```text
+ML-3m-trader/
+├── python_version/
+│   ├── backtester.py
+│   ├── config.py
+│   ├── data_fetcher.py
+│   ├── diag_mt5.py
+│   ├── features.py
+│   ├── GUIDE.md
+│   ├── labeler.py
+│   ├── main.py
+│   ├── metrics.py
+│   ├── model.py
+│   └── README.md
+├── rust_ml_trader/
+│   ├── data/
+│   │   └── raw_xauusdc_m3.csv
+│   ├── models/
+│   │   └── rf_model.bin
+│   ├── results/
+│   │   ├── report.txt
+│   │   └── trades.csv
+│   ├── src/
+│   │   ├── backtester.rs
+│   │   ├── config.rs
+│   │   ├── data_fetcher.rs
+│   │   ├── features.rs
+│   │   ├── labeler.rs
+│   │   ├── main.rs
+│   │   ├── metrics.rs
+│   │   ├── model.rs
+│   │   └── types.rs
+│   ├── .gitignore
+│   ├── Cargo.lock
+│   ├── Cargo.toml
+│   ├── GUIDE.md
+│   ├── LICENSE
+│   └── README.md
+├── SUM3API (local)/
+│   ├── MQL5/
+│   │   ├── Experts/
+│   │   │   └── ZmqPublisher.mq5
+│   │   ├── Include/
+│   │   │   └── Zmq/
+│   │   │       └── Zmq.mqh
+│   │   └── Libraries/
+│   │       ├── libsodium.dll
+│   │       └── libzmq.dll
+│   ├── Rustmt5-chart/
+│   │   ├── src/
+│   │   │   └── main.rs
+│   │   ├── Cargo.lock
+│   │   └── Cargo.toml
+│   └── .gitignore
+├── .gitignore
+├── feature_process.png
+├── LICENSE
+├── metrics.png
+├── README.md
+├── requirements.txt
+└── sractch.md
+```
+
+## Techstack
+Audit of **ML-3m-trader** project files:
+
+| File Type | Count | Lines | Syntax Hits | Size (KB) |
+| :--- | :--- | :--- | :--- | :--- |
+| Rust (.rs) | 10 | 2283 | 570 | 76.1 |
+| Python (.py) | 9 | 1459 | 438 | 46.9 |
+| Markdown (.md) | 7 | 5610 | 37 | 369.2 |
+| (no extension) | 5 | 95 | 0 | 2.5 |
+| CSV (.csv) | 5 | 31000 | 0 | 7,164.4 |
+| Plain Text (.txt) | 3 | 4872 | 0 | 341.7 |
+| DLL Library (.dll) | 2 | 3351 | 267 | 736.0 |
+| Lock File (.lock) | 2 | 5901 | 2780 | 145.7 |
+| PNG Image (.png) | 2 | 817 | 141 | 103.0 |
+| TOML (.toml) | 2 | 40 | 35 | 0.8 |
+| Binary File (.bin) | 1 | 1844 | 132 | 453.8 |
+| MQL Header (.mqh) | 1 | 145 | 22 | 3.9 |
+| MQL5 Source (.mq5) | 1 | 451 | 119 | 18.1 |
+| **Total** | **50** | **57868** | **4541** | **9,462.0** |
+
+## Dependencies
+
+### Python Dependencies
+- **MetaTrader5**: Terminal communication and data acquisition.
+- **lightgbm**: Gradient boosting framework for machine learning.
+- **pandas**: Data manipulation and analysis.
+- **numpy**: Scientific computing and vectorized operations.
+- **scikit-learn**: Machine learning utilities and preprocessing.
+- **joblib**: Model persistence and parallel processing.
+
+### Rust Dependencies
+- **zeromq**: Asynchronous messaging for MQL5 integration.
+- **tokio**: Asynchronous runtime for high-performance networking.
+- **chrono**: Date and time handling.
+- **serde / serde_json**: Serialization and deserialization.
+- **csv**: High-performance CSV parsing and writing.
+- **clap**: Command-line argument parsing.
+- **bincode**: Binary serialization for model weights.
+- **ndarray**: N-dimensional arrays for vectorized math.
+- **rand**: Random number generation for execution modeling.
+
+## Applications
+- High-frequency algorithmic trading of Gold (XAUUSDc).
+- Quantitative backtesting and performance auditing.
+- Machine learning model development and deployment in financial markets.

TECHSTACK.md

@@ -0,0 +1,70 @@
+## Techstack
+
+Audit of **ML-3m-trader** project files (excluding environment and cache):
+
+| File Type | Count | Lines | Syntax Hits | Size (KB) |
+| :--- | :--- | :--- | :--- | :--- |
+| (no extension) | 878 | 6854 | 775 | 239.2 |
+| C Header (.h) | 545 | 236942 | 54202 | 9,192.8 |
+| JSON (.json) | 357 | 371 | 20 | 238.5 |
+| TIMESTAMP (.timestamp) | 356 | 356 | 0 | 16.7 |
+| C++ Header (.hpp) | 350 | 54615 | 9065 | 1,746.7 |
+| D (.d) | 311 | 5923 | 19 | 1,550.1 |
+| C++ (.cpp) | 254 | 59704 | 11785 | 2,152.7 |
+| RMETA (.rmeta) | 250 | 1241287 | 38355 | 249,115.4 |
+| RLIB (.rlib) | 158 | 770933 | 21359 | 256,066.0 |
+| PDB (.pdb) | 106 | 755976 | 74785 | 184,504.0 |
+| Windows Executable (.exe) | 92 | 182892 | 10388 | 40,423.0 |
+| C++ Header (.hh) | 58 | 7563 | 972 | 199.7 |
+| CMake (.cmake) | 57 | 8261 | 111 | 269.8 |
+| Fortran (.f) | 51 | 37932 | 7492 | 1,295.2 |
+| Plain Text (.txt) | 50 | 8577 | 129 | 467.0 |
+| Rust (.rs) | 22 | 3018 | 676 | 101.5 |
+| C (.c) | 20 | 6619 | 2257 | 177.4 |
+| Python (.py) | 17 | 2788 | 915 | 90.5 |
+| DLL Library (.dll) | 16 | 213628 | 4299 | 28,980.5 |
+| CU (.cu) | 15 | 4980 | 742 | 179.3 |
+| EXP (.exp) | 14 | 33 | 1 | 17.5 |
+| Library (.lib) | 14 | 180 | 1 | 33.0 |
+| IN (.in) | 13 | 375 | 169 | 11.2 |
+| Shell Script (.sh) | 12 | 756 | 191 | 18.6 |
+| DAT (.dat) | 8 | 232 | 0 | 9.6 |
+| Binary File (.bin) | 7 | 92337 | 19040 | 8,852.6 |
+| C++ (.cc) | 7 | 1337 | 149 | 44.9 |
+| Markdown (.md) | 7 | 5610 | 37 | 369.2 |
+| CSV (.csv) | 5 | 31000 | 0 | 7,164.4 |
+| HTML (.html) | 5 | 153 | 20 | 19.5 |
+| I (.i) | 4 | 604 | 50 | 22.2 |
+| Lock File (.lock) | 4 | 5903 | 2780 | 145.7 |
+| reStructuredText (.rst) | 4 | 4188 | 130 | 159.8 |
+| C++ (.cxx) | 3 | 514 | 95 | 13.5 |
+| Common Lisp (.cl) | 3 | 2302 | 553 | 107.0 |
+| YAML (.yml) | 3 | 192 | 11 | 3.8 |
+| DOX (.dox) | 2 | 42 | 3 | 1.2 |
+| JavaScript (.js) | 2 | 3 | 8965 | 383.8 |
+| PNG Image (.png) | 2 | 817 | 141 | 103.0 |
+| TOML (.toml) | 2 | 40 | 35 | 0.8 |
+| APACHE (.apache) | 1 | 203 | 1 | 11.1 |
+| BSD (.bsd) | 1 | 27 | 0 | 1.5 |
+| BSL (.bsl) | 1 | 26 | 0 | 1.3 |
+| Config (.conf) | 1 | 3 | 1 | 0.0 |
+| CXXLIST (.cxxlist) | 1 | 29 | 8 | 1.4 |
+| Document Type Definition (.dtd) | 1 | 31 | 0 | 1.8 |
+| FILTERS (.filters) | 1 | 330 | 111 | 12.4 |
+| GPL (.gpl) | 1 | 675 | 1 | 34.3 |
+| Gradle (.gradle) | 1 | 108 | 5 | 3.1 |
+| HU (.hu) | 1 | 162 | 37 | 5.3 |
+| LGPL (.lgpl) | 1 | 503 | 6 | 25.9 |
+| MAIN (.main) | 1 | 13 | 9 | 0.1 |
+| MINPACK (.minpack) | 1 | 52 | 0 | 2.1 |
+| MK (.mk) | 1 | 16 | 1 | 0.3 |
+| MPL2 (.mpl2) | 1 | 374 | 0 | 16.3 |
+| MQL Header (.mqh) | 1 | 145 | 22 | 3.9 |
+| MQL5 Source (.mq5) | 1 | 451 | 119 | 18.1 |
+| README (.readme) | 1 | 19 | 0 | 0.8 |
+| SUBLIME-SYNTAX (.sublime-syntax) | 1 | 2062 | 15 | 70.6 |
+| TAG (.tag) | 1 | 4 | 0 | 0.2 |
+| VCXPROJ (.vcxproj) | 1 | 344 | 153 | 18.2 |
+| Visual Studio Solution (.sln) | 1 | 34 | 15 | 1.6 |
+| XML (.xml) | 1 | 2 | 1 | 0.0 |
+| **Total** | **4107** | **3761450** | **271222** | **794,717.6** |

requirements.txt

@@ -0,0 +1,6 @@
+MetaTrader5>=5.0.45
+lightgbm>=4.0.0
+pandas>=2.0.0
+numpy>=1.24.0
+scikit-learn>=1.3.0
+joblib>=1.3.0

sractch.md

@@ -0,0 +1,230 @@
+# ML-3m-trader: XAUUSDc 3-Minute Timeframe ML Trading System
+
+End-to-end machine learning pipeline for trading XAUUSDc (Gold) on the 3-minute timeframe. Uses MetaTrader 5 for data acquisition, LightGBM for classification, and a vectorized backtesting engine with realistic execution modeling.
+
+## User Review Required
+
+> [!IMPORTANT]
+> **ML Framework Choice: LightGBM** — LightGBM is the best-suited framework for this task because:
+> - Tabular classification (Buy/Sell/Hold/DoNothing) is LightGBM's strongest domain
+> - Extremely fast training, even on CPU (i5-7200U will handle it fine)
+> - Low memory footprint (well within 12 GB RAM)
+> - No GPU required (your MX110 is not needed)
+> - Outperforms deep learning on structured/tabular data in virtually all benchmarks
+>
+> **This will run entirely on your local machine. No Google Colab needed.**
+
+> [!WARNING]
+> **MetaTrader 5 Python API** only works on Windows (which you have). MT5 must be open and logged in when running the data fetch script. The `MetaTrader5` pip package handles communication.
+
+> [!NOTE]
+> **VIX Feature**: Since the CBOE VIX index is not directly available from MT5, the system will compute a **synthetic VIX proxy** using a rolling standard deviation of returns (realized volatility), which is the standard approach in non-US-equity trading systems. If you want the actual VIX, we would need a separate data source.
+
+---
+
+## Proposed Changes
+
+### Project Structure
+
+```
+ML-3m-trader/
+├── config.py             # All configuration constants
+├── data_fetcher.py       # MT5 data acquisition
+├── features.py           # Technical indicator computation
+├── labeler.py            # Trade label generation (Buy/Sell/Hold/DoNothing)
+├── model.py              # LightGBM training, prediction, persistence
+├── backtester.py         # Vectorized backtesting engine
+├── metrics.py            # Performance evaluation
+├── main.py               # CLI entry point
+├── requirements.txt
+├── LICENSE
+├── README.md
+├── GUIDE.md              # Step-by-step usage guide with tables
+└── .gitignore
+```
+
+---
+
+### Configuration
+
+#### [NEW] [config.py](file:///c:/Users/User/Desktop/debugrem/ML-3m-trader/config.py)
+
+Central configuration file containing all tunable parameters:
+- `SYMBOL = "XAUUSDc"`, `TIMEFRAME = mt5.TIMEFRAME_M3`
+- Feature list, lookback periods for SMA (14, 50), VROC (14), ADX (14), Momentum SI (10)
+- Risk/reward ratio = 1.0, default bet percentage logic
+- Slippage range (0–2 units), spread filter (`stoploss_size >= spread * 10`)
+- Train/test split ratio, model hyperparameters
+- Starting equity/balance
+
+---
+
+### Data Acquisition
+
+#### [NEW] [data_fetcher.py](file:///c:/Users/User/Desktop/debugrem/ML-3m-trader/data_fetcher.py)
+
+- Connects to MT5 terminal via `MetaTrader5` Python package
+- Fetches 1-year of 3-minute OHLCV bars for XAUUSDc
+- Returns a `pandas.DataFrame` with columns: `time, open, high, low, close, volume, spread`
+- Saves raw data to `data/raw_xauusdc_3m.csv` for reproducibility
+- Handles MT5 connection errors gracefully
+
+---
+
+### Feature Engineering
+
+#### [NEW] [features.py](file:///c:/Users/User/Desktop/debugrem/ML-3m-trader/features.py)
+
+Computes all required technical indicators using pure NumPy/Pandas (no TA-Lib dependency):
+
+| Feature | Method |
+|---------|--------|
+| SMA | Simple Moving Average (14-period) |
+| Double Moving Average | SMA(14) and SMA(50), plus crossover signal |
+| VROC | Volume Rate of Change (14-period) |
+| Synthetic VIX | Rolling std of log-returns (20-period) as volatility proxy |
+| Momentum Strength Index | Custom momentum oscillator (10-period, 0–100 scale) |
+| ADX | Average Directional Index (14-period) via Wilder's smoothing |
+| Time features | Hour-of-day, minute-of-hour, day-of-week (cyclical encoded) |
+
+All computations are vectorized with NumPy for maximum speed. NaN rows from lookback periods are dropped.
+
+---
+
+### Labeling Engine
+
+#### [NEW] [labeler.py](file:///c:/Users/User/Desktop/debugrem/ML-3m-trader/labeler.py)
+
+Generates ground-truth labels for supervised learning:
+
+1. For each bar, compute a potential **Buy** and **Sell** trade:
+   - **Buy**: entry at `close`, SL below recent swing low (ATR-based), TP = entry + (entry - SL) (1:1 RR)
+   - **Sell**: entry at `close`, SL above recent swing high (ATR-based), TP = entry - (SL - entry) (1:1 RR)
+2. Walk forward through subsequent bars to determine outcome (TP hit, SL hit, or neither within N bars)
+3. Apply **spread filter**: if `SL_distance < spread * 10`, label = `DO_NOTHING`
+4. Final labels: `BUY_WIN`, `BUY_LOSS`, `SELL_WIN`, `SELL_LOSS`, `HOLD`, `DO_NOTHING` → simplified to 4-class: `BUY (1)`, `SELL (2)`, `HOLD (3)`, `DO_NOTHING (0)`
+5. Only winning setups are labeled as BUY/SELL; losing setups become HOLD
+
+---
+
+### ML Model
+
+#### [NEW] [model.py](file:///c:/Users/User/Desktop/debugrem/ML-3m-trader/model.py)
+
+- **LightGBM** multi-class classifier (4 classes)
+- Hyperparameters tuned for tabular financial data:
+  - `num_leaves=63`, `max_depth=8`, `learning_rate=0.05`, `n_estimators=500`
+  - `subsample=0.8`, `colsample_bytree=0.8`, `min_child_samples=20`
+  - `class_weight='balanced'` to handle label imbalance
+- Train/validation split: 80/20 chronological (no shuffle — time series)
+- Feature importance output
+- Model persistence via `joblib` (save/load `.pkl`)
+- Early stopping on validation set
+
+---
+
+### Backtesting Engine
+
+#### [NEW] [backtester.py](file:///c:/Users/User/Desktop/debugrem/ML-3m-trader/backtester.py)
+
+Vectorized backtesting with realistic execution:
+
+- Takes model predictions and raw price data
+- **Position sizing**: bet % of current balance, accounting for full SL distance
+  - `lot_value = balance * bet_pct / sl_distance`
+- **Random slippage**: uniform 0–2 XAUUSDc units applied to entry price
+- **Spread filter**: skip trade if `sl_distance < spread * 10`
+- **1:1 Risk-Reward**: TP distance = SL distance
+- Walk forward bar-by-bar on test set, track equity curve
+- No trade limit — takes every valid signal
+- Records all trades with entry/exit prices, PnL, timestamps
+
+---
+
+### Metrics & Evaluation
+
+#### [NEW] [metrics.py](file:///c:/Users/User/Desktop/debugrem/ML-3m-trader/metrics.py)
+
+| Metric | Description |
+|--------|-------------|
+| Win Rate | % of trades closed at TP |
+| Average Win % | Mean profit per winning trade as % of balance |
+| Average Loss % | Mean loss per losing trade as % of balance |
+| Sharpe Ratio | Annualized risk-adjusted return |
+| Sortino Ratio | Downside-risk-adjusted return |
+| Max Drawdown | Largest peak-to-trough equity decline |
+| Profit Factor | Gross profit / Gross loss |
+| Start Equity | Initial balance |
+| End Equity | Final balance after all trades |
+| Total Trades | Number of executed trades |
+| Avg Trade Duration | Mean holding time in bars/minutes |
+| Daily PnL Stats | Intraday mean, std, min, max PnL |
+| Calmar Ratio | Annualized return / Max Drawdown |
+| Expectancy | Average PnL per trade |
+
+Outputs a formatted console report and saves to `results/report.txt`.
+
+---
+
+### CLI Entry Point
+
+#### [NEW] [main.py](file:///c:/Users/User/Desktop/debugrem/ML-3m-trader/main.py)
+
+Unified CLI with subcommands:
+
+```
+python main.py fetch       # Fetch 1-year data from MT5
+python main.py train       # Engineer features, label, train model
+python main.py backtest    # Run backtest on test set
+python main.py evaluate    # Print metrics report
+python main.py run         # Full pipeline: fetch → train → backtest → evaluate
+```
+
+Uses `argparse` with clear help text.
+
+---
+
+### Project Files
+
+#### [NEW] [requirements.txt](file:///c:/Users/User/Desktop/debugrem/ML-3m-trader/requirements.txt)
+
+```
+MetaTrader5>=5.0.45
+lightgbm>=4.0.0
+pandas>=2.0.0
+numpy>=1.24.0
+scikit-learn>=1.3.0
+joblib>=1.3.0
+```
+
+#### [NEW] [LICENSE](file:///c:/Users/User/Desktop/debugrem/ML-3m-trader/LICENSE)
+
+MIT License, author: Rembrant Oyangoren Albeos, year: 2026.
+
+#### [NEW] [README.md](file:///c:/Users/User/Desktop/debugrem/ML-3m-trader/README.md)
+
+Professional README with badges (Python, License, LightGBM), project description, features list, quick start, architecture overview, and configuration reference. No emojis.
+
+#### [NEW] [GUIDE.md](file:///c:/Users/User/Desktop/debugrem/ML-3m-trader/GUIDE.md)
+
+Step-by-step usage guide with tables for all commands, parameters, and expected outputs.
+
+#### [NEW] [.gitignore](file:///c:/Users/User/Desktop/debugrem/ML-3m-trader/.gitignore)
+
+Standard Python gitignore plus `data/`, `results/`, `models/`, `*.pkl`.
+
+---
+
+## Verification Plan
+
+### Automated Tests
+
+1. **Syntax validation** — run `python -m py_compile <file>` on every `.py` file to confirm no syntax errors
+2. **Import validation** — run `python -c "import config; import features; import labeler; import model; import backtester; import metrics"` to confirm all modules load correctly
+3. **Dry-run test** — run `python main.py --help` to confirm CLI is functional
+
+### Manual Verification
+
+1. **User runs `python main.py fetch`** with MT5 open and logged in, confirms data CSV is created in `data/`
+2. **User runs `python main.py run`** for the full pipeline, reviews the metrics report output
+3. **User inspects `results/report.txt`** for the performance metrics