mll

package module
v0.0.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 11, 2026 License: Apache-2.0 Imports: 11 Imported by: 0

README

MLL — Machine Learning Language

Standalone data interchange format for ML artifacts. See docs/specs/2026-04-10-mll-design.md in the gamejam2026 repo for the full spec.

Pronounced "mill." LLM backwards, by design.

Status

v1.0 binary core under construction. See implementation plan.

License

MLL is open source under the Apache License, Version 2.0. See LICENSE and NOTICE.

Documentation

Index

Constants

View Source 
const (
	StorageClassActivation uint8 = 0
	StorageClassWorkspace  uint8 = 1
	StorageClassIO         uint8 = 2
)

Storage classes for buffer declarations.

View Source 
const (
	DimBoundDynamic uint8 = 0 // bound later, at entry or load time
	DimBoundStatic  uint8 = 1 // value is fixed
)

DimBound kinds for a dimension declaration.

View Source 
const (
	EntryKindFunction uint8 = 0
	EntryKindPipeline uint8 = 1
	EntryKindKernel   uint8 = 2
)

Entry point kinds.

View Source 
const (
	SectionFlagRequired   uint16 = 1 << 0
	SectionFlagSkippable  uint16 = 1 << 1
	SectionFlagExternal   uint16 = 1 << 2
	SectionFlagCompressed uint16 = 1 << 3
	SectionFlagAligned    uint16 = 1 << 4
	SectionFlagSchemaless uint16 = 1 << 5
)

SectionFlag values (u16 in directory entries).

View Source 
const (
	ResidencyDeviceResident uint8 = 0
	ResidencyHostPinned     uint8 = 1
	ResidencyHostShared     uint8 = 2
	ResidencyLazyStaged     uint8 = 3
)

Residency classes for MEMP entries.

View Source 
const (
	OptimizerAdamW uint8 = 0
	OptimizerSGD   uint8 = 1
	OptimizerLAMB  uint8 = 2
)

Optimizer kinds for OPTM.

View Source 
const (
	PlanStepKernel uint8 = 0
	PlanStepHostOp uint8 = 1
)

PlanStepKind identifies one plan step variant.

View Source 
const (
	SigAlgorithmNone    uint8 = 0
	SigAlgorithmEd25519 uint8 = 1
)

Signature algorithm identifiers.

View Source 
const (
	TypeKindTensor        uint8 = 1
	TypeKindKVCache       uint8 = 2
	TypeKindCandidatePack uint8 = 3
)

TypeKind identifies the shape of a TYPE section entry.

View Source 
const DirectoryEntrySize = 64

DirectoryEntrySize is the fixed size of one section directory entry in bytes.

View Source 
const (
	FileFlagHasSignature uint8 = 1 << 0
)

FileFlag values.

View Source 
const HeaderSize = 24

HeaderSize is the fixed size of the file header in bytes.

Variables

View Source 
var (
	TagHEAD = [4]byte{'H', 'E', 'A', 'D'}
	TagSTRG = [4]byte{'S', 'T', 'R', 'G'}
	TagENUM = [4]byte{'E', 'N', 'U', 'M'}
	TagDIMS = [4]byte{'D', 'I', 'M', 'S'}
	TagTYPE = [4]byte{'T', 'Y', 'P', 'E'}
	TagPARM = [4]byte{'P', 'A', 'R', 'M'}
	TagENTR = [4]byte{'E', 'N', 'T', 'R'}
	TagBUFF = [4]byte{'B', 'U', 'F', 'F'}
	TagKRNL = [4]byte{'K', 'R', 'N', 'L'}
	TagPLAN = [4]byte{'P', 'L', 'A', 'N'}
	TagMEMP = [4]byte{'M', 'E', 'M', 'P'}
	TagTNSR = [4]byte{'T', 'N', 'S', 'R'}
	TagOPTM = [4]byte{'O', 'P', 'T', 'M'}
	TagSCHM = [4]byte{'S', 'C', 'H', 'M'}
	TagSGNM = [4]byte{'S', 'G', 'N', 'M'}
)

Section tags for the core set.

View Source 
var Magic = [4]byte{'M', 'L', 'L', 0}

Magic is the four-byte identifier at the start of every MLL binary file.

View Source 
var V1_0 = Version{Major: 1, Minor: 0}

V1_0 is MLL format version 1.0.

Functions

func Float64bits 

func Float64bits(f float64) uint64

Float64bits returns the IEEE 754 binary representation of f.

func Float64frombits 

func Float64frombits(b uint64) float64

Float64frombits returns the floating-point number corresponding to the IEEE 754 binary representation b.

func IsCustomTag 

func IsCustomTag(tag [4]byte) bool

IsCustomTag reports whether a tag is in the custom chunk tag space (X***).

func IsForbidden 

func IsForbidden(p Profile, tag [4]byte) bool

IsForbidden reports whether a section tag is forbidden for the given profile.

func IsRequired 

func IsRequired(p Profile, tag [4]byte) bool

IsRequired reports whether a section tag is required for the given profile.

func ReadUint16LE 

func ReadUint16LE(b []byte) (uint16, error)

ReadUint16LE reads a uint16 from the first 2 bytes of b.

func ReadUint32LE 

func ReadUint32LE(b []byte) (uint32, error)

ReadUint32LE reads a uint32 from the first 4 bytes of b.

func ReadUint64LE 

func ReadUint64LE(b []byte) (uint64, error)

ReadUint64LE reads a uint64 from the first 8 bytes of b.

func ReadUvarint 

func ReadUvarint(b []byte) (uint64, int, error)

ReadUvarint reads an LEB128 unsigned varint from b. Returns the value, the number of bytes consumed, and any error.

func ReadVarint 

