# gizlang:gguf

GGUF files, llama.cpp's model format. A file is the magic "GGUF", a version (2 or 3), the counts of tensors and of metadata values, the metadata (typed key-value pairs: the architecture, its sizes, the tokenizer), the tensors' names, shapes, GGML types and offsets, then their data from an aligned start. A reader takes the header alone; the tensors are Stored (gizlang:safetensors), whose reads decode the GGML block types. The Hugging Face view (config, tokenizer, tensors by their Hugging Face names) lets a model converter take a GGUF file as it takes a model folder.

```gizlang
import * as Gguf from "gizlang:gguf";
```

## Types

### `Gguf`

```gizlang
type Gguf = { path: string; values: Map<string, JsonValue>; tensors: Vec<Stored>; }
```

A GGUF file's header: its metadata values by key and its tensors (GGUF names, shapes row-major as Hugging Face
writes them, dtypes by GGML type name: "F32", "F16", "BF16", "Q8_0", "Q4_K", ...).

- `path`: `string`
- `values`: `_gizlang_sdk_collections.Map<string, gizlang_json.Json>`
- `tensors`: `Vec<gizlang_safetensors.Stored>`

## Functions

### `read`

```gizlang
function read(sys: System, path: string): Gguf throws string
```

The header of the GGUF file at `path`.

Effects: fail, io.

## Methods

### `Gguf.value`

```gizlang
function Gguf.value(self: Gguf, key: string): JsonValue
```

The metadata value `key` (null when the file has none).

Effects: fail.

### `Gguf.arch`

```gizlang
function Gguf.arch(self: Gguf): string
```

general.architecture: "llama", "qwen2", "qwen3", ...

Effects: fail.

### `Gguf.hfNamed`

```gizlang
function Gguf.hfNamed(self: Gguf): bool
```

Whether the file keeps the Hugging Face names of its tensors (DeepBeepMeep's files): none has a GGML name. Its
config and tokenizer are then not in its metadata.

Effects: fail.

### `Gguf.hfTensors`

```gizlang
function Gguf.hfTensors(self: Gguf): Vec<Stored> throws string
```

The tensors with the Hugging Face names of the architecture's model (Qwen2, Qwen3, Llama), in the Hugging Face row
order: llama.cpp writes the q and k rows of a Llama head in pairs of rotary partners, which a read takes back to
the head's two halves (Stored.interleaved).

Effects: fail.

### `Gguf.config`

```gizlang
function Gguf.config(self: Gguf, sys: System): JsonValue throws string
```

The model's config.json: the architecture's sizes from the metadata. rope_freqs.weight (Llama 3's rotary factors)
becomes `rope_factors`, each inverse frequency's divisor.

Effects: fail, io.

### `Gguf.tokenizer`

```gizlang
function Gguf.tokenizer(self: Gguf): JsonValue throws string
```

The tokenizer.json of a byte-level BPE vocabulary (tokenizer.ggml.model "gpt2") as Hugging Face writes it for the
pre-tokenizer named: "qwen2" (NFC first) or "llama-bpe" (Llama 3: the begin-of-text token first). Control and
user-defined tokens are added tokens; control ones are special.

Effects: fail.

### `Gguf.tokenizerConfig`

```gizlang
function Gguf.tokenizerConfig(self: Gguf): JsonValue
```

tokenizer_config.json: the chat template and the end-of-text and begin-of-text tokens.

Effects: fail.

### `Gguf.generationConfig`

```gizlang
function Gguf.generationConfig(self: Gguf): JsonValue
```

generation_config.json: the end-of-text token.

Effects: fail.