goai

package module
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Jul 13, 2026 License: MPL-2.0 Imports: 2 Imported by: 0

README

GoAI

ci

Go-native, full-spectrum AI library — Pure-Go-first, cgo-last.

Every operation ships as a validated Pure-Go reference first (cross-checked against PyTorch/tiktoken/ggml goldens), then optimized as a separate step against that reference. GPU backends are optional, benchmark-gated, and always fall back to Pure Go: CGO_ENABLED=0 builds and tests green with no C toolchain on any platform.

What works today

  • Transformer LLMs end-to-end: GPT and Llama (GQA/SwiGLU/RoPE) — build, train (full backward validated against real torch gradients at f64 rtol ~1e-9), checkpoint (safetensors/GGUF round-trips), tokenize (BPE bit-exact vs tiktoken, SentencePiece-Unigram, WordPiece), and generate.
  • GPU inference (Metal + Vulkan/MoltenVK): the llamagpu batched decoders record a whole decode step into one command buffer over device-resident weights and KV cache — measured 24× (Metal) / 21× (Vulkan) over per-op decode, 41× prompt prefill, cooperative long-context attention on every surface, and quantized (ggml Q-block) decode at 4-8× less weight memory.
  • Accelerated decoding, measured on real trained models: Medusa multi-head drafting (1.81×, 97% acceptance), lossless prompt-lookup (1.80×), draft-model speculative decoding (lossless; pays off on compute-bound targets), tree-Medusa (candidate trees verified in ONE masked forward), Jacobi parallel decoding, Self-Extend length extrapolation (4× the training length with no fine-tuning) — plus beam/diverse-beam, contrastive search & decoding, DoLa, classifier-free guidance, Mirostat, top-k/p/min-p/ typical/eta sampling, repetition penalties, regex-constrained decoding, and watermarking. Speed numbers in docs/benchmarking.md; what these features deliver on real trained models — measured — in docs/inference.md.
  • Training toolbox (nn, 100+ files): optimizers from SGD to Muon/SOAP/ Sophia/Schedule-Free with composable wrappers (SAM, Lookahead, GaLore, …), the PEFT family (LoRA/DoRA/PiSSA/VeRA/IA³/prefix/prompt, QLoRA proven end-to-end), quantization & pruning (AWQ/GPTQ/HQQ/NF4/SparseGPT/Wanda), post-transformer blocks (MoE/Mamba/RWKV/RetNet/MLA — every family proven end-to-end as a trained char-LM with structural causality checks; RWKV also in O(1)-state recurrent inference mode) — the optimizers and wrappers real-workload-verified with a measured comparison in docs/training.md — diffusion (DDPM/DDIM/EDM/flow matching), SSL, RLHF/alignment (GRPO, GSPO and the DPO family proven end-to-end on a real model, including a reproduced-and-mitigated reward-hacking case study — see docs/alignment.md), continual learning, and model merging.
  • Vision, classic ML & RL: a reference CNN image classifier over the NCHW conv/pool stack (vision); linear/softmax regression, K-Means, PCA (classic); environments, advantage estimation, and canonical agents (rl).

Every algorithm carries its paper citation (§R in SPEC.md) and is validated on the §V16 ladder: tier-1 parity against an official reference where one exists, tier-2 the defining paper.

Layout (§I)

Layer Package Role
L0 tensor Tensor, Dtype, strides/views
L1 backend, backend/ref op dispatch + Pure-Go reference (numerical truth)
L1b backend/cpu, backend/metal, backend/vulkan, backend/cuda optimized + GPU backends, auto-selected, always with fallback
L2 autograd reverse-mode tape + VJPs
L3 nn, ops, linalg layers, optimizers, losses; eager op API
L4 nlp, vision, classic, rl domain packages
L5 format safetensors, GGUF (every ggml quant reads: K-quants, all 8 i-quants, MXFP4), npy/npz
— llamagpu batched GPU decoding for GPT/Llama (Metal/Vulkan)

Build & verify