func ReadVarint(b []byte) (int64, int, error)

ReadVarint reads a zigzag-LEB128 signed varint from b.

func ValidateDimDepth 

func ValidateDimDepth(d Dimension) error

ValidateDimDepth reports an error if the dimension's expression tree exceeds the v1.0 depth limit of 8.

func WriteDimension 

func WriteDimension(w io.Writer, d Dimension) error

WriteDimension encodes a dimension to w using the canonical binary form. Format: 

u8 kind
kind == literal:  varint i64 value
kind == symbol:   u32 string_table_idx
kind == expr:     u8 op + Dimension(left) + Dimension(right)

The dimension is validated for depth before normalization, then normalized before encoding. This enforces the canonicalization rule that sealed/weights-only section bodies contain normalized dim expressions, without requiring every section builder to remember to call NormalizeDim. The function validates the input depth against the limit of 8.

func WriteDimensionWithIndex 

func WriteDimensionWithIndex(w io.Writer, d Dimension, stringIndex map[string]uint32) error

WriteDimensionWithIndex is like WriteDimension but takes a string-table index map so symbol-based commutative reordering uses the interned indices rather than lexicographic symbol names. Callers who have finalized the string table pass their index map; callers who haven't pass nil.

func WriteDirectory 

func WriteDirectory(w io.Writer, entries []DirectoryEntry) error

WriteDirectory writes a slice of directory entries to w.

func WriteShape 

func WriteShape(w io.Writer, shape []Dimension) error

WriteShape encodes a shape (sequence of dimensions) to w. Format: u32 rank + Dimension[rank].

func WriteToBytes 

func WriteToBytes(profile Profile, version Version, sections []SectionInput, opts ...WriterOption) ([]byte, error)

WriteToBytes is a convenience that writes to an in-memory buffer and returns the full file bytes.

func WriteUint16LE 

func WriteUint16LE(w io.Writer, v uint16) error

WriteUint16LE writes a uint16 to w in little-endian order.

func WriteUint32LE 

func WriteUint32LE(w io.Writer, v uint32) error

WriteUint32LE writes a uint32 to w in little-endian order.

func WriteUint64LE 

func WriteUint64LE(w io.Writer, v uint64) error

WriteUint64LE writes a uint64 to w in little-endian order.

func WriteUvarint 

func WriteUvarint(w io.Writer, v uint64) error

WriteUvarint writes v to w as an LEB128 unsigned varint.

func WriteVarint 

func WriteVarint(w io.Writer, v int64) error

WriteVarint writes v to w as a zigzag-LEB128 signed varint.

Types

type Bool 

type Bool bool

Typed scalar primitives. Go types directly model the MLL abstract data model.

type BuffBuilder 

type BuffBuilder struct {
	// contains filtered or unexported fields
}

func NewBuffBuilder 

func NewBuffBuilder() *BuffBuilder

func (*BuffBuilder) Add 

func (b *BuffBuilder) Add(d BuffDecl)

func (*BuffBuilder) Write 

func (b *BuffBuilder) Write(w io.Writer) error

Write encodes the BUFF section body. Layout: u32 count + repeat{ u32 name, Ref(8), u8 storage_class }

type BuffDecl 

type BuffDecl struct {
	NameIdx      uint32
	TypeRef      Ref
	StorageClass uint8
}

BuffDecl is one entry in the BUFF section.

type BuffSection 

type BuffSection struct {
	Decls []BuffDecl
}

func ReadBuffSection 

func ReadBuffSection(data []byte) (BuffSection, error)

type Bytes 

type Bytes []byte

Bytes is a raw byte blob with no encoding assumptions.

type CandidatePackType 

type CandidatePackType struct {
	Rank int // 2 or 3
}

CandidatePackType describes a retrieval candidate pack.

type Checkpoint 

type Checkpoint struct {
	// contains filtered or unexported fields
}

Checkpoint is a mutable MLL file of profile ProfileCheckpoint. Subsequent Save() calls rewrite via full sibling file + rename in v1.0.

Generation counter increments on every save and is stored in HEAD.Generation. Callers set the HEAD section via SetSection with any Generation value they like; Save() is responsible for re-encoding HEAD with the current generation counter before writing, so on-disk and in-memory values always agree.

func NewCheckpoint 

func NewCheckpoint(path string, opts CheckpointOptions) (*Checkpoint, error)

NewCheckpoint creates a new checkpoint writer that will emit to path. If path exists, opens it and reads the existing generation.

func (*Checkpoint) Close 

func (c *Checkpoint) Close() error

Close releases any resources held by the checkpoint. In v1.0 this is a no-op because Save closes its own file handle.

func (*Checkpoint) Generation 

func (c *Checkpoint) Generation() uint64

Generation returns the current generation counter (monotonically incremented by Save).

func (*Checkpoint) Save 

func (c *Checkpoint) Save() error

Save writes the checkpoint to disk via atomic sibling-file-plus-rename. Bumps the generation counter and re-encodes HEAD with the new value so on-disk HEAD.Generation matches Generation(). The in-memory counter is only advanced after the atomic rename succeeds.

func (*Checkpoint) SetSection 

func (c *Checkpoint) SetSection(s SectionInput)

SetSection stores a section to be written on the next Save. The HEAD section's Generation field is overwritten by Save(); callers do not need to track it manually.

type CheckpointOptions 

type CheckpointOptions struct {
	// SlackBytes is the number of padding bytes reserved at the end of each
	// rewritable section (OPTM, TNSR). Reserved for a v1.x in-place rewrite
	// optimization; v1.0 always does full-rewrite-and-rename.
	SlackBytes uint64

	// SkipRequirementCheck disables the profile required-section check on
	// the underlying Writer. Intended for unit tests that exercise
	// checkpoint save/rewrite bookkeeping without constructing every
	// section type the checkpoint profile requires. Production callers
	// should leave this false.
	SkipRequirementCheck bool
}

