Documentation
¶
Overview ¶
Package gguf reads the metadata header of a GGUF model file safely.
GGUF is the single-file format local model runtimes load. Its parser is a real code-execution surface: malformed files have repeatedly exploited the C parsers in popular runtimes. This reader exists so the metadata a downloaded model carries, above all its embedded chat template, can be inspected and overridden in memory-safe Go before the file is ever handed to a runtime, rather than trusting that runtime's parser to read it. It reads only the header and metadata, never the tensor data, and is hardened against hostile input: every length and count is bounded, so a malicious file is rejected rather than exhausting memory or looping without end.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrNotGGUF = errors.New("gguf: not a GGUF file")
ErrNotGGUF is returned when the data does not begin with the GGUF magic, so a caller can tell "this is not a GGUF file" apart from "this GGUF file is malformed".
Functions ¶
This section is empty.
Types ¶
type ChatTemplateDecision ¶
type ChatTemplateDecision struct {
// Template is the template to run with. It is always the caller's trusted
// template, never the model's, so the prompt contract cannot be set by the model.
Template string
// ModelSupplied reports that the model embedded its own chat template. That
// template is ignored for the contract; the field lets a caller log or refuse a
// model that ships an unexpected template.
ModelSupplied bool
}
ChatTemplateDecision is the outcome of choosing the chat template to run a model with: the template to actually use, and whether the model tried to supply its own.
func ChooseChatTemplate ¶
func ChooseChatTemplate(meta *Metadata, trusted string) ChatTemplateDecision
ChooseChatTemplate decides the chat template to run a model with. It never returns the model's embedded template for use: a hostile GGUF can embed a template that rewrites the prompt contract to inject instructions at inference, so the contract is always the caller's trusted template. The decision reports whether the model tried to supply one, so a caller can record or refuse that.
type Metadata ¶
type Metadata struct {
Version uint32
// contains filtered or unexported fields
}
Metadata is the string-valued metadata read from a GGUF header. Only string values are retained, since the security-relevant fields (the chat template, the architecture, the name) are strings; numeric and array values are validated and skipped, not stored.
func ReadMetadata ¶
ReadMetadata reads the GGUF header and metadata from r, stopping before the tensor data. It returns ErrNotGGUF if the magic does not match, and a descriptive error if the header is malformed or exceeds the safety bounds.
func (*Metadata) Architecture ¶
Architecture returns the model architecture label (e.g. "llama"), or "" if absent.
func (*Metadata) ChatTemplate ¶
ChatTemplate returns the model-embedded chat template, if the file carries one.
The returned value is UNTRUSTED: a hostile model can embed a template that rewrites the prompt contract to inject instructions at inference. Do not feed it to a prompt. Use ChooseChatTemplate to decide what template to actually run with.
Source Files