fixed the narration+traces

src/discoverroute/narrate/gazetteer.py

@@ -0,0 +1,69 @@
+"""Per-city geographic context the narrator is allowed to name.
+
+The zero-hallucination gate (:mod:`grounding`) rejects any capitalized place
+name that isn't a selected POI or an endpoint. That guarantee is sound for
+*venues* (you must not be told to visit an invented café), but it also rejected
+every neighbourhood, river and quarter a real city guide naturally mentions —
+so any vivid LLM narration crossing recognizable geography got thrown away and
+the flat template shipped instead.
+
+This module supplies a curated, real allowlist of district / quarter / river /
+landmark names per pre-baked city. These are *context* the narrator may
+reference ("as you cross the Marais", "along the Seine") — not stops. They are
+real OSM-scale places, so naming them is grounded, not invented. The generic
+era/architecture adjectives ("Roman", "Gothic") live in :data:`grounding._COMMON`
+instead, since they are city-independent.
+
+On-demand (arbitrary) cities have no gazetteer entry: they get only the POIs +
+endpoints, exactly as before, so an un-curated city still fails closed to the
+template rather than risking an ungrounded neighbourhood name.
+"""
+from __future__ import annotations
+
+# Keyed by ``Area.key`` (see routing/area.py): "paris", "london", "barcelona",
+# "newyork". On-demand areas use a bbox-hash key absent from this map -> no extra
+# context (safe default). Phrases may be multi-word; the gate substring-matches a
+# mention's distinctive core, so "the Latin Quarter" grounds against "Latin
+# Quarter" while "Eiffel Tower" (Eiffel not listed) still correctly fails.
+CITY_GAZETTEER: dict[str, list[str]] = {
+    "paris": [
+        # river / islands / banks
+        "Seine", "Rive Gauche", "Rive Droite", "Left Bank", "Right Bank",
+        "Île de la Cité", "Île Saint-Louis", "Canal Saint-Martin",
+        # quarters / neighbourhoods
+        "Le Marais", "Marais", "Quartier Latin", "Latin Quarter",
+        "Saint-Germain", "Saint-Germain-des-Prés", "Montmartre", "Montparnasse",
+        "Belleville", "Bastille", "Pigalle", "Oberkampf", "Le Sentier",
+        # well-known landmarks/areas a guide name-checks in passing
+        "Sorbonne", "Panthéon", "Champs-Élysées", "Tuileries", "Louvre",
+        "Notre-Dame", "Île-de-France",
+    ],
+    "london": [
+        "Thames", "South Bank", "Southbank", "North Bank", "the City",
+        "Bloomsbury", "Soho", "Covent Garden", "Mayfair", "Westminster",
+        "Southwark", "Lambeth", "Vauxhall", "Holborn", "Clerkenwell",
+        "Fitzrovia", "Marylebone", "the West End", "the East End", "Shoreditch",
+        "Bankside", "Embankment", "Strand", "Piccadilly",
+    ],
+    "barcelona": [
+        "Mediterranean", "Barri Gòtic", "Gothic Quarter", "El Raval", "El Born",
+        "La Ribera", "Eixample", "La Rambla", "Las Ramblas", "Barceloneta",
+        "Gràcia", "Montjuïc", "Poble Sec", "Ciutat Vella", "Port Vell",
+        "Passeig de Gràcia",
+    ],
+    "newyork": [
+        "Manhattan", "Midtown", "Downtown", "Uptown", "SoHo", "NoHo", "Tribeca",
+        "Greenwich Village", "the Village", "East Village", "West Village",
+        "Chelsea", "the Lower East Side", "the Upper West Side",
+        "the Upper East Side", "Times Square", "Central Park", "Hudson",
+        "East River", "Broadway", "Fifth Avenue", "the Flatiron",
+    ],
+}
+
+
+def geo_terms(area_key: str, label: str = "") -> list[str]:
+    """Allowed geographic-context names for an area (empty for un-curated ones)."""
+    terms = list(CITY_GAZETTEER.get((area_key or "").lower(), ()))
+    if label and label.strip():
+        terms.append(label.strip())  # the city's own name ("London", "Paris")
+    return terms

src/discoverroute/narrate/grounding.py

