Documentation
¶
Overview ¶
Package embed provides a pluggable embedding layer for the knowledge graph.
It defines the Embedder interface and provides implementations for Ollama (local-first) and any OpenAI-compatible API. Configuration is driven by Viper, and an optional content-hash cache avoids redundant embedding calls.
Index ¶
- type CachedEmbedder
- func (c *CachedEmbedder) Clear()
- func (c *CachedEmbedder) Dimensions() int
- func (c *CachedEmbedder) Embed(ctx context.Context, text string) ([]float32, error)
- func (c *CachedEmbedder) EmbedBatch(ctx context.Context, texts []string) ([][]float32, error)
- func (c *CachedEmbedder) Len() int
- func (c *CachedEmbedder) ModelName() string
- type Config
- type Embedder
- type HugotEmbedder
- type OllamaEmbedder
- type OpenAICompatibleEmbedder
- func (o *OpenAICompatibleEmbedder) Dimensions() int
- func (o *OpenAICompatibleEmbedder) Embed(ctx context.Context, text string) ([]float32, error)
- func (o *OpenAICompatibleEmbedder) EmbedBatch(ctx context.Context, texts []string) ([][]float32, error)
- func (o *OpenAICompatibleEmbedder) ModelName() string
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type CachedEmbedder ¶
type CachedEmbedder struct {
// contains filtered or unexported fields
}
CachedEmbedder wraps any Embedder with an in-memory content-hash cache. Cache keys are SHA-256(model + "\x00" + text) so that different models produce distinct cache entries for the same text.
func NewCachedEmbedder ¶
func NewCachedEmbedder(inner Embedder) *CachedEmbedder
NewCachedEmbedder wraps an existing Embedder with caching.
func (*CachedEmbedder) Clear ¶
func (c *CachedEmbedder) Clear()
Clear removes all entries from the cache.
func (*CachedEmbedder) Dimensions ¶
func (c *CachedEmbedder) Dimensions() int
Dimensions delegates to the inner Embedder.
func (*CachedEmbedder) EmbedBatch ¶
EmbedBatch returns cached embeddings where available and batches the remaining texts through the inner Embedder.
func (*CachedEmbedder) Len ¶
func (c *CachedEmbedder) Len() int
Len returns the number of entries currently in the cache.
func (*CachedEmbedder) ModelName ¶
func (c *CachedEmbedder) ModelName() string
ModelName delegates to the inner Embedder.
type Config ¶
type Config struct {
// Embedder selects the backend: "ollama" or "openai-compatible".
Embedder string
// Model is the embedding model name (e.g. "nomic-embed-text").
Model string
// URL is the base URL for the embedding service.
URL string
// APIKey is the bearer token for authenticated APIs (optional for Ollama).
APIKey string
// Dimensions overrides the expected vector dimensionality.
// When zero the embedder auto-detects from the first response.
Dimensions int
// CacheEnabled turns on the content-hash embedding cache.
CacheEnabled bool
}
Config holds all embedder-related settings.
func LoadConfig ¶
func LoadConfig() Config
LoadConfig reads embedder configuration from Viper.
Environment variables (prefix KNOWN_):
KNOWN_EMBEDDER - "hugot" (default), "ollama", or "openai-compatible" KNOWN_EMBED_MODEL - model name (default: sentence-transformers/all-MiniLM-L6-v2) KNOWN_EMBED_URL - base URL KNOWN_EMBED_API_KEY - API key / bearer token KNOWN_EMBED_DIMENSIONS - override vector dimensions KNOWN_EMBED_CACHE - "true" to enable caching
type Embedder ¶
type Embedder interface {
// Embed returns the embedding vector for a single text string.
Embed(ctx context.Context, text string) ([]float32, error)
// EmbedBatch returns embedding vectors for multiple texts.
// Implementations should batch the request when the backend supports it.
EmbedBatch(ctx context.Context, texts []string) ([][]float32, error)
// Dimensions returns the dimensionality of the embedding vectors
// produced by the underlying model.
Dimensions() int
// ModelName returns the identifier of the model used for embedding.
ModelName() string
}
Embedder generates vector embeddings from text.
func NewEmbedder ¶
NewEmbedder creates an Embedder from the current Viper configuration. It reads KNOWN_EMBEDDER to select the backend and delegates to the appropriate constructor.
type HugotEmbedder ¶
type HugotEmbedder struct {
// contains filtered or unexported fields
}
HugotEmbedder produces embeddings using a local ONNX model via hugot's pure Go backend (GoMLX). No external services or CGo required.
func NewHugotEmbedder ¶
func NewHugotEmbedder(cfg Config) (*HugotEmbedder, error)
NewHugotEmbedder creates an embedder that runs a sentence-transformer model locally using hugot's pure Go inference backend.
On first use the model is downloaded from Hugging Face to ~/.known/models/.
func (*HugotEmbedder) Destroy ¶
func (h *HugotEmbedder) Destroy()
Destroy releases the hugot session resources.
func (*HugotEmbedder) Dimensions ¶
func (h *HugotEmbedder) Dimensions() int
Dimensions returns the vector dimensionality. May return 0 until the first embedding call if not configured up front.
func (*HugotEmbedder) EmbedBatch ¶
EmbedBatch returns embedding vectors for multiple texts.
func (*HugotEmbedder) ModelName ¶
func (h *HugotEmbedder) ModelName() string
ModelName returns the Hugging Face model identifier.
type OllamaEmbedder ¶
type OllamaEmbedder struct {
// contains filtered or unexported fields
}
OllamaEmbedder produces embeddings via the Ollama REST API.
Ollama endpoint: POST <baseURL>/api/embed
Request: {"model": "...", "input": "..." | ["...", ...]}
Response: {"model": "...", "embeddings": [[...]]}
func NewOllamaEmbedder ¶
func NewOllamaEmbedder(cfg Config) (*OllamaEmbedder, error)
NewOllamaEmbedder creates an Embedder that talks to a local Ollama instance.
func (*OllamaEmbedder) Dimensions ¶
func (o *OllamaEmbedder) Dimensions() int
Dimensions returns the vector dimensionality. If not configured up front, this is detected from the first successful embedding call and may return 0 until then.
func (*OllamaEmbedder) EmbedBatch ¶
EmbedBatch returns embeddings for multiple texts in a single API call.
func (*OllamaEmbedder) ModelName ¶
func (o *OllamaEmbedder) ModelName() string
ModelName returns the Ollama model identifier.
type OpenAICompatibleEmbedder ¶
type OpenAICompatibleEmbedder struct {
// contains filtered or unexported fields
}
OpenAICompatibleEmbedder produces embeddings via any OpenAI-compatible /v1/embeddings endpoint (OpenAI, Azure OpenAI, vLLM, LiteLLM, etc.).
Endpoint: POST <baseURL>/v1/embeddings
Request: {"model": "...", "input": ["...", ...]}
Response: {"data": [{"embedding": [...], "index": 0}], "model": "..."}
func NewOpenAICompatibleEmbedder ¶
func NewOpenAICompatibleEmbedder(cfg Config) (*OpenAICompatibleEmbedder, error)
NewOpenAICompatibleEmbedder creates an Embedder backed by an OpenAI-compatible embedding API.
func (*OpenAICompatibleEmbedder) Dimensions ¶
func (o *OpenAICompatibleEmbedder) Dimensions() int
Dimensions returns the vector dimensionality. Like OllamaEmbedder, this may be auto-detected from the first response.
func (*OpenAICompatibleEmbedder) EmbedBatch ¶
func (o *OpenAICompatibleEmbedder) EmbedBatch(ctx context.Context, texts []string) ([][]float32, error)
EmbedBatch returns embeddings for multiple texts in a single API call.
func (*OpenAICompatibleEmbedder) ModelName ¶
func (o *OpenAICompatibleEmbedder) ModelName() string
ModelName returns the configured model identifier.
Source Files