gguf-quickref

name	gguf-quickref
description	Quick reference for src/vramgeist/gguf.py parser. Use before editing gguf.py or adding new metadata keys.

gguf-quickref

gguf.py is 150 lines, defensive binary parser. Read once, refer here after.

Public API

Symbol	Sig	Notes
read_gguf_metadata(path, max_kv=1000, max_key_len=1024, max_str_len=1_000_000)	`(dict	None, warnings[])`
estimate_model_size_mb(path)	float	Accepts str or Path
ParserError	exception	Raised on EOF

File format

magic[4]="GGUF" | version<u32> | tensor_count<u64> | kv_count<u64> | KVs...

KV layout: key_len<u64> key_bytes value_type<u32> value_payload.

value_type codes handled

Code	Type	Payload
4	STRING	len<u64> bytes
5	ARRAY	array_type<u32> array_len<u64> items — only STRING arrays decoded
6,7	INT32/UINT32	<u32>
8,9	INT64/UINT64	<u64>
10,11	FLOAT32/FLOAT64	<f>/<d>
12	BOOL	<?> 1 byte
else	unknown	stops parse, warning appended

Post-process

After raw KVs, parser scans STRING values + STRING ARRAY items for key=value substrings (split on \n,;) and adds them to metadata (without overwriting). Used for HF-style metadata blobs.

Layer-count keys to grep when computing n_layers

*.block_count, e.g. llama.block_count, gemma.block_count.

Gotchas

• Non-string array payloads are NOT skipped byte-by-byte → file pointer drifts. Adding non-string array decode = breaking change, write test first.
• All strings decoded UTF-8 with errors="replace" → never raises on bad bytes.
• Defensive caps: bump cautiously, document why.
• read_exact raises ParserError on short read → caught at top level returning (None, [...]).

Edit rule

Always test with tests/test_gguf.py tests/test_gguf_deep.py (see validate skill).