48 lines
1.5 KiB
Go
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
|
|
}
|