CheckpointOptions configures a checkpoint writer.

type CustomChunk 

type CustomChunk struct {
	Tag  [4]byte
	Body []byte
}

CustomChunk carries an X*** section tag + opaque body bytes. Full MCD handling lands in Plan 2; Plan 1 just preserves the bytes.

type DType 

type DType uint8

DType is the element type of a tensor. 

const (
	DTypeInvalid DType = 0
	DTypeI8      DType = 1
	DTypeI16     DType = 2
	DTypeI32     DType = 3
	DTypeI64     DType = 4
	DTypeU8      DType = 5
	DTypeU16     DType = 6
	DTypeU32     DType = 7
	DTypeU64     DType = 8
	DTypeF16     DType = 9
	DTypeF32     DType = 10
	DTypeF64     DType = 11
	DTypeQ4      DType = 12
	DTypeQ8      DType = 13
)

func (DType) ElementSize 

func (d DType) ElementSize() int

ElementSize returns the number of bytes per element for standard dtypes. Quantized types (Q4, Q8) require higher-level inspection to compute byte count.

type Digest 

type Digest [32]byte

Digest is a BLAKE3-256 hash (32 bytes).

func HashBytes 

func HashBytes(data []byte) Digest

HashBytes computes the BLAKE3-256 hash of the given bytes.

func SealedContentHash 

func SealedContentHash(version Version, profile Profile, fileFlags uint8, entries []DirectoryEntry) Digest

SealedContentHash computes the BLAKE3-256 content hash for a sealed or weights-only artifact per spec §Canonicalization / Sealed file content hash.

The pre-image byte sequence is fixed-width and endianness-unambiguous:

  • version: 2 bytes, [major, minor] (NOT little-endian u16 — explicit byte order)
  • profile: 1 byte
  • file flags with HAS_SIGNATURE forced to 0: 1 byte
  • for each directory entry in canonical order: tag: 4 bytes, raw flags: 2 bytes, little-endian u16 schema_version: 2 bytes, little-endian u16 digest: 32 bytes, raw

The pre-image deliberately uses [major, minor] byte order for the version, which differs from the on-disk little-endian u16 form (which stores bytes as [minor, major]). This is intentional and documented: the content hash operates on a semantic byte sequence, not a byte-by-byte copy of the file.

MinReaderMinor, file offsets, section sizes, total file size, padding bytes, reserved header bytes, and signature bytes are intentionally excluded. MinReaderMinor is a loader policy, not artifact content; the others are layout decisions that two conformant writers may make differently without changing what the artifact represents.

type DimDecl 

type DimDecl struct {
	NameIdx uint32 // string table index of the dim name
	Bound   uint8  // DimBoundDynamic | DimBoundStatic
	Value   int64  // meaningful when Bound == DimBoundStatic
}

DimDecl is one entry in the DIMS section.

type DimExpr 

type DimExpr struct {
	Op    DimOp
	Left  Dimension
	Right Dimension
}

DimExpr is a binary expression tree over dimensions. Left and Right are operand dimensions (which may themselves be expressions).

func NewDimExpr 

func NewDimExpr(op DimOp, left, right Dimension) *DimExpr

NewDimExpr constructs an expression with two leaf-style operands.

func (*DimExpr) Depth 

func (e *DimExpr) Depth() int

Depth returns the maximum depth of the expression tree rooted here. A leaf (literal or symbol) has depth 1.

func (*DimExpr) Equal 

func (e *DimExpr) Equal(other *DimExpr) bool

Equal reports deep equality of two expressions.

func (*DimExpr) String 

func (e *DimExpr) String() string

String returns the canonical text form of the expression.

type DimKind 

type DimKind uint8

DimKind identifies the form of a Dimension. 

const (
	DimKindLiteral DimKind = 0
	DimKindSymbol  DimKind = 1
	DimKindExpr    DimKind = 2
)

type DimOp 

type DimOp uint8

DimOp is a dimension expression operator. 

const (
	DimOpAdd DimOp = 0
	DimOpSub DimOp = 1
	DimOpMul DimOp = 2
	DimOpDiv DimOp = 3
)

type Dimension 

type Dimension struct {
	Kind      DimKind
	Value     int64    // valid when Kind == DimKindLiteral
	Symbol    string   // valid when Kind == DimKindSymbol (Go-side name)
	SymbolIdx uint32   // valid when Kind == DimKindSymbol (string table index)
	Expr      *DimExpr // valid when Kind == DimKindExpr (defined in dim_expr.go)
}

Dimension is a first-class primitive representing a tensor dimension. It is either a literal integer, a symbolic reference to a named dim, or an expression tree over other dims.

func DimLiteral 

func DimLiteral(v int64) Dimension

DimLiteral constructs a literal dimension.

func DimSymbol 

func DimSymbol(name string) Dimension

DimSymbol constructs a symbolic dimension reference.

func NormalizeDim 

func NormalizeDim(d Dimension, stringIndex map[string]uint32) Dimension

NormalizeDim applies canonical normalization and returns the normalized dimension. Returns a new Dimension — crucially, if an inner expression folds to a pure literal, the parent sees it as a literal Kind, which is required for constant folding to propagate up the tree.

The stringIndex argument maps symbol names to STRG indices for commutative reordering; pass nil for lexicographic symbol ordering.

func ReadDimension 

func ReadDimension(b []byte) (Dimension, int, error)

ReadDimension decodes a dimension from b. Returns the dimension, the number of bytes consumed, and any error.

func ReadShape 

