kjarni

package module
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: Sep 8, 2026 License: Apache-2.0 Imports: 11 Imported by: 0

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 Demo

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)

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, running inside your process against a native library. Models download automatically on first use and are cached on disk, so everything after that works offline.

The same engine ships for other runtimes: Kjarni on NuGet for C#, kjarni-wasm on npm for the browser, and a command line binary. Documentation and guides live at https://kjarni.ai and the source is at https://github.com/olafurjohannsson/kjarni

Getting started 

import "github.com/olafurjohannsson/kjarni-go"

emb, err := kjarni.NewEmbedder("minilm-l6-v2")
if err != nil {
	log.Fatal(err)
}
defer emb.Close()

vec, err := emb.Encode("hello world")

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func CosineSimilarity 

func CosineSimilarity(a, b []float32) float32

CosineSimilarity computes cosine similarity between two vectors in Go.

Types

type Chat added in v0.1.9 

type Chat struct {
	// contains filtered or unexported fields
}

func NewChat added in v0.1.9 

func NewChat(model string, opts ...interface{}) (*Chat, error)

func (*Chat) Close added in v0.1.9 

func (c *Chat) Close() error

releases the Chat resources

func (*Chat) ContextSize added in v0.1.9 

func (c *Chat) ContextSize() int

returns the model's context window size

func (*Chat) Conversation added in v0.1.9 

func (c *Chat) Conversation() (*ChatConversation, error)

create a stateful conversation with history management

func (*Chat) ModelName added in v0.1.9 

func (c *Chat) ModelName() string

returns model name

func (*Chat) Send added in v0.1.9 

func (c *Chat) Send(message string) (string, error)

sends a message and returns the full response, blocking

func (*Chat) SendWithConfig added in v0.1.9 

func (c *Chat) SendWithConfig(message string, config *GenerationConfig) (string, error)

sends a message with custom generation config

func (*Chat) Stream added in v0.1.9 

func (c *Chat) Stream(message string, onToken func(token string) bool) error

Stream sends a message and calls onToken for each generated token. Return false from onToken to stop generation.

func (*Chat) StreamWithConfig added in v0.1.9 

func (c *Chat) StreamWithConfig(message string, config *GenerationConfig, onToken func(token string) bool) error

streams with custom generation config.

type ChatConversation added in v0.1.9 

type ChatConversation struct {
	// contains filtered or unexported fields
}

ChatConversation maintains chat history parent Chat must outlive this object

func (*ChatConversation) Clear added in v0.1.9 

func (cc *ChatConversation) Clear(keepSystem bool)

clear the conversation history

func (*ChatConversation) Close added in v0.1.9 

func (cc *ChatConversation) Close() error

release the conversation resources

func (*ChatConversation) Length added in v0.1.9 

func (cc *ChatConversation) Length() int

returns the number of messages in history

func (*ChatConversation) Send added in v0.1.9 

func (cc *ChatConversation) Send(message string) (string, error)

Send sends a message and returns a response Both user message and response are added to history

func (*ChatConversation) SendWithConfig added in v0.1.9 

func (cc *ChatConversation) SendWithConfig(message string, config *GenerationConfig) (string, error)

send with custom generation config.

func (*ChatConversation) Stream added in v0.1.9 

func (cc *ChatConversation) Stream(message string, onToken func(token string) bool) error

streams a response. Message and full response are added to history

type ChatMode added in v0.1.9 

type ChatMode int32
const (
	ChatDefault   ChatMode = 0
	ChatCreative  ChatMode = 1
	ChatReasoning ChatMode = 2
)

type ChatOption added in v0.1.9 

type ChatOption func(*chatOptions)

func WithChatMode added in v0.1.9 

func WithChatMode(mode ChatMode) ChatOption

func WithSystemPrompt added in v0.1.9 

func WithSystemPrompt(prompt string) ChatOption

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 

func NewEmbedder(model string, opts ...Option) (*Embedder, error)

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) Close 

