Upload folder using huggingface_hub

app.py

@@ -30,7 +30,7 @@ from fastapi.responses import HTMLResponse  # noqa: E402
 from gradio import Server  # noqa: E402
 
 from matchday.agent import MatchDayAgent  # noqa: E402
-from matchday.agent_loop import BuildTripPackagesArgs  # noqa: E402
+from matchday.agent_loop import run_agent_loop  # noqa: E402
 from matchday.intent import parse_intent  # noqa: E402
 from matchday.models import TripRequest  # noqa: E402
 from matchday.prompts import EXPLANATION_HINT  # noqa: E402
@@ -97,18 +97,6 @@ async def _pulse(coro, holder, message, interval: int = 9):
         yield _ev(type="commentary", text=f"{message} ({int(time.monotonic() - start)}s)")
 
 
-def _args_to_trip(a: BuildTripPackagesArgs) -> TripRequest:
-    return TripRequest(
-        origin_airport=a.origin_airport,
-        match_name=a.match_name or "the match",
-        match_date=date.fromisoformat(a.match_date),
-        check_in=date.fromisoformat(a.check_in),
-        check_out=date.fromisoformat(a.check_out),
-        travelers=a.travelers,
-        budget_tier=a.budget_tier,
-    )
-
-
 async def _agent_explain(agent, user_text: str, trip: TripRequest, result) -> str:
     """Round 2 — Nemotron compares the packages. Best-effort ('' on failure)."""
     args_json = json.dumps(trip.model_dump(mode="json"))
@@ -157,70 +145,108 @@ async def plan_trip(user_text: str) -> str:
         except Exception as exc:
             logger.warning("agent init failed (%s); deterministic path.", exc)
 
-    # Round 1 — Nemotron decides which tool to call.
-    r1: dict = {"tool_calls": []}
-    if agent is not None:
-        yield _ev(type="commentary", text="🤖 Nemotron is choosing your best options…")
-        h1 = {}
-        try:
-            async for beat in _pulse(
-                agent.run([{"role": "user", "content": user_text}]),
-                h1,
-                "🤖 Nemotron is choosing your best options…",
-            ):
-                yield beat
-            r1 = h1["result"]
-        except Exception as exc:
-            logger.warning("agent round 1 failed (%s).", exc)
-            r1 = {"tool_calls": []}
-
-    # Resolve a validated trip: Nemotron's args first, then deterministic parse.
-    tool_calls = r1.get("tool_calls") or []
+    # ── Smart path: the bounded agent loop (K1). Nemotron UNDERSTANDS the
+    # request, may GROUND itself with web_search (I6), may CLARIFY to capture
+    # intent (P7), and calls build_trip_packages when ready. The loop validates
+    # args, dedups, and self-corrects one malformed call (A4). No more bypass.
+    messages: list[dict] = [{"role": "user", "content": user_text}]
     trip: TripRequest | None = None
-    if tool_calls and tool_calls[0].get("name") == "build_trip_packages":
-        try:
-            trip = _args_to_trip(
-                BuildTripPackagesArgs.model_validate(tool_calls[0].get("arguments", {}))
-            )
-        except Exception:
-            trip = None
-    if trip is None:
+    result = None          # TripPackageResult produced inside the loop's build call
+    agent_text = ""        # a clarify question or direct answer from the Brain
+
+    if agent is not None:
+        yield _ev(type="commentary", text="🧠 Nemotron is understanding your request…")
+        for attempt in range(3):  # cap grounding rounds (web_search → build)
+            h = {}
+            try:
+                async for beat in _pulse(
+                    run_agent_loop(agent, messages),
+                    h,
+                    "🧠 Nemotron is understanding your request & choosing tools",
+                ):
+                    yield beat
+                res = h.get("result")
+            except Exception as exc:
+                logger.warning("agent loop attempt %d failed (%s).", attempt, exc)
+                res = None
+
+            if res is None:
+                break
+
+            if res.type == "tool_called" and res.tool == "build_trip_packages":
+                result = res.result.get("full_result")
+                trip = res.result.get("trip")
+                break
+
+            if res.type == "tool_called" and res.tool == "web_search":
+                # Brain grounded itself — thread the result back so it can build.
+                tcid = f"call_ws_{attempt}"
+                messages.append({
+                    "role": "assistant", "content": "",
+                    "tool_calls": [{
+                        "id": tcid, "type": "function",
+                        "function": {
+                            "name": "web_search",
+                            "arguments": json.dumps(res.result.get("query") or {}),
+                        },
+                    }],
+                })
+                messages.append({
+                    "role": "tool", "tool_call_id": tcid, "name": "web_search",
+                    "content": json.dumps(res.result, ensure_ascii=False)[:1200],
+                })
+                yield _ev(
+                    type="commentary",
+                    text="🔎 Grounded with a web search — now building your packages…",
+                )
+                continue
+
+            if res.type == "final_answer":
+                agent_text = res.text or ""
+                break
+            # fallback_to_deterministic → drop through to the deterministic path
+            break
+
+    # ── 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:
         parsed = parse_intent(user_text)
