Upload folder using huggingface_hub

README.md

@@ -1,13 +1,65 @@
 ---
-title: Matchday
-emoji: 🐠
+title: MatchDay
+emoji: ⚽
 colorFrom: blue
-colorTo: pink
+colorTo: green
 sdk: gradio
-sdk_version: 6.18.0
-python_version: '3.13'
+sdk_version: "5.0"
 app_file: app.py
-pinned: false
+pinned: true
+license: mit
+tags:
+  - build-small-hackathon
+  - backyard-ai
+  - agents
+  - react-agent
+  - tool-use
+  - nemotron
+  - nvidia
+  - modal
+  - gradio
+  - fifa-world-cup-2026
+  - travel
+models:
+  - nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-BF16
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# MatchDay ⚽ — 2026 FIFA World Cup, Vancouver
+
+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.**
+
+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.
+
+## 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 · Modal (A100-80GB, SGLang v0.5.12) · Gradio · SerpApi
+(Google Flights/Hotels/Search) · Open-Meteo · OpenStreetMap · httpx/Pydantic v2.
+
+## Built for Build Small
+Track: **Backyard AI.** Targeting: 🟩 NVIDIA Nemotron Quest · 🟢 Modal Awards ·
+🤖 Best Agent · 🎨 Off-Brand (custom UI) · 📡 Sharing-is-Caring (agent trace on the
+Hub) · 📓 Field Notes. **Sponsor tools used: Nemotron-3-Nano-30B (NVIDIA) + Modal.**
+
+> Tag strings above are best-guess HF literals — confirm against the official
+> Build Small submission form before submitting.

app.py

@@ -0,0 +1,16 @@
+"""HF Space entry point — delegates to the MatchDay Gradio app.
+
+Hugging Face Spaces run this file and serve the module-level ``demo`` (a
+``gr.Blocks``). The real app lives in ``matchday/app.py``; this thin wrapper
+just makes the repo root Space-compatible.
+"""
+import os
+import sys
+
+# Ensure the repo root is importable when the Space runs this file.
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from matchday.app import demo  # noqa: E402,F401  (re-exported for the Space)
+
+if __name__ == "__main__":
+    demo.launch()

matchday/__init__.py

@@ -0,0 +1,28 @@
+"""MatchDay — AI trip planner for the 2026 FIFA World Cup in Vancouver.
+
+Brain + Hands architecture: Nemotron-3-Nano-30B-A3B (the brain) selects tools
+and writes explanations; Python (the hands) executes every API call and scores
+every price deterministically. The LLM never calls an API or computes a price.
+
+Package layout
+--------------
+models.py        Pydantic v2 domain schemas (the structured trip object).
+scoring.py       Deterministic package ranking (min-max + tiered weights).
+errors.py        FailoverReason taxonomy + classify_error + retry/backoff.
+api_registry.py  Self-registering normalizer registry + dispatch + gating.
+trip_tool.py     build_trip_packages composite (parallel dispatch + scoring).
+agent_loop.py    Bounded ReAct loop (Nemotron picks tools, Python runs them).
+prompts.py       System-prompt assembly (3 tiers + behavior preset).
+modal_spike.py   Nemotron-on-A100/SGLang Modal serving engine (remote only).
+apis/            Concrete API normalizers — registered on import.
+
+Normalizer registration is a side effect of importing ``matchday.apis`` (each
+``@register_api`` decorator runs at module load). Consumers that need dispatch
+to work must ``import matchday.apis`` first.
+"""
+
+# Intentionally no re-exports here: importing submodules from the package root
+# would risk circular imports (several submodules import each other). Import the
+# specific submodule you need, e.g. ``from matchday.models import TripRequest``.
+
+__version__ = "0.1.0"

matchday/agent.py

@@ -0,0 +1,142 @@
+"""The Nemotron agent (the Brain) — calls Modal SGLang with tools, returns
+parsed tool_calls.
+
+This is the ``agent`` object ``AgentLoop`` expects: an async ``run(messages)``
+returning ``{"tool_calls": [...], "text": str}``. It builds the OpenAI ``tools``
+array from the agent_loop argument schemas, prepends the system prompt, and
+calls ``Server.generate.remote.aio`` (Nemotron-3-Nano-30B on Modal A100).
+
+N13 (resolved): SGLang v0.5.12 + ``--tool-call-parser qwen3_coder`` +
+``--reasoning-parser nemotron_3`` emits structured ``tool_calls`` that this
+class parses. Nemotron decides; Python executes (Brain + Hands).
+
+Requires the Modal app to be deployed (``modal deploy matchday/modal_spike.py``)
+so ``Server().generate.remote()`` resolves from any client.
+"""
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any
+
+import modal
+
+from matchday.agent_loop import BuildTripPackagesArgs, ClarifyArgs, WebSearchArgs
+from matchday.prompts import build_system_prompt
+
+# The Modal app name (must match `modal.App("matchday-spike")` in modal_spike.py
+# and the `modal deploy` target). The 30B model runs remotely; this client only
+# needs the deployed handle — it never imports the serving code.
+_MODAL_APP = "matchday-spike"
+_MODAL_CLASS = "Server"
+
+logger = logging.getLogger(__name__)
+
+# OpenAI-style tool definitions. Parameters come from the Pydantic arg schemas
+# (single source of truth — the same schemas AgentLoop validates against).
+TOOL_SPECS: list[dict[str, Any]] = [
+    {
+        "type": "function",
+        "function": {
+            "name": "build_trip_packages",
+            "description": (
+                "Build 3 ranked, scored trip packages (flights, hotels, weather, "
+                "nearby spots) for a FIFA 2026 Vancouver trip. Use when the user "
+                "has given an origin, a match, and a date. Returns Cheapest / "
+                "Safest Arrival / Closest-to-Stadium packages with real prices."
+            ),
+            "parameters": BuildTripPackagesArgs.model_json_schema(),
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "clarify",
+            "description": (
+                "Ask the user ONE clarifying question when a required trip slot "
+                "(origin, match, or date) is missing and cannot be inferred."
+            ),
+            "parameters": ClarifyArgs.model_json_schema(),
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "web_search",
+            "description": (
+                "Search the web for supplemental FIFA/Vancouver context (kick-off "
+                "times, venue policies). NOT for prices, flights, hotels, or "
+                "weather — those come from build_trip_packages."
+            ),
+            "parameters": WebSearchArgs.model_json_schema(),
+        },
+    },
+]
+
+# Tool-calling sampling (NVIDIA model card): temp 0.6 / top_p 0.95.
+_TOOL_TEMPERATURE = 0.6
+_TOOL_TOP_P = 0.95
+_TOOL_MAX_TOKENS = 2048
+
+
+class MatchDayAgent:
+    """Nemotron-on-Modal wrapper presenting the ``async run(messages)`` contract.
+
+    Stateless across turns beyond the cached ``Server`` proxy and system prompt;
+    the AgentLoop owns conversation history.
+    """
+
+    def __init__(self, *, thinking: bool = False) -> None:
+        # Reference the DEPLOYED Modal app by name: a fresh client process (the
+        # Gradio app) cannot call .remote() on a bare imported class — the app
+        # must be looked up. Requires `modal deploy matchday/modal_spike.py`.
+        self._server = modal.Cls.from_name(_MODAL_APP, _MODAL_CLASS)()
+        self._system_prompt = build_system_prompt()
+        self._thinking = thinking
+
+    async def run(self, messages: list[dict], *, tools: list[dict] | None = None) -> dict[str, Any]:
+        """Call Nemotron; return ``{"tool_calls": [...], "text": str}``.
+
+        ``messages`` is the live conversation (user/assistant/tool roles) WITHOUT
+        the system prompt — this class prepends it. ``tools=None`` uses the
+        default ``TOOL_SPECS``; pass ``tools=[]`` to disable tool-calling (e.g.
+        the final explanation turn, where Nemotron must write text, not call a
+        tool). On any inference failure, returns empty tool_calls + empty text so
+        the caller can fall back.
+        """
+        eff_tools = TOOL_SPECS if tools is None else tools
+        full = [{"role": "system", "content": self._system_prompt}, *messages]
+        try:
+            msg: dict[str, Any] = await self._server.generate.remote.aio(
+                full,
+                tools=eff_tools,
+                temperature=_TOOL_TEMPERATURE,
+                top_p=_TOOL_TOP_P,
+                max_tokens=_TOOL_MAX_TOKENS,
+                enable_thinking=self._thinking,
+            )
+        except Exception as exc:
+            logger.error("Nemotron generate failed: %s", exc)
+            return {"tool_calls": [], "text": ""}
+
+        return {"tool_calls": _parse_tool_calls(msg), "text": msg.get("content") or ""}
+
+
+def _parse_tool_calls(msg: dict[str, Any]) -> list[dict[str, Any]]:
+    """Normalize SGLang tool_calls into ``{name, arguments, id}`` dicts."""
+    out: list[dict[str, Any]] = []
+    for tc in msg.get("tool_calls") or []:
+        fn = tc.get("function") or {}
+        raw_args = fn.get("arguments", "{}")
+        if isinstance(raw_args, str):
+            try:
+                args = json.loads(raw_args) if raw_args.strip() else {}
+            except json.JSONDecodeError:
+                logger.warning("Malformed tool_call arguments: %r", raw_args)
+                args = {}
+        elif isinstance(raw_args, dict):
+            args = raw_args
+        else:
+            args = {}
+        out.append({"name": fn.get("name", ""), "arguments": args, "id": tc.get("id", "")})
+    return out

matchday/agent_loop.py

@@ -0,0 +1,1076 @@
+"""
+MatchDay -- Bounded Nemotron agent loop with controlled tool use.
+
+Architecture (per Codex recommendation):
+- Maximum 2 tool rounds (Nemotron calls a tool -> result returned -> one more
+  turn to maybe call a second tool or produce final answer).
+- Tool-name allowlist: ["build_trip_packages", "web_search", "clarify"]
+- Pydantic argument validation before every tool call
+- Duplicate-call detection (same tool + same args in same turn)
+- One malformed-call correction attempt (send error back to Nemotron)
+- Per-tool timeout (30s default)
+- Controlled fallback: if agent loop fails, fall back to deterministic
+  intent extraction
+- Compact tool results (below 2,000 tokens total)
+
+Returns:
+    {"type": "tool_called", "tool": str, "result": dict}
+    {"type": "final_answer", "text": str}
+    {"type": "fallback_to_deterministic", "reason": str}
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field, field_validator
+
+from matchday.api_registry import registry
+from matchday.models import ScoredPackage
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+MAX_TOOL_ROUNDS: int = 5
+"""Maximum number of tool-call rounds Nemotron gets before we force a final
+answer or fall back to deterministic extraction. A ceiling, not a target —
+happy-path turns exit at 2-3 rounds (Nemotron calls build_trip_packages, then
+explains). 5 fits the hard path (4 tool rounds + 1 explain) with the grace call
+as a safety net; reference agents cap far higher (hermes 90, deepagents 9999)."""
+
+PER_TOOL_TIMEOUT_SECONDS: float = 30.0
+"""Timeout per individual tool execution."""
+
+MAX_RESULT_TOKENS: int = 2_000
+"""Upper bound on the tool-result string fed back to the model. Tool results
+longer than this are aggressively truncated."""
+
+ALLOWED_TOOLS: frozenset[str] = frozenset(
+    {"build_trip_packages", "web_search", "clarify"}
+)
+"""The only tool names Nemotron may call."""
+
+
+# ---------------------------------------------------------------------------
+# Pydantic schemas for tool arguments
+# ---------------------------------------------------------------------------
+
+
+class BuildTripPackagesArgs(BaseModel):
+    """Arguments for the build_trip_packages tool.
+
+    This tool assembles scored travel packages by dispatching to all enabled
+    API normalizers, then running the deterministic scoring engine. Nemotron
+    passes the TripRequest slots; the tool returns the top 3 ScoredPackage
+    objects.
+    """
+
+    origin_airport: str = Field(
+        ..., description="3-letter IATA departure airport code (e.g. YUL)"
+    )
+    match_date: str = Field(
+        ..., description="Match date in YYYY-MM-DD format"
+    )
+    check_in: str = Field(
+        ..., description="Hotel check-in date in YYYY-MM-DD format"
+    )
+    check_out: str = Field(
+        ..., description="Hotel check-out date in YYYY-MM-DD format"
+    )
+    travelers: int = Field(default=1, ge=1, le=6, description="Number of travelers")
+    budget_tier: str = Field(
+        default="mid_range",
+        pattern=r"^(budget|mid_range|premium)$",
+        description="Budget tier: budget, mid_range, or premium",
+    )
+    match_name: str = Field(
+        default="", description="Human-readable match description (optional)"
+    )
+
+    @field_validator("origin_airport")
+    @classmethod
+    def _normalize_airport(cls, v: str) -> str:
+        cleaned = v.strip().upper()
+        if len(cleaned) != 3 or not cleaned.isalpha():
+            raise ValueError(
+                f"Invalid airport code: {v!r}. Must be a 3-letter IATA code."
+            )
+        return cleaned
+
+
+class WebSearchArgs(BaseModel):
+    """Arguments for the web_search tool.
+
+    Nemotron uses this to fetch supplemental data (match schedule details,
+    venue info, current events near the travel date).
+    """
+
+    query: str = Field(..., min_length=1, description="Search query string")
+    max_results: int = Field(default=5, ge=1, le=10, description="Max results to return")
+
+
+class ClarifyArgs(BaseModel):
+    """Arguments for the clarify tool.
+
+    Nemotron uses this to ask the user a clarifying question when intent is
+    ambiguous. The assistant presents the question to the user and waits for
+    a response.
+    """
+
+    question: str = Field(
+        ..., min_length=1, description="Clarifying question for the user"
+    )
+
+
+# ---------------------------------------------------------------------------
+# Argument parser registry
+# ---------------------------------------------------------------------------
+
+_TOOL_ARG_SCHEMAS: dict[str, type[BaseModel]] = {
+    "build_trip_packages": BuildTripPackagesArgs,
+    "web_search": WebSearchArgs,
+    "clarify": ClarifyArgs,
+}
+
+
+def _parse_tool_args(tool_name: str, raw_args: dict[str, Any]) -> dict[str, Any]:
+    """Validate and parse tool arguments using the registered Pydantic schema.
+
+    Parameters
+    ----------
+    tool_name:
+        The tool name that Nemotron wants to call.
+    raw_args:
+        The raw arguments dict emitted by the model.
+
+    Returns
+    -------
+    dict[str, Any]
+        Validated arguments as a plain dict.
+
+    Raises
+    ------
+    ValueError
+        If the tool name is unknown or validation fails.
+    """
+    schema = _TOOL_ARG_SCHEMAS.get(tool_name)
+    if schema is None:
+        raise ValueError(
+            f"No argument schema registered for tool {tool_name!r}. "
+            f"Known tools: {list(_TOOL_ARG_SCHEMAS)}"
+        )
+    validated = schema.model_validate(raw_args)
+    return validated.model_dump()
+
+
+# ---------------------------------------------------------------------------
+# Duplicate-call detection
+# ---------------------------------------------------------------------------
+
+
+def _call_key(tool_name: str, args: dict[str, Any]) -> str:
+    """Deterministic key for a (tool_name, args) pair used in duplicate detection.
+
+    Args are serialised with sorted keys so that two calls with the same
+    semantic arguments produce the same key regardless of key ordering.
+    """
+    return f"{tool_name}:{json.dumps(args, sort_keys=True, default=str)}"
+
+
+# ---------------------------------------------------------------------------
+# Tool implementation
+# ---------------------------------------------------------------------------
+
+
+async def _build_trip_packages(
+    validated_args: dict[str, Any],
+) -> 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.
+
+    Parameters
+    ----------
+    validated_args:
+        Pre-validated argument dict from ``BuildTripPackagesArgs``.
+
+    Returns
+    -------
+    dict[str, Any]
+        A compact result dict with packages, or an error key.
+    """
+    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"])
+
+    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)
+        )
+
+    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"),
+    )
+
+    if not packages:
+        return {
+            "tool": "build_trip_packages",
+            "success": False,
+            "reason": "No valid trip packages could be formed with the available data.",
+            "packages": [],
+        }
+
+    # Serialise packages compactly
+    compact_packages = [_compact_package(pkg) for pkg in packages]
+
+    return {
+        "tool": "build_trip_packages",
+        "success": True,
+        "packages": compact_packages,
+    }
+
+
+async def _web_search(validated_args: dict[str, Any]) -> dict[str, Any]:
+    """Execute the web_search tool.
+
+    Delegates to the SerpApi web search normalizer registered in the API
+    registry. If no web search normalizer is enabled, returns a graceful
+    error rather than crashing.
+
+    Parameters
+    ----------
+    validated_args:
+        Pre-validated argument dict from ``WebSearchArgs``.
+
+    Returns
+    -------
+    dict[str, Any]
+        Compact search results.
+    """
+    web_search_names = registry.get_enabled_normalizers(category="web_search")
+    if not web_search_names:
+        return {
+            "tool": "web_search",
+            "success": False,
+            "reason": "Web search is not available (no API key configured).",
+            "results": [],
+        }
+
+    name = web_search_names[0]
+    params = {
+        "query": validated_args["query"],
+        "max_results": validated_args.get("max_results", 5),
+    }
+
+    try:
+        api_result = await asyncio.wait_for(
+            registry.dispatch(name, params),
+            timeout=PER_TOOL_TIMEOUT_SECONDS,
+        )
+    except asyncio.TimeoutError:
+        return {
+            "tool": "web_search",
+            "success": False,
+            "reason": f"Web search timed out after {PER_TOOL_TIMEOUT_SECONDS}s.",
+            "results": [],
+        }
+    except Exception as exc:
+        return {
+            "tool": "web_search",
+            "success": False,
+            "reason": f"Web search error: {exc}",
+            "results": [],
+        }
+
+    if not api_result.success:
+        return {
+            "tool": "web_search",
+            "success": False,
+            "reason": api_result.error or "Web search returned no data.",
+            "results": [],
+        }
+
+    # Compact the results
+    raw_results = api_result.data
+    if isinstance(raw_results, list):
+        compact_results = raw_results[: validated_args.get("max_results", 5)]
+    elif isinstance(raw_results, dict):
+        items = raw_results.get("results", raw_results.get("items", [raw_results]))
+        compact_results = items[: validated_args.get("max_results", 5)]
+    else:
+        compact_results = [raw_results]
+
+    return {
+        "tool": "web_search",
+        "success": True,
+        "results": compact_results,
+    }
+
+
+async def _clarify(validated_args: dict[str, Any]) -> dict[str, Any]:
+    """Execute the clarify tool.
+
+    This is the only tool that produces a final-answer-style output: the
+    agent loop returns the clarifying question as a ``type: final_answer``
+    so the frontend can present it to the user.
+
+    Parameters
+    ----------
+    validated_args:
+        Pre-validated argument dict from ``ClarifyArgs``.
+
+    Returns
+    -------
+    dict[str, Any]
+        A specially marked result that the agent loop interprets as a
+        final answer rather than a tool result to return to the model.
+    """
+    return {
+        "tool": "clarify",
+        "success": True,
+        "type": "final_answer",  # signals the loop to stop
+        "text": validated_args["question"],
+    }
+
+
+_TOOL_IMPLS: dict[str, Any] = {
+    "build_trip_packages": _build_trip_packages,
+    "web_search": _web_search,
+    "clarify": _clarify,
+}
+
+# ---------------------------------------------------------------------------
+# Result compaction
+# ---------------------------------------------------------------------------
+
+
+def _compact_package(pkg: ScoredPackage) -> dict[str, Any]:
+    """Serialize a ScoredPackage to a compact dict for model consumption.
+
+    Strips out verbose fields (generated_at, source identifiers) and
+    truncates amenity lists to at most 5 entries to stay within the
+    2,000-token budget.
+    """
+    amenities_compact = [
+        {
+            "name": a.name,
+            "category": a.category,
+            "distance_km": round(a.distance_km, 2),
+        }
+        for a in (pkg.amenities or [])
+    ][:5]
+
+    return {
+        "label": pkg.label,
+        "flight": {
+            "flight_number": pkg.flight.flight_number,
+            "airline": pkg.flight.airline,
+            "origin": pkg.flight.origin,
+            "destination": pkg.flight.destination,
+            "departure_time": pkg.flight.departure_time.isoformat(),
+            "arrival_time": pkg.flight.arrival_time.isoformat(),
+            "price_cad": pkg.flight.price_cad,
+        },
+        "hotel": (
+            {
+                "name": pkg.hotel.name,
+                "total_price_cad": pkg.hotel.total_price_cad,
+                "rating": pkg.hotel.rating,
+                "distance_to_stadium_km": pkg.hotel.distance_to_stadium_km,
+            }
+            if pkg.hotel is not None
+            else None
+        ),
+        "total_cost_cad": pkg.total_cost_cad,
+        "arrival_buffer_hours": pkg.arrival_buffer_hours,
+        "hotel_to_stadium_min": pkg.hotel_to_stadium_min,
+        "scores": dict(pkg.scores),
+        "explanation": pkg.explanation,
+        "amenities": amenities_compact,
+        "weather_summary": _compact_weather(pkg.weather),
+    }
+
+
+def _compact_weather(weather_list: list[Any]) -> list[dict[str, Any]]:
+    """Compact weather forecasts down to date + key metrics."""
+    return [
+        {
+            "date": str(w.date),
+            "temp_max_c": w.temp_max_c,
+            "temp_min_c": w.temp_min_c,
+            "precipitation_probability": w.precipitation_probability,
+        }
+        for w in weather_list
+    ]
+
+
+def _truncate_result(
+    result_str: str, max_tokens: int = MAX_RESULT_TOKENS
+) -> str:
+    """Crude token-truncation: roughly 4 characters per token."""
+    if not result_str:
+        return result_str
+    max_chars = max_tokens * 4
+    if len(result_str) <= max_chars:
+        return result_str
+    truncated = result_str[:max_chars]
+    # Cut at last newline to avoid corrupting a JSON object mid-stream
+    last_newline = truncated.rfind("\n")
+    if last_newline > max_chars // 2:
+        truncated = truncated[:last_newline]
+    return truncated + "\n... [truncated]"
+
+
+# ---------------------------------------------------------------------------
+# ToolAllowList
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class ToolAllowList:
+    """Governs which tools Nemotron may call and validates every invocation.
+
+    Responsibilities:
+    - Whitelist-based name checking.
+    - Pydantic argument validation per tool.
+    - Duplicate-call detection within a turn.
+    - Compact result formatting (under 2,000 tokens).
+    """
+
+    allowed_tools: frozenset[str] = field(default_factory=lambda: ALLOWED_TOOLS)
+    """Frozenset of permitted tool names. Immutable after construction."""
+
+    def validate_tool_name(self, name: str) -> bool:
+        """Check whether *name* is in the allowlist.
+
+        Returns
+        -------
+        bool
+            ``True`` if the tool name is permitted.
+        """
+        return name in self.allowed_tools
+
+    def validate_args(self, name: str, args: dict[str, Any]) -> dict[str, Any]:
+        """Validate tool arguments using the registered Pydantic schema.
+
+        Parameters
+        ----------
+        name:
+            The tool name.
+        args:
+            Raw arguments dict from the model.
+
+        Returns
+        -------
+        dict[str, Any]
+            Validated arguments as a plain dict.
+
+        Raises
+        ------
+        ValueError
+            If the tool name is unknown or validation fails (Pydantic
+            ``ValidationError`` is re-raised as ``ValueError``).
+        """
+        return _parse_tool_args(name, args)
+
+    def is_duplicate(
+        self, name: str, args: dict[str, Any], history: list[tuple[str, dict[str, Any]]]
+    ) -> bool:
+        """Detect if this exact (tool, args) pair was already called.
+
+        Parameters
+        ----------
+        name:
+            The tool name.
+        args:
+            The validated or raw arguments.
+        history:
+            List of ``(tool_name, args_dict)`` tuples from the current turn.
+
+        Returns
+        -------
+        bool
+            ``True`` if the same tool with semantically identical args has
+            already been called.
+        """
+        key = _call_key(name, args)
+        for prev_name, prev_args in history:
+            if prev_name == name and _call_key(prev_name, prev_args) == key:
+                return True
+        return False
+
+    def format_tool_result(self, name: str, result: dict[str, Any]) -> str:
+        """Format a tool result dict into a compact string for model consumption.
+
+        Parameters
+        ----------
+        name:
+            The tool name (unused, kept for future extensibility).
+        result:
+            The result dict from the tool implementation.
+
+        Returns
+        -------
+        str
+            Compact string representation, guaranteed under 2,000 tokens.
+        """
+        compact = _strip_nones(result)
+        raw = json.dumps(compact, indent=None, ensure_ascii=False, default=str)
+        return _truncate_result(raw, max_tokens=MAX_RESULT_TOKENS)
+
+
+def _strip_nones(obj: Any) -> Any:
+    """Recursively remove keys with ``None`` values from dicts.
+
+    Helps keep the serialised result compact by omitting empty fields
+    rather than emitting ``"field": null``.
+    """
+    if isinstance(obj, dict):
+        return {k: _strip_nones(v) for k, v in obj.items() if v is not None}
+    if isinstance(obj, list):
+        return [_strip_nones(item) for item in obj]
+    return obj
+
+
+# ---------------------------------------------------------------------------
+# AgentLoopResult
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class AgentLoopResult:
+    """The structured return value of ``AgentLoop.run()``.
+
+    Three possible outcomes:
+
+    1. **tool_called** -- Nemotron called a tool successfully and we have a
+       result to display. ``tool`` and ``result`` carry the details.
+    2. **final_answer** -- Nemotron produced a natural-language answer without
+       calling any tools (or called ``clarify``, which is terminal). ``text``
+       carries the answer.
+    3. **fallback_to_deterministic** -- The loop failed for a recoverable
+       reason (malformed JSON, timeout, invalid tool). ``reason`` describes
+       the failure mode.
+
+    This is intentionally a dataclass (not a Pydantic model) for maximum
+    simplicity -- it is the return value of the loop, not a domain model.
+    """
+
+    type: Literal["tool_called", "final_answer", "fallback_to_deterministic"]
+    """Outcome discriminator."""
+
+    tool: str = ""
+    """The tool name that was called (only for ``tool_called``)."""
+
+    result: dict[str, Any] = field(default_factory=dict)
+    """The tool result (only for ``tool_called``)."""
+
+    text: str = ""
+    """The final answer text (only for ``final_answer``)."""
+
+    reason: str = ""
+    """The failure reason (only for ``fallback_to_deterministic``)."""
+
+
+# ---------------------------------------------------------------------------
+# AgentLoop
+# ---------------------------------------------------------------------------
+
+
+class AgentLoop:
+    """Bounded agent loop that orchestrates Nemotron tool use.
+
+    The loop runs at most ``MAX_TOOL_ROUNDS`` (2) turns. Each turn:
+    1. Send the current message list to the agent (Nemotron).
+    2. Parse the agent's response.
+    3. If the agent calls a tool:
+       a. Validate the tool name against the allowlist.
+       b. Validate arguments via Pydantic.
+       c. Check for duplicates.
+       d. Execute the tool with a timeout.
+       e. Format the result and append it to messages.
+    4. If the agent produces a text answer, return it.
+    5. If anything goes wrong, attempt one correction pass, then fall back.
+
+    The loop terminates early on:
+    - A ``final_answer`` outcome (clarify tool or direct text answer).
+    - An unrecoverable error (fallback to deterministic).
+    - Exhaustion of tool rounds.
+    """
+
+    def __init__(
+        self,
+        agent: Any,
+        tools: dict[str, Any] | None = None,
+        max_rounds: int = MAX_TOOL_ROUNDS,
+    ) -> None:
+        """Initialise the agent loop.
+
+        Parameters
+        ----------
+        agent:
+            The LLM agent. Must have an ``async def run(messages: list[dict])``
+            method that returns either ``{"tool_calls": [...], "text": ...}``
+            or ``{"text": ...}``. This is typically a ``MatchDayAgent``
+            instance backed by SGLang + Nemotron.
+        tools:
+            Optional dict of additional tools beyond the built-in allowlist.
+            If ``None``, only the built-in allowlist tools are available.
+            The built-in allowlist always takes precedence; external tools
+            are checked separately.
+        max_rounds:
+            Maximum number of tool-call rounds (default 2). After this many
+            rounds the loop forces a final answer or falls back.
+        """
+        self._agent = agent
+        self._max_rounds = max_rounds
+        self._allow_list = ToolAllowList()
+
+        # Merge external tools if provided (built-in impls are always present)
+        self._tool_impls: dict[str, Any] = dict(_TOOL_IMPLS)
+        if tools is not None:
+            for name, impl in tools.items():
+                if name in ALLOWED_TOOLS:
+                    self._tool_impls[name] = impl
+                else:
+                    logger.debug(
+                        "Ignoring external tool %r: not in allowlist", name
+                    )
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    async def run(self, messages: list[dict]) -> AgentLoopResult:
+        """Run the bounded agent loop.
+
+        Parameters
+        ----------
+        messages:
+            The conversation so far as a list of OpenAI-style message dicts.
+            The first message is typically a system prompt, followed by
+            user messages. The loop appends tool results and assistant
+            responses as it progresses.
+
+        Returns
+        -------
+        AgentLoopResult
+            One of three outcome types (see ``AgentLoopResult``).
+        """
+        round_num = 0
+        tool_history: list[tuple[str, dict[str, Any]]] = []
+        correction_used = False
+
+        while round_num < self._max_rounds:
+            round_num += 1
+
+            # ---- Step 1: Call the agent ----
+            try:
+                response = await self._call_agent(messages)
+            except Exception as exc:
+                logger.error("Agent call failed on round %d: %s", round_num, exc)
+                return AgentLoopResult(
+                    type="fallback_to_deterministic",
+                    reason=f"Agent call failed on round {round_num}: {exc}",
+                )
+
+            # ---- Step 2: Check for tool calls ----
+            tool_calls = response.get("tool_calls", [])
+            text = response.get("text", "")
+
+            if not tool_calls:
+                # Agent produced a text-only answer.
+                final_text = text or "I don't have enough information to answer."
+                # Sanity-check: if text is empty or trivial, fall back
+                if len(final_text.strip()) < 5:
+                    return AgentLoopResult(
+                        type="fallback_to_deterministic",
+                        reason="Agent returned empty or trivial response.",
+                    )
+                return AgentLoopResult(
+                    type="final_answer",
+                    text=final_text,
+                )
+
+            # ---- Step 3: Process each tool call ----
+            # We process tool calls sequentially to keep message ordering
+            # deterministic and avoid confusing the model.
+            for tc in tool_calls:
+                tool_name = tc.get("name", "")
+                raw_args = tc.get("arguments", {})
+
+                # Handle both string and dict argument formats
+                if isinstance(raw_args, str):
+                    try:
+                        raw_args = json.loads(raw_args)
+                    except json.JSONDecodeError:
+                        raw_args = {}
+
+                # Process one tool call. On malformed/validation errors we send
+                # the error back to the agent (one correction attempt) by
+                # injecting an error message and looping around. On success
+                # we return immediately with the tool result.
+                result = await self._process_tool_call(
+                    tool_name=tool_name,
+                    raw_args=raw_args,
+                    tool_history=tool_history,
+                    messages=messages,
+                    correction_used=correction_used,
+                )
+
+                if isinstance(result, AgentLoopResult):
+                    # Terminal outcome: final_answer, tool_called, or fallback
+                    return result
+
+                # result is None = a correctable error occurred.
+                if not correction_used:
+                    # We injected an error message into `messages`. Set the
+                    # flag so the next loop round is the correction attempt.
+                    correction_used = True
+                    # Break out of the tool-calls loop to let the model retry
+                    # in the next round (the error message is already in
+                    # the message list).
+                    break
+
+                # Second malformed call in the same turn -> fall back.
+                # The error message is already in `messages` but we don't
+                # give the model another chance.
+                return AgentLoopResult(
+                    type="fallback_to_deterministic",
+                    reason=(
+                        f"Tool call {tool_name!r} failed after correction "
+                        f"attempt on round {round_num}."
+                    ),
+                )
+
+            else:
+                # All tool calls processed without error or correction.
+                # Continue to next round if rounds remain.
+                continue
+
+            # If we broke out of the for loop to use the correction attempt,
+            # continue the outer while loop to let the model retry.
+            continue
+
+        # ---- Round limit reached: force final answer or fallback ----
+        return AgentLoopResult(
+            type="fallback_to_deterministic",
+            reason=f"Agent loop exceeded maximum {self._max_rounds} tool rounds.",
+        )
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    async def _call_agent(self, messages: list[dict]) -> dict[str, Any]:
+        """Call the underlying agent and return its response.
+
+        The agent's ``run()`` method must be async and return a dict with
+        optional ``tool_calls`` and/or ``text`` keys.
+
+        Parameters
+        ----------
+        messages:
+            The current message list.
+
+        Returns
+        -------
+        dict[str, Any]
+            The agent response dict.
+
+        Raises
+        ------
+        asyncio.TimeoutError
+            If the agent call exceeds the per-tool timeout (30s).
+        Exception
+            Propagates any other exception from the agent.
+        """
+        try:
+            return await asyncio.wait_for(
+                self._agent.run(messages),
+                timeout=PER_TOOL_TIMEOUT_SECONDS,
+            )
+        except asyncio.TimeoutError:
+            raise  # re-raised so the caller handles it
+
+    async def _process_tool_call(
+        self,
+        tool_name: str,
+        raw_args: dict[str, Any],
+        tool_history: list[tuple[str, dict[str, Any]]],
+        messages: list[dict],
+        correction_used: bool,
+    ) -> AgentLoopResult | None:
+        """Process a single tool call from the agent.
+
+        Returns an ``AgentLoopResult`` if the tool call leads to a terminal
+        state (final answer, tool_called, fallback), or ``None`` if there
+        was a correctable error and the caller should retry.
+
+        Parameters
+        ----------
+        tool_name:
+            The tool name the agent wants to call.
+        raw_args:
+            The raw arguments dict.
+        tool_history:
+            History of tool calls in this turn.
+        messages:
+            The mutable conversation message list. Error messages are appended
+            here so the model can self-correct on the next round.
+        correction_used:
+            ``True`` if a correction attempt was already made this turn.
+
+        Returns
+        -------
+        AgentLoopResult | None
+            A terminal result, or ``None`` to signal a correctable error
+            (the error message is already in ``messages``).
+        """
+        # ---- Validate tool name ----
+        if not self._allow_list.validate_tool_name(tool_name):
+            error_msg = (
+                f"Tool {tool_name!r} is not allowed. "
+                f"Allowed tools: {sorted(self._allow_list.allowed_tools)}. "
+                "Please call one of the allowed tools or provide a text answer."
+            )
+            logger.warning("Blocked invalid tool name: %s", tool_name)
+
+            self._inject_error_message(messages, tool_name, error_msg)
+
+            if correction_used:
+                return AgentLoopResult(
+                    type="fallback_to_deterministic",
+                    reason=f"Invalid tool name {tool_name!r} after correction attempt.",
+                )
+            # One correction attempt allowed — signal caller to retry
+            return None
+
+        # ---- Validate arguments ----
+        try:
+            validated_args = self._allow_list.validate_args(tool_name, raw_args)
+        except Exception as exc:
+            error_msg = (
+                f"Argument validation failed for {tool_name!r}: {exc}. "
+                "Please correct the arguments and call the tool again."
+            )
+            logger.warning("Argument validation error: %s", exc)
+
+            self._inject_error_message(messages, tool_name, error_msg)
+
+            if correction_used:
+                return AgentLoopResult(
+                    type="fallback_to_deterministic",
+                    reason=(
+                        f"Argument validation failed for {tool_name!r} "
+                        f"after correction attempt: {exc}"
+                    ),
+                )
+            # One correction attempt allowed
+            return None
+
+        # ---- Check for duplicates ----
+        if self._allow_list.is_duplicate(tool_name, validated_args, tool_history):
+            # Silently skip: the result would be identical
+            logger.info("Skipping duplicate tool call: %s", tool_name)
+            return None
+
+        # ---- Execute the tool ----
+        impl = self._tool_impls.get(tool_name)
+        if impl is None:
+            return AgentLoopResult(
+                type="fallback_to_deterministic",
+                reason=f"No implementation registered for tool {tool_name!r}.",
+            )
+
+        try:
+            tool_result = await asyncio.wait_for(
+                impl(validated_args),
+                timeout=PER_TOOL_TIMEOUT_SECONDS,
+            )
+        except asyncio.TimeoutError:
+            return AgentLoopResult(
+                type="fallback_to_deterministic",
+                reason=(
+                    f"Tool {tool_name!r} timed out after "
+                    f"{PER_TOOL_TIMEOUT_SECONDS}s."
+                ),
+            )
+        except Exception as exc:
+            logger.error("Tool %s execution error: %s", tool_name, exc)
+            return AgentLoopResult(
+                type="fallback_to_deterministic",
+                reason=f"Tool {tool_name!r} execution failed: {exc}",
+            )
+
+        # ---- Handle clarify tool (terminal) ----
+        if tool_result.get("type") == "final_answer":
+            return AgentLoopResult(
+                type="final_answer",
+                text=tool_result.get("text", ""),
+            )
+
+        # ---- Return tool_called result ----
+        return AgentLoopResult(
+            type="tool_called",
+            tool=tool_name,
+            result=tool_result,
+        )
+
+    def _inject_error_message(
+        self,
+        messages: list[dict],
+        tool_name: str,
+        error: str,
+    ) -> None:
+        """Inject a tool error message into the conversation.
+
+        The message is added as a ``role: tool`` message so that the model
+        sees the error on the next round and can self-correct.
+
+        Parameters
+        ----------
+        messages:
+            The mutable conversation message list.
+        tool_name:
+            The tool name that produced the error.
+        error:
+            The error string.
+        """
+        messages.append({
+            "role": "tool",
+            "tool_call_id": tool_name,
+            "name": tool_name,
+            "content": error,
+        })
+
+
+# ---------------------------------------------------------------------------
+# Convenience: run_agent_loop
+# ---------------------------------------------------------------------------
+
+
+async def run_agent_loop(
+    agent: Any,
+    messages: list[dict],
+    tools: dict[str, Any] | None = None,
+    max_rounds: int = MAX_TOOL_ROUNDS,
+) -> AgentLoopResult:
+    """Top-level convenience function for the agent loop.
+
+    Parameters
+    ----------
+    agent:
+        The LLM agent with an ``async run(messages)`` method.
+    messages:
+        The conversation message list.
+    tools:
+        Optional extra tools (merged with built-in allowlist).
+    max_rounds:
+        Maximum tool rounds (default 2).
+
+    Returns
+    -------
+    AgentLoopResult
+        The loop outcome.
+    """
+    loop = AgentLoop(agent=agent, tools=tools, max_rounds=max_rounds)
+    return await loop.run(messages)

