Implementation:Ggml org Llama cpp Android GgufMetadataReaderImpl

Knowledge Sources	Ggml_org_Llama_cpp
Domains	Android, GGUF
Last Updated	2026-02-15 00:00 GMT

Overview

Pure Kotlin implementation of the GGUF binary format parser that reads and extracts structured metadata from GGUF model files without requiring native code.

Description

Implements `GgufMetadataReader` by reading the GGUF binary header (magic bytes "GGUF", version, tensor count, KV count) from an `InputStream`. Defines a `MetadataType` enum mapping all 13 GGUF value type codes and a `MetadataValue` sealed class hierarchy for type-safe representation of each type (UInt8, Int8, UInt16, Int16, UInt32, Int32, Float32, Bool, StringVal, ArrayVal, UInt64, Int64, Float64). Reads key-value pairs by parsing length-prefixed strings and typed values, with configurable key skipping and array summarization for large entries.

Usage

Use this reader when you need to inspect GGUF model metadata entirely in Kotlin/JVM without loading the model into llama.cpp, enabling pre-load validation, model information display, and format verification on the managed code side of an Android application.

Code Reference

Source Location

• Repository: Ggml_org_Llama_cpp
• File: examples/llama.android/lib/src/main/java/com/arm/aichat/internal/gguf/GgufMetadataReaderImpl.kt
• Lines: 1-590

Signature

internal class GgufMetadataReaderImpl(
    private val skipKeys: Set<String>,
    private val arraySummariseThreshold: Int,
) : GgufMetadataReader {

    enum class MetadataType(val code: Int) {
        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);
        companion object {
            fun fromCode(code: Int): MetadataType
        }
    }

    sealed class MetadataValue {
        data class UInt8(val value: UByte) : MetadataValue()
        data class Int8(val value: Byte) : MetadataValue()
        data class UInt16(val value: UShort) : MetadataValue()
        data class Int16(val value: Short) : MetadataValue()
        data class UInt32(val value: UInt) : MetadataValue()
        data class Int32(val value: Int) : MetadataValue()
        data class Float32(val value: Float) : MetadataValue()
        data class Bool(val value: Boolean) : MetadataValue()
        data class StringVal(val value: String) : MetadataValue()
        data class ArrayVal(val elementType: MetadataType, val elements: List<MetadataValue>) : MetadataValue()
        data class UInt64(val value: ULong) : MetadataValue()
        data class Int64(val value: Long) : MetadataValue()
        data class Float64(val value: Double) : MetadataValue()
    }

    override suspend fun ensureSourceFileFormat(file: File): Boolean
    override suspend fun readMetadata(uri: Uri, context: Context): GgufMetadata
}

Import

import android.content.Context
import android.net.Uri
import com.arm.aichat.gguf.GgufMetadata
import com.arm.aichat.gguf.GgufMetadataReader
import com.arm.aichat.gguf.InvalidFileFormatException
import java.io.File
import java.io.IOException
import java.io.InputStream

I/O Contract

Inputs

Name	Type	Required	Description
file	File	Yes	File object pointing to the GGUF model file for format validation
uri	Uri	Yes	Content URI to the GGUF file for full metadata reading
context	Context	Yes	Android Context for obtaining ContentResolver to read from URI
skipKeys	Set<String>	No	Set of metadata key names to skip during parsing
arraySummariseThreshold	Int	No	Threshold above which array values are summarized instead of fully read

Outputs

Name	Type	Description
isValid	Boolean	Whether the file has valid GGUF magic bytes (from ensureSourceFileFormat)
metadata	GgufMetadata	Structured metadata object containing all parsed key-value pairs, tensor count, and version info

Usage Examples

// Create a metadata reader that skips tokenizer keys and summarizes large arrays
val reader = GgufMetadataReaderImpl(
    skipKeys = setOf("tokenizer.ggml.tokens", "tokenizer.ggml.scores"),
    arraySummariseThreshold = 100
)

// Validate file format before loading
val file = File("/sdcard/models/llama-7b.gguf")
val isValid = reader.ensureSourceFileFormat(file)

// Read full metadata from a content URI
if (isValid) {
    val metadata = reader.readMetadata(uri, context)
    println("Model architecture: ${metadata.architecture}")
    println("Tensor count: ${metadata.tensorCount}")
}

Related Pages

• Principle:Ggml_org_Llama_cpp_GGUF_Format