pkg/gguf¶

GGUF format library for parsing, constructing, and serializing GGUF model files.

import "github.com/professor-moody/crucible/pkg/gguf"

Constants¶

Types¶

ValueType¶

type ValueType uint32

Enum for metadata value types in GGUF key-value pairs.

Methods¶

func (vt ValueType) String() string

Returns the human-readable name of the value type.

func ValueTypeSize(vt ValueType) int

Returns the byte size of a scalar value type. Returns -1 for ValueTypeArray and ValueTypeString.

GGMLType¶

type GGMLType uint32

Enum for tensor quantization types. See GGML Types for the full reference table.

GGMLTypeInfo¶

type GGMLTypeInfo struct {
    BlockSize int
    TypeSize  int
}

Describes the quantization block layout for a given GGMLType.

GGMLTypeInfoMap¶

var GGMLTypeInfoMap map[GGMLType]GGMLTypeInfo

Package-level map from GGMLType to its GGMLTypeInfo. Used for calculating tensor data sizes.

Header¶

type Header struct {
    Magic          [4]byte
    Version        uint32
    TensorCount    uint64
    MetadataKVCount uint64
}

The fixed-size header at the start of every GGUF file.

MetadataKV¶

type MetadataKV struct {
    Key       string
    ValueType ValueType
    Value     interface{}
}

A single key-value pair from the GGUF metadata section. Value holds the decoded value whose concrete type depends on ValueType.

ArrayValue¶

type ArrayValue struct {
    ElemType ValueType
    Data     []interface{}
}

Represents a GGUF array metadata value. All elements share the same ElemType.

TensorInfo¶

type TensorInfo struct {
    Name   string
    NDims  uint32
    Dims   []uint64
    Type   GGMLType
    Offset uint64
}

Describes a single tensor's layout within the GGUF file.

Methods¶

func (t *TensorInfo) NElements() uint64

Returns the product of all dimensions (total element count).

File¶

type File struct {
    Header
    Metadata   []MetadataKV
    Tensors    []TensorInfo
    TensorData []byte
    Alignment  uint64
}

In-memory representation of a complete GGUF file.

Methods¶

func (f *File) GetAlignment() uint64

Returns the file's alignment value. Falls back to DefaultAlignment (32) if not set in metadata.

func (f *File) SyncCounts()

Updates Header.TensorCount and Header.MetadataKVCount to match the actual lengths of Tensors and Metadata slices.

Functions¶

NewFile¶

func NewFile() *File

Returns a minimal valid GGUF file with correct magic, current version, default alignment, and empty metadata/tensor slices.

Marshal¶

func Marshal(f *File) ([]byte, error)

Serializes a File to GGUF binary format with proper alignment padding.

MarshalRaw¶

func MarshalRaw(f *File, skipPadding bool) ([]byte, error)

Serializes a File with explicit control over alignment padding. When skipPadding is true, no padding bytes are inserted between the metadata section and tensor data.

Unmarshal¶

func Unmarshal(data []byte) (*File, error)

Parses a byte slice into a File. Returns an error if the magic bytes are invalid, the version is unsupported, or the data is truncated.

TensorDataSize¶

func TensorDataSize(nElements uint64, typ GGMLType) (uint64, error)

Calculates the byte size required for tensor data:

size = ceil(nElements / blockSize) * typeSize

Returns an error if typ is not in GGMLTypeInfoMap.

NewReader¶

func NewReader(r io.Reader) *Reader

Returns a streaming GGUF reader that wraps an io.Reader.

NewWriter¶

func NewWriter(w io.Writer) *Writer

Returns a streaming GGUF writer that wraps an io.Writer.