ggufkit 0.1.0__py3-none-any.whl

ggufkit/__init__.py

@@ -0,0 +1,12 @@
+"""ggufkit: fingerprint, verify and visualize GGUF models."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("ggufkit")
+except PackageNotFoundError:  # pragma: no cover - only when running from a bare checkout
+    __version__ = "0.0.0+unknown"
+
+__all__ = ["__version__"]

ggufkit/__main__.py

@@ -0,0 +1,5 @@
+"""``python -m ggufkit``: the same as the ``ggufkit`` command."""
+
+from ggufkit.cli import entry
+
+entry()

ggufkit/_util.py

@@ -0,0 +1,75 @@
+"""Small helpers shared by the commands: safe output files and argument checks."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from contextlib import contextmanager
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+
+def prepare_output(path: Path, *, force: bool) -> None:
+    """Fail early, before any expensive work, if ``path`` cannot or must not be written."""
+    if path.exists() and not force:
+        msg = f"{path} already exists (use --force to overwrite)"
+        raise FileExistsError(msg)
+    parent = path.parent if str(path.parent) else Path()
+    if not parent.is_dir():
+        msg = f"{parent} is not a directory"
+        raise FileNotFoundError(msg)
+    if not os.access(parent, os.W_OK):
+        msg = f"cannot write to {parent}"
+        raise PermissionError(msg)
+
+
+@contextmanager
+def atomic_output(path: Path) -> Iterator[Path]:
+    """Yield a temporary path next to ``path``; move it into place only if the block succeeds.
+
+    An interrupted or failed write leaves ``path`` untouched instead of half-written.
+    """
+    tmp = path.with_name(f".{path.name}.{os.getpid()}.tmp")
+    try:
+        yield tmp
+        tmp.replace(path)
+    finally:
+        tmp.unlink(missing_ok=True)
+
+
+def write_text_atomic(path: Path, text: str) -> None:
+    with atomic_output(path) as tmp:
+        tmp.write_text(text, encoding="utf-8")
+
+
+def positive_int(value: str) -> int:
+    n = int(value)
+    if n < 1:
+        msg = f"must be at least 1, got {value}"
+        raise argparse.ArgumentTypeError(msg)
+    return n
+
+
+def non_negative_int(value: str) -> int:
+    n = int(value)
+    if n < 0:
+        msg = f"must not be negative, got {value}"
+        raise argparse.ArgumentTypeError(msg)
+    return n
+
+
+def positive_float(value: str) -> float:
+    x = float(value)
+    if not x > 0:
+        msg = f"must be greater than 0, got {value}"
+        raise argparse.ArgumentTypeError(msg)
+    return x
+
+
+def to_stderr(message: str) -> None:
+    """Progress and warnings go to stderr, so stdout carries only results."""
+    print(message, file=sys.stderr)

ggufkit/canon.py