func (e *Embedder) Close() error

Close releases the embedder resources. Safe to call multiple times.

func (*Embedder) Dim 

func (e *Embedder) Dim() int

Dim returns the dimensionality of the embedding model.

func (*Embedder) Encode 

func (e *Embedder) Encode(text string) ([]float32, error)

Encode returns the embedding vector for the given text.

func (*Embedder) EncodeBatch 

func (e *Embedder) EncodeBatch(texts []string) ([][]float32, error)

EncodeBatch encodes multiple texts and returns their embedding vectors.

func (*Embedder) Similarity 

func (e *Embedder) Similarity(a, b string) (float32, error)

Similarity returns the cosine similarity between two texts, computed by the engine.

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
	ErrGpuUnavailable  ErrorCode = 6
	ErrInvalidConfig   ErrorCode = 7
	ErrCancelled       ErrorCode = 8
	ErrTimeout         ErrorCode = 9
	ErrStreamEnded     ErrorCode = 10
	// ErrPanic reports a panic in the native engine caught at the ABI boundary. The
	// operation failed and its outputs are undefined; the handle stays valid to Close.
	ErrPanic   ErrorCode = 11
	ErrUnknown ErrorCode = 255
)

type GenerationConfig added in v0.1.9 

type GenerationConfig struct {
	Temperature       float32
	TopK              int32
	TopP              float32
	MinP              float32
	RepetitionPenalty float32
	MaxNewTokens      int32
	DoSample          int32
}

func CreativeGenerationConfig added in v0.1.9 

func CreativeGenerationConfig() GenerationConfig

func DefaultGenerationConfig added in v0.1.9 

func DefaultGenerationConfig() GenerationConfig

func GreedyGenerationConfig added in v0.1.9 

func GreedyGenerationConfig() GenerationConfig

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 

func NewIndexer(model string, opts ...Option) (*Indexer, error)

NewIndexer creates an indexer using the given embedding model. The model is used to generate vectors for each text chunk during indexing.

func (*Indexer) Close 

func (idx *Indexer) Close() error

Close releases the indexer resources. Safe to call multiple times.

func (*Indexer) Create 

func (idx *Indexer) Create(indexPath string, inputs []string) (*IndexStats, error)

Create builds a new search index at indexPath from the given input directories. Files are chunked, embedded, and stored for later retrieval with a Searcher.

type KjarniError 

type KjarniError struct {
	Code    ErrorCode
	Message string
}

KjarniError is an error returned by the kjarni engine.

func (*KjarniError) Error 

func (e *KjarniError) Error() string

type LabelScore 

type LabelScore struct {
	Label string
	Score float32
}

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 

func WithDevice(device string) Option

WithDevice sets the compute device. Supported values: "cpu", "gpu".

func WithQuiet 

func WithQuiet(quiet bool) Option

WithQuiet suppresses log output during model loading and inference.

type RerankResult 

type RerankResult struct {
	Index    int
	Score    float32
	Document string
}

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 

func NewReranker(opts ...Option) (*Reranker, error)

NewReranker creates a reranker using the default cross-encoder model. The model downloads automatically on first use and is cached locally.

func (*Reranker) Close 

func (r *Reranker) Close() error

Close releases the reranker resources. Safe to call multiple times.

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 

func (r *Reranker) RerankTopK(query string, documents []string, k int) ([]RerankResult, error)

RerankTopK scores all documents and returns the top k sorted by relevance.

func (*Reranker) Score 

func (r *Reranker) Score(query, document string) (float32, error)

Score returns the relevance score for a single query-document pair.

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 

type SearchResult struct {
	Score float32
	Text  string
}

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 

func NewSearcher(model string, rerankerModel string, opts ...Option) (*Searcher, error)

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) Close 

func (s *Searcher) Close() error

Close releases the searcher resources. Safe to call multiple times.

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

View all Source files

Directories

Path Synopsis
examples
classify command
embed command
rerank command

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.