Documentation
¶
Overview ¶
Package embed defines the embedding provider seam used by the indexing pipeline, semantic search, ranking seeds, and episodic memory.
Production code depends on the Embedder interface, not on a concrete client, so a new provider is one type that satisfies Embedder plus a case in FromResolution. When no provider is configured, Default returns Disabled, whose methods fail with ErrDisabled; callers log the reason and skip embedding work instead of crashing.
Two providers ship: Voyage (native API, asymmetric input types) and any OpenAI-compatible embeddings endpoint (OpenAI, Azure OpenAI, Gemini's OpenAI surface, Ollama, vLLM, LM Studio, OpenRouter, gateways). Selection is described by ResolveProvider so the startup log, doctor, and the pipeline all agree on which provider is active and why.
Index ¶
Constants ¶
const ( ProviderAuto = "auto" ProviderVoyage = "voyage" ProviderOpenAI = "openai" ProviderOff = "off" )
Provider names accepted by CODE_GRAPH_EMBED_PROVIDER.
const ( AuthBearer = "bearer" // Authorization: Bearer <key> (OpenAI, Ollama, vLLM, OpenRouter, Gemini) AuthAPIKey = "api-key" // api-key: <key> (Azure OpenAI) )
Credential header styles for the OpenAI-compatible provider.
const BatchSize = 64 // Voyage rate limit: 64 texts per batch is safe
BatchSize is the largest text batch a provider call should carry; callers chunk larger inputs so progress and cancellation stay responsive.
const DefaultOpenAIBaseURL = "https://api.openai.com/v1"
DefaultOpenAIBaseURL is used when the openai provider is selected without CODE_GRAPH_EMBED_BASE_URL.
const NoProviderHint = "set VOYAGE_API_KEY, or CODE_GRAPH_EMBED_BASE_URL and CODE_GRAPH_EMBED_MODEL for an OpenAI-compatible endpoint"
NoProviderHint tells a user how to turn embeddings on.
Variables ¶
var ErrDisabled = errors.New("embeddings disabled: no embedding provider configured (" + NoProviderHint + ")")
ErrDisabled is returned by Disabled when embedding work is requested without a configured provider.
var VoyageEmbedURL = "https://api.voyageai.com/v1/embeddings"
VoyageEmbedURL is the Voyage embeddings endpoint. Package-level var for test injection (same pattern as tools.releaseURL).
Functions ¶
func IsDisabled ¶
IsDisabled reports whether e is the Disabled provider (or nil).
Types ¶
type Disabled ¶
type Disabled struct{}
Disabled is the Embedder used when no provider is configured.
func (Disabled) EmbedBatch ¶
EmbedBatch always fails with ErrDisabled.
func (Disabled) EmbedSingle ¶
EmbedSingle always fails with ErrDisabled.
type Embedder ¶
type Embedder interface {
// Model returns the model identifier that produced the vectors, so tool
// responses and stored rows can record real provenance.
Model() string
// EmbedBatch embeds texts in order and honours ctx cancellation.
EmbedBatch(ctx context.Context, texts []string, inputType string) ([][]float32, error)
// EmbedSingle embeds one text.
EmbedSingle(ctx context.Context, text string, inputType string) ([]float32, error)
}
Embedder turns text into fixed-width vectors.
inputType is the provider's asymmetric hint: "document" while indexing and "query" while searching. Implementations that do not distinguish the two may ignore it.
func Default ¶
func Default() Embedder
Default resolves the configured provider from the environment and returns a ready client, or Disabled when none is configured or the configuration is contradictory (the reason is available through ResolveProvider).
func FromResolution ¶
func FromResolution(r *Resolution) Embedder
FromResolution builds the client described by r. Credentials are read from the environment at construction time; r only says which provider to use.
type OpenAI ¶
type OpenAI struct {
// contains filtered or unexported fields
}
OpenAI embeds text through any OpenAI-compatible /embeddings endpoint.
func NewOpenAI ¶
func NewOpenAI(r *Resolution) *OpenAI
NewOpenAI builds a client from a Resolution whose Provider is openai. Returns nil for any other provider or when the model is empty.
func (*OpenAI) EmbedBatch ¶
EmbedBatch embeds texts in order, in bounded batches, honouring ctx.
func (*OpenAI) EmbedSingle ¶
EmbedSingle embeds one text.
type Resolution ¶
type Resolution struct {
// Provider is voyage, openai, or off.
Provider string
// Requested is the raw CODE_GRAPH_EMBED_PROVIDER value (auto when unset).
Requested string
// Model is the model id that will be sent to the provider.
Model string
// BaseURL is the OpenAI-compatible endpoint (openai only), no trailing slash.
BaseURL string
// Dimension is the expected vector width when CODE_GRAPH_EMBED_DIMENSION
// is set; 0 means "accept what the API returns".
Dimension int
// AuthHeader is bearer or api-key (openai only).
AuthHeader string
// HasCredential reports whether a key will be sent.
HasCredential bool
// Reason explains an off Provider, including misconfigurations.
Reason string
// Err is set when the configuration is contradictory (for example the
// openai provider without a model); Provider is off in that case.
Err error
}
Resolution is the outcome of reading the provider configuration: which provider is active, with what model and endpoint, or why none is.
func ResolveProvider ¶
func ResolveProvider(getenv func(string) string) Resolution
ResolveProvider reads the provider configuration through getenv (os.Getenv in production, a map in tests) and returns the effective Resolution.
Rules, in order:
- CODE_GRAPH_EMBED_PROVIDER=off → off.
- =voyage → voyage when VOYAGE_API_KEY is set, else off with a reason.
- =openai → openai; CODE_GRAPH_EMBED_MODEL is required, the base URL defaults to api.openai.com, the key is CODE_GRAPH_EMBED_API_KEY then OPENAI_API_KEY and may be absent for self-hosted endpoints.
- auto (default) → voyage when VOYAGE_API_KEY is set, else openai when CODE_GRAPH_EMBED_BASE_URL is set, else off.
CODE_GRAPH_SKIP_EMBEDDINGS is deliberately not consulted here: it gates whether embedding passes run at all and is handled by the caller.
func (*Resolution) Describe ¶
func (r *Resolution) Describe() string
Describe returns a one-line human summary such as "voyage (voyage-code-3)" or "openai (nomic-embed-text @ localhost:11434)".
func (*Resolution) Host ¶
func (r *Resolution) Host() string
Host returns the endpoint host for logs and doctor output ("" for voyage or off).
type Voyage ¶
type Voyage struct {
// contains filtered or unexported fields
}
Voyage embeds text via the Voyage AI API.
func NewVoyage ¶
func NewVoyage() *Voyage
NewVoyage creates a client. Returns nil if VOYAGE_API_KEY is not set.
func (*Voyage) EmbedBatch ¶
func (vc *Voyage) EmbedBatch(ctx context.Context, texts []string, inputType string) ([][]float32, error)
EmbedBatch embeds a batch of texts and returns their vectors. inputType should be "document" for indexing, "query" for search. Honors ctx cancellation: returns ctx.Err() promptly instead of continuing retries through batches when the caller's deadline has passed.
func (*Voyage) EmbedSingle ¶
EmbedSingle embeds a single text and returns the vector.
Source Files