matchday/api_registry.py

@@ -0,0 +1,772 @@
+"""
+MatchDay -- Self-registering API normalizer registry.
+
+Based on hermes-agent ``tools/registry.py`` and Claude Code's ``buildTool`` pattern.
+
+Architecture:
+  - ``APINormalizer`` dataclass (with ``__slots__``) describing an external API
+    endpoint: its name, category, input/output Pydantic schemas, async handler,
+    availability check, and required environment variables.
+  - ``APIRegistry`` class that owns all normalizers, handles registration
+    (with collision detection), dispatch (input validation -> handler ->
+    ``APIResult`` envelope), and introspection (``get_enabled_normalizers``,
+    ``get_categories``).
+  - Category composition (``API_CATEGORIES``) with ``resolve_category()`` that
+    expands composite categories recursively (cycle-safe).
+  - Decorator ``@register_api(...)`` for declarative self-registration.
+  - ``build_normalizer()`` helper that merges ``NORMALIZER_DEFAULTS`` with
+    provided overrides (def wins).
+  - ``_check_ttl_cache`` -- 30-second TTL cache on ``check_fn`` results so
+    repeated ``is_enabled()`` calls don't hammer env-var lookups.
+
+Usage:
+    from matchday.api_registry import registry, register_api
+
+    @register_api("serpapi_flights", "flights", check_fn=lambda: bool(os.getenv("SERPAPI_KEY")))
+    async def search_flights(input: FlightInput) -> list[Flight]:
+        ...
+"""
+
+from __future__ import annotations
+
+import functools
+import os
+import time
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, ParamSpec, TypeVar
+
+from pydantic import BaseModel
+
+from matchday.models import APIResult
+
+# ---------------------------------------------------------------------------
+# APINormalizer -- single API endpoint descriptor
+# ---------------------------------------------------------------------------
+
+
+@dataclass(slots=True)
+class APINormalizer:
+    """Descriptor for one external API normalizer function.
+
+    Every normalizer registered in the system is represented by one of these.
+    The registry uses the fields below for dispatch, validation, and
+    availability gating.
+
+    ``slots=True`` eliminates the instance ``__dict__``, saving memory and
+    attribute-lookup overhead on the hot path.
+    """
+
+    name: str
+    """Unique identifier, e.g. ``serpapi_flights``."""
+
+    category: str
+    """Category key from ``API_CATEGORIES``, e.g. ``flights``, ``hotels``."""
+
+    input_schema: type[BaseModel]
+    """Pydantic model used to validate incoming parameters."""
+
+    output_schema: type[BaseModel]
+    """Pydantic model type that the handler returns (a single model or
+    ``list[Model]``). Used for type introspection / doc generation."""
+
+    handler: Callable[..., Awaitable[Any] | Any]
+    """The actual normalizer function. Signature should match what
+    ``dispatch()`` calls: ``handler(**validated_params)``."""
+
+    check_fn: Callable[[], bool]
+    """Called by ``is_enabled()`` to determine whether this normalizer's
+    API key / credentials are available. Defaults to a no-op returning
+    ``False`` (fail-closed)."""
+
+    requires_env: list[str] = field(default_factory=list)
+    """Environment variable names required for this normalizer, e.g.
+    ``["SERPAPI_KEY"]``. ``is_enabled()`` checks that all are set before
+    calling ``check_fn``."""
+
+    is_async: bool = True
+    """``True`` when ``handler`` is an async function. The registry uses this
+    to decide whether to ``await`` the call in ``dispatch()``."""
+
+    description: str = ""
+    """Human-readable description of what this normalizer does."""
+
+    emoji: str = ""
+    """Single emoji for frontend / logging decoration."""
+
+    def __post_init__(self) -> None:
+        """Validate invariants at construction time."""
+        if not self.name:
+            raise ValueError("APINormalizer.name must be a non-empty string.")
+        if not self.category:
+            raise ValueError("APINormalizer.category must be a non-empty string.")
+
+
+# ---------------------------------------------------------------------------
+# NORMALIZER_DEFAULTS -- fail-closed defaults (Claude Code buildTool pattern)
+# ---------------------------------------------------------------------------
+
+NORMALIZER_DEFAULTS: dict[str, Any] = {
+    "is_enabled": False,
+    "is_concurrency_safe": False,
+    "max_result_size_chars": 100_000,
+}
+"""Fail-closed defaults for all normalizers.
+
+These are NOT fields of ``APINormalizer`` itself but are used by calling code
+that wraps normalizers (e.g. builders, middleware) -- see ``build_normalizer``
+below.
+"""
+
+# ---------------------------------------------------------------------------
+# API_CATEGORIES -- category hierarchy with composition
+# ---------------------------------------------------------------------------
+
+API_CATEGORIES: dict[str, dict[str, Any]] = {
+    "flights": {
+        "description": "Flight search and pricing via SerpApi (Google Flights).",
+        "normalizers": ["serpapi_flights"],
+    },
+    "hotels": {
+        "description": "Hotel search and pricing via SerpApi (Google Hotels).",
+        "normalizers": ["serpapi_hotels"],
+    },
+    "weather": {
+        "description": "Weather forecasts via Open-Meteo.",
+        "normalizers": ["openmeteo_weather"],
+    },
+    "amenities": {
+        "description": "Points of interest near BC Place via OSM Overpass API.",
+        "normalizers": ["osm_amenities"],
+    },
+    "photos": {
+        "description": "Photo search for destinations and venues.",
+        "normalizers": ["pexels_photos"],
+    },
+    "web_search": {
+        "description": "General-purpose web search for supplemental data.",
+        "normalizers": ["serpapi_web_search"],
+    },
+    "full_trip": {
+        "description": "Composite category: all data needed for a complete trip package.",
+        "includes": ["flights", "hotels", "weather", "amenities"],
+    },
+}
+"""Category definitions.
+
+Each entry has either:
+  - ``normalizers``: list of concrete normalizer names in this category.
+  - ``includes``: list of sub-category names (recursive composition).
+"""
+
+
+def resolve_category(name: str, visited: set[str] | None = None) -> list[str]:
+    """Recursively expand a category into a flat list of normalizer names.
+
+    Composite categories (those with ``includes``) are expanded depth-first.
+    Cycle detection prevents infinite recursion.
+
+    Parameters
+    ----------
+    name:
+        Category key to resolve (e.g. ``"full_trip"``).
+    visited:
+        Internal set used for cycle detection. Pass ``None`` on the top-level
+        call; the function manages this automatically.
+
+    Returns
+    -------
+    list[str]
+        Flat list of concrete normalizer names belonging to this category.
+
+    Raises
+    ------
+    ValueError
+        If the category name is unknown or a cycle is detected.
+
+    Examples
+    --------
+    >>> resolve_category("full_trip")
+    ["serpapi_flights", "serpapi_hotels", "openmeteo_weather", "osm_amenities"]
+    """
+    if visited is None:
+        visited = set()
+
+    if name in visited:
+        raise ValueError(
+            f"Cycle detected resolving category {name!r}. "
+            f"Visited: {visited}"
+        )
+
+    category = API_CATEGORIES.get(name)
+    if category is None:
+        raise ValueError(
+            f"Unknown category {name!r}. Available: {list(API_CATEGORIES)}"
+        )
+
+    visited.add(name)
+
+    # Composite category -- expand includes recursively
+    if "includes" in category:
+        result: list[str] = []
+        for sub in category["includes"]:
+            result.extend(resolve_category(sub, visited))
+        return result
+
+    # Leaf category -- return normalizer names directly
+    return list(category.get("normalizers", []))
+
+
+# ---------------------------------------------------------------------------
+# TTL cache for check_fn results
+# ---------------------------------------------------------------------------
+
+
+class _TTLCache:
+    """Simple time-to-live cache with per-key expiry.
+
+    Used to avoid hammering env-var lookups and ``check_fn`` calls on every
+    ``is_enabled()`` invocation.
+    """
+
+    __slots__ = ("_data", "_ttl_seconds")
+
+    def __init__(self, ttl_seconds: float = 30.0) -> None:
+        self._data: dict[str, tuple[bool, float]] = {}
+        self._ttl_seconds = ttl_seconds
+
+    def get(self, key: str) -> bool | None:
+        """Return cached value if still fresh, or ``None`` if expired/missing."""
+        entry = self._data.get(key)
+        if entry is None:
+            return None
+        value, expires_at = entry
+        if time.monotonic() > expires_at:
+            del self._data[key]
+            return None
+        return value
+
+    def set(self, key: str, value: bool) -> None:
+        """Store value with a fresh expiry timestamp."""
+        self._data[key] = (value, time.monotonic() + self._ttl_seconds)
+
+    def invalidate(self, key: str) -> None:
+        """Remove a single key from the cache."""
+        self._data.pop(key, None)
+
+    def clear(self) -> None:
+        """Remove all cached entries."""
+        self._data.clear()
+
+
+_check_ttl_cache = _TTLCache(ttl_seconds=30.0)
+"""Module-level TTL cache shared across all ``is_enabled()`` calls.
+
+Keyed by normalizer name. Evicted after 30 seconds.
+"""
+
+
+# ---------------------------------------------------------------------------
+# APIRegistry
+# ---------------------------------------------------------------------------
+
+P = ParamSpec("P")
+T = TypeVar("T")
+
+
+class APIRegistry:
+    """Self-registering normalizer registry.
+
+    Owns all ``APINormalizer`` entries and provides:
+      - ``register()`` to add entries (with collision detection).
+      - ``dispatch()`` to call a normalizer by name with Pydantic validation
+        and ``APIResult`` envelope wrapping.
+      - ``is_enabled()`` to check API availability.
+      - ``get_enabled_normalizers()`` for introspection.
+      - ``get_categories()`` to enumerate category structure.
+    """
+
+    __slots__ = ("_normalizers", "_categories", "_generation")
+
+    def __init__(self) -> None:
+        self._normalizers: dict[str, APINormalizer] = {}
+        """name -> APINormalizer mapping."""
+        self._categories: dict[str, list[str]] = {}
+        """category -> [normalizer_name, ...] reverse index."""
+        self._generation: int = 0
+        """Monotonic counter bumped on every register/override for cache
+        invalidation (e.g. clearing downstream caches that key on registry
+        contents)."""
+
+    # ── registration ──────────────────────────────────────────────────────
+
+    def register(
+        self,
+        name: str,
+        category: str,
+        input_schema: type[BaseModel],
+        output_schema: type[BaseModel],
+        handler: Callable[..., Awaitable[Any] | Any],
+        check_fn: Callable[[], bool] | None = None,
+        *,
+        requires_env: list[str] | None = None,
+        is_async: bool = True,
+        description: str = "",
+        emoji: str = "",
+        override: bool = False,
+    ) -> None:
+        """Register a new normalizer in the registry.
+
+        Parameters
+        ----------
+        name:
+            Unique identifier for this normalizer (e.g. ``"serpapi_flights"``).
+        category:
+            Category key (must exist in ``API_CATEGORIES``).
+        input_schema:
+            Pydantic model for input validation in ``dispatch()``.
+        output_schema:
+            Pydantic model type for the return value.
+        handler:
+            The normalizer function. Called as ``handler(**validated_params)``.
+        check_fn:
+            Callable returning ``True`` if the API key/credentials are
+            available. Defaults to a function that returns ``False``
+            (fail-closed).
+        requires_env:
+            List of environment variable names required for this normalizer.
+        is_async:
+            ``True`` (default) if the handler is async.
+        description:
+            Human-readable description of this normalizer.
+        emoji:
+            Decoration emoji.
+        override:
+            If ``False`` (default), registering an existing name raises
+            ``ValueError``. If ``True``, the existing entry is replaced.
+
+        Raises
+        ------
+        ValueError
+            If ``name`` already exists and ``override=False``, or if category
+            is unknown.
+        """
+        # Validate category
+        if category not in API_CATEGORIES:
+            raise ValueError(
+                f"Unknown category {category!r}. "
+                f"Available: {list(API_CATEGORIES)}"
+            )
+
+        # Collision detection
+        if name in self._normalizers and not override:
+            raise ValueError(
+                f"Normalizer {name!r} is already registered. "
+                "Use override=True to replace."
+            )
+
+        normalizer = APINormalizer(
+            name=name,
+            category=category,
+            input_schema=input_schema,
+            output_schema=output_schema,
+            handler=handler,
+            check_fn=check_fn if check_fn is not None else (lambda: False),
+            requires_env=requires_env or [],
+            is_async=is_async,
+            description=description,
+            emoji=emoji,
+        )
+
+        self._normalizers[name] = normalizer
+
+        # Update reverse category index
+        if category not in self._categories:
+            self._categories[category] = []
+        if name not in self._categories[category]:
+            self._categories[category].append(name)
+
+        self._generation += 1
+
+    # ── lookup ────────────────────────────────────────────────────────────
+
+    def get_entry(self, name: str) -> APINormalizer | None:
+        """Look up a normalizer by name.
+
+        Returns
+        -------
+        APINormalizer or ``None`` if not found.
+        """
+        return self._normalizers.get(name)
+
+    # ── dispatch ──────────────────────────────────────────────────────────
+
+    async def dispatch(self, name: str, params: dict[str, Any]) -> APIResult:
+        """Call a normalizer by name with validated parameters.
+
+    1. Looks up the normalizer by ``name``.
+    2. Validates ``params`` against the normalizer's ``input_schema``
+       (Pydantic model).
+    3. Calls the handler with the validated data (as keyword arguments).
+    4. Wraps the result in an ``APIResult`` envelope.
+    5. Catches ALL exceptions and returns ``APIResult(success=False,
+       error=...)``.
+
+        Parameters
+        ----------
+        name:
+            Registered normalizer name.
+        params:
+            Raw parameters dict (will be validated against the normalizer's
+            ``input_schema``).
+
+        Returns
+        -------
+        APIResult
+            Success or failure envelope.
+        """
+        normalizer = self._normalizers.get(name)
+        if normalizer is None:
+            return APIResult(
+                success=False,
+                data=None,
+                error=f"Unknown normalizer: {name!r}.",
+                source="registry",
+                as_of=datetime.now(timezone.utc),
+            )
+
+        # Validate input with Pydantic
+        try:
+            validated = normalizer.input_schema.model_validate(params)
+        except Exception as exc:
+            return APIResult(
+                success=False,
+                data=None,
+                error=f"Input validation failed for {name!r}: {exc}",
+                source=name,
+                as_of=datetime.now(timezone.utc),
+            )
+
+        # Call handler
+        try:
+            raw_result = normalizer.handler(**validated.model_dump())
+
+            if normalizer.is_async:
+                raw_result = await raw_result  # type: ignore[assignment]
+        except Exception as exc:
+            return APIResult(
+                success=False,
+                data=None,
+                error=f"Handler {name!r} raised: {type(exc).__name__}: {exc}",
+                source=name,
+                as_of=datetime.now(timezone.utc),
+            )
+
+        return APIResult(
+            success=True,
+            data=raw_result,
+            error=None,
+            source=name,
+            as_of=datetime.now(timezone.utc),
+        )
+
+    # ── availability gating ───────────────────────────────────────────────
+
+    def is_enabled(self, name: str) -> bool:
+        """Check whether a normalizer is usable right now.
+
+        Returns ``True`` only when:
+          1. The normalizer is registered.
+          2. All ``requires_env`` variables are set (non-empty) in the
+             environment.
+          3. ``check_fn()`` returns ``True``.
+
+        Results are cached in ``_check_ttl_cache`` for 30 seconds.
+
+        Parameters
+        ----------
+        name:
+            Normalizer name to check.
+
+        Returns
+        -------
+        bool
+        """
+        normalizer = self._normalizers.get(name)
+        if normalizer is None:
+            return False
+
+        # Check TTL cache first
+        cached = _check_ttl_cache.get(name)
+        if cached is not None:
+            return cached
+
+        # Check required env vars
+        for env_var in normalizer.requires_env:
+            if not os.environ.get(env_var):
+                _check_ttl_cache.set(name, False)
+                return False
+
+        # Run the check_fn
+        try:
+            result = bool(normalizer.check_fn())
+        except Exception:
+            result = False
+
+        _check_ttl_cache.set(name, result)
+        return result
+
+    # ── introspection ─────────────────────────────────────────────────────
+
+    def get_enabled_normalizers(self, category: str | None = None) -> list[str]:
+        """Return names of all currently enabled normalizers.
+
+        Parameters
+        ----------
+        category:
+            If provided, filter to normalizers in this category (and its
+            sub-categories if composite). If ``None``, return all enabled
+            normalizers across all categories.
+
+        Returns
+        -------
+        list[str]
+            Sorted list of normalizer names whose ``is_enabled()`` is
+            ``True``.
+        """
+        names: list[str] = []
+
+        if category is not None:
+            # Resolve composite categories into concrete normalizer names
+            try:
+                resolved = resolve_category(category)
+            except ValueError:
+                # Unknown category or cycle
+                return []
+            names = resolved
+        else:
+            names = list(self._normalizers.keys())
+
+        return sorted(n for n in names if self.is_enabled(n))
+
+    def get_categories(self) -> dict[str, dict[str, Any]]:
+        """Return a shallow copy of the category definitions.
+
+        Returns
+        -------
+        dict
+            Keys are category names; values are the definition dicts from
+            ``API_CATEGORIES``.
+        """
+        return dict(API_CATEGORIES)
+
+    @property
+    def generation(self) -> int:
+        """Monotonic counter bumped on every registration change.
+
+        Consumers (e.g. caches that depend on registry contents) can store
+        the last-seen generation and compare to detect staleness.
+        """
+        return self._generation
+
+
+# ---------------------------------------------------------------------------
+# Module-level singleton
+# ---------------------------------------------------------------------------
+
+registry: APIRegistry = APIRegistry()
+"""Module-level singleton registry instance.
+
+All normalizers should register themselves against this instance, either
+via ``registry.register(...)`` or the ``@register_api`` decorator::
+
+    from matchday.api_registry import registry
+
+    registry.register("my_api", "flights", MyInput, MyOutput, my_handler, ...)
+"""
+
+
+# ---------------------------------------------------------------------------
+# Decorator: @register_api
+# ---------------------------------------------------------------------------
+
+
+def register_api(
+    name: str,
+    category: str,
+    *,
+    input_schema: type[BaseModel] | None = None,
+    output_schema: type[BaseModel] | None = None,
+    check_fn: Callable[[], bool] | None = None,
+    requires_env: list[str] | None = None,
+    is_async: bool = True,
+    description: str = "",
+    emoji: str = "",
+    override: bool = False,
+) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    """Decorator that registers a function as an API normalizer.
+
+    Usage::
+
+        @register_api("serpapi_flights", "flights",
+                      input_schema=FlightInput,
+                      output_schema=list[Flight],
+                      check_fn=lambda: bool(os.getenv("SERPAPI_KEY")))
+        async def search_flights(**kwargs) -> list[Flight]:
+            ...
+
+    Parameters
+    ----------
+    name:
+        Unique normalizer identifier.
+    category:
+        Category key (must exist in ``API_CATEGORIES``).
+    input_schema:
+        Pydantic model for input validation. If omitted, the decorated
+        function's type annotations will NOT be used -- you MUST provide
+        a schema or register manually.
+    output_schema:
+        Pydantic model type for the return value.
+    check_fn:
+        Callable returning ``True`` when the API is available.
+        Defaults to ``lambda: False`` (fail-closed).
+    requires_env:
+        Environment variables required by this normalizer.
+    is_async:
+        Whether the handler is async (default ``True``).
+    description:
+        Human-readable description.
+    emoji:
+        Decoration emoji.
+    override:
+        Allow replacing an existing registration with the same name.
+
+    Returns
+    -------
+    Callable
+        The original function (unchanged) -- the decorator only registers it
+        with the module-level ``registry`` singleton.
+
+    Raises
+    ------
+    ValueError
+        If ``input_schema`` is ``None`` (explicit schema is required).
+    """
+    if input_schema is None:
+        raise ValueError(
+            "@register_api requires an explicit input_schema. "
+            "Pydantic model is needed for input validation in dispatch()."
+        )
+
+    def decorator(fn: Callable[..., Any]) -> Callable[..., Any]:
+        registry.register(
+            name=name,
+            category=category,
+            input_schema=input_schema,
+            output_schema=output_schema or BaseModel,
+            handler=fn,
+            check_fn=check_fn,
+            requires_env=requires_env,
+            is_async=is_async,
+            description=description or fn.__doc__ or "",
+            emoji=emoji,
+            override=override,
+        )
+        return fn
+
+    return decorator
+
+
+# ---------------------------------------------------------------------------
+# Helper: build_normalizer
+# ---------------------------------------------------------------------------
+
+
+def build_normalizer(
+    *,
+    name: str,
+    category: str,
+    input_schema: type[BaseModel],
+    output_schema: type[BaseModel],
+    handler: Callable[..., Awaitable[Any] | Any],
+    check_fn: Callable[[], bool] | None = None,
+    requires_env: list[str] | None = None,
+    is_async: bool = True,
+    description: str = "",
+    emoji: str = "",
+) -> APINormalizer:
+    """Build an ``APINormalizer`` by applying ``NORMALIZER_DEFAULTS`` first,
+    then overlaying the provided keyword arguments (def wins).
+
+    This is the Claude Code ``buildTool`` pattern: start with fail-closed
+    defaults, then let the caller's explicit overrides take precedence.
+
+    Parameters
+    ----------
+    name:
+        Unique normalizer identifier.
+    category:
+        Category key.
+    input_schema:
+        Pydantic input model.
+    output_schema:
+        Pydantic output model type.
+    handler:
+        The normalizer function.
+    check_fn:
+        API availability check. Defaults to ``lambda: False``.
+    requires_env:
+        Required environment variables.
+    is_async:
+        Whether the handler is async.
+    description:
+        Human-readable description.
+    emoji:
+        Decoration emoji.
+
+    Returns
+    -------
+    APINormalizer
+        A fully populated normalizer instance.
+
+    Notes
+    -----
+    ``NORMALIZER_DEFAULTS`` fields (``is_enabled``, ``is_concurrency_safe``,
+    ``max_result_size_chars``) are NOT stored in ``APINormalizer`` itself --
+    they are returned in the extra info dict if you need them. Callers that
+    wrap normalizers (e.g. middleware, executors) should read those defaults
+    from ``NORMALIZER_DEFAULTS`` directly.
+    """
+    # Start with a fresh dict built from NORMALIZER_DEFAULTS
+    overrides: dict[str, Any] = {
+        "name": name,
+        "category": category,
+        "input_schema": input_schema,
+        "output_schema": output_schema,
+        "handler": handler,
+        "check_fn": check_fn if check_fn is not None else (lambda: False),
+        "requires_env": requires_env or [],
+        "is_async": is_async,
+        "description": description,
+        "emoji": emoji,
+    }
+
+    return APINormalizer(**overrides)
+
+
+# ---------------------------------------------------------------------------
+# Explicit re-export so that ``from matchday.api_registry import registry``
+# works cleanly.
+# ---------------------------------------------------------------------------
+
+__all__ = [
+    "APINormalizer",
+    "APIRegistry",
+    "API_CATEGORIES",
+    "NORMALIZER_DEFAULTS",
+    "build_normalizer",
+    "register_api",
+    "registry",
+    "resolve_category",
+]

matchday/apis/__init__.py

@@ -0,0 +1,26 @@
+"""Concrete API normalizers for MatchDay.
+
+Importing this package registers every normalizer with the module-level
+``registry`` singleton in ``matchday.api_registry`` — registration is a side
+effect of the ``@register_api`` decorator running at module load time.
+
+Any consumer that relies on ``registry.dispatch(...)`` / ``get_enabled_*`` must
+``import matchday.apis`` (or a specific submodule) before dispatching, otherwise
+the registry is inert and every dispatch returns "Unknown normalizer".
+
+Normalizers are grouped by data source:
+
+- ``weather`` — Open-Meteo daily forecast (keyless).
+- ``pois``    — OpenStreetMap points of interest near BC Place (keyless).
+- ``routes``  — OpenRouteService walking/transit routes (ORS key).
+- ``flights`` / ``hotels`` / ``web`` — SerpApi (Google Flights/Hotels/Search).
+"""
+
+# Load .env first so the registry's is_enabled() checks see API keys.
+# os.environ.setdefault is used, so real (deployed) env vars win over the file.
+from matchday import config  # noqa: F401
+
+# Importing each submodule triggers its @register_api side effects.
+from matchday.apis import flights, hotels, pois, weather, web  # noqa: F401  (side-effect registration)
+
+__all__ = ["config", "flights", "hotels", "pois", "weather", "web"]

matchday/apis/flights.py