func ReadShape(b []byte) ([]Dimension, int, error)

ReadShape decodes a shape from b. Returns the shape, bytes consumed, and any error.

func (Dimension) String 

func (d Dimension) String() string

String returns the canonical text form of the dimension.

type DimsBuilder 

type DimsBuilder struct {
	// contains filtered or unexported fields
}

DimsBuilder accumulates dim declarations.

func NewDimsBuilder 

func NewDimsBuilder() *DimsBuilder

NewDimsBuilder returns an empty builder.

func (*DimsBuilder) Add 

func (b *DimsBuilder) Add(d DimDecl)

Add appends a dim declaration.

func (*DimsBuilder) Decls 

func (b *DimsBuilder) Decls() []DimDecl

Decls returns the current slice (read-only).

func (*DimsBuilder) Write 

func (b *DimsBuilder) Write(w io.Writer) error

Write encodes the DIMS section body. Layout: u32 count + repeat{ u32 name_idx, u8 bound, i64 value (always, ignored for dynamic) }

type DimsSection 

type DimsSection struct {
	Decls []DimDecl
}

DimsSection is the decoded form of the DIMS section.

func ReadDimsSection 

func ReadDimsSection(data []byte) (DimsSection, error)

ReadDimsSection decodes a DIMS section body.

type DirectoryEntry 

type DirectoryEntry struct {
	Tag           [4]byte
	Offset        uint64
	Size          uint64
	Digest        Digest
	Flags         uint16
	SchemaVersion uint16
}

DirectoryEntry describes one section in the MLL file directory.

func CanonicalSectionOrder 

func CanonicalSectionOrder(entries []DirectoryEntry, profile Profile) []DirectoryEntry

CanonicalSectionOrder returns the directory entries in canonical order for sealed and weights-only profiles. Core sections appear in the fixed order defined by coreSectionOrder; custom chunks (X*) sort lexicographically after SCHM and before SGNM. Checkpoint profile returns the input unchanged.

func ReadDirectory 

func ReadDirectory(b []byte, n uint32) ([]DirectoryEntry, error)

ReadDirectory reads n directory entries from b.

func ReadDirectoryEntry 

func ReadDirectoryEntry(b []byte) (DirectoryEntry, error)

ReadDirectoryEntry decodes one directory entry from the first DirectoryEntrySize bytes of b.

func (DirectoryEntry) Write 

func (e DirectoryEntry) Write(w io.Writer) error

Write encodes e to w as exactly DirectoryEntrySize bytes.

type EntrBuilder 

type EntrBuilder struct {
	// contains filtered or unexported fields
}

func NewEntrBuilder 

func NewEntrBuilder() *EntrBuilder

func (*EntrBuilder) Add 

func (b *EntrBuilder) Add(e EntryPoint)

func (*EntrBuilder) Write 

func (b *EntrBuilder) Write(w io.Writer) error

Write encodes the ENTR section body. Layout: u32 count + repeat{ u32 name, u8 kind, u32 in_count, ValueBinding[in], u32 out_count, ValueBinding[out] } ValueBinding: u32 name_idx + Ref(8) type_ref

type EntrSection 

type EntrSection struct {
	Entries []EntryPoint
}

EntrSection is the decoded form.

func ReadEntrSection 

func ReadEntrSection(data []byte) (EntrSection, error)

ReadEntrSection decodes an ENTR section body.

type EntryPoint 

type EntryPoint struct {
	NameIdx uint32
	Kind    uint8
	Inputs  []ValueBinding
	Outputs []ValueBinding
}

EntryPoint is one entry in the ENTR section.

type EnumDecl 

type EnumDecl struct {
	Name   string
	Values []string
}

EnumDecl declares a named enum type with its valid values.

func (EnumDecl) HasValue 

func (e EnumDecl) HasValue(v string) bool

HasValue reports whether the given value is valid for this enum.

type EnumSection 

type EnumSection struct {
	Enums []EnumSectionEntry
}

EnumSection is the ENUM section body.

func ReadEnumSection 

func ReadEnumSection(b []byte) (EnumSection, error)

ReadEnumSection decodes an ENUM section body.

func (EnumSection) Write 

func (e EnumSection) Write(w io.Writer) error

Write encodes the ENUM section body.

type EnumSectionEntry 

type EnumSectionEntry struct {
	Name   uint32
	Values []uint32
}

EnumSectionEntry is one enum declaration in the ENUM section. All fields are string table indices.

type EnumValue 

type EnumValue struct {
	Type  string // name of the enum type
	Value string // one of the declared values
}

EnumValue is an instance of an enum: a type name plus a chosen value.

type FileHeader 

type FileHeader struct {
	Version        Version
	Profile        Profile
	Flags          uint8
	TotalFileSize  uint64
	SectionCount   uint32
	MinReaderMinor uint8
}

FileHeader is the fixed 24-byte header of every MLL binary file.

func ReadHeader 

func ReadHeader(b []byte) (FileHeader, error)

ReadHeader parses an MLL file header from the first HeaderSize bytes of b.

func (FileHeader) Write 

func (h FileHeader) Write(w io.Writer) error

Write encodes the header to w. Always writes exactly HeaderSize bytes on success.

type Float16 

type Float16 uint16

Float16 stores a 16-bit IEEE 754 half-precision float as uint16 bits. Use F16FromFloat32 / F16ToFloat32 for conversions.

type Float32 

type Float32 float32

Typed scalar primitives. Go types directly model the MLL abstract data model.

type Float64 

type Float64 float64

Typed scalar primitives. Go types directly model the MLL abstract data model.

type Hasher 

type Hasher struct {
	// contains filtered or unexported fields
}

Hasher is an incremental BLAKE3-256 hasher.

func NewHasher 

