kronos-mql5/README.md

# kronos-mql5

A native MQL5 port of Kronos-small inference. Kronos is a pretrained transformer
that forecasts candlesticks the way a language model predicts words.

## What it does

The whole forward pass runs inside MetaTrader 5. There is no Python at runtime.
Python is used once, offline, to export the weights and to capture reference
activations for verification.

The port is hand-written in MQL5 `matrix` and `vector` operations: RMSNorm,
SwiGLU, rotary position embeddings, scaled dot-product attention, causal
multi-head attention and non-causal cross-attention, plus the BSQ tokenizer
math that turns OHLCV bars into tokens and back.

Every stage has its own verification harness that checks MQL5 output against
the captured PyTorch reference. That is the part worth attention: a transformer
with a transposed weight or an off-by-one in the KV cache still produces
confident-looking forecasts.

On top of that sits a second, separate question: whether the forecasts are any
good. Verification answers fidelity to PyTorch and nothing else. The evaluation
harness answers market value, and the two are not the same claim.

## Layout

```
Include/Kronos/KronosTokenizerMath.mqh    preprocessing, BSQ bit math, weight loading
Include/Kronos/KronosTransformerCore.mqh  RMSNorm, SwiGLU, RoPE, attention, blocks
Include/Kronos/KronosSampling.mqh         softmax, top-k and top-p, multinomial
Include/Kronos/KronosEncoder.mqh          tokenizer encode chain
Include/Kronos/KronosDecoder.mqh          tokenizer decode chain
Include/Kronos/KronosPredictorS1.mqh      first-stage decode with KV cache
Include/Kronos/KronosPredictorS2.mqh      second-stage decode with cross-attention
Include/Kronos/KronosInference.mqh        autoregressive loop
Experts/Kronos/KronosForecast.mq5         draws the forecast candles on a live chart
Experts/Kronos/KronosSignalEA.mq5         Strategy Tester rule over a precomputed dump
Scripts/Kronos/KronosSelfTests.mq5        weight-free unit checks
Scripts/Kronos/KronosVerify*.mq5          per-stage checks against the reference
Scripts/Kronos/KronosBench.mq5            timing
Scripts/Kronos/KronosProfile.mq5          profiling
Scripts/Kronos/KronosForecastDump.mq5     walk-forward forecast dump to CSV
Scripts/Kronos/KronosEvalQuality.mq5      forecast quality against a random walk
Kronos_Python/export_kronos_weights.py    one-off weight export
Kronos_Python/kronos_reference_capture.py reference activations for verification
```

## Running it

1. Export weights with `export_kronos_weights.py` and capture references with
   `kronos_reference_capture.py`. Both are offline, run once.
2. Run `KronosSelfTests.mq5`, then the `KronosVerify*` harnesses in order. Each
   checks one stage against the reference.
3. Only then run inference. `KronosForecast.mq5` attaches to a chart and draws
   the predicted candles to the right of live price.

## Evaluating it

The evaluation is deliberately split into three programs so that no analysis can
change what the model predicted, and so that look-ahead is structurally hard
rather than merely promised.

1. `KronosForecastDump.mq5` walks history once and writes greedy forecasts, plus
   the realized future closes, to CSV. Context uses only bars before the
   evaluation bar; the realized closes are stored for scoring and never feed a
   decision. Greedy decoding makes the whole study reproduce exactly.
2. `KronosEvalQuality.mq5` scores that dump per horizon: directional accuracy,
   and an error skill ratio against a random-walk (no-change) baseline. A ratio
   below 1.0 means the model beats the baseline.
3. `KronosSignalEA.mq5` runs a deliberately trivial threshold rule over the same
   dump in the Strategy Tester. It performs no inference and discards the
   realized-close columns as it parses.

The dump is written to the terminal's shared `Common\Files` folder rather than
`MQL5\Files`, because a Strategy Tester agent is sandboxed to its own private
Files directory and cannot read what the script wrote otherwise. All three
programs open the CSV with `FILE_COMMON`.

## Result

On EURUSD H1 with tick-derived volume, this model has **no usable forecasting
edge**. Directional accuracy is 51% across roughly 15,000 horizon samples, and
the error skill ratio is above 1.0 at every horizon, meaning the point forecasts
are less accurate than assuming price will not move. A fair backtest at 150
trades gives Profit Factor 1.02 and Sharpe 0.13, before any spread or commission.

A high signal threshold produces a far prettier report, Profit Factor 2.70 and
Sharpe 1.87, but from only 15 trades, with a Z-Score confidence of 34%: it is
statistically indistinguishable from random. That contrast is the most useful
thing in this repository. Read the trade count before believing an equity curve.

Likely reasons for the negative result: Kronos was trained on equities and crypto
on daily and longer bars, FX feeds carry no real exchange volume so two of the six
input features are proxies the model never saw in training, and EURUSD intraday is
close to a martingale where "no change" is a very strong baseline. A retest on
daily bars with real volume is the obvious follow-up, and it belongs alongside
this result rather than instead of it.

## Disclaimer

Educational code. Past behaviour of any model or dataset says nothing about
future results. Test on your own data and broker conditions before drawing
conclusions.