@@ -0,0 +1,153 @@
+"""SerpApi (Google Flights) flight-search normalizer, with fixture fallback.
+
+Attempts a live SerpApi Google Flights query (origin -> YVR on match day); on
+any failure — no key, quota exhausted, network error, parse error, or empty
+result — it falls back to ``fixtures.fallback_flights`` so the pipeline always
+yields candidates. Live results carry ``source="serpapi"``; fallback carries
+``source="fallback"`` — honest provenance either way (the plan's A7/I4
+contract; Nemotron never prices, Python does).
+
+Plan alignment: P3 lifecycle, I4 provenance, A7 fixture fallback. Retry +
+timeout live inside the handler (I5 middleware deferred). SerpApi returns
+airport-local times (naive); scoring's ``_to_vancouver_aware`` handles them.
+"""
+from __future__ import annotations
+
+import logging
+import os
+from datetime import date, datetime, timezone
+from typing import Any
+
+import httpx
+from pydantic import BaseModel, ConfigDict, field_validator
+
+from matchday import fixtures
+from matchday.api_registry import register_api
+from matchday.errors import DegradeImmediately, MaxRetriesExceeded, retry_with_backoff
+from matchday.models import Flight
+
+logger = logging.getLogger(__name__)
+
+_SERPAPI_URL = "https://serpapi.com/search"
+_REQUEST_TIMEOUT = 30.0
+_MAX_RESULTS = 8
+
+
+class FlightsInput(BaseModel):
+    """Input for the flights normalizer.
+
+    Accepts the full ``TripRequest`` dump (extra ignored). ``match_date`` is
+    used as the outbound travel date (the app books travel on match day).
+    """
+
+    model_config = ConfigDict(extra="ignore")
+
+    origin_airport: str
+    match_date: date
+    destination: str = "YVR"
+
+    @field_validator("origin_airport", "destination")
+    @classmethod
+    def _iata(cls, v: str) -> str:
+        cleaned = v.strip().upper()
+        if len(cleaned) != 3 or not cleaned.isalpha():
+            raise ValueError(f"Invalid IATA code: {v!r}")
+        return cleaned
+
+
+def _parse_time(raw: str) -> datetime:
+    """Parse SerpApi's airport-local time string, e.g. '2026-06-26 11:00'."""
+    return datetime.fromisoformat(raw)
+
+
+def _normalize(groups: list[dict[str, Any]], origin: str, dest: str) -> list[Flight]:
+    """Turn SerpApi flight groups into ``Flight`` models (primary leg each)."""
+    fetched_at = datetime.now(timezone.utc)
+    out: list[Flight] = []
+    for group in groups[:_MAX_RESULTS]:
+        legs = group.get("flights") or []
+        if not legs:
+            continue
+        # Primary leg: first segment. (YUL->YVR is nonstop; connections are
+        # represented as multiple legs — we surface the operating carrier.)
+        leg = legs[0]
+        try:
+            dep = leg["departure_airport"]
+            arr = leg["arrival_airport"]
+            price = group.get("price")
+            out.append(
+                Flight(
+                    flight_number=str(leg.get("flight_number") or "").strip(),
+                    airline=str(leg.get("airline") or "Unknown").strip(),
+                    origin=origin,
+                    destination=dest,
+                    departure_time=_parse_time(dep["time"]),
+                    arrival_time=_parse_time(arr["time"]),
+                    price_cad=float(price) if price is not None else None,
+                    booking_url=None,  # booking_token requires a follow-up call; deferred
+                    source="serpapi",
+                    as_of=fetched_at,
+                )
+            )
+        except (KeyError, ValueError, TypeError) as exc:
+            logger.warning("Skipping SerpApi flight group: %s", exc)
+    return out
+
+
+@register_api(
+    "serpapi_flights",
+    "flights",
+    input_schema=FlightsInput,
+    output_schema=Flight,
+    check_fn=lambda: bool(os.getenv("SERPAPI_API_KEY")),
+    requires_env=["SERPAPI_API_KEY"],
+    is_async=True,
+    description="Flight search + pricing via SerpApi (Google Flights).",
+    emoji="✈️",
+)
+async def fetch_flights(
+    *, origin_airport: str, match_date: date, destination: str = "YVR", **_: Any
+) -> list[Flight]:
+    """Fetch flights origin -> destination on match_date via SerpApi.
+
+    Falls back to fixtures (source="fallback") on any failure so the pipeline
+    always yields candidates.
+    """
+    key = os.getenv("SERPAPI_API_KEY")
+    if not key:
+        logger.info("No SERPAPI_API_KEY — using fixture flights.")
+        return fixtures.fallback_flights(origin=origin_airport, match_date=match_date)
+
+    params = {
+        "engine": "google_flights",
+        "departure_id": origin_airport,
+        "arrival_id": destination,
+        "outbound_date": match_date.isoformat(),
+        "type": "2",  # one-way
+        "adults": "1",
+        "currency": "CAD",
+        "hl": "en",
+        "gl": "ca",
+        "api_key": key,
+    }
+
+    async def _get() -> dict[str, Any]:
+        async with httpx.AsyncClient(timeout=_REQUEST_TIMEOUT) as client:
+            resp = await client.get(_SERPAPI_URL, params=params)
+            resp.raise_for_status()
+            return resp.json()
+
+    try:
+        data = await retry_with_backoff(
+            _get, max_retries=1, base_delay=1.0, max_delay=4.0
+        )
+    except Exception as exc:  # DegradeImmediately / MaxRetriesExceeded / network
+        logger.warning("SerpApi flights failed (%s); fixture fallback.", exc)
+        return fixtures.fallback_flights(origin=origin_airport, match_date=match_date)
+
+    groups = (data.get("best_flights") or []) + (data.get("other_flights") or [])
+    flights = _normalize(groups, origin_airport, destination)
+    if not flights:
+        logger.warning("SerpApi flights parsed empty; fixture fallback.")
+        return fixtures.fallback_flights(origin=origin_airport, match_date=match_date)
+    return flights

matchday/apis/hotels.py

