feat(config): retrieval.rerank block + VLE_RETRIEVAL_RERANK_* env overrides

Adds ReRankBlock under RetrievalConfig with Enabled / Model /
MaxContentChars (default 2000) / TopK (default 0 = keep all) fields,
plus matching VLE_RETRIEVAL_RERANK_ENABLED, _MODEL,
_MAX_CONTENT_CHARS, and _TOP_K env overrides following the same shape
as the existing planning + agentic + answer_span env handling.

Re-rank is opt-in: defaults are Enabled=false / TopK=0 so existing
deployments behave identically. Per-request `enable_rerank` body field
(wired in the next commit) overrides this block when set.

Validate rejects negative MaxContentChars and TopK so a stray env or
YAML typo can't silently flip the model into "send no content" mode.
Zero is valid for both: TopK=0 means keep all candidates,
MaxContentChars=0 falls through to the ReRanker's compiled default.

Four new tests: default values, env override happy path, env disable
of a YAML-set true, env override rejects bad numeric values, and
validation of negative inputs.

Author: hallelx2

pkg/config/config.go

@@ -204,6 +204,44 @@ type RetrievalConfig struct {
 	AnswerSpan  AnswerSpanBlock  `yaml:"answer_span"`
 	Answer      AnswerBlock      `yaml:"answer"`
 	Planning    PlanningBlock    `yaml:"planning"`
+	ReRank      ReRankBlock      `yaml:"rerank"`
+}
+
+// ReRankBlock configures the Phase 2.3 content-aware re-rank pass.
+//
+// When enabled, every /v1/query and /v1/answer request that returns
+// candidate sections runs one extra LLM call: the candidates' first
+// MaxContentChars chars of content are fed to the model with the
+// query, and the model returns a per-section relevance score
+// (0-100). Sections are reordered by score; if TopK > 0 the response
+// is truncated to the top K.
+//
+// The pass is opt-in. Per-request `enable_rerank` body field
+// overrides this block.
+//
+// Re-rank failures never drop sections — at worst the original
+// strategy order is preserved and the request returns unchanged from
+// the no-rerank path. See pkg/retrieval/rerank.go for the exact
+// degradation contract.
+type ReRankBlock struct {
+	// Enabled toggles re-rank at the server level. Default: false.
+	Enabled bool `yaml:"enabled"`
+
+	// Model overrides the re-rank LLM model. Empty means use the
+	// request's model (which itself falls back to the engine default).
+	// Point this at a small/fast model — the re-rank prompt is short
+	// and shouldn't burn the flagship model's budget.
+	Model string `yaml:"model"`
+
+	// MaxContentChars caps how many characters of each candidate's
+	// content are sent to the model. Default: 2000.
+	MaxContentChars int `yaml:"max_content_chars"`
+
+	// TopK caps the number of sections kept after re-ranking. 0 means
+	// keep all candidates (re-rank only reorders). Useful when the
+	// strategy is configured to return a wide candidate list and the
+	// re-rank pass picks the focused top-k for synthesis.
+	TopK int `yaml:"top_k"`
 }
 
 // PlanningBlock configures Phase 2.1 query planning + Phase 2.2 multi-hop
@@ -368,6 +406,11 @@ func Default() Config {
 				CacheSize: 128,
 				Decompose: true,
 			},
+			ReRank: ReRankBlock{
+				Enabled:         false,
+				MaxContentChars: 2000,
+				TopK:            0,
+			},
 		},
 		Ingest: IngestConfig{
 			GlobalLLMConcurrency: 12,
@@ -556,6 +599,27 @@ func applyEnvOverrides(c *Config) {
 			c.Retrieval.Planning.Decompose = false
 		}
 	}
