Monte-Neo

<!-- mcp-name: io.github.NeoZorK/monte-neo -->

<h1 align="center">
  <img src="https://raw.githubusercontent.com/NeoZorK/Monte-Neo/main/docs/assets/social-preview.png" alt="Monte-Neo: the independent verifier for trading strategies written by AI agents and humans" width="860"/>
</h1>

<p align="center">
  <strong>The independent verifier for trading strategies written by AI agents and humans.</strong><br/>
  Catch look-ahead bias, hidden trading costs and overfitting before a backtest reaches your money.
</p>

<p align="center">
  <a href="https://pypi.org/project/monte-neo/"><img src="https://img.shields.io/pypi/v/monte-neo?label=PyPI&color=0a7bbb" alt="PyPI version"/></a>
  <a href="https://pepy.tech/projects/monte-neo"><img src="https://static.pepy.tech/badge/monte-neo" alt="Total downloads"/></a>
  <a href="https://pypistats.org/packages/monte-neo"><img src="https://img.shields.io/pypi/dm/monte-neo?label=downloads%2Fmonth" alt="Downloads per month"/></a>
  <a href="https://pypi.org/project/monte-neo/"><img src="https://img.shields.io/pypi/pyversions/monte-neo" alt="Python versions"/></a>
  <a href="https://github.com/NeoZorK/Monte-Neo/actions/workflows/ci.yml"><img src="https://github.com/NeoZorK/Monte-Neo/actions/workflows/ci.yml/badge.svg" alt="CI"/></a>
  <a href="https://github.com/NeoZorK/Monte-Neo/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="MIT license"/></a>
  <br/>
  <a href="https://registry.modelcontextprotocol.io/v0/servers?search=io.github.NeoZorK/monte-neo"><img src="https://img.shields.io/badge/MCP%20Registry-io.github.NeoZorK%2Fmonte--neo-6f42c1" alt="MCP Registry"/></a>
  <a href="https://neozork.github.io/Monte-Neo/guides/agents/"><img src="https://img.shields.io/badge/works%20with-Claude%20Code%20%C2%B7%20Codex%20%C2%B7%20Gemini%20CLI%20%C2%B7%20Cursor-444" alt="Works with coding agents"/></a>
  <a href="https://github.com/NeoZorK/Monte-Neo/stargazers"><img src="https://img.shields.io/github/stars/NeoZorK/Monte-Neo?style=flat" alt="GitHub stars"/></a>
</p>

<p align="center">
  <a href="https://neozork.github.io/Monte-Neo/">Docs</a> ·
  <a href="#quick-start">Quick start</a> ·
  <a href="https://neozork.github.io/Monte-Neo/guides/agents/">Use from agents</a> ·
  <a href="https://neozork.github.io/Monte-Neo/api/verify/">Verifier API</a> ·
  <a href="https://neozork.github.io/Monte-Neo/guides/trap-suite/">Trap Suite</a> ·
  <a href="https://github.com/NeoZorK/Monte-Neo/blob/main/docs/project/CHANGELOG.md">Changelog</a>
</p>

---

## The problem

A coding agent can turn a trading idea into a backtest in minutes. It will then tell you the
strategy returns 40% a year with a Sharpe of 3. Most of the time that number is wrong, for
the same few reasons:

- **Look-ahead bias.** The code reads future bars: `shift(-1)`, centred windows, `bfill`,
  statistics over the whole series, `np.gradient`, an FFT filter.
- **Missing costs.** The edge is smaller than fees and slippage, or it disappears when the fill
  comes one bar later.
- **Selection bias.** The agent tried 300 variants and reports the best one as if it were the only one.

Backtest libraries run whatever code you give them. None of them tell you the backtest itself is broken.

## The solution

**Monte-Neo checks the backtest, not the idea.** Give it the price data and the strategy code
or its positions. It returns one of four verdicts, the checks behind the verdict, concrete next
steps and a reproducible, optionally signed certificate.

<p align="center">
  <img src="https://raw.githubusercontent.com/NeoZorK/Monte-Neo/main/docs/assets/demo-verify.gif" alt="monte-neo verify rejects a leaky agent strategy, the agent fixes it, and the honest verdict follows" width="820"/>
</p>

The agent's strategy used `shift(-1)`, so it knew the next close. Monte-Neo found the leak in four
independent ways and named the line. After the fix, no look-ahead is left, and the verifier tells
the truth: on a random walk, the strategy has no edge after costs.

<details>
<summary>Text output of the first run</summary>

