Files
archie/internal/domain/sampling/contract.go
T

48 lines
1.5 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. The
// embedding-backed surprisal strategy is a separate, deferred consumer of this
// same interface -- it does not live here.
package sampling
import (
"context"
"time"
)
// Candidate is an item eligible for sampling.
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 candidates for a curator pass. Implementations must be
// deterministic.
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
}