Upload folder using huggingface_hub

README.md

@@ -1,7 +1,7 @@
 ---
 title: MatchDay
 emoji: ⚽
-colorFrom: blue
+colorFrom: indigo
 colorTo: green
 sdk: gradio
 app_file: app.py
@@ -12,70 +12,193 @@ tags:
   - backyard-ai
   - agents
   - react-agent
+  - agentic
+  - agent-loop
   - tool-use
+  - tool-calling
+  - multi-step-planning
   - nemotron
   - nvidia
+  - nvidia-nemotron
+  - nemotron-3-nano
   - modal
+  - modal-labs
+  - sglang
   - gradio
+  - gradio-server
+  - off-brand
   - fifa-world-cup-2026
-  - travel
+  - vancouver
+  - travel-planning
+  - trip-planner
+  - leaflet
 models:
   - nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-BF16
 ---
 
-# MatchDay ⚽ — 2026 FIFA World Cup, Vancouver
+# MatchDay ⚽ — your 2026 FIFA World Cup trip, planned by a small-model agent
 
-MatchDay is a Layla.ai-style **travel-intelligence agent** with one job: get you
-to a 2026 FIFA World Cup match in Vancouver with the **cheapest flight, the
-safest arrival, and a hotel closest to BC Place — explained, not just listed.**
+> **A Backyard AI app for a real Vancouver World Cup use case: helping a fan plan
+> one match-day trip with small-model reasoning, Gradio polish, and safe manual
+> booking links.**
 
-Say *"Flying from Montreal, want Canada vs Qatar, mid-range, June 26-29"* and
-MatchDay's agent builds **3 ranked, scored packages** (flights · hotels ·
-weather · what's near the stadium) on an interactive Leaflet map, each price
-tagged with **honest provenance** — `● live` vs `example` — so nothing is
-hallucinated.
+Type one sentence — *"Flying from Montreal, want Canada vs Qatar, mid-range,
+June 26-29, just me"* — and MatchDay's agent **grounds your request in the real
+schedule, searches live flights + hotels + weather, ranks 3 packages, and
+explains why each one won.** Every price is tagged `● live` or `example` so
+nothing is hallucinated, and every booking link is a safe **search** (never a
+fake "confirmed booking").
+
+## The idea
+
+The 2026 World Cup is in Vancouver. Fans have one chaotic question — *"how do I
+actually get to one match?"* — and existing tools split the answer across five
+tabs (flights here, hotels there, weather somewhere else). MatchDay collapses it
+into a single agent turn: **understand intent → ground it against the real
+fixture list → call live data tools → rank → explain.** It's a focused, backyard
+trip planner that treats a small model as a genuine decision-maker, not a chatbot.
+
+The standout agent behavior: **MatchDay corrects you when you're wrong and
+refuses to plan when a match doesn't exist.** Ask for *"Canada vs Qatar, June
+26"* and it tells you the real match is **June 18 at BC Place, 12:00 PM PT** and
+re-plans around it. Ask for *"Canada vs Morocco"* and it won't pretend — that
+match doesn't exist, so it offers the real alternatives instead. That grounding
+is the difference between an agent and a form.
 
 ## How it works — Brain + Hands
