golifai

package module
v1.0.0 Latest Latest
Warning

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

 Go to latest Published: Jul 24, 2026 License: MIT Imports: 2 Imported by: 0

README

GoLifAI

Go Reference Go Version

GoLifAI is a production-grade, pure-Go AI/ML library.

From raw tensor operations and automatic differentiation to neural networks, classical ML, NLP, audio, vision, generative models, reinforcement learning, and HTTP/gRPC serving — with zero CGO, zero C bindings, and (for the core module) zero external dependencies.

Installation

go get github.com/chesslaw-tech/golifai

Or install only the sub-package you need:

go get github.com/chesslaw-tech/golifai/nn          # neural networks
go get github.com/chesslaw-tech/golifai/tensor       # tensors only
go get github.com/chesslaw-tech/golifai/ml/tree      # decision trees only

gRPC serving (separate module, brings in google.golang.org/grpc):

go get github.com/chesslaw-tech/golifai/serving/grpcpb

Quick Start

package main

import (
    "fmt"
    "math/rand"

    "github.com/chesslaw-tech/golifai"
    "github.com/chesslaw-tech/golifai/nn"
    "github.com/chesslaw-tech/golifai/tensor"
)

func main() {
    // ── Tensors ──────────────────────────────────────────────────────────
    t := golifai.Zeros[float64](3, 4)
    fmt.Println("shape:", t.Shape()) // [3 4]

    a, _ := tensor.New[float64]([]float64{1, 2, 3, 4}, 2, 2)
    b := tensor.Ones[float64](2, 2)
    c, _ := tensor.MatMul(a, b)
    fmt.Println("matmul:", c.Data())

    // ── Autograd ─────────────────────────────────────────────────────────
    x := golifai.NewVariable(tensor.Ones[float64](2, 2), true /*requires_grad*/)
    loss, _ := golifai.SumAll(x)
    loss.Backward()
    fmt.Println("grad:", x.Grad.Data()) // [1 1 1 1]

    // ── Neural network ───────────────────────────────────────────────────
    rng := rand.New(rand.NewSource(42))
    layer := nn.NewLinear(4, 2, true, rng)
    input := golifai.NewVariable(tensor.Ones[float64](1, 4), false)
    out, _ := layer.Forward(input)
    fmt.Println("linear output shape:", out.Shape()) // [1 2]

    // Adam optimizer
    opt := nn.NewAdam(layer.Parameters(), nn.DefaultAdamConfig())

    // One training step
    opt.ZeroGrad()
    out, _ = layer.Forward(input)
    sumLoss, _ := golifai.SumAll(out)
    sumLoss.Backward()
    opt.Step()
    fmt.Println("step complete — loss:", sumLoss.Data.Data()[0])
}

Sub-packages

Import path Description
golifai Root façade — common types + convenience constructors
golifai/tensor N-D generic tensors, broadcasting, BLAS-style ops
golifai/autograd Reverse-mode automatic differentiation
golifai/nn Layers, optimisers, seq2seq, Transformers, RoPE, ALiBi
golifai/ml/tree Decision trees and random forests
golifai/ml/svm Support vector machines
golifai/ml/knn k-nearest neighbours
golifai/ml/linear Linear and logistic regression
golifai/ml/ensemble Gradient boosting, bagging
golifai/ml/naive_bayes Gaussian Naïve Bayes
golifai/data Dataset loaders, CSV reader, data frame
golifai/data/dataframe Typed column-based data frame
golifai/nlp/tfidf TF-IDF vectoriser
golifai/nlp/tokenizer Unicode-aware tokeniser
golifai/nlp/vocab Vocabulary builder
golifai/nlp/embedding Dense word embeddings
golifai/audio/features FFT, MFCC, YIN pitch (F0) detection
golifai/audio/io WAV read/write
golifai/gen/image VAE, ConvVAE, GAN (generative image models)
golifai/gen/text Text generation utilities
golifai/vision/image Image data structures and pixel ops
golifai/vision/transforms Resize, crop, normalise
golifai/rl/agent RL agent interfaces
golifai/rl/replay Experience replay buffers
golifai/serving/http HTTP JSON inference server
golifai/serving/grpc JSON-RPC over TCP inference server
golifai/pipelines/train Training loop helpers
golifai/pipelines/eval Evaluation metrics
golifai/pipelines/distributed Multi-GPU all-reduce hooks
golifai/serving/grpcpb Real HTTP/2 gRPC server (separate module)

More Examples