make build        # CGO_ENABLED=0 pure-Go build (§V7)
make vet test     # pure-Go gate: compiles tests too (§V23)
make metal-test   # Metal/MPS backend suite (darwin, cgo)
make vulkan-test  # Vulkan backend suite (MoltenVK on macOS)
make bench-compare  # cross-backend benchmark harness (§C3)

Requires Go 1.26+. No C toolchain needed for the default build. Architecture and task history live in SPEC.md (caveman-encoded, see FORMAT.md); design rationale in docs/; performance numbers and measurement policy in docs/benchmarking.md.

License

TBD.

License

GoAI is licensed under the Mozilla Public License 2.0 (see LICENSE): file-level copyleft. In practice:

  • Using GoAI in your product — statically or dynamically linked, open or closed source — imposes no obligations on your own code.
  • Modifying GoAI's files — those modified files (and only those) must remain available under the MPL, with source offered to recipients of your binaries.

Documentation

Overview

Package goai is a Go-native, full-spectrum AI library built Pure-Go-first / cgo-last. See SPEC.md for goals (§G), constraints (§C), architecture invariants (§I), and verification invariants (§V).

Layer model (§I): 

L0  tensor          core: Tensor, Dtype, strides/views
L1  backend         Backend/Kernel interface + Pure-Go reference (truth)
L1b backend/*        swappable accel backends (metal, vulkan, cuda) + fallback
L2  autograd        tape/graph + VJP rules
L3  nn, ops, linalg layers/optimizers/losses; eager ops; dense linear algebra
L4  nlp, vision,    domains
    classic, rl
L5  format          safetensors, GGUF, npy/npz
—   llamagpu        batched GPU decoding for GPT/Llama

Invariant: higher layers never import backend internals; every op has a Pure-Go fallback; CGO_ENABLED=0 builds green on macOS, Windows, Linux.

Index

Constants

View Source 
const Version = "0.0.0-dev"

Version is the current library version. Pre-release: API unstable (§V8).

Variables

This section is empty.

Functions

This section is empty.

Types

This section is empty.

Source Files

View all Source files

Directories

Path Synopsis
Package autograd is layer L2: tape-based reverse-mode automatic differentiation (ADR-0006).
 Package autograd is layer L2: tape-based reverse-mode automatic differentiation (ADR-0006).
Package backend is layer L1: the compute abstraction (ADR-0003).
 Package backend is layer L1: the compute abstraction (ADR-0003).
cpu
Package cpu is the optimized Pure-Go CPU backend (layer L1b).
 Package cpu is the optimized Pure-Go CPU backend (layer L1b).
cuda
Package cuda is the optional NVIDIA CUDA/cuBLAS GPU backend (layer L1b, §T42).
 Package cuda is the optional NVIDIA CUDA/cuBLAS GPU backend (layer L1b, §T42).
metal
Package metal is the Metal/MPS GPU backend (layer L1b, §T20).
 Package metal is the Metal/MPS GPU backend (layer L1b, §T20).
npu
Package npu documents GoAI's stance on NPU (neural-processing-unit) acceleration and provides an honest, always-false availability probe (§T44).
 Package npu documents GoAI's stance on NPU (neural-processing-unit) acceleration and provides an honest, always-false availability probe (§T44).
ref
Package ref is the Pure-Go scalar reference backend (layer L1).
 Package ref is the Pure-Go scalar reference backend (layer L1).
vulkan
Package vulkan is the optional, portable Vulkan compute GPU backend (layer L1b, §T43).
 Package vulkan is the optional, portable Vulkan compute GPU backend (layer L1b, §T43).
Package classic implements the classical (pre-deep-learning) machine-learning methods: ordinary least squares, softmax/logistic regression, k-means clustering, and principal component analysis.
 Package classic implements the classical (pre-deep-learning) machine-learning methods: ordinary least squares, softmax/logistic regression, k-means clustering, and principal component analysis.
Package format is layer L5: model interop and serialization.
 Package format is layer L5: model interop and serialization.
gguf
Package gguf reads the GGUF file format — the model container used by llama.cpp / ggml for quantized large language models.
 Package gguf reads the GGUF file format — the model container used by llama.cpp / ggml for quantized large language models.
npy
Package npy reads and writes single arrays in NumPy's .npy format (v1.0), the simplest numpy interchange format — a small ASCII header (dtype, shape, element order) followed by the raw C-order little-endian element bytes.
 Package npy reads and writes single arrays in NumPy's .npy format (v1.0), the simplest numpy interchange format — a small ASCII header (dtype, shape, element order) followed by the raw C-order little-endian element bytes.
npz
Package npz reads and writes NumPy .npz archives — a ZIP container holding one .npy array per named entry (numpy.savez / numpy.load).
 Package npz reads and writes NumPy .npz archives — a ZIP container holding one .npy array per named entry (numpy.savez / numpy.load).
safetensors
Package safetensors reads and writes the safetensors file format — the storage container Hugging Face uses for model weights.
 Package safetensors reads and writes the safetensors file format — the storage container Hugging Face uses for model weights.
internal
bench
Package bench holds deterministic data generators for benchmarks (§T10, §V5).
 Package bench holds deterministic data generators for benchmarks (§T10, §V5).
benchcompare
Package benchcompare holds cross-backend comparison micro-benchmarks (cpu vs metal vs vulkan vs the pure-Go reference) for the accelerated ops.
 Package benchcompare holds cross-backend comparison micro-benchmarks (cpu vs metal vs vulkan vs the pure-Go reference) for the accelerated ops.
linalg
Package linalg holds small dense-linear-algebra kernels shared across layers (classic PCA, nn GaLore) — currently a symmetric eigendecomposition.
 Package linalg holds small dense-linear-algebra kernels shared across layers (classic PCA, nn GaLore) — currently a symmetric eigendecomposition.
npy
Package npy is a minimal Pure-Go reader/writer for NumPy .npy files, used to exchange large golden tensors with the Python reference generator (§T10, §V1).
 Package npy is a minimal Pure-Go reader/writer for NumPy .npy files, used to exchange large golden tensors with the Python reference generator (§T10, §V1).
simd
Package simd is the internal SIMD wrapper (§B3).
 Package simd is the internal SIMD wrapper (§B3).
Package linalg provides gonum/numpy-style dense linear algebra over rank-2 tensors: an LU factorization with partial pivoting (P·A = L·U) and the derived determinant, linear solve, and matrix inverse.
 Package linalg provides gonum/numpy-style dense linear algebra over rank-2 tensors: an LU factorization with partial pivoting (P·A = L·U) and the derived determinant, linear solve, and matrix inverse.
Package llamagpu decodes nlp.Llama models on the GPU with batched command buffers (ADR-0019): each per-token step records the whole layer stack into ONE command buffer over device-resident weights and KV cache, instead of paying a dispatch round-trip per op.
 Package llamagpu decodes nlp.Llama models on the GPU with batched command buffers (ADR-0019): each per-token step records the whole layer stack into ONE command buffer over device-resident weights and KV cache, instead of paying a dispatch round-trip per op.
Package nlp builds transformer language models — the components that turn a stream of token ids into next-token predictions, and the decoding strategies that turn those predictions back into text.
 Package nlp builds transformer language models — the components that turn a stream of token ids into next-token predictions, and the decoding strategies that turn those predictions back into text.
Package nn is layer L3: neural-network building blocks.
 Package nn is layer L3: neural-network building blocks.
Package ops is the eager, functional API over GoAI's tensor operations: each function runs one kernel immediately and returns a new tensor, with no autograd tape involved.
 Package ops is the eager, functional API over GoAI's tensor operations: each function runs one kernel immediately and returns a new tensor, with no autograd tape involved.
Package rl provides the reinforcement-learning building blocks: episodic environments, return/advantage estimation, and two canonical agents.
 Package rl provides the reinforcement-learning building blocks: episodic environments, return/advantage estimation, and two canonical agents.
Package tensor is layer L0: the core data model every other layer builds on.
 Package tensor is layer L0: the core data model every other layer builds on.
Package vision is the L4 computer-vision domain package (§G1/§T457): image models assembled from the verified nn building blocks.
 Package vision is the L4 computer-vision domain package (§G1/§T457): image models assembled from the verified nn building blocks.

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.