+	if v := os.Getenv("VLE_RETRIEVAL_RERANK_ENABLED"); v != "" {
+		switch strings.ToLower(strings.TrimSpace(v)) {
+		case "1", "true", "yes", "on":
+			c.Retrieval.ReRank.Enabled = true
+		case "0", "false", "no", "off":
+			c.Retrieval.ReRank.Enabled = false
+		}
+	}
+	if v := os.Getenv("VLE_RETRIEVAL_RERANK_MODEL"); v != "" {
+		c.Retrieval.ReRank.Model = v
+	}
+	if v := os.Getenv("VLE_RETRIEVAL_RERANK_MAX_CONTENT_CHARS"); v != "" {
+		if n, err := strconv.Atoi(v); err == nil && n > 0 {
+			c.Retrieval.ReRank.MaxContentChars = n
+		}
+	}
+	if v := os.Getenv("VLE_RETRIEVAL_RERANK_TOP_K"); v != "" {
+		if n, err := strconv.Atoi(v); err == nil && n >= 0 {
+			c.Retrieval.ReRank.TopK = n
+		}
+	}
 }
 
 // Validate checks that required fields for the selected drivers are set.
@@ -642,5 +706,12 @@ func (c Config) Validate() error {
 		return fmt.Errorf("retrieval.planning.cache_size must be >= 0, got %d", c.Retrieval.Planning.CacheSize)
 	}
 
+	if c.Retrieval.ReRank.MaxContentChars < 0 {
+		return fmt.Errorf("retrieval.rerank.max_content_chars must be >= 0, got %d", c.Retrieval.ReRank.MaxContentChars)
+	}
+	if c.Retrieval.ReRank.TopK < 0 {
+		return fmt.Errorf("retrieval.rerank.top_k must be >= 0, got %d", c.Retrieval.ReRank.TopK)
+	}
+
 	return nil
 }

pkg/config/config_test.go

@@ -46,11 +46,123 @@ func TestDefaultValues(t *testing.T) {
 	if !cfg.Retrieval.Planning.Decompose {
 		t.Error("retrieval.planning.decompose should default to true (when planning is enabled)")
 	}
+	if cfg.Retrieval.ReRank.Enabled {
+		t.Error("retrieval.rerank.enabled should default to false (opt-in)")
+	}
+	if cfg.Retrieval.ReRank.MaxContentChars != 2000 {
+		t.Errorf("retrieval.rerank.max_content_chars = %d, want 2000", cfg.Retrieval.ReRank.MaxContentChars)
+	}
+	if cfg.Retrieval.ReRank.TopK != 0 {
+		t.Errorf("retrieval.rerank.top_k = %d, want 0 (keep all)", cfg.Retrieval.ReRank.TopK)
+	}
 	if cfg.Log.Level != "info" {
 		t.Errorf("log.level = %q, want info", cfg.Log.Level)
 	}
 }
 