func NewHasher() *Hasher

NewHasher returns a new BLAKE3-256 incremental hasher.

func (*Hasher) Reset 

func (h *Hasher) Reset()

Reset clears the hash state for reuse.

func (*Hasher) Sum 

func (h *Hasher) Sum() Digest

Sum finalizes the hash and returns the 32-byte digest.

func (*Hasher) Write 

func (h *Hasher) Write(p []byte) (int, error)

Write adds bytes to the hash state. Always returns nil error.

type HeadMetadataEntry 

type HeadMetadataEntry struct {
	Key       uint32 // string table index
	Kind      HeadValueKind
	Bool      bool
	I64       int64
	F64       float64
	StringIdx uint32
}

HeadMetadataEntry is one typed key-value in HEAD metadata.

type HeadSection 

type HeadSection struct {
	Name          uint32 // string table index (required)
	Description   uint32 // string table index (0 = absent)
	CreatedUnixMs int64
	Generation    uint64 // checkpoint only; zero for sealed and weights-only
	Backends      []uint16
	Capabilities  []uint32
	Metadata      []HeadMetadataEntry
}

HeadSection is the HEAD section body. Field semantics match the spec §HEAD Section.

func ReadHeadSection 

func ReadHeadSection(b []byte) (HeadSection, error)

ReadHeadSection decodes a HEAD section body from b.

func (HeadSection) DigestBody 

func (h HeadSection) DigestBody(profile Profile) []byte

DigestBody returns the byte sequence that should be hashed for this HEAD section under the given profile. For sealed and weights-only profiles, created_unix_ms and generation are zeroed so reproducible builds work across different wall clocks. For checkpoint profile, the full body is used.

func (HeadSection) Write 

func (h HeadSection) Write(w io.Writer) error

Write encodes the HEAD section body to w.

type HeadValueKind 

type HeadValueKind uint8

HeadValueKind is the private enum for HEAD metadata values. This enum is NOT the same as the global primitive KindXxx enum — HEAD metadata is restricted to scalar primitives. 

const (
	HeadValueNull   HeadValueKind = 0
	HeadValueBool   HeadValueKind = 1
	HeadValueI64    HeadValueKind = 2
	HeadValueF64    HeadValueKind = 3
	HeadValueString HeadValueKind = 4
)

type Int8 

type Int8 int8

Typed scalar primitives. Go types directly model the MLL abstract data model.

type Int16 

type Int16 int16

Typed scalar primitives. Go types directly model the MLL abstract data model.

type Int32 

type Int32 int32

Typed scalar primitives. Go types directly model the MLL abstract data model.

type Int64 

type Int64 int64

Typed scalar primitives. Go types directly model the MLL abstract data model.

type KVCacheType 

type KVCacheType struct {
	Layers  int
	Heads   int
	HeadDim int
}

KVCacheType describes a transformer key-value cache.

type KernelDecl 

type KernelDecl struct {
	NameIdx uint32
	Body    []byte
}

KernelDecl is a minimal kernel declaration. The full DSL (tile dims, variants, op bodies) lives in Plan 2+; Plan 1 stores the kernel name and an opaque body byte blob as a placeholder so callers can round-trip a KRNL section.

type KrnlBuilder 

type KrnlBuilder struct {
	// contains filtered or unexported fields
}

func NewKrnlBuilder 

func NewKrnlBuilder() *KrnlBuilder

func (*KrnlBuilder) Add 

func (b *KrnlBuilder) Add(k KernelDecl)

func (*KrnlBuilder) Write 

func (b *KrnlBuilder) Write(w io.Writer) error

Write layout: u32 count + repeat{ u32 name, u32 body_len, body_len bytes }

type KrnlSection 

type KrnlSection struct {
	Decls []KernelDecl
}

func ReadKrnlSection 

func ReadKrnlSection(data []byte) (KrnlSection, error)

type Layout 

type Layout uint8

Layout is the storage layout of a tensor's elements in memory. 

const (
	LayoutRowMajor Layout = 0
	LayoutColMajor Layout = 1
)

type List 

type List []any

List is an ordered sequence of values, heterogeneous types allowed.

type Map 

type Map map[string]any

Map is a keyed association of strings to values.

type MempBuilder 

type MempBuilder struct {
	// contains filtered or unexported fields
}

func NewMempBuilder 

func NewMempBuilder() *MempBuilder

func (*MempBuilder) Add 

func (b *MempBuilder) Add(e MempEntry)

func (*MempBuilder) Write 

func (b *MempBuilder) Write(w io.Writer) error

Write layout: u32 count + repeat{ Ref(8), u8 residency, u32 access_count }

type MempEntry 

type MempEntry struct {
	ParamRef    Ref
	Residency   uint8
	AccessCount uint32
}

MempEntry is one per-weight residency entry.

type MempSection 

type MempSection struct {
	Entries []MempEntry
}

func ReadMempSection 

func ReadMempSection(data []byte) (MempSection, error)

type OptmBuilder 

type OptmBuilder struct {
	// contains filtered or unexported fields
}

OptmBuilder accumulates optimizer state.

func NewOptmBuilder 

func NewOptmBuilder(kind uint8) *OptmBuilder

NewOptmBuilder returns a builder seeded with the given optimizer kind.

func (*OptmBuilder) AddMomentTensor 

func (b *OptmBuilder) AddMomentTensor(ref Ref)

AddMomentTensor records a reference to a moment tensor in TNSR.

func (*OptmBuilder) SetGeneration 

func (b *OptmBuilder) SetGeneration(gen uint64)

SetGeneration sets the checkpoint generation this OPTM entry belongs to.

func (*OptmBuilder) SetStep 

func (b *OptmBuilder) SetStep(step uint64)

