feat(trading): self-improving MetaTrader 5 trading bot with risk-first execution

[gareth-prog]

Adds a standalone systematic trading bot for MetaTrader 5 under ai-trading-bot/. It generates signals from a strategy book, learns which strategies work in which market regimes, sizes every position from a fixed risk budget, and can ingest externally-described strategies through a validation gauntlet.

Self-contained: no dependency on the ruflo framework, and nothing outside ai-trading-bot/ is touched.

Why the design looks like this

A dollar-per-week target is only meaningful relative to account size. goal/controller.py derives the required weekly return from live equity and classifies it (comfortable / aggressive / unlikely / infeasible). $1000/wk is 0.5%/wk on $200k and 20%/wk on $5k — the second is not a strategy, it's a wish.

The load-bearing property: the goal can only scale risk DOWN. scale is clamped to <= 1.0, so falling behind target can never talk the bot into betting bigger. That feedback loop — lose, size up to catch up, lose bigger — is the usual way accounts die, and here it is structurally impossible rather than discouraged. test_scale_never_exceeds_one asserts it across thousands of input combinations.

Risk decisions live in exactly one place (risk/manager.py) and it is the only component that can approve a trade. Sizing is risk-first: a wider stop buys a smaller position, so the dollar loss on a stop-out is invariant to instrument and volatility. Circuit breakers cover daily loss, weekly loss, max drawdown (hard halt, manual reset only) and a file-based kill switch. Guard state persists, so a crash loop cannot be used to reset the daily limit.

Learning runs on two independent mechanisms. A discounted Thompson-sampling bandit over (strategy, regime) learns what works and suppresses what stops working, using R-multiple rather than profit so statistics survive changes in account size. A gradient-boosting meta-model gates individual setups — and is refused outright if it cannot beat AUC 0.55 on a forward-chained holdout, since a filter with no demonstrated skill would just be an expensive random number generator.

The research pipeline never eval()s extracted text. It converts strategy descriptions into testable specs; research/safe_expr.py parses to an AST and rejects any node off an allowlist (no attribute access, subscripting, imports, comprehensions, or string literals). This matters because extracted rules would otherwise run on a machine logged into a brokerage account. Extracted strategies stay inert until they clear backtest → walk-forward → cost-shock → cross-instrument robustness, plus forward paper testing and a human ack. Martingale and grid sizing are refused at ingest rather than merely unsupported.

The backtester is deliberately pessimistic: stops win intrabar ties, signals act on the next bar's open, costs are charged both ways. A regression test asserts it loses money on a random walk — if that ever passes, it's cheating.

Live-trading safety

Real-money trading requires two independent keys (mode: live and allow_live: true) plus interactive confirmation. Paper mode is the default and runs the identical code path through the same Broker protocol. Credentials come from the environment or a gitignored file, never from config.yaml.

Verification

265 tests pass, including end-to-end integration tests that drive the real TradingEngine (signals → orders → closes → learning), property sweeps on the per-trade risk ceiling and the goal-scale invariant, indicator causality checks, and 22 sandbox escape attempts.

Three bugs found and fixed by those tests:

• A position sitting exactly at +1R computed r = 0.9999999999999556 from float subtraction, so the breakeven stop never applied and the trade could reverse into a full loss. Stops and targets both derive from the same ATR, so hitting the threshold exactly is routine, not a corner case.
• Strategy extraction mirrored the non-directional filter ADX > 25 into ADX < 25 for the short leg, silently inverting a trend filter into a chop filter. A leg of pure filters with no entry trigger would also have fired on most bars.
• Walk-forward laid folds out from bar 0, silently dropping the first window for lack of training data — so a caller asking for 4 windows got 3 and read it as a failure rather than a data limit.

Also fixed an O(n²) backtest (strategies recomputed indicators over full history each bar). Now linear at ~320 bars/sec with byte-identical results.

Reviewer notes

• No demonstrated edge is claimed. The five seed strategies are textbook setups — a substrate for the learning machinery, not a proven money-maker. Synthetic backtest numbers come from data with planted structure; the CLI prints a warning saying so on every run.
• Verified against a live MT5 install up to the point of broker login; the account in use was rejected by IC Markets as expired, so live-broker order placement is untested against a real account. Everything below that boundary (paper broker, engine loop, learning, risk) is covered by the integration tests.
• MetaTrader5 is Windows-only and marked as an optional extra, so it does not affect CI on other platforms.
• Was there interest in this living in ruflo at all? It's fully standalone and might be better as its own repository — happy to relocate it.

🤖 Generated with RuFlo