ADR-0002: Weight formats
Records which weight formats OKLM reads and writes, and that it follows the public specifications exactly instead of defining its own.
Status: accepted (2026-10-29).
Context
Open-weight models are distributed as GGUF files (llama.cpp
ecosystem) and as safetensors repositories with config.json
and tokenizer.json (Hugging Face). OKLM must run the models
people already have, without conversion by external tools, and its own
trained models should load in other tools.
Decision
- GGUF v3 is the primary format, read and written. v2 is read; v1 is rejected with a clear message. Only little-endian files are accepted.
- Tensor types use ggml's numbering and block layouts
exactly (
oklm_dtypevalues equalggml_typevalues). The legacy quants and the K-quants are read, computed and written (ADR-0013); IQ/TQ/MXFP4 types are recognized and reported as unsupported. - safetensors (with
config.json,tokenizer.json,tokenizer_config.json,generation_config.jsonand sharded index files) is read for import; F32/F16/BF16 and, read-only, F8_E4M3/E5M2 are accepted and can be quantized on the fly. - Training checkpoints are GGUF (weights) plus a sidecar GGUF for optimizer state (ADR-0008 decides the details).
- Vision projectors use llama.cpp's
mmprojGGUF layout (clip.*keys).
Consequences
Files written by OKLM load in llama.cpp and gguf-py, and
the reverse. Format code is checked against files produced by the
reference implementations. Any change to a file layout requires an
ADR.