gopherml

README

🐹 GopherML 🚀

Native Go machine learning: low-latency inference, zero dependencies, scikit-learn-style API.

GopherML is a machine learning library written entirely in Go, designed to provide ultra-fast training and inference tools using native concurrency (goroutines) and without Cgo or external dependencies. It follows Python’s scikit-learn architecture and API, adapted for cryptocurrency bots and high-frequency inference.

---

📑 Table of contents

1. Features
2. Installation
3. Getting started
4. Packages
5. Tests and CI
6. Repository structure
7. Documentation
8. Examples
9. Subproject: go-nlp
10. Roadmap
11. Design metrics
12. Contributing and license

---

1. Features

• ⚡ Low-latency inference: PredictSingle and PredictProbaSingle are optimized for bot hot paths (zero extra allocations per tick).
• 🧩 scikit-learn-style API: NewModel() → Fit(X, y) → Predict(X) → Score(X, y). If you already use scikit-learn, you'll feel at home.
• 🌊 Native concurrency: parallel training of Random Forest, GridSearchCV and linear algebra with goroutines and sync.WaitGroup — without Cgo.
• 🛡️ Strict validation: All input data is validated against NaN/Inf (utils.CheckFinite) before touching a model. It never fails in silence.
• 💾 Persistence with integrity: Save/Load in gob format, with automatic post-load validation via the persistence.Validator interface.
• 📈 Complete metrics: Accuracy, Precision, Recall, F1, R², MAE, MSE, RMSE, and ROC-AUC.
• 🪙 Crypto pipeline: the crypto/ package encapsulates the complete flow OHLCV → features → trading signal (Hold/Long/Short).
• 🚫 Zero dependencies: only the Go standard library. No NumPy, no CGO, no bindings.

---

2. Installation

Requirements: Go 1.23 or higher.

As a module published on GitHub

go get github.com/ateto3/gopherml@latest

As a local dependency (development)

Add a replace in your project's go.mod:

module github.com/your-user/your-bot

go 1.23

require github.com/ateto3/gopherml v0.0.0

replace github.com/ateto3/gopherml => /path/to/GopherML

Then run:

go mod tidy

---

3. Getting started

Complete binary classification with Random Forest:

package main

import (
	"fmt"
	"log"

	"github.com/ateto3/gopherml/ensemble"
	"github.com/ateto3/gopherml/preprocessing"
)

func main() {
	// Data: [length, width] → label 0 or 1
	X := [][]float64{
		{1.0, 2.0}, {1.5, 1.8}, {1.2, 2.5}, {1.1, 1.9},
		{5.0, 6.0}, {5.5, 5.8}, {5.2, 6.5}, {4.9, 5.9},
	}
	y := []float64{0, 0, 0, 0, 1, 1, 1, 1}

	// 1. Scale the data (essential for linear models)
	scaler := preprocessing.NewStandardScaler()
	Xs, err := scaler.FitTransform(X)
	if err != nil {
		log.Fatal(err)
	}

	// 2. Train
	rf := ensemble.NewRandomForestClassifier()
	rf.NEstimators = 100
	rf.MaxDepth = 5
	rf.RandomState = 42
	if err := rf.Fit(Xs, y); err != nil {
		log.Fatal(err)
	}

	// 3. Predict (batch)
	preds, err := rf.Predict(Xs)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("Predictions:", preds) // [0 0 0 0 1 1 1 1]

	// 4. Evaluate
	acc, err := rf.Score(Xs, y)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("Accuracy: %.2f%%\n", acc*100)

	// 5. Hot path: single sample, no batch overhead
	label, err := rf.PredictSingle([]float64{5.1, 6.1})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("Single sample:", label)
}

Full pipeline for crypto bots (OHLCV → signal):

cfg := crypto.DefaultPredictorConfig()
cfg.WindowSize = 20
cfg.MinConfidence = 0.65

p := crypto.NewCryptoPredictor(cfg)
if err := p.LoadModel("btcusdt_1h_rf.gob"); err != nil {
	log.Fatal(err)
}

signal, confidence, err := p.PredictSignal(lastCandles) // len(lastCandles) == WindowSize
if err == nil && confidence >= cfg.MinConfidence {
	// signal: crypto.SignalHold | crypto.SignalLong | crypto.SignalShort
	_ = signal
}

See USAGE.md for the full guide with trading examples.

---

4. Packages

