GRIT — Grouped Reduced-precision Interchange Type

A Q4_K blob and an MXFP4 blob are both "4-bit weights", but their decodes differ, their layouts differ, and nothing at the file boundary says so. GRIT makes that contract explicit: a 64-byte descriptor that can be checked against the bytes in O(1), fingerprinted, and diffed field-by-field when two artifacts disagree.

Start here: audit files you already have

grit scan requires zero adoption by any framework. Point it at safetensors or GGUF files, or at a directory tree:

grit-scan [--deep] [--json] PATH...

It recovers descriptors from a __grit__ safetensors header key or grit.desc.<tensor> GGUF KV entries (inferring them from well-known ggml block structs otherwise) and reports descriptor-vs-bytes violations, cross-file gid disagreements with field-by-field diffs, grade-drift clusters, and NOTE_ASSUMED escape-hatch exposure.

Exit codes: 0 clean, 1 structural violation, 2 disagreement, 3 warnings only, 4 unparseable.

The explicit contract fields

A GRIT array is a quadruple (Grade, Placement, Planes, Shape):

• Grade — the complete numeric contract: element format, group sizes, scale formats, zero-point convention, sparsity, rounding and saturation promises. It has one canonical string form and a derived 64-bit id (gid).
• Placement — the physical layout, carried as a 64-bit value, never a type parameter. New silicon means a new constant, not a new type.
• Planes — up to four byte buffers: data, scale0, scale1, aux.
• Shape — rank and extents, carried in the view.

The core guarantee: equal gid and equal plane bytes implies bit-identical decode() on every conformant implementation — and the descriptor check never has undefined behaviour, even on adversarial 64-byte input. gid certifies decode agreement and nothing else: not calibration quality, not provenance, not trustworthiness.

This package

Pure Python, standard library only; numpy is an optional extra used by grit.to_array() and is never imported at module scope. It is one of five independent implementations (C, C++, Rust, Python, TypeScript) that pass a shared 68-entry conformance vector suite generated by the executable reference, and that agree bit-for-bit on cross-language gid values.

The normative specification, the reference implementation, and the vector suite live in the project repository.

Licensed under Apache-2.0.