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
This commit is contained in:
1 parent
cd2ab3516b
commit
6affe0eea3
18 files changed
+1186
-21
No files matched your search
@@ -195,6 +195,19 @@ structures found in legacy packages.
|
||||
receiver, one dispatch config). Do not silently enable it for multi-identity
|
||||
deployments without first building per-identity routing -- see
|
||||
`ARCHITECTURE.md`'s "Webhook intake" section.
|
||||
- **`internal/domain/embedding/` + `internal/infrastructure/embedding/`:**
|
||||
Embedding client contract + implementation. Config-driven exactly like chat
|
||||
model roles: `models.embedding = "provider/model"` plus a `[providers.*]`
|
||||
entry. `infrastructure/embedding.New` degrades to `(nil, false)` -- never an
|
||||
error -- for a missing role, unknown provider, unsupported class, or
|
||||
unresolved credential; wired as an optional capability in
|
||||
`bootstrap.go`'s `setupEmbeddings`. Only provider classes matching
|
||||
`config.Provider`'s shape are supported (openai, gemini, ollama, cohere,
|
||||
mistral) -- azure needs a `Deployment` field this config type doesn't have.
|
||||
- **`internal/domain/sampling/`:** The curator `Sampler` interface (see
|
||||
`docs/prds/curator-sampler-wave1.md`) plus four pure, deterministic
|
||||
strategies (recency, staleness, random, all). No curator consumes a
|
||||
`Sampler` yet -- `curator.Registrar` is untouched by this package.
|
||||
|
||||
## Development Protocol
|
||||
|
||||
|
||||
@@ -87,6 +87,10 @@ parked = "archie:parked"
|
||||
triage = "openai/gpt-5.4"
|
||||
planner = "openai/gpt-5.4"
|
||||
builder = "openai/gpt-5.4"
|
||||
# `embedding` is optional: it powers in-process embedding consumers
|
||||
# (curators first). Unset, or a credential that fails to resolve, degrades
|
||||
# to the capability reporting unavailable -- archied still starts.
|
||||
# embedding = "openai/text-embedding-3-small"
|
||||
|
||||
[providers.openai]
|
||||
class = "openai"
|
||||
|
||||
@@ -57,26 +57,26 @@ Forge action positions are designed but not yet implemented (open
|
||||
investigation `archie-core-t2db.19`); when they land they follow the same
|
||||
model, not a new one.
|
||||
|
||||
## Curator surprisal sampling (deferred)
|
||||
## Curator surprisal sampling
|
||||
|
||||
**Deferred by decision, 2026-08-05** — Archie has no embedding capability, and
|
||||
wave 1 ships the strategy seam without one. Pick the deferred work up in order:
|
||||
[#436](https://github.com/samcharles93/archie-core/issues/436) first, then
|
||||
[#437](https://github.com/samcharles93/archie-core/issues/437) which depends on it
|
||||
and on [#407](https://github.com/samcharles93/archie-core/issues/407).
|
||||
**Decided 2026-08-05, wave 1 landed 2026-09-05** — the curator engine family
|
||||
(epic [#435](https://github.com/samcharles93/archie-core/issues/435)) selects which memories deserve agentic attention via
|
||||
surprisal-based sampling: score memories by how surprising they are and
|
||||
spend the sampled reasoner's agentic budget on the most surprising items.
|
||||
|
||||
The curator engine family (epic [#435](https://github.com/samcharles93/archie-core/issues/435)) selects which memories
|
||||
deserve agentic attention via surprisal-based sampling: score memories by how
|
||||
surprising they are and spend the sampled reasoner's agentic budget on the
|
||||
most surprising items. Wave 1 of the epic ships the `Sampler` strategy seam in
|
||||
`internal/curator` with cheap, embedding-free strategies (recency, random,
|
||||
all, and a staleness proxy). The embedding-backed strategy is a documented
|
||||
extension point and is gated behind an embedding capability Archie does not
|
||||
yet have — **any surprisal-style sampling is gated behind adding one**.
|
||||
The prerequisites are built: the embeddings capability
|
||||
([#436](https://github.com/samcharles93/archie-core/issues/436), `internal/domain/embedding` contract +
|
||||
`internal/infrastructure/embedding` implementation, config-driven via
|
||||
`models.embedding`) and the wave-1 `Sampler` strategy seam
|
||||
(`internal/domain/sampling` -- not `internal/curator`, see
|
||||
`docs/prds/curator-sampler-wave1.md` for the settled design and tracking)
|
||||
with four
|
||||
cheap, embedding-free strategies (recency, random, all, staleness proxy).
|
||||
No curator consumes a `Sampler` yet.
|
||||
|
||||
Requirements for the deferred work, so it can be picked up without
|
||||
re-deriving the design (tracked as [#436](https://github.com/samcharles93/archie-core/issues/436) embeddings capability,
|
||||
then [#437](https://github.com/samcharles93/archie-core/issues/437) surprisal strategies):
|
||||
Still deferred: [#437](https://github.com/samcharles93/archie-core/issues/437), the embedding-backed surprisal strategy, which
|
||||
depends on the above and on [#407](https://github.com/samcharles93/archie-core/issues/407). Requirements for that deferred work,
|
||||
so it can be picked up without re-deriving the design:
|
||||
|
||||
- A `Sampler` implementation behind the same interface as the cheap
|
||||
strategies; selection deterministic given fixed inputs.
|
||||
@@ -89,7 +89,3 @@ then [#437](https://github.com/samcharles93/archie-core/issues/437) surprisal st
|
||||
must never fail or crash a curator pass.
|
||||
- Cost bound: the graph build is quadratic in the candidate cap; the cap must
|
||||
be a named constant with a documented bound.
|
||||
- The embedding capability itself: a narrow typed client usable by in-process
|
||||
components, config-driven provider/model, credential-missing degrades to
|
||||
"capability unavailable" (daemon still starts), timeouts on network calls,
|
||||
tests via httptest only.
|
||||
@@ -0,0 +1,178 @@
|
||||
# Curator sampler wave 1: `Sampler` interface + four cheap strategies -- decision
|
||||
|
||||
**Status:** Approved for implementation
|
||||
**Date:** 2026-09-05
|
||||
**Beads issue:** none yet at time of writing (bead `archie-core-1786637500776-416-600a66e5`
|
||||
/ GitHub #437 covers the embedding-backed follow-on strategy only; this PRD
|
||||
covers the prerequisite interface + cheap strategies, tracked by the new
|
||||
issue this change files, see `new-issues.jsonl`)
|
||||
**Parent epic:** `archie-core-1786637500725` (curator engine)
|
||||
**Depends on:** nothing shipped (this is itself a prerequisite)
|
||||
**Blocks:** the embedding-backed surprisal strategy (GitHub #437), which
|
||||
implements this same interface once the embeddings capability
|
||||
(`internal/domain/embedding`, this change) lands
|
||||
|
||||
## Problem
|
||||
|
||||
A future curator that reviews a large body of content (memories, sessions,
|
||||
skills) cannot always afford to run its agentic budget over every candidate
|
||||
every pass. It needs to pick a bounded subset first. GitHub #437's acceptance
|
||||
criteria requires that subset-picking to sit "behind a `Sampler` interface
|
||||
that wave 1 of the curator epic ships (cheap strategies: recency, random,
|
||||
all, staleness proxy)" and that the embedding-backed strategy implement "the
|
||||
same interface" later. No such interface, and none of the four cheap
|
||||
strategies, exist anywhere in the codebase today (bead 434e5bb9's closure
|
||||
without a linked PR was the tracker being wrong, not the code existing) --
|
||||
this PRD is the one-page settled design for it, per this repo's Scope
|
||||
Discipline rule.
|
||||
|
||||
## Decision
|
||||
|
||||
A `Sampler` is a pure, call-scoped selection function: given a fixed slice of
|
||||
candidates and a request, it returns a subset. No lifecycle, no host access,
|
||||
no I/O for the four wave-1 strategies -- they are computation only, so they
|
||||
live directly in `internal/domain/sampling` (a domain package, not
|
||||
`internal/infrastructure/*`) alongside the contract, the same way
|
||||
`curator/activity.go`'s pure ring buffer sits next to `curator/contract.go`
|
||||
rather than in an infrastructure package.
|
||||
|
||||
```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.
|
||||
package sampling
|
||||
|
||||
// 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 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 here 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,
|
||||
// and is GitHub #437's stated acceptance criterion for the strategy it
|
||||
// adds behind this same interface.
|
||||
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)
|
||||
}
|
||||
```
|
||||
|
||||
### The four wave-1 strategies
|
||||
|
||||
All four are `internal/domain/sampling` types constructed with `NewX(...)`,
|
||||
each implementing `Sampler`:
|
||||
|
||||
- **`recency`** (`NewRecency()`): sorts candidates newest-`At`-first (stable
|
||||
sort, ties keep input order so output is deterministic even when two
|
||||
candidates share a timestamp), then truncates to `req.Cap` (0 = all).
|
||||
- **`staleness`** (`NewStaleness()`): the mirror of recency -- sorts oldest-
|
||||
`At`-first, then truncates to `req.Cap`. This is explicitly a *proxy*:
|
||||
"hasn't been touched in the longest time" using whatever timestamp the
|
||||
caller populated `Candidate.At` with (created, updated, or
|
||||
last-reviewed -- the caller's choice, not this package's), never the
|
||||
embedding-based surprisal calculation GitHub #437 owns.
|
||||
- **`all`** (`NewAll()`): no filtering. Returns candidates in input order,
|
||||
truncated to `req.Cap` (0 = every candidate). Input order is the only
|
||||
order this strategy has an opinion about, and preserving it is what makes
|
||||
it deterministic.
|
||||
- **`random`** (`NewRandom()`): a uniform-random subset, sized to
|
||||
`req.Cap` (0 = every candidate, order-shuffled). Determinism comes from
|
||||
`req.Seed`: `math/rand/v2`'s `rand.New(rand.NewPCG(seed, seed))` seeded
|
||||
per call (not a package-level or struct-level generator), so the same
|
||||
`(candidates, req)` pair always produces the same permutation regardless
|
||||
of call order or concurrent callers -- required for GitHub #437's
|
||||
determinism criterion and for this package's own tests.
|
||||
|
||||
### Why one shared `Request` and not one options struct per strategy
|
||||
|
||||
The embedding-backed strategy (GitHub #437) is deferred, but its stated
|
||||
shape -- "sample up to a candidate cap," a seed for reproducible tie-
|
||||
breaking in the power-iteration -- already fits `Request{Cap, Seed}`
|
||||
without modification. A per-strategy options type would mean GitHub #437
|
||||
either reuses this one (proving it was unnecessary to split) or grows its
|
||||
own incompatible shape that the `Sampler` interface can't express without a
|
||||
breaking change later. One shared, small `Request` is the smallest thing
|
||||
that already accommodates the known future consumer.
|
||||
|
||||
### Why `Candidate.Metadata map[string]any` instead of a typed field per strategy
|
||||
|
||||
Only `ID` and `At` are used by any wave-1 strategy. `Metadata` exists solely
|
||||
so GitHub #437 can carry an embedding vector (or whatever else the k-NN/
|
||||
power-iteration step needs) through the *same* `Candidate` type without this
|
||||
package importing `internal/domain/embedding` or growing a `Vector` field
|
||||
that every non-surprisal strategy ignores. Untyped and optional, exactly
|
||||
like `image.GenerateRequest.Options` and `curator.Action.Detail`'s existing
|
||||
"provider-specific overflow" convention elsewhere in this codebase.
|
||||
|
||||
## What we deliberately do NOT do
|
||||
|
||||
- **No curator-family wiring.** `curator.Registrar` gains no `Sampler`
|
||||
field and no curator declares one in this change. Nothing in
|
||||
`internal/domain/curator` consumes `sampling.Sampler` yet -- there is no
|
||||
curator that samples anything today. Wiring a sampler into a real
|
||||
curator's `Pass` is that future curator's job, not this prerequisite's.
|
||||
- **No embedding-backed strategy.** That is GitHub #437, explicitly
|
||||
deferred behind the embeddings capability this same change also adds
|
||||
(`internal/domain/embedding`) -- see that issue for the k-NN graph /
|
||||
power-iteration / surprisal-scoring algorithm. This package only
|
||||
guarantees the interface shape GitHub #437 must implement.
|
||||
- **No persistence, no candidate discovery.** `Sampler.Sample` takes
|
||||
`candidates` as a plain slice; where they come from (a memory store, a
|
||||
session list, a skill directory) is entirely the caller's concern, same
|
||||
boundary `curator.Registrar`'s `SkillStore`/`ConversationSource` already
|
||||
draw between "the curator finds candidates" and "the curator engine acts
|
||||
on them."
|
||||
- **No configuration surface.** Strategy selection (which `Sampler` a
|
||||
curator uses) is a future curator's constructor argument, not a new
|
||||
`[curator]` config section -- no curator exists yet to configure.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
1. `Sampler` interface plus `Candidate`/`Request` types exist in
|
||||
`internal/domain/sampling`, importing nothing from
|
||||
`internal/infrastructure/*` or `internal/app/*` (domain-layer rule).
|
||||
2. Four `Sampler` implementations (`recency`, `random`, `all`, `staleness`)
|
||||
with table-driven tests proving: correct selection per strategy,
|
||||
`Cap` truncation (including `Cap` larger than the candidate count, and
|
||||
`Cap` 0 meaning unlimited), and -- for `random` -- that the same
|
||||
`(candidates, req)` produces the same output across repeated calls
|
||||
(determinism), while a different `req.Seed` can produce a different
|
||||
permutation.
|
||||
3. Every strategy's `Sample` leaves the input `candidates` slice
|
||||
unmodified (verified by a shared test helper across all four).
|
||||
4. The interface shape is reviewed against GitHub #437's stated
|
||||
acceptance criteria ("a `Sampler` given fixed inputs producing
|
||||
deterministic selection," "sample up to a candidate cap") and
|
||||
accommodates them without a breaking change -- this document's
|
||||
"Why one shared `Request`" section is that review.
|
||||
|
||||
## Files this change adds
|
||||
|
||||
- `internal/domain/sampling/contract.go` -- `Sampler`, `Candidate`,
|
||||
`Request`
|
||||
- `internal/domain/sampling/recency.go`, `staleness.go`, `all.go`,
|
||||
`random.go` -- the four strategies
|
||||
- `internal/domain/sampling/*_test.go` -- table-driven tests per strategy
|
||||
plus the shared non-mutation test helper
|
||||
@@ -33,6 +33,7 @@ import (
|
||||
"github.com/samcharles93/archie-core/internal/domain/curator"
|
||||
"github.com/samcharles93/archie-core/internal/domain/eda/module"
|
||||
"github.com/samcharles93/archie-core/internal/domain/eda/playbook"
|
||||
domainembedding "github.com/samcharles93/archie-core/internal/domain/embedding"
|
||||
domainmemory "github.com/samcharles93/archie-core/internal/domain/memory"
|
||||
"github.com/samcharles93/archie-core/internal/domain/workflow"
|
||||
"github.com/samcharles93/archie-core/internal/domain/workflow/skillbuild"
|
||||
@@ -43,6 +44,7 @@ import (
|
||||
"github.com/samcharles93/archie-core/internal/gateway"
|
||||
"github.com/samcharles93/archie-core/internal/infrastructure/configuration"
|
||||
"github.com/samcharles93/archie-core/internal/infrastructure/configuration/overlay"
|
||||
infraembedding "github.com/samcharles93/archie-core/internal/infrastructure/embedding"
|
||||
"github.com/samcharles93/archie-core/internal/infrastructure/eventbus/nats"
|
||||
infraMemory "github.com/samcharles93/archie-core/internal/infrastructure/memory"
|
||||
"github.com/samcharles93/archie-core/internal/infrastructure/modelcatalog"
|
||||
@@ -121,6 +123,13 @@ type boot struct {
|
||||
|
||||
llm *runtime.Runtime
|
||||
|
||||
// embeddings is nil unless models["embedding"] and a working provider
|
||||
// credential are both configured -- see setupLLMAndChat's "Embeddings
|
||||
// capability" section. Consumers must treat a nil embeddings the same
|
||||
// as domainembedding.ErrUnavailable: skip, never fail startup or an
|
||||
// unrelated call.
|
||||
embeddings domainembedding.Client
|
||||
|
||||
toolReg *tools.Registry
|
||||
chatModels gateway.ModelManager
|
||||
personas *gateway.PersonaRegistry
|
||||
@@ -479,6 +488,23 @@ func (b *boot) setupContainers(ctx context.Context) func() {
|
||||
return closeDocker
|
||||
}
|
||||
|
||||
// setupEmbeddings builds the optional embedding capability. A client is
|
||||
// wired only when models["embedding"] names a provider/model and that
|
||||
// provider's credential resolves -- the same credential-missing-degrades-
|
||||
// not-fatal rule registerMinimaxTool follows for generate_video. No
|
||||
// warning when the role was simply never configured; a warning when it was
|
||||
// configured but couldn't be made to work, so a broken setup doesn't go
|
||||
// unnoticed the way AGENTS.md already warns an unnoticed optional-provider
|
||||
// degradation can.
|
||||
func (b *boot) setupEmbeddings(cfg config.Config, log *slog.Logger) {
|
||||
if client, ok := infraembedding.New(cfg, infraembedding.Options{}); ok {
|
||||
b.embeddings = client
|
||||
log.Info("embedding capability enabled", "role", infraembedding.Role)
|
||||
} else if cfg.Models[infraembedding.Role] != "" {
|
||||
log.Warn("embedding capability configured but unavailable; capability disabled", "role", infraembedding.Role)
|
||||
}
|
||||
}
|
||||
|
||||
// setupLLMAndChat wires the runtime, tool registry, model management,
|
||||
// personas and the dashboard's chat service.
|
||||
func (b *boot) setupLLMAndChat(ctx context.Context) {
|
||||
@@ -494,6 +520,8 @@ func (b *boot) setupLLMAndChat(ctx context.Context) {
|
||||
chatModels.ApplyModelCatalog(b.catalog)
|
||||
b.chatModels = chatModels
|
||||
|
||||
b.setupEmbeddings(cfg, log)
|
||||
|
||||
// ── Persona registry ─────────────────────────────────────────────
|
||||
b.personas = gateway.NewPersonaRegistry(gateway.DefaultPersonas())
|
||||
|
||||
|
||||
@@ -0,0 +1,44 @@
|
||||
// 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)
|
||||
}
|
||||
@@ -0,0 +1,19 @@
|
||||
package sampling
|
||||
|
||||
import "context"
|
||||
|
||||
// allSampler is the "all" strategy: no filtering, returns every candidate
|
||||
// in input order, truncated to Request.Cap.
|
||||
type allSampler struct{}
|
||||
|
||||
// NewAll builds the "all" strategy.
|
||||
func NewAll() Sampler { return allSampler{} }
|
||||
|
||||
func (allSampler) Name() string { return "all" }
|
||||
|
||||
func (allSampler) Sample(_ context.Context, candidates []Candidate, req Request) ([]Candidate, error) {
|
||||
n := effectiveCap(req.Cap, len(candidates))
|
||||
out := make([]Candidate, n)
|
||||
copy(out, candidates[:n])
|
||||
return out, nil
|
||||
}
|
||||
@@ -0,0 +1,61 @@
|
||||
package sampling
|
||||
|
||||
import (
|
||||
"context"
|
||||
"testing"
|
||||
"time"
|
||||
)
|
||||
|
||||
func TestAllSampler(t *testing.T) {
|
||||
t.Parallel()
|
||||
|
||||
base := time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC)
|
||||
candidates := []Candidate{
|
||||
{ID: "a", At: base},
|
||||
{ID: "b", At: base.Add(time.Hour)},
|
||||
{ID: "c", At: base.Add(2 * time.Hour)},
|
||||
}
|
||||
|
||||
tests := []struct {
|
||||
name string
|
||||
cap int
|
||||
wantIDs []string
|
||||
}{
|
||||
{name: "no cap returns everything in input order", cap: 0, wantIDs: []string{"a", "b", "c"}},
|
||||
{name: "cap truncates from the front", cap: 2, wantIDs: []string{"a", "b"}},
|
||||
{name: "cap larger than candidate count returns everything", cap: 100, wantIDs: []string{"a", "b", "c"}},
|
||||
{name: "negative cap means unlimited", cap: -1, wantIDs: []string{"a", "b", "c"}},
|
||||
}
|
||||
|
||||
s := NewAll()
|
||||
if s.Name() != "all" {
|
||||
t.Fatalf("Name() = %q, want %q", s.Name(), "all")
|
||||
}
|
||||
|
||||
for _, tt := range tests {
|
||||
t.Run(tt.name, func(t *testing.T) {
|
||||
t.Parallel()
|
||||
got, err := s.Sample(context.Background(), candidates, Request{Cap: tt.cap})
|
||||
if err != nil {
|
||||
t.Fatalf("Sample() error = %v", err)
|
||||
}
|
||||
assertIDs(t, got, tt.wantIDs)
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
func TestAllSamplerEmptyInput(t *testing.T) {
|
||||
t.Parallel()
|
||||
got, err := NewAll().Sample(context.Background(), nil, Request{})
|
||||
if err != nil {
|
||||
t.Fatalf("Sample() error = %v", err)
|
||||
}
|
||||
if len(got) != 0 {
|
||||
t.Fatalf("Sample() = %v, want empty", got)
|
||||
}
|
||||
}
|
||||
|
||||
func TestAllSamplerDoesNotMutateInput(t *testing.T) {
|
||||
t.Parallel()
|
||||
assertInputNotMutated(t, NewAll())
|
||||
}
|
||||
@@ -0,0 +1,56 @@
|
||||
// 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
|
||||
}
|
||||
@@ -0,0 +1,32 @@
|
||||
package sampling
|
||||
|
||||
import (
|
||||
"context"
|
||||
"math/rand/v2"
|
||||
)
|
||||
|
||||
// randomSampler is the "random" strategy: a uniform random subset, seeded
|
||||
// per call from Request.Seed so the same (candidates, req) pair always
|
||||
// produces the same selection -- a package-level or struct-level generator
|
||||
// would not give that guarantee under concurrent or repeated calls.
|
||||
type randomSampler struct{}
|
||||
|
||||
// NewRandom builds the "random" strategy.
|
||||
func NewRandom() Sampler { return randomSampler{} }
|
||||
|
||||
func (randomSampler) Name() string { return "random" }
|
||||
|
||||
func (randomSampler) Sample(_ context.Context, candidates []Candidate, req Request) ([]Candidate, error) {
|
||||
if len(candidates) == 0 {
|
||||
return nil, nil
|
||||
}
|
||||
n := effectiveCap(req.Cap, len(candidates))
|
||||
seed := uint64(req.Seed) //nolint:gosec // deterministic seeding, not a security boundary
|
||||
rng := rand.New(rand.NewPCG(seed, seed))
|
||||
order := rng.Perm(len(candidates))
|
||||
out := make([]Candidate, n)
|
||||
for i := range n {
|
||||
out[i] = candidates[order[i]]
|
||||
}
|
||||
return out, nil
|
||||
}
|
||||
@@ -0,0 +1,140 @@
|
||||
package sampling
|
||||
|
||||
import (
|
||||
"context"
|
||||
"testing"
|
||||
"time"
|
||||
)
|
||||
|
||||
func candidatesFor(n int) []Candidate {
|
||||
base := time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC)
|
||||
out := make([]Candidate, n)
|
||||
for i := range out {
|
||||
out[i] = Candidate{ID: string(rune('a' + i)), At: base.Add(time.Duration(i) * time.Hour)}
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
func TestRandomSamplerName(t *testing.T) {
|
||||
t.Parallel()
|
||||
if got := NewRandom().Name(); got != "random" {
|
||||
t.Fatalf("Name() = %q, want %q", got, "random")
|
||||
}
|
||||
}
|
||||
|
||||
func TestRandomSamplerCap(t *testing.T) {
|
||||
t.Parallel()
|
||||
candidates := candidatesFor(10)
|
||||
|
||||
tests := []struct {
|
||||
name string
|
||||
cap int
|
||||
wantLen int
|
||||
}{
|
||||
{name: "no cap returns every candidate", cap: 0, wantLen: 10},
|
||||
{name: "cap smaller than count", cap: 3, wantLen: 3},
|
||||
{name: "cap larger than count returns every candidate", cap: 100, wantLen: 10},
|
||||
}
|
||||
|
||||
for _, tt := range tests {
|
||||
t.Run(tt.name, func(t *testing.T) {
|
||||
t.Parallel()
|
||||
got, err := NewRandom().Sample(context.Background(), candidates, Request{Cap: tt.cap, Seed: 1})
|
||||
if err != nil {
|
||||
t.Fatalf("Sample() error = %v", err)
|
||||
}
|
||||
if len(got) != tt.wantLen {
|
||||
t.Fatalf("len(Sample()) = %d, want %d", len(got), tt.wantLen)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
func TestRandomSamplerSelectionIsASubsetOfInput(t *testing.T) {
|
||||
t.Parallel()
|
||||
candidates := candidatesFor(10)
|
||||
got, err := NewRandom().Sample(context.Background(), candidates, Request{Cap: 5, Seed: 42})
|
||||
if err != nil {
|
||||
t.Fatalf("Sample() error = %v", err)
|
||||
}
|
||||
|
||||
valid := make(map[string]bool, len(candidates))
|
||||
for _, c := range candidates {
|
||||
valid[c.ID] = true
|
||||
}
|
||||
seen := make(map[string]bool, len(got))
|
||||
for _, c := range got {
|
||||
if !valid[c.ID] {
|
||||
t.Fatalf("Sample() returned candidate %q not present in input", c.ID)
|
||||
}
|
||||
if seen[c.ID] {
|
||||
t.Fatalf("Sample() returned candidate %q more than once", c.ID)
|
||||
}
|
||||
seen[c.ID] = true
|
||||
}
|
||||
}
|
||||
|
||||
func TestRandomSamplerDeterministicForSameSeed(t *testing.T) {
|
||||
t.Parallel()
|
||||
candidates := candidatesFor(20)
|
||||
s := NewRandom()
|
||||
|
||||
first, err := s.Sample(context.Background(), candidates, Request{Cap: 8, Seed: 99})
|
||||
if err != nil {
|
||||
t.Fatalf("Sample() error = %v", err)
|
||||
}
|
||||
second, err := s.Sample(context.Background(), candidates, Request{Cap: 8, Seed: 99})
|
||||
if err != nil {
|
||||
t.Fatalf("Sample() error = %v", err)
|
||||
}
|
||||
|
||||
wantIDs := make([]string, len(first))
|
||||
for i, c := range first {
|
||||
wantIDs[i] = c.ID
|
||||
}
|
||||
assertIDs(t, second, wantIDs)
|
||||
}
|
||||
|
||||
func TestRandomSamplerDifferentSeedsCanDiffer(t *testing.T) {
|
||||
t.Parallel()
|
||||
candidates := candidatesFor(20)
|
||||
s := NewRandom()
|
||||
|
||||
a, err := s.Sample(context.Background(), candidates, Request{Cap: 8, Seed: 1})
|
||||
if err != nil {
|
||||
t.Fatalf("Sample() error = %v", err)
|
||||
}
|
||||
b, err := s.Sample(context.Background(), candidates, Request{Cap: 8, Seed: 2})
|
||||
if err != nil {
|
||||
t.Fatalf("Sample() error = %v", err)
|
||||
}
|
||||
|
||||
same := len(a) == len(b)
|
||||
if same {
|
||||
for i := range a {
|
||||
if a[i].ID != b[i].ID {
|
||||
same = false
|
||||
break
|
||||
}
|
||||
}
|
||||
}
|
||||
if same {
|
||||
t.Fatalf("Sample() with different seeds produced identical output: %v", a)
|
||||
}
|
||||
}
|
||||
|
||||
func TestRandomSamplerEmptyInput(t *testing.T) {
|
||||
t.Parallel()
|
||||
got, err := NewRandom().Sample(context.Background(), nil, Request{Seed: 1})
|
||||
if err != nil {
|
||||
t.Fatalf("Sample() error = %v", err)
|
||||
}
|
||||
if len(got) != 0 {
|
||||
t.Fatalf("Sample() = %v, want empty", got)
|
||||
}
|
||||
}
|
||||
|
||||
func TestRandomSamplerDoesNotMutateInput(t *testing.T) {
|
||||
t.Parallel()
|
||||
assertInputNotMutated(t, NewRandom())
|
||||
}
|
||||
@@ -0,0 +1,36 @@
|
||||
package sampling
|
||||
|
||||
import (
|
||||
"context"
|
||||
"slices"
|
||||
)
|
||||
|
||||
// recencySampler is the "recency" strategy: prefers more recently
|
||||
// created/updated content, i.e. the largest Candidate.At first.
|
||||
type recencySampler struct{}
|
||||
|
||||
// NewRecency builds the "recency" strategy.
|
||||
func NewRecency() Sampler { return recencySampler{} }
|
||||
|
||||
func (recencySampler) Name() string { return "recency" }
|
||||
|
||||
func (recencySampler) Sample(_ context.Context, candidates []Candidate, req Request) ([]Candidate, error) {
|
||||
sorted := sortByTime(candidates, true)
|
||||
return sorted[:effectiveCap(req.Cap, len(sorted))], nil
|
||||
}
|
||||
|
||||
// sortByTime returns a stably-sorted copy of candidates, never mutating the
|
||||
// input. newestFirst true sorts descending by At (recency); false sorts
|
||||
// ascending (staleness). A stable sort keeps ties in input order, which is
|
||||
// what makes both strategies deterministic when candidates share a
|
||||
// timestamp.
|
||||
func sortByTime(candidates []Candidate, newestFirst bool) []Candidate {
|
||||
sorted := append([]Candidate(nil), candidates...)
|
||||
slices.SortStableFunc(sorted, func(a, b Candidate) int {
|
||||
if newestFirst {
|
||||
return b.At.Compare(a.At)
|
||||
}
|
||||
return a.At.Compare(b.At)
|
||||
})
|
||||
return sorted
|
||||
}
|
||||
@@ -0,0 +1,64 @@
|
||||
package sampling
|
||||
|
||||
import (
|
||||
"context"
|
||||
"testing"
|
||||
"time"
|
||||
)
|
||||
|
||||
func TestRecencySampler(t *testing.T) {
|
||||
t.Parallel()
|
||||
|
||||
base := time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC)
|
||||
candidates := []Candidate{
|
||||
{ID: "oldest", At: base},
|
||||
{ID: "middle", At: base.Add(time.Hour)},
|
||||
{ID: "newest", At: base.Add(2 * time.Hour)},
|
||||
}
|
||||
|
||||
tests := []struct {
|
||||
name string
|
||||
cap int
|
||||
wantIDs []string
|
||||
}{
|
||||
{name: "no cap orders newest first", cap: 0, wantIDs: []string{"newest", "middle", "oldest"}},
|
||||
{name: "cap keeps only the most recent", cap: 2, wantIDs: []string{"newest", "middle"}},
|
||||
{name: "cap larger than count returns everything", cap: 100, wantIDs: []string{"newest", "middle", "oldest"}},
|
||||
}
|
||||
|
||||
s := NewRecency()
|
||||
if s.Name() != "recency" {
|
||||
t.Fatalf("Name() = %q, want %q", s.Name(), "recency")
|
||||
}
|
||||
|
||||
for _, tt := range tests {
|
||||
t.Run(tt.name, func(t *testing.T) {
|
||||
t.Parallel()
|
||||
got, err := s.Sample(context.Background(), candidates, Request{Cap: tt.cap})
|
||||
if err != nil {
|
||||
t.Fatalf("Sample() error = %v", err)
|
||||
}
|
||||
assertIDs(t, got, tt.wantIDs)
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
func TestRecencySamplerTiesKeepInputOrder(t *testing.T) {
|
||||
t.Parallel()
|
||||
at := time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC)
|
||||
candidates := []Candidate{
|
||||
{ID: "first", At: at},
|
||||
{ID: "second", At: at},
|
||||
{ID: "third", At: at},
|
||||
}
|
||||
got, err := NewRecency().Sample(context.Background(), candidates, Request{})
|
||||
if err != nil {
|
||||
t.Fatalf("Sample() error = %v", err)
|
||||
}
|
||||
assertIDs(t, got, []string{"first", "second", "third"})
|
||||
}
|
||||
|
||||
func TestRecencySamplerDoesNotMutateInput(t *testing.T) {
|
||||
t.Parallel()
|
||||
assertInputNotMutated(t, NewRecency())
|
||||
}
|
||||
@@ -0,0 +1,48 @@
|
||||
package sampling
|
||||
|
||||
import (
|
||||
"context"
|
||||
"testing"
|
||||
"time"
|
||||
)
|
||||
|
||||
// assertIDs checks got's IDs match want, in order.
|
||||
func assertIDs(t *testing.T, got []Candidate, want []string) {
|
||||
t.Helper()
|
||||
if len(got) != len(want) {
|
||||
t.Fatalf("got %d candidates, want %d (%v)", len(got), len(want), want)
|
||||
}
|
||||
for i, c := range got {
|
||||
if c.ID != want[i] {
|
||||
t.Fatalf("candidate[%d].ID = %q, want %q", i, c.ID, want[i])
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// assertInputNotMutated builds a candidate slice, samples it through s,
|
||||
// then verifies the original slice's order and values are untouched --
|
||||
// the non-mutation guarantee every Sampler implementation must uphold.
|
||||
func assertInputNotMutated(t *testing.T, s Sampler) {
|
||||
t.Helper()
|
||||
base := time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC)
|
||||
candidates := []Candidate{
|
||||
{ID: "a", At: base.Add(3 * time.Hour)},
|
||||
{ID: "b", At: base.Add(time.Hour)},
|
||||
{ID: "c", At: base.Add(2 * time.Hour)},
|
||||
{ID: "d", At: base},
|
||||
}
|
||||
original := append([]Candidate(nil), candidates...)
|
||||
|
||||
if _, err := s.Sample(context.Background(), candidates, Request{Cap: 2, Seed: 7}); err != nil {
|
||||
t.Fatalf("Sample() error = %v", err)
|
||||
}
|
||||
|
||||
if len(candidates) != len(original) {
|
||||
t.Fatalf("input slice length changed: got %d, want %d", len(candidates), len(original))
|
||||
}
|
||||
for i := range candidates {
|
||||
if candidates[i].ID != original[i].ID || !candidates[i].At.Equal(original[i].At) {
|
||||
t.Fatalf("input slice mutated at index %d: got %+v, want %+v", i, candidates[i], original[i])
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,20 @@
|
||||
package sampling
|
||||
|
||||
import "context"
|
||||
|
||||
// stalenessSampler is the "staleness proxy" strategy: prefers content that
|
||||
// hasn't been touched/reviewed in the longest time, i.e. the smallest
|
||||
// Candidate.At first. It is a cheap proxy only -- callers decide what
|
||||
// timestamp At holds (created, updated, or last-reviewed); this is never
|
||||
// the embedding-based surprisal calculation (see GitHub #437).
|
||||
type stalenessSampler struct{}
|
||||
|
||||
// NewStaleness builds the "staleness" strategy.
|
||||
func NewStaleness() Sampler { return stalenessSampler{} }
|
||||
|
||||
func (stalenessSampler) Name() string { return "staleness" }
|
||||
|
||||
func (stalenessSampler) Sample(_ context.Context, candidates []Candidate, req Request) ([]Candidate, error) {
|
||||
sorted := sortByTime(candidates, false)
|
||||
return sorted[:effectiveCap(req.Cap, len(sorted))], nil
|
||||
}
|
||||
@@ -0,0 +1,64 @@
|
||||
package sampling
|
||||
|
||||
import (
|
||||
"context"
|
||||
"testing"
|
||||
"time"
|
||||
)
|
||||
|
||||
func TestStalenessSampler(t *testing.T) {
|
||||
t.Parallel()
|
||||
|
||||
base := time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC)
|
||||
candidates := []Candidate{
|
||||
{ID: "newest", At: base.Add(2 * time.Hour)},
|
||||
{ID: "middle", At: base.Add(time.Hour)},
|
||||
{ID: "oldest", At: base},
|
||||
}
|
||||
|
||||
tests := []struct {
|
||||
name string
|
||||
cap int
|
||||
wantIDs []string
|
||||
}{
|
||||
{name: "no cap orders oldest first", cap: 0, wantIDs: []string{"oldest", "middle", "newest"}},
|
||||
{name: "cap keeps only the stalest", cap: 2, wantIDs: []string{"oldest", "middle"}},
|
||||
{name: "cap larger than count returns everything", cap: 100, wantIDs: []string{"oldest", "middle", "newest"}},
|
||||
}
|
||||
|
||||
s := NewStaleness()
|
||||
if s.Name() != "staleness" {
|
||||
t.Fatalf("Name() = %q, want %q", s.Name(), "staleness")
|
||||
}
|
||||
|
||||
for _, tt := range tests {
|
||||
t.Run(tt.name, func(t *testing.T) {
|
||||
t.Parallel()
|
||||
got, err := s.Sample(context.Background(), candidates, Request{Cap: tt.cap})
|
||||
if err != nil {
|
||||
t.Fatalf("Sample() error = %v", err)
|
||||
}
|
||||
assertIDs(t, got, tt.wantIDs)
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
func TestStalenessSamplerTiesKeepInputOrder(t *testing.T) {
|
||||
t.Parallel()
|
||||
at := time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC)
|
||||
candidates := []Candidate{
|
||||
{ID: "first", At: at},
|
||||
{ID: "second", At: at},
|
||||
{ID: "third", At: at},
|
||||
}
|
||||
got, err := NewStaleness().Sample(context.Background(), candidates, Request{})
|
||||
if err != nil {
|
||||
t.Fatalf("Sample() error = %v", err)
|
||||
}
|
||||
assertIDs(t, got, []string{"first", "second", "third"})
|
||||
}
|
||||
|
||||
func TestStalenessSamplerDoesNotMutateInput(t *testing.T) {
|
||||
t.Parallel()
|
||||
assertInputNotMutated(t, NewStaleness())
|
||||
}
|
||||
@@ -0,0 +1,151 @@
|
||||
// Package embedding implements the internal/domain/embedding.Client
|
||||
// contract over the ai-sdk provider SDKs already vendored for chat, so
|
||||
// this capability is config-driven the same way chat model roles already
|
||||
// are (a providers table + a role in [models]).
|
||||
package embedding
|
||||
|
||||
import (
|
||||
"context"
|
||||
"fmt"
|
||||
"net/http"
|
||||
"os"
|
||||
"strings"
|
||||
"time"
|
||||
|
||||
sdkembed "github.com/samcharles93/ai-sdk/embed"
|
||||
"github.com/samcharles93/ai-sdk/provider/cohere"
|
||||
"github.com/samcharles93/ai-sdk/provider/gemini"
|
||||
"github.com/samcharles93/ai-sdk/provider/mistral"
|
||||
"github.com/samcharles93/ai-sdk/provider/ollama"
|
||||
"github.com/samcharles93/ai-sdk/provider/openai"
|
||||
|
||||
"github.com/samcharles93/archie-core/internal/config"
|
||||
domainembedding "github.com/samcharles93/archie-core/internal/domain/embedding"
|
||||
)
|
||||
|
||||
// Role is the [models] key embedding consumers use, matching the
|
||||
// "builder"/"planner"/"triage" role convention chat models already use
|
||||
// (internal/domain/workflow/agent.go).
|
||||
const Role = "embedding"
|
||||
|
||||
// DefaultTimeout bounds one embedding request when Options.Timeout is
|
||||
// unset.
|
||||
const DefaultTimeout = 30 * time.Second
|
||||
|
||||
// Options configures New.
|
||||
type Options struct {
|
||||
// Getenv resolves a provider's APIKeyEnv to its credential. Defaults to
|
||||
// os.Getenv; overridable for tests.
|
||||
Getenv func(string) string
|
||||
// Timeout bounds one embedding request. Defaults to DefaultTimeout.
|
||||
Timeout time.Duration
|
||||
}
|
||||
|
||||
// New builds an embedding client from cfg.Models[Role] and the matching
|
||||
// cfg.Providers entry. It reports (nil, false) rather than an error when
|
||||
// the capability is not usable right now -- no role configured, an unknown
|
||||
// provider, an unsupported provider class, or a missing/blank credential
|
||||
// -- per the credential-missing-degrades-not-fatal rule (AGENTS.md):
|
||||
// callers must skip the capability, never fail daemon startup or an
|
||||
// unrelated call, over this.
|
||||
//
|
||||
// cfg.Providers is expected to already have secret refs resolved to
|
||||
// APIKeyEnv (see internal/app/archied/provider_secrets.go's
|
||||
// resolveProviderSecrets), the same precondition agentexec.NewRuntime
|
||||
// relies on for chat models.
|
||||
func New(cfg config.Config, opts Options) (domainembedding.Client, bool) {
|
||||
getenv := opts.Getenv
|
||||
if getenv == nil {
|
||||
getenv = os.Getenv
|
||||
}
|
||||
timeout := opts.Timeout
|
||||
if timeout <= 0 {
|
||||
timeout = DefaultTimeout
|
||||
}
|
||||
|
||||
providerID, modelID, ok := parseModelRef(cfg.Models[Role])
|
||||
if !ok {
|
||||
return nil, false
|
||||
}
|
||||
provider, ok := cfg.Providers[providerID]
|
||||
if !ok {
|
||||
return nil, false
|
||||
}
|
||||
|
||||
apiKey := ""
|
||||
if provider.APIKeyEnv != "" {
|
||||
apiKey = strings.TrimSpace(getenv(provider.APIKeyEnv))
|
||||
if apiKey == "" {
|
||||
return nil, false
|
||||
}
|
||||
}
|
||||
|
||||
sdkProvider, err := newSDKProvider(provider.Class, apiKey, provider.BaseURL, &http.Client{Timeout: timeout})
|
||||
if err != nil {
|
||||
return nil, false
|
||||
}
|
||||
return &client{provider: sdkembed.NewClient(sdkProvider), model: modelID}, true
|
||||
}
|
||||
|
||||
// parseModelRef splits a "provider/model" role value the same way
|
||||
// ai-sdk/runtime.Runtime.ParseModelRef does, without depending on a
|
||||
// Runtime instance.
|
||||
func parseModelRef(ref string) (providerID, modelID string, ok bool) {
|
||||
ref = strings.TrimSpace(ref)
|
||||
if ref == "" {
|
||||
return "", "", false
|
||||
}
|
||||
providerID, modelID, hasSlash := strings.Cut(ref, "/")
|
||||
providerID, modelID = strings.TrimSpace(providerID), strings.TrimSpace(modelID)
|
||||
if !hasSlash || providerID == "" || modelID == "" {
|
||||
return "", "", false
|
||||
}
|
||||
return providerID, modelID, true
|
||||
}
|
||||
|
||||
// newSDKProvider constructs the ai-sdk embed.Provider for a config class.
|
||||
// Only classes matching config.Provider's shape (APIKey/BaseURL, no
|
||||
// provider-specific extra fields) are supported -- azure's Deployment
|
||||
// requirement, for example, has no field to source it from yet, so an
|
||||
// "azure" class degrades like any other unsupported class rather than
|
||||
// gaining a special-cased partial wiring.
|
||||
func newSDKProvider(class, apiKey, baseURL string, httpClient *http.Client) (sdkembed.Provider, error) {
|
||||
switch class {
|
||||
case "openai", "openai-compatible":
|
||||
return openai.New(openai.Config{APIKey: apiKey, BaseURL: baseURL, HTTPClient: httpClient})
|
||||
case "gemini":
|
||||
return gemini.New(gemini.Config{APIKey: apiKey, BaseURL: baseURL, HTTPClient: httpClient})
|
||||
case "ollama":
|
||||
return ollama.New(ollama.Config{BaseURL: baseURL, HTTPClient: httpClient}), nil
|
||||
case "cohere":
|
||||
return cohere.New(cohere.Config{APIKey: apiKey, BaseURL: baseURL, HTTPClient: httpClient})
|
||||
case "mistral":
|
||||
return mistral.New(mistral.Config{APIKey: apiKey, BaseURL: baseURL, HTTPClient: httpClient})
|
||||
default:
|
||||
return nil, fmt.Errorf("embedding: provider class %q does not support embeddings", class)
|
||||
}
|
||||
}
|
||||
|
||||
// client adapts an ai-sdk embed.Client to domainembedding.Client.
|
||||
type client struct {
|
||||
provider *sdkembed.Client
|
||||
model string
|
||||
}
|
||||
|
||||
func (c *client) Embed(ctx context.Context, texts []string) ([]domainembedding.Vector, error) {
|
||||
if len(texts) == 0 {
|
||||
return nil, domainembedding.ErrEmptyInput
|
||||
}
|
||||
resp, err := c.provider.Embed(ctx, sdkembed.Request{Model: c.model, Inputs: texts})
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("embedding: %w", err)
|
||||
}
|
||||
vectors := make([]domainembedding.Vector, len(texts))
|
||||
for _, e := range resp.Embeddings {
|
||||
if e.Index < 0 || e.Index >= len(vectors) {
|
||||
continue
|
||||
}
|
||||
vectors[e.Index] = domainembedding.Vector(e.Vector)
|
||||
}
|
||||
return vectors, nil
|
||||
}
|
||||
@@ -0,0 +1,211 @@
|
||||
package embedding
|
||||
|
||||
import (
|
||||
"context"
|
||||
"encoding/json"
|
||||
"errors"
|
||||
"net/http"
|
||||
"net/http/httptest"
|
||||
"testing"
|
||||
"time"
|
||||
|
||||
"github.com/samcharles93/archie-core/internal/config"
|
||||
domainembedding "github.com/samcharles93/archie-core/internal/domain/embedding"
|
||||
)
|
||||
|
||||
func TestNewDegradesWhenNoRoleConfigured(t *testing.T) {
|
||||
t.Parallel()
|
||||
cfg := config.Config{}
|
||||
if _, ok := New(cfg, Options{}); ok {
|
||||
t.Fatal("New() ok = true, want false when models[embedding] is unset")
|
||||
}
|
||||
}
|
||||
|
||||
func TestNewDegradesWhenProviderUnknown(t *testing.T) {
|
||||
t.Parallel()
|
||||
cfg := config.Config{
|
||||
Models: map[string]string{Role: "openai/text-embedding-3-small"},
|
||||
}
|
||||
if _, ok := New(cfg, Options{}); ok {
|
||||
t.Fatal("New() ok = true, want false when the provider is not configured")
|
||||
}
|
||||
}
|
||||
|
||||
func TestNewDegradesWhenRefHasNoProviderPrefix(t *testing.T) {
|
||||
t.Parallel()
|
||||
cfg := config.Config{
|
||||
Models: map[string]string{Role: "text-embedding-3-small"},
|
||||
Providers: map[string]config.Provider{"openai": {Class: "openai", APIKeyEnv: "TEST_KEY"}},
|
||||
}
|
||||
if _, ok := New(cfg, Options{Getenv: constEnv("secret")}); ok {
|
||||
t.Fatal("New() ok = true, want false for a model ref with no provider/ prefix")
|
||||
}
|
||||
}
|
||||
|
||||
func TestNewDegradesWhenCredentialMissing(t *testing.T) {
|
||||
t.Parallel()
|
||||
cfg := config.Config{
|
||||
Models: map[string]string{Role: "openai/text-embedding-3-small"},
|
||||
Providers: map[string]config.Provider{"openai": {Class: "openai", APIKeyEnv: "TEST_MISSING_KEY"}},
|
||||
}
|
||||
if _, ok := New(cfg, Options{Getenv: constEnv("")}); ok {
|
||||
t.Fatal("New() ok = true, want false when the configured credential env var is empty")
|
||||
}
|
||||
}
|
||||
|
||||
func TestNewDegradesForUnsupportedProviderClass(t *testing.T) {
|
||||
t.Parallel()
|
||||
cfg := config.Config{
|
||||
Models: map[string]string{Role: "custom/some-model"},
|
||||
Providers: map[string]config.Provider{"custom": {Class: "azure", APIKeyEnv: "TEST_KEY"}},
|
||||
}
|
||||
if _, ok := New(cfg, Options{Getenv: constEnv("secret")}); ok {
|
||||
t.Fatal("New() ok = true, want false for a provider class embeddings doesn't support")
|
||||
}
|
||||
}
|
||||
|
||||
func TestNewSucceedsWhenNoCredentialRequired(t *testing.T) {
|
||||
t.Parallel()
|
||||
cfg := config.Config{
|
||||
Models: map[string]string{Role: "local/nomic-embed-text"},
|
||||
Providers: map[string]config.Provider{"local": {Class: "ollama"}},
|
||||
}
|
||||
if _, ok := New(cfg, Options{}); !ok {
|
||||
t.Fatal("New() ok = false, want true for a credential-free provider class (ollama)")
|
||||
}
|
||||
}
|
||||
|
||||
func TestClientEmbedReturnsVectorsInInputOrder(t *testing.T) {
|
||||
t.Parallel()
|
||||
|
||||
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
if r.URL.Path != "/v1/embeddings" {
|
||||
t.Fatalf("unexpected path %q", r.URL.Path)
|
||||
}
|
||||
var body struct {
|
||||
Model string `json:"model"`
|
||||
Input []string `json:"input"`
|
||||
}
|
||||
if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
|
||||
t.Fatalf("decode request: %v", err)
|
||||
}
|
||||
if body.Model != "text-embedding-3-small" {
|
||||
t.Fatalf("model = %q, want %q", body.Model, "text-embedding-3-small")
|
||||
}
|
||||
resp := map[string]any{
|
||||
"object": "list",
|
||||
"model": body.Model,
|
||||
"data": []map[string]any{
|
||||
{"object": "embedding", "index": 1, "embedding": []float32{0.4, 0.5}},
|
||||
{"object": "embedding", "index": 0, "embedding": []float32{0.1, 0.2}},
|
||||
},
|
||||
"usage": map[string]any{"prompt_tokens": 3, "total_tokens": 3},
|
||||
}
|
||||
w.Header().Set("Content-Type", "application/json")
|
||||
_ = json.NewEncoder(w).Encode(resp)
|
||||
}))
|
||||
t.Cleanup(srv.Close)
|
||||
|
||||
cfg := config.Config{
|
||||
Models: map[string]string{Role: "openai/text-embedding-3-small"},
|
||||
Providers: map[string]config.Provider{
|
||||
"openai": {Class: "openai", APIKeyEnv: "TEST_OPENAI_KEY", BaseURL: srv.URL},
|
||||
},
|
||||
}
|
||||
c, ok := New(cfg, Options{Getenv: constEnv("secret")})
|
||||
if !ok {
|
||||
t.Fatal("New() ok = false, want true")
|
||||
}
|
||||
|
||||
vectors, err := c.Embed(context.Background(), []string{"hello", "world"})
|
||||
if err != nil {
|
||||
t.Fatalf("Embed() error = %v", err)
|
||||
}
|
||||
if len(vectors) != 2 {
|
||||
t.Fatalf("len(vectors) = %d, want 2", len(vectors))
|
||||
}
|
||||
if got := vectors[0]; len(got) != 2 || got[0] != 0.1 || got[1] != 0.2 {
|
||||
t.Fatalf("vectors[0] = %v, want [0.1 0.2]", got)
|
||||
}
|
||||
if got := vectors[1]; len(got) != 2 || got[0] != 0.4 || got[1] != 0.5 {
|
||||
t.Fatalf("vectors[1] = %v, want [0.4 0.5]", got)
|
||||
}
|
||||
}
|
||||
|
||||
func TestClientEmbedSurfacesProviderFailureAsError(t *testing.T) {
|
||||
t.Parallel()
|
||||
|
||||
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
w.WriteHeader(http.StatusUnauthorized)
|
||||
_, _ = w.Write([]byte(`{"error":"invalid api key"}`))
|
||||
}))
|
||||
t.Cleanup(srv.Close)
|
||||
|
||||
cfg := config.Config{
|
||||
Models: map[string]string{Role: "openai/text-embedding-3-small"},
|
||||
Providers: map[string]config.Provider{
|
||||
"openai": {Class: "openai", APIKeyEnv: "TEST_OPENAI_KEY", BaseURL: srv.URL},
|
||||
},
|
||||
}
|
||||
c, ok := New(cfg, Options{Getenv: constEnv("bad-key")})
|
||||
if !ok {
|
||||
t.Fatal("New() ok = false, want true")
|
||||
}
|
||||
|
||||
if _, err := c.Embed(context.Background(), []string{"hello"}); err == nil {
|
||||
t.Fatal("Embed() error = nil, want a reported error for the 401 response")
|
||||
}
|
||||
}
|
||||
|
||||
func TestClientEmbedRespectsTimeout(t *testing.T) {
|
||||
t.Parallel()
|
||||
|
||||
release := make(chan struct{})
|
||||
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
<-release
|
||||
}))
|
||||
// Cleanups run LIFO: srv.Close (registered first) waits for the
|
||||
// in-flight handler to return, so release must close before it does --
|
||||
// hence registering it second, not for statement-order readability.
|
||||
t.Cleanup(srv.Close)
|
||||
t.Cleanup(func() { close(release) })
|
||||
|
||||
cfg := config.Config{
|
||||
Models: map[string]string{Role: "openai/text-embedding-3-small"},
|
||||
Providers: map[string]config.Provider{
|
||||
"openai": {Class: "openai", APIKeyEnv: "TEST_OPENAI_KEY", BaseURL: srv.URL},
|
||||
},
|
||||
}
|
||||
c, ok := New(cfg, Options{Getenv: constEnv("secret"), Timeout: 50 * time.Millisecond})
|
||||
if !ok {
|
||||
t.Fatal("New() ok = false, want true")
|
||||
}
|
||||
|
||||
start := time.Now()
|
||||
_, err := c.Embed(context.Background(), []string{"hello"})
|
||||
if err == nil {
|
||||
t.Fatal("Embed() error = nil, want a timeout error")
|
||||
}
|
||||
if elapsed := time.Since(start); elapsed > 2*time.Second {
|
||||
t.Fatalf("Embed() took %v, want it bounded by the configured timeout", elapsed)
|
||||
}
|
||||
}
|
||||
|
||||
func TestClientEmbedRejectsEmptyInput(t *testing.T) {
|
||||
t.Parallel()
|
||||
cfg := config.Config{
|
||||
Models: map[string]string{Role: "local/nomic-embed-text"},
|
||||
Providers: map[string]config.Provider{"local": {Class: "ollama"}},
|
||||
}
|
||||
c, ok := New(cfg, Options{})
|
||||
if !ok {
|
||||
t.Fatal("New() ok = false, want true")
|
||||
}
|
||||
if _, err := c.Embed(context.Background(), nil); !errors.Is(err, domainembedding.ErrEmptyInput) {
|
||||
t.Fatalf("Embed() error = %v, want %v", err, domainembedding.ErrEmptyInput)
|
||||
}
|
||||
}
|
||||
|
||||
func constEnv(value string) func(string) string {
|
||||
return func(string) string { return value }
|
||||
}
|
||||
Reference in new issue
Block a user