@@ -0,0 +1,200 @@
+"""Canonical byte encodings behind the ``ggufkit-fp/1`` fingerprint specification.
+
+Everything here is deliberately boring: fixed-width little-endian integers, SHA-256, and no
+dependence on where in the file a value happened to be stored. The full specification lives in
+``docs/FINGERPRINT.md``; this module is its reference implementation.
+
+Why not just hash the file? Because two GGUF files with identical weights routinely differ in
+bytes: metadata gets reordered or edited by ``gguf-set-metadata``, a model gets split into
+shards, alignment padding changes. A content hash that ignores all of that lets you answer
+"is this the same model?" and "did only the metadata change?" without re-downloading anything.
+"""
+
+from __future__ import annotations
+
+import struct
+import sys
+from hashlib import sha256
+from typing import TYPE_CHECKING
+
+import numpy as np
+from gguf import GGUFEndian, GGUFValueType
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+    from gguf.gguf_reader import ReaderField, ReaderTensor
+
+SPEC_ID = "ggufkit-fp/1"
+
+#: Tensor data is hashed in slices of this many bytes so multi-gigabyte tensors never get copied.
+CHUNK_SIZE = 64 << 20
+
+_KV_TAG = b"kv\0"
+_TI_TAG = b"ti\0"
+_WT_TAG = b"wt\0"
+
+_SCALAR_TYPES = frozenset(
+    {
+        GGUFValueType.UINT8,
+        GGUFValueType.INT8,
+        GGUFValueType.UINT16,
+        GGUFValueType.INT16,
+        GGUFValueType.UINT32,
+        GGUFValueType.INT32,
+        GGUFValueType.FLOAT32,
+        GGUFValueType.UINT64,
+        GGUFValueType.INT64,
+        GGUFValueType.FLOAT64,
+        GGUFValueType.BOOL,
+    }
+)
+
+
+class UnsupportedModelError(ValueError):
+    """Raised for files whose canonical form ggufkit cannot compute yet."""
+
+
+def _u32(value: int) -> bytes:
+    return struct.pack("<I", value)
+
+
+def _u64(value: int) -> bytes:
+    return struct.pack("<Q", value)
+
+
+def _little_endian_bytes(arr: np.ndarray) -> bytes:
+    """Raw bytes of ``arr`` with multi-byte values in little-endian order."""
+    if arr.dtype.byteorder == ">" or (arr.dtype.byteorder == "=" and sys.byteorder == "big"):
+        arr = arr.astype(arr.dtype.newbyteorder("<"))
+    return arr.tobytes()
+
+
+def _encode_value(parts: list[np.ndarray], cursor: int, vtype: GGUFValueType) -> tuple[bytes, int]:
+    """Encode the value starting at ``parts[cursor]`` and return it with the next cursor.
+
+    The reader stores a field's parts in file order, so walking them with a cursor rebuilds
+    the exact structure of the value, including nested arrays which the reader otherwise
+    flattens.
+    """
+    if vtype == GGUFValueType.STRING:
+        data = parts[cursor + 1]
+        return _u64(int(data.nbytes)) + data.tobytes(), cursor + 2
+    if vtype in _SCALAR_TYPES:
+        arr = parts[cursor]
+        if vtype == GGUFValueType.BOOL:
+            return struct.pack("<B", 1 if bool(arr[0]) else 0), cursor + 1
+        return _little_endian_bytes(arr), cursor + 1
+    if vtype == GGUFValueType.ARRAY:
+        item_type = GGUFValueType(int(parts[cursor][0]))
+        count = int(parts[cursor + 1][0])
+        cursor += 2
+        out = bytearray(_u32(int(item_type)) + _u64(count))
+        for _ in range(count):
+            chunk, cursor = _encode_value(parts, cursor, item_type)
+            out += chunk
+        return bytes(out), cursor
+    msg = f"Unknown GGUF value type {vtype!r}"
+    raise UnsupportedModelError(msg)
+
+
+def encode_kv(field: ReaderField) -> bytes:
+    """Canonical encoding of one metadata entry: tag, name, type, value."""
+    if len(field.parts) < 3 or not field.types:
+        msg = f"Field {field.name!r} is not a metadata entry"
+        raise ValueError(msg)
+    name = field.name.encode("utf-8")
+    vtype = field.types[0]
+    payload, end = _encode_value(field.parts, 3, vtype)
+    if end != len(field.parts):
+        msg = f"Field {field.name!r}: consumed {end} of {len(field.parts)} parts"
+        raise UnsupportedModelError(msg)
+    return _KV_TAG + _u64(len(name)) + name + _u32(int(vtype)) + payload
+
+
+def encode_tensor_info(tensor: ReaderTensor) -> bytes:
+    """Canonical encoding of a tensor's descriptor: tag, name, dims in GGUF order, type.
+
+    The file offset is left out on purpose: it changes whenever anything before the tensor
+    changes, and it says nothing about the tensor.
+    """
+    name = tensor.name.encode("utf-8")
+    dims = [int(d) for d in tensor.shape]
+    return (
+        _TI_TAG
+        + _u64(len(name))
+        + name
+        + _u32(len(dims))
+        + b"".join(_u64(d) for d in dims)
+        + _u32(int(tensor.tensor_type))
+    )
+
+
+def kv_digest(field: ReaderField) -> bytes:
+    return sha256(encode_kv(field)).digest()
+
+
+def tensor_info_digest(tensor: ReaderTensor) -> bytes:
+    return sha256(encode_tensor_info(tensor)).digest()
+
+
+def is_element_type(tensor: ReaderTensor) -> bool:
+    """Return whether the reader exposes the tensor with a real dtype (F32, F16, F64, I8..I64)."""
+    return tensor.data.dtype != np.uint8
+
+
+def tensor_data_digest(
+    tensor: ReaderTensor,
+    file_endianess: GGUFEndian,
+    chunk_size: int = CHUNK_SIZE,
+) -> bytes:
+    """SHA-256 of the tensor's stored bytes, normalized to little-endian for element types.
+
+    Quantized blocks mix scales and packed values, so their byte order cannot be normalized
+    without decoding the block layout. Big-endian quantized files are refused rather than
+    silently fingerprinted differently; convert them with llama.cpp's ``gguf-convert-endian``.
+    """
+    data = tensor.data
+    if is_element_type(tensor):
+        if data.dtype.byteorder == ">" or (data.dtype.byteorder == "=" and sys.byteorder == "big"):
+            data = data.astype(data.dtype.newbyteorder("<"))
+    elif file_endianess == GGUFEndian.BIG:
+        msg = (
+            f"Tensor {tensor.name!r} is {tensor.tensor_type.name} in a big-endian file; "
+            "convert the file to little-endian first (gguf-convert-endian)"
+        )
+        raise UnsupportedModelError(msg)
+
+    flat = np.ascontiguousarray(data).reshape(-1).view(np.uint8)
+    digest = sha256()
+    for start in range(0, flat.size, chunk_size):
+        digest.update(flat[start : start + chunk_size])
+    return digest.digest()
+
+
+def encode_weight(name: str, data_digest: bytes) -> bytes:
+    """Canonical encoding of one tensor's data under its name: tag, name, data digest.
+
+    Binding the name to the bytes is what makes swapping the data of two tensors with the
+    same shape and type show up in ``weights``.
+    """
+    raw = name.encode("utf-8")
+    return _WT_TAG + _u64(len(raw)) + raw + data_digest
+
+
+def weight_digest(name: str, data_digest: bytes) -> bytes:
+    return sha256(encode_weight(name, data_digest)).digest()
+
+
+def combine(digests: Iterable[bytes]) -> bytes:
+    """Hash a sequence of digests in the order given."""
+    return sha256(b"".join(digests)).digest()
+
+
+def overall_digest(kv: bytes, tensor_info: bytes, weights: bytes) -> bytes:
+    return sha256(SPEC_ID.encode("ascii") + b"\0" + kv + tensor_info + weights).digest()
+
+
+def sorted_by_name(names: Iterable[str]) -> list[str]:
+    """Names in byte-wise UTF-8 order, which is what the spec requires."""
+    return sorted(names, key=lambda s: s.encode("utf-8"))

