---
library_name: pytorch
tags:
  - finance
  - limit-order-book
  - order-flow
  - time-series
  - generative-model
  - custom-code
license: cc-by-nc-4.0
---

# 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

```text
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:

| Model | Size | Open-sourced |
| --- | ---: | :---: |
| tiny | 10M | ✅ |
| small | 25M | ✅ |
| base | 75M | ✅ |
| large | 366M | ❌ |
| xlarge | 1.27B | ❌ |

Released tokenizer:

| Component | Checkpoint |
| --- | --- |
| VQ tokenizer2 base | `tokenizer/base/best.pt` |

### 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

```bash
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:

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

Switch model size with:

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

The tokenizer decoded feature order is:

```text
[relative_open_price, log_volume, delta_time_seconds, action, side]
```