SetStep sets the current optimizer step.

func (*OptmBuilder) Write 

func (b *OptmBuilder) Write(w io.Writer) error

Write encodes the OPTM section body. Layout: u8 kind + u64 step + u8 lr_schedule + u32 lr_state_len + lr_state + u64 generation + u32 moment_count + Ref[moment_count]

type OptmSection 

type OptmSection struct {
	Kind          uint8
	Step          uint64
	LRSchedule    uint8
	LRStateBytes  []byte
	Generation    uint64
	MomentTensors []Ref
}

OptmSection is the OPTM section (checkpoint-only).

func ReadOptmSection 

func ReadOptmSection(data []byte) (OptmSection, error)

ReadOptmSection decodes an OPTM section body.

type ParmBuilder 

type ParmBuilder struct {
	// contains filtered or unexported fields
}

ParmBuilder accumulates parameter declarations.

func NewParmBuilder 

func NewParmBuilder() *ParmBuilder

NewParmBuilder returns an empty builder.

func (*ParmBuilder) Add 

func (b *ParmBuilder) Add(p ParmDecl)

Add appends a parameter declaration.

func (*ParmBuilder) Write 

func (b *ParmBuilder) Write(w io.Writer) error

Write encodes the PARM section body. Layout: u32 count + repeat{ u32 name_idx, Ref(8) type_ref, u32 binding_idx, u8 trainable }

type ParmDecl 

type ParmDecl struct {
	NameIdx    uint32
	TypeRef    Ref    // reference into TYPE section
	BindingIdx uint32 // string table index; 0 if no binding
	Trainable  bool
}

ParmDecl is one entry in the PARM section.

type ParmSection 

type ParmSection struct {
	Decls []ParmDecl
}

ParmSection is the decoded form.

func ReadParmSection 

func ReadParmSection(data []byte) (ParmSection, error)

ReadParmSection decodes a PARM section body.

type PlanBuilder 

type PlanBuilder struct {
	// contains filtered or unexported fields
}

func NewPlanBuilder 

func NewPlanBuilder() *PlanBuilder

func (*PlanBuilder) Add 

func (b *PlanBuilder) Add(s PlanStep)

func (*PlanBuilder) Write 

func (b *PlanBuilder) Write(w io.Writer) error

Write layout: u32 count + repeat{ Ref entry, u8 kind, u32 name, Ref kernel, 

u32 in_count, Ref[in], u32 out_count, Ref[out] }

type PlanSection 

type PlanSection struct {
	Steps []PlanStep
}

func ReadPlanSection 

func ReadPlanSection(data []byte) (PlanSection, error)

type PlanStep 

type PlanStep struct {
	EntryRef  Ref
	Kind      uint8
	NameIdx   uint32
	KernelRef Ref // valid when Kind == PlanStepKernel
	Inputs    []Ref
	Outputs   []Ref
}

PlanStep is one step in a PLAN section.

type PrimitiveKind 

type PrimitiveKind uint8

Primitive kinds in the MLL abstract data model. 

const (
	KindNull PrimitiveKind = iota
	KindBool
	KindInt8
	KindInt16
	KindInt32
	KindInt64
	KindUint8
	KindUint16
	KindUint32
	KindUint64
	KindFloat16
	KindFloat32
	KindFloat64
	KindString
	KindBytes
	KindList
	KindMap
	KindTensor
	KindEnum
	KindRef
	KindDim
	KindValue
)

type Profile 

type Profile uint8

Profile identifies the role of an MLL artifact. 

const (
	ProfileSealed      Profile = 0x01
	ProfileCheckpoint  Profile = 0x02
	ProfileWeightsOnly Profile = 0x03
)

type ReadOption 

type ReadOption func(*readerConfig)

ReadOption configures Reader behavior.

func WithDigestVerification 

func WithDigestVerification() ReadOption

WithDigestVerification instructs the reader to verify every section's BLAKE3-256 digest against the directory entry.

type Reader 

type Reader struct {
	// contains filtered or unexported fields
}

Reader represents a loaded MLL binary file.

func ReadBytes 

func ReadBytes(data []byte, opts ...ReadOption) (*Reader, error)

ReadBytes parses an MLL binary file from a byte slice. By default, section digests are NOT verified (for speed); pass WithDigestVerification() to enable verification.

func ReadFile 

func ReadFile(path string, opts ...ReadOption) (*Reader, error)

ReadFile is a convenience wrapper that reads from a file path.

func (*Reader) DirectoryEntries 

func (r *Reader) DirectoryEntries() []DirectoryEntry

DirectoryEntries returns a copy of the directory entries.

func (*Reader) Profile 

func (r *Reader) Profile() Profile

Profile returns the file's profile byte.

func (*Reader) Section 

func (r *Reader) Section(tag [4]byte) ([]byte, bool)

Section returns the body bytes for the section with the given tag. The returned slice is a view into the underlying file bytes; callers MUST NOT modify it. Returns (nil, false) if the section is not present.

func (*Reader) SectionCount 

func (r *Reader) SectionCount() uint32

SectionCount returns the number of sections in the file.

func (*Reader) Version 

func (r *Reader) Version() Version

Version returns the file's format version.

type Ref 

type Ref struct {
	Tag   [4]byte // section tag of the target section
	Index uint32  // intra-section index of the target entity
}

Ref is a typed pointer to a named entity in another section. Fixed-width 8 bytes: 4-byte section tag + 4-byte intra-section index.

func DecodeRef 

func DecodeRef(b []byte) (Ref, error)

DecodeRef reads a ref from 8 bytes.

func (Ref) Encode 

func (r Ref) Encode() []byte

Encode returns the 8-byte binary representation of a ref.

type SchmSection 