-- **Brain:** **NVIDIA Nemotron-3-Nano-30B-A3B-BF16** — a 30B-total / **3B-active**
-  Mixture-of-Experts model, served on **Modal A100** via SGLang. It selects tools,
-  reasons, and writes the explanations. **It never calls an API or names a price.**
-- **Hands:** deterministic Python calls the APIs (flights, hotels, weather, POIs),
-  scores packages with a fixed cost / arrival-buffer / stadium-proximity formula,
-  and attaches provenance to every value.
-- **Loop:** a bounded ReAct agent (≤5 tool rounds). Nemotron decides the sequence,
-  the hands execute, results return — Nemotron-3-Nano emits structured tool calls
-  via SGLang's `qwen3_coder` + `nemotron_3` parsers.
-
-## Why this is "small"
-Nemotron-3-Nano-30B is a MoE — only **~3B parameters activate per token**, so the
-reasoning path is genuinely lean. Heavy 30B inference runs **remotely on Modal**
-(sanctioned hackathon compute); the Gradio Space itself stays lightweight.
-
-## Tech
-Nemotron-3-Nano-30B-A3B (3B-active MoE) · Modal A100-80GB (SGLang v0.5.12,
-`qwen3_coder`+`nemotron_3`) · **gradio.Server** custom frontend (streaming chat +
-Leaflet map + day-by-day timeline — not stock Gradio) · SerpApi (Google
-Flights/Hotels/Search) · Open-Meteo · OpenStreetMap · httpx/Pydantic v2.
+
+- **🧠 Brain (decides + explains):** **NVIDIA Nemotron-3-Nano-30B-A3B** — a
+  30B-total / **3B-active** Mixture-of-Experts model — served on **Modal A100**
+  via **SGLang**. It reads the request, picks tools, reasons about results, and
+  writes the final comparison. **It never calls an API, fetches a URL, or states
+  a price itself.**
+- **✋ Hands (execute + score):** deterministic **Python** calls every API
+  (flights, hotels, weather, nearby spots), fans them out concurrently, and
+  scores each package with a fixed formula (cost / arrival-buffer /
+  stadium-proximity). Every value gets a provenance badge.
+- **🔁 Loop:** a bounded ReAct agent loop (**≤5 tool rounds**) with an allowlist,
+  Pydantic argument validation, duplicate-call detection, one self-correction
+  pass, per-tool timeouts, and an honest deterministic fallback. Nemotron emits
+  structured tool calls via SGLang's `qwen3_coder` + `nemotron_3` parsers.
+
+## 🤖 Best Agent — multi-step tool use & planning (under the 32B cap)
+
+This is the category we care about most, so here's exactly what makes MatchDay
+an agent and not a pipeline:
+
+- **3 tools, picked autonomously:** `build_trip_packages` (the data/scoring tool),
+  `web_search` (factual grounding — kickoff times, venue policy), and `clarify`
+  (ask one question when origin/date is genuinely missing).
+- **Genuine multi-step turns:** Nemotron can `web_search` to ground a fact, read
+  the result, *then* call `build_trip_packages` with corrected understanding —
+  results threaded back into the conversation between rounds. Happy path is 2-3
+  rounds; the ceiling is 5 (`matchday/agent_loop.py`).
+- **Schedule grounding before planning** (`matchday/wc2026.py`): a verified
+  fixture table is the ground truth. The agent re-centers the trip on the *real*
+  match date (preserving the user's nights) and refuses nonexistent matchups
+  with honest alternatives — proven by `tests/test_wc2026_grounding.py`
+  (6/6 zero-network checks: Canada vs Qatar → Jun 18 / 12:00 PT / 3 nights;
+  Brazil vs Germany and Canada vs Morocco refused).
+- **Guardrails that keep it honest:** tool allowlist, Pydantic arg validation,
+  duplicate suppression, one malformed-call correction, timeouts, and a
+  user-visible fallback to deterministic parsing when Modal is cold-starting.
+- **Brain + Hands separation:** the model decides and explains; Python executes
+  every external call and scores every price — so the model can't hallucinate a
+  flight number or invent a rate.
+
+Nemotron-3-Nano-30B is **30B total parameters < the 32B cap.**
+
+## 🎨 Off-Brand — a custom UI on `gradio.Server`, well past stock Gradio
+
+MatchDay does **not** use stock Gradio components. It runs on **`gradio.Server`**
+(`app.py`), which serves a fully bespoke `index.html` frontend at `/` while a
+single `@app.api("plan_trip")` async generator streams typed JSON events through
+Gradio's queue (SSE) — so the UI updates live as the agent decides → Python
+scores → Nemotron explains. `gr.Server` gives us Gradio's backend (queuing,
+concurrency, Spaces hosting) under a hand-built product UI:
+
+- Layla-style **photo-header package cards** with overlaid price + "★ Best match".
+- **Provenance pills** on every figure (`● live` vs `example`) — the
+  anti-hallucination differentiator, visible right in the card.
+- An interactive **Leaflet map** (stadium + hotels + POIs, hotel→stadium lines,
+  full-screen toggle) built in `matchday/render.py`.
+- A **day-by-day itinerary** with unique, date-aware roles (arrival / match day /
+  local explore / departure) and a live **agent progress panel**.
+- Per-option **action buttons**: a real flight/hotel **search** and
+  trip-specific **transit directions** (always with explicit origins) — never an
+  over-claiming "Book" button.
+
+## 🟢 NVIDIA Nemotron Quest — Nemotron is the Brain
+
+- **Model:** `nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-BF16` (30B MoE, ~3B active/token).
+- **Served with SGLang** (`matchday/modal_spike.py`) using the NVIDIA-card
+  recommended tool-calling config: `--tool-call-parser qwen3_coder` +
+  `--reasoning-parser nemotron_3` + `--attention-backend flashinfer`. Verified
+  live that SGLang returns *parsed* `tool_calls` (not raw text) — the whole
+  Brain+Hands design depends on it. See `matchday/NEMOTRON_SGLANG_VERIFICATION.md`.
+- **Reasoning mode:** Nemotron-3-Nano's thinking toggle (`enable_thinking`) is
+  wired end-to-end (`modal_spike.generate` → `matchday.agent.MatchDayAgent` →
+  `app.py`) per the official Nemotron usage guide. Enable on the Space with
+  `MATCHDAY_THINKING=1` to run the decide/ground/explain turns with
+  chain-of-thought reasoning.
+- **Sampling** follows the model card: `temperature=0.6 / top_p=0.95` for tool
+  routing, reasoning on for complex planning.
+
+## 🟣 Modal — the runtime & inference layer
+
+- Nemotron runs **remotely on Modal** (`modal.App("matchday-spike")`) on an
+  **A100-80GB** via a containerized SGLang server (`matchday/modal_spike.py`).
+- The Gradio Space calls it with `modal.Cls.from_name(...).generate.remote.aio`
+  — the Space stays lightweight while the heavy 30B inference happens on
+  sanctioned Modal GPU compute.
+- **Cold-start engineering:** a 60GB-model HF cache **Volume** (warm reload
+  ~1-2 GB/s vs re-download), `startup_timeout=120 min` for first load, a
+  server-side `warmup()`, and a Space-boot `_warm_nemotron()` task so the first
+  user query isn't stuck behind a cold start.
+
+## Tech stack
+
+Nemotron-3-Nano-30B-A3B (3B-active MoE) · Modal A100-80GB + SGLang v0.5.12
+(`qwen3_coder` + `nemotron_3`) · **gradio.Server** bespoke frontend · SerpApi
+(Google Flights / Hotels / Search) · Open-Meteo (weather) · OpenStreetMap/Overpass
+(nearby spots) · Leaflet + CARTO map · httpx + Pydantic v2 · Python 3.11.
 
 ## Try it
