feat: lazy-init + threshold calibration for semantic router

Lazy initialization:
- SemanticRouter.TryInitialize() auto-initializes when embedding provider
  loads after startup (e.g., CLI pushes API key via POST /v1/settings/providers)
- Router always passed to ServerDeps (never nil) — legacy classifier handles
  traffic until centroids are computed
- IsInitialized() exposed in admin stats endpoint

Threshold calibration:
- POST /admin/routing/threshold {"route":"...", "threshold":0.62} hot-updates
  per-route similarity thresholds without restart
- Tier 2 logs all route similarity scores at Debug level for observability
- X-Route-Scores header emits top-3 scores on every embedding-routed response
- RoutingDecision.Scores field carries per-route scores through the pipeline

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: TresPies-source

main.go

@@ -337,27 +337,20 @@ func main() {
 
 	// Initialization embeds all route utterances — this requires a live provider
 	// with embedding support. If the provider isn't loaded yet (keys pushed later
-	// by CLI), initialization is deferred and the legacy classifier handles traffic
-	// until the admin triggers re-init or the provider becomes available.
+	// by CLI), initialization is deferred and TryInitialize will be called
+	// automatically when a provider key is registered via POST /v1/settings/providers.
 	if _, err := pluginManager.GetProvider(embeddingProvider); err == nil {
 		initCtx, initCancel := context.WithTimeout(context.Background(), 60*time.Second)
-		if err := semanticRouter.Initialize(initCtx); err != nil {
-			slog.Warn("semantic router initialization failed — falling back to legacy classifier",
-				"error", err,
-				"embedding_provider", embeddingProvider)
-			semanticRouter = nil
-		} else {
+		if ok, err := semanticRouter.TryInitialize(initCtx); err != nil {
+			slog.Warn("semantic router initialization failed — will retry when provider loads",
+				"error", err, "embedding_provider", embeddingProvider)
+		} else if ok {
 			slog.Info("semantic router initialized — embedding-based routing active")
 		}
 		initCancel()
 	} else {
-		slog.Info("semantic router deferred — embedding provider not yet loaded, using legacy classifier",
+		slog.Info("semantic router deferred — embedding provider not yet loaded, will auto-init when available",
 			"provider", embeddingProvider)
-		// Keep semanticRouter non-nil but uninitialized. The chat handler's
-		// fallback to the legacy classifier handles this safely because
-		// tier2Embedding will fail and cascade through to tier3 or degrade.
-		// Set to nil to use legacy classifier cleanly until provider is available.
-		semanticRouter = nil
 	}
 
 	// ─── Initialize Orchestration ────────────────────────────────────

server/agent/intent_types.go

@@ -67,5 +67,6 @@ type RoutingDecision struct {
 	Confidence        float64
 	Category          IntentCategory
 	Reasoning         []string
-	SpecialistAgentID string // bridges category → specialist agent
+	SpecialistAgentID string            // bridges category → specialist agent
+	Scores            map[string]float64 `json:"scores,omitempty"` // per-route similarity scores from Tier 2; empty for Tier 1/3 decisions
 }

server/agent/semantic_router.go

@@ -75,12 +75,15 @@ func (b *ProviderEmbeddingBackend) Embed(ctx context.Context, text string) ([]fl
 //
 // Thread-safety: route definitions are protected by a RWMutex; the routing
 // mode is stored as an atomic int32 so reads and writes are lock-free.
+// initialized is an atomic bool so IsInitialized and TryInitialize are safe
+// to call from any goroutine.
 type SemanticRouter struct {
-	mu        sync.RWMutex
-	routes    []RouteDefinition
-	mode      atomic.Int32 // stores RoutingMode
-	embedder  EmbeddingBackend
-	llmRouter LLMRouter
+	mu          sync.RWMutex
+	routes      []RouteDefinition
+	mode        atomic.Int32 // stores RoutingMode
+	initialized atomic.Bool
+	embedder    EmbeddingBackend
+	llmRouter   LLMRouter
 }
 
 // NewSemanticRouter creates a SemanticRouter with the given EmbeddingBackend
@@ -125,6 +128,21 @@ func (sr *SemanticRouter) SetMode(mode RoutingMode) {
 	slog.Info("semantic router: mode changed", "mode", mode.String())
 }
 
+// SetRouteThreshold updates the similarity threshold for a named route.
+// Returns an error if no route with that name exists.
+func (sr *SemanticRouter) SetRouteThreshold(name string, threshold float64) error {
+	sr.mu.Lock()
+	defer sr.mu.Unlock()
+	for i := range sr.routes {
+		if sr.routes[i].Name == name {
+			sr.routes[i].Threshold = threshold
+			slog.Info("semantic router: threshold updated", "route", name, "threshold", threshold)
+			return nil
+		}
+	}
+	return fmt.Errorf("semantic router: route %q not found", name)
+}
+
 // Initialize computes centroids for all registered routes by embedding each
 // utterance and averaging the resulting vectors. This must be called before
 // Route; it may also be called again after AddRoute to update centroids.
@@ -150,9 +168,33 @@ func (sr *SemanticRouter) Initialize(ctx context.Context) error {
 	}
 
 	slog.Info("semantic router: initialization complete", "routes", len(sr.routes))
+	sr.initialized.Store(true)
 	return nil
 }
 
+// IsInitialized reports whether centroids have been successfully computed.
+// Safe to call from any goroutine.
+func (sr *SemanticRouter) IsInitialized() bool {
+	return sr.initialized.Load()
+}
+
+// TryInitialize attempts to initialize the router if it has not been
+// initialized yet. Returns (true, nil) when initialization succeeds,
+// (false, nil) when the router was already initialized, and (false, err)
+// when initialization fails. Thread-safe: concurrent calls are safe because
+// Initialize holds the write lock, but only one caller will observe the
+// centroids being computed — subsequent callers after the first success
+// will return (false, nil).
+func (sr *SemanticRouter) TryInitialize(ctx context.Context) (bool, error) {
+	if sr.initialized.Load() {
+		return false, nil
+	}
+	if err := sr.Initialize(ctx); err != nil {
+		return false, err
+	}
+	return true, nil
+}
+
 // Route classifies query and returns a RoutingDecision. The pipeline executed
 // depends on the active RoutingMode:
 //   - RoutingModeCascade: Tier1 → Tier2 → Tier3
@@ -269,13 +311,15 @@ func (sr *SemanticRouter) tier2Embedding(ctx context.Context, query string) (Rou
 		return RoutingDecision{}, false, fmt.Errorf("tier2: embed query: %w", err)
 	}
 
+	allScores := make(map[string]float64, len(routes))
 	var best RouteMatch
 	found := false
 	for _, route := range routes {
 		if len(route.Centroid) == 0 {
 			continue
 		}
 		sim := cosineSimilarityLocal(vec, route.Centroid)
+		allScores[route.Name] = sim
 		if !found || sim > best.Similarity {
 			best = RouteMatch{Route: route, Similarity: sim}
 			found = true
@@ -291,8 +335,15 @@ func (sr *SemanticRouter) tier2Embedding(ctx context.Context, query string) (Rou
 		threshold = best.Route.Threshold
 	}
 
+	slog.Debug("semantic router: tier2 scores",
+		"query_len", len(query),
+		"best_route", best.Route.Name,
+		"best_similarity", best.Similarity,
+		"threshold", threshold,
+		"matched", best.Similarity >= threshold,
+	)
+
 	if best.Similarity < threshold {
-		slog.Debug("semantic router: tier2 no match", "best_route", best.Route.Name, "similarity", best.Similarity, "threshold", threshold)
 		return RoutingDecision{}, false, nil
 	}
 
@@ -303,6 +354,7 @@ func (sr *SemanticRouter) tier2Embedding(ctx context.Context, query string) (Rou
 		Fallback:   best.Route.Fallback,
 		Confidence: best.Similarity,
 		Category:   category,
+		Scores:     allScores,
 		Reasoning: []string{
 			fmt.Sprintf("tier2: embedding match route=%s similarity=%.4f threshold=%.4f",
 				best.Route.Name, best.Similarity, threshold),

server/handle_admin_routing.go

@@ -154,6 +154,62 @@ func (s *Server) handleAdminSetRoutingMode(c *gin.Context) {
 	})
 }
 
+// handleAdminSetRouteThreshold updates the similarity threshold for a named route.
+//
+// POST /admin/routing/threshold
+//
+// Request body:
+//
+//	{"route": "deep_inference", "threshold": 0.62}
+//
+// Response 200 — updated route summary list.
+// Response 400 — missing fields, unknown route, or threshold out of [0.0, 1.0].
+// Response 503 — semantic router not initialised.
+func (s *Server) handleAdminSetRouteThreshold(c *gin.Context) {
+	if s.semanticRouter == nil {
+		slog.Warn("handleAdminSetRouteThreshold: semanticRouter not initialised")
+		c.JSON(http.StatusServiceUnavailable, gin.H{
+			"error": "semantic router not initialised",
+		})
+		return
+	}
+
+	var req struct {
+		Route     string  `json:"route"     binding:"required"`
+		Threshold float64 `json:"threshold" binding:"required"`
+	}
+	if err := c.ShouldBindJSON(&req); err != nil {
+		slog.Warn("handleAdminSetRouteThreshold: invalid request body", "error", err)
+		c.JSON(http.StatusBadRequest, gin.H{
+			"error": "request body must contain 'route' and 'threshold' fields",
+		})
+		return
+	}
+
+	if req.Threshold < 0.0 || req.Threshold > 1.0 {
+		c.JSON(http.StatusBadRequest, gin.H{
+			"error": "threshold must be in [0.0, 1.0]",
+		})
+		return
+	}
+
+	if err := s.semanticRouter.SetRouteThreshold(req.Route, req.Threshold); err != nil {
+		slog.Warn("handleAdminSetRouteThreshold: route not found", "route", req.Route)
+		c.JSON(http.StatusBadRequest, gin.H{
+			"error": err.Error(),
+		})
+		return
+	}
+
+	slog.Info("admin: route threshold updated", "route", req.Route, "threshold", req.Threshold)
+	summaries := buildRouteSummaries(s.semanticRouter.GetRoutes())
+	c.JSON(http.StatusOK, gin.H{
+		"route":     req.Route,
+		"threshold": req.Threshold,
+		"routes":    summaries,
+	})
+}
+
 // handleAdminRoutingStats returns routing statistics and a route inventory.
 //
 // GET /admin/routing/stats
@@ -189,6 +245,7 @@ func (s *Server) handleAdminRoutingStats(c *gin.Context) {
 	c.JSON(http.StatusOK, gin.H{
 		"current_mode": currentMode.String(),
 		"route_count":  len(routes),
+		"initialized":  s.semanticRouter.IsInitialized(),
 		"stats":        nil,
 	})
 }

server/handle_gateway.go

@@ -1092,6 +1092,20 @@ func (s *Server) handleSetProviderKey(c *gin.Context) {
 		if s.pluginManager != nil {
 			s.hotRegisterProvider(req.Provider, req.Key)
 		}
+
+		// If the semantic router exists but hasn't been initialized yet,
+		// attempt lazy initialization now that a new provider is available.
+		if s.semanticRouter != nil && !s.semanticRouter.IsInitialized() {
+			go func() {
+				ctx, cancel := context.WithTimeout(context.Background(), 60*time.Second)
+				defer cancel()
+				if ok, err := s.semanticRouter.TryInitialize(ctx); err != nil {
+					slog.Warn("semantic router auto-init failed", "error", err)
+				} else if ok {
+					slog.Info("semantic router auto-initialized after provider registration")
+				}
+			}()
+		}
 	}
 
 	// Persist

server/handlers/chat.go

@@ -7,6 +7,7 @@ import (
 	"io"
 	"log/slog"
 	"net/http"
+	"sort"
 	"strings"
 	"time"
 
@@ -192,6 +193,11 @@ func (h *ChatHandler) Chat(c *gin.Context) {
 		"reasoning", decision.Reasoning,
 	)
 
+	// Emit per-route similarity scores as a debug header when Tier 2 was used.
+	if len(decision.Scores) > 0 {
+		c.Header("X-Route-Scores", formatRouteScores(decision.Scores))
+	}
+
 	// Route based on decision
 	switch decision.Handler {
 	case "template":
@@ -731,3 +737,28 @@ func (h *ChatHandler) lookupUserTier(ctx context.Context, userID string) string
 
 	return ""
 }
+
+// formatRouteScores produces a compact "route=score" string for the top-3
+// routes by descending similarity, e.g. "fast_inference=0.82,direct_response=0.71,deep_inference=0.65".
+// Intended for the X-Route-Scores debug header.
+func formatRouteScores(scores map[string]float64) string {
+	type routeScore struct {
+		name  string
+		score float64
+	}
+	pairs := make([]routeScore, 0, len(scores))
+	for name, score := range scores {
+		pairs = append(pairs, routeScore{name, score})
+	}
+	sort.Slice(pairs, func(i, j int) bool {
+		return pairs[i].score > pairs[j].score
+	})
+	if len(pairs) > 3 {
+		pairs = pairs[:3]
+	}
+	parts := make([]string, len(pairs))
+	for i, p := range pairs {
+		parts[i] = fmt.Sprintf("%s=%.4f", p.name, p.score)
+	}
+	return strings.Join(parts, ",")
+}

server/router.go

@@ -249,6 +249,7 @@ func (s *Server) setupRoutes() {
 		admin.GET("/routing/mode", s.handleAdminRoutingMode)
 		admin.POST("/routing/mode", s.handleAdminSetRoutingMode)
 		admin.GET("/routing/stats", s.handleAdminRoutingStats)
+		admin.POST("/routing/threshold", s.handleAdminSetRouteThreshold)
 
 		// User management (Wave 1)
 		admin.GET("/users", s.handleAdminListUsers)