Documentation
¶
Overview ¶
Package noisefloor turns a raw top-hit cosine similarity into an honest relevance signal, relative to the vault's noise floor N — the cosine an off-topic ("garbage") query gets to any note in the vault.
Why this exists: the prior confidence label was derived from the gap between the top two RRF scores, which measures candidate separation, not relevance. A 2026-05-30 probe across two real vaults (BGE-M3) proved it mislabels — garbage queries got "moderate", real ones got "weak". Absolute cosine against a noise floor separated real from garbage; a 2026-05-31 probe then showed an ABSOLUTE band doesn't transfer across vault tightness (a tight persona vault compresses everything near a high floor), so the bands are normalized by the vault's own dispersion.
z = (top_cosine − N) / σ — how many vault-σ the top hit clears N by floor_cos = min(N − 0.5σ, EmbedderDefaultN) — the no_match cutoff (cosine)
The FLOOR is the robust, probe-validated signal: a top cosine at/below it is indistinguishable from off-topic, and the recall hook reads no_match as "inject nothing" (silence beats noise). The min(…, EmbedderDefaultN) clamp lets a per-vault measurement only RELAX the floor, never raise it above the embedder ceiling — which is what keeps a tight vault's high measured N from silencing its own weak-but-real queries. The finer z-bands above the floor are PROVISIONAL (fit on n=2 vaults with near-equal σ) until the validation harness earns them on vaults of genuinely different tightness.
Index ¶
Constants ¶
const ( // SigmaFloor / SigmaCeil bound σ before it divides into z. Below the floor // (near-duplicate or tiny vault) z would explode and the no_match band would // collapse to a razor-thin cosine sliver. The ceiling only catches a // pathological/corrupt σ: clamping a legitimately-diverse vault's σ DOWN // inflates z toward over-confident labels (a false "strong" misleads more // than a false "weak"), so the ceiling sits well above the measured BGE-M3 σ // (~0.072) — typical vaults use their real σ; only a clearly-broken // measurement is capped. PROVISIONAL — the validation harness will set both // bounds from σ observed across vaults of genuinely different tightness. SigmaFloor = 0.03 SigmaCeil = 0.12 // MinCalibNotes / MinCalibPairs gate whether a measured snapshot is trusted // for the live label. noteToNoteStats yields (0,0,0) for <2 notes, and a // floor/σ estimated from a handful of notes is noise. Below either threshold // the ask path falls back to the embedder defaults rather than a poisoned // per-vault measurement. MinCalibNotes = 30 MinCalibPairs = 100 )
Calibration gating + the σ scale used by the z-relevance bands.
z = (top_cosine − N) / σ expresses relevance in units of the vault's own embedding-space spread (the note-to-note cosine stddev). σ must stay finite and in a sane range, and a σ/N pair measured from too small a vault is too noisy to trust — these constants enforce both.
const ( ConfidenceStrong = "strong" ConfidenceModerate = "moderate" ConfidenceWeak = "weak" // ConfidenceNoMatch — the top hit is at or below the noise floor, i.e. // indistinguishable from what an off-topic query scores. Callers treat // this as "nothing relevant" and inject silence. ConfidenceNoMatch = "no_match" )
Confidence tier strings. Kept identical to internal/query's tiers so the agent-facing label vocabulary is unchanged; only the derivation is honest now.
const ( // FloorSigmaMargin sets the no_match floor FloorSigmaMargin·σ below N, so a // genuinely weak match just under N degrades to "weak" rather than being // silenced (moving the floor from N to N−0.5σ recovered all 20 real probe // queries across both vaults). FloorSigmaMargin = 0.5 // Above-floor z-bands on z = (top_cosine − N)/σ. WeakMaxZ = 1.0 // (floor, 1.0] → weak ModerateMaxZ = 2.5 // (1.0, 2.5] → moderate; above → strong )
Relevance-band parameters.
PROVISIONAL (2026-05-31): the z-cutoffs are grounded in the probe (identity + research vaults, BGE-M3) but NOT yet validated on a large/diverse query set. Observed z: real queries 0.45–4.09, garbage −2.5–0.3 (the one overlap is a lexical "flat-pack"≈"context-pack" collision). The floor margin is the robust part; these inner cutoffs are what the validation harness must confirm.
const ProbeSetVersion = 1
ProbeSetVersion identifies the probe set above. Bump it when the strings change so stored calibrations measured against an old set are distinguishable.
const TightVaultMu = 0.58
TightVaultMu is the note-to-note cosine mean (μ) above which a vault is treated as "tight" — its notes are so self-similar that the embedder can't spread a correct top hit far above the noise floor, so genuine matches read "weak". On a tight vault, a weak label often means "best available correct match", not "nothing relevant"; the ask formatter surfaces that as a one-line hint so an agent doesn't misread persistent weak labels as a broken vault.
PROVISIONAL (n=2, 2026-05-31): the identity persona vault measured μ≈0.62 (tight), the research vault μ≈0.51 (not). The threshold splits those two; a third vault should confirm or move it. Kept deliberately above 0.51 and below 0.62 with margin on both sides.
Variables ¶
var DefaultProbes = []string{
"the weather forecast for next tuesday afternoon",
"how to bake chocolate chip cookies from scratch",
"final score of last night's football match",
"today's stock market closing prices",
"instructions for assembling flat-pack furniture",
"the lyrics to the happy birthday song",
"train timetable between two european cities",
"the chemical formula for ordinary table salt",
}
DefaultProbes is the fixed set of off-topic strings used to measure a vault's noise floor N: each is embedded and scored against every note, and N is the max cosine any of them reaches. They span diverse, mundane semantic regions no personal-knowledge vault should match, so their ceiling estimates "the cosine garbage gets" rather than a lucky single outlier. Fixed and versioned (changing the set changes N, so a recalibration is required) — never stored, never exported; only the resulting float matters.
Functions ¶
func ClampSigma ¶
ClampSigma constrains σ to [SigmaFloor, SigmaCeil]. A NaN or non-positive σ (cold-start, tiny vault, or a corrupt measurement) maps to SigmaFloor — never passed through, because a NaN σ would make z NaN and NaN fails every band comparison, silently falling through to the strongest label.
func DefaultDispersion ¶
DefaultDispersion returns the shipped note-to-note σ for an embedder of the given dimensionality, or 0.0 for unknown dims. The 0.0 is intentionally out-of-range: ClampSigma lifts it to SigmaFloor, so an unknown embedder gets a safe finite σ rather than a divide-by-zero.
func DefaultNoiseFloor ¶
DefaultNoiseFloor returns the shipped noise floor for an embedder of the given dimensionality, or 0.0 for unknown dims (the safe choice: no false "nothing relevant").
func IsTightVault ¶
IsTightVault reports whether a vault's measured note-to-note μ marks it as low-contrast. μ ≤ 0 (uncalibrated) is never tight.
func Relevance ¶
Relevance turns a raw top-hit cosine into an honest relevance score z and a tier label, given the vault's noise floor N, its note-to-note dispersion σ (pre-clamped — see ClampSigma), and the embedder's shipped default floor.
no_match is decided by a COSINE floor, not by z: floor_cos = min(N − FloorSigmaMargin·σ, embedderDefaultN). The min keeps a per-vault measurement from ever raising the floor above the probe-validated embedder ceiling. Above the floor, z = (top_cosine − N)/σ is banded at WeakMaxZ / ModerateMaxZ.
The NaN/Inf guard runs first: a degenerate σ (≈0) would make z non-finite, and a NaN z fails every band comparison below and would fall through to "strong" — labeling garbage as a confident match. ClampSigma upstream should prevent this; the guard is defence in depth.
Types ¶
This section is empty.
Source Files