Documentation
¶
Overview ¶
Package embedding provides the EmbeddingClient interface and provider implementations (OpenAI-compatible, Ollama) for BubbleFish Nexus.
Callers MUST treat all errors from Embed as graceful-degradation signals — never crash or return 5xx to the client when the embedding provider is unreachable or times out.
Reference: Tech Spec Section 14.4, Phase 5 Behavioral Contract.
Index ¶
Constants ¶
const ( ProviderOpenAI = "openai" ProviderOllama = "ollama" ProviderCompatible = "compatible" )
Provider name constants match the daemon.toml embedding.provider values.
Variables ¶
ErrEmbeddingUnavailable is returned when the embedding provider is unreachable, times out, or returns a non-success HTTP response. Callers should treat this as a graceful degradation signal: skip Stages 2 and 4 and set _nexus.semantic_unavailable = true in the response.
Reference: Tech Spec Section 3.4 — Stage 4, Phase 5 Behavioral Contract 4.
Functions ¶
This section is empty.
Types ¶
type EmbeddingClient ¶
type EmbeddingClient interface {
// Embed returns a vector embedding for the given text.
// Returns ErrEmbeddingUnavailable when the provider is unreachable or times
// out. Callers must degrade gracefully on any error — do not propagate to
// the end client.
Embed(ctx context.Context, text string) ([]float32, error)
// Dimensions returns the number of dimensions this client produces.
// Used to validate stored embeddings are compatible with the query vector.
Dimensions() int
// Close releases any resources held by the client (idle connections, etc.).
// Safe to call once. No-op after the first call.
Close() error
}
EmbeddingClient computes dense vector embeddings for text. All implementations must be safe for concurrent use.
Reference: Tech Spec Section 14.4.
func NewClient ¶
func NewClient(cfg config.EmbeddingConfig, resolvedAPIKey string, logger *slog.Logger) (EmbeddingClient, error)
NewClient creates an EmbeddingClient from the daemon.toml embedding config.
Returns (nil, nil) when embedding is disabled (cfg.Enabled = false). Callers must treat a nil client as "embedding not configured" and degrade gracefully: skip Stages 2 and 4, set _nexus.semantic_unavailable = true.
resolvedAPIKey is the pre-resolved API key (from config.ResolveEnv). It is passed in so this function never calls os.Getenv — all key resolution happens once at startup.
INVARIANT: resolvedAPIKey is never logged at any level.
Reference: Tech Spec Section 9.2.8, Phase 5 Behavioral Contract 2.
Source Files