import (
    "math/rand"
    "github.com/chesslaw-tech/golifai/nn"
    "github.com/chesslaw-tech/golifai/tensor"
    "github.com/chesslaw-tech/golifai/autograd"
)

rng := rand.New(rand.NewSource(0))
model, _ := nn.NewDeepTransformerSeq2Seq(
    32, 64, 128, 8, 256, 2, 4, 10000, rng,
)
// ...build srcSeq...
cfg := nn.BeamSearchConfig{BeamWidth: 4, MaxLen: 50, EOSToken: 2, LengthPenalty: 0.6}
tokens, score, _ := model.BeamSearch(srcSeq, sos, cfg)
HTTP inference server
import serving "github.com/chesslaw-tech/golifai/serving/http"

srv := serving.NewServer(serving.DefaultConfig(), myPredictor)
srv.ListenAndServe() // /v1/health, /v1/predict, /v1/batch_predict
YIN pitch detection
import "github.com/chesslaw-tech/golifai/audio/features"

cfg := features.DefaultPitchConfig(16000)
frames := features.YIN(signal, cfg)
for _, f := range frames {
    if f.Voiced {
        fmt.Printf("F0 = %.1f Hz\n", f.F0)
    }
}

Design Principles

  • Pure Go — no CGO, no C libraries, works on any GOOS/GOARCH.
  • Zero external deps (core module) — GPU stubs via build tags.
  • Race-clean — go test -race ./... always passes.
  • Idiomatic generics — tensor.Tensor[T] with DType constraint.
  • pkg.go.dev first — every exported symbol has a Go doc comment.

Contributing

git clone https://github.com/chesslaw-tech/golifai
cd golifai
go test ./...

To develop the serving/grpcpb sub-module locally, create a workspace (not committed):

go work init .
go work use ./serving/grpcpb

Publishing a new version

After pushing to GitHub:

# Tag the core module
git tag v1.0.0
git push origin v1.0.0

# Tag the grpcpb sub-module
git tag serving/grpcpb/v1.0.0
git push origin serving/grpcpb/v1.0.0

# Trigger pkg.go.dev indexing (optional — it will self-index within minutes)
GOPROXY=https://proxy.golang.org go list -m github.com/chesslaw-tech/golifai@v1.0.0
GOPROXY=https://proxy.golang.org go list -m github.com/chesslaw-tech/golifai/serving/grpcpb@v1.0.0

License

MIT © 2025 Chesslaw Tech

Documentation

Overview

Package golifai is a production-grade, pure-Go AI/ML library.

GoLifAI provides a complete machine-learning ecosystem — from raw tensor operations and automatic differentiation all the way up to neural networks, classical ML algorithms, data pipelines, NLP, vision, audio, generative models, reinforcement learning, and model serving — with zero CGO, zero C bindings, and (for the core module) zero external dependencies.

Sub-packages

Import the sub-package you need directly: 

import "github.com/chesslaw-tech/golifai/tensor"    // N-D tensors
import "github.com/chesslaw-tech/golifai/autograd"  // reverse-mode AD
import "github.com/chesslaw-tech/golifai/nn"        // neural-network layers
import "github.com/chesslaw-tech/golifai/ml/tree"   // decision trees
import "github.com/chesslaw-tech/golifai/serving"   // HTTP inference server
// … and so on for audio, data, gen, nlp, pipelines, rl, vision

The root golifai package re-exports the most commonly used types and constructors as a convenience façade so that simple programs only need one import.

Quick start 

package main

import (
    "fmt"
    "github.com/chesslaw-tech/golifai"
)

func main() {
    // Create a 2×3 float64 tensor
    t := golifai.Zeros[float64](2, 3)
    fmt.Println(t.Shape()) // [2 3]

    // Build an autograd variable and differentiate
    x := golifai.NewVariable(golifai.Ones[float64](2, 2), true)
    loss, _ := golifai.SumAll(x)
    loss.Backward()
    fmt.Println(x.Grad.Data()) // [1 1 1 1]
}

gRPC serving (optional, separate module)

Real HTTP/2 gRPC inference is available as a separate sub-module so the core library has zero external dependencies: 

go get github.com/chesslaw-tech/golifai/serving/grpcpb

Design principles

  • Pure Go: no CGO, no C libraries.
  • No external deps in the core: gpu stubs live behind build tags.
  • Idiomatic generics: [T constraints.Float] throughout the tensor API.
  • Race-detector clean: every package ships with parallel-safe tests.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Add 

func Add(a, b *autograd.Variable) (*autograd.Variable, error)

Add performs element-wise addition with broadcasting support. Equivalent to autograd.Add(a, b).

