LNMP Go SDK

Pure Go implementation of the LNMP (LLM Native Minimal Protocol) - a compact, deterministic binary format for AI/ML data interchange.

Features

• 🚀 Zero Dependencies - Pure Go, no CGO required
• ⚡ High Performance - Binary codec with zero-copy decoding
• 🔒 Deterministic - Byte-identical output across platforms
• 📦 Compact - 40-60% smaller than JSON
• 🔢 Type Safe - Field IDs with runtime validation
• 🌐 Full Parity - Complete Rust lnmp-protocol compatibility

Installation

go get github.com/lnmplang/lnmp-sdk-go

Requirements: Go 1.21+

Quick Start

package main

import (
    "fmt"
    lnmp "github.com/lnmplang/lnmp-sdk-go"
)

func main() {
    // Build a record using fluent API
    record := lnmp.NewRecordBuilder().
        WithInt(lnmp.FidUserId, 14532).
        WithBool(lnmp.FidIsActive, true).
        WithString(lnmp.FidName, "Alice").
        WithFloat(lnmp.FidScore, 0.95).
        Build()

    // Encode to text format
    text := lnmp.Encode(record)
    fmt.Println(text) // F7=1\nF12=14532\nF20=Alice\nF41=0.95

    // Encode to binary (compact)
    binary, _ := lnmp.EncodeBinary(record)
    fmt.Printf("Binary: %d bytes\n", len(binary))

    // Parse text format
    parsed, _ := lnmp.Parse("F12=100;F7=1")

    // Wrap in envelope with metadata
    env := lnmp.Wrap(record, 
        lnmp.WithSource("my-service"),
        lnmp.WithKind(lnmp.KindEvent))
}

Modules

Module	Description	Key Features
core	Types, FID constants, checksum	Record, Field, Value, 140+ FIDs
codec	Parser, encoder, binary codec	Text/Binary, container format
envelope	Message wrapping, metadata	Source, trace ID, routing
net	Routing, QoS, filtering	Priority, TTL, importance
embedding	Vector operations	Encode/decode, delta, similarity
quant	Quantization (FP16, Int4, Int8)	2x-8x compression
spatial	3D types (Position, Rotation)	Vec3, Quaternion, BoundingBox
sfe	Semantic Field Extraction	Dictionary, scoring
sanitize	Input sanitization	Field filtering, validation

Module Import

// Meta package (recommended)
import lnmp "github.com/lnmplang/lnmp-sdk-go"

// Individual modules
import "github.com/lnmplang/lnmp-sdk-go/core"
import "github.com/lnmplang/lnmp-sdk-go/codec"
import "github.com/lnmplang/lnmp-sdk-go/quant"
import "github.com/lnmplang/lnmp-sdk-go/spatial"

Determinism Guarantee

LNMP ensures byte-identical output across platforms:

// Same input → Same output (always)
record := lnmp.NewRecordBuilder().
    WithInt(lnmp.FidUserId, 12345).
    Build()

binary1, _ := lnmp.EncodeBinary(record)
binary2, _ := lnmp.EncodeBinary(record)

bytes.Equal(binary1, binary2) // Always true

Determinism features:

• Canonical field ordering (sorted by FID)
• IEEE 754 float representation
• SC32 checksums for integrity
• Big-endian binary encoding

Binary Format

The binary format provides 40-60% size reduction:

// Text: ~50 bytes
text := "F12=14532\nF7=1\nF20=test\nF41=3.14159"

// Binary: ~28 bytes (44% smaller)
binary, _ := lnmp.EncodeBinary(record)

Container Format

import "github.com/lnmplang/lnmp-sdk-go/codec"

// Build container with metadata
builder := codec.NewContainerBuilder(core.ModeBinary).
    WithFlags(core.FlagChecksumRequired)

data, _ := builder.EncodeRecord(record)

// Parse container
frame, _ := codec.ParseContainerFrame(data)
decoded, _ := frame.DecodeRecord()

Quantization

Compress embedding vectors with minimal accuracy loss:

import "github.com/lnmplang/lnmp-sdk-go/quant"

// FP16: 2x compression, ~99.9% accuracy
encoder := quant.NewQuantEncoder(quant.SchemeFP16)
qv, _ := encoder.Encode([]float32{0.1, 0.2, 0.3, 0.4})

// Int4: 8x compression, ~95% accuracy
encoder := quant.NewQuantEncoder(quant.SchemeInt4)
qv, _ := encoder.Encode(values)

// Decode back
decoder := quant.NewQuantDecoder()
restored, _ := decoder.Decode(qv)

Spatial Types

Full 3D math support for robotics/games:

import "github.com/lnmplang/lnmp-sdk-go/spatial"

// Position and velocity
pos := spatial.Position3D{X: 1.0, Y: 2.0, Z: 3.0}
vel := spatial.Velocity{VX: 0.1, VY: 0.2, VZ: 0.3}

// Quaternion operations
q1 := spatial.Quaternion{W: 1, X: 0, Y: 0, Z: 0}
q2 := spatial.EulerToQuaternion(spatial.Rotation{Pitch: 0.5})
result := spatial.QuaternionMultiply(q1, q2)

// Validation
if err := spatial.ValidateQuaternion(q1); err != nil {
    // Handle non-normalized quaternion
}

FID Registry

Runtime validation with the official Field ID registry:

import "github.com/lnmplang/lnmp-sdk-go/core"

registry := core.NewFidRegistry()
registry.AddEntry(&core.FidEntry{
    Fid:          core.FidUserId,
    Name:         "user_id",
    ExpectedType: core.TypeExpectInt,
    Status:       core.RegStatusActive,
})

// Validate fields
results := registry.ValidateRecord(record)
for _, r := range results {
    if !r.Valid {
        log.Printf("Invalid field: FID %d", r.Fid)
    }
}

Performance

Benchmarks on Apple M1:

Operation	Throughput	Latency
Parse (text)	2.1M records/s	476ns
Encode (text)	3.5M records/s	286ns
Parse (binary)	5.2M records/s	192ns
Encode (binary)	6.8M records/s	147ns
Checksum	12M fields/s	83ns

Testing

# Run all tests
go test ./...

# Run with coverage
go test ./... -cover

# Run benchmarks
go test ./... -bench=.

Test coverage: 9 packages, 100+ test cases, all passing.

Examples

See the examples directory:

• examples/basic - Quick start
• examples/determinism - Cross-platform consistency demo

Protocol Compatibility

This SDK is fully compatible with:

• Rust: lnmp-protocol v0.5.x
• JavaScript: lnmp-sdk-js
• Python: lnmp-sdk-python

License

MIT License - see LICENSE

Contributing

Contributions welcome! Please read CONTRIBUTING.md.