OKLMdocumentation v1.0.3
On this page

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_dtype values equal ggml_type values). 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.json and 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 mmproj GGUF 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.