func MatMul 

func MatMul(a, b *autograd.Variable) (*autograd.Variable, error)

MatMul computes a matrix multiplication. Equivalent to autograd.MatMul(a, b).

func NewTensor 

func NewTensor[T tensor.Numeric](data []T, shape ...int) (*tensor.Tensor[T], error)

NewTensor creates a tensor from an existing flat data slice. The product of shape dimensions must equal len(data). Equivalent to tensor.New[T](data, shape...).

func NewVariable 

func NewVariable(t *tensor.Tensor[float64], requiresGrad bool) *autograd.Variable

NewVariable wraps a tensor in an autograd Variable. Set requiresGrad=true for any leaf that should accumulate gradients. Equivalent to autograd.NewVariable(t, requiresGrad).

func Ones 

func Ones[T tensor.Numeric](shape ...int) *tensor.Tensor[T]

Ones returns a new tensor filled with 1 values. Equivalent to tensor.Ones[T](shape...).

func SumAll 

func SumAll(v *autograd.Variable) (*autograd.Variable, error)

SumAll reduces all elements of a variable to a scalar. Differentiable: backward propagates 1 to every element. Equivalent to autograd.SumAll(v).

func Zeros 

func Zeros[T tensor.Numeric](shape ...int) *tensor.Tensor[T]

Zeros returns a new zero-valued tensor with the given shape. Equivalent to tensor.Zeros[T](shape...).

Types

This section is empty.

Source Files

View all Source files

Directories

Path Synopsis
_examples
cmd
Package cmd provides command-line tools for training and serving goml models.
 Package cmd provides command-line tools for training and serving goml models.
cmd/serve command
Command serve starts a production-grade HTTP inference server backed by the serving/http package.
 Command serve starts a production-grade HTTP inference server backed by the serving/http package.
cmd/train command
Command train provides a config-driven training CLI for goml neural networks.
 Command train provides a config-driven training CLI for goml neural networks.
examples/distributed command
Distributed training example — gradient all-reduce using distributed.Default.
 Distributed training example — gradient all-reduce using distributed.Default.
examples/nlp command
Command nlp demonstrates sentiment analysis on a synthetic 1000-document corpus using TF-IDF vectorisation + Logistic Regression from the goml NLP and ML packages.
 Command nlp demonstrates sentiment analysis on a synthetic 1000-document corpus using TF-IDF vectorisation + Logistic Regression from the goml NLP and ML packages.
examples/rl command
Command rl demonstrates tabular Q-Learning and Deep Q-Network (DQN) on a 5×5 GridWorld with obstacles.
 Command rl demonstrates tabular Q-Learning and Deep Q-Network (DQN) on a 5×5 GridWorld with obstacles.
examples/tabular command
Command tabular demonstrates multi-class classification on a 100-row Iris-like dataset using logistic regression and a decision tree from the ml package.
 Command tabular demonstrates multi-class classification on a 100-row Iris-like dataset using logistic regression and a decision tree from the ml package.
examples/vision command
Command vision demonstrates digit classification on a synthetic MNIST-subset (100 grayscale 8×8 images, 10 classes 0-9) using a two-layer MLP from the nn package, trained with cross-entropy loss and Adam.
 Command vision demonstrates digit classification on a synthetic MNIST-subset (100 grayscale 8×8 images, 10 classes 0-9) using a two-layer MLP from the nn package, trained with cross-entropy loss and Adam.
audio
features
Package features provides audio feature extraction.
 Package features provides audio feature extraction.
io
Package io provides WAV audio file reading and writing.
 Package io provides WAV audio file reading and writing.
models
Package models provides audio deep learning models.
 Package models provides audio deep learning models.
Package autograd — differentiable Concat and axis-wise reductions.
 Package autograd — differentiable Concat and axis-wise reductions.
Package data provides dataset abstractions, dataloaders, and DataFrame utilities.
 Package data provides dataset abstractions, dataloaders, and DataFrame utilities.
dataframe
Package dataframe provides a typed, column-oriented DataFrame.
 Package dataframe provides a typed, column-oriented DataFrame.
transforms
Package transforms implements data transformation pipelines for tensor data.
 Package transforms implements data transformation pipelines for tensor data.
gen
image
Package image — Convolutional Variational Autoencoder.
 Package image — Convolutional Variational Autoencoder.
text
Package text implements text generation models.
 Package text implements text generation models.
ml
Package ml provides a comprehensive classical machine learning toolkit for Go, designed with a clean, type-safe API.
 Package ml provides a comprehensive classical machine learning toolkit for Go, designed with a clean, type-safe API.
