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 0 for ValueTypeArray, ValueTypeString, and unknown values.

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{}
    KeyLenOverride *uint64
    ValLenOverride *uint64
}

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{}
    CountOverride *uint64
}

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            Header
    Metadata          []MetadataKV
    Tensors           []TensorInfo
    TensorData        []byte
    Alignment         uint64
    TruncationWarning string
}

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.

func (f *File) Clone() *File

Returns a deep copy suitable for isolated mutation.

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.

Tensor-data truncation that can be bounded safely may instead be surfaced through File.TruncationWarning; callers that need complete payloads must check it.

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.