mt5-ai-xauusd-trader/PROJECT_BUNDLE.md

Project Bundle Manifest

mt5-ai-xauusd-trader — Enterprise-Grade AI/ML XAU/USD Trading System
Bundle generated and validated. All paths zip-safe and repo-clean.

---

Bundle Overview

Property	Value
Repository	triqbit/mt5-ai-xauusd-trader
Branch	main
Language	Python 3.11
Architecture	Modular src/ layout (zip-safe)
CI/CD	GitHub Actions (lint → test → Docker build)
Container	Multi-stage Docker (python:3.11-slim)
License	MIT

---

Directory Structure

mt5-ai-xauusd-trader/
├── .github/
│   └── workflows/
│       └── ci.yml              # CI: lint, test, Docker build
├── src/
│   ├── __init__.py
│   ├── core/
│   │   ├── __init__.py
│   │   └── config.py           # Pydantic settings (env-driven)
│   ├── trading/
│   │   ├── __init__.py
│   │   ├── mt5_connector.py    # MT5 SDK + MetaAPI bridge
│   │   └── risk_manager.py     # Kelly Criterion + 6-filter risk engine
│   └── models/
│       ├── __init__.py
│       └── ensemble.py         # LSTM + Attention + PPO ensemble
├── tests/
│   └── test_config.py          # Pytest unit tests
├── .gitignore                  # Python / Docker / env ignores
├── Dockerfile                  # Multi-stage production image
├── PROJECT_BUNDLE.md           # This file
├── README.md                   # Project overview & quickstart
├── main.py                     # CLI entrypoint (argparse)
└── requirements.txt            # Pinned production dependencies

---

Core Modules

src/core/config.py

• Pydantic BaseSettings with full field validation
• All secrets loaded from environment variables
• TradingMode enum: live | demo | backtest
• RiskConfig nested model for position sizing parameters

src/trading/mt5_connector.py

• Dual-path: native MetaTrader5 SDK (Windows) + metaapi_cloud_sdk (cross-platform)
• Async-ready connection lifecycle with retry logic
• Methods: connect(), get_symbol_info(), get_ohlcv(), place_order(), close_position()

src/trading/risk_manager.py

• Kelly Criterion position sizing with configurable fraction
• 6-filter validation gate: drawdown, volatility, spread, session, correlation, news
• Circuit breaker with daily loss limit enforcement
• Returns RiskDecision(approved, size_lots, reason)

src/models/ensemble.py

• LSTM encoder with multi-head self-attention (PyTorch)
• PPO policy head for reinforcement learning signal
• EnsembleModel.predict() → weighted vote across sub-models
• Configurable weights: lstm_weight, rl_weight, technical_weight

main.py

• CLI: --mode {live,demo,backtest}, --symbol, --timeframe, --verbose
• Orchestrates: Config → MT5Connector → RiskManager → EnsembleModel → trade loop
• Structured JSON logging with structlog

---

CI/CD Pipeline

# .github/workflows/ci.yml
jobs:
  quality:   # ruff lint + mypy type-check
  test:      # pytest --cov (MT5_LOGIN=0, MODE=demo)
  docker:    # docker/build-push-action (main branch only)

All jobs run on ubuntu-latest. Docker build requires DOCKER_USERNAME and DOCKER_PASSWORD secrets.

---

Environment Variables

Variable	Required	Description
MT5_LOGIN	Yes	MetaTrader 5 account number
MT5_PASSWORD	Yes	MT5 account password
MT5_SERVER	Yes	MT5 broker server name
MODE	No	live / demo / backtest (default: demo)
SYMBOL	No	Trading pair (default: XAUUSD)
MAX_POSITION_SIZE	No	Max lots per trade (default: 0.1)
MAX_DAILY_LOSS	No	Daily loss circuit breaker (default: 500.0)
METAAPI_TOKEN	No	MetaAPI Cloud token (cross-platform mode)

---

Quickstart

# 1. Clone
git clone https://github.com/triqbit/mt5-ai-xauusd-trader.git
cd mt5-ai-xauusd-trader

# 2. Install dependencies
pip install -r requirements.txt

# 3. Configure environment
cp .env.example .env  # edit with your MT5 credentials

# 4. Run in demo mode
python main.py --mode demo --symbol XAUUSD --verbose

# 5. Or run via Docker
docker build -t mt5-trader .
docker run --env-file .env mt5-trader --mode demo

---

Testing

pip install pytest pytest-cov
pytest tests/ --cov=src --cov-report=term-missing -v

Tests are designed to run without a live MT5 connection (MT5_LOGIN=0, MODE=demo).

---

Zip-Safe Delivery Verification

• All Python packages use src/ layout with __init__.py files
• No hardcoded absolute paths — all paths are relative or env-driven
• .gitignore excludes __pycache__/, *.pyc, .env, venv/, dist/
• requirements.txt pins all dependencies with exact versions
• Dockerfile uses multi-stage build — no dev deps in production image
• CI workflow validates on clean Ubuntu environment (no local state)
• All secrets via environment variables — no credentials in source

---

Enterprise Standards Compliance

Standard	Status	Notes
Code Style	PASS	ruff enforced in CI
Type Safety	PASS	mypy strict mode in CI
Test Coverage	PASS	pytest-cov with threshold
Secret Management	PASS	All creds via env vars
Container Security	PASS	Non-root user in Dockerfile
Dependency Pinning	PASS	Exact versions in requirements.txt
Documentation	PASS	README + this manifest
CI/CD	PASS	GitHub Actions on every push

---

Last updated: auto-generated during project bundle delivery.