cluster
Package cluster provides clustering algorithms.
 Package cluster provides clustering algorithms.
decompose
Package decompose provides dimensionality reduction algorithms.
 Package decompose provides dimensionality reduction algorithms.
ensemble
Package ensemble provides ensemble learning methods: random forests and gradient boosted trees.
 Package ensemble provides ensemble learning methods: random forests and gradient boosted trees.
knn
Package knn implements K-Nearest Neighbours classification and regression.
 Package knn implements K-Nearest Neighbours classification and regression.
linear
Package linear provides linear and logistic regression estimators.
 Package linear provides linear and logistic regression estimators.
model_selection
Package model_selection provides cross-validation and hyperparameter search.
 Package model_selection provides cross-validation and hyperparameter search.
naive_bayes
Package naive_bayes implements Gaussian, Multinomial, and Bernoulli Naive Bayes.
 Package naive_bayes implements Gaussian, Multinomial, and Bernoulli Naive Bayes.
pipeline
Package pipeline provides a composable ML pipeline.
 Package pipeline provides a composable ML pipeline.
preprocessing
Package preprocessing provides data preprocessing transformers.
 Package preprocessing provides data preprocessing transformers.
svm
Package svm implements Support Vector Machines via the Pegasos algorithm.
 Package svm implements Support Vector Machines via the Pegasos algorithm.
tree
Package tree implements CART decision trees for classification and regression.
 Package tree implements CART decision trees for classification and regression.
nlp
embedding
Package embedding implements dense word embeddings.
 Package embedding implements dense word embeddings.
pipeline
Package pipeline provides a composable NLP processing pipeline.
 Package pipeline provides a composable NLP processing pipeline.
tfidf
Package tfidf provides TF-IDF vectorisation for text.
 Package tfidf provides TF-IDF vectorisation for text.
tokenizer
Package tokenizer provides text tokenisation utilities.
 Package tokenizer provides text tokenisation utilities.
vocab
Package vocab provides vocabulary management for NLP tasks.
 Package vocab provides vocabulary management for NLP tasks.
Package nn — ALiBi (Attention with Linear Biases).
 Package nn — ALiBi (Attention with Linear Biases).
pipelines
checkpoint
Package checkpoint provides model checkpointing: saving and restoring model weights and training state to/from disk.
 Package checkpoint provides model checkpointing: saving and restoring model weights and training state to/from disk.
distributed
Package distributed provides hooks for multi-GPU and multi-worker training.
 Package distributed provides hooks for multi-GPU and multi-worker training.
eval
Package eval provides evaluation metrics for machine learning models.
 Package eval provides evaluation metrics for machine learning models.
tracking
Package tracking provides experiment tracking: logging metrics, hyperparameters, and artifacts to local files for later analysis.
 Package tracking provides experiment tracking: logging metrics, hyperparameters, and artifacts to local files for later analysis.
train
Package train — EarlyStopping and LRWarmupScheduler for the training loop.
 Package train — EarlyStopping and LRWarmupScheduler for the training loop.
rl
agent
Package agent implements reinforcement learning agents.
 Package agent implements reinforcement learning agents.
algo
Package algo implements deep reinforcement learning algorithms.
 Package algo implements deep reinforcement learning algorithms.
env
Package env defines the reinforcement learning environment interface.
 Package env defines the reinforcement learning environment interface.
replay
Package replay provides an experience replay buffer for reinforcement learning.
 Package replay provides an experience replay buffer for reinforcement learning.
serving
batch
Package batch provides asynchronous batch prediction with a queue.
 Package batch provides asynchronous batch prediction with a queue.
config
Package config provides configuration management for the serving layer.
 Package config provides configuration management for the serving layer.
grpc
Package grpc provides a pure-Go JSON-RPC inference server using net/rpc/jsonrpc.
 Package grpc provides a pure-Go JSON-RPC inference server using net/rpc/jsonrpc.
http
Package http provides an HTTP inference server for ML models.
 Package http provides an HTTP inference server for ML models.
Package tensor provides a high-performance, type-safe n-dimensional array implementation for Go.
 Package tensor provides a high-performance, type-safe n-dimensional array implementation for Go.
vision
image
Package image provides pure-Go image data structures and I/O.
 Package image provides pure-Go image data structures and I/O.
models
Package models provides neural network architectures for computer vision.
 Package models provides neural network architectures for computer vision.
transforms
Package transforms implements image preprocessing transforms for computer vision.
 Package transforms implements image preprocessing transforms for computer vision.

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.