Package	Description
/crypto	Crypto pipeline: OHLCV → feature engineering → trading signal (CryptoPredictor)
/linear_model	LinearRegression, Ridge, Lasso, ElasticNet, LogisticRegression, SGDClassifier + parallel versions
/tree	DecisionTreeClassifier and DecisionTreeRegressor (CART; Gini, Entropy, and MSE criteria)
/ensemble	RandomForestClassifier and RandomForestRegressor (parallel training with bootstrap)
/metrics	Accuracy, Precision, Recall, F1, R², MAE, MSE, RMSE, ROC-AUC, reports, and confusion matrix
/model_selection	KFold, CrossValScore, and parallel GridSearchCV
/preprocessing	StandardScaler, MinMaxScaler, LabelEncoder, PolynomialFeatures
/persistence	Model Save/Load with post-load integrity validation
/utils	Data validation (CheckXy, CheckFinite), TrainTestSplit, LoadCSV, deterministic RNG
/examples	Executable end-to-end examples

---

---

5. Tests and CI

# Build everything
go build ./...

# Analyze code (must be clean)
go vet ./...

# Tests with race detector
go test ./... -race

# Format (recommended before a PR)
gofmt -w .

Current status: all packages in green and clean go vet. Each push runs the CI workflow (go vet + go test -race).

---

6. Repository structure

GopherML/
├── README.md              # This file
├── USAGE.md               # Usage guide with crypto bot examples
├── EXPLAINING.md          # Architecture and internal logic
├── CONTRIBUTING.md        # How to contribute (includes AI guidelines)
├── CHANGELOG.md           # Change history
├── docs/                  # Extended documentation (guides, API, FAQ)
├── crypto/                # OHLCV → features → signal pipeline
├── ensemble/              # Random Forest
├── linear_model/          # Linear models and SGD
├── tree/                  # CART decision trees
├── metrics/               # Evaluation metrics
├── model_selection/       # Cross-validation and grid search
├── preprocessing/         # Scaling and encoding
├── persistence/           # Save/load models (gob)
├── utils/                 # Data validation and utilities
├── examples/              # Executable examples
├── go-nlp/                # Submodule: concurrent NLP (NLTK port)
└── .github/               # Issue/PR templates and CI

---

7. Documentation

Document	Content
docs/GETTING_STARTED.md	Step-by-step tutorial from scratch
USAGE.md	Usage guide with crypto bot examples
docs/API_REFERENCE.md	API reference for all packages
EXPLAINING.md	Architecture and internal logic
docs/ARCHITECTURE.md	Detailed architecture and design decisions
docs/PERFORMANCE.md	Performance guide and optimizations
docs/FAQ.md	Frequently asked questions
CONTRIBUTING.md	Contribution guide and code standards
CHANGELOG.md	Change history

Full index in docs/README.md.

---

8. Examples

All examples are executable programs (package main):

# Classification with Random Forest + metrics + cross-validation
go run examples/classification/basic_classification.go

# Regression: LinearRegression vs RandomForestRegressor
go run examples/regression/basic_regression.go

# Crypto pipeline: synthetic OHLCV → signal → persistence
go run examples/crypto/crypto_trading_bot.go

# Save and load a trained model
go run examples/persistence/model_persistence.go

# Parallel hyperparameter search with GridSearchCV
go run examples/grid_search/hyperparameter_tuning.go

# Preprocessing pipeline with scalers and encoder
go run examples/preprocessing/preprocessing_pipeline.go

Details in examples/README.md.

---

9. Subproject: go-nlp

The go-nlp/ directory contains a ** standalone Go module ** (github.com/ateto3/gopherml/go-nlp): a concurrent NLTK port with tokenization, POS tagging, parsing, text classification and sentiment analysis, plus token optimization for LLM APIs.

⚠️ go-nlp has its own go.mod: it is independently compiled and tested with cd go-nlp && go build ./... && go test ./...

See go-nlp/README.md for full documentation.

---

10. Roadmap

• Basic ML models (linear regression, classification, trees, forests, ensembles)
• Model persistence (Save/Load with integrity validation)
• Evaluation metrics (accuracy, precision, recall, F1, R², MAE, RMSE)
• Model selection and cross-validation (KFold, GridSearchCV)
• Data preprocessing (StandardScaler, MinMaxScaler, LabelEncoder)
• NaN/Inf validation on all input data
• PredictProba + PredictSingle for high-frequency bots
• crypto/ package — OHLCV → features → trading signal pipeline
• GradientBoosting (XGBoost-like)
• Streaming data support (online updates)

---

11. Design metrics

Objective	Specification
Language	Go 1.23+
Module	github.com/ateto3/gopherml
Target	Low latency inference/crypto bots
Hardware	Optimized for ARM64 (Raspberry Pi 4) and x86_64
Dependencies	Zero (Go stdlib only)
Tests	go test ./... -race — 100% green tests

---

12. Contributing and license

Contributions are welcome! Read CONTRIBUTING.md for workflow, code standards, and performance guidelines (including guidelines for AI assistants). Before sending a PR, make sure they pass:

go vet ./... && go test ./... -race

This project is licensed under mit — see LICENSE.

---

Developer

The code must be modular so that it can be easily imported into other Go binaries or automation microservices.

"The code must be so fast that Go's garbage collector doesn't even know we're here."