Documentation
¶
Overview ¶
Package embedding implements the §4.7 EmbeddingProvider SPI plus the four built-in providers (`openai`, `voyage`, `cohere`, `ollama`). Providers translate text into a fixed-dimensional float vector that the vector store indexes for hybrid retrieval.
Implementations are stateless HTTP clients over the provider's embeddings endpoint. None of them require an SDK; the wire format is JSON over `net/http`. Tests use `httptest.NewServer` to replay vendored response fixtures so the parsing path is exercised without external services.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrEmptyTexts is returned when Embed is called with no inputs. ErrEmptyTexts = errors.New("embedding: empty texts") // ErrUnreachable wraps a transient network or 5xx failure. // Callers retry with backoff or fall back to BM25-only. ErrUnreachable = errors.New("embedding: provider unreachable") // ErrAuth wraps a 401/403 from the provider. ErrAuth = errors.New("embedding: auth failed") // ErrQuota wraps a 429 / quota-exceeded response. ErrQuota = errors.New("embedding: quota exceeded") )
Errors returned by Provider implementations.
var Default = NewRegistry()
Default is the process-global embedding-provider registry the bootstrap consults before its built-in switch. It is empty by default; the built-in providers (openai, voyage, cohere, ollama) remain the switch's concern so their per-provider env-var validation is unchanged. Deployers add custom providers via Default.Register.
Functions ¶
This section is empty.
Types ¶
type Cohere ¶
Cohere is the §4.7 Cohere embeddings provider. Defaults to `embed-v4` (1024 dim); set Model to override.
Wire format: POST <BaseURL>/embed with body `{"model":"<model>","texts":[...],"input_type":"search_document"}`.
func (Cohere) Dimensions ¶
Dimensions returns the configured dimension; defaults vary by model (embed-v4 = 1024).
type Factory ¶ added in v0.1.3
Factory constructs a Provider from the resolved settings. Returning an error fails startup rather than silently disabling search.
type Ollama ¶
Ollama is the §4.7 self-hosted embeddings provider. Points at any Ollama endpoint; defaults to `http://localhost:11434` with model `nomic-embed-text` (768 dim). Recommended for offline / air-gapped deployments where no cloud provider is acceptable.
Wire format: POST <BaseURL>/api/embeddings with body `{"model":"<model>","prompt":"<text>"}`. Ollama processes one text per call; the provider issues N HTTP calls for a batch of N texts. This is ergonomically slower than batch APIs but keeps the wire format simple and matches what Ollama itself supports.
func (Ollama) Dimensions ¶
Dimensions returns the configured dimension; defaults vary by model (nomic-embed-text = 768, mxbai-embed-large = 1024).
type OpenAI ¶
type OpenAI struct {
APIKey string
Model_ string
Dim int
BaseURL string
Org string
Client *http.Client
}
OpenAI is the §4.7 OpenAI embeddings provider. Defaults to `text-embedding-3-small` (1536 dim); set Model to override.
Wire format: POST <BaseURL>/embeddings with body `{"model":"<model>","input":[<texts>]}`. Response carries one `{embedding: [...float...], index: int}` per input.
func (OpenAI) Dimensions ¶
Dimensions returns the configured dimension; defaults to 1536 for text-embedding-3-small.
type Provider ¶
type Provider interface {
// ID returns the provider identifier ("openai" | "voyage" |
// "cohere" | "ollama" | ...).
ID() string
// Model returns the configured model name (e.g. "voyage-3").
Model() string
// Dimensions returns the output vector size. Providers report
// this from configuration or by hard-coded model-default tables;
// callers use it to validate vector-store schema compatibility.
Dimensions() int
// Embed converts a batch of texts into a batch of float vectors.
// The returned slice has the same length and order as texts.
// Errors map to the package-level sentinels via errors.Is.
Embed(ctx context.Context, texts []string) ([][]float32, error)
}
Provider is the SPI implementations satisfy.
type Registry ¶ added in v0.1.3
type Registry struct {
// contains filtered or unexported fields
}
Registry is the process-global registration seam for the §9.1 EmbeddingProvider SPI, distributed per §9.2 as an in-process Go module imported into a registry build. §9.1 states custom backends "register through this SPI as Go-module plugins (§9.2)"; this is the seam that makes the claim hold. A deployment imports a package whose init calls Default.Register, and the bootstrap selects the provider by the PODIUM_EMBEDDING_PROVIDER id, consulting this registry before the built-in switch.
Settings is a wire-serializable map of resolved configuration values so a future out-of-process provider (§9.3) receives the same inputs.
spec: §9.1 (EmbeddingProvider), §9.2 (Go-module plugins).
func NewRegistry ¶ added in v0.1.3
func NewRegistry() *Registry
NewRegistry returns an empty Registry.
type Voyage ¶
Voyage is the §4.7 Voyage AI embeddings provider. Defaults to `voyage-3` (1024 dim); set Model to override.
Wire format: POST <BaseURL>/embeddings with body `{"model":"<model>","input":[<texts>],"input_type":"document"}`.
func (Voyage) Dimensions ¶
Dimensions returns the configured dimension; defaults vary by model (voyage-3 = 1024).
Source Files