Metadata-Version: 2.4
Name: grit-datatype
Version: 1.0.0
Summary: Check what a quantized tensor actually means: GRIT descriptors carry the numeric contract, and `grit scan` audits safetensors/GGUF files you already have
Author-email: singhpratech <singhpratech@users.noreply.github.com>
Maintainer-email: singhpratech <singhpratech@users.noreply.github.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/singhpratech/grit-datatype
Project-URL: Repository, https://github.com/singhpratech/grit-datatype
Project-URL: Specification, https://github.com/singhpratech/grit-datatype/blob/main/spec/SPEC.md
Project-URL: Issues, https://github.com/singhpratech/grit-datatype/issues
Keywords: quantization,mxfp4,nvfp4,block-scaled,microscaling,safetensors,gguf,descriptor,conformance
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Archiving :: Packaging
Classifier: Typing :: Typed
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Provides-Extra: numpy
Requires-Dist: numpy; extra == "numpy"

# 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:

```sh
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 64-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.
