Round-2 route-fit: top-N category cap + weak-match honesty

Adversarial round 2 (NOT-CONVERGED) found two systemic issues, both fixed:
- AFFINITY_FLOOR let all 17 categories keep weight, so ranks 5-17 silently
backfilled routes with off-vibe filler (same statues/churches bled into
10+ unrelated routes). Now cap to TOP_AFFINITY_CATEGORIES=6; the tail is
zeroed (sparse routes end honestly short, not confabulated). Applied in
embed + centrally in resolve_affinity (covers llm/keyword tiers too).
- min-max forces a top category to 1.00 even for weak/out-of-vocabulary
vibes, so "brutalist architecture" got churches confidently labelled "a
match for your vibe". Added raw-cosine confidence (WEAK_MATCH_SIMILARITY
=0.55; real vibes 0.66-0.85, brutalist 0.51, nonsense ~0.49); weak vibes
now get honest framing ("no strong match — here's my closest guess") and
drop the per-stop "a match for your vibe" tag.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

src/discoverroute/config.py

@@ -101,6 +101,16 @@ TRACE_REPO = os.environ.get(
 # Affinity floor: the least-matching category still keeps this much interest so
 # the route can explore a little; the best-matching category maps to 1.0.
 AFFINITY_FLOOR = 0.15
+# Only the top-N matched categories drive a vibe route; the rest are zeroed so
+# the long tail (ranks N+1..17) can't silently backfill stops with off-vibe
+# filler (the adversarial review found the same statues/churches bleeding into
+# 10+ unrelated routes via the floor). Sparse routes then end honestly short.
+TOP_AFFINITY_CATEGORIES = 6
+# A vibe whose BEST raw cosine to any category gloss is below this is a weak/
+# out-of-vocabulary match (measured: real vibes peak 0.66-0.85; "brutalist
+# architecture" 0.51, nonsense ~0.49). We still route, but the narration says so
+# honestly instead of claiming "a match for your vibe".
+WEAK_MATCH_SIMILARITY = 0.55
 # Below this cosine-similarity span across categories, a vibe is treated as
 # off-domain/neutral rather than amplified into false preferences. Measured
 # (bge-small, 16-vibe battery): gibberish "asdfqwer" spans 0.081; the LOWEST

src/discoverroute/interpret/affinity.py

@@ -15,6 +15,7 @@ from __future__ import annotations
 
 import functools
 
+from discoverroute import config
 from discoverroute.data import taxonomy
 
 
@@ -22,6 +23,16 @@ def _neutral() -> dict[str, float]:
     return {c: 1.0 for c in taxonomy.CATEGORIES}
 
 
+def _cap_top_n(aff: dict[str, float]) -> dict[str, float]:
+    """Zero all but the top-N categories so the long tail can't backfill routes
+    with off-vibe filler. (Embed self-caps; this also covers the LLM/keyword
+    tiers so the guarantee holds regardless of which one ran.)"""
+    if not aff:
+        return aff
+    keep = set(sorted(aff, key=aff.get, reverse=True)[: config.TOP_AFFINITY_CATEGORIES])
+    return {c: (v if c in keep else 0.0) for c, v in aff.items()}
+
+
 @functools.lru_cache(maxsize=256)
 def resolve_affinity(vibe: str) -> tuple[dict[str, float], str]:
     """Return ``(affinity, source)`` where source ∈ {llm, embed, keyword, neutral}."""
@@ -33,9 +44,9 @@ def resolve_affinity(vibe: str) -> tuple[dict[str, float], str]:
     from discoverroute.interpret import llm_vibe
     result = llm_vibe.extract(vibe)
     if result:
-        return result["affinity"], "llm"
+        return _cap_top_n(result["affinity"]), "llm"
 
-    # tier 2 — sentence embeddings (CPU)
+    # tier 2 — sentence embeddings (CPU); embed.vibe_to_affinity self-caps
     try:
         from discoverroute.interpret import embed
         return embed.vibe_to_affinity(vibe), "embed"
@@ -46,7 +57,7 @@ def resolve_affinity(vibe: str) -> tuple[dict[str, float], str]:
     from discoverroute.interpret import keywords
     kw = keywords.keyword_affinity(vibe)
     if kw:
-        return kw, "keyword"
+        return _cap_top_n(kw), "keyword"
 
     return _neutral(), "neutral"
 

src/discoverroute/interpret/embed.py

@@ -82,4 +82,21 @@ def vibe_to_affinity(vibe: str) -> dict[str, float]:
     if span < config.MIN_AFFINITY_SPAN:
         return {c: 1.0 for c in cats}
     floor = config.AFFINITY_FLOOR
-    return {c: floor + (1.0 - floor) * (float(s) - lo) / span for c, s in zip(cats, sims)}
+    aff = {c: floor + (1.0 - floor) * (float(s) - lo) / span for c, s in zip(cats, sims)}
+    # Keep only the top-N categories; zero the long tail so off-vibe categories
+    # can't backfill route slots once on-vibe candidates run out.
+    keep = set(sorted(aff, key=aff.get, reverse=True)[: config.TOP_AFFINITY_CATEGORIES])
+    return {c: (v if c in keep else 0.0) for c, v in aff.items()}
+
+
+@functools.lru_cache(maxsize=256)
+def raw_top_similarity(vibe: str) -> float:
+    """Best raw cosine of the vibe to any category gloss — a match-confidence
+    signal (independent of the min-max rescale, which always forces a 1.0)."""
+    vibe = (vibe or "").strip()
+    if not vibe:
+        return 0.0
+    _, gloss_emb = _gloss_matrix()
+    _, encode = _encoder()
+    q = encode([config.EMBED_QUERY_INSTRUCTION + vibe])[0]
+    return float((gloss_emb @ q).max())

src/discoverroute/interpret/vibe.py

@@ -37,6 +37,8 @@ class Interpretation:
     budget_hint: float | None      # suggested budget, or None if not implied
     explanation: str               # human-readable, inspectable
     top_categories: list[str] = field(default_factory=list)
+    confidence: float = 1.0        # best raw cosine to a category gloss
+    weak: bool = False             # True => out-of-vocabulary / weak match
 
 
 def _contains(text: str, cues) -> bool:
@@ -68,11 +70,19 @@ def interpret(vibe: str, adventurousness: float = config.DEFAULT_ADVENTUROUSNESS
         budget_hint = 0.2
 
     top = sorted(affinity, key=affinity.get, reverse=True)[:4]
-    explanation = _explain(vibe, top, affinity, posture, budget_hint)
-    return Interpretation(affinity, weights, posture, budget_hint, explanation, top)
-
-
-def _explain(vibe, top, affinity, posture, budget_hint) -> str:
+    # Match confidence from the raw embedding cosine (independent of rescaling).
+    try:
+        from discoverroute.interpret import embed
+        confidence = embed.raw_top_similarity(vibe)
+    except Exception:  # noqa: BLE001 - encoder unavailable
+        confidence = 1.0
+    weak = bool(text) and confidence < config.WEAK_MATCH_SIMILARITY
+    explanation = _explain(vibe, top, affinity, posture, budget_hint, weak)
+    return Interpretation(affinity, weights, posture, budget_hint, explanation, top,
+                          confidence=confidence, weak=weak)
+
+
+def _explain(vibe, top, affinity, posture, budget_hint, weak=False) -> str:
     if not (vibe or "").strip():
         return "_No vibe given — every kind of place is weighted equally._"
     # Off-domain / unreadable vibe: the interpreter degraded to neutral (all
@@ -81,7 +91,9 @@ def _explain(vibe, top, affinity, posture, budget_hint) -> str:
     if vals and (max(vals) - min(vals)) < 1e-6:
         return (f"_I couldn't read a clear taste from “{vibe.strip()}” — "
                 f"weighting every kind of place equally._")
-    lines = [f"**Reading “{vibe.strip()}” as:**"]
+    header = (f"**No strong match for “{vibe.strip()}” — here's my closest guess:**"
+              if weak else f"**Reading “{vibe.strip()}” as:**")
+    lines = [header]
     for c in top:
         nice = c.replace("_", " ")
         lines.append(f"- {nice} (affinity {affinity[c]:.2f}, "

src/discoverroute/narrate/narrate.py

@@ -57,7 +57,7 @@ def _hours_badge(poi, posture_val: str) -> str:
 
 
 def template_narration(plain, discovery, pois, vibe, mode, start_label="",
-                       end_label="", posture=None, weights=None) -> str:
+                       end_label="", posture=None, weights=None, weak=False) -> str:
     posture = posture or {}
     n = len(pois)
     extra = round(discovery.time_min + getattr(discovery, "dwell_s", 0.0) / 60.0
@@ -65,7 +65,14 @@ def template_narration(plain, discovery, pois, vibe, mode, start_label="",
     unit = "minute" if extra == 1 else "minutes"
     place_word = "place" if n == 1 else "places"
     v = (vibe or "").strip()
-    vibe_clause = f" to match your *{v}* mood" if v else ""
+    # Honest framing for a weak / out-of-vocabulary vibe: don't pretend these are
+    # tailored matches (the review found "brutalist architecture" → churches
+    # confidently labelled "a match for your vibe").
+    if v and weak:
+        vibe_clause = (f" — I didn't find a strong match for *{v}*, so here's a "
+                       f"varied walk worth taking")
+    else:
+        vibe_clause = f" to match your *{v}* mood" if v else ""
     lead = "### Why this route\n"
     lead += (
         f"Spending **{extra} extra {unit}**{vibe_clause}, your {mode} threads "
@@ -73,9 +80,10 @@ def template_narration(plain, discovery, pois, vibe, mode, start_label="",
         f"{end_label or 'the destination'}:\n"
     )
     # The categories the vibe leans on most — used to tie a stop back to the vibe.
+    # A weak vibe has no real matches, so don't tag stops "a match for your vibe".
     top_cats: set[str] = set()
     aff = getattr(weights, "category_affinity", None)
-    if v and aff:
+    if v and aff and not weak:
         top_cats = set(sorted(aff, key=aff.get, reverse=True)[:3])
 
     lines = [lead]
@@ -128,10 +136,10 @@ def llm_available() -> bool:
 
 
 def narrate(plain, discovery, pois, vibe="", mode="walk", start_label="",
-            end_label="", posture=None, weights=None) -> tuple[str, bool]:
+            end_label="", posture=None, weights=None, weak=False) -> tuple[str, bool]:
     """Return (markdown, used_llm). Output is guaranteed grounded."""
     template = template_narration(
-        plain, discovery, pois, vibe, mode, start_label, end_label, posture, weights
+        plain, discovery, pois, vibe, mode, start_label, end_label, posture, weights, weak
     )
     if not llm_available():
         return template, False

src/discoverroute/pipeline.py

@@ -114,6 +114,7 @@ def _plan_route_impl(
     # Taste resolution priority: (persistent profile ⊕ trip vibe) > manual sliders.
     from discoverroute.data import taxonomy
     interp_md = ""
+    weak_match = False
     posture = {c: taxonomy.posture(c) for c in taxonomy.CATEGORIES}
     has_vibe = bool((vibe or "").strip())
     has_profile = bool(
@@ -128,6 +129,7 @@ def _plan_route_impl(
             interp = interpret(vibe, adventurousness, budget)
             posture = interp.posture
             interp_md = interp.explanation
+            weak_match = interp.weak
             # An explicit pace word in the vibe ("quick", "all day") nudges the
             # budget — BUT never resurrects a detour the user explicitly disabled
             # by zeroing the slider (P0-3: budget 0 == plain route, slider wins).
@@ -169,7 +171,7 @@ def _plan_route_impl(
             itinerary_md, _ = narrate(
                 plain, discovery, selected, vibe=vibe, mode=mode,
                 start_label=start_query.strip(), end_label=dest_query.strip(),
-                posture=posture, weights=weights,
+                posture=posture, weights=weights, weak=weak_match,
             )
             alternatives.append(Alternative(
                 discovery=discovery, pois=selected,