Files
archie/internal/domain/sampling/contract.go
T
sam 268283eb16 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

57 lines
2.2 KiB
Go

// Package sampling is the curator sampler family: given a bounded set of
// candidates, pick a subset to spend a curator pass's agentic budget on.
// See docs/prds/curator-sampler-wave1.md for the design and the four
// wave-1 strategies (recency, random, all, staleness) this package ships.
// The embedding-backed surprisal strategy (GitHub #437) is a separate,
// deferred consumer of this same interface -- it does not live here.
package sampling
import (
"context"
"time"
)
// Candidate is one item eligible for sampling. It is deliberately narrow:
// an opaque identifier, the timestamp the timestamp-based strategies score
// against, and an open Metadata bag for whatever a future strategy needs
// (e.g. the embedding-backed surprisal strategy's vector) without widening
// this struct for every strategy that comes after wave 1.
type Candidate struct {
ID string
At time.Time
Metadata map[string]any
}
// Request carries the knobs every strategy shares: a selection cap and a
// deterministic seed. Both are optional -- Cap 0 (or negative) means
// unlimited (the "all" strategy relies on this), Seed 0 is a valid seed,
// not "unset".
type Request struct {
Cap int
Seed int64
}
// Sampler selects a subset of candidates to spend a curator pass's agentic
// budget on. Every implementation -- the four in this package and the
// future embedding-backed surprisal strategy (GitHub #437) -- must be
// deterministic given the same candidates and Request: same inputs, same
// output, every time. That is what makes a pass reproducible and testable.
type Sampler interface {
// Name identifies the strategy for logging/attribution (e.g.
// "recency", "random", "all", "staleness", later "surprisal").
Name() string
// Sample selects from candidates per req. Implementations must not
// mutate candidates or rely on anything but candidates and req --
// determinism depends on that.
Sample(ctx context.Context, candidates []Candidate, req Request) ([]Candidate, error)
}
// effectiveCap resolves req.Cap against n candidates: zero, negative, or
// larger than n means unlimited (every candidate); otherwise req.Cap.
func effectiveCap(reqCap, n int) int {
if reqCap <= 0 || reqCap > n {
return n
}
return reqCap
}