trade-jev

Tests Jev (TypeSafe) as a BUY / SELL / HOLD trader on NQ L10 order-book data from Databento (15 trading days, Jun 8–26 2026). Findings: results/FINDINGS.md. Published Jev answers and results are in results/; where the market data goes and how it was pulled is in data/DATA.md.

Concepts

• Run: a backtest that calls Jev and stores its answers and trades in runs/<id>/. It's the only step that costs money.
• Settings: harness parameters: cutoff, agreeing answers, min hold, stop, target, commission.
• Replay: a run's stored answers re-scored under new settings. It needs no API calls.
• View: one local web app that replays any mix of runs, days and settings live.

Flow: run once → replay many times → view.

0) Setup

Install dependencies, add your API key, and point at the data. Databento day files go in data/databento/ (gitignored), or anywhere set by TRADE_JEV_DATA; see data/DATA.md. No data yet? Use the synthetic sample.

uv sync
echo "TYPESAFE_API_KEY=..." >> .env
echo "TRADE_JEV_DATA=/path/to/databento/files" >> .env        # optional; default data/databento/
TRADE_JEV_DATA=data/sample uv run python -m trade_jev.run --days 2026-06-23 --policies hold,random,imbalance   # smoke test

In git: code, docs, data/sample/ (synthetic), results/ (published runs), runs/index.jsonl. Local only: Databento data, runs/<id>/ (includes the order books Jev saw), cache/, .env.

1) Run

Asks Jev every 15s and trades 1 contract next to the hold / random / imbalance baselines. It prints Jev calls and P&L, saves to runs/<id>/, and appends to runs/index.jsonl, which the viewer lists.

uv run python -m trade_jev.run --days 2026-06-23                                   # one day
uv run python -m trade_jev.run --days 2026-06-08,2026-06-09,2026-06-10             # several days
uv run python -m trade_jev.run --all                                               # all 15 days
uv run python -m trade_jev.run --days 2026-06-23 --policies hold,random,imbalance  # baselines only, no API

2) Run settings

Defaults are the registered setting from results/FINDINGS.md: cutoff 0.7, 4 agreeing answers, 30s min hold, 200-tick stop, 100-tick target (0 = off; defined in src/trade_jev/settings.py). Settings change which positions Jev sees, so a new run calls Jev again.

uv run python -m trade_jev.run --days 2026-06-23 \
  --min-conf 0.6 --agree 2 --min-hold 60 --stop-ticks 400 --target-ticks 0 \
  --cadence-s 15 --latency-ms 250 --commission 2.5

3) Replay

Replays one or more runs under many settings at once to find settings that hold up across days. It's free but approximate, because Jev answered with the run's own positions.

uv run python scripts/replay_sweep.py runs/<id> [runs/<id> ...]         # quick per-day table
uv run python scripts/replay_grid.py runs/<id> [runs/<id> ...]          # 1,920 settings → runs/replays/grid-<ts>.csv
uv run python scripts/analyze_replays.py runs/replays/grid-<ts>.csv     # rank + overfitting checks
uv run python scripts/findings.py --tune runs/<a> --test runs/<b> --grid runs/replays/grid-<ts>.csv  # tune vs test report

4) View

A local web app that lists every run in runs/index.jsonl. Pick any mix of runs and days, replay them live with the sliders, save presets to compare, press play, and click any point to see what Jev saw.

uv run python -m trade_jev.view                  # → http://localhost:8765
uv run python -m trade_jev.view --port 9000 --no-open

Links keep the view: ?sel=<run>@<day>,<run>@<day>&minConf=0.6&agree=2&minHold=60&stop=400&target=0 plus &play=1 (autoplay) or &at=11:02 (jump to a time).

5) Publish

Copies a run's Jev answers, probabilities, trades and results to results/<id>/ for sharing. Order books and prices are stripped, since they're licensed Databento data.

uv run python scripts/publish_run.py runs/<id> [runs/<id> ...]

6) Test

Unit tests, plus a check that the page's replays match the Python replays.

uv run pytest -q
uv run python scripts/check_viewer.py runs/<id>
uv run python scripts/make_sample.py        # regenerate the synthetic sample