```console
$ monte-neo verify --ohlcv prices.csv --strategy agent_strategy.py --n-trials 40
REJECT  certificate 7f0603b0e604bea5
  check                    category    status  summary
  data_integrity           integrity   pass    OHLCV is clean
  lookahead_truncation     lookahead   fail    truncation probe: LEAK DETECTED
  lookahead_perturbation   lookahead   fail    future-perturbation probe: LEAK DETECTED
  lookahead_static_lint    lookahead   fail    static lint: negative_shift
  implausible_accuracy     lookahead   fail    next-bar hit rate 1.000 over 2999 bars (z 54.8)
  net_profitability        economics   fail    net total return -64.97% after costs
  deflated_sharpe          statistics  fail    deflated Sharpe 0.000 over 40 trial(s)
  ...                                          (16 more checks)
→ The signal at bar t changes when later bars are removed: compute features only from rows <= t
  (no shift(-k), centered windows, bfill or full-sample stats).
→ Fix the flagged source lines (negative shift, center=True, backward fill) and re-run verify. Lines: 6.
```

The run used a synthetic random walk; output shortened.

</details>

| Verdict | Meaning | CLI exit code |
|---------|---------|---------------|
| `PASS` | No problems found | 0 |
| `PASS_WITH_WARNINGS` | Usable; read the warnings | 0 |
| `NEEDS_MORE_EVIDENCE` | Too few trades, or the Sharpe does not survive the number of variants tried | 1 |
| `REJECT` | The backtest is broken or loses money after costs | 2 |

## New: catch look-ahead that hides in milliseconds

<p align="center">
  <img src="https://raw.githubusercontent.com/NeoZorK/Monte-Neo/main/docs/assets/demo-arrival.gif" alt="monte-neo verify --quotes: a fast strategy earns +191% on exchange time and loses 23% on arrival time; a slow honest strategy keeps its profit" width="820"/>
</p>

**The problem.** A quote has two times: when the exchange stamped it and when it reached you. Most backtests on
intraday quotes bin them by the stamp, so a fast strategy trades on prices it could not have seen yet. No code lint finds
this: the leak is in the clock, not in the code.

**What Monte-Neo does** (`monte-neo verify --quotes quotes.csv --strategy my_strategy.py`):

- **Arrival look-ahead.** The same strategy sees bars built from the arrival time and trades against the market. If the
  profit exists only with zero latency, it is a leak at millisecond scale.
- **The delay where the profit vanishes.** One number you can act on: "the profit disappears at 38 ms of extra delay".
- **Latency Monte Carlo.** Each quote's latency is redrawn from the latency you actually observed (inside its venue),
  200 seeded draws: the distribution of the return and the probability of a loss. It shows when a profit was lucky latency.
- **Order delay.** `--order-latency-ms` delays every fill, so an edge that lives in instant execution is rejected.
- **No server near the exchange?** `--latency-model lognormal:8,25` assumes the latency (median and p95 in ms) instead of
  reading it, and the certificate says plainly that it is assumed, not measured.
- **Several feeds in one strategy.** `--symbol` and `--feeds` let a strategy trade one instrument on the prices of another
  (lead-lag, futures against spot); each feed has its own latency. A leader that arrives after the follower moved is caught.
- **Look-ahead probes too.** The truncation and perturbation probes of `verify_strategy` run on the arrival bars, so a strategy
  that reads the next bar (`shift(-1)`) is rejected: that leak exists on every clock.
- **Quote quality.** Crossed quotes, negative latency, out-of-order arrivals and **bursty latency**: a congested path
  (VPN, Wi-Fi) holds messages and releases them in bursts, and the check says so instead of reporting your network as a result.
- **A certificate.** Signed, and reproducible with `--recheck` like every other certificate.

```console
$ monte-neo verify --demo-quotes     # no files: a fast strategy and an honest one
$ python -m monte_neo.data.quote_recorder --symbol BTCUSDT --seconds 600 --out quotes.csv   # your own latency
```

What sets it apart: it is an **audit, not an environment**. It takes a finished strategy from any source (any `signal(df)`
function, or an agent's code) and your own quote recording, and says whether the profit survives the time the data
arrived, with a certificate others can reproduce. The strategy does not have to be written for a particular engine.

Honest scope: experimental. The latency checks are context (`warn` at most) and were calibrated on synthetic data, so record
real latency on the machine that will trade, or state an assumed latency and read the verdict as conditional on it. Fills
are taker orders at the mid, with the data latency from the quotes (or assumed) plus a fixed order delay. **Queue position and
partial fills are not modelled, on purpose** (they need the order book and a passive-order model; a rough formula would give
false precision), so a market-making strategy cannot be validated here; the certificate lists these assumptions.
[Read the guide](https://neozork.github.io/Monte-Neo/guides/arrival-time/).

## What it checks

| Family | Checks |
|--------|--------|
| **Look-ahead** | Truncation probe (does bar *t* change when later bars are removed?), future-perturbation probe, outside-data watch (files or network read by the strategy), static AST lint (23 rules), implausible hit rate |
| **Economics** | Net return after commission and slippage (with optional funding, short-borrow fees, stops inside the bar and per-symbol costs for universes), break-even cost in bps, one- and two-bar execution delay, a spread estimate from high and low next to the modeled cost, capacity from volume (for universes with the tightest symbols named) |
| **Statistics** | Probabilistic and Deflated Sharpe priced by `n_trials`, Monte Carlo timing test (does the signal beat shifted copies of it