From 6affe0eea32f6de420d587f4000e4591e5bd4352 Mon Sep 17 00:00:00 2001 From: Sam Date: Sat, 5 Sep 2026 22:53:08 +1000 Subject: [PATCH] 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 --- CLAUDE.md | 13 ++ config.example.toml | 4 + docs/architecture/plugins-and-extensions.md | 38 ++-- docs/prds/curator-sampler-wave1.md | 178 +++++++++++++++ internal/app/archied/bootstrap.go | 28 +++ internal/domain/embedding/contract.go | 44 ++++ internal/domain/sampling/all.go | 19 ++ internal/domain/sampling/all_test.go | 61 +++++ internal/domain/sampling/contract.go | 56 +++++ internal/domain/sampling/random.go | 32 +++ internal/domain/sampling/random_test.go | 140 ++++++++++++ internal/domain/sampling/recency.go | 36 +++ internal/domain/sampling/recency_test.go | 64 ++++++ internal/domain/sampling/sampling_test.go | 48 ++++ internal/domain/sampling/staleness.go | 20 ++ internal/domain/sampling/staleness_test.go | 64 ++++++ .../infrastructure/embedding/embedding.go | 151 +++++++++++++ .../embedding/embedding_test.go | 211 ++++++++++++++++++ 18 files changed, 1186 insertions(+), 21 deletions(-) create mode 100644 docs/prds/curator-sampler-wave1.md create mode 100644 internal/domain/embedding/contract.go create mode 100644 internal/domain/sampling/all.go create mode 100644 internal/domain/sampling/all_test.go create mode 100644 internal/domain/sampling/contract.go create mode 100644 internal/domain/sampling/random.go create mode 100644 internal/domain/sampling/random_test.go create mode 100644 internal/domain/sampling/recency.go create mode 100644 internal/domain/sampling/recency_test.go create mode 100644 internal/domain/sampling/sampling_test.go create mode 100644 internal/domain/sampling/staleness.go create mode 100644 internal/domain/sampling/staleness_test.go create mode 100644 internal/infrastructure/embedding/embedding.go create mode 100644 internal/infrastructure/embedding/embedding_test.go diff --git a/CLAUDE.md b/CLAUDE.md index 14af5fcb2..6dfe03733 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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 diff --git a/config.example.toml b/config.example.toml index 6292cb3aa..7f01cd4aa 100644 --- a/config.example.toml +++ b/config.example.toml @@ -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" diff --git a/docs/architecture/plugins-and-extensions.md b/docs/architecture/plugins-and-extensions.md index b6696c3b9..8bdc4096d 100644 --- a/docs/architecture/plugins-and-extensions.md +++ b/docs/architecture/plugins-and-extensions.md @@ -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. diff --git a/docs/prds/curator-sampler-wave1.md b/docs/prds/curator-sampler-wave1.md new file mode 100644 index 000000000..335d875c0 --- /dev/null +++ b/docs/prds/curator-sampler-wave1.md @@ -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 diff --git a/internal/app/archied/bootstrap.go b/internal/app/archied/bootstrap.go index 06fda3d89..448f76ed0 100644 --- a/internal/app/archied/bootstrap.go +++ b/internal/app/archied/bootstrap.go @@ -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()) diff --git a/internal/domain/embedding/contract.go b/internal/domain/embedding/contract.go new file mode 100644 index 000000000..35e145c42 --- /dev/null +++ b/internal/domain/embedding/contract.go @@ -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) +} diff --git a/internal/domain/sampling/all.go b/internal/domain/sampling/all.go new file mode 100644 index 000000000..be23f7f41 --- /dev/null +++ b/internal/domain/sampling/all.go @@ -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 +} diff --git a/internal/domain/sampling/all_test.go b/internal/domain/sampling/all_test.go new file mode 100644 index 000000000..0cc319d41 --- /dev/null +++ b/internal/domain/sampling/all_test.go @@ -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()) +} diff --git a/internal/domain/sampling/contract.go b/internal/domain/sampling/contract.go new file mode 100644 index 000000000..9a8030f85 --- /dev/null +++ b/internal/domain/sampling/contract.go @@ -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 +} diff --git a/internal/domain/sampling/random.go b/internal/domain/sampling/random.go new file mode 100644 index 000000000..5ba3f8ecb --- /dev/null +++ b/internal/domain/sampling/random.go @@ -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 +} diff --git a/internal/domain/sampling/random_test.go b/internal/domain/sampling/random_test.go new file mode 100644 index 000000000..d074e78a1 --- /dev/null +++ b/internal/domain/sampling/random_test.go @@ -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()) +} diff --git a/internal/domain/sampling/recency.go b/internal/domain/sampling/recency.go new file mode 100644 index 000000000..ef803489d --- /dev/null +++ b/internal/domain/sampling/recency.go @@ -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 +} diff --git a/internal/domain/sampling/recency_test.go b/internal/domain/sampling/recency_test.go new file mode 100644 index 000000000..21d093173 --- /dev/null +++ b/internal/domain/sampling/recency_test.go @@ -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()) +} diff --git a/internal/domain/sampling/sampling_test.go b/internal/domain/sampling/sampling_test.go new file mode 100644 index 000000000..d51962f41 --- /dev/null +++ b/internal/domain/sampling/sampling_test.go @@ -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]) + } + } +} diff --git a/internal/domain/sampling/staleness.go b/internal/domain/sampling/staleness.go new file mode 100644 index 000000000..67eb0c18f --- /dev/null +++ b/internal/domain/sampling/staleness.go @@ -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 +} diff --git a/internal/domain/sampling/staleness_test.go b/internal/domain/sampling/staleness_test.go new file mode 100644 index 000000000..3ea0d682f --- /dev/null +++ b/internal/domain/sampling/staleness_test.go @@ -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()) +} diff --git a/internal/infrastructure/embedding/embedding.go b/internal/infrastructure/embedding/embedding.go new file mode 100644 index 000000000..e10f3ad62 --- /dev/null +++ b/internal/infrastructure/embedding/embedding.go @@ -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 +} diff --git a/internal/infrastructure/embedding/embedding_test.go b/internal/infrastructure/embedding/embedding_test.go new file mode 100644 index 000000000..9146d4113 --- /dev/null +++ b/internal/infrastructure/embedding/embedding_test.go @@ -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 } +}