-        if parsed.trip_request is not None:
-            trip = parsed.trip_request
-
-    if trip is None:
-        clarify_q = ""
-        if tool_calls and tool_calls[0].get("name") == "clarify":
-            clarify_q = tool_calls[0].get("arguments", {}).get("question", "")
-        if not clarify_q:
-            clarify_q = parse_intent(user_text).question
-        yield _ev(
-            type="clarify",
-            text=clarify_q
-            or "Tell me where you're flying from and which match you want to see.",
-        )
-        return
+        trip = parsed.trip_request
+        if trip is not None:
+            yield _ev(type="greenlight", text=trip.summary())
+            yield _ev(
+                type="commentary",
+                text="✈️ Scanning airlines · 🏨 Finding hotels near BC Place · 🌤️ Checking the match-day forecast…",
+            )
+            hb = {}
+            try:
+                async for beat in _pulse(
+                    build_trip_packages(trip),
+                    hb,
+                    "✈️ Scanning airlines · 🏨 hotels near BC Place · 🌤️ weather",
+                ):
+                    yield beat
+                result = hb["result"]
+            except Exception as exc:
+                yield _ev(type="error", text=f"⚠️ {exc}")
+                return
+        else:
+            yield _ev(
+                type="clarify",
+                text=parsed.question
+                or "Tell me where you're flying from and which match you want to see.",
+            )
+            return
 
-    yield _ev(type="greenlight", text=trip.summary())
-    yield _ev(
-        type="commentary",
-        text="✈️ Scanning airlines · 🏨 Finding hotels near BC Place · 🌤️ Checking the match-day forecast…",
-    )
-    hb = {}
-    try:
-        async for beat in _pulse(
-            build_trip_packages(trip),
-            hb,
-            "✈️ Scanning airlines · 🏨 hotels near BC Place · 🌤️ weather",
-        ):
-            yield beat
-        result = hb["result"]
-    except Exception as exc:
-        yield _ev(type="error", text=f"⚠️ {exc}")
+    # Clarify / direct answer from the Brain (no packages to show).
+    if result is None:
+        yield _ev(type="clarify", text=agent_text)
         return
 
-    yield _ev(type="commentary", text="🗺️ Scoring 3 packages — Nemotron is writing your comparison…")
+    # ── Render. greenlight confirms the captured intent just before the packages.
+    if trip is not None:
+        yield _ev(type="greenlight", text=trip.summary())
+    yield _ev(type="commentary", text="🗺️ Nemotron is comparing your 3 packages…")
     explanation = ""
     if agent is not None:
         he = {}
@@ -228,7 +254,7 @@ async def plan_trip(user_text: str) -> str:
             async for beat in _pulse(
                 _agent_explain(agent, user_text, trip, result),
                 he,
-                "🗺️ Scoring 3 packages — Nemotron is writing your comparison…",
+                "🗺️ Nemotron is comparing your 3 packages…",
             ):
                 yield beat
             explanation = he["result"]

matchday/agent.py

@@ -22,6 +22,7 @@ from typing import Any
 import modal
 
 from matchday.agent_loop import BuildTripPackagesArgs, ClarifyArgs, WebSearchArgs
