go-bayes

go-bayes

github.com/KEINOS/go-bayes/bayes is a Bayesian inference package for Go.

It learns ordered sequences and predicts the value that is likely to come next. The current model is a Folded Context Transition Predictor (FCTP).

[!IMPORTANT] The API can change before the first stable release. The latest published release is v0.0.4. Until v1.0.0, a clear API, ease of use, and measured performance are more important than backward compatibility.

Quick Start

Install the module:

go get github.com/KEINOS/go-bayes@latest

Use the package:

import "github.com/KEINOS/go-bayes/bayes"

String Sequence

Train a sequence and predict its next value.

ctx := context.Background()
const datasetID uint64 = 100
predictor, err := bayes.New(ctx, bayes.MemoryStorage, datasetID)
if err != nil {
 log.Fatal(err)
}
defer predictor.Close()

melody := []string{
 "So", "So", "La", "So", "Do", "Si",
 "So", "So", "La", "So", "Re", "Do",
}

err = predictor.Train(ctx, melody)
if err != nil {
 log.Fatal(err)
}

classID, err := predictor.Predict(ctx, []string{"So", "So", "La", "So", "Do", "Si"})
if err != nil {
 log.Fatal(err)
}

fmt.Println(predictor.GetClass(classID))
// Output: So

View the complete source, or run it online.

Integer Sequence

The same API accepts discrete integer values. This example learns HTTP status history and predicts recovery after rate limiting and a temporary outage.

ctx := context.Background()
const datasetID uint64 = 101
predictor, err := bayes.New(ctx, bayes.MemoryStorage, datasetID)
if err != nil {
 log.Fatal(err)
}
defer predictor.Close()

statusHistory := []int{
 http.StatusOK,
 http.StatusCreated,
 http.StatusNoContent,
 http.StatusOK,
 http.StatusTooManyRequests,
 http.StatusServiceUnavailable,
 http.StatusOK,
 http.StatusCreated,
 http.StatusNoContent,
 http.StatusOK,
 http.StatusTooManyRequests,
 http.StatusServiceUnavailable,
 http.StatusOK,
}

err = predictor.Train(ctx, statusHistory)
if err != nil {
 log.Fatal(err)
}

classID, err := predictor.Predict(ctx, []int{
 http.StatusOK,
 http.StatusTooManyRequests,
 http.StatusServiceUnavailable,
})
if err != nil {
 log.Fatal(err)
}

fmt.Println(predictor.GetClass(classID))
// Output: 200

View the complete source, or run it online.

[!NOTE]

• New creates an isolated predictor backed by in-memory storage and uses xxHash3 for value and context IDs by default.
• A Predictor is not safe for concurrent use; callers must synchronize shared access.

More Examples

A context can be a time sequence or an ordered set of features. The examples overview links to runnable programs for both uses:

• Melody: Predict the next note in a string sequence.
• HTTP status: Predict the next status in an integer sequence.
• Iris: Predict a species from four ordered measurements.
• Wine: Predict a cultivar class from 13 ordered measurements.
• Mushroom: Predict the edible or poisonous class from 22 ordered categorical features.

The Go Reference examples provide shorter examples for melody, Iris, New, WithHasher, and Storage.Type.

Features and Behavior

The predictor learns transitions from an ordered context to a possible next value. It uses learned probabilities to select the most likely class for the supplied context. This is Bayesian inference, but it is not a Naive Bayes classifier.

Its current model is a Folded Context Transition Predictor (FCTP). It converts each value to a fixed-width ID and folds an ordered context of any supported length into one context ID. GetClass resolves the predicted class ID to the original value recorded during training.

Training A -> B -> C -> D records the suffix contexts that lead to D:

FOLD(C)       -> D
FOLD(B, C)    -> D
FOLD(A, B, C) -> D

Context order matters. The predictor matches exact folded IDs. It does not measure similarity between values or retry shorter contexts when the complete context is unknown.

Supported Values

Train, Predict, and HashTrans accept slices or values composed of these built-in types:

• bool and string;
• int, int16, int32, and int64;
• uint, uint16, uint32, and uint64;
• float32 and float64.

Each value is encoded with its Go type before it is hashed. For example, true, int(1), uint64(1), and float64(1) have different IDs. Integer signs and floating-point fractions are preserved.

IDs are deterministic identifiers, not collision-free or reversible encodings. Training fails with ErrHashCollision instead of replacing a class when two class values produce the same ID. GetClass depends on the predictor's class map and returns nil for an unknown class ID.

Hashers

xxHash3 is the default algorithm for value and context IDs. Select BLAKE3 when you need BLAKE3-based IDs:

predictor, err := bayes.New(
 context.Background(),
 bayes.MemoryStorage,
 42,
 bayes.WithHasher("blake3"),
)

Use NewPredictor to inject a custom implementation of bayes.Hasher:

predictor, err := bayes.NewPredictor(context.Background(), bayes.PredictorConfig{
 Storage: bayes.MemoryStorage,
 ScopeID: 42,
 Hasher:  customHasher,
})

The selected hasher creates every value ID and context ID. It is fixed when the predictor is created. A custom hasher must return a stable, non-empty name for model-file compatibility.

Model Storage

Memory storage is the simplest choice for a short-lived predictor. Save its complete state as a portable SQLite model file:

err := predictor.Save(ctx, "model.db")

Load copies a saved model into memory. Open operates directly on the model file and keeps new training data there:

inMemory, err := bayes.Load(ctx, "model.db")
onDisk, err := bayes.Open(ctx, "model.db")

Call Close for every predictor. A directly opened model has exclusive lifetime ownership, so another cooperating process cannot open or replace the same path until it is closed.

Create a new file-backed model with SQLiteStorage:

predictor, err := bayes.New(
 ctx,
 bayes.SQLiteStorage,
 datasetID,
 bayes.WithSQLitePath("model.db"),
)

SQLite support uses github.com/mattn/go-sqlite3 and requires cgo. Builds with CGO_ENABLED=0 can use memory storage, but Save, Load, Open, and SQLiteStorage return ErrSQLiteUnavailable.

Model files preserve exact supported Go value types, transition counts, scope, codec version, and hasher identity. A custom-hasher model can be loaded only when the same compatible Hasher is supplied. JSON model persistence is no longer supported.

Train and Reset are atomic store operations. Reset clears learned transitions and classes but keeps the current storage backend, scope, and hasher.

Technical Details

Read the technical specification for the two-ID learning model, token IDs, context folding, suffix expansion, Bayesian scoring, class recovery, and current design limits.

Contributing

Contributor resources:

• Contributing guide: Implementation details and validation commands.
• Security policy: How to report a vulnerability.
• Issues and roadmap: Bugs, feature requests, and planned work.

License

go-bayes is available under the MIT License.