type SchmSection struct{}

SchmSection is the SCHM section. In Plan 1 this is always empty — full schema support lands in Plan 2.

func ReadSchmSection 

func ReadSchmSection(data []byte) (SchmSection, error)

ReadSchmSection decodes a SCHM body. Plan 1 accepts and ignores any entries.

func (SchmSection) Write 

func (s SchmSection) Write(w io.Writer) error

Write encodes an empty SCHM section: u32 count = 0.

type SectionInput 

type SectionInput struct {
	Tag           [4]byte
	Body          []byte
	DigestBody    []byte // optional; falls back to Body if nil
	Flags         uint16
	SchemaVersion uint16
}

SectionInput describes one section the caller wants to include in the file. If DigestBody is non-nil, it is used for the section's BLAKE3 digest computation instead of Body. This is needed for HEAD under sealed and weights-only profiles, where wall-clock fields are zeroed in the digest but preserved in the on-disk body.

type SgnmSection 

type SgnmSection struct {
	KeyIDIdx  uint32 // string table index of the key identifier
	Algorithm uint8
	Signature []byte
}

SgnmSection holds the signature bytes.

func ReadSgnmSection 

func ReadSgnmSection(data []byte) (SgnmSection, error)

ReadSgnmSection decodes a SGNM section body.

func (SgnmSection) Write 

func (s SgnmSection) Write(w io.Writer) error

Write layout: u32 key_id_idx + u8 algorithm + u32 sig_len + sig_len bytes

type String 

type String string

String is an interned UTF-8 string. At the data model level it's a Go string; binary encoding replaces it with a u32 index into the STRG section.

type StringTable 

type StringTable struct {
	// contains filtered or unexported fields
}

StringTable represents the STRG section: a list of interned strings referenced by u32 index from elsewhere in the file.

func NewStringTableBuilder 

func NewStringTableBuilder() *StringTable

NewStringTableBuilder returns an empty string table builder.

func ReadStringTable 

func ReadStringTable(b []byte) (*StringTable, error)

ReadStringTable parses a STRG section body from b.

func (*StringTable) At 

func (t *StringTable) At(idx uint32) string

At returns the string at the given index.

func (*StringTable) CanonicalizeLexicographic 

func (t *StringTable) CanonicalizeLexicographic() map[uint32]uint32

CanonicalizeLexicographic re-sorts the strings into lexicographic UTF-8 byte order and returns the remapping table: remap[old_index] = new_index. Callers must rewrite every string reference in every section using this map.

func (*StringTable) Contains 

func (t *StringTable) Contains(s string) bool

Contains reports whether s is in the table.

func (*StringTable) Intern 

func (t *StringTable) Intern(s string) uint32

Intern returns the index for s, inserting it if not already present. During accumulation, indices are assigned in first-seen order. CanonicalizeLexicographic rewrites indices to canonical order.

func (*StringTable) Lookup 

func (t *StringTable) Lookup(s string) (uint32, bool)

Lookup returns the index of s, or (0, false) if not present.

func (*StringTable) Size 

func (t *StringTable) Size() int

Size returns the number of strings in the table.

func (*StringTable) Write 

func (t *StringTable) Write(w io.Writer) error

Write encodes the string table to w as a STRG section body. Format: 

u32 string_count
for each string:
  u32 length
  utf8 bytes

type Tensor 

type Tensor struct {
	Name       string      // name of the tensor; resolved to STRG index
	DType      DType       // element type
	Shape      []Dimension // shape as symbolic dimensions
	Layout     Layout      // memory layout
	DataOffset uint64      // byte offset within the TNSR section body (set during seal)
	DataSize   uint64      // byte length (set during seal)
}

Tensor is a first-class primitive representing tensor metadata and a reference to its data. The raw bytes live in the TNSR section; this struct holds the metadata plus a pointer (by name) into TNSR.

type TensorEntry 

type TensorEntry struct {
	NameIdx    uint32 // string table index for tensor name
	DType      DType
	Shape      []uint64
	BodyOffset uint64 // offset within the TNSR section body (computed by builder)
	BodySize   uint64 // byte length of tensor data (computed by builder)
	Data       []byte // raw bytes (used during build; read-only during load)
}

TensorEntry describes one tensor in the TNSR section.

type TensorType 

type TensorType struct {
	DType DType
	Shape []Dimension
}

TensorType describes a tensor's type (element type and shape).

type TnsrBuilder 

type TnsrBuilder struct {
	// contains filtered or unexported fields
}

TnsrBuilder accumulates tensor entries and writes a properly aligned section.

func NewTnsrBuilder 

func NewTnsrBuilder() *TnsrBuilder

NewTnsrBuilder creates an empty builder.

func (*TnsrBuilder) Add 

func (b *TnsrBuilder) Add(e TensorEntry)

Add appends a tensor entry.

func (*TnsrBuilder) Write 

func (b *TnsrBuilder) Write(w io.Writer) error

Write encodes the TNSR section body to w. Tensor bodies are 64-byte aligned within the section. The caller is responsible for setting the ALIGNED flag on the directory entry so the section body itself is page-aligned in the file.

Section body layout: 

u32 tensor_count
for each tensor:
    u32 name_idx
    u8  dtype
    u32 rank
    u64[rank] shape
    u64 body_offset  (filled in during write)
    u64 body_size
    u8  flags
    u8[3] pad
[alignment pad to 64-byte boundary]
[tensor 1 raw bytes]
[alignment pad]
[tensor 2 raw bytes]
...

type TnsrSection 

type TnsrSection struct {
	Tensors []TensorEntry
}

TnsrSection is the TNSR section body.

func ReadTnsrSection 

func ReadTnsrSection(data []byte) (TnsrSection, error)

