CleoLOB

Reproducible market-microstructure and execution research.

CleoLOB studies execution strategies under explicit constraints around historical reconstruction, calibration, queue observability, incomplete execution, and out-of-sample evaluation.

What it is

CleoLOB is an open-source quantitative research platform for limit order books, historical replay, execution algorithms, empirical calibration, reinforcement learning, and reproducible experiments.

Its design goal is simple: make invalid assumptions, incomplete fills, data leakage, unsupported market-data inference, and selective reporting harder to mistake for evidence.

It is a research framework, not a production trading system.

Current evidence

Negative, null, and failed results are retained rather than removed from the research record.

The v0.5 research report documents the real-market validation study released as v0.5.0. The v0.4 final report documents the latest release.

Core capabilities

• deterministic FIFO synthetic exchange with limit/market orders, partial fills, cancellation and modification
• historical aggregate-L2 reconstruction and snapshot validation
• formal trades/L1/L2/MBO/simulator capability contracts
• identity-preserving MBO replay with lifecycle, queue and priority-reset semantics
• chronological calibration with sealed holdouts and consumed-dataset tracking
• calibration-failure diagnostics across distributions, tails, coverage, persistence and dependence
• TWAP, VWAP, POV, Almgren-Chriss and heuristic execution controls
• Stable-Baselines3 PPO and discrete-action DQN research workflows
• completion-constrained execution with actual-fill and residual-valuation separation
• bounded historical counterfactual execution (conservative / observable-FIFO / optimistic fill bounds) and historical policy replay
• frozen protocols with a hash-chained dataset-consumption ledger
• paired bootstrap inference and multiplicity-aware registered comparisons
• experiment provenance, source/config/data/model hashes and artifact verification
• risk, settlement and residual-inventory accounting
• registered performance and scaling studies
• FastAPI/Three.js and Streamlit exploration interfaces

Quick start

Requires Python 3.11+.

Install the latest release from PyPI:

python -m pip install cleolob

Verify:

cleo --help

For development:

git clone https://github.com/damraka/CleoLOB.git
cd CleoLOB
python -m venv .venv

Linux/macOS:

source .venv/bin/activate

Windows PowerShell:

.\.venv\Scripts\Activate.ps1

Install the development environment:

python -m pip install -e '.[dev]'

Optional RL and web dependencies:

python -m pip install -e '.[dev,rl,web]'

Run the test suite:

python -m pytest -q

Example commands:

cleo config validate configs/research.yaml
cleo validate-data examples/data/canonical-events.jsonl
cleo replay examples/data/canonical-events.jsonl
cleo validate-mbo examples/studies/v04/mbo-input/synthetic-events.jsonl \
  --manifest examples/studies/v04/mbo-input/adapter-manifest.json \
  --references examples/studies/v04/mbo-input/synthetic-aggregate.jsonl \
  --out results/mbo-check
cleo multiperiod-study --config configs/v04-multiperiod-smoke.json --out results/multiperiod
cleo scaling-study --out results/scaling
cleo smoke --out results/smoke
cleo verify-artifact results/smoke

See docs/reproduction.md and docs/v04-reproduction.md for the full reproduction workflows.

Historical reconstruction

CleoLOB has been evaluated against public Deribit ETH-PERPETUAL Level-2 data.

Across the preserved April/May validation samples:

One registered approximately 24-hour April stream contained 2,321,160 incremental rows, 1,531,713 reconstructed states and 988,235 exact top-five snapshot matches.

This demonstrates reconstruction consistency with published source snapshots. It does not establish exchange truth, hidden liquidity, exact passive-fill counterfactuals, or strategy profitability.

See historical validation and public market-data documentation.

Market-data capabilities, MBO and queue research

Aggregate L2 does not reveal individual order identities or exact FIFO queue positions, so CleoLOB keeps L2 and MBO evidence mechanically separated.

The v0.4 capability layer distinguishes trades, L1, aggregate L2, genuine order-level MBO, and simulator-internal information. Consumers are expected to fail explicitly when they request evidence the underlying source cannot establish.

The MBO layer supports source-native identities where available, ADD/MODIFY/CANCEL/EXECUTE events, deterministic replay, lifecycle validation, queue-ahead tracking, priority resets, observed maker executions, censoring and MBO-to-L2 aggregation.

The bundled MBO fixtures are synthetic. v0.5 adds a Bitstamp adapter for genuine venue order-level messages recorded live; its registered validation is INVALID and genuine historical vendor MBO validation remains NOT_AVAILABLE (v0.5 MBO).

See docs/mbo.md and docs/v04-data-contracts.md.

