M3-market-microstructure

M3: A State-Event Generative Foundation Model for Market Microstructure Dynamics

<!-- This folder is the prepared open-source release package for GitHub and Hugging Face. --> <!-- It contains the released M3 LOB-prefix autoregressive checkpoints and one shared base VQ tokenizer checkpoint. Each model folder contains only the original training `best.pt`. -->

Files

tiny/best.pt
small/best.pt
base/best.pt
tokenizer/base/best.pt
vq_order_model/
examples/minimal_inference.py
requirements.txt
config.json
LICENSE

AR model release status:

Released tokenizer:

Note on the Deprecated Zero-Inflated Time Head

Tokenizer checkpoint may still contain legacy time_head.* parameters from an earlier zero-inflated time modeling experiment. This branch is deprecated and is not used in the M3 tokenizer.

For the released tokenizer, time decoding is performed with decode_time_mode="reconstruction", i.e., delta_time_seconds is decoded directly from the continuous reconstruction head. Users should ignore this head and use the reconstruction-based time output.

Install

pip install -r requirements.txt

Minimal Inference

The examples/ folder contains one tiny smoke-test sample (prompt_ids.npy, conditioning.npz, and example_metadata.json). Then run:

python examples/minimal_inference.py --model-size base

Switch model size with:

python examples/minimal_inference.py --model-size tiny
python examples/minimal_inference.py --model-size small

The tokenizer decoded feature order is:

[relative_open_price, log_volume, delta_time_seconds, action, side]