ReadTnsrSection parses a TNSR section body.

type TypeBuilder 

type TypeBuilder struct {
	// contains filtered or unexported fields
}

TypeBuilder accumulates type declarations.

func NewTypeBuilder 

func NewTypeBuilder() *TypeBuilder

NewTypeBuilder returns an empty builder.

func (*TypeBuilder) AddCandidatePackType 

func (b *TypeBuilder) AddCandidatePackType(nameIdx uint32, rank uint32) uint32

AddCandidatePackType appends a candidate-pack type and returns its index.

func (*TypeBuilder) AddKVCacheType 

func (b *TypeBuilder) AddKVCacheType(nameIdx uint32, layers, heads, headDim uint32) uint32

AddKVCacheType appends a kv-cache type and returns its index.

func (*TypeBuilder) AddTensorType 

func (b *TypeBuilder) AddTensorType(nameIdx uint32, dtype DType, shape []Dimension) uint32

AddTensorType appends a tensor type and returns its index.

func (*TypeBuilder) Decls 

func (b *TypeBuilder) Decls() []TypeDecl

Decls returns the current slice (read-only).

func (*TypeBuilder) Write 

func (b *TypeBuilder) Write(w io.Writer) error

Write encodes the TYPE section body. Layout: u32 count + repeat{ u32 name_idx, u8 kind, kind-specific payload } 

tensor:         u8 dtype + Shape (u32 rank + Dimension[rank] via WriteShape)
kv_cache:       u32 layers + u32 heads + u32 head_dim
candidate_pack: u32 rank

type TypeDecl 

type TypeDecl struct {
	NameIdx uint32
	Kind    uint8
	// Tensor fields (valid when Kind == TypeKindTensor)
	DType DType
	Shape []Dimension
	// KV cache fields (valid when Kind == TypeKindKVCache)
	Layers  uint32
	Heads   uint32
	HeadDim uint32
	// Candidate pack fields (valid when Kind == TypeKindCandidatePack)
	Rank uint32
}

TypeDecl is one entry in the TYPE section.

type TypeSection 

type TypeSection struct {
	Decls []TypeDecl
}

TypeSection is the decoded form of the TYPE section.

func ReadTypeSection 

func ReadTypeSection(data []byte) (TypeSection, error)

ReadTypeSection decodes a TYPE section body.

type Uint8 

type Uint8 uint8

Typed scalar primitives. Go types directly model the MLL abstract data model.

type Uint16 

type Uint16 uint16

Typed scalar primitives. Go types directly model the MLL abstract data model.

type Uint32 

type Uint32 uint32

Typed scalar primitives. Go types directly model the MLL abstract data model.

type Uint64 

type Uint64 uint64

Typed scalar primitives. Go types directly model the MLL abstract data model.

type Value 

type Value interface {
}

Value is the universal interface for any MLL primitive value at the Go API level. All primitive types satisfy Value via empty-interface embedding — this is deliberately loose because the binary encoder uses reflection on Kind() to dispatch to the correct codec. The data model is the source of truth; Go types are views.

type ValueBinding 

type ValueBinding struct {
	NameIdx uint32
	TypeRef Ref
}

ValueBinding is one input or output slot of an entry point.

type ValueKind 

type ValueKind uint8

ValueKind is the discriminator for a Value primitive. 

const (
	ValueKindInvalid       ValueKind = 0
	ValueKindTensor        ValueKind = 1
	ValueKindKVCache       ValueKind = 2
	ValueKindCandidatePack ValueKind = 3
)

type ValueType 

type ValueType struct {
	Kind          ValueKind
	Tensor        *TensorType
	KVCache       *KVCacheType
	CandidatePack *CandidatePackType
}

ValueType is a discriminated union over the three first-class value kinds.

func ValueOfCandidatePack 

func ValueOfCandidatePack(c CandidatePackType) ValueType

ValueOfCandidatePack constructs a candidate_pack-kind ValueType.

func ValueOfKVCache 

func ValueOfKVCache(k KVCacheType) ValueType

ValueOfKVCache constructs a kv_cache-kind ValueType.

func ValueOfTensor 

func ValueOfTensor(t TensorType) ValueType

ValueOfTensor constructs a tensor-kind ValueType.

type Version 

type Version struct {
	Major uint8
	Minor uint8
}

Version describes an MLL format version.

func (Version) Uint16 

func (v Version) Uint16() uint16

Uint16 returns the 16-bit encoded form (major in high byte, minor in low byte).

type Writer 

type Writer struct {
	// contains filtered or unexported fields
}

Writer composes an MLL binary file.

func NewWriter 

func NewWriter(out io.Writer, profile Profile, version Version, opts ...WriterOption) *Writer

NewWriter constructs a Writer that will emit an MLL file of the given profile.

func (*Writer) AddSection 

func (w *Writer) AddSection(s SectionInput)

AddSection appends a section to be written.

func (*Writer) ContentHash 

func (w *Writer) ContentHash() Digest

ContentHash returns the sealed content hash computed by Finish. Returns the zero Digest for checkpoint profiles.

func (*Writer) Finish 

func (w *Writer) Finish() error

Finish writes the complete file to the output writer.

func (*Writer) SetFileFlag 

func (w *Writer) SetFileFlag(flag uint8)

SetFileFlag sets a file-level flag bit.

type WriterOption 

type WriterOption func(*Writer)

WriterOption configures Writer behavior.

func WithSkipRequirementCheck 

func WithSkipRequirementCheck() WriterOption

WithSkipRequirementCheck disables the profile required-section check. Intended for test vector generators and unit tests that need to produce minimal files without assembling every required section.

Source Files

View all Source files

Directories

Path Synopsis
cmd
gen_test_vectors command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.