@@ -45,6 +45,18 @@ _COMMON = {
     "weaving", "dip", "duck", "swing", "loop", "breathe", "slow", "set", "make",
     "expect", "stay", "keep", "give", "spend", "spent", "thread", "threaded",
     "minute", "hour", "hours", "place", "places", "stops", "option", "options",
+    # city-independent descriptive words a guide uses: era/architecture styles,
+    # nationalities, and generic geographic nouns. Never standalone venue names,
+    # so admitting them lets prose breathe without opening a hallucination vector
+    # (a distinctive token like "Eiffel" still has to match an allowed name).
+    "roman", "gothic", "medieval", "renaissance", "baroque", "romanesque",
+    "neoclassical", "art", "deco", "nouveau", "modern", "ancient", "classical",
+    "victorian", "georgian", "haussmann", "french", "parisian", "english",
+    "british", "spanish", "catalan", "american", "european",
+    "river", "riverside", "quarter", "district", "neighbourhood", "neighborhood",
+    "bank", "island", "hill", "boulevard", "avenue", "street", "lane", "square",
+    "park", "garden", "gardens", "bridge", "quay", "embankment", "canal",
+    "market", "quartier", "rue", "pont", "jardin", "plaza", "passeig",
 }
 
 _TOKEN_RE = re.compile(r"[A-Za-zÀ-ÖØ-öø-ÿ][A-Za-zÀ-ÖØ-öø-ÿ0-9'’.\-]*")
@@ -58,11 +70,18 @@ def _norm(s: str) -> str:
     return re.sub(r"\s+", " ", s).strip()
 
 
-def allowed_names(pois, start_label: str = "", end_label: str = "") -> list[str]:
+def allowed_names(pois, start_label: str = "", end_label: str = "",
+                  extra_allowed=None) -> list[str]:
     names = [p.name for p in pois if getattr(p, "name", None)]
     for lbl in (start_label, end_label):
         if lbl and lbl.strip():
             names.append(lbl.strip())
+    # Geographic context the narrator may name (districts, river, landmarks) —
+    # supplied per city by narrate.gazetteer. Real OSM-scale places, not invented
+    # venues, so admitting them keeps the grounding guarantee while letting the
+    # LLM write like an actual city guide instead of falling back to the template.
+    if extra_allowed:
+        names.extend(a for a in extra_allowed if a and a.strip())
     names.append("Paris")
     return names
 
@@ -139,9 +158,15 @@ def _is_grounded_mention(mention: str, allowed_norm: list[str]) -> bool:
     return any(core in a for a in allowed_norm if a)
 
 
-def verify_grounded(text: str, pois, start_label="", end_label="") -> tuple[bool, list[str]]:
-    """(ok, offenders). ok=True iff every mention maps to an allowed name."""
-    allowed_norm = [_norm(a) for a in allowed_names(pois, start_label, end_label)]
+def verify_grounded(text: str, pois, start_label="", end_label="",
+                    extra_allowed=None) -> tuple[bool, list[str]]:
+    """(ok, offenders). ok=True iff every mention maps to an allowed name.
+
+    ``extra_allowed`` is the per-city geographic gazetteer (districts, river,
+    landmarks) the narrator may reference beyond the selected POIs + endpoints.
+    """
+    allowed_norm = [_norm(a)
+                    for a in allowed_names(pois, start_label, end_label, extra_allowed)]
     offenders = [
         mention for mention in extract_mentions(text)
         if not _is_grounded_mention(mention, allowed_norm)

src/discoverroute/narrate/llm.py

@@ -12,9 +12,17 @@ import functools
 
 from discoverroute import config
 
+# ZeroGPU reserves the requested ``duration`` seconds of quota *per call*, so a
+# fat slice drains a day's allowance in a dozen requests (the live Space was
+# erroring "180s requested vs. 170s left" then falling back to the template). A
+# 1B model loading from cache + generating ≤480 tokens on an A10G finishes well
+# inside 45s, so request that — ~3× more calls per day, with headroom over the
+# first-call weight-load cost.
+GPU_DURATION_S = 45
+
 try:
     import spaces  # ZeroGPU; effect-free off-Spaces
-    _gpu = spaces.GPU(duration=120)
+    _gpu = spaces.GPU(duration=GPU_DURATION_S)
 except Exception:  # noqa: BLE001 - not on a Space / package absent
     def _gpu(fn):
         return fn
@@ -41,13 +49,18 @@ def run_inference(messages: list[dict], max_new_tokens: int = 320,
                   temperature: float = 0.7) -> str:
     """Run a chat completion. ``messages`` = [{"role","content"}, ...]."""
     tok, model = _load()
+    # MiniCPM5 is a hybrid-reasoning model: with thinking on it emits a
+    # <think>...</think> block first, which would devour the JSON/narration token
+    # budget and leave nothing usable. We want the fast direct answer, so disable
+    # it explicitly (the kwarg is ignored harmlessly by templates that lack it).
     text = tok.apply_chat_template(
-        messages, tokenize=False, add_generation_prompt=True
+        messages, tokenize=False, add_generation_prompt=True, enable_thinking=False
     )
     inputs = tok([text], return_tensors="pt").to(model.device)
+    # MiniCPM5 "no-think" recommended sampling: temperature 0.7, top_p 0.95.
     out = model.generate(
         **inputs, max_new_tokens=max_new_tokens,
-        temperature=temperature, top_p=0.8, top_k=20, do_sample=True,
+        temperature=temperature, top_p=0.95, top_k=20, do_sample=True,
     )
     gen = out[0][inputs.input_ids.shape[1]:]
     return tok.decode(gen, skip_special_tokens=True).strip()

src/discoverroute/narrate/narrate.py

@@ -135,8 +135,14 @@ def llm_available() -> bool:
 
 
 def narrate(plain, discovery, pois, vibe="", mode="walk", start_label="",
-            end_label="", posture=None, weights=None, weak=False) -> tuple[str, bool]:
-    """Return (markdown, used_llm). Output is guaranteed grounded."""
+            end_label="", posture=None, weights=None, weak=False,
+            geo_allowed=None, city_label="") -> tuple[str, bool]:
+    """Return (markdown, used_llm). Output is guaranteed grounded.
+
+    ``geo_allowed`` is the per-city geographic gazetteer (districts, river,
+    landmarks) the LLM may name; ``city_label`` localises the guide's voice
+    (e.g. "London" instead of the old hardcoded "Parisian").
+    """
     template = template_narration(
         plain, discovery, pois, vibe, mode, start_label, end_label, posture, weights, weak
     )