@@ -0,0 +1,159 @@
+"""SerpApi (Google Hotels) hotel-search normalizer, with fixture fallback.
+
+Attempts a live SerpApi Google Hotels query (Vancouver near BC Place for the
+trip window); on any failure it falls back to ``fixtures.fallback_hotels``.
+Live results carry ``source="serpapi"``; fallback carries ``source="fallback"``.
+Hotel-to-stadium distance is computed (haversine from GPS) so scoring's transit
+dimension has real geometry. Nemotron never prices; Python does.
+
+Plan alignment: P3 lifecycle, I4 provenance, A7 fixture fallback. Retry +
+timeout inside the handler (I5 deferred).
+"""
+from __future__ import annotations
+
+import logging
+import math
+import os
+from datetime import date, datetime, timezone
+from typing import Any
+
+import httpx
+from pydantic import BaseModel, ConfigDict
+
+from matchday import fixtures
+from matchday.api_registry import register_api
+from matchday.errors import DegradeImmediately, MaxRetriesExceeded, retry_with_backoff
+from matchday.models import Hotel
+
+logger = logging.getLogger(__name__)
+
+_SERPAPI_URL = "https://serpapi.com/search"
+_BC_PLACE_LAT = 49.2827
+_BC_PLACE_LON = -123.1207
+_REQUEST_TIMEOUT = 30.0
+_MAX_RESULTS = 10
+
+
+class HotelsInput(BaseModel):
+    """Input for the hotels normalizer (accepts the full TripRequest dump)."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    check_in: date
+    check_out: date
+
+
+def _haversine_km(lat1: float, lon1: float, lat2: float, lon2: float) -> float:
+    earth_radius_km = 6371.0088
+    p1 = math.radians(lat1)
+    p2 = math.radians(lat2)
+    d_phi = math.radians(lat2 - lat1)
+    d_lambda = math.radians(lon2 - lon1)
+    a = (
+        math.sin(d_phi / 2) ** 2
+        + math.cos(p1) * math.cos(p2) * math.sin(d_lambda / 2) ** 2
+    )
+    return 2 * earth_radius_km * math.asin(math.sqrt(a))
+
+
+def _normalize(
+    properties: list[dict[str, Any]], check_in: date, check_out: date
+) -> list[Hotel]:
+    """Turn SerpApi hotel properties into ``Hotel`` models."""
+    fetched_at = datetime.now(timezone.utc)
+    nights = max(1, (check_out - check_in).days)
+    out: list[Hotel] = []
+    for prop in properties[:_MAX_RESULTS]:
+        try:
+            name = prop.get("name")
+            if not name:
+                continue
+            rpn = prop.get("rate_per_night") or {}
+            trate = prop.get("total_rate") or {}
+            per_night = rpn.get("extracted_lowest")
+            total = trate.get("extracted_lowest")
+            if total is None and per_night is not None:
+                total = float(per_night) * nights  # derive when SerpApi omits it
+
+            gps = prop.get("gps_coordinates") or {}
+            lat = gps.get("latitude") or gps.get("lat")
+            lon = gps.get("longitude") or gps.get("lng")
+            distance = (
+                round(_haversine_km(_BC_PLACE_LAT, _BC_PLACE_LON, lat, lon), 3)
+                if lat is not None and lon is not None
+                else None
+            )
+            rating = prop.get("overall_rating")
+
+            out.append(
+                Hotel(
+                    name=name,
+                    price_per_night_cad=float(per_night) if per_night is not None else None,
+                    total_price_cad=float(total) if total is not None else None,
+                    latitude=float(lat) if lat is not None else None,
+                    longitude=float(lon) if lon is not None else None,
+                    distance_to_stadium_km=distance,
+                    rating=float(rating) if rating is not None else None,
+                    booking_url=prop.get("link"),
+                    source="serpapi",
+                    as_of=fetched_at,
+                )
+            )
+        except (ValueError, TypeError) as exc:
+            logger.warning("Skipping SerpApi hotel %r: %s", prop.get("name"), exc)
+    return out
+
+
+@register_api(
+    "serpapi_hotels",
+    "hotels",
+    input_schema=HotelsInput,
+    output_schema=Hotel,
+    check_fn=lambda: bool(os.getenv("SERPAPI_API_KEY")),
+    requires_env=["SERPAPI_API_KEY"],
+    is_async=True,
+    description="Hotel search + pricing via SerpApi (Google Hotels).",
+    emoji="🏨",
+)
+async def fetch_hotels(*, check_in: date, check_out: date, **_: Any) -> list[Hotel]:
+    """Fetch hotels near BC Place for the trip window via SerpApi.
+
+    Falls back to fixtures (source="fallback") on any failure.
+    """
+    key = os.getenv("SERPAPI_API_KEY")
+    if not key:
+        logger.info("No SERPAPI_API_KEY — using fixture hotels.")
+        return fixtures.fallback_hotels(check_in=check_in, check_out=check_out)
+
+    params = {
+        "engine": "google_hotels",
+        "q": "Hotels in Vancouver near BC Place",
+        "check_in_date": check_in.isoformat(),
+        "check_out_date": check_out.isoformat(),
+        "adults": "2",
+        "currency": "CAD",
+        "hl": "en",
+        "gl": "ca",
+        "api_key": key,
+    }
+
+    async def _get() -> dict[str, Any]:
+        async with httpx.AsyncClient(timeout=_REQUEST_TIMEOUT) as client:
+            resp = await client.get(_SERPAPI_URL, params=params)
+            resp.raise_for_status()
+            return resp.json()
+
+    try:
+        data = await retry_with_backoff(
+            _get, max_retries=1, base_delay=1.0, max_delay=4.0
+        )
+    except Exception as exc:
+        logger.warning("SerpApi hotels failed (%s); fixture fallback.", exc)
+        return fixtures.fallback_hotels(check_in=check_in, check_out=check_out)
+
+    properties = data.get("properties") or []
+    hotels = _normalize(properties, check_in, check_out)
+    if not hotels:
+        logger.warning("SerpApi hotels parsed empty; fixture fallback.")
+        return fixtures.fallback_hotels(check_in=check_in, check_out=check_out)
+    return hotels

matchday/apis/pois.py

@@ -0,0 +1,161 @@
+"""OpenStreetMap points-of-interest normalizer (keyless — no API key).
+
+Uses the Overpass API to find food & drink amenities (restaurants, cafes, bars,
+pubs, fast food, food courts) near BC Place Stadium, Vancouver. Each result is
+normalized into an ``Amenity`` model with straight-line (haversine) distance to
+BC Place and inline provenance (``source="osm"``).
+
+Plan alignment
+--------------
+- P3  full normalizer lifecycle (validate -> fetch -> normalize -> provenance).
+- U3  output budget: results capped at ``_MAX_RESULTS``, sorted by distance.
+- I4  inline provenance on each Amenity (source + as_of).
+- Keyless per the bootstrap (OpenStreetMap only asks for a descriptive
+       User-Agent). Retry + timeout inside the handler (I5 deferred).
+"""
+from __future__ import annotations
+
+import logging
+import math
+from datetime import datetime, timezone
+from typing import Any
+
+import httpx
+from pydantic import BaseModel, ConfigDict, Field
+
+from matchday.api_registry import register_api
+from matchday.errors import DegradeImmediately, MaxRetriesExceeded, retry_with_backoff
+from matchday.models import Amenity
+
+logger = logging.getLogger(__name__)
+
+# BC Place Stadium, Vancouver — anchor for every POI search.
+_BC_PLACE_LAT = 49.2827
+_BC_PLACE_LON = -123.1207
+_OVERPASS_URL = "https://overpass-api.de/api/interpreter"
+_USER_AGENT = (
+    "MatchDay/0.1 (FIFA 2026 Vancouver trip planner; "
+    "build-small-hackathon Space)"
+)
+# Food & drink amenities worth surfacing near a stadium on match day.
+_AMENITY_FILTER = "restaurant|cafe|bar|pub|fast_food|food_court"
+_MAX_RESULTS = 40
+_REQUEST_TIMEOUT = 25.0
+
+
+class POIInput(BaseModel):
+    """Input schema for the POI normalizer.
+
+    Accepts the full ``TripRequest`` dump (extra ignored); ``radius_km``
+    defaults to 1.0 km when absent (the whole-trip dispatch path omits it).
+    """
+
+    model_config = ConfigDict(extra="ignore")
+
+    radius_km: float = Field(default=1.0, ge=0.1, le=5.0)
+
+
+def _haversine_km(lat1: float, lon1: float, lat2: float, lon2: float) -> float:
+    """Great-circle distance in km between two lat/lon points."""
+    earth_radius_km = 6371.0088
+    phi1 = math.radians(lat1)
+    phi2 = math.radians(lat2)
+    d_phi = math.radians(lat2 - lat1)
+    d_lambda = math.radians(lon2 - lon1)
+    a = (
+        math.sin(d_phi / 2) ** 2
+        + math.cos(phi1) * math.cos(phi2) * math.sin(d_lambda / 2) ** 2
+    )
+    return 2 * earth_radius_km * math.asin(math.sqrt(a))
+
+
+def _build_query(radius_m: int) -> str:
+    """Build an Overpass QL query for food/drink nodes near BC Place."""
+    return (
+        "[out:json][timeout:25];"
+        "node[\"amenity\"~\""
+        + _AMENITY_FILTER
+        + "\"]"
+        + f"(around:{radius_m},{_BC_PLACE_LAT},{_BC_PLACE_LON});"
+        + f"out body {_MAX_RESULTS};"
+    )
+
+
+def _normalize(elements: list[dict[str, Any]]) -> list[Amenity]:
+    """Turn Overpass elements into distance-sorted ``Amenity`` models."""
+    fetched_at = datetime.now(timezone.utc)
+    out: list[Amenity] = []
+    for el in elements:
+        if el.get("type") != "node":
+            continue
+        tags = el.get("tags") or {}
+        name = tags.get("name")
+        category = tags.get("amenity")
+        if not name or not category:
+            continue  # unnamed / untagged nodes are useless to a traveler
+        lat = el.get("lat")
+        lon = el.get("lon")
+        if lat is None or lon is None:
+            continue
+        try:
+            out.append(
+                Amenity(
+                    name=name,
+                    category=category,
+                    distance_km=round(
+                        _haversine_km(_BC_PLACE_LAT, _BC_PLACE_LON, lat, lon), 3
+                    ),
+                    latitude=lat,
+                    longitude=lon,
+                    source="osm",
+                    as_of=fetched_at,
+                )
+            )
+        except (ValueError, TypeError) as exc:
+            logger.warning("Skipping POI %r: %s", name, exc)
+
+    out.sort(key=lambda a: a.distance_km)
+    return out
+
+
+@register_api(
+    "osm_amenities",
+    "amenities",
+    input_schema=POIInput,
+    output_schema=Amenity,
+    check_fn=lambda: True,  # keyless — always available
+    requires_env=[],
+    is_async=True,
+    description="Food/drink points of interest near BC Place via OpenStreetMap Overpass.",
+    emoji="🗺️",
+)
+async def fetch_pois(*, radius_km: float = 1.0, **_: Any) -> list[Amenity]:
+    """Fetch food/drink POIs near BC Place within ``radius_km``.
+
+    Returns a distance-sorted list of ``Amenity`` models (nearest first), or
+    ``[]`` on any failure — the registry wraps the result in an ``APIResult``.
+    """
+    radius_m = int(radius_km * 1000)
+    query = _build_query(radius_m)
+
+    async def _post() -> dict[str, Any]:
+        async with httpx.AsyncClient(
+            timeout=_REQUEST_TIMEOUT, headers={"User-Agent": _USER_AGENT}
+        ) as client:
+            resp = await client.post(_OVERPASS_URL, data={"data": query})
+            resp.raise_for_status()
+            return resp.json()
+
+    try:
+        data = await retry_with_backoff(
+            _post, max_retries=2, base_delay=2.0, max_delay=10.0
+        )
+    except (DegradeImmediately, MaxRetriesExceeded) as exc:
+        logger.warning("Overpass fetch degraded/exhausted: %s", exc)
+        return []
+    except Exception as exc:  # pragma: no cover — final safety net
+        logger.warning("Overpass unexpected error: %s", exc)
+        return []
+
+    elements = data.get("elements") or []
+    return _normalize(elements)

matchday/apis/weather.py

@@ -0,0 +1,182 @@
+"""Open-Meteo weather forecast normalizer (keyless — no API key required).
+
+Open-Meteo (https://api.open-meteo.com/v1/forecast) provides free, no-auth
+daily forecasts. We query Vancouver (BC Place Stadium) across the trip window
+and normalize the response into ``Weather`` models carrying inline provenance
+(``source="openmeteo"``, ``as_of=<fetch time>``).
+
+Plan alignment
+--------------
+- P3  full normalizer lifecycle (validate -> fetch -> classify -> normalize ->
+       attach provenance). Timeout + retry live inside this handler rather
+       than in a registry middleware layer (I5): smallest production-quality
+       approach that reuses ``errors.retry_with_backoff`` (N30) without a new
+       abstraction. Assumption noted in BUILD_PROGRESS.md.
+- U3  output budget: the response is already compact (one Weather per day); no
+       extra truncation needed here.
+- I2  (cache) + I4 (envelope provenance) are layered on in later slices.
+- Brain + Hands: Nemotron never fetches weather; Python does, deterministically.
+"""
+from __future__ import annotations
+
+import logging
+from datetime import date, datetime, timedelta, timezone
+from typing import Any
+
+import httpx
+from pydantic import BaseModel, ConfigDict
+
+from matchday.api_registry import register_api
+from matchday.errors import DegradeImmediately, MaxRetriesExceeded, retry_with_backoff
+from matchday.models import Weather
+
+logger = logging.getLogger(__name__)
+
+# Vancouver is this app's only destination (2026 FIFA World Cup host city).
+# BC Place Stadium coordinates — every forecast is anchored here.
+_BC_PLACE_LAT = 49.2827
+_BC_PLACE_LON = -123.1207
+_OPEN_METEO_URL = "https://api.open-meteo.com/v1/forecast"
+_DAILY_VARS = (
+    "temperature_2m_max",
+    "temperature_2m_min",
+    "precipitation_probability_max",
+    "weather_code",
+)
+# Open-Meteo's free forecast horizon is ~16 days FROM TODAY (it rejects
+# end_date beyond today+~16d with HTTP 400). Use 15 for a safety margin. The
+# window is clamped to this horizon; a wholly-out-of-range window degrades to [].
+_MAX_FORECAST_DAYS = 15
+_REQUEST_TIMEOUT = 20.0
+
+
+class WeatherInput(BaseModel):
+    """Input schema for the weather normalizer.
+
+    Accepts the full ``TripRequest`` dump (extra fields ignored) and uses only
+    the check-in / check-out window to bound the forecast range. Dates arrive
+    as ``date`` objects from ``TripRequest.model_dump()``.
+    """
+
+    model_config = ConfigDict(extra="ignore")
+
+    check_in: date
+    check_out: date
+
+
+def _clamp_window(check_in: date, check_out: date) -> tuple[date, date] | None:
+    """Bound the forecast window to Open-Meteo's today-relative horizon.
+
+    Open-Meteo rejects ``end_date`` beyond today+~16d (HTTP 400). Clamp ``end``
+    to the horizon; return ``None`` if the whole window is beyond it so the
+    caller degrades to ``[]`` gracefully. Match-day forecasts (the ones that
+    matter for the demo) survive as long as the match is within ~15 days.
+    """
+    horizon = date.today() + timedelta(days=_MAX_FORECAST_DAYS)
+    start = check_in
+    end = min(check_out, horizon)
+    if end < start:
+        return None
+    return start, end
+
+
+def _normalize(data: dict[str, Any]) -> list[Weather]:
+    """Turn an Open-Meteo daily payload into a list of ``Weather`` models.
+
+    Defensive against missing keys / null cells: Open-Meteo occasionally omits
+    a variable for a given day. Each row is built independently so one bad day
+    does not discard the whole forecast.
+    """
+    daily = data.get("daily") or {}
+    times: list[str] = daily.get("time") or []
+    if not times:
+        return []
+
+    t_max = daily.get("temperature_2m_max") or []
+    t_min = daily.get("temperature_2m_min") or []
+    precip = daily.get("precipitation_probability_max") or []
+    wcode = daily.get("weather_code") or []
+    fetched_at = datetime.now(timezone.utc)
+
+    out: list[Weather] = []
+    for i, day_str in enumerate(times):
+        try:
+            out.append(
+                Weather(
+                    date=date.fromisoformat(day_str),
+                    temp_max_c=float(t_max[i])
+                    if i < len(t_max) and t_max[i] is not None
+                    else 0.0,
+                    temp_min_c=float(t_min[i])
+                    if i < len(t_min) and t_min[i] is not None
+                    else 0.0,
+                    precipitation_probability=float(precip[i])
+                    if i < len(precip) and precip[i] is not None
+                    else 0.0,
+                    weather_code=int(wcode[i])
+                    if i < len(wcode) and wcode[i] is not None
+                    else 0,
+                    source="openmeteo",
+                    as_of=fetched_at,
+                )
+            )
+        except (ValueError, IndexError, TypeError) as exc:
+            logger.warning("Skipping weather day %r: %s", day_str, exc)
+
+    return out
+
+
+@register_api(
+    "openmeteo_weather",
+    "weather",
+    input_schema=WeatherInput,
+    output_schema=Weather,
+    check_fn=lambda: True,  # keyless — always available
+    requires_env=[],
+    is_async=True,
+    description="Daily weather forecast for Vancouver (BC Place) via Open-Meteo.",
+    emoji="🌤️",
+)
+async def fetch_weather(*, check_in: date, check_out: date, **_: Any) -> list[Weather]:
+    """Fetch the daily forecast for Vancouver across ``check_in..check_out``.
+
+    Returns a list of ``Weather`` models (one per day), or ``[]`` on any failure
+    — the registry still wraps the result in an ``APIResult`` envelope, so the
+    caller sees a clean success/failure signal rather than an exception.
+    """
+    window = _clamp_window(check_in, check_out)
+    if window is None:
+        logger.info(
+            "Trip window %s..%s beyond Open-Meteo horizon; no forecast.",
+            check_in,
+            check_out,
+        )
+        return []
+    start, end = window
+    params = {
+        "latitude": _BC_PLACE_LAT,
+        "longitude": _BC_PLACE_LON,
+        "daily": ",".join(_DAILY_VARS),
+        "start_date": start.isoformat(),
+        "end_date": end.isoformat(),
+        "timezone": "auto",
+    }
+
+    async def _get() -> dict[str, Any]:
+        async with httpx.AsyncClient(timeout=_REQUEST_TIMEOUT) as client:
+            resp = await client.get(_OPEN_METEO_URL, params=params)
+            resp.raise_for_status()
+            return resp.json()
+
+    try:
+        data = await retry_with_backoff(
+            _get, max_retries=2, base_delay=1.0, max_delay=8.0
+        )
+    except (DegradeImmediately, MaxRetriesExceeded) as exc:
+        logger.warning("Open-Meteo fetch degraded/exhausted: %s", exc)
+        return []
+    except Exception as exc:  # pragma: no cover — final safety net
+        logger.warning("Open-Meteo unexpected error: %s", exc)
+        return []
+
+    return _normalize(data)

matchday/apis/web.py

@@ -0,0 +1,89 @@
+"""SerpApi (Google Search) web-search normalizer, with graceful [] fallback.
+
+Supplemental data for the agent: match-schedule details, venue info, current
+events near the travel date. Returns compact ``{title, url, snippet}`` dicts
+(K6 budget: title|url|snippet[:160]). On any failure (no key, quota, network)
+it returns ``[]`` — web search is optional, so the pipeline never blocks on it.
+
+Plan alignment: P3 lifecycle, K6 compact serialization, A7 graceful degrade.
+Nemotron never fetches; Python does. Retry + timeout inside the handler.
+"""
+from __future__ import annotations
+
+import logging
+import os
+from typing import Any
+
+import httpx
+from pydantic import BaseModel, ConfigDict, Field
+
+from matchday.api_registry import register_api
+from matchday.errors import DegradeImmediately, MaxRetriesExceeded, retry_with_backoff
+
+logger = logging.getLogger(__name__)
+
+_SERPAPI_URL = "https://serpapi.com/search"
+_REQUEST_TIMEOUT = 30.0
+_SNIPPET_CAP = 160
+
+
+class WebSearchInput(BaseModel):
+    """Input for the web_search normalizer."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    query: str = Field(min_length=1, description="Search query string")
+    max_results: int = Field(default=5, ge=1, le=10)
+
+
+def _normalize(organic: list[dict[str, Any]] | None, max_results: int) -> list[dict[str, str]]:
+    out: list[dict[str, str]] = []
+    for r in (organic or [])[:max_results]:
+        title = (r.get("title") or "").strip()
+        url = (r.get("link") or r.get("url") or "").strip()
+        snippet = (r.get("snippet") or "").strip()[:_SNIPPET_CAP]
+        if title and url:
+            out.append({"title": title, "url": url, "snippet": snippet})
+    return out
+
+
+@register_api(
+    "serpapi_web_search",
+    "web_search",
+    input_schema=WebSearchInput,
+    check_fn=lambda: bool(os.getenv("SERPAPI_API_KEY")),
+    requires_env=["SERPAPI_API_KEY"],
+    is_async=True,
+    description="General web search via SerpApi (Google).",
+    emoji="🔍",
+)
+async def fetch_web_search(*, query: str, max_results: int = 5, **_: Any) -> list[dict[str, str]]:
+    """Fetch web results for ``query`` via SerpApi. Returns [] on any failure."""
+    key = os.getenv("SERPAPI_API_KEY")
+    if not key:
+        logger.info("No SERPAPI_API_KEY — web_search returning [].")
+        return []
+
+    params = {
+        "engine": "google",
+        "q": query,
+        "hl": "en",
+        "gl": "ca",
+        "api_key": key,
+    }
+
+    async def _get() -> dict[str, Any]:
+        async with httpx.AsyncClient(timeout=_REQUEST_TIMEOUT) as client:
+            resp = await client.get(_SERPAPI_URL, params=params)
+            resp.raise_for_status()
+            return resp.json()
+
+    try:
+        data = await retry_with_backoff(
+            _get, max_retries=1, base_delay=1.0, max_delay=4.0
+        )
+    except Exception as exc:
+        logger.warning("SerpApi web_search failed (%s); returning [].", exc)
+        return []
+
+    return _normalize(data.get("organic_results"), max_results)

matchday/app.py

@@ -0,0 +1,245 @@
+"""MatchDay — Gradio app for the 2026 FIFA World Cup in Vancouver.
+
+Agentic flow (primary): Nemotron (Brain, on Modal) decides which tool to call
+and extracts the trip intent -> Python (Hands) executes build_trip_packages and
+scores every price deterministically -> Nemotron writes the comparison. Falls
+back to the deterministic intent parser if the agent is unavailable or declines
+to call a tool, so the demo never breaks.
+
+Brain + Hands: Nemotron never calls an API or names a price; Python does. Every
+figure carries a provenance badge (live vs example).
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from datetime import date
+
+import gradio as gr
+
+from matchday.agent import MatchDayAgent
+from matchday.agent_loop import BuildTripPackagesArgs
+from matchday.intent import parse_intent
+from matchday.models import TripRequest
+from matchday.prompts import EXPLANATION_HINT
+from matchday.render import render_full
+from matchday.trip_tool import build_trip_packages, format_for_nemotron
+
+logger = logging.getLogger(__name__)
+
+# Nemotron primary, deterministic fallback. Flip to False to force the
+# deterministic path (useful if Modal is down or for a lightning-fast demo).
+USE_AGENT = True
+
+_HEADER = """
+<div style="font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif;
+            background:linear-gradient(135deg,#0f172a,#1e3a8a);color:#fff;
+            padding:22px 26px;border-radius:14px;margin-bottom:6px">
+  <div style="font-size:28px;font-weight:800;letter-spacing:-.02em">⚽ MatchDay</div>
+  <div style="font-size:14px;opacity:.88;margin-top:4px">
+    Your AI trip planner for the <b>2026 FIFA World Cup in Vancouver</b>.
+    Powered by Nemotron-3-Nano-30B (the brain) + deterministic Python (the hands)
+    on Modal. Tell me where you're flying from and which match — I'll build 3
+    ranked packages (flights · hotels · weather · what's near the stadium) with
+    <b>live data and honest provenance</b>.
+  </div>
+</div>
+"""
+
+_EXAMPLES = [
+    "Flying from Montreal, want Canada vs Qatar, mid-range, June 26-29, just me",
+    "I want to fly from Toronto to see Brazil vs Germany, premium, July 12, 2 adults",
+    "Take me from Ottawa to Vancouver for Canada vs Qatar on 2026-06-26, budget",
+    "From Halifax, Canada vs Morocco June 18, couple, luxury",
+]
+
+
+def _greenlight_html(summary: str) -> str:
+    return (
+        '<div style="font-family:-apple-system,Roboto,sans-serif;padding:12px 16px;'
+        'background:#f0fdf4;border:1px solid #bbf7d0;border-radius:12px;'
+        f'color:#166534;font-size:14px;margin:8px 0">✅ <b>Planning your trip:</b> '
+        f"{summary}</div>"
+    )
+
+
+def _clarify_html(question: str) -> str:
+    return (
+        '<div style="font-family:-apple-system,Roboto,sans-serif;padding:16px;'
+        'background:#eff6ff;border:1px solid #bfdbfe;border-radius:12px;'
+        f'color:#1e3a8a;font-size:15px">💬 {question}</div>'
+    )
+
+
+def _explain_html(text: str) -> str:
+    safe = text.replace("<", "&lt;").replace(">", "&gt;").replace("\n", "<br>")
+    return (
+        '<div style="font-family:-apple-system,Roboto,sans-serif;padding:14px 16px;'
+        'background:#f8fafc;border:1px solid #e2e8f0;border-radius:12px;'
+        f'color:#0f172a;font-size:14px;margin-top:10px;line-height:1.5">'
+        f'<b style="color:#1e3a8a">🤖 Nemotron compares your options:</b><br>{safe}</div>'
+    )
+
+
+def _fallback_note_html() -> str:
+    return (
+        '<div style="font-size:11px;color:#64748b;padding:4px 2px">'
+        "⚙️ agent offline — showing deterministic result.</div>"
+    )
+
+
+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).
+
+    Builds a tool_call/tool_result pair from the executed trip so Nemotron sees
+    the packages regardless of whether it or the deterministic parser drove the
+    build.
+    """
+    args_json = json.dumps(trip.model_dump(mode="json"))
+    convo = [
+        {"role": "user", "content": user_text},
+        {
+            "role": "assistant",
+            "content": "",
+            "tool_calls": [{
+                "id": "call_build",
+                "type": "function",
+                "function": {"name": "build_trip_packages", "arguments": args_json},
+            }],
+        },
+        {
+            "role": "tool",
+            "tool_call_id": "call_build",
+            "name": "build_trip_packages",
+            "content": format_for_nemotron(result),
+        },
+        {"role": "user", "content": EXPLANATION_HINT},
+    ]
+    try:
+        r2 = await agent.run(convo, tools=[])  # no tools -> Nemotron must write text
+        return (r2.get("text") or "").strip()
+    except Exception as exc:
+        logger.warning("explanation round failed: %s", exc)
+        return ""
+
+
+async def _agentic(user_text: str) -> str | None:
+    """Nemotron decides + explains, with a deterministic build safety net.
+
+    Nemotron (round 1) picks a tool. If it calls build_trip_packages we use its
+    args; if it clarifies/declines but the deterministic parser can still extract
+    a complete trip, we build anyway (the 30B model is sometimes over-cautious).
+    Only a genuinely incomplete request yields a clarifying question. Nemotron
+    always writes the final comparison (round 2).
+    """
+    try:
+        agent = MatchDayAgent()
+    except Exception as exc:
+        logger.warning("agent init failed (%s); deterministic fallback.", exc)
+        return None
+
+    base = [{"role": "user", "content": user_text}]
+    try:
+        r1 = await agent.run(base)
+    except Exception as exc:
+        logger.warning("agent round 1 failed (%s); deterministic fallback.", exc)
+        return None
+
+    tool_calls = r1.get("tool_calls") or []
+    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 as exc:
+            logger.warning("agent build_trip_packages args invalid (%s).", exc)
+
+    # Safety net: if Nemotron clarified/declined/gave bad args, try deterministic.
+    if trip is None:
+        parsed = parse_intent(user_text)
+        if parsed.trip_request is not None:
+            trip = parsed.trip_request
+
+    if trip is None:
+        # Genuinely incomplete: surface a clarifying question (Nemotron's, if any).
+        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
+        return _clarify_html(
+            clarify_q or "Tell me where you're flying from and which match you want to see."
+        )
+
+    try:
+        result = await build_trip_packages(trip)
+    except Exception as exc:
+        return _greenlight_html(trip.summary()) + f'<div style="color:#991b1b;padding:12px">⚠️ {exc}</div>'
+
+    explanation = await _agent_explain(agent, user_text, trip, result)
+    return (
+        _greenlight_html(trip.summary())
+        + render_full(result)
+        + (_explain_html(explanation) if explanation else "")
+    )
+
+
+async def _deterministic(user_text: str) -> str:
+    parsed = parse_intent(user_text)
+    if parsed.trip_request is None:
+        return _clarify_html(parsed.question)
+    greenlight = _greenlight_html(parsed.trip_request.summary())
+    try:
+        result = await build_trip_packages(parsed.trip_request)
+    except Exception as exc:
+        return greenlight + f'<div style="color:#991b1b;padding:12px">⚠️ {exc}</div>'
+    return greenlight + _fallback_note_html() + render_full(result)
+
+
+async def _plan(user_text: str) -> str:
+    if USE_AGENT:
+        html = await _agentic(user_text)
+        if html is not None:
+            return html
+    return await _deterministic(user_text)
+
+
+def plan_trip(user_text: str) -> str:
+    """Gradio handler (sync wrapper around the async agentic pipeline)."""
+    return asyncio.run(_plan(user_text))
+
+
+with gr.Blocks(title="MatchDay — FIFA World Cup Vancouver") as demo:
+    gr.HTML(_HEADER)
+    with gr.Row():
+        user_input = gr.Textbox(
+            label="Tell me about your trip",
+            placeholder="e.g. Flying from Montreal, want Canada vs Qatar, mid-range, June 26-29, just me",
+            lines=2,
+            value=_EXAMPLES[0],
+            scale=4,
+        )
+        plan_btn = gr.Button("🏈 Plan my trip", variant="primary", scale=1)
+    output = gr.HTML(label="Your trip packages")
+    gr.Examples(examples=_EXAMPLES, inputs=user_input)
+    plan_btn.click(fn=plan_trip, inputs=user_input, outputs=output)
+    user_input.submit(fn=plan_trip, inputs=user_input, outputs=output)
+
+
+if __name__ == "__main__":
+    demo.launch()

matchday/config.py

@@ -0,0 +1,40 @@
+"""Environment configuration for MatchDay.
+
+Loads ``matchday/.env`` into ``os.environ`` at import so the registry's
+``is_enabled()`` checks (which read ``os.environ``) see the API keys. Safe to
+import multiple times. Uses manual parsing — no python-dotenv dependency, so
+the HF Space runtime stays lightweight.
+
+Real environment variables always win over ``.env`` (``os.environ.setdefault``),
+so deployed Space secrets take precedence over the local file.
+"""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+_LOADED = False
+
+
+def load_env(path: str | os.PathLike | None = None) -> None:
+    """Populate ``os.environ`` from a ``.env`` file (idempotent)."""
+    global _LOADED
+    if _LOADED and path is None:
+        return
+
+    env_path = Path(path) if path else Path(__file__).resolve().parent / ".env"
+    if env_path.exists():
+        for line in env_path.read_text().splitlines():
+            line = line.strip()
+            if not line or line.startswith("#") or "=" not in line:
+                continue
+            key, value = line.split("=", 1)
+            key = key.strip()
+            value = value.strip().strip('"').strip("'")
+            os.environ.setdefault(key, value)
+
+    _LOADED = True
+
+
+# Load on import so any subsequent registry / normalizer code sees the keys.
+load_env()

matchday/errors.py

@@ -0,0 +1,733 @@
+"""
+MatchDay -- Error handling taxonomy, classification, and retry logic.
+
+Based on the hermes-agent error_classifier.py FailoverReason pattern and
+retry_utils.py jittered_backoff implementation.
+
+Architecture:
+  - FailoverReason enum: 22 types covering API, model, scoring, and network
+    failures, plus UNKNOWN as the final catch-all.
+  - ClassifiedError dataclass: Every exception is classified into one of these
+    types with a safe user_message, retry policy, and degradation flag.
+  - classify_error(): Maps Python exceptions + HTTP status codes to
+    ClassifiedError.
+  - jittered_backoff(): Exponential backoff with random jitter to prevent
+    thundering herd on shared infrastructure.
+  - retry_with_backoff(): Async retry loop that classifies, backs off, and
+    either retries or signals graceful degradation.
+  - GRACEFUL_DEGRADATION: Map from FailoverReason to user-facing messages.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import random
+import time
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Awaitable, Callable, TypeVar
+
+# ---------------------------------------------------------------------------
+# FailoverReason — exhaustive taxonomy of everything that can go wrong
+# ---------------------------------------------------------------------------
+
+
+class FailoverReason(Enum):
+    """Every failure mode the MatchDay system can encounter.
+
+    Naming convention: ``SOURCE_SPECIFIC_ERROR`` so callers can pattern-match
+    on the prefix for broad categories (API_*, MODEL_*, SCORING_*, NETWORK_*,
+    VALIDATION_*).
+    """
+
+    # ── API provider failures ────────────────────────────────────────────
+    API_RATE_LIMIT = "rate_limit"
+    """Provider returned HTTP 429 or equivalent rate-limit signal."""
+
+    API_AUTH = "api_auth"
+    """Provider returned HTTP 401/403 — key expired, revoked, or missing."""
+
+    API_TIMEOUT = "api_timeout"
+    """Provider did not respond within the configured timeout window."""
+
+    API_DOWN = "api_down"
+    """Provider returned HTTP 5xx or the endpoint is unreachable (DNS/TCP)."""
+
+    API_PARSE_ERROR = "api_parse_error"
+    """Provider returned a body that could not be parsed (malformed JSON,
+       unexpected schema, empty response)."""
+
+    API_QUOTA_EXCEEDED = "api_quota_exceeded"
+    """Provider returned HTTP 402/429 indicating the billing quota is
+       exhausted (distinct from transient rate-limiting)."""
+
+    API_INTERNAL_ERROR = "api_internal_error"
+    """Provider returned HTTP 500/502/503 with a server-side fault."""
+
+    # ── Model inference failures ─────────────────────────────────────────
+    MODEL_COLD_START = "model_cold_start"
+    """The ML model (Nemotron) is still loading — warmup not yet complete."""
+
+    MODEL_OOM = "model_oom"
+    """GPU out-of-memory during inference. Usually requires scale-down or
+       model restart."""
+
+    MODEL_MALFORMED_JSON = "model_malformed_json"
+    """Model output could not be parsed as valid JSON for structured
+       extraction."""
+
+    MODEL_TIMEOUT = "model_timeout"
+    """Inference exceeded the per-call timeout (usually 60-120s)."""
+
+    MODEL_EMPTY_RESPONSE = "model_empty_response"
+    """Model returned a zero-length or whitespace-only string."""
+
+    MODEL_CONTEXT_LENGTH = "model_context_length"
+    """Input exceeded the model's maximum context length (8,192 tokens for
+       the current Nemotron deployment)."""
+
+    MODEL_REPETITIVE = "model_repetitive"
+    """Model entered a repetition loop (same token sequence repeated 3+ times)
+       producing unusable output."""
+
+    # ── Scoring / ranking failures ───────────────────────────────────────
+    SCORING_EMPTY = "scoring_empty"
+    """No scored packages were produced — all flights/hotels were filtered
+       out or no trips matched the constraints."""
+
+    SCORING_ALL_LATE = "scoring_all_late"
+    """All candidate flights arrive after kickoff; no packages can be formed
+       with a non-negative arrival buffer."""
+
+    SCORING_MISSING_PRICES = "scoring_missing_prices"
+    """Essential price data is missing from the underlying API results
+       (e.g. all flights have price_cad=None), making scoring impossible."""
+
+    SCORING_NO_HOTELS = "scoring_no_hotels"
+    """No hotels were returned for the check-in/check-out window. Scoring
+       can still proceed with hotel=None, but the user should be warned."""
+
+    # ── Network / infrastructure failures ────────────────────────────────
+    NETWORK_ERROR = "network_error"
+    """Generic network failure (DNS resolution failure, connection refused,
+       SSL/TLS handshake error, connection reset)."""
+
+    NETWORK_TIMEOUT = "network_timeout"
+    """The TCP connection or TLS handshake timed out (not an API-level
+       timeout — occurred before the HTTP request was sent)."""
+
+    # ── Input / validation failures ──────────────────────────────────────
+    VALIDATION_ERROR = "validation_error"
+    """Input validation failed (e.g. Pydantic validation error, invalid
+       airport code, date outside World Cup window)."""
+
+    # ── Catch-all ────────────────────────────────────────────────────────
+    UNKNOWN = "unknown"
+    """An exception type that did not match any known classifier. Should be
+       logged and investigated; the system degrades gracefully."""
+
+
+# ---------------------------------------------------------------------------
+# ClassifiedError — structured error envelope
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class ClassifiedError:
+    """Every exception in the system is classified into this envelope.
+
+    The caller can inspect ``reason`` to decide on retry vs. degrade,
+    use ``user_message`` for safe UI display, and check ``should_degrade``
+    to bypass the retry loop and fall back to fixtures / partial results.
+    """
+
+    reason: FailoverReason
+    """The classified failure mode from the taxonomy above."""
+
+    message: str
+    """Detailed, developer-oriented diagnostic message (includes exception
+       repr, stack context, etc.). NOT safe for UI display."""
+
+    status_code: int | None
+    """HTTP status code when the failure originated from an API call,
+       or ``None`` for local errors (validation, model parsing, etc.)."""
+
+    retryable: bool
+    """``True`` when a retry with backoff is likely to succeed.
+       ``False`` when the error is permanent (auth failure, validation
+       error, malformed model output that won't change on re-run)."""
+
+    retry_after_seconds: float | None
+    """For rate-limited errors, the ``Retry-After`` header value from the
+       provider. ``None`` when no explicit retry-after is available — callers
+       should use jittered_backoff defaults instead."""
+
+    should_degrade: bool
+    """``True`` when the system should skip retries and fall back to
+       fixtures / partial results / cached data immediately. This is set
+       for permanent failures (auth, validation, malformed JSON) and for
+       errors where retrying is pointless (all flights late, no hotels)."""
+
+    user_message: str
+    """A safe, user-facing message that explains what happened without
+       exposing internal details (provider names, stack traces, API keys).
+       Display this in the UI when ``should_degrade`` is ``True``."""
+
+    timestamp: float = field(default_factory=time.time)
+    """Unix timestamp when this error was classified. Useful for logging
+       and for computing time-in-state in monitoring dashboards."""
+
+
+# ---------------------------------------------------------------------------
+# classify_error — map Python exceptions to ClassifiedError
+# ---------------------------------------------------------------------------
+
+
+# Sentinel object used to detect missing Retry-After header without
+# conflating None-as-not-provided with None-as-value.
+_MISSING = object()
+
+
+def classify_error(
+    exception: Exception,
+    status_code: int | None = None,
+    retry_after_header: str | None = None,
+) -> ClassifiedError:
+    """Map any Python exception to a ``ClassifiedError``.
+
+    Parameters
+    ----------
+    exception:
+        The caught exception to classify.
+    status_code:
+        HTTP status code if the error originated from an API response.
+        ``None`` for non-HTTP errors.
+    retry_after_header:
+        Raw ``Retry-After`` header value from the provider response, if
+        available. Parsed as seconds if present.
+
+    Returns
+    -------
+    ClassifiedError
+        Structured error envelope suitable for retry/ degrade decisions and
+        safe UI display.
+    """
+    # ---- Parse Retry-After header if present ----
+    retry_after: float | None = None
+    if retry_after_header is not None:
+        try:
+            retry_after = float(retry_after_header)
+        except (ValueError, TypeError):
+            retry_after = None
+
+    # ---- Re-classify an already classified error (pass-through) ----
+    if isinstance(exception, ClassifiedError):
+        return exception
+
+    exc_name = type(exception).__name__
+    exc_repr = repr(exception)
+
+    # ---- HTTP status-code-based classification ----
+    if status_code is not None:
+        return _classify_by_status(
+            exception, exc_name, exc_repr, status_code, retry_after
+        )
+
+    # ---- Exception-type-based classification ----
+    return _classify_by_exception(exception, exc_name, exc_repr, retry_after)
+
+
+def _classify_by_status(
+    exception: Exception,
+    exc_name: str,
+    exc_repr: str,
+    status_code: int,
+    retry_after: float | None,
+) -> ClassifiedError:
+    """Classify based on HTTP status code."""
+    # 429 — Rate limited
+    if status_code == 429:
+        return ClassifiedError(
+            reason=FailoverReason.API_RATE_LIMIT,
+            message=f"API rate limited (HTTP 429): {exc_repr}",
+            status_code=status_code,
+            retryable=True,
+            retry_after_seconds=retry_after,
+            should_degrade=False,
+            user_message="Too many requests. Retrying automatically...",
+        )
+
+    # 401, 403 — Auth failure (never retry)
+    if status_code in (401, 403):
+        return ClassifiedError(
+            reason=FailoverReason.API_AUTH,
+            message=f"API authentication failed (HTTP {status_code}): {exc_repr}",
+            status_code=status_code,
+            retryable=False,
+            retry_after_seconds=None,
+            should_degrade=True,
+            user_message="A service connection is misconfigured. Please try again later.",
+        )
+
+    # 402 — Payment / quota required
+    if status_code == 402:
+        return ClassifiedError(
+            reason=FailoverReason.API_QUOTA_EXCEEDED,
+            message=f"API quota exceeded (HTTP 402): {exc_repr}",
+            status_code=status_code,
+            retryable=False,
+            retry_after_seconds=retry_after,
+            should_degrade=True,
+            user_message="A search service has reached its monthly limit. Results may be incomplete.",
+        )
+
+    # 408 — Request timeout (retryable — could be transient)
+    if status_code == 408:
+        return ClassifiedError(
+            reason=FailoverReason.API_TIMEOUT,
+            message=f"API request timed out (HTTP 408): {exc_repr}",
+            status_code=status_code,
+            retryable=True,
+            retry_after_seconds=None,
+            should_degrade=False,
+            user_message="Search is taking longer than expected. Retrying...",
+        )
+
+    # 5xx — Server error (retryable)
+    if 500 <= status_code <= 599:
+        return ClassifiedError(
+            reason=FailoverReason.API_INTERNAL_ERROR,
+            message=f"API internal error (HTTP {status_code}): {exc_repr}",
+            status_code=status_code,
+            retryable=True,
+            retry_after_seconds=retry_after,
+            should_degrade=False,
+            user_message="A search service is temporarily unavailable. Retrying...",
+        )
+
+    # -- Any other non-2xx status --
+    return ClassifiedError(
+        reason=FailoverReason.API_DOWN,
+        message=f"API returned unexpected HTTP {status_code}: {exc_repr}",
+        status_code=status_code,
+        retryable=True,
+        retry_after_seconds=None,
+        should_degrade=False,
+        user_message="Unexpected response from search service. Retrying...",
+    )
+
+
+def _classify_by_exception(
+    exception: Exception,
+    exc_name: str,
+    exc_repr: str,
+    retry_after: float | None,
+) -> ClassifiedError:
+    """Classify based on exception type when no HTTP status code is available."""
+
+    # ---- Timeouts ----
+    # Note: asyncio.TimeoutError is a subclass of TimeoutError in 3.11+.
+    if isinstance(exception, TimeoutError):
+        return ClassifiedError(
+            reason=FailoverReason.NETWORK_TIMEOUT,
+            message=f"Connection timed out: {exc_repr}",
+            status_code=None,
+            retryable=True,
+            retry_after_seconds=None,
+            should_degrade=False,
+            user_message="Connection timed out. Retrying...",
+        )
+
+    # ---- Connection / network errors ----
+    # ConnectionError is the base for ConnectionRefusedError,
+    # ConnectionResetError, ConnectionAbortedError, etc.
+    # OSError covers DNS failures, "No route to host", etc.
+    if isinstance(exception, ConnectionError):
+        return ClassifiedError(
+            reason=FailoverReason.NETWORK_ERROR,
+            message=f"Connection error: {exc_repr}",
+            status_code=None,
+            retryable=True,
+            retry_after_seconds=None,
+            should_degrade=False,
+            user_message="Could not connect to a search service. Retrying...",
+        )
+
+    # OSError after checking ConnectionError subclasses above — catches
+    # "socket.gaierror", "EHOSTUNREACH", "ENETUNREACH", etc.
+    if isinstance(exception, OSError):
+        return ClassifiedError(
+            reason=FailoverReason.NETWORK_ERROR,
+            message=f"OS/network error: {exc_repr}",
+            status_code=None,
+            retryable=True,
+            retry_after_seconds=None,
+            should_degrade=False,
+            user_message="Network error. Retrying...",
+        )
+
+    # ---- JSON decode errors (API parse failure) ----
+    if isinstance(exception, (ValueError, json.JSONDecodeError)) and "JSON" in exc_name:
+        return ClassifiedError(
+            reason=FailoverReason.API_PARSE_ERROR,
+            message=f"Failed to parse API response: {exc_repr}",
+            status_code=None,
+            retryable=False,
+            retry_after_seconds=None,
+            should_degrade=True,
+            user_message="Received an unexpected response format. Please try again.",
+        )
+
+    # ---- General ValueError (likely data issues) ----
+    if isinstance(exception, ValueError):
+        return ClassifiedError(
+            reason=FailoverReason.VALIDATION_ERROR,
+            message=f"Validation error: {exc_repr}",
+            status_code=None,
+            retryable=False,
+            retry_after_seconds=None,
+            should_degrade=True,
+            user_message="Something didn't look right. Please refine your search.",
+        )
+
+    # ---- Type errors (programming bugs — never retry) ----
+    if isinstance(exception, TypeError):
+        return ClassifiedError(
+            reason=FailoverReason.VALIDATION_ERROR,
+            message=f"Type error: {exc_repr}",
+            status_code=None,
+            retryable=False,
+            retry_after_seconds=None,
+            should_degrade=True,
+            user_message="An internal error occurred. Please try again.",
+        )
+
+    # ---- KeyError / IndexError (data structure mismatches) ----
+    if isinstance(exception, (KeyError, IndexError)):
+        return ClassifiedError(
+            reason=FailoverReason.API_PARSE_ERROR,
+            message=f"Data structure error: {exc_repr}",
+            status_code=None,
+            retryable=False,
+            retry_after_seconds=None,
+            should_degrade=True,
+            user_message="Received unexpected data. Please try again.",
+        )
+
+    # ---- Unicode / encoding errors ----
+    if isinstance(exception, (UnicodeError, LookupError)):
+        return ClassifiedError(
+            reason=FailoverReason.API_PARSE_ERROR,
+            message=f"Encoding error: {exc_repr}",
+            status_code=None,
+            retryable=False,
+            retry_after_seconds=None,
+            should_degrade=True,
+            user_message="Received unreadable data. Please try again.",
+        )
+
+    # ---- Fallthrough: anything we haven't explicitly matched ----
+    return ClassifiedError(
+        reason=FailoverReason.UNKNOWN,
+        message=f"Unhandled exception ({exc_name}): {exc_repr}",
+        status_code=None,
+        retryable=False,
+        retry_after_seconds=None,
+        should_degrade=True,
+        user_message="An unexpected error occurred. Please try again.",
+    )
+
+
+# Import json module used in the classifier above
+import json  # noqa: E402 (imported here to keep it close to usage)
+
+
+# ---------------------------------------------------------------------------
+# jittered_backoff — exponential backoff with random jitter
+# ---------------------------------------------------------------------------
+
+
+def jittered_backoff(
+    attempt: int,
+    *,
+    base_delay: float = 5.0,
+    max_delay: float = 120.0,
+    jitter_ratio: float = 0.5,
+) -> float:
+    """Compute the sleep duration before retry attempt ``attempt``.
+
+    Uses exponential backoff with additive jitter (1-based exponent), matching
+    the hermes-agent retry_utils.py pattern:
+        delay = min(base_delay * 2 ** (attempt - 1), max_delay)
+        sleep = delay + random_uniform(0, jitter_ratio * delay)
+
+    This prevents the thundering herd problem: when N clients all fail at the
+    same time and retry, exponential backoff with additive jitter spreads
+    independently instead of having them all land at the same moments.
+
+    Parameters
+    ----------
+    attempt:
+        The retry attempt number (1-based). ``attempt=1`` is the first retry.
+    base_delay:
+        Base delay in seconds. Default 5.0.
+    max_delay:
+        Maximum delay cap in seconds. Default 120.0 (2 minutes).
+
+    Returns
+    -------
+    float
+        Seconds to sleep before the next retry.
+
+    Examples
+    --------
+    >>> import time
+    >>> sleep_for = jittered_backoff(attempt=1, base_delay=5.0)
+    >>> time.sleep(sleep_for)
+    """
+    delay = min(base_delay * (2 ** (attempt - 1)), max_delay)
+    jitter = random.uniform(0, jitter_ratio * delay)
+    return delay + jitter
+
+
+# ---------------------------------------------------------------------------
+# retry_with_backoff — async retry loop with graceful degradation
+# ---------------------------------------------------------------------------
+
+T = TypeVar("T")
+
+
+class MaxRetriesExceeded(Exception):
+    """Raised after ``max_retries`` attempts all failed.
+
+    The final ``ClassifiedError`` from the last attempt is stored in
+    ``.last_error``. The original exception is chained via ``.__cause__``.
+    Callers can inspect ``.last_error.reason`` to decide on degradation.
+    """
+
+    def __init__(self, last_error: ClassifiedError) -> None:
+        self.last_error = last_error
+        super().__init__(
+            f"Max retries exceeded. Last error: {last_error.reason.value} "
+            f"({last_error.message})"
+        )
+
+
+class DegradeImmediately(Exception):
+    """Raised when the first classification indicates immediate degradation.
+
+    This is a control-flow exception: it bypasses the retry loop and signals
+    the caller to fall back to fixtures / partial results. The attached
+    ``ClassifiedError`` describes why.
+    """
+
+    def __init__(self, classified: ClassifiedError) -> None:
+        self.classified = classified
+        self.reason = classified.reason
+        self.user_message = classified.user_message
+        super().__init__(classified.user_message)
+
+
+async def retry_with_backoff(
+    fn: Callable[..., Awaitable[T]],
+    max_retries: int = 3,
+    base_delay: float = 5.0,
+    max_delay: float = 120.0,
+    *args,
+    **kwargs,
+) -> T:
+    """Call ``fn(*args, **kwargs)`` with exponential backoff and retry logic.
+
+    On each failure the exception is classified via ``classify_error``.
+    Non-retryable or degradation-worthy errors raise ``DegradeImmediately``
+    to short-circuit the retry loop. Retryable errors back off with jitter
+    and then retry. After ``max_retries`` consecutive failures,
+    ``MaxRetriesExceeded`` is raised with the final ``ClassifiedError``
+    attached.
+
+    Parameters
+    ----------
+    fn:
+        An async callable to invoke and retry on failure.
+    max_retries:
+        Maximum number of retry attempts after the initial call (default 3).
+        Total calls = 1 initial + ``max_retries`` retries.
+    base_delay:
+        Base backoff delay in seconds (passed to ``jittered_backoff``).
+    max_delay:
+        Maximum backoff delay cap in seconds.
+    *args, **kwargs:
+        Forwarded to ``fn`` on every invocation.
+
+    Returns
+    -------
+    T
+        The return value of ``fn`` on success.
+
+    Raises
+    ------
+    DegradeImmediately
+        On the first failure, if the error is non-retryable or should
+        degrade (e.g. auth failure, validation error, malformed JSON).
+        The caller should catch this and switch to degraded mode.
+    MaxRetriesExceeded
+        After all retries are exhausted. The caller should catch this and
+        switch to degraded mode.
+
+    Examples
+    --------
+    .. code-block:: python
+
+        from matchday.errors import retry_with_backoff, DegradeImmediately, MaxRetriesExceeded
+
+        try:
+            result = await retry_with_backoff(
+                my_api_call, max_retries=2, arg1="foo"
+            )
+        except DegradeImmediately as exc:
+            logger.warning("Degrading: %s", exc.user_message)
+            result = fallback_fixture()
+        except MaxRetriesExceeded as exc:
+            logger.error("All retries failed: %s", exc.last_error.message)
+            result = fallback_fixture()
+    """
+    last_error: ClassifiedError | None = None
+    last_exception: BaseException | None = None
+
+    for attempt in range(1 + max_retries):
+        try:
+            return await fn(*args, **kwargs)
+        except DegradeImmediately as exc:
+            # Re-raise control-flow exceptions from nested retry calls.
+            raise
+        except Exception as exc:
+            classified = classify_error(exc)
+
+            # If this is the first attempt and we should degrade immediately,
+            # short-circuit — don't waste time retrying.
+            if attempt == 0 and classified.should_degrade:
+                raise DegradeImmediately(classified) from exc
+
+            last_error = classified
+            last_exception = exc
+
+            # Non-retryable errors on subsequent attempts also degrade.
+            if not classified.retryable:
+                raise DegradeImmediately(classified) from exc
+
+            # If we still have retries left, sleep with jittered backoff.
+            if attempt < max_retries:
+                # Respect provider-specified retry-after if present, otherwise
+                # use our own computed backoff.
+                delay = (
+                    classified.retry_after_seconds
+                    if classified.retry_after_seconds is not None
+                    else jittered_backoff(attempt + 1, base_delay=base_delay, max_delay=max_delay)
+                )
+                await asyncio.sleep(delay)
+
+    # All attempts exhausted.
+    raise MaxRetriesExceeded(last_error) from last_exception
+
+
+# ---------------------------------------------------------------------------
+# GRACEFUL_DEGRADATION — user-facing messages per failure mode
+# ---------------------------------------------------------------------------
+
+GRACEFUL_DEGRADATION: dict[FailoverReason, str] = {
+    # ── API provider failures ────────────────────────────────────────────
+    FailoverReason.API_RATE_LIMIT: (
+        "Live search temporarily unavailable. Showing example data."
+    ),
+    FailoverReason.API_AUTH: (
+        "A service connection is misconfigured. Showing example data."
+    ),
+    FailoverReason.API_TIMEOUT: (
+        "Search timed out. Results may be incomplete."
+    ),
+    FailoverReason.API_DOWN: (
+        "A search service is temporarily down. Showing example data."
+    ),
+    FailoverReason.API_PARSE_ERROR: (
+        "Received unexpected data from a search service. "
+        "Showing example data."
+    ),
+    FailoverReason.API_QUOTA_EXCEEDED: (
+        "A search service has reached its monthly limit. "
+        "Showing example data."
+    ),
+    FailoverReason.API_INTERNAL_ERROR: (
+        "A search service encountered an error. Retrying..."
+    ),
+    # ── Model inference failures ─────────────────────────────────────────
+    FailoverReason.MODEL_COLD_START: (
+        "Warming up our AI. This takes about 2 minutes..."
+    ),
+    FailoverReason.MODEL_OOM: (
+        "The AI model ran out of memory. Showing example data."
+    ),
+    FailoverReason.MODEL_MALFORMED_JSON: (
+        "Our AI produced unexpected output. Please try again."
+    ),
+    FailoverReason.MODEL_TIMEOUT: (
+        "AI response timed out. Please try again."
+    ),
+    FailoverReason.MODEL_EMPTY_RESPONSE: (
+        "AI returned no response. Please try again."
+    ),
+    FailoverReason.MODEL_CONTEXT_LENGTH: (
+        "Your request was too long. Please try a simpler search."
+    ),
+    FailoverReason.MODEL_REPETITIVE: (
+        "AI output was not usable. Please try again."
+    ),
+    # ── Scoring / ranking failures ───────────────────────────────────────
+    FailoverReason.SCORING_EMPTY: (
+        "No matching trips found. Try different dates or budget."
+    ),
+    FailoverReason.SCORING_ALL_LATE: (
+        "Flights arrive too close to kickoff. "
+        "Consider arriving a day earlier."
+    ),
+    FailoverReason.SCORING_MISSING_PRICES: (
+        "Price data is unavailable. Showing partial results."
+    ),
+    FailoverReason.SCORING_NO_HOTELS: (
+        "No hotels found for your dates. Showing flight-only options."
+    ),
+    # ── Network / infrastructure failures ────────────────────────────────
+    FailoverReason.NETWORK_ERROR: (
+        "Network connection issue. Please check your connection."
+    ),
+    FailoverReason.NETWORK_TIMEOUT: (
+        "Request timed out. Please check your connection."
+    ),
+    # ── Input / validation failures ──────────────────────────────────────
+    FailoverReason.VALIDATION_ERROR: (
+        "Something didn't look right. Please refine your search."
+    ),
+    # ── Catch-all ────────────────────────────────────────────────────────
+    FailoverReason.UNKNOWN: (
+        "An unexpected error occurred. Please try again."
+    ),
+}
+
+
+def user_message_for(reason: FailoverReason, fallback: str = "") -> str:
+    """Look up the user-facing message for a ``FailoverReason``.
+
+    Parameters
+    ----------
+    reason:
+        The failure reason to look up.
+    fallback:
+        Optional fallback string used when the reason is not found in the
+        degradation map (defensive — should never happen in practice since
+        the map covers all enum members).
+
+    Returns
+    -------
+    str
+        The user-safe message string.
+    """
+    return GRACEFUL_DEGRADATION.get(reason, fallback or reason.value.replace("_", " ").title())

matchday/file-listing-deepagents.txt

@@ -0,0 +1,713 @@
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/.DS_Store
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/.github/actions/uv_setup/action.yml
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/.github/CODEOWNERS
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/.github/dependabot.yml
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/.github/images/logo-dark.svg
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/.github/images/logo-light.svg
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/.github/ISSUE_TEMPLATE/bug-report.yml
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/.github/ISSUE_TEMPLATE/config.yml
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/.github/ISSUE_TEMPLATE/feature-request.yml
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/.github/ISSUE_TEMPLATE/privileged.yml
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/.github/PULL_REQUEST_TEMPLATE.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/.github/RELEASING.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/.github/scripts/aggregate_evals.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/.github/scripts/analyze_eval_failures.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/.github/scripts/check_extras_sync.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/.github/scripts/check_version_equality.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/.github/scripts/models.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/.github/scripts/pr-labeler-config.json
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/.github/scripts/pr-labeler.js
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/.github/scripts/test_release_options.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/.github/workflows/_benchmark.yml
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/.github/workflows/_lint.yml
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/.github/workflows/_test.yml
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/.github/workflows/auto-label-by-package.yml
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/.github/workflows/check_extras_sync.yml
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/.github/workflows/check_lockfiles.yml
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/.github/workflows/check_partner_bounds.yml
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/.github/workflows/check_sdk_pin.yml
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/.github/workflows/check_versions.yml
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/.github/workflows/ci.yml
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/.github/workflows/close_unchecked_issues.yml
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/.github/workflows/deepagents-example.yml.example
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/.github/workflows/evals.yml
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/.github/workflows/harbor.yml
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/.github/workflows/integration_tests.yml
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/.github/workflows/pr_labeler_backfill.yml
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/.github/workflows/pr_labeler.yml
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/.github/workflows/pr_lint.yml
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/.github/workflows/release-please.yml
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/.github/workflows/release.yml
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/.github/workflows/reopen_on_assignment.yml
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/.github/workflows/require_issue_link.yml
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/.github/workflows/sync_priority_labels.yml
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/.github/workflows/tag-external-issues.yml
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/.gitignore
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/.markdownlint.json
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/.mcp.json
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/.pre-commit-config.yaml
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/.release-please-manifest.json
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/.vscode/extensions.json
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/.vscode/settings.json
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/action.yml
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/AGENTS.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/.DS_Store
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/async-subagent-server/.env.example
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/async-subagent-server/pyproject.toml
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/async-subagent-server/README.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/async-subagent-server/server.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/async-subagent-server/supervisor.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/async-subagent-server/test_server.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/async-subagent-server/uv.lock
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/better-harness/.DS_Store
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/better-harness/.gitignore
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/better-harness/better_harness_optimization.svg
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/better-harness/better_harness_plugin.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/better-harness/better_harness/__init__.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/better-harness/better_harness/agent.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/better-harness/better_harness/core.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/better-harness/better_harness/patching.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/better-harness/better_harness/runners.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/better-harness/examples/deepagents_example.toml
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/better-harness/pyproject.toml
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/better-harness/README.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/better-harness/tests/__init__.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/better-harness/tests/test_better_harness.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/better-harness/uv.lock
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/content-builder-agent/.gitignore
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/content-builder-agent/AGENTS.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/content-builder-agent/content_writer.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/content-builder-agent/pyproject.toml
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/content-builder-agent/README.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/content-builder-agent/skills/blog-post/SKILL.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/content-builder-agent/skills/social-media/SKILL.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/content-builder-agent/subagents.yaml
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/content-builder-agent/uv.lock
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/deep_research/.env.example
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/deep_research/agent.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/deep_research/langgraph.json
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/deep_research/pyproject.toml
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/deep_research/README.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/deep_research/research_agent.ipynb
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/deep_research/research_agent/__init__.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/deep_research/research_agent/prompts.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/deep_research/research_agent/tools.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/deep_research/utils.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/deep_research/uv.lock
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/deploy-coding-agent/.env.example
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/deploy-coding-agent/AGENTS.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/deploy-coding-agent/deepagents.assistant-scope.toml
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/deploy-coding-agent/deepagents.toml
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/deploy-coding-agent/mcp.json
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/deploy-coding-agent/README.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/deploy-coding-agent/skills/code-review/lint_check.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/deploy-coding-agent/skills/code-review/SKILL.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/deploy-coding-agent/skills/coding-prefs/SKILL.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/deploy-coding-agent/skills/planning/SKILL.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/deploy-content-writer/.env.example
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/deploy-content-writer/AGENTS.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/deploy-content-writer/deepagents.toml
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/deploy-content-writer/README.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/deploy-content-writer/skills/blog-post/SKILL.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/deploy-content-writer/skills/social-media/SKILL.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/deploy-content-writer/test_user_memory.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/deploy-content-writer/user/AGENTS.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/deploy-gtm-agent/AGENTS.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/deploy-gtm-agent/deepagents.toml
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/deploy-gtm-agent/mcp.json
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/deploy-gtm-agent/README.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/deploy-gtm-agent/skills/competitor-analysis/SKILL.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/deploy-gtm-agent/subagents/market-researcher/AGENTS.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/deploy-gtm-agent/subagents/market-researcher/deepagents.toml
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/deploy-gtm-agent/subagents/market-researcher/skills/analyze-market/SKILL.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/deploy-mcp-docs-agent/AGENTS.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/deploy-mcp-docs-agent/deepagents.toml
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/deploy-mcp-docs-agent/mcp.json
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/deploy-mcp-docs-agent/README.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/downloading_agents/content-writer.zip
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/downloading_agents/README.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/nvidia_deep_agent/.env.example
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/nvidia_deep_agent/.gitignore
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/nvidia_deep_agent/langgraph.json
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/nvidia_deep_agent/pyproject.toml
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/nvidia_deep_agent/README.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/nvidia_deep_agent/skills/cudf-analytics/SKILL.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/nvidia_deep_agent/skills/cuml-machine-learning/SKILL.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/nvidia_deep_agent/skills/data-visualization/SKILL.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/nvidia_deep_agent/skills/gpu-document-processing/SKILL.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/nvidia_deep_agent/src/__init__.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/nvidia_deep_agent/src/agent.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/nvidia_deep_agent/src/AGENTS.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/nvidia_deep_agent/src/backend.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/nvidia_deep_agent/src/prompts.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/nvidia_deep_agent/src/tools.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/nvidia_deep_agent/uv.lock
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/ralph_mode/ralph_mode_diagram.png
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/ralph_mode/ralph_mode.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/ralph_mode/README.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/README.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/repl_swarm/pyproject.toml
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/repl_swarm/README.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/repl_swarm/skills/swarm/index.ts
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/repl_swarm/skills/swarm/SKILL.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/repl_swarm/swarm_agent.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/repl_swarm/uv.lock
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/rlm_agent/pyproject.toml
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/rlm_agent/README.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/rlm_agent/rlm_agent.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/rlm_agent/uv.lock
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/text-to-sql-agent/.env.example
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/text-to-sql-agent/.gitignore
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/text-to-sql-agent/agent.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/text-to-sql-agent/AGENTS.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/text-to-sql-agent/pyproject.toml
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/text-to-sql-agent/README.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/text-to-sql-agent/skills/query-writing/SKILL.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/text-to-sql-agent/skills/schema-exploration/SKILL.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/text-to-sql-agent/text-to-sql-langsmith-trace.png
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/examples/text-to-sql-agent/uv.lock
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/acp/.env.example
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/acp/CHANGELOG.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/acp/deepagents_acp/__init__.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/acp/deepagents_acp/__main__.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/acp/deepagents_acp/_version.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/acp/deepagents_acp/py.typed.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/acp/deepagents_acp/server.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/acp/deepagents_acp/utils.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/acp/examples/__init__.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/acp/examples/demo_agent.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/acp/examples/local_context.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/acp/Makefile
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/acp/pyproject.toml
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/acp/README.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/acp/run_demo_agent.sh
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/acp/static/img/deepagentsacp.gif
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/acp/static/img/newdeepagent.png
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/acp/tests/__init__.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/acp/tests/chat_model.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/acp/tests/test_agent.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/acp/tests/test_command_allowlist.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/acp/tests/test_dangerous_patterns.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/acp/tests/test_main.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/acp/tests/test_model_switching.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/acp/tests/test_utils.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/acp/uv.lock
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/CHANGELOG.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/__init__.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/__main__.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/_ask_user_types.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/_cli_context.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/_debug.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/_env_vars.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/_git.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/_server_config.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/_session_stats.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/_testing_models.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/_textual_patches.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/_version.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/agent.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/app.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/app.tcss
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/ask_user.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/built_in_skills/__init__.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/built_in_skills/remember/SKILL.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/built_in_skills/skill-creator/scripts/init_skill.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/built_in_skills/skill-creator/scripts/quick_validate.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/built_in_skills/skill-creator/SKILL.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/clipboard.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/command_registry.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/config.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/configurable_model.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/default_agent_prompt.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/deploy/__init__.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/deploy/bundler.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/deploy/commands.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/deploy/config.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/deploy/templates.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/editor.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/extras_info.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/file_ops.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/formatting.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/hooks.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/input.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/integrations/__init__.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/integrations/sandbox_factory.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/integrations/sandbox_provider.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/local_context.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/main.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/mcp_tools.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/mcp_trust.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/media_utils.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/model_config.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/non_interactive.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/notifications.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/offload.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/output.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/project_utils.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/py.typed
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/remote_client.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/server_graph.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/server_manager.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/server.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/sessions.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/skills/__init__.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/skills/commands.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/skills/invocation.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/skills/load.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/subagents.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/system_prompt.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/terminal_capabilities.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/textual_adapter.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/theme.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/token_state.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/tool_display.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/tools.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/ui.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/unicode_security.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/update_check.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/widgets/__init__.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/widgets/_links.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/widgets/agent_selector.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/widgets/approval.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/widgets/ask_user.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/widgets/autocomplete.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/widgets/chat_input.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/widgets/diff.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/widgets/history.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/widgets/loading.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/widgets/mcp_viewer.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/widgets/message_store.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/widgets/messages.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/widgets/model_selector.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/widgets/notification_center.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/widgets/notification_detail.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/widgets/notification_settings.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/widgets/status.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/widgets/theme_selector.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/widgets/thread_selector.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/widgets/tool_renderers.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/widgets/tool_widgets.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/widgets/update_available.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/deepagents_cli/widgets/welcome.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/DEV.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/examples/deploy-content-writer/.env.example
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/examples/deploy-content-writer/skills/blog-post/SKILL.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/examples/deploy-content-writer/skills/social-media/SKILL.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/examples/deploy-content-writer/user/context.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/examples/deploy-content-writer/user/preferences.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/examples/skills/arxiv-search/arxiv_search.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/examples/skills/arxiv-search/SKILL.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/examples/skills/langgraph-docs/SKILL.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/examples/skills/skill-creator/scripts/init_skill.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/examples/skills/skill-creator/scripts/quick_validate.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/examples/skills/skill-creator/SKILL.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/examples/skills/web-research/SKILL.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/images/cli.png
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/Makefile
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/pyproject.toml
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/README.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/scripts/check_imports.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/scripts/debug_server.sh
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/scripts/install.sh
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/integration_tests/__init__.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/integration_tests/benchmarks/__init__.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/integration_tests/benchmarks/test_codspeed_import_benchmarks.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/integration_tests/benchmarks/test_startup_benchmarks.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/integration_tests/conftest.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/integration_tests/test_acp_mode.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/integration_tests/test_compact_resume.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/integration_tests/test_sandbox_factory.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/integration_tests/test_sandbox_operations.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/README.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/__init__.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/conftest.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/deploy/__init__.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/deploy/test_bundler.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/deploy/test_commands.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/deploy/test_config.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/skills/__init__.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/skills/test_commands.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/skills/test_load.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/skills/test_skills_json.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_agent_friendly.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_agent_selector.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_agent.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_app.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_approval.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_args.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_ask_user_middleware.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_ask_user.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_autocomplete.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_charset.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_chat_input.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_command_registry.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_compact_tool.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_config.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_configurable_model.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_debug.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_editor.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_end_to_end.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_env_vars.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_exception_handling.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_extras_info.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_file_ops.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_formatting.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_git.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_history.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_hooks.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_imports.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_input_parsing.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_links.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_loading.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_local_context.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_main_acp_mode.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_main_args.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_main.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_mcp_tools.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_mcp_trust.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_mcp_viewer.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_media_utils.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_message_store.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_messages.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_model_config.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_model_selector.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_model_switch.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_non_interactive.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_notification_center.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_notification_detail.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_notifications.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_offload_dict_messages.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_offload.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_output.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_reload.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_remote_client.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_sandbox_factory.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_server_config.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_server_graph.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_server_helpers.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_server_manager.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_server.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_session_stats.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_sessions.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_shell_allow_list.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_skill_invocation.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_status.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_subagents.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_terminal_capabilities.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_textual_adapter.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_textual_patches.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_theme.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_thread_selector.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_token_tracker.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_tool_display.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_ui.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_unicode_security.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_update_available.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_update_check.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_version.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/test_welcome.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/tools/__init__.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/tests/unit_tests/tools/test_fetch_url.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/THREAT_MODEL.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/cli/uv.lock
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/CHANGELOG.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/deepagents/__init__.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/deepagents/_models.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/deepagents/_version.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/deepagents/backends/__init__.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/deepagents/backends/composite.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/deepagents/backends/filesystem.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/deepagents/backends/langsmith.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/deepagents/backends/local_shell.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/deepagents/backends/protocol.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/deepagents/backends/sandbox.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/deepagents/backends/state.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/deepagents/backends/store.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/deepagents/backends/utils.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/deepagents/graph.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/deepagents/middleware/__init__.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/deepagents/middleware/_tool_exclusion.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/deepagents/middleware/_utils.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/deepagents/middleware/async_subagents.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/deepagents/middleware/filesystem.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/deepagents/middleware/memory.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/deepagents/middleware/patch_tool_calls.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/deepagents/middleware/permissions.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/deepagents/middleware/skills.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/deepagents/middleware/subagents.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/deepagents/middleware/summarization.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/deepagents/profiles/__init__.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/deepagents/profiles/_harness_profiles.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/deepagents/profiles/_openai.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/deepagents/profiles/_openrouter.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/deepagents/py.typed
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/Makefile
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/pyproject.toml
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/README.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/scripts/check_imports.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/tests/__init__.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/tests/benchmarks/__init__.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/tests/benchmarks/test_benchmark_create_deep_agent.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/tests/integration_tests/__init__.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/tests/integration_tests/test_deepagents.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/tests/integration_tests/test_filesystem_middleware.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/tests/integration_tests/test_langsmith_sandbox.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/tests/integration_tests/test_subagent_middleware.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/tests/README.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/tests/unit_tests/__init__.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/tests/unit_tests/backends/__init__.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/tests/unit_tests/backends/test_backwards_compat.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/tests/unit_tests/backends/test_composite_backend_async.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/tests/unit_tests/backends/test_composite_backend.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/tests/unit_tests/backends/test_file_format.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/tests/unit_tests/backends/test_files_update_deprecation.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/tests/unit_tests/backends/test_filesystem_backend_async.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/tests/unit_tests/backends/test_filesystem_backend.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/tests/unit_tests/backends/test_langsmith_sandbox.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/tests/unit_tests/backends/test_local_shell_backend.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/tests/unit_tests/backends/test_protocol.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/tests/unit_tests/backends/test_sandbox_backend.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/tests/unit_tests/backends/test_state_backend_async.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/tests/unit_tests/backends/test_state_backend.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/tests/unit_tests/backends/test_store_backend_async.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/tests/unit_tests/backends/test_store_backend.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/tests/unit_tests/backends/test_timeout_compat.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/tests/unit_tests/backends/test_utils.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/tests/unit_tests/chat_model.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/tests/unit_tests/middleware/__init__.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/tests/unit_tests/middleware/test_compact_tool.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/tests/unit_tests/middleware/test_filesystem_middleware_init.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/tests/unit_tests/middleware/test_memory_middleware_async.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/tests/unit_tests/middleware/test_memory_middleware.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/tests/unit_tests/middleware/test_skills_middleware_async.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/tests/unit_tests/middleware/test_skills_middleware.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/tests/unit_tests/middleware/test_subagent_middleware_init.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/tests/unit_tests/middleware/test_summarization_factory.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/tests/unit_tests/middleware/test_summarization_middleware.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/tests/unit_tests/middleware/test_tool_schemas.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/tests/unit_tests/smoke_tests/__init__.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/tests/unit_tests/smoke_tests/conftest.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/tests/unit_tests/smoke_tests/snapshots/custom_system_message_tools.json
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/tests/unit_tests/smoke_tests/snapshots/custom_system_message.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/tests/unit_tests/smoke_tests/snapshots/system_prompt_with_execute_tools.json
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/tests/unit_tests/smoke_tests/snapshots/system_prompt_with_execute.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/tests/unit_tests/smoke_tests/snapshots/system_prompt_with_memory_and_skills_tools.json
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/tests/unit_tests/smoke_tests/snapshots/system_prompt_with_memory_and_skills.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/tests/unit_tests/smoke_tests/snapshots/system_prompt_with_sync_and_async_subagents_tools.json
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/tests/unit_tests/smoke_tests/snapshots/system_prompt_with_sync_and_async_subagents.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/tests/unit_tests/smoke_tests/snapshots/system_prompt_without_execute_tools.json
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/tests/unit_tests/smoke_tests/snapshots/system_prompt_without_execute.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/tests/unit_tests/smoke_tests/test_system_prompt.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/tests/unit_tests/test_artifacts_root.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/tests/unit_tests/test_async_subagents.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/tests/unit_tests/test_end_to_end.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/tests/unit_tests/test_file_system_tools_async.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/tests/unit_tests/test_file_system_tools.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/tests/unit_tests/test_graph.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/tests/unit_tests/test_local_sandbox_operations.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/tests/unit_tests/test_local_shell.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/tests/unit_tests/test_middleware_async.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/tests/unit_tests/test_middleware.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/tests/unit_tests/test_models.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/tests/unit_tests/test_permissions.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/tests/unit_tests/test_subagents.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/tests/unit_tests/test_timing.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/tests/unit_tests/test_todo_middleware.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/tests/unit_tests/test_version.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/tests/utils.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/THREAT_MODEL.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/deepagents/uv.lock
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/CONTRIBUTING.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/deepagents_evals/__init__.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/deepagents_evals/categories.json
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/deepagents_evals/radar.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/deepagents_harbor/__init__.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/deepagents_harbor/backend.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/deepagents_harbor/deepagents_wrapper.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/deepagents_harbor/failure.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/deepagents_harbor/langsmith_environment.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/deepagents_harbor/langsmith.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/deepagents_harbor/metadata.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/deepagents_harbor/stats.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/EVAL_CATALOG.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/Makefile
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/MODEL_GROUPS.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/pyproject.toml
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/README.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/scripts/analyze.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/scripts/generate_eval_catalog.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/scripts/generate_model_groups.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/scripts/generate_radar.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/scripts/harbor_langsmith.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/tests/__init__.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/tests/evals/__init__.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/tests/evals/conftest.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/tests/evals/data/benchmark_samples/bfcl_v3_final.json
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/tests/evals/data/benchmark_samples/frames_final.json
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/tests/evals/data/benchmark_samples/nexus_final.json
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/tests/evals/data/bfcl_apis/__init__.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/tests/evals/data/bfcl_apis/long_context.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/tests/evals/data/bfcl_apis/message_api.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/tests/evals/data/bfcl_apis/ticket_api.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/tests/evals/data/bfcl_apis/trading_bot.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/tests/evals/data/bfcl_apis/travel_booking.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/tests/evals/data/bfcl_apis/vehicle_control.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/tests/evals/external_benchmarks.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/tests/evals/fixtures/summarization_seed_messages.json
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/tests/evals/llm_judge.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/tests/evals/memory_agent_bench/__init__.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/tests/evals/memory_agent_bench/configs.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/tests/evals/memory_agent_bench/data_utils.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/tests/evals/memory_agent_bench/eval_utils.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/tests/evals/memory_agent_bench/test_memory_agent_bench.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/tests/evals/pytest_reporter.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/tests/evals/README.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/tests/evals/tau2_airline/__init__.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/tests/evals/tau2_airline/data/db.json
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/tests/evals/tau2_airline/data/policy.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/tests/evals/tau2_airline/data/tasks.json
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/tests/evals/tau2_airline/domain.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/tests/evals/tau2_airline/evaluation.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/tests/evals/tau2_airline/LICENSE
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/tests/evals/tau2_airline/runner.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/tests/evals/tau2_airline/test_tau2_airline.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/tests/evals/tau2_airline/user_sim.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/tests/evals/test__reporter_sample.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/tests/evals/test_external_benchmarks.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/tests/evals/test_file_operations.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/tests/evals/test_followup_quality.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/tests/evals/test_hitl.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/tests/evals/test_memory_multiturn.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/tests/evals/test_memory.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/tests/evals/test_skills.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/tests/evals/test_subagents.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/tests/evals/test_summarization.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/tests/evals/test_system_prompt.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/tests/evals/test_todos.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/tests/evals/test_tool_selection.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/tests/evals/test_tool_usage_incident_graph.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/tests/evals/test_tool_usage_relational.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/tests/evals/utils.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/tests/unit_tests/__init__.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/tests/unit_tests/test_analyze_eval_failures.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/tests/unit_tests/test_category_tagging.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/tests/unit_tests/test_eval_catalog.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/tests/unit_tests/test_external_benchmark_helpers.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/tests/unit_tests/test_generate_radar_script.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/tests/unit_tests/test_harbor_backend.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/tests/unit_tests/test_imports.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/tests/unit_tests/test_infra.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/tests/unit_tests/test_langsmith_environment.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/tests/unit_tests/test_langsmith.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/tests/unit_tests/test_model_groups.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/tests/unit_tests/test_pytest_reporter.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/tests/unit_tests/test_radar.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/tests/unit_tests/test_trajectory.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/evals/uv.lock
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/Makefile
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/daytona/CHANGELOG.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/daytona/langchain_daytona/__init__.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/daytona/langchain_daytona/_version.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/daytona/langchain_daytona/sandbox.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/daytona/LICENSE
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/daytona/Makefile
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/daytona/pyproject.toml
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/daytona/README.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/daytona/tests/__init__.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/daytona/tests/integration_tests/__init__.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/daytona/tests/integration_tests/test_integration.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/daytona/tests/test_import.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/daytona/tests/unit_tests/__init__.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/daytona/tests/unit_tests/test_import.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/daytona/uv.lock
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/modal/CHANGELOG.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/modal/langchain_modal/__init__.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/modal/langchain_modal/_version.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/modal/langchain_modal/sandbox.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/modal/LICENSE
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/modal/Makefile
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/modal/pyproject.toml
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/modal/README.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/modal/tests/__init__.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/modal/tests/integration_tests/__init__.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/modal/tests/integration_tests/test_integration.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/modal/tests/test_import.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/modal/tests/unit_tests/__init__.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/modal/tests/unit_tests/test_import.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/modal/uv.lock
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/quickjs/CHANGELOG.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/quickjs/langchain_quickjs/__init__.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/quickjs/langchain_quickjs/_format.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/quickjs/langchain_quickjs/_prompt.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/quickjs/langchain_quickjs/_ptc.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/quickjs/langchain_quickjs/_repl.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/quickjs/langchain_quickjs/_skills.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/quickjs/langchain_quickjs/middleware.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/quickjs/langchain_quickjs/py.typed
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/quickjs/LICENSE
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/quickjs/Makefile
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/quickjs/pyproject.toml
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/quickjs/README.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/quickjs/tests/__init__.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/quickjs/tests/integration_tests/__init__.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/quickjs/tests/integration_tests/test_rlm.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/quickjs/tests/unit_tests/__init__.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/quickjs/tests/unit_tests/smoke_tests/__init__.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/quickjs/tests/unit_tests/smoke_tests/conftest.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/quickjs/tests/unit_tests/smoke_tests/snapshots/quickjs_system_prompt_mixed_foreign_functions.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/quickjs/tests/unit_tests/smoke_tests/snapshots/quickjs_system_prompt_no_tools.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/quickjs/tests/unit_tests/smoke_tests/test_system_prompt.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/quickjs/tests/unit_tests/test_end_to_end_async.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/quickjs/tests/unit_tests/test_end_to_end.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/quickjs/tests/unit_tests/test_ptc.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/quickjs/tests/unit_tests/test_repl_middleware.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/quickjs/tests/unit_tests/test_skills_integration.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/quickjs/tests/unit_tests/test_skills.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/quickjs/uv.lock
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/runloop/CHANGELOG.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/runloop/langchain_runloop/__init__.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/runloop/langchain_runloop/_version.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/runloop/langchain_runloop/sandbox.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/runloop/LICENSE
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/runloop/Makefile
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/runloop/pyproject.toml
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/runloop/README.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/runloop/tests/__init__.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/runloop/tests/integration_tests/__init__.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/runloop/tests/integration_tests/test_integration.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/runloop/tests/test_import.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/runloop/tests/unit_tests/__init__.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/runloop/tests/unit_tests/test_import.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/partners/runloop/uv.lock
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/README.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/repl/CHANGELOG.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/repl/langchain_repl/__init__.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/repl/langchain_repl/_foreign_function_docs.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/repl/langchain_repl/_version.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/repl/langchain_repl/interpreter.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/repl/langchain_repl/middleware.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/repl/LICENSE
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/repl/Makefile
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/repl/pyproject.toml
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/repl/README.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/repl/tests/__init__.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/repl/tests/benchmarks/test_benchmark_interpreter.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/repl/tests/unit_tests/__init__.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/repl/tests/unit_tests/chat_model.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/repl/tests/unit_tests/smoke_tests/__init__.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/repl/tests/unit_tests/smoke_tests/conftest.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/repl/tests/unit_tests/smoke_tests/snapshots/langchain_repl_system_prompt_mixed_foreign_functions_old.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/repl/tests/unit_tests/smoke_tests/snapshots/langchain_repl_system_prompt_mixed_foreign_functions.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/repl/tests/unit_tests/smoke_tests/snapshots/langchain_repl_system_prompt_no_tools_old.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/repl/tests/unit_tests/smoke_tests/snapshots/langchain_repl_system_prompt_no_tools.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/repl/tests/unit_tests/smoke_tests/test_system_prompt.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/repl/tests/unit_tests/test_end_to_end_async.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/repl/tests/unit_tests/test_end_to_end.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/repl/tests/unit_tests/test_foreign_function_docs.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/repl/tests/unit_tests/test_import.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/repl/tests/unit_tests/test_interpreter.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/repl/tests/unit_tests/test_system_prompt.py
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/libs/repl/uv.lock
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/LICENSE
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/README.md
+/Users/mmz_10/Desktop/Telecom/context-other-codebases/deepagents-main/release-please-config.json

matchday/fixtures.py

@@ -0,0 +1,115 @@
+"""Fallback fixture data for MatchDay (graceful degradation).
+
+When a live provider is unavailable — no API key, quota exhausted, network
+failure, or unparseable response — the SerpApi normalizers fall back to these
+realistic Vancouver World Cup fixtures so the pipeline always produces scored
+packages and the demo never crashes.
+
+Provenance is HONEST: every fixture carries ``source="fallback"`` and a fixed
+``as_of`` sentinel, so the frontend can clearly mark it as example data rather
+than live. This is the plan's A7/I4 fixture-fallback contract: live data when
+available, deterministic example data otherwise, always labelled.
+
+Fixtures are deterministic (no randomness) so demos and tests reproduce.
+"""
+from __future__ import annotations
+
+from datetime import date, datetime, timezone
+from zoneinfo import ZoneInfo
+
+from matchday.models import Flight, Hotel
+
+# Vancouver time zone (PDT, UTC-7, during the 2026 World Cup).
+_VANCOUVER = ZoneInfo("America/Vancouver")
+# Fixed "static" timestamp marking fixture (non-live) data.
+_STATIC_AS_OF = datetime(2026, 6, 1, 0, 0, 0, tzinfo=timezone.utc)
+_YVR = "YVR"
+
+
+# Realistic hotels near BC Place Stadium. ``dist_km`` is approximate
+# straight-line distance to the stadium. Per-night rates in CAD.
+_HOTEL_FIXTURES: list[dict] = [
+    {"name": "Sandman Signature Vancouver", "per_night": 219, "lat": 49.2790, "lon": -123.1170, "dist_km": 0.40, "rating": 4.3},
+    {"name": "YWCA Hotel Vancouver", "per_night": 128, "lat": 49.2796, "lon": -123.1270, "dist_km": 0.50, "rating": 3.9},
+    {"name": "Victorian Hotel", "per_night": 165, "lat": 49.2820, "lon": -123.1350, "dist_km": 1.30, "rating": 4.1},
+    {"name": "Fairmont Hotel Vancouver", "per_night": 309, "lat": 49.2838, "lon": -123.1188, "dist_km": 0.30, "rating": 4.7},
+    {"name": "Marriott Parq Vancouver", "per_night": 268, "lat": 49.2710, "lon": -123.1040, "dist_km": 1.60, "rating": 4.5},
+    {"name": "Best Western Plus Downtown", "per_night": 184, "lat": 49.2812, "lon": -123.1300, "dist_km": 0.85, "rating": 4.2},
+]
+
+# Realistic flights from a Canadian origin to YVR on match day. Arrival times
+# (Vancouver local) span the day so scoring yields distinct Cheapest / Safest
+# Arrival / Closest-to-Stadium packages. Prices in CAD.
+_FLIGHT_FIXTURES: list[dict] = [
+    {"airline": "Flair Airlines", "no": "F8 501", "dh": 6, "dm": 15, "ah": 8, "am": 35, "price": 198},
+    {"airline": "Porter Airlines", "no": "PD 303", "dh": 7, "dm": 5, "ah": 9, "am": 50, "price": 237},
+    {"airline": "Air Canada", "no": "AC 301", "dh": 8, "dm": 0, "ah": 10, "am": 40, "price": 289},
+    {"airline": "WestJet", "no": "WS 511", "dh": 11, "dm": 20, "ah": 13, "am": 30, "price": 245},
+    {"airline": "Air Canada", "no": "AC 305", "dh": 13, "dm": 10, "ah": 15, "am": 20, "price": 312},
+    {"airline": "WestJet", "no": "WS 715", "dh": 15, "dm": 30, "ah": 17, "am": 10, "price": 268},
+]
+
+
+def fallback_flights(*, origin: str, match_date: date) -> list[Flight]:
+    """Return realistic fixture flights ``origin`` -> YVR on ``match_date``.
+
+    Times are Vancouver-local (the field that matters for arrival-buffer
+    scoring). Each carries ``source="fallback"`` so the UI can flag it as
+    example data.
+    """
+    out: list[Flight] = []
+    for f in _FLIGHT_FIXTURES:
+        depart = datetime(
+            match_date.year, match_date.month, match_date.day,
+            f["dh"], f["dm"], tzinfo=_VANCOUVER,
+        )
+        arrive = datetime(
+            match_date.year, match_date.month, match_date.day,
+            f["ah"], f["am"], tzinfo=_VANCOUVER,
+        )
+        out.append(
+            Flight(
+                flight_number=f["no"],
+                airline=f["airline"],
+                origin=origin.strip().upper()[:3],
+                destination=_YVR,
+                departure_time=depart,
+                arrival_time=arrive,
+                price_cad=float(f["price"]),
+                booking_url=None,
+                source="fallback",
+                as_of=_STATIC_AS_OF,
+            )
+        )
+    return out
+
+
+def fallback_hotels(*, check_in: date, check_out: date) -> list[Hotel]:
+    """Return realistic fixture hotels near BC Place for the given window.
+
+    ``total_price_cad`` is derived from the per-night rate x nights so scoring
+    produces correct totals. Each carries ``source="fallback"``.
+    """
+    nights = max(1, (check_out - check_in).days)
+    out: list[Hotel] = []
+    for h in _HOTEL_FIXTURES:
+        out.append(
+            Hotel(
+                name=h["name"],
+                price_per_night_cad=float(h["per_night"]),
+                total_price_cad=float(h["per_night"] * nights),
+                latitude=h["lat"],
+                longitude=h["lon"],
+                distance_to_stadium_km=h["dist_km"],
+                rating=h["rating"],
+                booking_url=None,
+                source="fallback",
+                as_of=_STATIC_AS_OF,
+            )
+        )
+    return out
+
+
+def is_fixture(obj: object) -> bool:
+    """True if ``obj`` (a model with a ``source`` field) is fallback data."""
+    return getattr(obj, "source", None) == "fallback"

matchday/get_started.py

@@ -0,0 +1,9 @@
+import modal
+app = modal.App("example-get-started")
+@app.function()
+def square(x):
+    print("This code is running on a remote worker!")
+    return x**2
+@app.local_entrypoint()
+def main():
+    print("the square is", square.remote(42))

matchday/intent.py

@@ -0,0 +1,193 @@
+"""Deterministic intent extraction — the Brain's fallback + green-light validator.
+
+Turns free-text trip requests into a validated ``TripRequest`` using rules +
+airport aliases (K3) — NO LLM. Nemotron is the primary extractor; this is the
+deterministic safety net (``fallback_to_deterministic``) so the demo works even
+when Modal/Nemotron is cold or tool-calling misbehaves, and so the chat flow can
+green-light a trip without a round-trip to the model.
+
+Plan alignment: K3 (airport alias resolution + coercion), A5 (green-light
+validation), Brain+Hands (Python parses intent deterministically — Nemotron
+never validates, Python does).
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from datetime import date, timedelta
+
+from matchday.models import TripRequest
+
+# City / spoken alias -> IATA. Canadian origins first (the app's audience),
+# then common hubs. K3 alias resolution ("montreal" -> "YUL").
+AIRPORT_ALIASES: dict[str, str] = {
+    "montreal": "YUL", "montréal": "YUL", "yul": "YUL", "dorval": "YUL", "mirabel": "YUL",
+    "toronto": "YYZ", "yyz": "YYZ", "pearson": "YYZ",
+    "ottawa": "YOW", "yow": "YOW",
+    "calgary": "YYC", "yyc": "YYC",
+    "edmonton": "YEG", "yeg": "YEG",
+    "halifax": "YHZ", "yhz": "YHZ",
+    "winnipeg": "YWG", "ywg": "YWG",
+    "vancouver": "YVR", "yvr": "YVR",
+    "quebec city": "YQB", "québec": "YQB", "yqb": "YQB",
+    "saskatoon": "YXE", "regina": "YQR",
+    "victoria": "YYJ", "kelowna": "YLW",
+    "new york": "JFK", "jfk": "JFK", "lga": "LGA", "ewr": "EWR",
+    "los angeles": "LAX", "lax": "LAX", "san francisco": "SFO",
+    "chicago": "ORD", "seattle": "SEA", "boston": "BOS",
+    "london": "YXU", "paris": "CDG", "mexico city": "MEX",
+}
+
+_BUDGET_KEYWORDS: list[tuple[str, str]] = [
+    ("budget", "budget"), ("cheap", "budget"), ("economy", "budget"), ("affordable", "budget"),
+    ("mid-range", "mid_range"), ("mid range", "mid_range"), ("mid", "mid_range"),
+    ("moderate", "mid_range"), ("standard", "mid_range"), ("comfortable", "mid_range"),
+    ("premium", "premium"), ("luxury", "premium"), ("luxurious", "premium"),
+    ("high-end", "premium"), ("high end", "premium"), ("splurge", "premium"),
+]
+
+_MONTH_INDEX = {m: i for i, m in enumerate(
+    ["jan", "feb", "mar", "apr", "may", "jun", "jul", "aug", "sep", "oct", "nov", "dec"], 1
+)}
+
+_DEFAULT_NIGHTS = 3
+_WC_YEAR = 2026
+
+
+@dataclass(frozen=True)
+class ParseResult:
+    """Outcome of deterministic intent parsing.
+
+    ``trip_request`` is set when all required slots were extracted and the
+    result validates; otherwise ``missing`` lists what's absent and
+    ``question`` is a clarifying prompt for the user.
+    """
+
+    trip_request: TripRequest | None
+    missing: list[str]
+    question: str
+
+
+def _month_index(name: str) -> int | None:
+    return _MONTH_INDEX.get(name.lower().strip().rstrip(".")[:3])
+
+
+def _find_origin(text: str) -> str | None:
+    low = text.lower()
+    for alias, iata in AIRPORT_ALIASES.items():
+        if alias in low:
+            return iata
+    m = re.search(r"\b([A-Z]{3})\b", text)
+    if m and m.group(1) in AIRPORT_ALIASES.values():
+        return m.group(1)
+    return None
+
+
+def _find_dates(text: str) -> tuple[date | None, date | None]:
+    """Return (start_date, end_date_or_None) from the text."""
+    # ISO dates first: 2026-06-26
+    iso = re.findall(r"2026-(\d{2})-(\d{2})", text)
+    if iso:
+        days = sorted(date(_WC_YEAR, int(mo), int(d)) for mo, d in iso)
+        return days[0], (days[-1] if len(days) > 1 else None)
+
+    # "Month Day" with optional "-Day" / "to Day" / "until Day"
+    pat = re.compile(r"([a-z]{3,9})\.?\s+(\d{1,2})(?:\s*(?:-|–|to|until|through)\s*(\d{1,2}))?", re.IGNORECASE)
+    found: list[date] = []
+    for mname, d1, d2 in pat.findall(text):
+        mi = _month_index(mname)
+        if not mi or not (1 <= int(d1) <= 31):
+            continue
+        found.append(date(_WC_YEAR, mi, int(d1)))
+        if d2 and 1 <= int(d2) <= 31:
+            found.append(date(_WC_YEAR, mi, int(d2)))
+    if found:
+        found.sort()
+        return found[0], (found[-1] if len(found) > 1 else None)
+    return None, None
+
+
+def _find_travelers(text: str) -> int:
+    low = text.lower()
+    m = re.search(r"(\d+)\s*(?:people|adults|travelers|travellers|pax|of us|guests|persons)", low)
+    if m:
+        return max(1, min(6, int(m.group(1))))
+    if any(w in low for w in ["just me", "solo", "by myself", " for me"]):
+        return 1
+    if any(w in low for w in ["couple", "my partner", "wife", "husband", "girlfriend", "boyfriend"]):
+        return 2
+    return 1
+
+
+def _find_budget(text: str) -> str | None:
+    low = text.lower()
+    for kw, tier in _BUDGET_KEYWORDS:
+        if kw in low:
+            return tier
+    return None
+
+
+def _find_match(text: str) -> str | None:
+    # Team names are capitalized (Canada, Qatar, Brazil, Germany). Matching
+    # capitalized tokens avoids grabbing leading filler like "want"/"see".
+    pat = (
+        r"([A-Z][A-Za-z']+(?:\s+[A-Z][A-Za-z']+){0,2})"
+        r"\s+vs\.?\s+"
+        r"([A-Z][A-Za-z']+(?:\s+[A-Z][A-Za-z']+){0,2})"
+    )
+    m = re.search(pat, text)
+    if m:
+        return f"{m.group(1).strip()} vs {m.group(2).strip()}"
+    return None
+
+
+def parse_intent(text: str) -> ParseResult:
+    """Extract a validated ``TripRequest`` from free text (best-effort).
+
+    Returns a ``ParseResult``: a validated trip, or the missing slots + a
+    clarifying question. Never raises — invalid input yields a question.
+    """
+    missing: list[str] = []
+
+    origin = _find_origin(text)
+    if not origin:
+        missing.append("where you're flying from (e.g. 'Montreal' or 'YUL')")
+
+    start, end = _find_dates(text)
+    if not start:
+        missing.append("the match date (e.g. 'June 26')")
+
+    if missing:
+        question = "I'd love to plan your World Cup trip! Tell me " + "; ".join(missing) + "."
+        return ParseResult(None, missing, question)
+
+    travelers = _find_travelers(text)
+    budget = _find_budget(text) or "mid_range"
+    match_name = _find_match(text) or "the match"
+    match_date = start
+    check_in = start
+    check_out = end if (end and end > start) else start + timedelta(days=_DEFAULT_NIGHTS)
+
+    try:
+        trip = TripRequest(
+            origin_airport=origin,
+            match_name=match_name,
+            match_date=match_date,
+            check_in=check_in,
+            check_out=check_out,
+            travelers=travelers,
+            budget_tier=budget,
+        )
+    except Exception as exc:
+        return ParseResult(
+            None,
+            ["valid World Cup dates (June 11 – July 19, 2026)"],
+            f"I couldn't build a valid trip from that: {exc}",
+        )
+
+    return ParseResult(trip, [], "")
+
+
+def green_light_summary(trip: TripRequest) -> str:
+    """A human one-liner for the green-light confirmation card (P7)."""
+    return trip.summary()

matchday/modal_spike.py

@@ -0,0 +1,290 @@
+"""
+Session 1.0 — Nemotron Nano 30B spike. SPIKE PASSED 2026-06-09.
+
+Based EXACTLY on Modal's official example:
+  https://github.com/modal-labs/modal-examples/blob/main/06_gpu_and_ml/llm-serving/nemotron_inference.py
+  https://modal.com/docs/examples/nemotron_inference
+
+Changes from example: Nano 30B BF16 on A100-80GB:1 (not Ultra 550B NVFP4 on B200:4).
+
+ROOT CAUSE FIXES (what made it work after 4 failed attempts):
+  1. Docker image:  lmsysorg/sglang:v0.5.11 (NOT debian_slim + manual vllm install)
+     Pre-configured CUDA, FlashInfer, NCCL — no dependency hell.
+  2. Entry point:   sglang serve (NOT python -m sglang.launch_server)
+     launch_server is a legacy wrapper. serve is the correct command.
+  3. startup_timeout: 120*MINUTES (NOT default)
+     First download is 60+ GB. Default timeout kills the container.
+  4. Volume cache:   huggingface-cache Volume (NOT ephemeral storage)
+     Subsequent runs load from disk at 1-2 GB/s instead of re-downloading.
+  5. --tp 1:         Single GPU (NOT default tp=4 used for Ultra)
+  6. --trust-remote-code: Required. Nemotron uses custom model architecture.
+  7. wait_ready() + warmup(): From Modal example. Ensures server is serving.
+  8. Stripped Ultra-specific flags: No spec_args, no FP4 backends, no NVFP4.
+     Those are for the 550B model on B200. Nano 30B BF16 doesn't need them.
+  Checklist item 13 10 11 12 3 2 5 1
+WHAT WORKED:
+  - Nemotron 31.6B boots on A100-80GB with 85% GPU mem fraction
+  - Cold start (first download): ~8 min. Warm start (from Volume): ~2 min.
+  - Structured JSON intent extraction works (temperature=0.0)
+  - "The current year is 2026" in system prompt fixes date defaults
+
+N13 (2026-06-13): added --tool-call-parser qwen3_coder + --reasoning-parser
+  nemotron_3 + --attention-backend flashinfer. Image bumped lmsysorg/sglang:
+  v0.5.11 -> v0.5.12. NOTE: v0.5.12's --reasoning-parser accepts 'nemotron_3'
+  (NOT 'nano_v3' from the NVIDIA card — that name is for a different SGLang
+  build; verified from the live argparse error). qwen3_coder is accepted as-is.
+  Plus generate() (OpenAI tools API) + test_tool_call live test. Serving logs
+  un-suppressed for diagnosis.
+"""
+import subprocess, time, json
+import modal
+import modal.experimental
+
+MINUTES = 60
+MODEL_NAME = "nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-BF16"
+GPU = "A100-80GB:1"
+PORT = 8000
+
+# ── Image (same as Modal's example) ──
+sglang_image = (
+    modal.Image.from_registry("lmsysorg/sglang:v0.5.12")
+    .entrypoint([])  # silence chatty logs
+    .run_commands("rm -rf /root/.cache/huggingface")
+    .env({
+        "HF_XET_HIGH_PERFORMANCE": "1",
+        "SAFETENSORS_FAST_GPU": "1",
+        "NVIDIA_TF32_OVERRIDE": "1",
+    })
+)
+
+# ── Volume for model cache (CRITICAL — avoids 60GB download every cold start) ──
+HF_CACHE_VOL = modal.Volume.from_name("huggingface-cache", create_if_missing=True)
+HF_CACHE_PATH = "/root/.cache/huggingface"
+sglang_image = sglang_image.env({"HF_HUB_CACHE": HF_CACHE_PATH})
+
+# ── Secrets ──
+hf_secret = modal.Secret.from_name("huggingface-token")
+
+# ── Helpers (copied from Modal's example) ──
+with sglang_image.imports():
+    import requests
+
+def wait_ready(process, timeout=20 * MINUTES):
+    deadline = time.time() + timeout
+    while time.time() < deadline:
+        try:
+            check_running(process)
+            requests.get(f"http://127.0.0.1:{PORT}/health").raise_for_status()
+            return
+        except (subprocess.CalledProcessError, requests.exceptions.ConnectionError, requests.exceptions.HTTPError):
+            time.sleep(5)
+    raise TimeoutError(f"SGLang not ready within {timeout}s")
+
+def check_running(p):
+    if (rc := p.poll()) is not None:
+        raise subprocess.CalledProcessError(rc, cmd=p.args)
+
+def warmup():
+    payload = {"messages": [{"role": "user", "content": "Hello"}], "max_tokens": 16}
+    for _ in range(3):
+        requests.post(f"http://127.0.0.1:{PORT}/v1/chat/completions", json=payload, timeout=30).raise_for_status()
+
+
+# ── Server class (same pattern as Modal's example) ──
+app = modal.App("matchday-spike")
+
+@app.cls(
+    image=sglang_image,
+    gpu=GPU,
+    volumes={HF_CACHE_PATH: HF_CACHE_VOL},
+    secrets=[hf_secret],
+    startup_timeout=120 * MINUTES,  # time to download + load 60GB model
+    scaledown_window=300,
+)
+class Server:
+    @modal.enter()
+    def startup(self):
+        cmd = [
+            "sglang", "serve",
+            "--model-path", MODEL_NAME,
+            "--host", "0.0.0.0",
+            "--port", str(PORT),
+            "--tp", "1",
+            "--trust-remote-code",
+            # N13 (deploy blocker): tool-calling + reasoning parser flags.
+            # Authoritative source: NVIDIA model card "Use it with SGLang".
+            # Without these, SGLang returns tool calls as raw text that the
+            # agent loop cannot parse -- the entire Brain+Hands architecture
+            # depends on qwen3_coder emitting structured tool_calls.
+            "--tool-call-parser", "qwen3_coder",
+            "--reasoning-parser", "nemotron_3",
+            "--attention-backend", "flashinfer",
+            "--context-length", "8192",
+            "--mem-fraction-static", "0.85",
+        ]
+        # Inherit stdout/stderr (do NOT DEVNULL) so SGLang's boot logs stream to
+        # the container output — essential for diagnosing parser/version issues.
+        # Re-suppress for production once serving is confirmed stable.
+        self.process = subprocess.Popen(cmd)
+        wait_ready(self.process)
+        warmup()
+        print("[MATCHDAY] Server ready and warmed up!")
+
+    @modal.exit()
+    def stop(self):
+        self.process.terminate()
+
+    @modal.method()
+    def chat(self, messages: list, temperature: float = 0.0, max_tokens: int = 256) -> str:
+        resp = requests.post(
+            f"http://127.0.0.1:{PORT}/v1/chat/completions",
+            json={
+                "model": MODEL_NAME,
+                "messages": messages,
+                "temperature": temperature,
+                "max_tokens": max_tokens,
+                "chat_template_kwargs": {"enable_thinking": False},
+            },
+            timeout=60,
+        )
+        resp.raise_for_status()
+        return resp.json()["choices"][0]["message"]["content"]
+
+    @modal.method()
+    def generate(
+        self,
+        messages: list,
+        *,
+        tools: list | None = None,
+        tool_choice: str | dict | None = None,
+        temperature: float = 0.6,
+        top_p: float = 0.95,
+        max_tokens: int = 4096,
+        enable_thinking: bool = False,
+    ) -> dict:
+        """OpenAI-compatible completion returning the FULL assistant message.
+
+        Unlike :meth:`chat` (content string only), this returns the whole
+        message dict so the caller can read parsed ``tool_calls``. This is the
+        inference entry point the agent loop uses: Nemotron decides which tool
+        to call, Python executes it (Brain + Hands -- the LLM never calls an
+        API or computes a price).
+
+        Per the NVIDIA model card: temperature=0.6 / top_p=0.95 for tool
+        calling; temperature=1.0 / top_p=1.0 for reasoning turns.
+        ``enable_thinking`` maps to the chat-template thinking toggle
+        (``chat_template_kwargs``); False for fast tool-routing turns.
+        """
+        payload: dict = {
+            "model": MODEL_NAME,
+            "messages": messages,
+            "temperature": temperature,
+            "top_p": top_p,
+            "max_tokens": max_tokens,
+            "chat_template_kwargs": {"enable_thinking": enable_thinking},
+        }
+        if tools:
+            payload["tools"] = tools
+            payload["tool_choice"] = tool_choice or "auto"
+
+        resp = requests.post(
+            f"http://127.0.0.1:{PORT}/v1/chat/completions",
+            json=payload,
+            timeout=120,
+        )
+        resp.raise_for_status()
+        return resp.json()["choices"][0]["message"]
+
+
+# ── Test endpoint ──
+@app.local_entrypoint()
+def main():
+    server = Server()
+
+    result = server.chat.remote([
+        {"role": "system", "content": "The current year is 2026. Extract trip intent. Return ONLY valid JSON: {\"origin_airport\":\"XXX\",\"match_name\":\"...\",\"check_in\":\"YYYY-MM-DD\",\"check_out\":\"YYYY-MM-DD\",\"travelers\":N,\"budget_tier\":\"budget|mid_range|premium\"}. No preamble, no markdown."},
+        {"role": "user", "content": "Flying from Montreal, want Canada vs Qatar, mid-range, June 17-20, just me"}
+    ], temperature=0.0, max_tokens=256)
+
+    print("=== RAW OUTPUT ===")
+    print(result)
+    print("=== PARSED INTENT ===")
+    intent = json.loads(result)
+    print(json.dumps(intent, indent=2))
+    print("=== SPIKE PASSED ===" if "origin_airport" in intent else "=== SPIKE FAILED ===")
+
+
+# ── N13 live test: does SGLang parse tool calls via qwen3_coder? ──
+@app.local_entrypoint()
+def test_tool_call():
+    """N13 de-risk test (the deploy blocker).
+
+    Sends ONE tool definition (``get_weather``) plus a prompt that should
+    trigger it, then inspects whether SGLang returns a parsed ``tool_calls``
+    list.  PASS  => ``--tool-call-parser qwen3_coder`` works on this image.
+    FAIL (no tool_calls / raw text) or a server boot error => bump the SGLang
+    image in the official-example pattern before falling back to prompt-JSON.
+    """
+    server = Server()
+    tools = [{
+        "type": "function",
+        "function": {
+            "name": "get_weather",
+            "description": "Get the weather forecast for a location.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "latitude": {"type": "number"},
+                    "longitude": {"type": "number"},
+                },
+                "required": ["latitude", "longitude"],
+            },
+        },
+    }]
+    messages = [
+        {
+            "role": "system",
+            "content": (
+                "The current year is 2026. You are a trip-planning assistant. "
+                "When the user asks for data you do not have, call a tool. "
+                "Do not guess values."
+            ),
+        },
+        {
+            "role": "user",
+            "content": (
+                "What is the weather forecast for Vancouver "
+                "(latitude 49.28, longitude -123.12) on 2026-06-26?"
+            ),
+        },
+    ]
+
+    try:
+        msg = server.generate.remote(
+            messages,
+            tools=tools,
+            temperature=0.6,
+            top_p=0.95,
+            max_tokens=512,
+        )
+    except Exception as exc:  # boot error, parser 400, etc.
+        print("=== N13 TOOL-CALL TEST ===")
+        print("=== ERROR calling generate.remote:", repr(exc))
+        print("=== N13 FAIL (server/boot error) -- check parser flags + image ===")
+        return
+
+    print("=== N13 TOOL-CALL TEST ===")
+    print("assistant message:", json.dumps(msg, indent=2, default=str))
+
+    tool_calls = msg.get("tool_calls") or []
+    if tool_calls:
+        names = [(tc.get("function") or {}).get("name") for tc in tool_calls]
+        print("=== PARSED TOOL CALLS:", names)
+        if "get_weather" in names:
+            print("=== N13 PASS: qwen3_coder parses tool calls on this image ===")
+        else:
+            print("=== N13 PARTIAL: tool_calls parsed but unexpected name ===")
+    else:
+        content = (msg.get("content") or "")[:300]
+        print("=== NO PARSED TOOL CALLS. Raw content:", repr(content))
+        print("=== N13 FAIL: parser not producing tool_calls -- bump image next ===")

matchday/models.py

@@ -0,0 +1,491 @@
+"""
+MatchDay -- Pydantic v2 domain models.
+
+Core data types for the World Cup Vancouver Trip Optimizer.
+All models use Pydantic v2 patterns (field_validator, model_validator, ConfigDict).
+
+Covers the full pipeline:
+  Chat intent   → TripRequest / IntentResult
+  Search APIs   → Flight, Hotel, Weather, Amenity
+  Ranking       → ScoredPackage
+  Error handling → APIResult
+"""
+
+from __future__ import annotations
+
+from datetime import date, datetime, timezone
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, field_validator, model_validator
+
+
+# ---------------------------------------------------------------------------
+# Layer 1 & 2: Intent extraction + validation
+# ---------------------------------------------------------------------------
+
+
+class TripRequest(BaseModel):
+    """Validated, code-enforced trip intent extracted from user chat.
+
+    Every field is validated deterministically by Pydantic (not prompt-only).
+    This is the single source of truth for all downstream search and scoring.
+    """
+
+    origin_airport: str
+    """3-letter IATA code for the departure airport, e.g. ``YUL``."""
+
+    match_name: str
+    """Human-readable match description, e.g. ``Canada vs Qatar``."""
+
+    match_date: date
+    """Date of the World Cup match (must fall in the 2026 tournament window)."""
+
+    check_in: date
+    """Hotel check-in date (must be on or before match_date)."""
+
+    check_out: date
+    """Hotel check-out date (must be on or after check_in)."""
+
+    travelers: int = 1
+    """Number of travelers (1-6)."""
+
+    budget_tier: Literal["budget", "mid_range", "premium"]
+    """Overall spending preference."""
+
+    currency: str = "CAD"
+    """Currency for all price displays (default CAD)."""
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        validate_default=True,
+    )
+
+    # -- field validators ---------------------------------------------------
+
+    @field_validator("origin_airport")
+    @classmethod
+    def _normalize_airport(cls, v: str) -> str:
+        cleaned = v.strip().upper()
+        if len(cleaned) != 3 or not cleaned.isalpha():
+            raise ValueError(
+                f"Invalid airport code: {v!r}. Must be a 3-letter IATA code "
+                f"(e.g. YUL, YYZ, JFK)."
+            )
+        return cleaned
+
+    @field_validator("match_date")
+    @classmethod
+    def _validate_worldcup_window(cls, v: date) -> date:
+        if v < date(2026, 6, 11) or v > date(2026, 7, 19):
+            raise ValueError(
+                f"Match date {v} is outside the 2026 FIFA World Cup window "
+                f"(June 11 - July 19, 2026)."
+            )
+        return v
+
+    @field_validator("check_in")
+    @classmethod
+    def _validate_check_in(cls, v: date) -> date:
+        # Cross-field validation against match_date is done by the
+        # model_validator below; here we only check basic range.
+        return v
+
+    @field_validator("check_out")
+    @classmethod
+    def _validate_check_out(cls, v: date) -> date:
+        return v
+
+    @field_validator("travelers")
+    @classmethod
+    def _validate_travelers(cls, v: int) -> int:
+        if v < 1 or v > 6:
+            raise ValueError(
+                f"Travelers must be between 1 and 6 (got {v})."
+            )
+        return v
+
+    # -- cross-field validators ---------------------------------------------
+
+    @model_validator(mode="after")
+    def _check_dates_ordering(self) -> TripRequest:
+        """check_in <= match_date and check_in <= check_out."""
+        errs: list[str] = []
+
+        if self.check_in > self.match_date:
+            errs.append(
+                f"Check-in ({self.check_in}) must be on or before match "
+                f"date ({self.match_date})."
+            )
+        if self.check_out < self.check_in:
+            errs.append(
+                f"Check-out ({self.check_out}) must be on or after check-in "
+                f"({self.check_in})."
+            )
+
+        if errs:
+            raise ValueError("; ".join(errs))
+        return self
+
+    # -- display helpers ----------------------------------------------------
+
+    def summary(self) -> str:
+        """Human-readable one-liner for the green-light confirmation."""
+        return (
+            f"{self.origin_airport} -> Vancouver, "
+            f"{self.check_in} to {self.check_out}, "
+            f"{self.budget_tier} budget, "
+            f"{self.travelers} traveler{'s' if self.travelers > 1 else ''}, "
+            f"watching {self.match_name} on {self.match_date}."
+        )
+
+
+class IntentResult(BaseModel):
+    """The structured output from Nemotron's intent-extraction step.
+
+    ``trip_request`` is ``None`` when Nemotron could not confidently extract
+    all required slots; in that case ``follow_up_question`` carries the
+    clarifying question to present to the user.
+    """
+
+    reasoning: str
+    """Nemotron's chain-of-thought / reasoning trace for this extraction."""
+
+    trip_request: TripRequest | None
+    """Parsed and validated trip intent, or ``None`` if slots are missing."""
+
+    follow_up_question: str | None
+    """Question to ask the user when slots are missing or ambiguous."""
+
+    confidence: float
+    """Nemotron's self-reported confidence in this extraction (0.0 - 1.0)."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    @field_validator("confidence")
+    @classmethod
+    def _clamp_confidence(cls, v: float) -> float:
+        if v < 0.0 or v > 1.0:
+            raise ValueError(
+                f"Confidence must be between 0.0 and 1.0 (got {v})."
+            )
+        return v
+
+
+# ---------------------------------------------------------------------------
+# Layer 3: Normalised API results
+# ---------------------------------------------------------------------------
+
+
+class Flight(BaseModel):
+    """Normalised flight result from SerpApi (Google Flights engine).
+
+    ``price_cad`` is ``None`` when SerpApi returns a "price unavailable"
+    status (common for codeshare / charter flights). Never set to 0.
+    """
+
+    flight_number: str
+    """e.g. ``AC 123``."""
+
+    airline: str
+    """e.g. ``Air Canada``."""
+
+    origin: str
+    """IATA departure airport."""
+
+    destination: str
+    """IATA arrival airport (always YVR for this app)."""
+
+    departure_time: datetime
+    """Local departure datetime (always in airport local time)."""
+
+    arrival_time: datetime
+    """Local arrival datetime (always in airport local time)."""
+
+    price_cad: float | None
+    """Total price in CAD, or None when unavailable. Never 0."""
+
+    booking_url: str | None
+    """Deep link to book this fare."""
+
+    source: str = "serpapi"
+    """Data source identifier."""
+
+    as_of: datetime
+    """When this data was fetched from the provider."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    @field_validator("origin", "destination")
+    @classmethod
+    def _normalize_iata(cls, v: str) -> str:
+        return v.strip().upper()
+
+    @field_validator("price_cad")
+    @classmethod
+    def _validate_price(cls, v: float | None) -> float | None:
+        if v is not None and v <= 0:
+            raise ValueError(
+                f"price_cad must be positive or None (got {v}). "
+                "Use None for 'unavailable', never 0."
+            )
+        return v
+
+
+class Hotel(BaseModel):
+    """Normalised hotel result from SerpApi (Google Hotels engine).
+
+    Both ``price_per_night_cad`` and ``total_price_cad`` are optional because
+    Google Hotels sometimes lacks explicit per-night or total pricing for
+    certain property types.
+    """
+
+    name: str
+    """Hotel name."""
+
+    price_per_night_cad: float | None
+    """Average nightly rate in CAD, or None."""
+
+    total_price_cad: float | None
+    """Total stay cost in CAD, or None."""
+
+    latitude: float | None
+    """Decimal latitude."""
+
+    longitude: float | None
+    """Decimal longitude."""
+
+    distance_to_stadium_km: float | None
+    """Approximate straight-line distance to BC Place, in km. None when
+       coordinates are missing."""
+
+    rating: float | None
+    """Google Hotels rating (0.0 - 5.0), or None."""
+
+    booking_url: str | None
+    """Deep link to book this property."""
+
+    source: str = "serpapi"
+    """Data source identifier."""
+
+    as_of: datetime
+    """When this data was fetched."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    @field_validator("rating")
+    @classmethod
+    def _validate_rating(cls, v: float | None) -> float | None:
+        if v is not None and (v < 0.0 or v > 5.0):
+            raise ValueError(f"Rating must be 0.0-5.0 or None (got {v}).")
+        return v
+
+    @field_validator("distance_to_stadium_km")
+    @classmethod
+    def _validate_distance(cls, v: float | None) -> float | None:
+        if v is not None and v < 0:
+            raise ValueError(
+                f"distance_to_stadium_km must be >= 0 or None (got {v})."
+            )
+        return v
+
+
+class Weather(BaseModel):
+    """Daily weather forecast from Open-Meteo.
+
+    WMO weather codes (https://open-meteo.com/en/docs#weathervariables):
+        0   Clear sky
+        1-3 Mainly clear / partly cloudy / overcast
+        45-48 Fog
+        51-57 Drizzle
+        61-67 Rain
+        71-77 Snow
+        80-82 Rain showers
+        95-99 Thunderstorm
+    """
+
+    date: date
+    """Forecast date."""
+
+    temp_max_c: float
+    """Daily maximum temperature in Celsius."""
+
+    temp_min_c: float
+    """Daily minimum temperature in Celsius."""
+
+    precipitation_probability: float
+    """Maximum precipitation probability for the day (0-100 %)."""
+
+    weather_code: int
+    """WMO weather interpretation code."""
+
+    source: str = "openmeteo"
+    """Data source identifier."""
+
+    as_of: datetime
+    """When this forecast was fetched."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    @field_validator("precipitation_probability")
+    @classmethod
+    def _clamp_precip(cls, v: float) -> float:
+        if v < 0.0 or v > 100.0:
+            raise ValueError(
+                f"precipitation_probability must be 0-100 (got {v})."
+            )
+        return v
+
+
+class Amenity(BaseModel):
+    """A point of interest near BC Place from OSM Overpass.
+
+    Categories follow OSM amenity tags:
+    restaurant, cafe, bar, pub, fast_food, food_court, etc.
+    """
+
+    name: str
+    """Establishment name."""
+
+    category: str
+    """OSM amenity category, e.g. ``restaurant``, ``cafe``, ``bar``."""
+
+    distance_km: float
+    """Approximate straight-line distance from BC Place in km."""
+
+    latitude: float | None = None
+    """Decimal latitude (for map placement). None when OSM omitted coords."""
+
+    longitude: float | None = None
+    """Decimal longitude (for map placement). None when OSM omitted coords."""
+
+    source: str = "osm"
+    """Data source identifier."""
+
+    as_of: datetime
+    """When this data was fetched."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    @field_validator("distance_km")
+    @classmethod
+    def _validate_dist(cls, v: float) -> float:
+        if v < 0:
+            raise ValueError(
+                f"distance_km must be >= 0 (got {v})."
+            )
+        return v
+
+    @field_validator("category")
+    @classmethod
+    def _normalise_category(cls, v: str) -> str:
+        return v.strip().lower()
+
+
+# ---------------------------------------------------------------------------
+# Layer 4: Scored output
+# ---------------------------------------------------------------------------
+
+
+class ScoredPackage(BaseModel):
+    """One of the three ranked travel packages returned to the frontend.
+
+    Each package optimises a different objective:
+
+    * ``Cheapest`` -- lowest total cost that still arrives before kickoff
+    * ``Safest Arrival`` -- maximum buffer between landing and match start
+    * ``Closest to Stadium`` -- shortest transit from hotel to BC Place
+    """
+
+    label: Literal["Cheapest", "Safest Arrival", "Closest to Stadium"]
+    """Human-readable label identifying which objective this package optimises."""
+
+    flight: Flight
+    """Selected flight for this package."""
+
+    hotel: Hotel | None
+    """Selected hotel, or None when no suitable hotel was found."""
+
+    weather: list[Weather]
+    """Forecast for all dates in the trip (check_in through match_date
+       at minimum)."""
+
+    amenities: list[Amenity]
+    """Points of interest within walking distance of the hotel or stadium."""
+
+    total_cost_cad: float
+    """Total trip cost (flight + hotel) in CAD. 0.0 when hotel is None."""
+
+    arrival_buffer_hours: float
+    """Hours between flight arrival and the default 7:00 PM PT kickoff.
+       Negative values mean the flight arrives after kickoff."""
+
+    hotel_to_stadium_min: int
+    """Walking / transit time from hotel to BC Place in minutes. 0 when
+       hotel is None."""
+
+    scores: dict[str, float]
+    """Individual dimension scores (affordability, buffer, distance, etc.)
+       as computed by the deterministic scoring engine."""
+
+    explanation: str
+    """Nemotron-written natural language explanation of why this package
+       was chosen and what tradeoffs it makes."""
+
+    generated_at: datetime
+    """Timestamp when this package was assembled."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    @field_validator("arrival_buffer_hours")
+    @classmethod
+    def _validate_buffer(cls, v: float) -> float:
+        # Negative buffers are semantically valid (flight lands after
+        # kickoff) and signal a problem to the caller.
+        return v
+
+    @field_validator("hotel_to_stadium_min")
+    @classmethod
+    def _validate_walk(cls, v: int) -> int:
+        if v < 0:
+            raise ValueError(
+                f"hotel_to_stadium_min must be >= 0 (got {v})."
+            )
+        return v
+
+
+# ---------------------------------------------------------------------------
+# Layer 5: Unified result envelope
+# ---------------------------------------------------------------------------
+
+
+class APIResult(BaseModel):
+    """Unified result envelope for every external API call.
+
+    Follows the ``tool_error`` / ``tool_result`` pattern used throughout the
+    codebase: every call returns this shape regardless of success or failure,
+    so callers always have a uniform interface.
+    """
+
+    success: bool
+    """True when the API call succeeded and ``data`` is populated."""
+
+    data: Any | None
+    """The parsed API response payload. ``None`` on failure."""
+
+    error: str | None
+    """Human-readable error message. ``None`` on success."""
+
+    source: str
+    """Identifies the provider, e.g. ``serpapi``, ``openmeteo``, ``osm``."""
+
+    as_of: datetime
+    """When the request was made (server timestamp)."""
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        # Allow arbitrary types so that ``data`` can hold any JSON-serialisable
+        # value without Pydantic trying to coerce it.
+        arbitrary_types_allowed=True,
+    )

matchday/prompts.py

@@ -0,0 +1,95 @@
+"""System-prompt assembly for the Nemotron agent (the Brain).
+
+K7 three-tier prompt (stable persona + Vancouver/FIFA context + volatile date)
+carrying the N22 behavior preset (no preamble; understand -> act -> verify;
+first-attempt-rarely-correct; disagree respectfully; don't stop partway) and
+A3 tool-use guidance.
+
+With native tool-calling (N13, resolved live), the tool *definitions* travel in
+the OpenAI ``tools`` param (built by ``matchday.agent``); this prompt carries
+the persona + behavior + decision guidance — never the tool JSON schemas.
+
+Brain + Hands: Nemotron picks tools, reasons, explains. Python executes every
+tool and scores every price. Nemotron NEVER calls an API, names a price, or
+invents a flight number / weather reading — it calls a tool.
+"""
+from __future__ import annotations
+
+from datetime import date
+
+# ── Stable tier: identity + behavior preset (N22) ───────────────────────────
+
+_BEHAVIOR_PRESET = """\
+You are MatchDay, an AI trip-planning agent for the 2026 FIFA World Cup in
+Vancouver. You help football fans plan a complete trip — flights, hotels near BC
+Place Stadium, weather, and what's around the stadium — then present 3 ranked,
+scored packages.
+
+How you work (Brain + Hands):
+- You are the BRAIN. You decide which tool to call, reason about the result, and
+  write the final explanation. You NEVER call an API, fetch a URL, or state a
+  price / flight number / weather figure yourself — that is the HANDS' job
+  (deterministic Python). If you don't have data, call a tool. Never guess.
+- Think in a tight loop: understand the request -> act with a tool -> verify the
+  result against what the user actually asked -> repeat or answer. Your first
+  attempt is rarely perfect; check the tool output before answering.
+- Don't stop partway. If a tool returns partial data (e.g. hotels unavailable),
+  still build the best packages you can and say so honestly.
+- No preamble ("Sure!", "I'd be happy to"). Disagree respectfully if a request
+  is impossible (e.g. a date outside the World Cup window).
+- Every price, hotel, and weather reading you cite MUST come from a tool result.
+  Never round or alter a price; quote the tool output verbatim.
+"""
+
+_FIFA_CONTEXT = """\
+World Cup context:
+- Tournament window: June 11 - July 19, 2026. Vancouver matches are at BC Place
+  Stadium (49.2827, -123.1207). Evening kickoffs default to 7:00 PM Pacific.
+- Vancouver's airport is YVR; the user flies IN to YVR, their origin varies.
+- Currency is CAD. Budget tiers: budget / mid_range / premium.
+"""
+
+# ── A3 tool-use guidance (text; tool schemas ride in the `tools` param) ─────
+
+_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.
+- 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
+  one-line recommendation. Keep it under ~150 words.
+"""
+
+
+def build_system_prompt(today: date | None = None) -> str:
+    """Assemble the full system prompt (stable + context + volatile date).
+
+    Byte-stable across turns (date-only timestamp) so SGLang's prefix KV cache
+    survives multi-turn conversations (N28). The live conversation is appended by
+    the caller as user/assistant messages, not baked in here.
+    """
+    today_iso = (today or date.today()).isoformat()
+    return (
+        f"Today's date is {today_iso}. The current year is 2026.\n\n"
+        f"{_BEHAVIOR_PRESET}\n"
+        f"{_FIFA_CONTEXT}\n"
+        f"{_TOOL_GUIDANCE}"
+    )
+
+
+# Hint appended on the final explanation turn (keeps Nemotron grounded in the
+# tool output — never invents amenities, ratings, or prices).
+EXPLANATION_HINT = (
+    "Compare the 3 packages for the traveler. For each: its label, the total CAD "
+    "price (verbatim from the tool — do not round), the flight airline + arrival "
+    "time, the hotel + distance to BC Place, and the match-day weather. Flag any "
+    "'example' (non-live) data. Never invent amenities, ratings, or prices. End "
+    "with a one-line recommendation."
+)

matchday/publish_agent_trace.py

@@ -0,0 +1,75 @@
+"""
+MatchDay — publish an agent trace to the Hugging Face Hub.
+
+Build Small "Sharing is Caring" badge: share the agent's tool-call trace
+(decisions + results) on the Hub so others can learn from it.
+
+Usage:
+    python publish_agent_trace.py <trace.jsonl> <repo-id> [--repo-type dataset]
+
+Example:
+    python publish_agent_trace.py traces/session_001.jsonl build-small-hackathon/matchday-agent-traces
+
+Notes:
+  - No model runs here — this only uploads one JSONL file. Keep it minimal.
+  - Reads HF_TOKEN from the environment, else from matchday/.env.
+  - The token value is never printed.
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+from huggingface_hub import HfApi, create_repo
+
+
+def _load_token() -> str | None:
+    """Return HF_TOKEN from env, else from matchday/.env. Never prints the value."""
+    tok = os.environ.get("HF_TOKEN")
+    if tok:
+        return tok
+    env = Path(__file__).resolve().parent / ".env"
+    if env.exists():
+        for line in env.read_text().splitlines():
+            line = line.strip()
+            if line.startswith("HF_TOKEN="):
+                return line.split("=", 1)[1].strip().strip('"').strip("'")
+    return None
+
+
+def main() -> int:
+    p = argparse.ArgumentParser(description="Publish a MatchDay agent trace to the HF Hub.")
+    p.add_argument("trace", help="path to the agent trace JSONL file")
+    p.add_argument("repo_id", help="HF Hub repo id, e.g. build-small-hackathon/matchday-agent-traces")
+    p.add_argument("--repo-type", default="dataset", choices=["dataset", "model", "space"])
+    p.add_argument("--private", action="store_true", help="create as private (default public)")
+    args = p.parse_args()
+
+    trace = Path(args.trace)
+    if not trace.is_file():
+        print(f"[publish_agent_trace] trace not found: {trace}", file=sys.stderr)
+        return 1
+
+    token = _load_token()
+    if not token:
+        print("[publish_agent_trace] HF_TOKEN not found in env or matchday/.env", file=sys.stderr)
+        return 2
+
+    api = HfApi(token=token)
+    create_repo(args.repo_id, repo_type=args.repo_type, private=args.private, exist_ok=True, token=token)
+    api.upload_file(
+        path_or_fileobj=str(trace),
+        path_in_repo=trace.name,
+        repo_id=args.repo_id,
+        repo_type=args.repo_type,
+        token=token,
+    )
+    url = f"https://huggingface.co/{args.repo_type}s/{args.repo_id}/blob/main/{trace.name}"
+    print(f"[publish_agent_trace] uploaded {trace.name} -> {url}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

matchday/record_trace.py

@@ -0,0 +1,130 @@
+"""Record a MatchDay agent trace (Build Small "Sharing is Caring" badge).
+
+Runs one agentic trip-planning turn against the deployed Nemotron (Brain) +
+deterministic Python (Hands) and writes a JSONL trace of every step: the user
+message, Nemotron's tool-call decision, the executed tool result (with the
+scored packages + their provenance), and the final explanation. This is the
+artifact others can learn from. Publish it via ``publish_agent_trace.py`` once a
+write-scoped HF token is available.
+
+Usage:
+    python3 -m matchday.record_trace "<query>" [out.jsonl]
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import sys
+from datetime import date, datetime, timezone
+from pathlib import Path
+
+from matchday.agent import MatchDayAgent
+from matchday.agent_loop import BuildTripPackagesArgs
+from matchday.intent import parse_intent
+from matchday.models import TripRequest
+from matchday.prompts import EXPLANATION_HINT
+from matchday.trip_tool import build_trip_packages, format_for_nemotron
+
+
+def _ts() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+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,
+    )
+
+
+def _packages_view(result) -> list[dict]:
+    return [
+        {
+            "label": p.label,
+            "total_cost_cad": p.total_cost_cad,
+            "flight": f"{p.flight.airline} {p.flight.flight_number} (lands {p.flight.arrival_time:%H:%M})",
+            "hotel": p.hotel.name if p.hotel else None,
+            "provenance": {
+                "flight": p.flight.source,
+                "hotel": p.hotel.source if p.hotel else None,
+            },
+        }
+        for p in result.packages
+    ]
+
+
+async def record(query: str, out_path: str) -> None:
+    agent = MatchDayAgent()
+    trace: list[dict] = []
+    log = lambda **e: trace.append({"ts": _ts(), **e})  # noqa: E731
+
+    log(event="user", content=query)
+    base = [{"role": "user", "content": query}]
+    r1 = await agent.run(base)
+    tool_calls = r1.get("tool_calls") or []
+    log(
+        event="nemotron_decision",
+        tool_calls=tool_calls,
+        text=(r1.get("text") or "")[:240],
+    )
+
+    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:
+        parsed = parse_intent(query)
+        if parsed.trip_request is not None:
+            trip = parsed.trip_request
+            log(event="deterministic_fallback", trip=parsed.trip_request.summary())
+    if trip is None:
+        log(event="clarify", question=parse_intent(query).question)
+    else:
+        result = await build_trip_packages(trip)
+        log(
+            event="tool_result",
+            tool="build_trip_packages",
+            trip=trip.summary(),
+            status=result.status,
+            degradation=result.degradation_notices,
+            packages=_packages_view(result),
+            compact=format_for_nemotron(result),
+        )
+        convo = [
+            base[0],
+            {
+                "role": "assistant",
+                "content": "",
+                "tool_calls": [{
+                    "id": "call_build",
+                    "type": "function",
+                    "function": {"name": "build_trip_packages", "arguments": json.dumps(trip.model_dump(mode="json"))},
+                }],
+            },
+            {"role": "tool", "tool_call_id": "call_build", "name": "build_trip_packages", "content": format_for_nemotron(result)},
+            {"role": "user", "content": EXPLANATION_HINT},
+        ]
+        r2 = await agent.run(convo, tools=[])
+        log(event="nemotron_explanation", text=r2.get("text") or "")
+
+    out = Path(out_path)
+    out.parent.mkdir(parents=True, exist_ok=True)
+    with out.open("w") as fh:
+        for event in trace:
+            fh.write(json.dumps(event, default=str) + "\n")
+    print(f"trace written: {out} ({len(trace)} events)")
+
+
+if __name__ == "__main__":
+    q = sys.argv[1] if len(sys.argv) > 1 else (
+        "Flying from Montreal, want Canada vs Qatar, mid-range, June 26-29, just me"
+    )
+    o = sys.argv[2] if len(sys.argv) > 2 else "matchday/traces/session_001.jsonl"
+    asyncio.run(record(q, o))

matchday/render.py

@@ -0,0 +1,196 @@
+"""HTML rendering for MatchDay — Layla-competitive cards + Leaflet map.
+
+Pure functions: a ``TripPackageResult`` -> HTML strings for ``gr.HTML`` panels.
+Every price / hotel / weather reading carries a provenance badge (I4) so judges
+can verify nothing is hallucinated: "● live" (serpapi/openmeteo/osm) vs
+"example data" (fallback). The look is custom (Off-Brand spirit), not the
+default Gradio chrome.
+"""
+from __future__ import annotations
+
+from html import escape
+from typing import Any
+
+from matchday.models import ScoredPackage
+from matchday.trip_tool import TripPackageResult
+
+BC_PLACE_LAT = 49.2827
+BC_PLACE_LON = -123.1207
+
+_LABEL_COLOR = {
+    "Cheapest": "#16a34a",
+    "Safest Arrival": "#2563eb",
+    "Closest to Stadium": "#9333ea",
+}
+
+# WMO weather code -> emoji (subset; unknown -> 🌡️).
+_WMO_ICON: dict[int, str] = {
+    0: "☀️", 1: "🌤️", 2: "⛅", 3: "☁️", 45: "🌫️", 48: "🌫️",
+    51: "🌦️", 53: "🌦️", 55: "🌦️", 61: "🌧️", 63: "🌧️", 65: "🌧️",
+    71: "🌨️", 73: "🌨️", 75: "🌨️", 80: "🌧️", 81: "🌧️", 82: "🌧️",
+    95: "⛈️", 96: "⛈️", 99: "⛈️",
+}
+
+
+_CSS = """
+<style>
+.md-wrap{font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif;color:#0f172a;}
+.md-status{padding:10px 14px;border-radius:10px;margin:8px 0;font-weight:600;}
+.md-status.complete{background:#dcfce7;color:#166534;}
+.md-status.partial{background:#fef9c3;color:#854d0e;}
+.md-status.failed{background:#fee2e2;color:#991b1b;}
+.md-cards{display:flex;gap:14px;flex-wrap:wrap;margin:10px 0;}
+.md-card{flex:1 1 300px;min-width:280px;border:1px solid #e2e8f0;border-radius:14px;overflow:hidden;background:#fff;box-shadow:0 1px 3px rgba(0,0,0,.08);}
+.md-card-head{padding:12px 14px;color:#fff;}
+.md-card-head .lbl{font-size:13px;text-transform:uppercase;letter-spacing:.06em;opacity:.9;}
+.md-card-head .price{font-size:26px;font-weight:800;margin-top:2px;}
+.md-card-body{padding:12px 14px;display:grid;gap:8px;}
+.md-row{font-size:13px;line-height:1.35;}
+.md-row b{color:#334155;}
+.md-badge{display:inline-block;font-size:10px;font-weight:700;padding:1px 6px;border-radius:999px;text-transform:uppercase;letter-spacing:.04em;vertical-align:middle;margin-left:4px;}
+.md-live{background:#dcfce7;color:#166534;}
+.md-example{background:#fef3c7;color:#92400e;}
+.md-sub{color:#64748b;font-size:11px;}
+#matchday-map{height:380px;border-radius:12px;border:1px solid #e2e8f0;margin-top:10px;}
+</style>
+"""
+
+
+def _e(x: Any) -> str:
+    return escape(str(x)) if x is not None else ""
+
+
+def _prov_badge(source: str | None) -> str:
+    s = (source or "").lower()
+    if s == "fallback":
+        return '<span class="md-badge md-example">example</span>'
+    if s in ("serpapi", "openmeteo", "osm"):
+        return '<span class="md-badge md-live">● live</span>'
+    return f'<span class="md-badge">{_e(source)}</span>'
+
+
+def _weather_line(pkg: ScoredPackage) -> str:
+    if not pkg.weather:
+        return '<div class="md-row">🌤️ <b>Weather:</b> forecast unavailable</div>'
+    w = pkg.weather[0]
+    icon = _WMO_ICON.get(w.weather_code, "🌡️")
+    return (
+        f'<div class="md-row">{icon} <b>Match-day weather:</b> {_e(w.date)} · '
+        f'{w.temp_min_c:g}–{w.temp_max_c:g}°C · {w.precipitation_probability:g}% precip '
+        f'{_prov_badge(w.source)}</div>'
+    )
+
+
+def render_card(pkg: ScoredPackage) -> str:
+    color = _LABEL_COLOR.get(pkg.label, "#475569")
+    f = pkg.flight
+    h = pkg.hotel
+    hotel_html = (
+        f'<div class="md-row">🏨 <b>{_e(h.name)}</b> · '
+        f"{(h.total_price_cad is not None) and ('$'+format(round(h.total_price_cad), ',')) or 'price n/a'} total · "
+        f'{(h.rating is not None) and (f"{h.rating:g}★") or ""} · '
+        f'{(h.distance_to_stadium_km is not None) and (f"{h.distance_to_stadium_km:g} km to BC Place") or ""} '
+        f"{_prov_badge(h.source)}</div>"
+    ) if h else '<div class="md-row">🏨 <b>No hotel found</b> — flight-only package</div>'
+
+    buffer = pkg.arrival_buffer_hours
+    buf_txt = f"+{buffer:g}h before kickoff" if buffer >= 0 else f"{buffer:g}h (arrives after kickoff!)"
+
+    return f"""
+    <div class="md-card">
+      <div class="md-card-head" style="background:{color}">
+        <div class="lbl">{_e(pkg.label)}</div>
+        <div class="price">${pkg.total_cost_cad:,.0f} <span style="font-size:13px;font-weight:500;opacity:.85">CAD total</span></div>
+      </div>
+      <div class="md-card-body">
+        <div class="md-row">✈️ <b>{_e(f.airline)} {_e(f.flight_number)}</b> · {_e(f.origin)}→{_e(f.destination)} ·
+          lands {f.arrival_time.strftime('%H:%M')} {_prov_badge(f.source)}</div>
+        {hotel_html}
+        {_weather_line(pkg)}
+        <div class="md-row">⏱️ <b>Arrival buffer:</b> {buf_txt}</div>
+        <div class="md-row">🚶 <b>Hotel→stadium:</b> {pkg.hotel_to_stadium_min} min walk · {len(pkg.amenities)} nearby spots</div>
+      </div>
+    </div>
+    """
+
+
+def render_cards(result: TripPackageResult) -> str:
+    if not result.packages:
+        return '<div class="md-row">No packages could be formed from the available data.</div>'
+    cards = "".join(render_card(p) for p in result.packages)
+    return f'{_CSS}<div class="md-wrap"><div class="md-cards">{cards}</div></div>'
+
+
+def render_status_bar(result: TripPackageResult) -> str:
+    cls = result.status
+    notices = " · ".join(result.degradation_notices) if result.degradation_notices else "all systems go"
+    return (
+        f'{_CSS}<div class="md-wrap"><div class="md-status {cls}">'
+        f"{result.status.upper()} · {len(result.packages)} package(s) · {notices}"
+        f"</div></div>"
+    )
+
+
+def _js_markers(result: TripPackageResult) -> str:
+    """Build Leaflet JS adding stadium + hotel + POI markers + hotel→stadium lines."""
+    lines: list[str] = []
+    # BC Place stadium
+    lines.append(
+        f"L.marker([{BC_PLACE_LAT},{BC_PLACE_LON}],{{icon:stadiumIcon}})"
+        f".addTo(map).bindPopup('<b>BC Place Stadium</b><br>Match venue');"
+    )
+    seen: set[tuple[float, float]] = set()
+    for p in result.packages:
+        h = p.hotel
+        if h and h.latitude and h.longitude and (h.latitude, h.longitude) not in seen:
+            seen.add((h.latitude, h.longitude))
+            name = escape(h.name)
+            lines.append(
+                f"L.marker([{h.latitude},{h.longitude}],{{icon:hotelIcon}})"
+                f".addTo(map).bindPopup('<b>🏨 {name}</b><br>{_e(p.label)}');"
+            )
+            lines.append(
+                f"L.polyline([[{h.latitude},{h.longitude}],[{BC_PLACE_LAT},{BC_PLACE_LON}]],"
+                f"{{color:'#2563eb',dashArray:'5,7',weight:2}}).addTo(map);"
+            )
+    # POIs (from first package that has them)
+    for p in result.packages:
+        for a in (p.amenities or [])[:15]:
+            if a.latitude and a.longitude and (a.latitude, a.longitude) not in seen:
+                seen.add((a.latitude, a.longitude))
+                lines.append(
+                    f"L.marker([{a.latitude},{a.longitude}],{{icon:poiIcon}})"
+                    f".addTo(map).bindPopup('{escape(a.category)} · {escape(a.name)}');"
+                )
+        if p.amenities:
+            break
+    return "\n".join(lines)
+
+
+def render_map(result: TripPackageResult) -> str:
+    return f"""
+{_CSS}
+<div class="md-wrap">
+  <link rel="stylesheet" href="https://unpkg.com/leaflet@1.9.4/dist/leaflet.css"/>
+  <div id="matchday-map"></div>
+  <script src="https://unpkg.com/leaflet@1.9.4/dist/leaflet.js"></script>
+  <script>
+  (function(){{
+    var el=document.getElementById('matchday-map');
+    if(!el||window.L===undefined){{return;}}
+    if(el._lmap){{el._lmap.remove();}}
+    var map=L.map('matchday-map').setView([{BC_PLACE_LAT},{BC_PLACE_LON}],15);
+    el._lmap=map;
+    L.tileLayer('https://{{s}}.tile.openstreetmap.org/{{z}}/{{x}}/{{y}}.png',{{maxZoom:19,attribution:'© OpenStreetMap'}}).addTo(map);
+    var stadiumIcon=L.divIcon({{html:'🏟️',iconSize:[26,26],iconAnchor:[13,13]}});
+    var hotelIcon=L.divIcon({{html:'🏨',iconSize:[22,22],iconAnchor:[11,11]}});
+    var poiIcon=L.divIcon({{html:'📍',iconSize:[16,16],iconAnchor:[8,8]}});
+    {_js_markers(result)}
+  }})();
+  </script>
+</div>
+"""
+
+
+def render_full(result: TripPackageResult) -> str:
+    return render_status_bar(result) + render_cards(result) + render_map(result)

matchday/scoring.py

@@ -0,0 +1,608 @@
+"""
+MatchDay -- Deterministic scoring engine for travel package ranking.
+
+Based on the blueprint scoring section (IMPLEMENTATION_PLAN.md), lessons from
+errors.py (FailoverReason taxonomy), and models.py (Pydantic domain models).
+
+Architecture:
+  - ScoringWeights: frozen dataclass holding cost/buffer/transit weight triples
+    (inspired by BudgetConfig pattern from reference codebases).
+  - BUDGET_WEIGHTS: tiered weight profiles (budget, mid_range, premium).
+  - min_max_scale: 0-1 normalizer with epsilon guard against zero-variance.
+  - filter_late_arrivals: removes flights whose arrival is after kickoff.
+  - score_options: the main entry point -- cartesian product of flights x hotels,
+    normalizes, applies weights, deduplicates, returns top 3 ScoredPackage.
+  - Dedup key: (flight_number, departure_time.date(), origin, hotel_name,
+    hotel_address) per blueprint audit finding H3.
+
+Edge cases handled:
+  - Empty flights list => return []
+  - Empty hotels list => score flights only with hotel=None
+  - All flights arrive after kickoff => return [] (scoring_all_late)
+  - All prices are None => return [] (scoring_missing_prices)
+  - Single or double distinct options => return what is available
+  - Zero-variance cost/buffer/transit => neutral score (0.5) via epsilon
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import date, datetime, timezone
+from typing import Literal
+from zoneinfo import ZoneInfo
+
+from matchday.models import Flight, Hotel, ScoredPackage, Weather
+
+
+# ---------------------------------------------------------------------------
+# ScoringWeights -- frozen weight triples (BudgetConfig pattern)
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class ScoringWeights:
+    """Dimension weights for the composite scoring formula.
+
+    Every weight is a float in [0.0, 1.0]. The three weights do not
+    strictly need to sum to 1.0, but they do in every defined profile for
+    intuitive interpretability.
+
+    Attributes
+    ----------
+    cost:
+        Weight for the normalised cost dimension (higher = more important).
+        Invert=true is applied before weighting: *lower* costs score higher.
+    buffer:
+        Weight for the arrival buffer dimension (hours before kickoff).
+        Higher buffers score higher.
+    transit:
+        Weight for the hotel-to-stadium transit dimension (minutes).
+        Invert=true is applied before weighting: *shorter* transits score higher.
+    """
+
+    cost: float
+    buffer: float
+    transit: float
+
+
+BUDGET_WEIGHTS: dict[str, ScoringWeights] = {
+    "budget": ScoringWeights(cost=0.50, buffer=0.30, transit=0.20),
+    "mid_range": ScoringWeights(cost=0.35, buffer=0.30, transit=0.35),
+    "premium": ScoringWeights(cost=0.20, buffer=0.35, transit=0.45),
+}
+"""Tiered weight profiles keyed by budget_tier string.
+
+- ``budget``: Cost matters most (50 %), transit least (20 %).
+- ``mid_range``: Balanced, with a slight lean toward cost.
+- ``premium``: Comfort (buffer + transit) matters more than cost.
+"""
+
+
+# ---------------------------------------------------------------------------
+# Normalization helper
+# ---------------------------------------------------------------------------
+
+
+def min_max_scale(values: list[float], invert: bool = False) -> list[float]:
+    """Normalise a list of floats to [0.0, 1.0] via min-max scaling.
+
+    When ``invert=True``, the result is flipped so that the *smallest* input
+    value maps to 1.0 and the *largest* maps to 0.0. Use this for dimensions
+    where lower is better (cost, transit time).
+
+    The ``epsilon = 1e-6`` guard prevents division by zero when all values
+    are identical. In that degenerate case, every element receives 0.5,
+    representing a neutral score (neither better nor worse than peers).
+
+    Parameters
+    ----------
+    values:
+        The raw dimension values to normalise. Must be non-empty.
+    invert:
+        When True, smaller raw values produce larger normalised scores.
+
+    Returns
+    -------
+    list[float]
+        Normalised scores in [0.0, 1.0], one per input value.
+
+    Examples
+    --------
+    >>> min_max_scale([100.0, 200.0, 300.0])
+    [0.0, 0.5, 1.0]
+    >>> min_max_scale([100.0, 200.0, 300.0], invert=True)
+    [1.0, 0.5, 0.0]
+    >>> min_max_scale([5.0, 5.0, 5.0])
+    [0.5, 0.5, 0.5]  # epsilon guard
+    """
+    if not values:
+        return []
+
+    epsilon = 1e-6
+    v_min = min(values)
+    v_max = max(values)
+    span = v_max - v_min
+
+    # All values are identical (within epsilon): return neutral score.
+    if span < epsilon:
+        return [0.5] * len(values)
+
+    scaled = [(v - v_min) / span for v in values]
+    return [1.0 - s if invert else s for s in scaled]
+
+
+# ---------------------------------------------------------------------------
+# Late arrival filter
+# ---------------------------------------------------------------------------
+
+
+# Vancouver time zone — BC Place matches kick off in Pacific Time. ZoneInfo is
+# DST-aware, so the kickoff instant is correct on both PDT (UTC-7) and PST dates.
+_VANCOUVER = ZoneInfo("America/Vancouver")
+_DEFAULT_KICKOFF_HOUR = 19  # 7:00 PM local
+
+
+def _to_vancouver_aware(dt: datetime) -> datetime:
+    """Return ``dt`` as a Vancouver-timezone-aware datetime.
+
+    Naive datetimes (e.g. SerpApi local times that carry no tz info) are
+    treated as Vancouver-local. This keeps comparisons/subtractions against the
+    aware kickoff from raising ``TypeError`` (aware vs naive) and keeps the
+    timezone consistent across the scoring math.
+    """
+    if dt.tzinfo is None:
+        return dt.replace(tzinfo=_VANCOUVER)
+    return dt
+
+
+def _default_kickoff_dt(match_date: date) -> datetime:
+    """Default kickoff as 7:00 PM Pacific Time on ``match_date``.
+
+    World Cup matches at BC Place are typically evening local time. The result
+    is DST-aware (correct PDT/PST offset for the date), fixing the prior bug
+    where kickoff was built as 19:00 UTC (12:00 PDT) — 7 hours too early.
+    """
+    return datetime(
+        match_date.year,
+        match_date.month,
+        match_date.day,
+        _DEFAULT_KICKOFF_HOUR,
+        0,
+        0,
+        tzinfo=_VANCOUVER,
+    )
+
+
+def filter_late_arrivals(
+    flights: list[Flight], kickoff: datetime
+) -> list[Flight]:
+    """Return only flights whose arrival is strictly before kickoff.
+
+    Flights arriving exactly at or after ``kickoff`` are excluded because
+    the traveler cannot reach BC Place before the match starts.
+
+    Parameters
+    ----------
+    flights:
+        Candidate flights to filter.
+    kickoff:
+        Match kickoff datetime (timezone-aware). Flights with arrival times
+        prior to this (strictly less) are kept.
+
+    Returns
+    -------
+    list[Flight]
+        Flights that arrive before kickoff. May be empty.
+    """
+    return [f for f in flights if _to_vancouver_aware(f.arrival_time) < kickoff]
+
+
+# ---------------------------------------------------------------------------
+# Deduplication
+# ---------------------------------------------------------------------------
+
+
+def _dedup_key(flight: Flight, hotel: Hotel | None) -> tuple:
+    """Compute a stable deduplication key for a flight+hotel combination.
+
+    Per blueprint audit finding H3, the dedup key is:
+        (flight_number, departure_time.date(), origin, hotel_name, hotel_address)
+
+    When ``hotel`` is None (no hotels available), the hotel_name and
+    hotel_address are both replaced with ``"__NONE__"`` so that flight-only
+    options are still deduplicated among themselves.
+
+    Parameters
+    ----------
+    flight:
+        The flight in this combination.
+    hotel:
+        The hotel in this combination, or None.
+
+    Returns
+    -------
+    tuple
+        A hashable dedup key.
+    """
+    return (
+        flight.flight_number,
+        flight.departure_time.date(),
+        flight.origin,
+        hotel.name if hotel is not None else "__NONE__",
+        # Use hotel name as proxy for address since Hotel model has no
+        # explicit address field. Coordinates would be more precise but
+        # are impractical as a dedup key component.
+        hotel.name if hotel is not None else "__NONE__",
+    )
+
+
+# ---------------------------------------------------------------------------
+# Main scoring function
+# ---------------------------------------------------------------------------
+
+
+def score_options(
+    flights: list[Flight],
+    hotels: list[Hotel],
+    weather: list[Weather],
+    match_date: date,
+    budget_tier: str = "mid_range",
+) -> list[ScoredPackage]:
+    """Score and rank travel packages from candidate flights and hotels.
+
+    This is the main entry point for the scoring engine. It performs:
+
+    1. Filter late arrivals (flights arriving after 7 PM PT kickoff).
+    2. Cartesian product of every (flight, hotel) combination.
+    3. Compute ``total_cost_cad``, ``arrival_buffer_hours``, and
+       ``hotel_to_stadium_min`` for each combination.
+    4. Skip combinations where cost data is missing (None sentinel).
+    5. Min-max normalise each dimension across all valid combinations.
+    6. Apply budget-adjusted weights to produce a composite score.
+    7. Sort by composite score descending.
+    8. Select top 3 distinct combinations (by dedup key).
+    9. Label each selected package: cheapest by cost, safest by buffer,
+       closest by transit.
+
+    Edge cases (all produce deterministic results, never raise):
+
+    - ``flights`` is empty -> return []
+    - ``hotels`` is empty -> score flights only, label hotels as "unavailable"
+    - All flights arrive after kickoff -> return [] (reason: scoring_all_late)
+    - All prices are None -> return [] (reason: scoring_missing_prices)
+    - Only 1-2 distinct dedup options -> return what is available
+
+    Parameters
+    ----------
+    flights:
+        All candidate flights from the SerpApi normalizer.
+    hotels:
+        All candidate hotels from the SerpApi normalizer. May be empty.
+    weather:
+        Weather forecasts for dates overlapping the trip. Used as display
+        data only -- not incorporated into the composite score (per audit
+        finding H4).
+    match_date:
+        The date of the match. Used to compute the default kickoff time.
+    budget_tier:
+        One of ``"budget"``, ``"mid_range"``, or ``"premium"``. Selects
+        the weight profile from ``BUDGET_WEIGHTS``. Defaults to
+        ``"mid_range"``.
+
+    Returns
+    -------
+    list[ScoredPackage]
+        Ranked packages, at most 3, ordered by composite score descending.
+        Empty list when no valid combinations exist.
+    """
+    # -- Resolve weights ----------------------------------------------------
+    weights = BUDGET_WEIGHTS.get(
+        budget_tier,
+        BUDGET_WEIGHTS["mid_range"],  # safe fallback
+    )
+
+    # -- Edge case: no flights ----------------------------------------------
+    if not flights:
+        return []
+
+    # -- Filter late arrivals -----------------------------------------------
+    kickoff = _default_kickoff_dt(match_date)
+    on_time_flights = filter_late_arrivals(flights, kickoff)
+
+    # -- Edge case: all flights are late ------------------------------------
+    if not on_time_flights:
+        return []
+
+    # -- Build all valid (flight, hotel) combinations -----------------------
+    # When hotels is empty, treat it as [None] so we create flight-only combos.
+    hotel_list: list[Hotel | None] = list(hotels) if hotels else [None]
+
+    scored: list[_ScoredCandidate] = []
+
+    for flight in on_time_flights:
+        for hotel in hotel_list:
+            candidate = _score_single_option(
+                flight=flight,
+                hotel=hotel,
+                kickoff=kickoff,
+            )
+            if candidate is not None:
+                scored.append(candidate)
+
+    # -- Edge case: all prices are None -------------------------------------
+    if not scored:
+        return []
+
+    # -- Normalise each dimension -------------------------------------------
+    costs = [c.total_cost_cad for c in scored]
+    buffers = [c.arrival_buffer_hours for c in scored]
+    transits = [c.hotel_to_stadium_min for c in scored]
+
+    norm_costs = min_max_scale(costs, invert=True)    # lower cost = higher score
+    norm_buffers = min_max_scale(buffers)              # higher buffer = higher score
+    norm_transits = min_max_scale(transits, invert=True)  # shorter transit = higher score
+
+    # -- Compute composite score --------------------------------------------
+    for i, candidate in enumerate(scored):
+        candidate.composite = (
+            weights.cost * norm_costs[i]
+            + weights.buffer * norm_buffers[i]
+            + weights.transit * norm_transits[i]
+        )
+
+    # -- Sort by composite descending ---------------------------------------
+    scored.sort(key=lambda c: c.composite, reverse=True)
+
+    # -- Deduplicate, keeping highest-scoring per key -----------------------
+    seen: set[tuple] = set()
+    distinct: list[_ScoredCandidate] = []
+    for candidate in scored:
+        key = _dedup_key(candidate.flight, candidate.hotel)
+        if key not in seen:
+            seen.add(key)
+            distinct.append(candidate)
+
+    # -- Select top 3 -------------------------------------------------------
+    top = distinct[:3]
+
+    # -- Label winners ------------------------------------------------------
+    _label_top_three(top)
+
+    # -- Build ScoredPackage models -----------------------------------------
+    now = datetime.now(timezone.utc)
+    packages: list[ScoredPackage] = []
+
+    for candidate in top:
+        # Compute per-dimension scores for the scores dict
+        dim_scores = {
+            "affordability": norm_costs[scored.index(candidate)]
+            if candidate in scored
+            else 0.5,
+            "arrival_buffer": norm_buffers[scored.index(candidate)]
+            if candidate in scored
+            else 0.5,
+            "proximity": norm_transits[scored.index(candidate)]
+            if candidate in scored
+            else 0.5,
+            "composite": candidate.composite,
+        }
+
+        package = ScoredPackage(
+            label=candidate.label,
+            flight=candidate.flight,
+            hotel=candidate.hotel,
+            weather=weather,
+            amenities=[],  # amenities are populated by the caller
+            total_cost_cad=candidate.total_cost_cad,
+            arrival_buffer_hours=candidate.arrival_buffer_hours,
+            hotel_to_stadium_min=candidate.hotel_to_stadium_min,
+            scores=dim_scores,
+            explanation="",  # Explanation is filled by Nemotron after scoring
+            generated_at=now,
+        )
+        packages.append(package)
+
+    return packages
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+class _ScoredCandidate:
+    """Internal mutable candidate for scoring before ScoredPackage assembly.
+
+    This is a simple attribute holder (not a frozen dataclass) because the
+    composite score is computed in two phases: first the raw dimensions are
+    calculated, then after normalisation the composite is set.
+    """
+
+    __slots__ = (
+        "flight",
+        "hotel",
+        "total_cost_cad",
+        "arrival_buffer_hours",
+        "hotel_to_stadium_min",
+        "composite",
+        "label",
+    )
+
+    def __init__(
+        self,
+        flight: Flight,
+        hotel: Hotel | None,
+        total_cost_cad: float,
+        arrival_buffer_hours: float,
+        hotel_to_stadium_min: int,
+    ) -> None:
+        self.flight = flight
+        self.hotel = hotel
+        self.total_cost_cad = total_cost_cad
+        self.arrival_buffer_hours = arrival_buffer_hours
+        self.hotel_to_stadium_min = hotel_to_stadium_min
+        self.composite = 0.0
+        self.label: Literal["Cheapest", "Safest Arrival", "Closest to Stadium", ""] = ""
+
+
+def _score_single_option(
+    flight: Flight,
+    hotel: Hotel | None,
+    kickoff: datetime,
+) -> _ScoredCandidate | None:
+    """Compute raw dimensions for one (flight, hotel) combination.
+
+    Returns ``None`` when the combination is invalid (missing price data).
+
+    Parameters
+    ----------
+    flight:
+        The flight in this combination.
+    hotel:
+        The hotel in this combination, or None for flight-only.
+    kickoff:
+        Match kickoff datetime.
+
+    Returns
+    -------
+    _ScoredCandidate | None
+        The candidate with raw dimensions, or None if prices are missing.
+    """
+    # -- Total cost ---------------------------------------------------------
+    # Flights with unavailable prices cannot be scored.
+    if flight.price_cad is None:
+        return None
+
+    total_cost = flight.price_cad
+
+    # Add hotel cost when hotel is available and has a total price.
+    if hotel is not None:
+        if hotel.total_price_cad is not None:
+            total_cost += hotel.total_price_cad
+        elif hotel.price_per_night_cad is not None:
+            # Approximate: total = price_per_night * nights
+            # Nights can't be derived without check-in/check-out from the
+            # caller; this path uses price_per_night as a fallback.
+            # The calling code should pass explicit total_price_cad when
+            # available.
+            total_cost += hotel.price_per_night_cad
+        else:
+            # Hotel has no price data at all -- score it with flight cost only.
+            # This is a partial result; the frontend will display "price
+            # unavailable" for the hotel.
+            pass
+
+    # -- Arrival buffer -----------------------------------------------------
+    # kickoff and flight.arrival_time are both timezone-aware (or naive but
+    # consistent). Compute the difference in hours.
+    buffer_seconds = (kickoff - _to_vancouver_aware(flight.arrival_time)).total_seconds()
+    buffer_hours = buffer_seconds / 3600.0
+
+    # -- Hotel-to-stadium transit -------------------------------------------
+    if hotel is not None and hotel.distance_to_stadium_km is not None:
+        # Convert distance to an estimated walking time at 5 km/h average pace.
+        # This is a rough proxy; the ORS API provides actual walking routes.
+        transit_min = int(round((hotel.distance_to_stadium_km / 5.0) * 60))
+    elif hotel is not None and hotel.latitude is not None and hotel.longitude is not None:
+        # Hotel has coordinates but no pre-computed distance. Use a small
+        # default rather than failing.
+        transit_min = 30
+    else:
+        transit_min = 0
+
+    return _ScoredCandidate(
+        flight=flight,
+        hotel=hotel,
+        total_cost_cad=round(total_cost, 2),
+        arrival_buffer_hours=round(buffer_hours, 2),
+        hotel_to_stadium_min=transit_min,
+    )
+
+
+def _label_top_three(
+    candidates: list[_ScoredCandidate],
+) -> None:
+    """Assign labels to the top scored candidates.
+
+    Labels are assigned greedily by finding the best-in-class for each
+    objective:
+
+    - ``Cheapest``: The candidate with the lowest ``total_cost_cad``.
+    - ``Safest Arrival``: The candidate with the highest
+      ``arrival_buffer_hours``.
+    - ``Closest to Stadium``: The candidate with the lowest
+      ``hotel_to_stadium_min``.
+
+    A single candidate can win only one label. If fewer than 3 candidates
+    exist, only the available labels are assigned.
+
+    Parameters
+    ----------
+    candidates:
+        The top scored candidates (at most 3), pre-sorted by composite
+        descending. Labels are assigned in-place.
+    """
+    if not candidates:
+        return
+
+    # Available labels to assign
+    labels: list[Literal["Cheapest", "Safest Arrival", "Closest to Stadium"]] = [
+        "Cheapest",
+        "Safest Arrival",
+        "Closest to Stadium",
+    ]
+
+    # Track which candidates have already received a label
+    assigned_indices: set[int] = set()
+
+    for label in labels:
+        if len(assigned_indices) >= len(candidates):
+            break
+
+        best_idx: int | None = None
+
+        if label == "Cheapest":
+            # Pick the candidate with the lowest cost that hasn't been labelled
+            best_val = float("inf")
+            for i, c in enumerate(candidates):
+                if i in assigned_indices:
+                    continue
+                if c.total_cost_cad < best_val:
+                    best_val = c.total_cost_cad
+                    best_idx = i
+        elif label == "Safest Arrival":
+            # Pick the candidate with the highest buffer
+            best_val = float("-inf")
+            for i, c in enumerate(candidates):
+                if i in assigned_indices:
+                    continue
+                if c.arrival_buffer_hours > best_val:
+                    best_val = c.arrival_buffer_hours
+                    best_idx = i
+        elif label == "Closest to Stadium":
+            # Pick the candidate with the lowest transit time
+            best_val = float("inf")
+            for i, c in enumerate(candidates):
+                if i in assigned_indices:
+                    continue
+                if c.hotel_to_stadium_min < best_val:
+                    best_val = c.hotel_to_stadium_min
+                    best_idx = i
+
+        if best_idx is not None:
+            candidates[best_idx].label = label
+            assigned_indices.add(best_idx)
+
+    # Safety net for any still-unlabelled candidate. Not reachable when
+    # len(candidates) <= 3 (the greedy loop above assigns one distinct label
+    # per candidate), but assign from the UNUSED labels rather than by raw
+    # index so duplicate labels are impossible even if this ever fires.
+    used = {c.label for c in candidates if c.label}
+    remaining = [
+        lab
+        for lab in ("Cheapest", "Safest Arrival", "Closest to Stadium")
+        if lab not in used
+    ]
+    for c in candidates:
+        if c.label == "" and remaining:
+            c.label = remaining.pop(0)

matchday/traces/session_001.jsonl

@@ -0,0 +1,4 @@
+{"ts": "2026-06-13T21:09:55.888255+00:00", "event": "user", "content": "Flying from Montreal, want Canada vs Qatar, mid-range, June 26-29, just me"}
+{"ts": "2026-06-13T21:09:58.239967+00:00", "event": "nemotron_decision", "tool_calls": [{"name": "build_trip_packages", "arguments": {"check_out": "2026-06-29", "budget_tier": "mid_range", "origin_airport": "YUL", "match_name": "Canada vs Qatar", "check_in": "2026-06-26", "match_date": "2026-06-26", "travelers": 1}, "id": "call_c70b566e1c79417b8ae924eb"}], "text": "\n"}
+{"ts": "2026-06-13T21:09:59.343542+00:00", "event": "tool_result", "tool": "build_trip_packages", "trip": "YUL -> Vancouver, 2026-06-26 to 2026-06-29, mid_range budget, 1 traveler, watching Canada vs Qatar on 2026-06-26.", "status": "complete", "degradation": ["Photos unavailable"], "packages": [{"label": "Cheapest", "total_cost_cad": 890.0, "flight": "Flair Airlines F8 107 (lands 11:00)", "hotel": "Hotel At The Waldorf", "provenance": {"flight": "serpapi", "hotel": "serpapi"}}, {"label": "Safest Arrival", "total_cost_cad": 970.0, "flight": "Air Canada AC 303 (lands 10:45)", "hotel": "Hotel At The Waldorf", "provenance": {"flight": "serpapi", "hotel": "serpapi"}}, {"label": "Closest to Stadium", "total_cost_cad": 1353.0, "flight": "Flair Airlines F8 107 (lands 11:00)", "hotel": "Best Western Premier Chateau Granville Hotel & Suites & Conf. Centre", "provenance": {"flight": "serpapi", "hotel": "serpapi"}}], "compact": "STATUS: complete | 1 degradation(s) | 3 package(s) scored\n  DEGRADATION: Photos unavailable\n#1 Cheapest             | $890.00 CAD | Flight Flair Airlines F8 107 lands 11:00 from YUL (source=serpapi) | Hotel Hotel At The Waldorf 3.367km to BC Place 3.6\u2605 (source=serpapi) | +8.0h buffer | 40 min walk | rain risk 35%\n#2 Safest Arrival       | $970.00 CAD | Flight Air Canada AC 303 lands 10:45 from YUL (source=serpapi) | Hotel Hotel At The Waldorf 3.367km to BC Place 3.6\u2605 (source=serpapi) | +8.2h buffer | 40 min walk | rain risk 35%\n#3 Closest to Stadium   | $1,353.00 CAD | Flight Flair Airlines F8 107 lands 11:00 from YUL (source=serpapi) | Hotel Best Western Premier Chateau Granville Hotel & Suites & Conf. Centre 0.615km to BC Place 4.2\u2605 (source=serpapi) | +8.0h buffer | 7 min walk | rain risk 35%"}
+{"ts": "2026-06-13T21:10:01.869612+00:00", "event": "nemotron_explanation", "text": "**#1 Cheapest** \u2013 $890.00 CAD | Airline: Flair Airlines | Arrival: 11:00 | Hotel: Hotel At The Waldorf | Distance: 3.367km to BC Place | Weather: rain risk 35% (example)  \n**#2 Safest Arrival** \u2013 $970.00 CAD | Airline: Air Canada | Arrival: 10:45 | Hotel: Hotel At The Waldorf | Distance: 3.367km to BC Place | Weather: rain risk 35% (example)  \n**#3 Closest to Stadium** \u2013 $1,353.00 CAD | Airline: Flair Airlines | Arrival: 11:00 | Hotel: Best Western Premier Chateau Granville Hotel & Suites & Conf. Centre | Distance: 0.615km to BC Place | Weather: rain risk 35% (example)  \n\n**Recommendation:** Closest to Stadium offers the shortest walk but at a premium price."}

matchday/trip_tool.py

@@ -0,0 +1,563 @@
+"""
+MatchDay -- Coarse-grained trip-package assembly tool.
+
+Nemotron calls this single tool with a validated ``TripRequest``. Python
+handles everything inside:
+
+1. Validate the ``TripRequest`` with Pydantic (belt-and-suspenders).
+2. Call all enabled API normalizers (flights, hotels, weather, amenities,
+   photos) concurrently via ``asyncio.gather()``.
+3. Handle partial failures -- some APIs may be down, others succeed.
+4. Run deterministic scoring via ``scoring.score_options()``.
+5. Return a compact ``TripPackageResult``.
+
+Nemotron never sees raw API results. It only sees the scored packages and
+compact text summaries.
+
+Architecture
+------------
+``build_trip_packages`` is the top-level entry point called by Nemotron.
+It performs the full pipeline synchronisation, then hands the scored result
+to ``format_for_nemotron`` for compact serialisation.
+
+``TripPackageResult`` is the structured return type, carrying the scored
+packages, a status enum, degradation notices, and provenance metadata.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from datetime import datetime, timezone
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict
+
+from matchday import scoring
+from matchday.api_registry import registry
+from matchday.errors import (
+    DegradeImmediately,
+    FailoverReason,
+    MaxRetriesExceeded,
+    user_message_for,
+)
+from matchday.models import (
+    Amenity,
+    Flight,
+    Hotel,
+    ScoredPackage,
+    TripRequest,
+    Weather,
+)
+
+# Side-effect import: registers every API normalizer (weather/pois/flights/
+# hotels) with the module-level ``registry`` so dispatch() below finds them.
+# Without this, the registry is inert and every dispatch returns "Unknown
+# normalizer". Keep this AFTER the ``matchday.*`` imports above.
+import matchday.apis  # noqa: F401,E402
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# TripPackageResult -- Nemotron-facing result envelope
+# ---------------------------------------------------------------------------
+
+
+class TripPackageResult(BaseModel):
+    """Compact result envelope returned to Nemotron.
+
+    ``packages`` is always sorted by composite score descending (highest
+    overall value first). The list may be empty when no valid packages
+    could be formed.
+
+    ``status`` reflects the overall health of the pipeline:
+      - ``"complete"``: All four core API categories (flights, hotels,
+        weather, amenities) succeeded.
+      - ``"partial"``: At least one core category failed but packages
+        were still formed from the available data.
+      - ``"failed"``: No packages could be formed (critical failures
+        across all categories).
+    """
+
+    packages: list[ScoredPackage]
+    """Scored and ranked packages, at most 3. May be empty."""
+
+    status: Literal["complete", "partial", "failed"]
+    """Pipeline health indicator."""
+
+    degradation_notices: list[str]
+    """Human-readable notices for every category that failed or degraded.
+
+    Examples::
+
+        ["Hotels unavailable, showing flights only",
+         "Weather forecast unavailable"]
+    """
+
+    generated_at: datetime
+    """Timestamp when this result was assembled."""
+
+    total_combinations_scored: int
+    """Number of (flight, hotel) combinations that were scored.
+
+    Zero indicates that no combinations were valid (e.g. all prices
+    missing, all flights late).
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+
+# ---------------------------------------------------------------------------
+# Category constants
+# ---------------------------------------------------------------------------
+
+_CORE_CATEGORIES: list[str] = [
+    "flights",
+    "hotels",
+    "weather",
+    "amenities",
+]
+"""Categories that are required for a ``"complete"`` status."""
+
+_OPTIONAL_CATEGORIES: list[str] = [
+    "photos",
+]
+"""Categories that are always optional; their failure never degrades status."""
+
+_ALL_CATEGORIES: list[str] = _CORE_CATEGORIES + _OPTIONAL_CATEGORIES
+"""All categories dispatched during build_trip_packages."""
+
+
+# ---------------------------------------------------------------------------
+# Category dispatch helpers
+# ---------------------------------------------------------------------------
+
+
+async def _dispatch_category(
+    category: str,
+    params: dict[str, Any],
+) -> tuple[str, Any]:
+    """Dispatch all enabled normalizers in *category* and return their data.
+
+    Parameters
+    ----------
+    category:
+        Category key to dispatch (e.g. ``"flights"``, ``"hotels"``).
+    params:
+        Input parameters forwarded to every normalizer in the category.
+
+    Returns
+    -------
+    tuple[str, Any]
+        ``(category, aggregated_data)`` where *aggregated_data* is the
+        merged result from all successful normalizers in the category.
+        The merge strategy is category-specific:
+
+        - ``flights``: merged list of ``Flight`` objects.
+        - ``hotels``: merged list of ``Hotel`` objects.
+        - ``weather``: merged list of ``Weather`` objects.
+        - ``amenities``: merged list of ``Amenity`` objects.
+        - ``photos``: merged list of photo URLs / metadata.
+
+        On total failure (no normalizers enabled, all failed, or none
+        registered), the value is ``None``.
+    """
+    enabled = registry.get_enabled_normalizers(category=category)
+
+    if not enabled:
+        return category, None
+
+    # Dispatch all enabled normalizers concurrently
+    tasks = [registry.dispatch(name, params) for name in enabled]
+    results = await asyncio.gather(*tasks, return_exceptions=True)
+
+    # Collect successful data, log failures
+    merged: list[Any] = []
+    for name, result in zip(enabled, results):
+        if isinstance(result, Exception):
+            logger.warning(
+                "Normalizer %s raised exception: %s: %s",
+                name,
+                type(result).__name__,
+                result,
+            )
+            continue
+        if result.success and result.data is not None:
+            data = result.data
+            if isinstance(data, list):
+                merged.extend(data)
+            else:
+                merged.append(data)
+        else:
+            logger.info(
+                "Normalizer %s returned failure: %s",
+                name,
+                result.error,
+            )
+
+    if not merged:
+        return category, None
+
+    return category, merged
+
+
+async def _dispatch_all(params: dict[str, Any]) -> dict[str, Any]:
+    """Dispatch all categories concurrently.
+
+    Parameters
+    ----------
+    params:
+        Input parameters forwarded to every category's normalizers.
+
+    Returns
+    -------
+    dict[str, Any]
+        Mapping from category name to aggregated data (or ``None`` on
+        total failure). Keys match those in ``_ALL_CATEGORIES``.
+    """
+    tasks = [_dispatch_category(cat, params) for cat in _ALL_CATEGORIES]
+    results = await asyncio.gather(*tasks)
+
+    return dict(results)
+
+
+# ---------------------------------------------------------------------------
+# Degradation notice generation
+# ---------------------------------------------------------------------------
+
+
+def _build_degradation_notices(category_data: dict[str, Any]) -> list[str]:
+    """Build human-readable degradation notices for failed categories.
+
+    Parameters
+    ----------
+    category_data:
+        Mapping from category name to aggregated data (``None`` means
+        total failure for that category).
+
+    Returns
+    -------
+    list[str]
+        Notices sorted in display order (core first).
+    """
+    notices: list[str] = []
+
+    for cat in _ALL_CATEGORIES:
+        data = category_data.get(cat)
+        if data is not None:
+            continue  # category succeeded
+
+        if cat == "flights":
+            notices.append("Flight search unavailable")
+        elif cat == "hotels":
+            notices.append("Hotels unavailable, showing flights only")
+        elif cat == "weather":
+            notices.append("Weather forecast unavailable")
+        elif cat == "amenities":
+            notices.append("Nearby amenities unavailable")
+        elif cat == "photos":
+            notices.append("Photos unavailable")
+
+    return notices
+
+
+def _infer_status(
+    category_data: dict[str, Any],
+    packages: list[ScoredPackage],
+) -> Literal["complete", "partial", "failed"]:
+    """Infer the result status from category health and packages.
+
+    "failed" when no packages exist and critical data (flights) is missing.
+    "complete" when all core categories succeeded.
+    "partial" when at least one core category failed but packages exist.
+    """
+    if not packages:
+        return "failed"
+
+    core_ok = all(
+        category_data.get(cat) is not None for cat in _CORE_CATEGORIES
+    )
+    return "complete" if core_ok else "partial"
+
+
+# ---------------------------------------------------------------------------
+# Main entry point
+# ---------------------------------------------------------------------------
+
+
+async def build_trip_packages(trip_request: TripRequest) -> TripPackageResult:
+    """Assemble and score trip packages for a validated ``TripRequest``.
+
+    This is the single coarse-grained tool that Nemotron calls. It:
+
+    1. Validates the ``TripRequest`` with Pydantic (already validated by
+       the caller, but belt-and-suspenders).
+    2. Dispatches all enabled API normalizers (flights, hotels, weather,
+       amenities, photos) concurrently via ``asyncio.gather()``.
+    3. Aggregates results per category; failures are recorded in
+       degradation notices rather than aborting the whole pipeline.
+    4. Passes flights, hotels, and weather to ``scoring.score_options()``
+       for deterministic ranking.
+    5. Attaches amenities to the top packages.
+    6. Wraps everything in a ``TripPackageResult`` with status and source
+       provenance.
+
+    Parameters
+    ----------
+    trip_request:
+        Fully validated trip intent from Nemotron's extraction step.
+        Every field has been checked by Pydantic validators in the
+        ``TripRequest`` model before reaching this function.
+
+    Returns
+    -------
+    TripPackageResult
+        Scored packages with status, degradation notices, and metadata.
+        **Never raises.** All errors (API failures, network issues, empty
+        results) are captured inside the result envelope.
+
+    Examples
+    --------
+    >>> from datetime import date
+    >>> req = TripRequest(
+    ...     origin_airport="YUL",
+    ...     match_name="Canada vs Qatar",
+    ...     match_date=date(2026, 7, 1),
+    ...     check_in=date(2026, 6, 30),
+    ...     check_out=date(2026, 7, 2),
+    ...     travelers=2,
+    ...     budget_tier="mid_range",
+    ... )
+    >>> result = await build_trip_packages(req)
+    >>> result.status
+    'complete'
+    >>> len(result.packages)
+    3
+    """
+    now = datetime.now(timezone.utc)
+
+    # ------------------------------------------------------------------
+    # 1. Validate TripRequest (belt-and-suspenders -- caller should have
+    #    already validated, but Pydantic model_validate is cheap)
+    # ------------------------------------------------------------------
+    try:
+        trip_request = TripRequest.model_validate(
+            trip_request.model_dump()
+        )
+    except Exception as exc:
+        return TripPackageResult(
+            packages=[],
+            status="failed",
+            degradation_notices=[f"Invalid trip request: {exc}"],
+            generated_at=now,
+            total_combinations_scored=0,
+        )
+
+    # ------------------------------------------------------------------
+    # 2. Dispatch all API categories concurrently
+    # ------------------------------------------------------------------
+    params = trip_request.model_dump()
+    # Add derived parameters that normalizers need
+    params["destination"] = "YVR"  # Vancouver International Airport
+    params["match_date"] = trip_request.match_date
+
+    category_data = await _dispatch_all(params)
+
+    flights_data: list[Flight] | None = category_data.get("flights")
+    hotels_data: list[Hotel] | None = category_data.get("hotels")
+    weather_data: list[Weather] | None = category_data.get("weather")
+    amenities_data: list[Amenity] | None = category_data.get("amenities")
+
+    # ------------------------------------------------------------------
+    # 3. Build degradation notices
+    # ------------------------------------------------------------------
+    degradation_notices = _build_degradation_notices(category_data)
+
+    # ------------------------------------------------------------------
+    # 4. Run deterministic scoring
+    # ------------------------------------------------------------------
+    if flights_data is None:
+        flights_data = []
+
+    if hotels_data is None:
+        hotels_data = []
+
+    if weather_data is None:
+        weather_data = []
+
+    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,
+    )
+
+    # ------------------------------------------------------------------
+    # 5. Attach amenities to scored packages
+    # ------------------------------------------------------------------
+    if scored_packages and amenities_data:
+        # ScoredPackage is frozen, so rebuild the list with amenities attached.
+        # The prior loop rebinding the local name ``pkg`` was a silent no-op --
+        # it never mutated ``scored_packages``. Cap per package (U3 budget).
+        amenities = list(amenities_data)[:25]
+        scored_packages = [
+            pkg.model_copy(update={"amenities": amenities})
+            for pkg in scored_packages
+        ]
+
+    total_combinations = len(scored_packages)
+
+    # ------------------------------------------------------------------
+    # 6. Build result envelope
+    # ------------------------------------------------------------------
+    status = _infer_status(category_data, scored_packages)
+
+    return TripPackageResult(
+        packages=scored_packages,
+        status=status,
+        degradation_notices=degradation_notices,
+        generated_at=now,
+        total_combinations_scored=total_combinations,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Compact serialisation for Nemotron
+# ---------------------------------------------------------------------------
+
+
+def format_for_nemotron(result: TripPackageResult) -> str:
+    """Return a compact string representation of ``TripPackageResult``.
+
+    The output is designed to stay under 2,000 tokens so Nemotron can
+    ingest it without consuming its entire context window. Only the most
+    salient fields are included:
+
+      - ``label`` (package objective name)
+      - ``total_cost`` (flight + hotel in CAD)
+      - ``arrival_buffer`` (hours before kickoff)
+      - ``transit_min`` (hotel-to-stadium walking minutes)
+      - ``weather_risk`` (simple summary of precipitation risk)
+
+    Raw API responses, full flight/hotel JSON blobs, and raw score vectors
+    are **not** included.
+
+    Parameters
+    ----------
+    result:
+        The result envelope from ``build_trip_packages``.
+
+    Returns
+    -------
+    str
+        Compact multi-line string representation, one line per package,
+        plus a status summary line.
+
+    Examples
+    --------
+    >>> result = await build_trip_packages(trip_request)
+    >>> print(format_for_nemotron(result))
+    STATUS: complete | 1 degradation | 3 packages scored
+      #1 Cheapest           | $1,245.00 CAD | +4.5h buffer | 12 min walk | rain risk 30%
+      #2 Safest Arrival     | $1,520.00 CAD | +8.2h buffer | 18 min walk | rain risk 30%
+      #3 Closest to Stadium | $1,670.00 CAD | +3.0h buffer |  5 min walk | rain risk 60%
+    """
+    lines: list[str] = []
+
+    status_line_parts: list[str] = [
+        f"STATUS: {result.status}",
+    ]
+
+    if result.degradation_notices:
+        status_line_parts.append(
+            f"{len(result.degradation_notices)} degradation(s)"
+        )
+    else:
+        status_line_parts.append("no degradation")
+
+    status_line_parts.append(
+        f"{result.total_combinations_scored} package(s) scored"
+    )
+    lines.append(" | ".join(status_line_parts))
+
+    # Append degradation detail lines when present
+    for notice in result.degradation_notices:
+        lines.append(f"  DEGRADATION: {notice}")
+
+    if not result.packages:
+        lines.append("  No packages available.")
+        return "\n".join(lines)
+
+    for idx, pkg in enumerate(result.packages, start=1):
+        parts: list[str] = [
+            f"#{idx} {pkg.label:<20}",
+        ]
+
+        parts.append(f"${pkg.total_cost_cad:,.2f} CAD")
+
+        # Flight details — give Nemotron the REAL carrier/route/time so its
+        # explanation quotes them instead of inventing flight numbers.
+        f = pkg.flight
+        parts.append(
+            f"Flight {f.airline} {f.flight_number} lands "
+            f"{f.arrival_time:%H:%M} from {f.origin} (source={f.source})"
+        )
+
+        # Hotel details — real name + distance so it isn't hallucinated.
+        h = pkg.hotel
+        if h is not None:
+            rating = f"{h.rating:g}★" if h.rating is not None else ""
+            parts.append(
+                f"Hotel {h.name} {h.distance_to_stadium_km:g}km to BC Place "
+                f"{rating} (source={h.source})"
+            )
+        else:
+            parts.append("Hotel: none (flight-only)")
+
+        buffer_sign = "+" if pkg.arrival_buffer_hours >= 0 else ""
+        parts.append(
+            f"{buffer_sign}{pkg.arrival_buffer_hours:.1f}h buffer"
+        )
+
+        parts.append(f"{pkg.hotel_to_stadium_min} min walk")
+
+        # Weather risk: pick max precipitation probability
+        if pkg.weather:
+            max_precip = max(
+                w.precipitation_probability for w in pkg.weather
+            )
+            parts.append(f"rain risk {max_precip:.0f}%")
+        else:
+            parts.append("weather N/A")
+
+        lines.append(" | ".join(parts))
+
+    return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# Convenience: build-and-format in one async call
+# ---------------------------------------------------------------------------
+
+
+async def build_and_format(trip_request: TripRequest) -> str:
+    """Build packages and return the compact string representation.
+
+    This is a convenience wrapper for Nemotron that collapses the two-step
+    pipeline into a single call. Nemotron calls this when it only needs the
+    text summary, not the structured ``TripPackageResult``.
+
+    Parameters
+    ----------
+    trip_request:
+        Validated trip intent.
+
+    Returns
+    -------
+    str
+        Compact formatted output from ``format_for_nemotron``.
+    """
+    result = await build_trip_packages(trip_request)
+    return format_for_nemotron(result)

requirements.txt

@@ -0,0 +1,8 @@
+# MatchDay runtime dependencies (HF Space + local).
+# The deterministic path needs only the first three; `modal` is required once
+# the Nemotron agent layer (N13) is wired in (it calls Modal remotely — the
+# 30B model never runs locally).
+gradio>=5.0
+httpx>=0.27
+pydantic>=2.0
+modal>=0.70