Calibration and historical generalization

CleoLOB uses chronological rather than random train/test evaluation and supports frozen selection, sealed holdouts, consumed-dataset tracking and observable-level failure diagnostics.

The preserved v0.3 external calibration failure remains part of the evidence record. v0.4 also evaluated the immutable historical model against a fresh June 2020 Deribit ETH-PERPETUAL period under the frozen design. That fresh holdout failed as well.

CleoLOB therefore does not currently claim that its calibrated synthetic market generalizes across unseen real-market regimes.

The diagnostics can describe associations with distribution shift, tails, coverage, persistence, dependence and regime behavior, but they do not by themselves establish a unique causal explanation for calibration failure.

See docs/calibration-v03.md and docs/v04-calibration.md.

Execution and reinforcement learning

The registered v0.4 policy study applies the same completion mechanism to PPO, DQN and the classical control family.

It trained 24 final models, totaling 49,152 training steps, and retained 1,080 registered evaluation episodes across three regimes, four training seeds and twelve evaluation market seeds.

Observed completion:

No new orders are submitted after the decision horizon. Post-horizon settlement is reported separately, and hypothetical residual valuation never creates an actual fill.

Of the 48 registered economic contrasts, 47 multiplicity-adjusted intervals included zero. The single exception was stress DQN minus POV, but zero joint cost-and-completion success gates passed. Learned-policy superiority, equivalence, adequate power, convergence and live profitability therefore remain NOT_ESTABLISHED.

The v0.3 PPO/DQN study remains preserved separately rather than being overwritten.

See docs/rl-v03.md and docs/v04-rl.md.

Performance and scaling

v0.4 includes a registered study covering 45 workload configurations across replay, simulation, parsing, calibration, serialization and related research paths.

The results characterize local Python research workloads. They are not production trading, exchange-colocation or HFT latency measurements.

See docs/v04-performance.md.

Reproducibility

Registered experiments can retain:

• normalized configuration
• source identity and hashes
• dataset identity and hashes
• model/checkpoint identity
• normalization identity
• random seeds
• study registration
• evaluation locks
• outcomes and validity status
• statistical results
• provenance metadata

Committed evidence can be verified with:

cleo verify-artifact examples/studies/v03
cleo verify-artifact examples/studies/v04/evidence
cleo verify-artifact examples/studies/v05/evidence

The v0.4 release passed 817 tests, cross-platform GitHub CI on Windows/Linux with Python 3.11-3.14, package builds, clean-wheel installation, CLI smoke tests and compact-evidence verification. The v0.5 research branch passes 974 tests locally (Windows, Python 3.14); every v0.5 study is bound to a frozen protocol and a hash-chained dataset-consumption ledger (v0.5 reproduction).

Byte-integrity verification establishes artifact consistency, not independent scientific replication.

Limitations

CleoLOB does not currently establish:

• genuine historical MBO queue validity
• hidden liquidity
• exact passive-fill counterfactuals from aggregate L2
• successful broad cross-regime simulator calibration
• agreement of simulated impact and resilience with history
• transfer of simulated policy conclusions to historical execution
• PPO/DQN or learned-policy superiority
• adequate power for broad policy-superiority claims
• live alpha or profitability
• production HFT or exchange-colocated performance
• universal cross-instrument or cross-venue transfer

These are explicit research boundaries rather than hidden assumptions.

Roadmap

v0.5, real-market execution validation, is implemented on the research branch: order-level validation, bounded historical execution, calibration v2, impact and resilience, strict completion, multi-regime external validity, a registered policy study and historical transfer. Its outcomes, including every negative and invalid one, are in the v0.5 report and the final report. See the v0.5 roadmap.

Documentation

• Architecture
• MBO semantics
• Public market data
• Research methodology
• Reproduction guide
• v0.3 calibration protocol
• v0.3 RL protocol
• v0.3 final report
• v0.4 roadmap
• v0.4 data contracts
• v0.4 calibration
• v0.4 RL study
• v0.4 performance
• v0.4 reproduction
• v0.4 final report
• v0.5 roadmap
• v0.5 research report and final report
• v0.5 details: protocol, data, MBO, historical execution, calibration, impact, execution, external validity, RL, transfer, statistics, performance, reproduction

Citation

Academic users can use the metadata in CITATION.cff.

License

CleoLOB is licensed under the GNU Lesser General Public License v3.0 or later (LGPL-3.0-or-later).

Disclaimer

CleoLOB is provided for research and educational purposes. Nothing in this repository constitutes investment advice, a recommendation to trade, or evidence of future trading performance.