+from matchday.errors import classify_error
 from matchday.prompts import build_system_prompt
 
 # The Modal app name (must match `modal.App("matchday-spike")` in modal_spike.py
@@ -116,8 +117,15 @@ class MatchDayAgent:
                 enable_thinking=self._thinking,
             )
         except Exception as exc:
-            logger.error("Nemotron generate failed: %s", exc)
-            return {"tool_calls": [], "text": ""}
+            # Classify (N29) instead of swallowing to an opaque empty result.
+            # Re-raise so the AgentLoop can degrade gracefully (fallback to the
+            # deterministic parser); the classified reason is logged here.
+            classified = classify_error(exc)
+            logger.error(
+                "Nemotron generate failed: %s (reason=%s, retryable=%s, degrade=%s)",
+                exc, classified.reason.value, classified.retryable, classified.should_degrade,
+            )
+            raise
 
         return {"tool_calls": _parse_tool_calls(msg), "text": msg.get("content") or ""}
 

matchday/agent_loop.py

@@ -196,9 +196,12 @@ async def _build_trip_packages(
 ) -> dict[str, Any]:
     """Execute the build_trip_packages tool.
 
-    Dispatches to all enabled API normalizers via the registry, then runs
-    the deterministic scoring engine to produce the top 3 ScoredPackage
-    objects.
+    Routes through the canonical ``trip_tool.build_trip_packages`` (U1 parallel
+    gather + K4 scoring) -- no dispatch duplication -- and returns BOTH the
+    compact packages (for the Brain's context) AND the full ``TripPackageResult``
+    (stashed as ``full_result``) plus the resolved ``TripRequest`` (as ``trip``)
+    so the caller (app.py) can render the cards / map / timeline without
+    re-running the searches.
 
     Parameters
     ----------
@@ -208,124 +211,67 @@ async def _build_trip_packages(
     Returns
     -------
     dict[str, Any]
-        A compact result dict with packages, or an error key.
+        ``{tool, success, packages(compact), full_result, trip}`` or an error.
     """
-    from matchday.scoring import score_options
-    from matchday.models import Flight, Hotel, Weather
-
-    # Determine which normalizers are available
-    normalizer_names = registry.get_enabled_normalizers(category="full_trip")
-    if not normalizer_names:
-        # Fall back to individual categories
-        flight_names = registry.get_enabled_normalizers(category="flights")
-        hotel_names = registry.get_enabled_normalizers(category="hotels")
-        weather_names = registry.get_enabled_normalizers(category="weather")
-        amenity_names = registry.get_enabled_normalizers(category="amenities")
-    else:
-        flight_names = [n for n in normalizer_names if n in registry.get_enabled_normalizers(category="flights")]
-        hotel_names = [n for n in normalizer_names if n in registry.get_enabled_normalizers(category="hotels")]
-        weather_names = [n for n in normalizer_names if n in registry.get_enabled_normalizers(category="weather")]
-        amenity_names = [n for n in normalizer_names if n in registry.get_enabled_normalizers(category="amenities")]
-
-    # Build dispatch params
     from datetime import date
 
-    match_date = date.fromisoformat(validated_args["match_date"])
-    check_in = date.fromisoformat(validated_args["check_in"])
-    check_out = date.fromisoformat(validated_args["check_out"])
+    from matchday.models import TripRequest
+    from matchday.trip_tool import build_trip_packages
 