@@ -151,8 +157,9 @@ def narrate(plain, discovery, pois, vibe="", mode="walk", start_label="",
     t0 = time.time()
     try:
         text = _llm_narration(plain, discovery, pois, vibe, mode,
-                              start_label, end_label, weights)
-        ok, offenders = grounding.verify_grounded(text, pois, start_label, end_label)
+                              start_label, end_label, weights, geo_allowed, city_label)
+        ok, offenders = grounding.verify_grounded(
+            text, pois, start_label, end_label, extra_allowed=geo_allowed)
         latency = int((time.time() - t0) * 1000)
         if ok and text.strip():
             trace.log_trace("narration", meta, {"text": text}, latency,
@@ -179,8 +186,14 @@ def _weights_summary(weights) -> str:
 
 
 def _llm_narration(plain, discovery, pois, vibe, mode, start_label, end_label,
-                   weights=None) -> str:
-    """Generate narration with MiniCPM5-1B, constrained to the allowed names."""
+                   weights=None, geo_allowed=None, city_label="") -> str:
+    """Generate narration with MiniCPM5-1B, constrained to the allowed names.
+
+    The model may colour the route with the listed neighbourhoods / river /
+    landmarks (``geo_allowed``) so it reads like a real guide — but it still must
+    not invent a *venue* to visit. Anything it slips past that rule is caught by
+    the grounding gate and the template ships instead.
+    """
     from discoverroute.narrate.llm import run_inference
 
     names = [taxonomy.display_label(p) for p in pois]