-- **Live Space:** https://huggingface.co/spaces/build-small-hackathon/matchday
-- **Agent trace (Sharing-is-Caring):** https://huggingface.co/datasets/build-small-hackathon/matchday-agent-traces
+
+- **Live app:** https://build-small-hackathon-matchday.hf.space
+- **Space:** https://huggingface.co/spaces/build-small-hackathon/matchday
 - **Field Notes (architecture story):** `matchday/FIELD_NOTES.md`
+- **Nemotron + SGLang verification:** `matchday/NEMOTRON_SGLANG_VERIFICATION.md`
+
+**Example queries to try:**
+1. *Flying from Montreal, want Canada vs Qatar, mid-range, June 26-29, just me* → watch it correct the date to **June 18**.
+2. *Toronto to see Brazil vs Germany, premium, July 12, 2 adults* → watch it **refuse** a nonexistent match honestly.
+3. *From Halifax, Canada vs Morocco, June 18, couple, luxury* → refused with real Group B alternatives.
+
+## Prizes we're competing for
+
+| Prize | Why MatchDay qualifies |
+| --- | --- |
+| 🤖 **Best Agent** | Bounded ReAct loop (≤5 rounds), 3 tools chosen autonomously, genuine multi-step turns (search → build), schedule grounding + honest refusal, guardrails. 30B < 32B. |
+| 🎨 **Off-Brand** | Bespoke Layla-style UI on `gradio.Server` — custom HTML/CSS/JS, photo cards, Leaflet map, provenance pills. Not stock Gradio. |
+| 🟢 **NVIDIA Nemotron Quest** | Nemotron-3-Nano-30B is the Brain; SGLang tool-calling verified live; reasoning mode wired. |
+| 🟣 **Modal** | A100 inference runtime, documented above (`matchday/modal_spike.py`). |
+| 🎬 **Best Demo** | App + demo script (`matchday/DEMO_VIDEO_SCRIPT.md`) + social post (`matchday/SOCIAL_POST.md`). |
+| 🏆 **Bonus Quest Champion** | Nemotron + Modal + Gradio + agent + custom UI, all in one focused app. |
+| 🗳️ **Judges' Wildcard** | A genuinely useful, honest, small-model trip planner that corrects its user. |
+
+> **Honest note on Tiny Titan:** we are **not** claiming Tiny Titan. That prize
+> requires a model of ≤4B parameters; Nemotron-3-Nano-30B is a 30B-total MoE
+> (only ~3B *active* per token, but 30B total weights). We'd rather flag this
+> than over-claim.
 
 ## Built for Build Small
-**Track: Backyard AI.** Sponsor tools used: **Nemotron-3-Nano-30B (NVIDIA)** +
-**Modal** (noted here per the Modal-prize requirement; Modal A100 is the runtime).
-
-Targeting:
-- 🟩 **NVIDIA Nemotron** — Nemotron-3-Nano-30B-A3B is the Brain.
-- 🟢 **Modal** ($10k/7k/3k) — Modal A100 serves the model.
-- 🤖 **Best Agent** — bounded multi-step tool use, ≤32B.
-- 🎨 **Off-Brand** — `gradio.Server` custom UI well beyond stock Gradio.
-- 📡 **Sharing-is-Caring** — agent trace on the Hub (link above).
-- 📓 **Field Notes** — architecture blog (`matchday/FIELD_NOTES.md`).
-- 🏆 **Bonus Quest Champion** + 🎬 **Best Demo** + 🗳️ **Community Choice**.
+
+**Track: Backyard AI** — a focused, real-world Vancouver World Cup use case.
+Sponsor tools used: **NVIDIA Nemotron-3-Nano-30B** (the Brain) + **Modal A100**
+(the runtime) + **Gradio `gradio.Server`** (the Off-Brand UI).
 
 ## Social
