* feat(curator): add embedding client and sampler wave-1 prerequisites Bead archie-core-1786637500752-415-434e5bb9 (GitHub #436) was closed with no linked PR/commits, and the surprisal-sampling bead archie-core-1786637500776-416-600a66e5 (GitHub #437) found none of its stated prerequisites -- an embedding client, a Sampler interface, or the four wave-1 cheap sampling strategies -- actually exist. This builds them: - internal/domain/embedding + internal/infrastructure/embedding: a narrow typed embedding client, config-driven via a providers table + a role in [models], mirroring the existing chat model role convention. Degrades to capability-unavailable (never fails startup or a call) for a missing role, unknown provider, unsupported class, or unresolved credential. Wired as an optional capability in bootstrap.go's setupEmbeddings. - internal/domain/sampling: the Sampler interface plus recency, random, all, and staleness-proxy strategies, per docs/prds/curator-sampler-wave1.md. Deterministic given fixed inputs, matching GitHub #437's stated acceptance criterion for the embedding-backed strategy it will add behind this same interface (not part of this change). Table-driven tests throughout; httptest for the embedding client, no live service. No curator wiring yet -- nothing consumes either capability in this change. * no-mistakes(document): docs(architecture): mark curator sampling prereqs as landed
45 lines
1.9 KiB
Go
45 lines
1.9 KiB
Go
// Package embedding is the embedding capability: a narrow typed boundary
|
|
// for turning text into vectors, so consumers (curators first, per bead
|
|
// archie-core-1786637500752-415-434e5bb9 / GitHub #436) never depend on a
|
|
// specific provider SDK.
|
|
//
|
|
// Unlike curator and memory (internal/domain/curator, internal/domain/
|
|
// memory), a Client has no Lifecycle: it is call-scoped, not long-running,
|
|
// the same reasoning internal/domain/image's Provider contract already
|
|
// uses -- "is this usable right now" is exactly what Embed returning
|
|
// ErrUnavailable already communicates.
|
|
package embedding
|
|
|
|
import (
|
|
"context"
|
|
"errors"
|
|
)
|
|
|
|
// Sentinel errors every implementation wraps with fmt.Errorf("%w: ...", ...)
|
|
// so callers can errors.Is regardless of backend.
|
|
var (
|
|
// ErrUnavailable means the capability cannot serve right now: no role
|
|
// is configured, the provider is unknown, or its credential could not
|
|
// be resolved. Per the credential-missing-degrades-not-fatal rule
|
|
// (AGENTS.md), this must never prevent the daemon from starting or
|
|
// fail an unrelated chat turn -- a caller must degrade (skip the
|
|
// content, fall back to free exploration) instead.
|
|
ErrUnavailable = errors.New("embedding capability unavailable")
|
|
// ErrEmptyInput means Embed was called with no texts.
|
|
ErrEmptyInput = errors.New("embedding request has no input text")
|
|
)
|
|
|
|
// Vector is one embedding: a dense float32 vector.
|
|
type Vector []float32
|
|
|
|
// Client is the narrow typed contract every embedding backend implements.
|
|
type Client interface {
|
|
// Embed returns one Vector per entry in texts, in the same order.
|
|
// Network calls must carry a timeout; a failure is returned as an
|
|
// error, never a panic. Callers must treat any non-nil error as
|
|
// "skip this batch," matching image.Provider's ErrUnavailable
|
|
// convention -- an embedding failure must never crash or fail an
|
|
// unrelated caller.
|
|
Embed(ctx context.Context, texts []string) ([]Vector, error)
|
|
}
|