| --- |
| 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] |
| ``` |
|
|
