README
¶
kjarni-go
Text classification, embeddings, semantic search, and reranking for Go. No Python, no containers, no ONNX. One go get and you're running inference.
Kjarni inference engine
This go library uses the custom built Kjarni engine to do inference
Models download automatically on first use and are cached locally.
Classify
package main
import (
"fmt"
"github.com/olafurjohannsson/kjarni-go"
)
func main() {
c, _ := kjarni.NewClassifier("roberta-sentiment")
defer c.Close()
text := "I’m pretty sure there’s a lot more to life than being really, really, ridiculously good looking."
result, _ := c.Classify(text)
fmt.Printf("Label: %s\nScore: %.3f\n\nAll scores:\n", result.Label, result.Score)
for _, s := range result.AllScores {
fmt.Printf(" %s: %.3f\n", s.Label, s.Score)
}
}
Available models: distilbert-sentiment, roberta-sentiment, bert-sentiment-multilingual, distilroberta-emotion, roberta-emotions, toxic-bert
Embeddings
package main
import (
"fmt"
"github.com/olafurjohannsson/kjarni-go"
)
func main() {
e, _ := kjarni.NewEmbedder("minilm-l6-v2")
defer e.Close()
word1 := "doctor"
word2 := "physician"
sim, _ := e.Similarity(word1, word2)
fmt.Printf("Word 1: %s\nWord 2: %s\nSimilarity: %.1f%%\n", word1, word2, sim*100)
}
Available models: minilm-l6-v2 (384d), mpnet-base-v2 (768d), distilbert-base (768d)
Search
Index a directory and search using keyword (BM25), semantic (vector), or hybrid (both combined).
// index
idx, _ := kjarni.NewIndexer("minilm-l6-v2", kjarni.WithQuiet(true))
idx.Create("/path/to/index", []string{"/path/to/docs"})
idx.Close()
// search
s, _ := kjarni.NewSearcher("minilm-l6-v2", "", kjarni.WithQuiet(true))
defer s.Close()
results, _ := s.Search("/path/to/index", "how do returns work?", kjarni.Hybrid)
for _, r := range results {
fmt.Printf("%.4f: %s\n", r.Score, r.Text)
}
To enable cross-encoder reranking, pass a reranker model when creating the searcher:
s, _ := kjarni.NewSearcher("minilm-l6-v2", "minilm-l6-v2-cross-encoder", kjarni.WithQuiet(true))
Rerank
Score and sort documents by relevance to a query using a cross-encoder.
r, _ := kjarni.NewReranker(kjarni.WithQuiet(true))
defer r.Close()
docs := []string{
"The weather is nice today.",
"Machine learning is a branch of AI.",
"Deep learning uses neural networks.",
}
ranked, _ := r.Rerank("What is machine learning?", docs)
for _, result := range ranked {
fmt.Printf("[%d] %.2f %s\n", result.Index, result.Score, result.Document)
}
// or get only the top k
top, _ := r.RerankTopK("machine learning", docs, 1)
How it works
This package embeds a Rust inference engine as a shared library (.so on Linux, .dll on Windows). The library is extracted to a temp directory at runtime and loaded via purego — no cgo required.
The same engine powers the C# NuGet package, the CLI, and the WASM build.
Platform support
| OS | Arch | Status |
|---|---|---|
| Linux | amd64 | supported |
| Windows | amd64 | supported |
License
MIT
Documentation
¶
Overview ¶
Package kjarni provides text classification, embeddings, semantic search, and reranking using pre-trained transformer models. No Python, no ONNX, no containers. Models download automatically on first use.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CosineSimilarity ¶
CosineSimilarity computes cosine similarity between two vectors in Go.
Types ¶
type Classifier ¶
type Classifier struct {
// contains filtered or unexported fields
}
Classifier runs text classification using a pre-trained model.
func NewClassifier ¶
func NewClassifier(model string, opts ...Option) (*Classifier, error)
NewClassifier creates a classifier for the given model. Available models: distilbert-sentiment, roberta-sentiment, bert-sentiment-multilingual, distilroberta-emotion, roberta-emotions, toxic-bert. Models download automatically on first use and are cached locally.
func (*Classifier) Classify ¶
func (c *Classifier) Classify(text string) (*ClassifyResult, error)
Classify runs the model on the given text and returns scored labels.
func (*Classifier) Close ¶
func (c *Classifier) Close() error
Close releases the classifier resources. Safe to call multiple times.
func (*Classifier) NumLabels ¶
func (c *Classifier) NumLabels() int
NumLabels returns the number of labels the model supports.
type ClassifyResult ¶
type ClassifyResult struct {
Label string
Score float32
AllScores []LabelScore
}
ClassifyResult holds the output of a classification. Label and Score contain the top prediction. AllScores contains scores for every label.
func (*ClassifyResult) String ¶
func (r *ClassifyResult) String() string
String returns the result as "label (score%)".
func (*ClassifyResult) ToJSON ¶
func (r *ClassifyResult) ToJSON() string
ToJSON returns the result as a JSON string.
type Embedder ¶
type Embedder struct {
// contains filtered or unexported fields
}
Embedder encodes text into vector embeddings for similarity and search.
func NewEmbedder ¶
NewEmbedder creates an embedder for the given model. Available models: minilm-l6-v2 (384d), mpnet-base-v2 (768d), distilbert-base (768d). Models download automatically on first use and are cached locally.
func (*Embedder) EncodeBatch ¶
EncodeBatch encodes multiple texts and returns their embedding vectors.
type ErrorCode ¶
type ErrorCode int32
ErrorCode represents error codes returned by the kjarni engine.
const ( ErrOk ErrorCode = 0 ErrNullPointer ErrorCode = 1 ErrInvalidUtf8 ErrorCode = 2 ErrModelNotFound ErrorCode = 3 ErrLoadFailed ErrorCode = 4 ErrInferenceFailed ErrorCode = 5 ErrInvalidConfig ErrorCode = 7 ErrCancelled ErrorCode = 8 ErrTimeout ErrorCode = 9 ErrStreamEnded ErrorCode = 10 ErrUnknown ErrorCode = 255 )
type IndexStats ¶
type IndexStats struct {
DocumentsIndexed int
ChunksCreated int
Dimension int
SizeBytes uint64
FilesProcessed int
FilesSkipped int
ElapsedMs uint64
}
IndexStats holds statistics from an indexing operation.
type Indexer ¶
type Indexer struct {
// contains filtered or unexported fields
}
Indexer creates search indexes from files in a directory.
func NewIndexer ¶
NewIndexer creates an indexer using the given embedding model. The model is used to generate vectors for each text chunk during indexing.
type KjarniError ¶
KjarniError is an error returned by the kjarni engine.
func (*KjarniError) Error ¶
func (e *KjarniError) Error() string
type LabelScore ¶
LabelScore is a single label with its confidence score.
type Option ¶
type Option func(*options)
Option configures a classifier, embedder, or other kjarni component.
func WithDevice ¶
WithDevice sets the compute device. Supported values: "cpu", "gpu".
type RerankResult ¶
RerankResult holds a single reranked document with its relevance score.
type Reranker ¶
type Reranker struct {
// contains filtered or unexported fields
}
Reranker scores query-document relevance using a cross-encoder model.
func NewReranker ¶
NewReranker creates a reranker using the default cross-encoder model. The model downloads automatically on first use and is cached locally.
func (*Reranker) Rerank ¶
func (r *Reranker) Rerank(query string, documents []string) ([]RerankResult, error)
Rerank scores all documents and returns them sorted by relevance to the query.
func (*Reranker) RerankTopK ¶
RerankTopK scores all documents and returns the top k sorted by relevance.
type SearchMode ¶
type SearchMode int
SearchMode determines the search strategy.
const ( // Keyword uses BM25 term matching. Keyword SearchMode = 0 // Semantic uses vector similarity. Semantic SearchMode = 1 // Hybrid combines BM25 and vector similarity. Hybrid SearchMode = 2 )
type SearchResult ¶
SearchResult holds a single search result with its relevance score.
type Searcher ¶
type Searcher struct {
// contains filtered or unexported fields
}
Searcher queries indexes created by an Indexer.
func NewSearcher ¶
NewSearcher creates a searcher using the given embedding model. Pass a non-empty rerankerModel to enable cross-encoder reranking of results. Pass an empty string to disable reranking.
func (*Searcher) Search ¶
func (s *Searcher) Search(indexPath string, query string, mode SearchMode) ([]SearchResult, error)
Search queries the index at indexPath and returns results using the given mode.
Source Files
Directories