Documentation
¶
Overview ¶
Package embed provides interfaces and implementations for generating vector embeddings from text content. The primary implementation uses Ollama's HTTP API for local model inference.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func PrepareChunk ¶
PrepareChunk creates an embedding-ready chunk from block content by prepending the heading hierarchy context path. This provides semantic context for the embedding model — a block about "From Source" under "Installation" in "setup.md" becomes:
"setup.md > Installation > From Source\n\ncontent..."
Returns the formatted chunk string, truncated to maxChunkChars (~512 tokens) to fit within the embedding model's context window. Empty headings in the path are skipped. Uses rune-based truncation to avoid splitting multi-byte UTF-8 characters.
Design decision: Block-level chunking was chosen over page-level or fixed-size windows because blocks are the natural semantic units in a Markdown vault (Decision 4 in research.md). Each block has a stable UUID enabling incremental re-embedding when content changes.
Types ¶
type Embedder ¶
type Embedder interface {
// Embed generates a vector embedding for the given text.
// Returns a float32 slice representing the embedding vector.
Embed(ctx context.Context, text string) ([]float32, error)
// EmbedBatch generates vector embeddings for multiple texts in a single request.
// Returns one float32 slice per input text, in the same order.
EmbedBatch(ctx context.Context, texts []string) ([][]float32, error)
// Available reports whether the embedding model is loaded and ready.
// Returns false if the provider is unreachable or the model is not pulled.
Available() bool
// ModelID returns the model identifier used for embeddings.
ModelID() string
}
Embedder generates vector embeddings from text. Implementations must be safe for concurrent use. The interface abstracts the embedding provider, enabling testing with mock implementations and future provider swaps.
type OllamaEmbedder ¶
type OllamaEmbedder struct {
// contains filtered or unexported fields
}
OllamaEmbedder implements Embedder using Ollama's HTTP API. It calls POST /api/embed for embedding generation and GET /api/tags for model availability checks.
Design decision: Uses standard net/http instead of an SDK dependency because the Ollama API is simple (2 endpoints) and the Embedder interface allows swapping implementations without changing callers.
func NewOllamaEmbedder ¶
func NewOllamaEmbedder(baseURL, model string) *OllamaEmbedder
NewOllamaEmbedder creates an OllamaEmbedder that connects to the Ollama API at baseURL (e.g., "http://localhost:11434") using the specified model (e.g., "granite-embedding:30m"). Returns a ready-to-use embedder with a 30-second HTTP timeout and 30-second availability cache interval.
The returned embedder is safe for concurrent use. Call OllamaEmbedder.Available to check if the model is loaded before calling OllamaEmbedder.Embed.
func (*OllamaEmbedder) Available ¶
func (o *OllamaEmbedder) Available() bool
Available reports whether the configured embedding model is available in the Ollama instance by querying GET /api/tags. Returns false if Ollama is unreachable, returns a non-200 status, or the model is not in the list. Caches the result for 30 seconds to avoid excessive HTTP calls. Safe for concurrent use.
func (*OllamaEmbedder) Embed ¶
Embed generates a vector embedding for the given text by calling Ollama's POST /api/embed endpoint. Returns the float32 embedding vector for the input text. Returns an error if the HTTP request fails, Ollama returns a non-200 status, the response cannot be parsed, or the response contains no embeddings.
func (*OllamaEmbedder) EmbedBatch ¶
EmbedBatch generates vector embeddings for multiple texts in a single request by passing an array of strings to the Ollama API. Returns one float32 vector per input text in the same order. Returns (nil, nil) if texts is empty. Returns an error if the HTTP request fails or the response cannot be parsed.
func (*OllamaEmbedder) ModelID ¶
func (o *OllamaEmbedder) ModelID() string
ModelID returns the model identifier string (e.g., "granite-embedding:30m") used for embedding generation and storage lookups.
Source Files