Skip to main content

Model Format

TinyLoop models are stored as .tinyloop binary artifacts.

The format is intentionally narrow: it stores the exact model family that TinyLoop is built to run, not an open-ended arbitrary graph format.

The public header declares:

  • MAGIC = 0x504C4C54
  • VERSION = 3

At load time, TinyLoop validates:

  • file magic
  • format version
  • dimensions
  • head divisibility
  • pre-block count assumptions
  • quantization metadata when present

Header Field Order​

The runtime reads the following fields in order:

  1. magic
  2. version
  3. dim
  4. n_heads
  5. ffn_dim
  6. vocab_size
  7. embed_factor_dim
  8. n_pre_blocks
  9. default_loops
  10. quantization bit metadata when version >= 2
  11. quantization group-size metadata when version >= 3

Supported Versions​

Documented public runtime support is:

  • v1
  • v2
  • v3

Version meaning:

VersionMeaning
v1baseline low-bit artifact
v2explicit quantization bit metadata
v3explicit quantization group-size metadata

Weight Storage Modes​

TinyLoop currently supports two embedding/head layouts.

Factored mode​

Triggered when embed_factor_dim > 0.

Stored tensors include:

  • embed_weight
  • embed_proj
  • head_proj
  • head_weight

This is the mode used by the current target artifact with E=64.

Direct quantized mode​

Triggered when embed_factor_dim == 0.

Stored tensors include:

  • quantized embedding
  • quantized head

Quantization Metadata​

Per public runtime support, artifacts describe:

  • quantization bit-width
  • quantization group size

Current runtime execution supports low-bit paths such as INT2 and INT4, plus optional dequantized FP16 body caches at load time for faster execution.

Compatibility Policy​

If you change artifact semantics:

  1. bump the format version
  2. update the loader explicitly
  3. update docs and tests together
  4. avoid silent compatibility drift

Operational Guidance​

When you receive a new artifact:

  1. run inspect
  2. verify dimensions and memory footprint
  3. benchmark it
  4. validate behavior against a known reference path

Do not treat a successful load alone as proof that the artifact is correct.