born

About born

This large README is shown as a plain-text preview. Read the full README at the source

# Born - Production-Ready ML for Go

<p align="center">
  <img src="assets/born.png" alt="Born ML Framework - Inspired by Burn" width="800">
</p>

[![Go Version](https://img.shields.io/badge/Go-1.25+-00ADD8?style=flat&logo=go)](https://go.dev/)
[![Go Reference](https://pkg.go.dev/badge/github.com/born-ml/born.svg)](https://pkg.go.dev/github.com/born-ml/born)
[![Go Report Card](https://goreportcard.com/badge/github.com/born-ml/born)](https://goreportcard.com/report/github.com/born-ml/born)
[![Pure Go](https://img.shields.io/badge/100%25-Pure_Go-00ADD8)](https://golang.org/)
[![Release](https://img.shields.io/github/v/release/born-ml/born?include_prereleases&label=version)](https://github.com/born-ml/born/releases)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Test Status](https://github.com/born-ml/born/actions/workflows/test.yml/badge.svg)](https://github.com/born-ml/born/actions/workflows/test.yml)
[![Codecov](https://codecov.io/gh/born-ml/born/branch/main/graph/badge.svg?token=CODECOV_TOKEN)](https://codecov.io/gh/born-ml/born)
[![Discussions](https://img.shields.io/github/discussions/born-ml/born?logo=github&label=Discussions)](https://github.com/born-ml/born/discussions)
<a href="https://opencollective.com/born-ml"><img src="https://opencollective.com/born-ml/all/badge.svg?label=financial+contributors" alt="Financial Contributors on Open Collective"></a>

> **"Models are born production-ready"**

Born is a modern deep learning framework for Go, inspired by [Burn](https://github.com/tracel-ai/burn) (Rust). Build ML models in pure Go and deploy as single binaries - no Python runtime, no complex dependencies.

*Pure Go ML with GPU acceleration - no CGO required!*

---

## Why Born?

### The Problem
Deploying ML models is hard:
- Python runtime required
- Complex dependency management
- Large Docker images
- Slow startup times
- Integration friction with Go backends

### The Born Solution
```go
import "github.com/born-ml/born"

// Models "born" ready for production
model := born.Load("resnet50.born")
prediction := model.Predict(image)

// That's it. No Python. No containers. Just Go.
```

**Benefits**:
- Single binary deployment
- Fast startup (< 100ms)
- Small memory footprint
- Native Go integration
- Cross-platform out of the box

---

## Features

### Core
- **Pure Go** - No CGO dependencies, trivial cross-compilation
- **Type Safe** - Generics-powered API for compile-time guarantees
- **Autodiff** - Automatic differentiation via decorator pattern
- **Production Ready** - Single binary deployment, fast startup
- **WebAssembly** - Run inference in browsers natively (core tensor has zero platform-specific code)

### GPU Acceleration
- **WebGPU Backend** - Zero-CGO GPU via [gogpu/wgpu](https://github.com/gogpu/wgpu) (pure Go), 123x MatMul speedup
- **38+ GPU Operations** - MatMul, BatchMatMul, Conv2D, MaxPool2D, Softmax, and more
- **Lazy Evaluation** - GPU-resident tensors, command batching (~90s → <5s/step)
- **Multi-dim Transpose** - GPU-accelerated 3D/4D/5D/6D tensors
- **Explicit Memory** - Deterministic GPU buffer lifecycle via `Release()` (no GC dependency)

### LLM & Transformers
- **Flash Attention 2** - O(N) memory, WebGPU WGSL shader, 2x+ speedup on long sequences
- **Speculative Decoding** - Draft model + verification, 2-4x inference speedup
- **Multi-Head Attention** - MHA, SDPA, Grouped Query Attention (GQA)
- **KV-Cache** - Efficient autoregressive generation (3.94x speedup)
- **Positional Encodings** - RoPE, ALiBi, Sinusoidal, Learned
- **Modern FFN** - SwiGLU, GeGLU, ReGLU with gated activations
- **Normalizations** - LayerNorm, RMSNorm (LLaMA style)
- **Tokenizers** - TikToken, BPE, HuggingFace format, chat templates
- **Sampling** - Temperature, Top-K, Top-P, Min-P, repetition penalty
- **Text Generation** - Streaming API, stop sequences

### Model Import & Export
- **ONNX Import** - Load PyTorch/TensorFlow models via `.onnx` (57 operators)
- **GGUF Import** - llama.cpp format with K-quant dequantization (Q4_K, Q5_K, Q6_K, Q8_0); embedded tokenizer support (GPT-2 BPE, SentencePiece)
- **LLaMA** - `models/llama.LoadGGUF()` for end-to-end LLaMA inference; verified on TinyLlama 1.1B Q8_0 and Q4_K_M; CPU embedding fallback for large-vocab models
- **Injectable Attention** - swap attention implementation at model load time for research experiments
- **Native Format** - `.born` format with `nn.Save()` / `nn.Load()` / `nn.SaveTo()` / `nn.LoadFrom()` (file, stream, or `[]byte`)
- **Checkpoints** - Resume training with optimizer state preservation
- **SafeTensors** - HuggingFace compatible; F16/BF16 tensors widened to float32 on load
- **Reproducibility** - `nn.SetSeed()` for deterministic weight initialization

---

## Quick Start

### Installation

```bash
# Clone repository
git clone https://github.com/born-ml/born.git
cd born

# Build
make build

# Or install CLI
make install
```

### Development Setup

**Requirements**:
- Go 1.26+ (1.26 required for optional SIMD support via `GOEXPERIMENT=simd`)
- Make (optional, but recommended)
- golangci-lint (for linting)

**Build**:
```bash
make build          # Build all binaries
make test           # Run tests
make lint           # Run linter
make bench          # Run benchmarks
```

### Example: MNIST Classification

**Working example included!** See `examples/mnist/` for complete implementation.

```go
package main

import (
    "github.com/born-ml/born/autodiff"
    "github.com/born-ml/born/backend/cpu"
    "github.com/born-ml/born/nn"
    "github.com/born-ml/born/optim"
)

func main() {
    // Create backend with autodiff
    backend := autodiff.New(cpu.New())

    // Define model (784 → 128 → 10)
    model := NewMNISTNet(backend)

    // Create loss and optimizer
    criterion := nn.NewCrossEntropyLoss(backend)
    optimizer := optim.NewAdam(model.Parameters(), optim.AdamConfig{
        LR:    0.001,
        Betas: [2]float32{0.9, 0.999},
    }, backend)

    // Training loop
    for epoch := range 10 {
        // Forward pass
        logits := model.Forward(batch.ImagesTensor)
        loss := criterion.Forward(logits, batch.LabelsTensor)

        // Backward pass
        optimizer.ZeroGrad()
        grads := backend.Backward(loss.Raw())
        optimizer.Step(grads)

        // Log progress
        acc := nn.Accuracy(logits, batch.LabelsTensor)
        fmt.Printf("Epoch %d: Loss=%.4f, Accuracy=%.2f%%\n",
            epoch, loss.Raw().AsFloat32()[0], acc*100)
    }
}
```

**Run it:** `cd examples/mnist && go run .`

### Example: LLM Inference (LLaMA)

```go
package main

import (
    "fmt"
    "github.com/born-ml/born/backend/cpu"
    "github.com/born-ml/born/models/llama"
    "github.com/born-ml/born/generate"
    "github.com/born-ml/born/tokenizer"
)

func main() {
    backend := cpu.New()

    // Load LLaMA model from GGUF (Q4_K_M, Q8_0, F16, F32 supported)
    model, _ := llama.LoadGGUF("tinyllama-1.1b.Q8_0.gguf", backend)
    defer model.Release()

    // Load tokenizer
    tok, _ := tokenizer.NewTikTokenForModel("gpt-4")

    // Create generator with sampling config
    gen := generate.NewTextGenerator(model, tok, generate.SamplingConfig{
        Temperature: 0.7,
        TopP:        0.9,
        TopK:        40,
    })

    // Generate text
    result, _ := gen.Generate("Hello, world!", generate.GenerateConfig{
        MaxTokens: 100,
    })
    fmt.Println(result)

    // Or use streaming
    stream, _ := gen.GenerateStream("Once upon a time", generate.GenerateConfig{
        MaxTokens: 50,
        Stream:    true,
    })
    for chunk := range stream {
        fmt.Print(chunk.Token)
    }
}
```

Verified working: TinyLlama 1.1B Q8_0 and Q4_K_M.

**Core Features:**
- ✅ Tensor operations (Add, MatMul, Reshape, Exp, Sqrt, Cat, etc.)
- ✅ **35+ GPU operations** (BatchMatMul, Conv2D, MaxPool2D, Comparisons, Reductions)
- ✅ **31 type-safe public API operations** (MulScalar, Greater, Softmax, Int32, etc.)
- ✅ Automatic differentiation with gradient tape
- ✅ Neural network modules (Linear, Conv2D, ReLU, SiLU, RMSNorm, Embedding)
- ✅ Optimizers (SGD with momentum, Adam with bias correction)
- ✅ Losses (CrossEntropyLoss with numerical stability)
- ✅ **Complete WebGPU backend** (zero-CGO, 123x MatMul speedup)
- ✅ Transformer primitives (for LLaMA, GPT, Mistral architectures)

---

## Architecture

### Backend Abstraction

Born uses a backend interface for device independence:

```go
type Backend interface {
    Add(a, b *RawTensor) *RawTensor
    MatMul(a, b *RawTensor) *RawTensor
    // ... other operations
}
```

**Available Backends:**

| Backend | Status | Description |
|---------|--------|-------------|
| CPU | ✅ **Available** | Pure Go implementation, all operations |
| WebGPU | ✅ **Available** | Zero-CGO GPU via [gogpu/wgpu](https://github.com/gogpu/wgpu) (pure Go) |
| Vulkan | 📋 Planned | Cross-platform GPU compute (Linux focus) |
| CUDA | 📋 Planned | NVIDIA GPU via zero-CGO |
| Metal | 📋 Planned | Apple GPU (macOS/iOS) |

**WebGPU Operation Support** 🎉

| Category | Operations | Backend |
|----------|------------|---------|
| **Math** | Add, Sub, Mul, Div (float32 + int32), Exp, Sqrt, Rsqrt, Log, Cos, Sin | ✅ GPU |
| **Matrix** | MatMul, **BatchMatMul** (3D/4D), Transpose, Reshape | ✅ GPU |
| **CNN** | **Conv2D**, **MaxPool2D** | ✅ GPU |
| **Activation** | ReLU, Sigmoid, Tanh, Softmax | ✅ GPU |
| **Scalar** | MulScalar, AddScalar, SubScalar, DivScalar | ✅ GPU |
| **Reduction** | **Sum**, SumDim, MeanDim, **Argmax** | ✅ GPU/CPU hybrid |
| **Compare** | **Greater**, **Lower**, GreaterEqual, LowerEqual, **Equal**, NotEqual | ✅ GPU |
| **Boolean** | **And**, **Or**, **Not** | ✅ GPU |
| **Shape** | Cat, Chunk, Unsqueeze, Squeeze, **Expand** | ✅ CPU (efficient) |
| **Selection** | **Where**, **Gather**, **Embedding** | ✅ GPU |
| **Type** | **Cast** (float32, int32) | ✅ CPU |

**Total: 38+ GPU-accelerated operations!**

*All operations required for LLM inference (Attention, RoPE, LayerNorm, etc.) are fully supported on GPU.*

**GPU Backend Setup:**

The WebGPU backend uses [gogpu/wgpu](https://github.com/gogpu/wgpu) — a pure Go WebGPU implementation. **No shared libraries, no DLLs, no CGO.** Just `go build` and it works.

```bash
# That's it. No downloads, no system libraries.
go build ./...
```

Currently supported on **Windows (D3D12)**. Linux (Vulkan) and macOS (Metal) support coming soon — gogpu/wgpu supports all three backends.

**Usage:**
```go
import (
    "github.com/born-ml/born/autodiff"
    "github.com/born-ml/born/backend/cpu"
    "github.com/born-ml/born/backend/webgpu"
)

// Automatic GPU/CPU selection with graceful fallback
var backend tensor.Backend
if webgpu.IsAvailable() {
    gpu, err := webgpu.New()
    if err == nil {
        backend = autodiff.New(gpu)
        defer gpu.Release() // Don't forget to release GPU resources
    }
}
if backend == nil {
    backend = autodiff.New(cpu.New())
}
```

### Decorator Pattern

Functionality composed via decorators (inspired by Burn):

```go
// Basic backend
base := cpu.New()

// Add autodiff
withAutodiff := autodiff.New(base)

// Add kernel fusion
optimized := fusion.New(withAutodiff)

// Your code works with any backend!
model := createModel(optimized)
```

### Type Safety with Generics

```go
type Tensor[T DType, B Backend] struct {
    raw     *RawTensor
    backend B
}

// Compile-time type checking
func (t *Tensor[float32, B]) MatMul(other *Tensor[float32, B]) *Tensor[float32, B]
```

---

## Roadmap

### ✅ What's Working

**Core Framework**
- Tensor API with generics, autodiff, NN modules (Linear, Conv2D, ReLU, etc.)
- Optimizers (SGD, Adam), losses (CrossEntropyLoss)
- MNIST: 97.44% MLP, 98.18% CNN accuracy

**GPU Acceleration**
- WebGPU backend with 38+ operations (123x MatMul speedup)
- Lazy evaluation, command batching (~90s → <5s/step)
- CNN support (Conv2D, MaxPool2D, BatchMatMul)

**LLM & Transformers**
- Multi-Head Attention, GQA, KV-Cache (3.94x speedup)
- RoPE, ALiBi, RMSNorm, SwiGLU
- Tokenizers (TikToken, BPE), text generation with streaming

**Model Import & Export**
- ONNX import (57 operators)
- GGUF loading (LLaMA, Mistral, DeepSeek)
- Native `.born` format, SafeTensors export

### 🚀 Upcoming

**Quantization** (v0.8.0) - GPTQ/AWQ (4x smaller), KV Cache compression, Model Zoo

**Production Serving** - PagedAttention, Continuous Batching, OpenAI-compatible API

**Scale & Stability** - Multi-GPU, CPU SIMD (AVX2/Neon), Gradient Checkpointing

**v1.0 LTS** - API freeze, 3+ years support, production hardening

**Full roadmap & changelog**: See [ROADMAP.md](ROADMAP.md) and [CHANGELOG.md](CHANGELOG.md)

---

## Documentation

### For Users

- **[Philosophy](docs/PHILOSOPHY.md)** - Production-first design principles
- **[Use Cases](docs/USE_CASES.md)** - When to use Born (and when not)
- **[Getting Started](docs/getting-started.md)** - Installation and first steps *(coming soon)*
- **[API Reference](https://pkg.go.dev/github.com/born-ml/born)** - Complete API documentation
- **[Examples](examples/)** - Sample code (MNIST MLP, CNN, GPU inference, GPU training)

### For Contributors

- **[Contributing](CONTRIBUTING.md)** - How to contribute
- **[GitHub Issues](https://github.com/born-ml/born/issues)** - Report bugs or request features

---

## Philosophy

### "Born Ready"

Models trained anywhere (PyTorch, TensorFlow) are **imported** and **born** production-ready:

```
Training → Birth → Production
 (Burn)    (Born)    (Run)

PyTorch trains  →  Born imports  →  Born deploys
TensorFlow trains → Born imports → Born deploys
Born trains    →  Born ready   →  Born serves
```

### Production First

- **Single Binary**: Entire model in one executable
- **No Runtime**: No Python, no dependencies
- **Fast Startup**: < 100ms cold start
- **Small Memory**: Minimal footprint
- **Cloud Native**: Natural fit for Go services

### Developer Experience

- **Type Safe**: Catch errors at compile time
- **Clean API**: Intuitive and ergonomic
- **Great Docs**: Comprehensive documentation
- **Easy Deploy**: `go build` and you're done

---

## Performance

**Actual Benchmarks** (AMD Ryzen 9 5950X, NVIDIA RTX 3080):

### Matrix Operations (WebGPU vs CPU)

| Operation | CPU | GPU | Speedup |
|-----------|-----|-----|---------|
| MatMul 1024x1024 | 7143ms | 58ms | **123x** |
| MatMul 512x512 | 499ms | 12ms | **41x** |
| MatMul 256x256 | 56ms | 3.7ms | **15x** |

### Neural Network Inference

| Batch Size | CPU | GPU | Speedup | Throughput |
|------------|-----|-----|---------|------------|
| 64 | 48ms | 19ms | 2.5x | 3,357/s |
| 256 | 182ms | 21ms | **8.5x** | 11,883/s |
| 512 | 348ms | 32ms | **10.9x** | 15,973/s |

*CPU backend includes cache-tiled MatMul (3–5x), AVX2 SIMD micro-kernel (3.5x), and SIMD element-wise ops (up to 5.4x). Build with `GOEXPERIMENT=simd` to enable.*

### WebGPU WGSL Shaders

Born includes **30+ optimized WGSL compute shaders**:

| Shader | Workgroup | Description |
|--------|-----------|-------------|
| `addShader` | 256 | Element-wise addition |
| `subShader` | 256 | Element-wise subtraction |
| `mulShader` | 256 | Element-wise multiplication |
| `divShader` | 256 | Element-wise division |
| `matmulShader` | 16x16 | Matrix multiplication (2D) |
| `batchMatMulShader` | 8x8x1 | Batched matmul (3D/4D) |
| `conv2dShader` | 8x8x1 | 2D convolution with padding |
| `maxPool2dShader` | 8x8x1 | 2D max pooling |
| `transposeShader` | 16x16 | Matrix transpose |
| `reluShader` | 256 | ReLU activation |
| `sigmoidShader` | 256 | Sigmoid activation |
| `tanhShader` | 256 | Tanh activation |
| `softmaxShader` | 256 | Softmax (numerically stable) |
| `expShader` | 256 | Element-wise exp |
| `sqrtShader` | 256 | Element-wise sqrt |
| `rsqrtShader` | 256 | Reciprocal sqrt (1/√x) |
| `cosShader` | 256 | Element-wise cosine |
| `sinShader` | 256 | Element-wise sine |
| `greaterShader` | 256 | Greater-than comparison |
| `lowerShader` | 256 | Less-than comparison |
| `equalShader` | 256 | Equality comparison |
| `andShader` | 256 | Logical AND |
| `orShader` | 256 | Logical OR |
| `notShader` | 256 | Logical NOT |
| `argmaxShader` | 256 | Argmax along dimension |
| `globalSumShader` | 256 | Parallel sum reduction |
| `scalarMulShader` | 256 | Scalar multiplication |
| `scalarAddShader` | 256 | Scalar addition |
| `addShaderInt32` | 256 | Int32 element-wise addition |
| `subShaderInt32` | 256 | Int32 element-wise subtraction |
| `mulShaderInt32` | 256 | Int32 element-wise multiplication |
| `divShaderInt32` | 256 | Int32 element-wise division |

All shaders use **workgroup shared memory** for optimal performance and support **bounds checking** for safety.

---

## Inspiration

Born is inspired by and learns from:

- **[Burn](https://github.com/tracel-ai/burn)** - Architecture patterns, decorator design
- **[PyTorch](https://pytorch.org/)** - API ergonomics
- **[TinyGrad](https://github.com/geohot/tinygrad)** - Simplicity principles
- **[Gonum](https://github.com/gonum/gonum)** - Go numerical computing
- **[HDF5 for Go](https://github.com/scigolib/hdf5)** - Model serialization, dataset storage (planned)

---

## Acknowledgments

Special thanks to the projects that made Born possible:

### 🙏 [gogpu/wgpu](https://github.com/gogpu/wgpu) & [gogpu/naga](https://github.com/gogpu/naga)

Born's GPU acceleration is powered by **gogpu/wgpu** — a pure Go WebGPU implementation with **gogpu/naga** shader compiler.

**Why this stack is special:**
- **Pure Go** — No CGO, no shared libraries, no runtime dependencies
- **Single binary** — `go build` produces one executable with GPU support built in
- **Cross-platform** — Windows (D3D12) now, Linux (Vulkan) and macOS (Metal) coming soon
- **naga compatibility** — Shader compiler is 100% compatible with Rust naga
- **Integrated development** — Both gogpu and Born are developed by the same team

No DLL downloads, no `LD_LIBRARY_PATH`, no system-level installs. True single binary deployment for production ML inference.

---

## Community

**Project is in early development**. Star the repo to follow progress!

- **GitHub Org**: [github.com/born-ml](https://github.com/born-ml)
- **Main Repo**: [github.com/born-ml/born](https://github.com/born-ml/born)
- **Discussions**: [GitHub Discussions](https://github.com/born-ml/born/discussions)
  - [Announcements](https://github.com/born-ml/born/discussions/2)
  - [Q&A](https://github.com/born-ml/born/discussions/3)
  - [Feature Requests](https://github.com/born-ml/born/discussions/4)
- **Issues**: [Report bugs or request features](https://github.com/born-ml/born/issues)

---

## Sponsors

Born ML is an independent open-source project. Development is sustained by contributors and sponsors.

<a href="https://opencollective.com/born-ml"><img src="https://opencollective.com/born-ml/sponsors.svg?width=890&button=false" alt="Sponsors"></a>

### Backers

<a href="https://opencollective.com/born-ml"><img src="https://opencollective.com/born-ml/backers.svg?width=890&button=false" alt="Backers"></a>

<a href="https://opencollective.com/born-ml"><img src="https://img.shields.io/badge/Sponsor-Open%20Collective-7FADF2?logo=opencollective" alt="Sponsor on Open Collective"></a>

---

## License

Licensed under the **Apache License, Version 2.0**.

**Why Apache 2.0?**
- ✅ **Patent protection** - Critical for ML algorithms and production use
- ✅ **Enterprise-friendly** - Clear legal framework for commercial adoption
- ✅ **Industry standard** - Same as TensorFlow, battle-tested in ML ecosystem
- ✅ **Contributor protection** - Explicit patent grant and termination clauses

See [LICENSE](LICENSE) file for full terms.

---

## FAQ

**Q: Why not use Gorgonia?**
A: Gorgonia is great but uses a different approach. Born focuses on modern Go (generics), pure Go (no CGO), and production-first design inspired by Burn.

**Q: Can I run LLMs with Born?**

Frequently Asked Questions