Documentation
¶
Overview ¶
Package fusion implements the REQ-RET-106 fusion A/B decision-gate harness.
It compares the production position-only Reciprocal Rank Fusion (RRF, k=60 — the exact semantics mirrored from internal/retrieval/retrieval.go fuseInputs) against a calibrated convex combination of min-max normalized lexical and vector scores (arXiv 2210.11934) on a deterministic, fully offline synthetic corpus. The harness is READ-ONLY over retrieval inputs: it never mutates production fusion, never touches the network, and its recommendation field is advisory. REQ-RET-002 (score-as-rank) stays untouched here; any future production fusion flip requires an explicit decision-gate approval.
Index ¶
Constants ¶
const ( // SchemaVersion identifies the report contract of this harness. SchemaVersion = "1" // DefaultRRFConstant mirrors the production RRF constant (k=60). DefaultRRFConstant = 60 // DefaultTopK is the evaluation cutoff for recall/precision/nDCG. DefaultTopK = 10 // DefaultSeed makes the corpus fully reproducible across runs. DefaultSeed = 0xF00D2026 // DefaultTuningFraction of queries are reserved as the held-out split // used to calibrate the convex-combination weight. The remainder is the // evaluation split both strategies are scored on. DefaultTuningFraction = 0.5 // DefaultAlphaGridStep is the calibration grid resolution in [0,1]. DefaultAlphaGridStep = 0.05 // RecommendationKeepRRF means the position-only production fusion stays. RecommendationKeepRRF = "keep-rrf-k60" // RecommendationConvex means the calibrated convex combination measured // strictly better on the evaluation split (advisory; still requires a // decision-gate approval before any production change). RecommendationConvex = "convex-combination" )
const ContractNote = "Advisory report only: production fusion remains position-only RRF k=60 " +
"with the REQ-RET-002 score-as-rank contract intact. Adopting the convex combination " +
"requires an explicit decision-gate approval and a reviewed contract change."
ContractNote is embedded in every report to make the REQ-RET-106 / REQ-RET-002 boundary explicit in the decision-gate artifact.
Variables ¶
This section is empty.
Functions ¶
func CalibrateAlpha ¶
CalibrateAlpha grid-searches the convex weight maximizing mean nDCG@k on the tuning split. Ties resolve deterministically: prefer the alpha closest to 0.5 (least committed to one signal), then the lower alpha.
Types ¶
type Candidate ¶
Candidate is one retrieval candidate with its raw per-signal scores. The pre-ranked order of Lexical/Vector lists is what position-only RRF sees; the raw scores are what the convex combination sees.
func ConvexFuse ¶
ConvexFuse computes alpha*normalizedLexical + (1-alpha)*normalizedVector for every candidate of the union, sorted score DESC with ID DESC tie-break. alpha=1 is pure lexical, alpha=0 is pure vector.
func RRFFuse ¶
RRFFuse mirrors the production position-only RRF: for each signal list, rank r (0-based) contributes weight/(k+r+1); credits accumulate per ID; results sort score DESC with ID DESC as the deterministic tie-break. Weight is fixed at 1.0 per signal to match the default production weights.
type Config ¶
type Config struct {
CorpusSize int
QueryCount int
TopK int
Seed int64
TuningFraction float64
AlphaGridStep float64
}
Config parameterizes the harness. Zero-value fields resolve to defaults.
type Options ¶
type Options struct {
RRFConstant int
}
Options tunes RRFFuse. Zero RRFConstant falls back to DefaultRRFConstant.
type QueryCase ¶
type QueryCase struct {
ID string
Lexical []Candidate
Vector []Candidate
Relevant map[string]float64
}
QueryCase is one evaluation query: candidate lists plus graded relevance (0 = not relevant) for nDCG, and binary relevance derived for recall/MRR.
func GenerateCorpus ¶
GenerateCorpus deterministically builds a synthetic offline corpus with planted relevance and controlled lexical/vector disagreement so the A/B has signal: a third of the queries is lexical-strong, a third vector-strong, and a third balanced.
type Report ¶
type Report struct {
SchemaVersion string `json:"schema_version"`
Config Config `json:"config"`
TuningQueries int `json:"tuning_queries"`
EvalQueries int `json:"eval_queries"`
CalibratedAlpha float64 `json:"calibrated_alpha"`
Strategies []StrategyReport `json:"strategies"`
Recommendation string `json:"recommendation"`
Rationale string `json:"rationale"`
ContractNote string `json:"contract_note"`
}
Report is the decision-gate artifact.
type StrategyReport ¶
type StrategyReport struct {
Name string `json:"name"`
RecallAtK float64 `json:"recall_at_k"`
PrecisionAtK float64 `json:"precision_at_k"`
NDCGAtK float64 `json:"ndcg_at_k"`
MRR float64 `json:"mrr"`
LatencyNSPerQuery float64 `json:"latency_ns_per_query"`
}
StrategyReport holds the per-strategy decision-gate metrics. Latency is the median wall-clock fusion time per query over the evaluation split; it is informational ONLY and is excluded from the recommendation decision so the recommendation field is stable across runs on identical inputs.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
fusion
command
Command fusion runs the REQ-RET-106 fusion A/B decision-gate harness and prints the report (human-readable summary plus optional JSON artifact).
|
Command fusion runs the REQ-RET-106 fusion A/B decision-gate harness and prints the report (human-readable summary plus optional JSON artifact). |