#soehi/gguf

#Install

moon add soehi/gguf

#Usage

fn inspect(buf : Bytes) -> Unit {
  // parse with full metadata when you need the vocabulary; plain `parse`
  // summarizes large arrays (a 100k-entry token list) instead of materializing.
  let file = match @gguf.parse(buf) {
    Ok(f) => f
    Err(e) => {
      println("parse failed: \{e.message()}")
      return
    }
  }
  // Metadata is typed, by key: get_string / get_int / get_double / get.
  let arch = file.get_string("general.architecture")   // String?
  println(arch.unwrap_or("unknown"))

  // Tensor lookup is an Option, not a Result.
  let idx = match file.index_of_tensor("blk.0.attn_q.weight") {
    Some(i) => i
    None => {
      println("no such tensor")
      return
    }
  }
  let info = file.tensors[idx]
  println("dims: \{info.n_dims()}, dequantizable: \{info.is_dequantizable()}")

  // Raw payload (owned copy), or decoded floats. Both are Result; an
  // unsupported storage type is an Err that names the type.
  let raw = match file.tensor_bytes(idx) {
    Ok(b) => b
    Err(e) => {
      println("cannot read payload: \{e.message()}")
      return
    }
  }
  println("payload bytes: \{raw.length()}")
  let vals = match file.dequant_tensor(idx) {
    Ok(v) => v
    Err(e) => {
      println("cannot dequantize: \{e.message()}")
      return
    }
  }
  println("decoded floats: \{vals.length()}")
}

• index_of_tensor returns Option[Int], while tensor_bytes, tensor_span and dequant_tensor return Result[_, GgufError]. The error carries the file offset where the problem was found.
• tensor_span gives offsets into the buffer you already hold, so a caller that keeps buf alive can avoid the copy tensor_bytes makes.
• dequant_tensor returns Err (not a trap) for a storage type this build does not decode, naming the type; is_dequantizable() on TensorInfo asks the same question ahead of time.

#Packages

#Scope

#Non-goals

• Writing GGUF. This module does not produce files. Serializing a container needs a policy for alignment and metadata ordering that the reader cannot infer.
• Quantization. Only dequantization. Producing q4_0/q5_0 blocks means choosing a quantization objective, which is a different problem with a different set of tradeoffs.
• Inference. No matvec, no attention, no sampling. The consumer supplies the arithmetic; this module stops at "give me the numbers for this block".
• Tokenizer, model config, or engine glue. Those live in the MoonLM module and are what depend on this one, not the other way round.

#Verification

• Golden vectors per block type, at 1e-6 relative tolerance, on both targets.
• Cross-checked against llama.cpp's own Python gguf reader on real models (header, all metadata, the complete tensor directory, and decoded values).
• Malformed-input coverage: truncation at many offsets, byte-level mutation, and one hand-aimed case per parser guard.

#Regenerating the test fixtures

pip install numpy
python tools/gen_fixtures.py

#Maintenance

• Semver. Breaking changes bump the major version. Within a major version, new dequantizable types and new metadata helpers are additive and land in a minor; bug fixes and error-message improvements land in a patch.
• Issues. Please file them in the gguf repository.
• License. Apache-2.0, same as MoonLM.