-    params: dict[str, dict[str, Any]] = {}
-    for fn in flight_names:
-        params[fn] = {
-            "origin": validated_args["origin_airport"],
-            "destination": "YVR",
-            "departure_date": validated_args["match_date"],
-        }
-    for hn in hotel_names:
-        params[hn] = {
-            "check_in_date": validated_args["check_in"],
-            "check_out_date": validated_args["check_out"],
-        }
-    for wn in weather_names:
-        params[wn] = {
-            "latitude": 49.2827,
-            "longitude": -123.1207,
-            "start_date": validated_args["check_in"],
-            "end_date": validated_args["check_out"],
-        }
-    for an in amenity_names:
-        params[an] = {
-            "latitude": 49.2827,
-            "longitude": -123.1207,
-            "radius_km": 1.0,
-        }
-
-    # Dispatch all enabled normalizers concurrently
-    tasks: dict[str, asyncio.Task[Any]] = {}
-    for normalizer_name in flight_names + hotel_names + weather_names + amenity_names:
-        p = params.get(normalizer_name, {})
-        tasks[normalizer_name] = asyncio.create_task(
-            registry.dispatch(normalizer_name, p)
+    # Resolve a validated TripRequest from the tool arguments.
+    try:
+        args = BuildTripPackagesArgs.model_validate(validated_args)
+        trip = TripRequest(
+            origin_airport=args.origin_airport,
+            match_name=args.match_name or "the match",
+            match_date=date.fromisoformat(args.match_date),
+            check_in=date.fromisoformat(args.check_in),
+            check_out=date.fromisoformat(args.check_out),
+            travelers=args.travelers,
+            budget_tier=args.budget_tier,
         )
+    except Exception as exc:  # invalid args -> graceful error back to the Brain
+        logger.warning("build_trip_packages arg resolution failed: %s", exc)
+        return {
+            "tool": "build_trip_packages",
+            "success": False,
+            "reason": f"Invalid trip arguments: {exc}",
+            "packages": [],
+            "full_result": None,
+            "trip": None,
+        }
 
-    results: dict[str, Any] = {}
-    for normalizer_name, task in tasks.items():
-        try:
-            api_result = await asyncio.wait_for(task, timeout=PER_TOOL_TIMEOUT_SECONDS)
-            results[normalizer_name] = api_result
-        except asyncio.TimeoutError:
-            logger.warning("Normalizer %s timed out after %ss", normalizer_name, PER_TOOL_TIMEOUT_SECONDS)
-            results[normalizer_name] = None
-        except Exception as exc:
-            logger.warning("Normalizer %s failed: %s", normalizer_name, exc)
-            results[normalizer_name] = None
-
-    # Collect flights, hotels, weather from API results
-    flights: list[Flight] = []
-    hotels: list[Hotel] = []
-    weather_list: list[Weather] = []
-
-    for fn in flight_names:
-        r = results.get(fn)
-        if r is not None and r.success and isinstance(r.data, list):
-            flights.extend(r.data)
-
-    for hn in hotel_names:
-        r = results.get(hn)
-        if r is not None and r.success and isinstance(r.data, list):
-            hotels.extend(r.data)
-
-    for wn in weather_names:
-        r = results.get(wn)
-        if r is not None and r.success:
-            data = r.data
-            if isinstance(data, list):
-                weather_list.extend(data)
-
-    # Run deterministic scoring
-    packages = score_options(
-        flights=flights,
-        hotels=hotels,
-        weather=weather_list,
-        match_date=match_date,
-        budget_tier=validated_args.get("budget_tier", "mid_range"),
-    )
+    # Single canonical dispatch + scoring path.
+    try:
+        full = await build_trip_packages(trip)
+    except Exception as exc:
+        logger.warning("build_trip_packages failed: %s", exc)
+        return {
+            "tool": "build_trip_packages",
+            "success": False,
+            "reason": str(exc),
+            "packages": [],
+            "full_result": None,
+            "trip": trip,
+        }
 
-    if not packages:
+    if not full.packages:
         return {
             "tool": "build_trip_packages",
             "success": False,
             "reason": "No valid trip packages could be formed with the available data.",
             "packages": [],
+            "full_result": full,
+            "trip": trip,
         }
 
-    # Serialise packages compactly
-    compact_packages = [_compact_package(pkg) for pkg in packages]
-
+    compact_packages = [_compact_package(pkg) for pkg in full.packages]
     return {
         "tool": "build_trip_packages",
         "success": True,
         "packages": compact_packages,
+        "full_result": full,
+        "trip": trip,
     }
 
 

matchday/prompts.py

@@ -53,14 +53,21 @@ World Cup context:
 
 _TOOL_GUIDANCE = """\
 Tool-use rules:
-- DEFAULT TO ACTION. If the user names a departure city or airport, a match, and
-  any date, call `build_trip_packages` immediately — do NOT clarify. This single
-  tool runs all searches in parallel and returns 3 scored packages. Only call
-  `clarify` if the origin OR the date is entirely absent.
-- Do NOT call a tool you already called with identical arguments this turn.
-- Do NOT call `web_search` for prices, flights, hotels, or weather — those come
-  from `build_trip_packages`. Use `web_search` only for supplemental context
-  (a kick-off time, a venue policy) the other tools don't provide.
+- UNDERSTAND FIRST, THEN ACT. Read what the traveler actually wants before
+  calling a tool. Capture their intent: the origin city/airport, the match,
+  the dates, the budget, the vibe.
+- If the request is clear (you can infer an origin, a match, and at least one
+  date), call `build_trip_packages` right away — it runs all searches in
+  parallel and returns 3 scored packages.
+- You MAY use `web_search` (restricted to fifa.com, vancouverfwc26.ca,
+  bcplace.com, translink.ca) to GROUND your understanding — e.g. confirm a
+  match exists on the date, or find a kickoff time / venue rule the other
+  tools don't provide. Do NOT use it for prices, flights, hotels, or weather;
+  those come from `build_trip_packages`.
+- If the origin OR the date is genuinely missing or ambiguous, call `clarify`
+  with ONE specific, friendly question (offer concrete options, e.g. "Flying
+  from Montreal (YUL) or Toronto (YYZ)?"). Do not over-clarify a clear request.
+- Do not call a tool you already called with identical arguments this turn.
 - When you have the packages, write a concise comparison: name each package's
   strength (Cheapest / Safest Arrival / Closest to Stadium), cite the real
   prices from the tool, note any 'example' (non-live) data, and end with a

matchday/scoring.py

@@ -31,6 +31,7 @@ from datetime import date, datetime, timezone
 from typing import Literal
 from zoneinfo import ZoneInfo
 
+from matchday.errors import FailoverReason
 from matchday.models import Flight, Hotel, ScoredPackage, Weather
 
 
@@ -247,6 +248,7 @@ def score_options(
     weather: list[Weather],
     match_date: date,
     budget_tier: str = "mid_range",
+    reason_out: list | None = None,
 ) -> list[ScoredPackage]:
     """Score and rank travel packages from candidate flights and hotels.
 
@@ -303,6 +305,8 @@ def score_options(
 
     # -- Edge case: no flights ----------------------------------------------
     if not flights:
+        if reason_out is not None:
+            reason_out.append(FailoverReason.SCORING_EMPTY)
         return []
 
     # -- Filter late arrivals -----------------------------------------------
@@ -311,6 +315,8 @@ def score_options(
 
     # -- Edge case: all flights are late ------------------------------------
     if not on_time_flights:
+        if reason_out is not None:
+            reason_out.append(FailoverReason.SCORING_ALL_LATE)
         return []
 
     # -- Build all valid (flight, hotel) combinations -----------------------
@@ -331,6 +337,8 @@ def score_options(
 
     # -- Edge case: all prices are None -------------------------------------
     if not scored:
+        if reason_out is not None:
+            reason_out.append(FailoverReason.SCORING_MISSING_PRICES)
         return []
 
     # -- Normalise each dimension -------------------------------------------

matchday/trip_tool.py

@@ -386,13 +386,20 @@ async def build_trip_packages(trip_request: TripRequest) -> TripPackageResult:
     if weather_data is None:
         weather_data = []
 
+    score_reason: list = []
     scored_packages = scoring.score_options(
         flights=flights_data,
         hotels=hotels_data,
         weather=weather_data,
         match_date=trip_request.match_date,
         budget_tier=trip_request.budget_tier,
+        reason_out=score_reason,
     )
+    if not scored_packages and score_reason:
+        # Surface the SCORING_* taxonomy reason (N15) instead of an opaque
+        # 'failed' status, so the user learns WHY no packages could be formed
+        # (e.g. all flights land after kickoff vs. flights API was down).
+        degradation_notices.append(user_message_for(score_reason[0]))
 
     # ------------------------------------------------------------------
     # 5. Attach amenities to scored packages