@@ -190,26 +203,36 @@ def _llm_narration(plain, discovery, pois, vibe, mode, start_label, end_label,
     extra = round(discovery.time_min - plain.time_min)
     total_min = round(discovery.time_min + getattr(discovery, "dwell_s", 0.0) / 60.0)
     weights_line = _weights_summary(weights)
+    guide = f"{city_label} " if city_label else ""
+    context_terms = ", ".join(geo_allowed) if geo_allowed else ""
 
     system = (
-        "You are a Parisian city guide who knows every street. Write a warm, "
-        "specific, first-person itinerary for this walking route. Reference the "
-        "user's stated vibe directly. For each stop, explain in one sentence why "
-        "it matches what they were looking for. Format as markdown with one "
-        "header per stop.\n"
-        "CRITICAL: mention ONLY the place names listed in the prompt, spelled "
-        "exactly. Never invent or name any other place, street, landmark, or "
-        "neighbourhood. If unsure, refer to a place by its type, not a name."
+        f"You are a {guide}city guide who knows every street. Write a warm, "
+        "vivid, first-person itinerary for this route — sensory and specific, "
+        "the kind of thing a local would actually say. Reference the user's "
+        "stated vibe directly, and in one sentence per stop say why it fits.\n"
+        "You MAY set the scene with the districts, river, and landmarks listed "
+        "under 'You may reference' — name them freely to give the walk a sense "
+        "of place.\n"
+        "HARD RULE: every specific stop you tell the user to visit must be one of "
+        "the 'Ordered stops', spelled exactly. Never invent a café, shop, museum, "
+        "restaurant or any other named venue that isn't in that list. If unsure, "
+        "describe a place by its type, not a made-up name.\n"
+        "Format as markdown with one bold header per stop."
     )
     user = (
         f"Vibe: {vibe or 'open to anything'}\n"
         + (f"Weights extracted: {weights_line}\n" if weights_line else "")
         + f"Mode: {mode} from {start_label or 'the start'} to "
         f"{end_label or 'the destination'}\n"
-        f"Ordered stops:\n{bullet}\n"
+        + (f"You may reference (scene-setting only, do not list as stops): "
+           f"{context_terms}\n" if context_terms else "")
+        + f"Ordered stops (the ONLY venues you may name):\n{bullet}\n"
         f"Total time: {total_min} minutes (about {extra} minutes of discovery)\n\n"
         "Write the itinerary."
     )
     messages = [{"role": "system", "content": system},
                 {"role": "user", "content": user}]
-    return run_inference(messages, max_new_tokens=600)
+    # ≤480 tokens comfortably covers ~6 stops (one short paragraph each) and keeps
+    # generation inside the 45s ZeroGPU slice (see llm.GPU_DURATION_S).
+    return run_inference(messages, max_new_tokens=480)

src/discoverroute/pipeline.py

@@ -185,10 +185,13 @@ def _plan_route_impl(
             if discovery is None or not selected:
                 break
             used_ids.update(p.osm_id for p in selected)
+            from discoverroute.narrate import gazetteer
+            geo_allowed = gazetteer.geo_terms(area.key, area.label)
             itinerary_md, _ = narrate(
                 plain, discovery, selected, vibe=vibe, mode=mode,
                 start_label=start_query.strip(), end_label=dest_query.strip(),
                 posture=posture, weights=weights, weak=weak_match,
+                geo_allowed=geo_allowed, city_label=area.label,
             )
             alternatives.append(Alternative(
                 discovery=discovery, pois=selected,

tests/test_narration.py

@@ -69,6 +69,40 @@ def test_gate_allows_unnamed_by_type():
     assert ok, offenders
 
 
+def test_geo_gazetteer_allows_real_districts():
+    """A guide may name the city's real districts/river when given the gazetteer,
+    so vivid prose passes the gate instead of being thrown out for the template."""
+    from discoverroute.narrate import gazetteer
+    geo = gazetteer.geo_terms("paris", "Paris")
+    text = ("From the Marais, drift down toward the Seine and into the Latin "
+            "Quarter, passing Jardin des Plantes for some green and Fontaine "
+            "Médicis. A very Parisian wander with Roman echoes near the Panthéon.")
+    ok, offenders = grounding.verify_grounded(
+        text, POIS, start_label="Bastille", end_label="Panthéon",
+        extra_allowed=geo,
+    )
+    assert ok, offenders
+
+
+def test_geo_gazetteer_still_blocks_invented_venue():
+    """Loosening for districts must NOT let an invented venue through."""
+    from discoverroute.narrate import gazetteer
+    geo = gazetteer.geo_terms("paris", "Paris")
+    text = ("Cross the Marais, then stop at Café des Mensonges, a charming "
+            "invented spot, before Jardin des Plantes.")
+    ok, offenders = grounding.verify_grounded(
+        text, POIS, start_label="Bastille", extra_allowed=geo,
+    )
+    assert not ok
+    assert any("Mensonges" in o for o in offenders)
+
+
+def test_uncurated_city_has_no_extra_context():
+    """An on-demand area (bbox-hash key) gets no gazetteer => fails closed."""
+    from discoverroute.narrate import gazetteer
+    assert gazetteer.geo_terms("48.1,2.2,48.2,2.3", "this area") == ["this area"]
+
+
 class _Route:
     def __init__(self, time_min):
         self.time_min = time_min