Last updated: 2026-06-12

Model Format & Loading

GGUF

Parse GGUF container files and expose the metadata needed by the loader.

The helpers in this module decode GGUF headers, metadata values, tensor offsets, and GGML quantization information without copying the whole file.

10 exports 15 methods src/model/gguf.zig

10 exports shown

constant

GGUF_MAGIC

pub const GGUF_MAGIC: u32 = 0x46554747

Little-endian magic value expected at the start of every GGUF file.

src/model/gguf.zig:10

enum

GGUFVersion

pub const GGUFVersion = enum(u32)

GGUF container versions recognized by the parser.

src/model/gguf.zig:13

enum

GGUFType

pub const GGUFType = enum(u32)

Primitive metadata value tags defined by the GGUF format.

src/model/gguf.zig:20

enum

GGMLType

pub const GGMLType = enum(u32)

GGML tensor storage and quantization formats referenced by GGUF tensors.

src/model/gguf.zig:38

Methods

method

GGMLType.blockSize

pub fn blockSize(self: GGMLType) u32

Return the number of tensor elements encoded by one storage block.

Parameters

self: GGML tensor format to inspect.

Returns

The number of logical elements represented by one block of this format.

Notes

Quantized formats pack many elements into one block, while plain scalar types return `1`.

src/model/gguf.zig:75

method

GGMLType.bytesPerBlock

pub fn bytesPerBlock(self: GGMLType) u32

Return the serialized byte width of one storage block.

Parameters

self: GGML tensor format to inspect.

Returns

The number of on-disk bytes consumed by one block of this format.

Notes

Use this together with `blockSize()` to convert element counts into tensor byte ranges.

src/model/gguf.zig:97

union

MetadataValue

pub const MetadataValue = union(enum)

Typed representation of a GGUF metadata value.

src/model/gguf.zig:126

Methods

method

MetadataValue.asString

pub fn asString(self: MetadataValue) ?[]const u8

Interpret the metadata value as a string slice when the stored type is `.string`.

Returns

The string contents, or `null` when the value is not a string.

src/model/gguf.zig:143

method

MetadataValue.asU32

pub fn asU32(self: MetadataValue) ?u32

Interpret the metadata value as an unsigned 32-bit integer when it fits.

Returns

A normalized `u32` or `null` when the stored value cannot be represented as one.

src/model/gguf.zig:152

method

MetadataValue.asU64

pub fn asU64(self: MetadataValue) ?u64

Interpret the metadata value as an unsigned 64-bit integer when it fits.

Returns

A normalized `u64` or `null` when the stored value cannot be represented as one.

src/model/gguf.zig:163

method

MetadataValue.asF32

pub fn asF32(self: MetadataValue) ?f32

Interpret the metadata value as a 32-bit floating-point number when possible.

Returns

An `f32` value or `null` when the stored value is not a floating-point type.

src/model/gguf.zig:174

method

MetadataValue.asBool

pub fn asBool(self: MetadataValue) ?bool

Interpret the metadata value as a boolean when possible.

Returns

A normalized `bool` or `null` when the stored value is not boolean-like.

src/model/gguf.zig:184

struct

TensorInfo

pub const TensorInfo = struct

Tensor descriptor read from the GGUF header for a single named weight tensor.

src/model/gguf.zig:196

Methods

method

TensorInfo.numElements

pub fn numElements(self: *const TensorInfo) u64

Multiply the active tensor dimensions to get the logical element count.

Parameters

self: Tensor descriptor to inspect.

Returns

The total number of logical elements across the first `n_dims` entries in `dims`.

src/model/gguf.zig:211

method

TensorInfo.sizeBytes

pub fn sizeBytes(self: *const TensorInfo) u64

Compute the serialized tensor byte size for the descriptor's GGML storage format.

Parameters

self: Tensor descriptor to inspect.

Returns

The number of bytes occupied by the tensor payload, rounded up to whole quantization blocks.

Notes

Quantized tensors round element counts up to a full block before multiplying by bytes-per-block.

src/model/gguf.zig:223

struct

GGUFFile

pub const GGUFFile = struct

Fully decoded GGUF file: header fields, key-value metadata, and tensor descriptor table.

src/model/gguf.zig:234

Methods

method

GGUFFile.deinit

pub fn deinit(self: *GGUFFile) void

Release metadata keys, metadata payloads, and tensor names owned by the parsed file.

Parameters

self: Parsed GGUF file to tear down in place.

src/model/gguf.zig:250

method

GGUFFile.getString

pub fn getString(self: *const GGUFFile, key: []const u8) ?[]const u8

Look up a metadata string value by key.

Parameters

self: Parsed GGUF file.
key: Metadata key to search for.

Returns

The stored string value when present and typed as `.string`.

src/model/gguf.zig:271

method

GGUFFile.getU32

pub fn getU32(self: *const GGUFFile, key: []const u8) ?u32

Look up a metadata value as `u32` when it can be normalized to that type.

Parameters

self: Parsed GGUF file.
key: Metadata key to search for.

Returns

The normalized integer value when present.

src/model/gguf.zig:280

method

GGUFFile.getF32

pub fn getF32(self: *const GGUFFile, key: []const u8) ?f32

Look up a metadata value as `f32` when it can be normalized to that type.

Parameters

self: Parsed GGUF file.
key: Metadata key to search for.

Returns

The normalized floating-point value when present.

src/model/gguf.zig:289

method

GGUFFile.getBool

pub fn getBool(self: *const GGUFFile, key: []const u8) ?bool

Look up a metadata value as `bool` when it can be normalized to that type.

Parameters

self: Parsed GGUF file.
key: Metadata key to search for.

Returns

The normalized boolean value when present.

src/model/gguf.zig:298

method

GGUFFile.findTensor

pub fn findTensor(self: *const GGUFFile, name: []const u8) ?*const TensorInfo

Find a tensor descriptor by name.

Parameters

self: Parsed GGUF file.
name: Tensor name to look up.

Returns

A pointer to the tensor descriptor when the tensor exists.

src/model/gguf.zig:307

struct

ParseOptions

pub const ParseOptions = struct

Optional flags that control GGUF parsing behavior.

src/model/gguf.zig:329

function

parse

pub fn parse(data: []const u8, allocator: std.mem.Allocator) !GGUFFile

Parse a GGUF file from a byte slice.

Parameters

data: Raw GGUF bytes, typically from a memory-mapped file.
allocator: Allocator used for metadata strings, arrays, and tensor descriptors.

Returns

A `GGUFFile` with all data heap-allocated; call `deinit` to free all owned memory.

src/model/gguf.zig:339

function

parseWithOptions

pub fn parseWithOptions(data: []const u8, allocator: std.mem.Allocator, options: ParseOptions) !GGUFFile

Parse a GGUF file from a byte slice with optional logging control.

Parameters

data: Raw GGUF bytes, typically from a memory-mapped file.
allocator: Allocator used for metadata keys, string values, array payloads, and tensor name copies.
options: Flags controlling parse-time side effects such as summary logging.

Returns

A `GGUFFile` whose string data is heap-allocated; call `deinit` to free all owned memory.

Notes

Returns `error.InvalidMagic` when the four-byte magic is wrong, or `error.UnknownMetadataType` for unrecognized type tags.

src/model/gguf.zig:349