Embedding models
The embedding package provides a unified abstraction for generating dense vector representations (embedding.Vector) from text and multimodal content across cloud and local providers.
Embedding models map inputs—such as sentences, document chunks, images, or audio—into a shared vector space where semantically related items sit close together. These vectors power semantic search, Retrieval-Augmented Generation (RAG), classification, clustering, and long-term agent memory.
1. Core Abstractions
Provider: The backend implementation that executes embedding requests (loomopenai,loomgenai,loomollama).Model: The high-level wrapper around aProviderand model name. Provides single-query and batch-document helpers, dimension and task configuration, automatic token cost calculation, and middleware chains.Vector: A[]float32slice with built-in vector math methods (CosineSimilarity,Dot,EuclideanDistance,Normalize,Float64,Dimension).Input: A single item to embed. Supports plain text (embedding.Text,embedding.Texts) as well as multimodalmessage.Blockparts (embedding.Image,embedding.ImageURL,embedding.Multimodal,Input.WithParts).TaskType: Optional hint informing task-aware models how vectors will be used (TaskRetrievalQuery,TaskRetrievalDocument,TaskSemanticSimilarity,TaskClassification,TaskClustering).
2. Supported Providers
OpenAI Embeddings API
OpenAI provides hosted text embedding models (text-embedding-3-small, text-embedding-3-large, text-embedding-ada-002) with Matryoshka dimension reduction support.
import ( "github.com/masterkeysrd/loom/embedding" loomopenai "github.com/masterkeysrd/loom/providers/openai")
// Uses OPENAI_API_KEY from environmentprovider, err := loomopenai.NewDefaultProvider()if err != nil { log.Fatal(err)}
model, err := embedding.NewModel(provider, "text-embedding-3-small", nil)Google Gemini Embeddings API
Google Gemini (gemini-embedding-001, gemini-embedding-2) supports task-aware embeddings (TaskType), configurable output dimensionality, and multimodal inputs (text, images, audio, video, and PDF documents).
import ( "context" "github.com/masterkeysrd/loom/embedding" loomgenai "github.com/masterkeysrd/loom/providers/genai")
// Uses GOOGLE_API_KEY from environmentprovider, err := loomgenai.NewDefaultProvider(context.Background())if err != nil { log.Fatal(err)}
model, err := embedding.NewModel(provider, "gemini-embedding-001", nil)Ollama Local Embeddings API
Ollama runs open-weights embedding models locally (nomic-embed-text, mxbai-embed-large, bge-m3, all-minilm, qwen3-embedding) via /api/embed.
import ( "github.com/masterkeysrd/loom/embedding" loomollama "github.com/masterkeysrd/loom/providers/ollama")
// Connects to http://127.0.0.1:11434 by defaultprovider, err := loomollama.NewDefaultProvider()if err != nil { log.Fatal(err)}
model, err := embedding.NewModel(provider, "nomic-embed-text", nil)3. Embedding Queries and Documents
In retrieval workflows, indexing documents and embedding search queries are the two primary operations. Model provides dedicated helpers that automatically apply TaskRetrievalDocument and TaskRetrievalQuery:
ctx := context.Background()
// 1. Batch-embed documentsdocs := []string{ "Loom orchestrates stateful AI workflows using directed graphs.", "Checkpointers persist graph execution state to SQLite or PostgreSQL.", "Decision models evaluate fast System One predicates and choices.",}docVectors, err := model.EmbedDocuments(ctx, docs)if err != nil { log.Fatal(err)}
// 2. Embed a single search queryqueryVector, err := model.EmbedQuery(ctx, "How is workflow state persisted?")if err != nil { log.Fatal(err)}
// 3. Score similarity using Vector methodsfor i, docVec := range docVectors { score := queryVector.CosineSimilarity(docVec) fmt.Printf("[%.4f] %s\n", score, docs[i])}If you also need token usage and cost metrics, call model.Embed directly to receive the full *embedding.Response:
resp, err := model.Embed(ctx, embedding.Texts("first chunk", "second chunk"))if err != nil { log.Fatal(err)}
fmt.Printf("Generated %d vectors (tokens: %d, cost: %s)\n", len(resp.Embeddings), resp.Metrics.Tokens.Input, resp.Metrics.TotalCost,)4. Configuring Dimensions & Task Types
Many modern embedding models support truncating vectors to a smaller dimensionality (Dimensions) to reduce vector storage size and speed up similarity comparisons:
// Configure defaults on a cloned modelmodel512 := model. WithDimensions(512). WithTaskType(embedding.TaskSemanticSimilarity)
// Or pass per-call optionsvec, err := model.EmbedQuery( ctx, "semantic search query", embedding.WithDimensionsOption(256), embedding.WithTaskTypeOption(embedding.TaskRetrievalQuery),)5. Multimodal Embeddings
Models such as Google’s gemini-embedding-2 can embed images, audio, video, and documents directly into the same vector space as text:
import ( "github.com/masterkeysrd/loom/embedding" "github.com/masterkeysrd/loom/message")
// Embed a single inline imageimgVec, err := model.EmbedInput(ctx, embedding.Image(imageBytes, "image/png"))
// Embed text combined with multiple media blockscombined := embedding.Text("Architecture diagram and voice note").WithParts( &message.ImageBlock{Data: imageBytes, MIMEType: "image/png"}, &message.AudioBlock{Data: audioBytes, MIMEType: "audio/mp3"},)vec, err := model.EmbedInput(ctx, combined)6. Vector Similarity & Math Operations
embedding.Vector ([]float32) includes built-in methods for comparing and transforming vectors without external dependencies:
| Method | Description |
|---|---|
v.Dimension() int |
Returns the number of elements in the vector (len(v)). |
v.CosineSimilarity(other Vector) float32 |
Computes cosine similarity by dividing the dot product by the product of the two vector norms. Returns 0 on dimension mismatch or zero norm. |
v.Dot(other Vector) float32 |
Computes the inner dot product by summing pairwise products. |
v.EuclideanDistance(other Vector) float32 |
Computes the Euclidean distance as the square root of the sum of squared element-wise differences. |
v.Normalize() Vector |
Returns a new L₂-normalized unit vector (|v| = 1). |
v.Float64() []float64 |
Converts the []float32 vector into a []float64 slice. |
7. Middleware & Observability
Like llm.Model and decision.Model, embedding.Model attaches TelemetryMiddleware by default and supports custom embedding.Middleware chains:
customModel := model.WithMiddleware(func(next embedding.Embedder) embedding.Embedder { return func(ctx context.Context, req *embedding.Request) (*embedding.Response, error) { log.Printf("embedding %d inputs with model %s", len(req.Inputs), req.Model) return next(ctx, req) }})- OpenTelemetry Spans & Metrics: Automatically records
embed {model}client spans (gen_ai.operation.name = "embeddings") and GenAI duration/token usage histograms. - Stream Writer Integration: Emits
on_embeddingevents when astream.Writeris attached toctx.