-**Post:** <paste your social post URL here> (REQ-04 — link your post, then redeploy).
-A ready-to-post draft is in `matchday/SOCIAL_POST.md`.
 
+**Post:** _<paste your social post URL here, then redeploy>_ — a ready-to-post
+draft is in `matchday/SOCIAL_POST.md`.

app.py

@@ -187,7 +187,14 @@ async def plan_trip(user_text: str) -> str:
     agent = None
     if USE_AGENT:
         try:
-            agent = MatchDayAgent()
+            # Nemotron reasoning toggle (NVIDIA Nemotron Quest + Best Agent): the
+            # official Nemotron-3-Nano usage guide serves complex planning turns
+            # with thinking ON (chain-of-thought before the tool call). Default
+            # OFF to preserve the verified fast tool-routing path; set
+            # MATCHDAY_THINKING=1 on the Space to turn on reasoning for the
+            # agent's decide/ground/explain turns.
+            thinking = os.environ.get("MATCHDAY_THINKING", "").lower() in ("1", "true", "yes")
+            agent = MatchDayAgent(thinking=thinking)
         except Exception as exc:
             logger.warning("agent init failed (%s); deterministic path.", exc)
 
@@ -222,6 +229,23 @@ async def plan_trip(user_text: str) -> str:
             if res.type == "tool_called" and res.tool == "build_trip_packages":
                 result = res.result.get("full_result")
                 trip = res.result.get("trip")
+                # Sync the display trip to the GROUNDED dates + canonical match
+                # name (the match was re-centered on the real WC fixture inside
+                # the tool), and surface any correction note to the user.
+                if result is not None and getattr(result, "grounded_match_date", None) and trip is not None:
+                    upd = {
+                        "match_date": result.grounded_match_date,
+                        "check_in": result.grounded_check_in,
+                        "check_out": result.grounded_check_out,
+                    }
+                    if getattr(result, "grounded_match_name", ""):
+                        upd["match_name"] = result.grounded_match_name
+                    try:
+                        trip = trip.model_copy(update=upd)
+                    except Exception:
+                        pass
+                if result is not None and getattr(result, "grounding_note", ""):
+                    yield _ev(type="commentary", text="📅 " + result.grounding_note)
                 break
 
             if res.type == "tool_called" and res.tool == "web_search":
@@ -263,6 +287,14 @@ async def plan_trip(user_text: str) -> str:
                 )
             break
 
+    # If the agent's build already flagged an unrecognized match, surface it as a
+    # clarification with real alternatives (Best-Agent honesty: never silently
+    # plan a trip around a nonexistent fixture like "Canada vs Morocco").
+    if result is not None and getattr(result, "match_unrecognized", ""):
+        yield _ev(type="progress", step="ready", status="fallback", text="Match not found")
+        yield _ev(type="clarify", text=result.match_unrecognized)
+        return
+
     # ── Deterministic fallback (K3): parse intent + build directly. Used when
     # the agent is unavailable, hedged to a non-build answer, or the loop failed.
     if result is None and not agent_text:
@@ -290,6 +322,27 @@ async def plan_trip(user_text: str) -> str:
             except Exception as exc:
                 yield _ev(type="error", text=f"⚠️ {exc}")
                 return
