GGUF Binary Format Specification¶

pub const GGUFHeader = struct {
    magic: u32,
    version: u32,
    tensor_count: u64,
    metadata_kv_count: u64,

    pub fn validate(self: GGUFHeader) !void {
        if (self.magic != GGUF_MAGIC) return error.InvalidGGUFMagic;
        if (self.version != GGUF_VERSION) return error.UnsupportedGGUFVersion;
    }
};

pub const GGUFTensorInfo = struct {
    name: []const u8,
    n_dims: u32,
    dimensions: []u64,
    type: GGMLType,
    offset: u64,

    pub fn elementCount(self: GGUFTensorInfo) u64 {
        var count: u64 = 1;
        for (self.dimensions) |dim| count *= dim;
        return count;
    }

    pub fn sizeInBytes(self: GGUFTensorInfo) u64 {
        const elements = self.elementCount();
        const block_size = self.type.blockSize();
        const type_size = self.type.typeSize();
        if (block_size == 1) return elements * type_size;
        return ((elements + block_size - 1) / block_size) * type_size;
    }
};

pub const GGUFType = enum(u32) {
    uint8   = 0,
    int8    = 1,
    uint16  = 2,
    int16   = 3,
    uint32  = 4,
    int32   = 5,
    float32 = 6,
    bool    = 7,
    string  = 8,
    array   = 9,
    uint64  = 10,
    int64   = 11,
    float64 = 12,
};

pub const GGUFReader = struct {
    file: std.fs.File,
    allocator: std.mem.Allocator,

    pub fn init(file: std.fs.File, allocator: std.mem.Allocator) GGUFReader {
        return GGUFReader{ .file = file, .allocator = allocator };
    }

    pub fn readFile(self: *GGUFReader) !GGUFFile {
        var gguf = GGUFFile.init(self.allocator);
        errdefer gguf.deinit();

        gguf.file_size = (try self.file.stat()).size;
        try self.file.seekTo(0);

        gguf.header = try self.readHeader();
        try gguf.header.validate();

        try self.readMetadata(&gguf);
        try self.readTensorInfo(&gguf);

        // Align to 32-byte boundary for tensor data
        const current_pos = try self.file.getPos();
        gguf.data_offset = std.mem.alignForward(u64, current_pos, 32);

        return gguf;
    }
};

fn readHeader(self: *GGUFReader) !GGUFHeader {
    const reader = self.file.reader();
    return GGUFHeader{
        .magic            = try reader.readInt(u32, .little),
        .version          = try reader.readInt(u32, .little),
        .tensor_count     = try reader.readInt(u64, .little),
        .metadata_kv_count = try reader.readInt(u64, .little),
    };
}

fn readValue(self: *GGUFReader, value_type: GGUFType) !GGUFValue {
    const reader = self.file.reader();
    return switch (value_type) {
        .uint8   => GGUFValue{ .uint8   = try reader.readInt(u8, .little) },
        .int32   => GGUFValue{ .int32   = try reader.readInt(i32, .little) },
        .float32 => GGUFValue{ .float32 = @bitCast(try reader.readInt(u32, .little)) },
        .string  => GGUFValue{ .string  = try self.readString() },
        .array   => blk: {
            const arr_type = @as(GGUFType, @enumFromInt(try reader.readInt(u32, .little)));
            const arr_len  = try reader.readInt(u64, .little);
            const elem_size = arr_type.size() orelse return error.UnsupportedArrayType;
            const data = try self.allocator.alloc(u8, arr_len * elem_size);
            _ = try reader.readAll(data);
            break :blk GGUFValue{ .array = .{ .type = arr_type, .len = arr_len, .data = data } };
        },
        // ... remaining types ...
    };
}

pub fn readTensorData(self: *GGUFReader, gguf: *GGUFFile,
                      tensor_info: *GGUFTensorInfo, allocator: std.mem.Allocator) ![]u8 {
    const size = tensor_info.sizeInBytes();
    const data = try allocator.alloc(u8, size);
    try self.file.seekTo(gguf.data_offset + tensor_info.offset);
    _ = try self.file.readAll(data);
    return data;
}

pub const GGUFModelLoader = struct {
    gguf: GGUFFile,
    reader: GGUFReader,
    allocator: std.mem.Allocator,

    pub fn init(file_path: []const u8, allocator: std.mem.Allocator) !GGUFModelLoader {
        const file = try std.fs.cwd().openFile(file_path, .{});
        var reader = GGUFReader.init(file, allocator);
        const gguf = try reader.readFile();
        return GGUFModelLoader{ .gguf = gguf, .reader = reader, .allocator = allocator };
    }

    pub fn loadTensor(self: *GGUFModelLoader, name: []const u8) !Tensor {
        const info = self.gguf.getTensor(name) orelse return error.TensorNotFound;
        const raw = try self.reader.readTensorData(&self.gguf, info, self.allocator);
        defer self.allocator.free(raw);
        // ... dequantize based on info.type ...
    }
};