ggufkit/cli.py

@@ -0,0 +1,80 @@
+"""Command-line entry point: ``ggufkit <command> ...``."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import re
+import sys
+from typing import TYPE_CHECKING
+
+from ggufkit import __version__
+from ggufkit import diff as diff_cmd
+from ggufkit import fingerprint as fingerprint_cmd
+from ggufkit import manifest as manifest_cmd
+from ggufkit import stitch as stitch_cmd
+from ggufkit import verify as verify_cmd
+from ggufkit import viz as viz_cmd
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+EXIT_OK = 0
+EXIT_MISMATCH = 1
+EXIT_ERROR = 2
+EXIT_BROKEN_PIPE = 141
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="ggufkit",
+        description="Fingerprint, verify and visualize GGUF models.",
+    )
+    parser.add_argument("--version", action="version", version=f"ggufkit {__version__}")
+    sub = parser.add_subparsers(dest="command", metavar="<command>")
+    fingerprint_cmd.add_parser(sub)
+    manifest_cmd.add_parser(sub)
+    verify_cmd.add_parser(sub)
+    diff_cmd.add_parser(sub)
+    stitch_cmd.add_parser(sub)
+    viz_cmd.add_parser(sub)
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    func = getattr(args, "func", None)
+    if func is None:
+        parser.print_help()
+        return EXIT_ERROR
+    try:
+        return int(func(args))
+    except BrokenPipeError:
+        # The reader went away (``ggufkit ... | head``): stop quietly, like other Unix tools.
+        return EXIT_BROKEN_PIPE
+    except (ValueError, OSError, re.error) as e:
+        # ValueError covers ggufkit's own errors (bad models, manifests, arguments).
+        print(f"error: {e}", file=sys.stderr)
+        return EXIT_ERROR
+    except KeyboardInterrupt:
+        print("interrupted", file=sys.stderr)
+        return 130
+
+
+def entry() -> None:  # pragma: no cover - exercised by the installed ``ggufkit`` script
+    """Console-script entry point: :func:`main`, plus a quiet exit when stdout is closed."""
+    try:
+        code = main()
+        sys.stdout.flush()
+    except BrokenPipeError:
+        code = EXIT_BROKEN_PIPE
+    if code == EXIT_BROKEN_PIPE:
+        # Point stdout at /dev/null so the interpreter's final flush cannot fail again.
+        devnull = os.open(os.devnull, os.O_WRONLY)
+        os.dup2(devnull, sys.stdout.fileno())
+    sys.exit(code)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    entry()

ggufkit/dequant.py

@@ -0,0 +1,70 @@
+"""Turn any tensor ggufkit can read into float32, reusing llama.cpp's own dequantizers."""
+
+from __future__ import annotations
+
+from functools import cache
+from typing import TYPE_CHECKING
+
+import numpy as np
+from gguf import GGMLQuantizationType, GGUFEndian, quants
+from gguf.constants import GGML_QUANT_SIZES
+
+from ggufkit.canon import UnsupportedModelError, is_element_type
+
+if TYPE_CHECKING:
+    from gguf.gguf_reader import ReaderTensor
+
+ELEMENT_TYPES = frozenset(
+    {
+        GGMLQuantizationType.F32,
+        GGMLQuantizationType.F16,
+        GGMLQuantizationType.F64,
+        GGMLQuantizationType.I8,
+        GGMLQuantizationType.I16,
+        GGMLQuantizationType.I32,
+        GGMLQuantizationType.I64,
+    }
+)
+
+
+@cache
+def can_dequantize(qtype: GGMLQuantizationType) -> bool:
+    """Whether the installed ``gguf`` package knows how to decode ``qtype``."""
+    if qtype in ELEMENT_TYPES:
+        return True
+    if qtype not in GGML_QUANT_SIZES:
+        return False
+    _block, type_size = GGML_QUANT_SIZES[qtype]
+    try:
+        quants.dequantize(np.zeros((1, type_size), dtype=np.uint8), qtype)
+    except NotImplementedError:
+        return False
+    except Exception:  # noqa: BLE001 - zero blocks are not always valid, but the path exists
+        return True
+    return True
+
+
+def to_f32(
+    tensor: ReaderTensor,
+    file_endianess: GGUFEndian = GGUFEndian.LITTLE,
+    rows: slice | None = None,
+) -> np.ndarray:
+    """Decode ``tensor`` (or a slice of its leading axis) to a float32 array.
+
+    The result has numpy shape, which is the reverse of the GGUF ``ne`` order: a
+    ``[n_embd, n_vocab]`` GGUF tensor comes back as ``(n_vocab, n_embd)``. Slicing by rows
+    keeps memory bounded on multi-gigabyte tensors: quantization blocks never span rows.
+    """
+    data = tensor.data if rows is None else tensor.data[rows]
+    if is_element_type(tensor):
+        return data.astype(np.float32, copy=False)
+    if file_endianess == GGUFEndian.BIG:
+        msg = (
+            f"Tensor {tensor.name!r} is {tensor.tensor_type.name} in a big-endian file; "
+            "convert the file to little-endian first (gguf-convert-endian)"
+        )
+        raise UnsupportedModelError(msg)
+    if not can_dequantize(tensor.tensor_type):
+        msg = f"The installed gguf package cannot dequantize {tensor.tensor_type.name}"
+        raise UnsupportedModelError(msg)
+    return quants.dequantize(data, tensor.tensor_type)