+            # Sync the display trip to the GROUNDED dates so greenlight +
+            # itinerary match the packages (match was re-centered on the real
+            # WC fixture inside build_trip_packages). Honesty: show the note.
+            if getattr(result, "grounded_match_date", None):
+                upd = {
+                    "match_date": result.grounded_match_date,
+                    "check_in": result.grounded_check_in,
+                    "check_out": result.grounded_check_out,
+                }
+                if getattr(result, "grounded_match_name", ""):
+                    upd["match_name"] = result.grounded_match_name
+                try:
+                    trip = trip.model_copy(update=upd)
+                except Exception:
+                    pass
+            if getattr(result, "match_unrecognized", ""):
+                yield _ev(type="progress", step="ready", status="fallback", text="Match not found")
+                yield _ev(type="clarify", text=result.match_unrecognized)
+                return
+            if getattr(result, "grounding_note", ""):
+                yield _ev(type="commentary", text="📅 " + result.grounding_note)
         else:
             yield _ev(type="progress", step="ready", status="fallback", text="Need a detail from you")
             yield _ev(

matchday/render.py

@@ -414,10 +414,13 @@ def render_status_bar(result: TripPackageResult) -> str:
 def _js_markers(result: TripPackageResult) -> str:
     """Build Leaflet JS: stadium + hotel + POI markers + hotel→stadium lines."""
     lines: list[str] = []
+    # Real kickoff from the grounded fixture (e.g. "12:00 PT"); never the old
+    # hard-coded "7:00 PM PT". Empty → honest "kickoff TBD".
+    kickoff = result.kickoff_local or "kickoff TBD"
     lines.append(
         f"var bb=[[{BC_PLACE_LAT},{BC_PLACE_LON}]];"
         f"L.marker([{BC_PLACE_LAT},{BC_PLACE_LON}],{{icon:stadiumIcon}})"
-        f".addTo(map).bindPopup('<b>🏟️ BC Place Stadium</b><br>Match venue · 7:00 PM PT');"
+        f".addTo(map).bindPopup('<b>🏟️ BC Place Stadium</b><br>Match venue · {kickoff}');"
     )
     seen: set[tuple[float, float]] = {(BC_PLACE_LAT, BC_PLACE_LON)}
     for p in result.packages:
@@ -510,6 +513,8 @@ def render_timeline(trip, result: TripPackageResult) -> str:
     from datetime import timedelta
 
     top = result.packages[0] if result.packages else None
+    # Real kickoff (e.g. "12:00 PT") from the grounded fixture; "" → "kickoff TBD".
+    kickoff = (", " + result.kickoff_local) if getattr(result, "kickoff_local", "") else ""
     wx_by_date = {}
     if top and top.weather:
         wx_by_date = {w.date: w for w in top.weather}
@@ -544,7 +549,7 @@ def render_timeline(trip, result: TripPackageResult) -> str:
                 arrive = f"Land via {flight_bit}, drop bags at <b>{_e(hotel_name)}</b>, then "
             icon, lbl, title, body, cls = (
                 "🏟️", "Match day", f"{head} — MATCH DAY",
-                f"{arrive}<b>{_e(trip.match_name)}</b> at BC Place, ~7:00 PM PT. "
+                f"{arrive}<b>{_e(trip.match_name)}</b> at BC Place{kickoff}. "
                 "Soak up the FIFA fan zone first, then it's a short "
                 f"{top.hotel_to_stadium_min if top else 'few'}-min walk from "
                 f"<b>{_e(hotel_name)}</b>.{_wx_note(d)} Head back after full-time.",

matchday/trip_tool.py

@@ -34,7 +34,7 @@ from __future__ import annotations
 
 import asyncio
 import logging
-from datetime import datetime, timezone
+from datetime import date, datetime, timezone
 from typing import Any, Literal
 
 from pydantic import BaseModel, ConfigDict
@@ -55,6 +55,7 @@ from matchday.models import (
     TripRequest,
     Weather,
 )
+from matchday.wc2026 import ground_match
 
 # Side-effect import: registers every API normalizer (weather/pois/flights/
 # hotels) with the module-level ``registry`` so dispatch() below finds them.
@@ -111,6 +112,33 @@ class TripPackageResult(BaseModel):
     missing, all flights late).
     """
 
+    grounding_note: str = ""
+    """Human-readable note when the match was grounded in the verified 2026 WC
+    schedule — e.g. a date correction, or a non-Vancouver-venue warning.
+    Empty when the user's match/date were already correct."""
+
+    match_unrecognized: str = ""
+    """When non-empty, the named match is NOT a real 2026 fixture; this string
+    holds an honest explanation + real alternatives. The pipeline halts (no
+    packages) rather than planning a trip around a nonexistent match."""
+
+    kickoff_local: str = ""
+    """The verified match kickoff in local time (e.g. ``"12:00 PT"``), or ``""``
+    when unconfirmed. Render replaces the old hard-coded "7:00 PM PT"."""
+
+    grounded_match_date: date | None = None
+    """The REAL match date after schedule grounding, when the trip was
+       re-centered on the verified fixture. Callers sync their display trip
+       to this so the itinerary + greenlight match the packages."""
+
+    grounded_check_in: date | None = None
+    grounded_check_out: date | None = None
+    """Re-bracketed check-in/out around ``grounded_match_date``."""
+
+    grounded_match_name: str = ""
+    """Canonical match name from the verified schedule (e.g. ``"Canada vs Qatar"``)
+       after grounding. Empty when the match was unrecognized."""
+
     model_config = ConfigDict(frozen=True, extra="forbid")
 
 
@@ -360,6 +388,58 @@ async def build_trip_packages(trip_request: TripRequest) -> TripPackageResult:
             total_combinations_scored=0,
         )
 