+func TestReRankEnvOverride(t *testing.T) {
+	// Not parallel — mutates env. Restore on exit.
+	prevEnabled := os.Getenv("VLE_RETRIEVAL_RERANK_ENABLED")
+	prevModel := os.Getenv("VLE_RETRIEVAL_RERANK_MODEL")
+	prevMax := os.Getenv("VLE_RETRIEVAL_RERANK_MAX_CONTENT_CHARS")
+	prevTopK := os.Getenv("VLE_RETRIEVAL_RERANK_TOP_K")
+	defer func() {
+		os.Setenv("VLE_RETRIEVAL_RERANK_ENABLED", prevEnabled)
+		os.Setenv("VLE_RETRIEVAL_RERANK_MODEL", prevModel)
+		os.Setenv("VLE_RETRIEVAL_RERANK_MAX_CONTENT_CHARS", prevMax)
+		os.Setenv("VLE_RETRIEVAL_RERANK_TOP_K", prevTopK)
+	}()
+
+	os.Setenv("VLE_RETRIEVAL_RERANK_ENABLED", "true")
+	os.Setenv("VLE_RETRIEVAL_RERANK_MODEL", "gemini-2.0-flash")
+	os.Setenv("VLE_RETRIEVAL_RERANK_MAX_CONTENT_CHARS", "1500")
+	os.Setenv("VLE_RETRIEVAL_RERANK_TOP_K", "3")
+
+	cfg := Default()
+	applyEnvOverrides(&cfg)
+
+	if !cfg.Retrieval.ReRank.Enabled {
+		t.Error("VLE_RETRIEVAL_RERANK_ENABLED=true should enable rerank")
+	}
+	if cfg.Retrieval.ReRank.Model != "gemini-2.0-flash" {
+		t.Errorf("rerank model = %q, want gemini-2.0-flash", cfg.Retrieval.ReRank.Model)
+	}
+	if cfg.Retrieval.ReRank.MaxContentChars != 1500 {
+		t.Errorf("rerank max_content_chars = %d, want 1500", cfg.Retrieval.ReRank.MaxContentChars)
+	}
+	if cfg.Retrieval.ReRank.TopK != 3 {
+		t.Errorf("rerank top_k = %d, want 3", cfg.Retrieval.ReRank.TopK)
+	}
+}
+
+func TestReRankEnvOverrideDisable(t *testing.T) {
+	// Toggle off via env: start from a config that defaults to false,
+	// then set =false explicitly; verify the path executes (not just
+	// that the default value is preserved).
+	prev := os.Getenv("VLE_RETRIEVAL_RERANK_ENABLED")
+	defer os.Setenv("VLE_RETRIEVAL_RERANK_ENABLED", prev)
+
+	cfg := Default()
+	cfg.Retrieval.ReRank.Enabled = true // simulate a YAML-set true
+	os.Setenv("VLE_RETRIEVAL_RERANK_ENABLED", "false")
+	applyEnvOverrides(&cfg)
+	if cfg.Retrieval.ReRank.Enabled {
+		t.Error("VLE_RETRIEVAL_RERANK_ENABLED=false should disable rerank even when YAML set it true")
+	}
+}
+
+func TestReRankEnvOverrideRejectsBad(t *testing.T) {
+	// Garbage env values should be rejected, not silently zero the field.
+	prevMax := os.Getenv("VLE_RETRIEVAL_RERANK_MAX_CONTENT_CHARS")
+	prevTopK := os.Getenv("VLE_RETRIEVAL_RERANK_TOP_K")
+	defer func() {
+		os.Setenv("VLE_RETRIEVAL_RERANK_MAX_CONTENT_CHARS", prevMax)
+		os.Setenv("VLE_RETRIEVAL_RERANK_TOP_K", prevTopK)
+	}()
+
+	os.Setenv("VLE_RETRIEVAL_RERANK_MAX_CONTENT_CHARS", "not-a-number")
+	os.Setenv("VLE_RETRIEVAL_RERANK_TOP_K", "abc")
+
+	cfg := Default()
+	applyEnvOverrides(&cfg)
+	if cfg.Retrieval.ReRank.MaxContentChars != 2000 {
+		t.Errorf("bad max_content_chars env should preserve default, got %d", cfg.Retrieval.ReRank.MaxContentChars)
+	}
+	if cfg.Retrieval.ReRank.TopK != 0 {
+		t.Errorf("bad top_k env should preserve default, got %d", cfg.Retrieval.ReRank.TopK)
+	}
+}
+
+func TestValidateReRankNegatives(t *testing.T) {
+	t.Parallel()
+
+	// Negative max_content_chars rejected.
+	cfg := Default()
+	cfg.Database.URL = "postgres://localhost/test"
+	cfg.Retrieval.ReRank.MaxContentChars = -1
+	if err := cfg.Validate(); err == nil {
+		t.Error("negative max_content_chars should fail validation")
+	}
+
+	// Negative top_k rejected.
+	cfg2 := Default()
+	cfg2.Database.URL = "postgres://localhost/test"
+	cfg2.Retrieval.ReRank.TopK = -1
+	if err := cfg2.Validate(); err == nil {
+		t.Error("negative top_k should fail validation")
+	}
+
+	// Zero on both is valid (TopK=0 means "keep all", MaxContentChars=0
+	// means "use default").
+	cfg3 := Default()
+	cfg3.Database.URL = "postgres://localhost/test"
+	cfg3.Retrieval.ReRank.MaxContentChars = 0
+	cfg3.Retrieval.ReRank.TopK = 0
+	if err := cfg3.Validate(); err != nil {
+		t.Errorf("zero rerank values should pass validation: %v", err)
+	}
+}
+
 func TestPlanningEnvOverride(t *testing.T) {
 	// Not parallel — mutates env. Restore on exit.
 	prevEnabled := os.Getenv("VLE_RETRIEVAL_PLANNING_ENABLED")