Documentation
¶
Overview ¶
Package embeddings owns Harbor's embedding client — the seam that turns text into vectors (RFC §6.5).
The `Embedder` is a standalone primitive, deliberately separate from the one-method chat `LLMClient`: an embeddings-only consumer must not inherit the chat client's dependency surface (artifact store + event bus). The package ships the §4.4 extensibility-seam plumbing — interface, sentinel errors, registry + factory (`Open`) — and the cosine-similarity helper its retrieval consumers share.
Consumers:
- The memory subsystem's opt-in semantic-retrieval mode (`internal/memory`, RFC §6.6) injects an `Embedder` via `memory.Deps.Embedder`.
- The skills subsystem's opt-in semantic skill retrieval (`internal/skills`, RFC §6.7) injects one via `skills.Deps.Embedder`.
- À-la-carte consumers call `Open` + `Embed` directly and rank with `Cosine` over their own corpus — no memory subsystem, no config file, no Protocol (see `docs/recipes/embed-and-retrieve.md`).
Identity is mandatory at the `Embed` edge, mirroring the chat edge: embedding calls are billable provider traffic, so the runtime fails closed on a missing identity. The seam stays Protocol-free — `identity.With` / `identity.WithRun` is the library consumer's path.
Concurrent reuse: one `Embedder` instance is safe to share across N concurrent goroutines. Drivers hold no per-call state; per-call data lives on `ctx` and the argument slice.
Index ¶
Constants ¶
const DefaultDriver = "bifrost"
DefaultDriver is the production embedding driver name. There is no mock or stub default: a consumer that enables an embedding-backed mode without a configured provider fails loudly at construction (AGENTS.md §13 — no test stubs as production defaults).
Variables ¶
var ( // ErrInvalidConfig — the `ConfigSnapshot` (or `Deps`) failed // construction-time validation. The wrapped message names the // offending field. ErrInvalidConfig = errors.New("embeddings: invalid config") // ErrUnknownDriver — `Open` was asked for a driver name no // registered factory handles. The wrapped message lists the // registered names. ErrUnknownDriver = errors.New("embeddings: unknown driver") // ErrIdentityMissing — `Embed` was called with a `ctx` carrying // no Harbor identity. The embedding edge fails closed, mirroring // the chat edge (AGENTS.md §6 rule 9). ErrIdentityMissing = errors.New("embeddings: identity missing from context") // ErrEmptyInput — `Embed` was called with no texts, or with an // empty-string element. Providers reject empty inputs; the edge // fails loudly instead of forwarding a doomed request. ErrEmptyInput = errors.New("embeddings: empty input") // ErrClientClosed — a method was called after `Close`. ErrClientClosed = errors.New("embeddings: client is closed") // ErrDimensionMismatch — `Cosine` was handed vectors of // different lengths. Almost always model drift: vectors derived // under one embedding model are not comparable with another's. ErrDimensionMismatch = errors.New("embeddings: vector dimension mismatch") )
Sentinel errors. Callers compare via `errors.Is`.
Functions ¶
func Cosine ¶
Cosine returns the cosine similarity of two vectors in [-1, 1]. Vectors of different lengths return `ErrDimensionMismatch`; zero-length vectors return `ErrEmptyInput`. A zero-norm vector yields similarity 0 (no direction to compare).
This is the one shared ranking primitive the semantic-retrieval consumers (memory turns, skill descriptions) and à-la-carte callers all use — a second cosine implementation elsewhere in the tree is a bug.
func HasIdentity ¶
HasIdentity reports whether `ctx` carries a Harbor identity (either the triple or the run-scoped quadruple). The embedding edge MUST validate this before invoking any driver — the runtime fails closed on missing identity. Mirrors the chat edge's check; presence implies validity because `identity.With` / `WithRun` validate at write time.
func Register ¶
Register installs a driver factory under `name`. Drivers self- register from their package `init()`; the production driver aggregator (`internal/drivers/prod`) blank-imports them so the binary and embedders pick the registrations up at boot. Per AGENTS.md §4.4.
Re-registering the same name panics — the registration model is write-once-at-init and a duplicate signals a build misconfig.
func RegisteredDrivers ¶
func RegisteredDrivers() []string
RegisteredDrivers returns a sorted list of driver names. Useful for boot-log emission and for surfacing in error messages.
Types ¶
type ConfigSnapshot ¶
type ConfigSnapshot struct {
Driver string
Provider string
Model string
APIKey string
BaseURL string
Timeout time.Duration
Dimensions int
}
ConfigSnapshot is the strict subset of `config.EmbeddingsConfig` the embeddings package consumes. Keeping a snapshot decouples drivers from the config package's type evolution (the same pattern the chat client and memory subsystems use). Callers either project the operator config via `SnapshotFromConfig` or construct the snapshot directly — both paths are first-class.
- `Driver` selects the §4.4 factory. Empty defaults to `DefaultDriver`.
- `Provider` / `Model` / `APIKey` / `BaseURL` / `Timeout` are the provider-gateway knobs, configured separately from the chat model: the embedding model is its own operator choice. `APIKey` accepts a literal value or an `env.NAME` reference, matching the chat client's convention.
- `Dimensions`, when > 0, requests a reduced output dimension from providers that support it. Zero leaves the model's native dimension.
func SnapshotFromConfig ¶
func SnapshotFromConfig(cfg config.EmbeddingsConfig) ConfigSnapshot
SnapshotFromConfig projects the operator-facing `config.EmbeddingsConfig` block onto the embeddings package's decoupled ConfigSnapshot. Every config field maps 1:1.
type Deps ¶
type Deps struct{}
Deps carries the runtime dependencies an embedding driver consumes. Deliberately empty at this revision: the embedding seam is dependency-light by design — an embeddings-only consumer should not have to wire an artifact store or an event bus the way a chat consumer does. The struct exists so the factory signature (`Open(ctx, cfg, deps)`) stays stable when future revisions add a dependency (e.g. governance metering).
type Embedder ¶
type Embedder interface {
Embed(ctx context.Context, texts []string) ([][]float32, error)
Close(ctx context.Context) error
}
Embedder is Harbor's embedding-client interface. A single mandatory surface; every driver implements every method — no `Supports*` ceremony per AGENTS.md §4.4.
`Embed` returns one vector per input text, in input order. The vectors of one call share a dimension (the configured model's); callers persist the model name alongside derived vectors when they need to detect model drift (vectors from different models are not comparable).
Identity-mandatory contract: `Embed` fails closed with `ErrIdentityMissing` when `ctx` carries no Harbor identity. The registry path (`Open`) enforces this by construction; drivers re-check defensively at their own edge.
`Close` releases driver resources (provider worker pools). After `Close`, `Embed` returns `ErrClientClosed`. Close is idempotent.
func Open ¶
Open returns the `Embedder` built by the factory whose name matches `cfg.Driver` (defaults to `DefaultDriver` when empty).
The returned client enforces the embedding-edge contract by construction — every `Embed` through the registry path:
- fails closed with `ErrIdentityMissing` when `ctx` carries no Harbor identity (mirroring the chat edge);
- rejects empty input (`ErrEmptyInput`) before any provider traffic;
- honours `ctx` cancellation between phases of work.
Misconfiguration errors name the offending field; an unknown driver error lists the registered drivers.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
drivers
|
|
|
bifrost
Package bifrost is Harbor's production `embeddings.Embedder` driver, wired to the bifrost provider gateway's embedding surface.
|
Package bifrost is Harbor's production `embeddings.Embedder` driver, wired to the bifrost provider gateway's embedding surface. |
|
Package embeddingstest provides a deterministic, test-grade `embeddings.Embedder` for conformance suites and integration tests that need meaningful similarity without provider traffic.
|
Package embeddingstest provides a deterministic, test-grade `embeddings.Embedder` for conformance suites and integration tests that need meaningful similarity without provider traffic. |