Documentation
¶
Overview ¶
Package embed defines the Embedder port (ADR-0004) and a local adapter that speaks the OpenAI-compatible /embeddings endpoint. Embeddings stay local in the sense that the store persists them on host; the endpoint may be local (Ollama, vLLM) or remote (OpenAI) — configured per provider.
Index ¶
Constants ¶
const ( DefaultBaseURL = "https://api.openai.com/v1" // DefaultTimeout bounds a single Embed call when no caller-supplied // http.Client is set. DefaultTimeout = 30 * time.Second )
Variables ¶
var ErrDimensionDrift = errors.New("embed: dimension drift")
ErrDimensionDrift is returned by Local.Embed when the endpoint returns vectors whose dimension disagrees with the dimension pinned on the first successful Embed. Callers use errors.Is to distinguish it from transport failures — the fallback path (FallbackTo) does NOT trigger on dim drift, because the fallback endpoint almost certainly uses a different model and a different vector space.
Functions ¶
This section is empty.
Types ¶
type Embedder ¶
type Embedder interface {
Embed(ctx context.Context, texts []string) ([][]float32, error)
Dim() int
}
Embedder turns text into fixed-dimension float32 vectors. Dim() returns the pinned dimension (0 before the first successful Embed).
type Local ¶
type Local struct {
BaseURL string
APIKey string
Model string
// Timeout bounds a single Embed call when HTTP is nil. Zero means
// DefaultTimeout. Ignored when HTTP is non-nil (the caller's client
// wins, including its timeout).
Timeout time.Duration
HTTP *http.Client
// contains filtered or unexported fields
}
Local is the OpenAI-compatible /embeddings adapter. It pins the vector dimension on the first successful Embed and rejects later mismatches.
func (*Local) FallbackTo ¶
FallbackTo wraps l with a fallback Embedder that is consulted only on transport-class errors (network failure, 5xx, 429). It returns an Embedder; the wrapper itself is a small struct holding primary and fallback. Dim() reports the primary's pinned dimension.
FallbackTo does NOT trigger on ErrDimensionDrift (the fallback endpoint almost certainly uses a different model with a different vector space) or on 4xx other than 429 (those are caller errors, not transport errors).
Calling FallbackTo on a nil receiver is a programming error and returns nil.
Source Files