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.

Header

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:

Version	Meaning
v1	baseline low-bit artifact
v2	explicit quantization bit metadata
v3	explicit 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.