Warrior_EA/README.md

# Warrior EA

A production-grade MetaTrader 5 Expert Advisor that trains and trades its own neural
networks, written entirely against the standard MQL5 toolchain (a compatible
`.mq5`/`.mqh` build also runs unmodified in StrategyQuantX/SQX). It fuses classic
technical/Wyckoff signal analysis with a custom, from-scratch deep-learning library
(dense, convolutional, LSTM, batch-norm) that trains, validates, and deploys itself
live on the chart — no external ML runtime, no Python dependency at inference time.

Designed for prop-firm-grade correctness: every subsystem that touches money,
capacity, or a deploy decision is built around one governing idea — **raw bar count is
not the sample size**. Overlapping labels, pooled instruments, and correlated bars all
get corrected down to an effective, independent sample size before anything is allowed
to size a network, weight a loss, or clear a gate.

> See [`PIPELINE_ANALYSIS.md`](PIPELINE_ANALYSIS.md) for a source-verified, file:line-cited
> deep dive into the data pipeline, network sizing, labeling, training loop, and deploy
> gating — written for technical review, not marketing.

## What it does

- **Trains its own models per instrument/timeframe**, on the chart, continuously —
  no offline training step is required to get a first model live.
- **Runs as a fleet**: multiple charts train independently but pool label statistics,
  capacity budgets, and deploy verdicts across instruments through a shared file-based
  pool, with a heartbeat/revive sweep that detects and restarts charts whose EA has
  fatally errored (a dead EA still leaves a chart window open — this is checked for).
- **Sizes its own network**: hidden-layer depth and width are derived from an
  overlap-corrected estimate of independent observations, not raw bar count or a fixed
  hyperparameter, and re-derived (without discarding trained weights) as more data
  accumulates.
- **Labels itself** with a leg-ride pivot label built on a from-scratch,
  lookahead-free replica of the ZigZag indicator, rather than reading the live
  indicator's repainting buffer.
- **Trains with a corrected loss**: class-prior logit adjustment, money-weighted
  sampling, and an average-uniqueness correction for overlapping labels, combined
  into a single per-sample weight.
- **Gates its own deployment**: a model only goes live once it clears measurability,
  coverage, two-sidedness, and a statistical edge test run against the same
  overlap-corrected sample size used to size it — not the raw row count.
- **Keeps learning after deployment**, blending online updates into a shadow network
  under a rolling-accuracy guardrail, rather than freezing at deploy time.
- **Enforces risk independently of the model**: a separate, always-on risk-budget
  layer (drawdown floors, an expectancy-based trading halt, position-size capping)
  runs on every tick regardless of what the model or the vote says.

## Architecture

```
Warrior_EA/
├── AI/                 Custom neural-network engine (dense / conv / LSTM / batch-norm)
│   └── Impl/           OpenCL, DirectML, CPU-DLL and pure-MQL5 backend implementations
├── Expert/
│   ├── AIBase/          Feature building, topology sizing, labeling, training, inference
│   ├── Labeling/        Leg-ride label, ZigZag replica, label overlap / effective-N
│   ├── Training/        Deploy gate, pooled cross-instrument gate, training pool
│   ├── Features/        Feature builder, fractional differencing
│   ├── Topology/        Capacity-budgeted layer sizing
│   ├── Signal/          Signal declustering (NMS)
│   ├── Chart/           Chart UI, vote/arrow rendering
│   ├── Persistence/     Model save/load, architecture-change handling
│   └── OnlineLearning/  Post-deployment shadow-network updates
├── Signals/             PAI / CONV / LSTM / HYBRID neural signals + classic indicator votes
├── Variables/           Central inputs, feature mask, money/uniqueness weighting, risk budget
├── Money/               Position-sizing strategies (fixed lot, fixed risk)
├── Trailing/             Trailing-stop strategies
├── Database/             Trade/signal journaling and statistics
├── System/               Infrastructure: alt-data fetch, atomic file I/O, retry/backoff
├── Panel/                In-terminal control panel (CAppDialog)
└── Scripts/              Offline research scripts (indicator param search, tick export)
```

## Getting started

1. Open `Warrior_EA.mq5` in MetaEditor (or SQX) and compile — all dependencies are
   relative includes within this repository.
2. Configure feature toggles, labeling, and training parameters in `Variables/Inputs.mqh`.
   Most feature-family flags are compile-time constants by design (they key the model's
   fingerprint), not runtime inputs.
3. Attach to a chart, enable Algo Trading, and let the EA build its indicator/feature
   cache and begin training from era 0.
4. Use the in-terminal control panel to monitor training progress, feature/topology
   state, and deploy-gate verdicts without needing to read the Experts log.
5. For a multi-instrument fleet, enable fleet expansion in `Expert/FleetExpansion.mqh`'s
   symbol list; charts will self-add and self-revive on a 10-minute sweep.

## Documentation

| Document | Covers |
|---|---|
| [`PIPELINE_ANALYSIS.md`](PIPELINE_ANALYSIS.md) | Full pipeline: features, network sizing, labeling, training/optimizer, deploy gating — source-cited |
| [`AI_NETWORK.md`](AI_NETWORK.md) | Neural-network engine internals (layer types, backends, kernels) |
| [`SIGNALS.md`](SIGNALS.md) | Signal module catalog (AI and classic) |
| [`DATABASE.md`](DATABASE.md) | Trade/signal persistence schema |
| [`EXPERIMENTS.md`](EXPERIMENTS.md) | Research log |
| Per-directory `README.md` files | Subsystem-local notes |

## Status

Actively developed against a live and a paper/backtest fleet. Architecture, labeling,
and gating logic all change frequently as measurement work continues — treat any
document in this repository (including this one) as accurate as of its last commit,
not as a permanent contract. `PIPELINE_ANALYSIS.md` is the one kept closest to current
source.

## Disclaimer

This is a research and trading system, not investment advice. Automated trading
carries a substantial risk of loss. Nothing in this repository should be construed as
a recommendation to trade any instrument or strategy.