Documentation
¶
Overview ¶
Package embeddings provides a pluggable embedding provider interface. Supported: OpenAI, Voyage AI, and a local stub (returns hash-based pseudo-vectors).
Index ¶
- func Cosine(a, b []float32) float32
- func ExtractRetryDelay(errMsg string) time.Duration
- func GetInputType(model string, mode EmbedMode) string
- func GetMaxBatchSize(model string) int
- type EmbedMode
- type EmbeddingMemo
- func (m *EmbeddingMemo) Get(content string) ([]float32, bool)
- func (m *EmbeddingMemo) GetMode(content string, mode EmbedMode) ([]float32, bool)
- func (m *EmbeddingMemo) Len() int
- func (m *EmbeddingMemo) Put(content string, embedding []float32)
- func (m *EmbeddingMemo) PutMode(content string, mode EmbedMode, embedding []float32)
- type MemoizedProvider
- func (p *MemoizedProvider) Dims() int
- func (p *MemoizedProvider) Embed(ctx context.Context, text string) ([]float32, error)
- func (p *MemoizedProvider) EmbedBatch(ctx context.Context, texts []string) ([][]float32, error)
- func (p *MemoizedProvider) EmbedWithMode(ctx context.Context, text string, mode EmbedMode) ([]float32, error)
- func (p *MemoizedProvider) Memo() *EmbeddingMemo
- func (p *MemoizedProvider) Name() string
- type ModelDefaults
- type Pacer
- type Provider
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ExtractRetryDelay ¶
ExtractRetryDelay parses rate-limit error messages for the recommended wait time. It recognises patterns such as "Please try again in 1.5s", "retry in 500ms", and "try again in 2 seconds". Returns 0 if no delay is found.
func GetInputType ¶
GetInputType returns the appropriate input_type string for the given model and embed mode. If the model has no asymmetric input types, an empty string is returned.
func GetMaxBatchSize ¶
GetMaxBatchSize returns the maximum batch size for a model, or 64 as the default when the model is unknown.
Types ¶
type EmbedMode ¶
type EmbedMode int
EmbedMode specifies whether a text is a document or a query for asymmetric embedding models.
type EmbeddingMemo ¶
type EmbeddingMemo struct {
// contains filtered or unexported fields
}
EmbeddingMemo caches embeddings to skip re-embedding unchanged content.
The cache key is namespace + mode + sha256(content), NOT content alone. The namespace identifies the embedding model (provider Name()), so swapping models or model versions no longer serves stale, incomparable vectors from the old model. The mode dimension keeps document- and query-mode vectors separate for asymmetric retrieval models (e.g. Cohere v3 search_document vs search_query).
func NewEmbeddingMemo ¶
func NewEmbeddingMemo(maxEntries int) *EmbeddingMemo
NewEmbeddingMemo creates a memo cache with the given max entry count. The namespace is empty; prefer NewEmbeddingMemoNS so the cache is keyed by model identity. Pass "" only for tests or single-model callers that never switch.
func NewEmbeddingMemoNS ¶
func NewEmbeddingMemoNS(namespace string, maxEntries int) *EmbeddingMemo
NewEmbeddingMemoNS creates a memo cache namespaced by model identity, so that changing the embedding model invalidates the cache instead of serving stale vectors from the previous model.
func (*EmbeddingMemo) Get ¶
func (m *EmbeddingMemo) Get(content string) ([]float32, bool)
Get returns a cached embedding for the content in ModeDocument, if present.
func (*EmbeddingMemo) GetMode ¶
func (m *EmbeddingMemo) GetMode(content string, mode EmbedMode) ([]float32, bool)
GetMode returns a cached embedding for the content under the given mode.
func (*EmbeddingMemo) Len ¶
func (m *EmbeddingMemo) Len() int
Len returns the number of cached entries.
func (*EmbeddingMemo) Put ¶
func (m *EmbeddingMemo) Put(content string, embedding []float32)
Put stores an embedding for the given content in ModeDocument.
type MemoizedProvider ¶
type MemoizedProvider struct {
// contains filtered or unexported fields
}
MemoizedProvider wraps a Provider with content-addressed memoization.
func NewMemoizedProvider ¶
func NewMemoizedProvider(inner Provider, maxEntries int) *MemoizedProvider
NewMemoizedProvider wraps an existing Provider with a memo cache. The cache is namespaced by the inner provider's Name() (which encodes the model), so a model swap can never serve stale vectors from the previous model.
func (*MemoizedProvider) Dims ¶
func (p *MemoizedProvider) Dims() int
func (*MemoizedProvider) EmbedBatch ¶
func (*MemoizedProvider) EmbedWithMode ¶
func (*MemoizedProvider) Memo ¶
func (p *MemoizedProvider) Memo() *EmbeddingMemo
Memo returns the underlying cache for inspection/testing.
func (*MemoizedProvider) Name ¶
func (p *MemoizedProvider) Name() string
type ModelDefaults ¶
type ModelDefaults struct {
IndexInputType string // e.g., "search_document", "RETRIEVAL_DOCUMENT"
QueryInputType string // e.g., "search_query", "RETRIEVAL_QUERY"
Dimensions int // output dimensions
MaxBatchSize int // max texts per batch request
}
ModelDefaults maps model names to their optimal embedding parameters.
func GetModelDefaults ¶
func GetModelDefaults(model string) (ModelDefaults, bool)
GetModelDefaults returns the defaults for a known model. The second return value is false when the model is not in the table.
type Pacer ¶
type Pacer struct {
// contains filtered or unexported fields
}
Pacer enforces minimum intervals between API requests to stay under rate limits.
func (*Pacer) SetInterval ¶
SetInterval adjusts the pacer's minimum interval dynamically.
type Provider ¶
type Provider interface {
Embed(ctx context.Context, text string) ([]float32, error)
EmbedBatch(ctx context.Context, texts []string) ([][]float32, error)
EmbedWithMode(ctx context.Context, text string, mode EmbedMode) ([]float32, error)
Dims() int
Name() string
}
Provider generates vector embeddings for text.
func NewCohere ¶
NewCohere creates a Cohere embedding provider. model: "embed-english-v3.0" (1024 dims) or "embed-multilingual-v3.0" (1024 dims).
func NewLocal ¶
func NewLocal() Provider
NewLocal returns a local stub provider that generates deterministic pseudo-vectors from SHA-256 hashes. Useful for testing and offline use. NOT semantically meaningful — use OpenAI/Voyage for real semantic search.
Source Files