Files
archie/internal/domain/embedding/contract.go
T
sam 6affe0eea3 chore(curator): add embedding client and sampler interface prerequisites (#752)
* 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
2026-09-05 22:53:08 +10:00

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)
}