+    # ------------------------------------------------------------------
+    # 1b. GROUND the match in the verified 2026 WC schedule (Best-Agent
+    #     crux: a real agent corrects "Canada vs Qatar, June 26" to the real
+    #     June 18 fixture, and refuses to plan a trip around a nonexistent
+    #     match like "Canada vs Morocco"). Every downstream call (flights,
+    #     hotels, weather, scoring, itinerary) then uses the REAL date +
+    #     kickoff, so packages are built around truth, not the user's typo.
+    # ------------------------------------------------------------------
+    grounding_note = ""
+    match_unrecognized = ""
+    kickoff_local = ""
+    try:
+        grounded = ground_match(
+            trip_request.match_name,
+            trip_request.match_date,
+            trip_request.check_in,
+            trip_request.check_out,
+        )
+    except Exception:  # grounding must never break the build
+        grounded = None
+
+    if grounded is not None:
+        kickoff_local = grounded.kickoff
+        grounding_note = grounded.note
+        # Re-center the trip on the REAL date (keeps the user's trip length).
+        # TripRequest is frozen + validated, so rebuild via model_copy.
+        try:
+            trip_request = trip_request.model_copy(update={
+                "match_name": grounded.match_name,
+                "match_date": grounded.match_date,
+                "check_in": grounded.check_in,
+                "check_out": grounded.check_out,
+            })
+        except Exception:
+            pass  # keep the user's original dates if re-bracketing is invalid
+    else:
+        # Matchup not in the verified schedule → resolve() built alternatives.
+        from matchday.wc2026 import resolve_match
+        res = resolve_match(trip_request.match_name)
+        match_unrecognized = res.note or (
+            f"“{trip_request.match_name}” isn't a recognized 2026 World Cup "
+            "fixture. Tell me which real match you'd like to plan around."
+        )
+        return TripPackageResult(
+            packages=[],
+            status="failed",
+            degradation_notices=[match_unrecognized],
+            generated_at=now,
+            total_combinations_scored=0,
+            match_unrecognized=match_unrecognized,
+        )
+
     # ------------------------------------------------------------------
     # 2. Dispatch all API categories concurrently
     # ------------------------------------------------------------------
@@ -433,6 +513,12 @@ async def build_trip_packages(trip_request: TripRequest) -> TripPackageResult:
         degradation_notices=degradation_notices,
         generated_at=now,
         total_combinations_scored=total_combinations,
+        grounding_note=grounding_note,
+        kickoff_local=kickoff_local,
+        grounded_match_date=trip_request.match_date,
+        grounded_check_in=trip_request.check_in,
+        grounded_check_out=trip_request.check_out,
+        grounded_match_name=trip_request.match_name,
     )
 
 

matchday/wc2026.py

@@ -0,0 +1,240 @@
+"""Verified 2026 FIFA World Cup fixtures — MatchDay's ground truth for match
+grounding (the "Best Agent" crux: intent → ground in reality → rank).
+
+WHY THIS EXISTS
+---------------
+Before this module, MatchDay accepted whatever match name + date the user typed
+and built a trip around it — so "Canada vs Qatar, June 26" produced a June 26
+trip even though the real match is **June 18 at BC Place**, and "Canada vs
+Morocco" silently planned a trip for a match that doesn't exist. A real agent
+grounds intent in truth. This module is that ground truth.
+
+DATA PROVENANCE
+---------------
+Schedule facts below are the *published* fixtures from the official FIFA match
+schedule released after the Final Draw (Dec 5, 2025), cross-checked across
+FIFA.com, ESPN, Sky Sports and host-city sites. This is a STATIC, curated table
+— NOT a live feed. For any match not listed here, callers should fall back to
+the agent's live ``web_search`` grounding rather than guess.
+
+Source of truth: https://www.figma.com → FIFA:
+https://www.fifa.com/en/tournaments/mens/worldcup/canadamexicousa2026/scores-fixtures
+
+ACCURACY POLICY
+---------------
+Only fixtures confirmed across multiple sources are listed. Kickoff times are
+included only when well-sourced; otherwise ``""`` (rendered as "kickoff TBD —
+check FIFA") — we never fabricate a time.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import date, timedelta
+
+TOURNAMENT_START = date(2026, 6, 11)
+TOURNAMENT_END = date(2026, 7, 19)
+
+
+@dataclass(frozen=True)
+class Fixture:
+    """One verified 2026 World Cup fixture."""
+
+    match: str            # canonical "Team A vs Team B" (as scheduled)
+    match_date: date
+    venue: str            # "BC Place"
+    city: str             # "Vancouver"
+    kickoff: str          # "12:00 PT" or "" when unconfirmed
+    group: str            # "B"
+
+
+# ── Verified fixtures (high confidence) ──────────────────────────────────────
+# Canada's full Group B slate + the other BC Place group games + Brazil/Group C
+# (enough to correct every one of the user's example queries honestly).
+_FIXTURES: list[Fixture] = [
+    # Group B — Canada's group (Canada, Bosnia & Herzegovina, Qatar, Switzerland)
+    Fixture("Canada vs Bosnia and Herzegovina", date(2026, 6, 12), "BMO Field", "Toronto", "15:00 ET", "B"),
+    Fixture("Canada vs Qatar", date(2026, 6, 18), "BC Place", "Vancouver", "12:00 PT", "B"),
+    Fixture("Canada vs Switzerland", date(2026, 6, 24), "BC Place", "Vancouver", "12:00 PT", "B"),
+    Fixture("Qatar vs Switzerland", date(2026, 6, 13), "Levi's Stadium", "San Francisco Bay Area", "", "B"),
+    Fixture("Switzerland vs Bosnia and Herzegovina", date(2026, 6, 18), "SoFi Stadium", "Los Angeles", "", "B"),
+    Fixture("Bosnia and Herzegovina vs Qatar", date(2026, 6, 24), "Lumen Field", "Seattle", "", "B"),
+    # Group C — Brazil's group (Brazil, Morocco, Scotland, Haiti)
+    Fixture("Brazil vs Morocco", date(2026, 6, 13), "MetLife Stadium", "New York / New Jersey", "18:00 ET", "C"),
+    # Other BC Place (Vancouver) group-stage games
+    Fixture("Australia vs Türkiye", date(2026, 6, 13), "BC Place", "Vancouver", "21:00 PT", "D"),
+    Fixture("New Zealand vs Egypt", date(2026, 6, 22), "BC Place", "Vancouver", "", "G"),
+    Fixture("Argentina vs Austria", date(2026, 6, 22), "BC Place", "Vancouver", "", "G"),
+]
+
+# Spoken team-name aliases → canonical token used for matching. Lets "Bosnia"
+# match "Bosnia and Herzegovina", "USA" match "United States", etc.
+_TEAM_ALIASES: dict[str, str] = {
+    "bosnia and herzegovina": "bosnia", "bosnia & herzegovina": "bosnia",
+    "bosnia-herzegovina": "bosnia",
+    "new zealand": "newzealand",
+    "united states": "usa", "united states of america": "usa", "america": "usa",
+    "south korea": "korea", "korea republic": "korea",
+    "ir iran": "iran", "iran ir": "iran",
+    "türkiye": "turkey", "turkiye": "turkey",
+    "czechia": "czechrepublic", "czech republic": "czechrepublic",
+}
+
+
+def _norm_team(raw: str) -> str:
+    """Normalize one team name to a canonical lowercase token."""
+    t = raw.lower().strip().replace("&", "and").replace(".", "").replace("-", " ")
+    t = " ".join(t.split())
+    return _TEAM_ALIASES.get(t, t)
+
+
+def _split_match(match_name: str) -> list[str]:
+    """Split 'A vs B' into normalized team tokens (any order)."""
+    import re
+    parts = re.split(r"\b(?:vs?\.?|versus|[-–])\b", match_name, maxsplit=1, flags=re.IGNORECASE)
+    if len(parts) != 2:
+        return []
+    return [_norm_team(parts[0]), _norm_team(parts[1])]
+
+
+def _teams_match(query_teams: list[str], fixture: Fixture) -> bool:
+    """Order-independent match: both query teams appear among the fixture teams."""
+    if len(query_teams) != 2:
+        return False
+    ft = {_norm_team(fixture.match.split(" vs ")[0]), _norm_team(fixture.match.split(" vs ")[1])}
+    # a query team matches if it equals a fixture team OR one is a substring of
+    # the other (handles "Bosnia" vs "bosnia", "Korea" vs "south korea").
+    def hit(q: str) -> str | None:
+        for f in ft:
+            if q == f or (len(q) >= 3 and (q in f or f in q)):
+                return f
+        return None
+    a, b = hit(query_teams[0]), hit(query_teams[1])
+    return bool(a and b and a != b)
+
+
+@dataclass(frozen=True)
+class ResolveResult:
+    """Outcome of resolving a user's match name against verified fixtures."""
+
+    fixture: Fixture | None       # the verified fixture, or None if unrecognized
+    recognized: bool              # True iff the matchup exists in 2026 (any venue)
+    in_vancouver: bool            # True iff a recognized fixture is at BC Place
+    note: str                     # human-readable grounding note for the UI
+
+
+def resolve_match(match_name: str) -> ResolveResult:
+    """Resolve a user-typed match to a verified 2026 fixture.
+
+    Returns the Fixture if the matchup is real, plus flags + a UI note. If the
+    two teams never play each other in 2026, ``fixture`` is None and ``note``
+    suggests the nearest real alternatives so the app can clarify honestly.
+    """
+    qt = _split_match(match_name or "")
+    if len(qt) != 2:
+        return ResolveResult(None, False, False, "")
+
+    # Does this exact matchup exist?
+    exact = next((f for f in _FIXTURES if _teams_match(qt, f)), None)
+    if exact:
+        van = exact.city.lower() == "vancouver"
+        return ResolveResult(exact, True, van, "")
+
+    # Matchup not found — are BOTH teams in the tournament (just not vs each
+    # other)? Build honest alternatives from each team's real fixtures.
+    a_games = [f for f in _FIXTURES if _teams_match([qt[0], "__probe__"], f) or _has_team(f, qt[0])]
+    b_games = [f for f in _FIXTURES if _has_team(f, qt[1])]
+    # Simpler: gather each team's fixtures directly.
+    a_games = [f for f in _FIXTURES if _has_team(f, qt[0])]
+    b_games = [f for f in _FIXTURES if _has_team(f, qt[1])]
+
+    def _summarize(games: list[Fixture], team: str) -> str:
+        if not games:
+            return ""
+        items = ", ".join(
+            f"{_other(f, team)} ({f.match_date:%b %-d}, {f.city})" for f in games
+        )
+        return f"{team.title()} plays: {items}."
+
+    note = f"“{match_name}” isn't a 2026 World Cup fixture. "
+    note += _summarize(a_games, qt[0]) + " " if a_games else ""
+    note += _summarize(b_games, qt[1]) + " " if b_games else ""
+    note += "Tell me which real match you'd like to plan around."
+    note = " ".join(note.split())
+    return ResolveResult(None, False, False, note)
+
+
+def _has_team(fixture: Fixture, team_token: str) -> bool:
+    ft = {_norm_team(fixture.match.split(" vs ")[0]), _norm_team(fixture.match.split(" vs ")[1])}
+    return any(team_token == f or (len(team_token) >= 3 and (team_token in f or f in team_token)) for f in ft)
+
+
+def _other(fixture: Fixture, team_token: str) -> str:
+    """Return the fixture's team that is NOT the given token (for summaries)."""
+    a, b = fixture.match.split(" vs ")
+    return a if _norm_team(b) == team_token or team_token in _norm_team(b) else b
+
+
+@dataclass(frozen=True)
+class GroundedTrip:
+    """Result of grounding a TripRequest against the real schedule."""
+
+    match_name: str           # canonical match name (e.g. "Canada vs Qatar")
+    match_date: date          # the REAL match date (corrected)
+    check_in: date            # re-bracketed around the real date
+    check_out: date
+    venue: str                # "BC Place"
+    city: str                 # "Vancouver"
+    kickoff: str              # "12:00 PT" or ""
+    corrected: bool           # was the user's date different from real?
+    user_match_date: date     # what the user originally said
+    note: str                 # grounding note (correction / non-Vancouver / etc.)
+
+
+def ground_match(match_name: str, user_match_date: date, check_in: date, check_out: date) -> GroundedTrip | None:
+    """Ground a trip's match against verified fixtures.
+
+    Returns a ``GroundedTrip`` with the REAL date + venue/kickoff and a UI note,
+    or ``None`` when the matchup isn't recognized (caller should clarify).
+    Keeps the trip's original length (nights) but re-centers it on the real date.
+    """
+    res = resolve_match(match_name)
+    if not res.fixture:
+        return None  # unrecognized — caller uses res.note to clarify
+
+    fx = res.fixture
+    nights = max(1, (check_out - check_in).days)
+    # Preserve the user's trip LENGTH but make sure the real match is inside the
+    # window. If their stated dates already cover the real match, keep them; if
+    # not (e.g. "Canada vs Qatar, June 26-29" — the real match is June 18),
+    # re-bracket around the real date keeping the same number of nights and
+    # arriving the day before the match. Avoids silently stretching a 3-night
+    # trip into an 11-night one just to absorb a date correction.
+    if check_in <= fx.match_date <= check_out:
+        real_ci, real_co = check_in, check_out
+    else:
+        lead = min(nights - 1, 1)  # arrive 1 day before the match (same-day if 1 night)
+        real_ci = fx.match_date - timedelta(days=lead)
+        real_co = real_ci + timedelta(days=nights)
+
+    corrected = fx.match_date != user_match_date
+    note = ""
+    if corrected:
+        note = (
+            f"{fx.match} is on {fx.match_date:%A %b %-d}, {fx.match_date.year} at "
+            f"{fx.venue} (you said {user_match_date:%b %-d}) — I've planned your trip around the real date."
+        )
+    if not res.in_vancouver:
+        note += (
+            f" Heads up: {fx.match} is in {fx.city} ({fx.venue}), not Vancouver. "
+            "MatchDay plans Vancouver / BC Place trips."
+        )
+    return GroundedTrip(
+        match_name=fx.match, match_date=fx.match_date, check_in=real_ci,
+        check_out=real_co, venue=fx.venue, city=fx.city, kickoff=fx.kickoff,
+        corrected=corrected, user_match_date=user_match_date, note=note.strip(),
+    )
+
+
+def vancouver_fixtures() -> list[Fixture]:
+    """All verified fixtures at BC Place, Vancouver (the app's home venue)."""
+    return [f for f in _FIXTURES if f.city.lower() == "vancouver"]