feat: Phase 2 - Functional simulation, OSM POI Overpass integration, and first-aid RAG

MR_DESCRIPTION.md

@@ -1,39 +1,35 @@
-# Merge Request / Pull Request Description: Initial Codebase Setup
+# Merge Request / Pull Request Description: Phase 2 - Functional + POI Integration
 
 ## 📝 Overview
-This Merge Request initializes the **Trailhead** Git repository. It configures the project settings, excludes local development artifacts, establishes container packaging setup, and adds user-facing documentation detailing the system architecture and features.
+This Merge Request delivers **Phase 2: Functional + POI Integration** for the **Trailhead** project. It introduces live and offline Points of Interest (POI) extraction via OpenStreetMap (Overpass API), integrates a local Wilderness First-Aid medical manual RAG search, and implements a full route simulation player with metrics HUD and proximity alert indicators.
 
 ## 🚀 Key Changes
-1. **Repository Setup**: Initialized local git configuration and renamed the default branch to `main`.
-2. **Environment Filtering (`.gitignore`)**: Added a standard `.gitignore` for Python environments to exclude:
-   - Python byte-code/compiled cache (`__pycache__/`, `*.pyc`)
-   - Virtual environments (`.venv/`, `venv/`, `env/`)
-   - Large model binary weights (`*.gguf`, `model/`)
-   - Operating system artifacts (`Thumbs.db`, `.DS_Store`)
-   - Local execution directories (`temp/`, `*.cache.json`)
-3. **Documentation (`README.md`)**:
-   - Outlined core features: GPX parsing, offline metrics (smoothed elevation gain, Naismith's time estimation), Wilderness Guide LLM (`google_gemma-4-E2B-it-GGUF` via `llama.cpp`), and voice-journaling.
-   - Built a Mermaid architecture flow diagram.
-   - Added setup and Docker deployment guides.
-4. **Containerization (`Dockerfile`)**: Configured the build setup, including pre-compiled CPU wheels for `llama-cpp-python` and pre-download steps for Gemma 4.
+1. **POI Integration (`gpx_parser.py`)**:
+   * Fetches key POIs (drinking water, spring, huts, shelters, campsites) dynamically within a custom bounding box of the track via the **OSM Overpass API**.
+   * Filters amenities locally using the **Haversine formula** within a 150m buffer of the route.
+   * Serializes/saves POIs into GPX XML `<extensions>` and `<wpt>` tags via `save_enhanced_gpx` for offline capabilities.
+2. **Wilderness First-Aid Guide (`first_aid_guide.json` & `rag.py`)**:
+   * Created a wilderness medical corpus covering 5 key sections (bleeding, hypothermia, heat, altitude sickness, musculoskeletal).
+   * Implemented keyword intersection matching in `rag.py` to ground first-aid queries, returning relevant guide text along with section citations.
+3. **Simulation HUD & Playback UI (`app.py`)**:
+   * Added simulation controls (Play, Pause, Speed slider, Reset).
+   * Displays dashboard metrics (Route progress %, distance walked, altitude, and dynamic ETA to next checkpoint).
+   * Sounds/shows offline proximity alerts when within 150m of any drinking water, camp, or hut.
+   * Integrated Wilderness First-Aid tab with static emergency cards and RAG manual search.
 
 ## 🛠️ Verification Done
-- Verified that untracked directories like `.venv/` and `temp/` are successfully ignored.
-- Ran `git status` to ensure clean staging.
-- Created local initial commit on branch `main`.
+* Created [test_overpass.py](file:///c:/Users/skushwaha/Documents/hckthn/TrailHead/test_overpass.py) to parse the preloaded Trento Track.
+* Verified Overpass API (`https://overpass-api.de/api/interpreter`) fetched, filtered, and returned 2 drinking water amenities successfully within a 150m buffer.
+* Validated that the first-aid RAG keyword search retrieves correct sections and references them.
 
 ---
 
 ## 📋 Steps to Push to GitHub
-If you haven't created the repository on GitHub yet:
-1. Go to [GitHub - Create a New Repository](https://github.com/new).
-2. Set the repository name to `TrailHead`. Do **not** initialize it with a README, gitignore, or license (since we have already created them).
-3. Copy the remote URL (e.g., `https://github.com/your-username/TrailHead.git`).
-4. Run the following commands in your terminal:
-   ```bash
-   # Add the remote repository
-   git remote add origin <your-github-repo-url>
+```bash
+# Add the remote repository (if not already linked)
+git remote add origin <your-github-repo-url>
+
+# Push all files to main
+git push -u origin main
+```
 
-   # Push the main branch to GitHub
-   git push -u origin main
-   ```

app.py

@@ -4,8 +4,9 @@ import requests
 import gradio as gr
 import pandas as pd
 import folium
-from src.gpx_parser import parse_gpx_file
+from src.gpx_parser import parse_gpx_file, haversine, save_enhanced_gpx
 import src.llm as llm
+import src.rag as rag
 
 # Initialize cache and temp folders
 os.makedirs("./temp", exist_ok=True)
@@ -13,21 +14,37 @@ os.makedirs("./temp", exist_ok=True)
 # Preloaded route path
 PRELOADED_ROUTE_PATH = r"C:\Users\skushwaha\Documents\hckthn\TrailHead\Routes\track_5-14724236830.gpx"
 
-def generate_folium_map(points, checkpoints):
+EMERGENCY_CARD = """
+## 🚨 IMMEDIATE BACKCOUNTRY EMERGENCY CARD (OFFLINE)
+If you encounter a medical crisis with no cellular signal, follow these basic steps:
+
+1. **Severe Bleeding:** Apply direct pressure with clean dressing. Elevate limb. Use tourniquet if blood is spurting.
+2. **Hypothermia:** Wrap in windproof shell/sleeping bag. Replace wet clothes. Provide warm sweet drinks.
+3. **Heat Stroke:** Move to shade. Actively cool by wetting skin and fanning. Sip cool water.
+4. **Altitude Illness (AMS/HAPE/HACE):** Descend immediately. Do not ascend. Administer oxygen if available.
+5. **Ankle Sprain (R.I.C.E):** Rest the joint. Ice or apply cold pack. Compress with elastic bandage. Elevate limb.
+
+*Disclaimer: This guide is for offline reference only. Always carry a PLB/satellite communicator on remote trails.*
+"""
+
+def generate_folium_map(points, checkpoints, pois, hiker_pos=None):
     """
-    Generate interactive folium map.
+    Generate interactive folium map rendering track, checkpoints, POIs, and current hiker pos.
     """
     if not points:
-        # Default centered map
         m = folium.Map(location=[46.0734974, 11.1717214], zoom_start=13)
         return m._repr_html_()
         
-    # Center map on the middle point of the track
-    mid_idx = len(points) // 2
-    start_lat = points[mid_idx]["lat"]
-    start_lon = points[mid_idx]["lon"]
-    
-    m = folium.Map(location=[start_lat, start_lon], zoom_start=14)
+    # Center map on current hiker position or middle of track
+    if hiker_pos:
+        center_lat, center_lon = hiker_pos["lat"], hiker_pos["lon"]
+        zoom_val = 15
+    else:
+        mid_idx = len(points) // 2
+        center_lat, center_lon = points[mid_idx]["lat"], points[mid_idx]["lon"]
+        zoom_val = 14
+        
+    m = folium.Map(location=[center_lat, center_lon], zoom_start=zoom_val)
     
     # Draw track polyline
     locations = [(p["lat"], p["lon"]) for p in points]
@@ -41,7 +58,6 @@ def generate_folium_map(points, checkpoints):
         ele = cp["ele"]
         dist = cp["cum_dist"]
         
-        # Color code markers
         if name == "Start":
             color = "green"
             icon = "play"
@@ -59,7 +75,6 @@ def generate_folium_map(points, checkpoints):
             Elevation: {ele:.1f} m
         </div>
         """
-        
         folium.Marker(
             location=[lat, lon],
             popup=popup_text,
@@ -67,6 +82,45 @@ def generate_folium_map(points, checkpoints):
             icon=folium.Icon(color=color, icon=icon)
         ).add_to(m)
         
+    # Draw POIs
+    for poi in pois:
+        poi_type = poi["type"]
+        icon_color = "purple"
+        icon_name = "info-sign"
+        
+        if "water" in poi_type or "spring" in poi_type:
+            icon_color = "blue"
+            icon_name = "tint"
+        elif "camp" in poi_type:
+            icon_color = "orange"
+            icon_name = "home"
+        elif "hut" in poi_type or "shelter" in poi_type:
+            icon_color = "green"
+            icon_name = "home"
+            
+        popup_text = f"""
+        <div style="font-family: 'Outfit', sans-serif; font-size: 11px;">
+            <b>{poi['name']}</b><br>
+            Type: {poi_type.replace('_', ' ').title()}<br>
+            Distance to Route: {poi['distance']:.1f} m
+        </div>
+        """
+        folium.Marker(
+            location=[poi["lat"], poi["lon"]],
+            popup=popup_text,
+            tooltip=poi['name'],
+            icon=folium.Icon(color=icon_color, icon=icon_name)
+        ).add_to(m)
+        
+    # Draw hiker's simulated position
+    if hiker_pos:
+        folium.Marker(
+            location=[hiker_pos["lat"], hiker_pos["lon"]],
+            popup=f"Current: {hiker_pos['cum_dist']/1000.0:.2f}km<br>Ele: {hiker_pos['ele']:.1f}m",
+            tooltip="Hiker Position",
+            icon=folium.Icon(color="red", icon="user")
+        ).add_to(m)
+        
     return m._repr_html_()
 
 def get_map_iframe(map_html):
@@ -93,7 +147,6 @@ def fetch_ors_route(start_coords, end_coords, profile, api_key):
     file_path = os.path.join(temp_dir, "ors_fetched_route.gpx")
     
     if not api_key:
-        # Create a mock straight-line GPX (3 coordinates: start, mid, end) for demo purposes
         mid_lat = (start_lat + end_lat) / 2.0
         mid_lon = (start_lon + end_lon) / 2.0
         gpx_content = f"""<?xml version="1.0" encoding="UTF-8"?>
@@ -131,7 +184,6 @@ def fetch_ors_route(start_coords, end_coords, profile, api_key):
         else:
             raise ValueError(f"ORS returned status {response.status_code}")
     except Exception as e:
-        # Fallback straight-line
         mid_lat = (start_lat + end_lat) / 2.0
         mid_lon = (start_lon + end_lon) / 2.0
         gpx_content = f"""<?xml version="1.0" encoding="UTF-8"?>
@@ -149,30 +201,10 @@ def fetch_ors_route(start_coords, end_coords, profile, api_key):
         gr.Warning(f"ORS Fetch failed ({e}). Generated straight-line fallback route.")
         return file_path
 
-def handle_route_update(preloaded_sel, uploaded_file, start_coords, end_coords, profile, api_key, request: gr.Request = None):
-    # Determine which file to parse
-    file_path = PRELOADED_ROUTE_PATH
-    
-    # Check trigger source
-    # We can inspect input priority or simply prioritize upload -> fetch -> preloaded
-    if uploaded_file is not None:
-        file_path = uploaded_file.name
-    elif start_coords and end_coords:
-        # If coordinates are changed and user hits the trigger, we can fetch
-        # However, to avoid automatic fetching on load, we only fetch when this is called via button click.
-        # Since this function handles all triggers, we'll let app buttons set a temporary flag.
-        pass
-
-    try:
-        data = parse_gpx_file(file_path)
-    except Exception as e:
-        return (
-            f"<div style='color:#ef4444; padding:15px; border:1px solid #ef4444; border-radius:8px;'>Error loading GPX: {e}</div>",
-            f"<iframe srcdoc='<h3 style=\"color:red;\">Error rendering map: {e}</h3>' width='100%' height='520px'></iframe>",
-            []
-        )
-        
-    # Generate Stats HUD
+def format_route_view(data):
+    """
+    Format route data for presentation inside stats display and checkpoint lists.
+    """
     stats_html = f"""
     <div style='display: grid; grid-template-columns: repeat(auto-fit, minmax(130px, 1fr)); gap: 15px; margin-bottom: 20px;'>
         <div class='hud-stat-box'>
@@ -198,11 +230,9 @@ def handle_route_update(preloaded_sel, uploaded_file, start_coords, end_coords,
     </div>
     """
     
-    # Generate Folium Map
-    map_html = generate_folium_map(data["points"], data["checkpoints"])
+    map_html = generate_folium_map(data["points"], data["checkpoints"], data.get("pois", []))
     map_iframe = get_map_iframe(map_html)
     
-    # Format Checkpoint List for Dataframe
     checkpoint_table_data = []
     for cp in data["checkpoints"]:
         checkpoint_table_data.append([
@@ -214,33 +244,215 @@ def handle_route_update(preloaded_sel, uploaded_file, start_coords, end_coords,
         
     return stats_html, map_iframe, checkpoint_table_data
 
+def handle_route_update(preloaded_sel, uploaded_file, start_coords, end_coords, profile, api_key):
+    file_path = PRELOADED_ROUTE_PATH
+    if uploaded_file is not None:
+        file_path = uploaded_file.name
+        
+    try:
+        data = parse_gpx_file(file_path)
+    except Exception as e:
+        import traceback
+        traceback.print_exc()
+        return (
+            f"<div style='color:#ef4444;'>Error parsing GPX: {e}</div>",
+            "",
+            [],
+            {},
+            0,
+            gr.update(active=False),
+            "",
+            ""
+        )
+        
+    stats_html, map_iframe, checkpoint_table_data = format_route_view(data)
+    # Save a copy with POIs saved to disk
+    try:
+        enhanced_file = os.path.join("./temp", "trek_with_poi.gpx")
+        save_enhanced_gpx(file_path, enhanced_file, data.get("pois", []))
+    except Exception as ex:
+        print(f"[app] Error saving enhanced GPX: {ex}")
+        
+    return stats_html, map_iframe, checkpoint_table_data, data, 0, gr.update(active=False), "", ""
+
 def handle_ors_fetch_click(start_coords, end_coords, profile, api_key):
-    """Button click handler for fetching online routes."""
     try:
         route_file = fetch_ors_route(start_coords, end_coords, profile, api_key)
-        return handle_route_update(None, None, start_coords, end_coords, profile, api_key)
+        data = parse_gpx_file(route_file)
+        stats_html, map_iframe, checkpoint_table_data = format_route_view(data)
+        
+        try:
+            enhanced_file = os.path.join("./temp", "trek_with_poi.gpx")
+            save_enhanced_gpx(route_file, enhanced_file, data.get("pois", []))
+        except Exception as ex:
+            print(f"[app] Error saving enhanced GPX: {ex}")
+            
+        return stats_html, map_iframe, checkpoint_table_data, data, 0, gr.update(active=False), "", ""
     except Exception as e:
         return (
-            f"<div style='color:#ef4444; padding:15px; border:1px solid #ef4444; border-radius:8px;'>ORS Routing Error: {e}</div>",
-            gr.update(),
-            gr.update()
+            f"<div style='color:#ef4444;'>Error: {e}</div>",
+            "",
+            [],
+            {},
+            0,
+            gr.update(active=False),
+            "",
+            ""
         )
 
-# --- Gradio Chatbot Integration ---
-def respond(message, history):
-    # Enforce streaming for better UX
-    response_accumulator = ""
+# --- Playback Simulation Loop ---
+def step_simulation(current_idx, route_data, speed):
+    if not route_data or "points" not in route_data:
+        return current_idx, gr.update(), gr.update(), gr.update(), gr.update()
+        
+    points = route_data["points"]
+    checkpoints = route_data["checkpoints"]
+    pois = route_data.get("pois", [])
+    
+    if current_idx >= len(points):
+        return current_idx, gr.update(), gr.update(), gr.update(), gr.update()
+        
+    step_size = int(speed)
+    next_idx = current_idx + step_size
+    if next_idx >= len(points):
+        next_idx = len(points) - 1
+        
+    current_pt = points[next_idx]
+    
+    lat = current_pt["lat"]
+    lon = current_pt["lon"]
+    ele = current_pt["ele"]
+    cum_dist = current_pt["cum_dist"]
+    
+    total_dist = points[-1]["cum_dist"]
+    pct_complete = (cum_dist / total_dist) * 100.0 if total_dist > 0 else 0.0
+    
+    # Proximity alerts check
+    active_alerts = []
+    for poi in pois:
+        d = haversine(lat, lon, poi["lat"], poi["lon"])
+        if d <= 150.0:
+            icon_map = {
+                "drinking_water": "💧",
+                "spring": "💧",
+                "water_point": "💧",
+                "alpine_hut": "🏡",
+                "camp_site": "⛺",
+                "shelter": "🛡️"
+            }
+            icon = icon_map.get(poi["type"], "📍")
+            active_alerts.append(f"<div style='background:rgba(245,158,11,0.15); border:1px solid #f59e0b; padding:10px; border-radius:8px; margin-bottom:5px; color:#f59e0b;'>{icon} <b>PROXIMITY:</b> {poi['name']} is {d:.0f}m away! ({poi['type'].replace('_', ' ').title()})</div>")
+            
+    # Checkpoint ETA progress
+    next_cp = None
+    for cp in checkpoints:
+        if cp["cum_dist"] * 1000.0 > cum_dist:
+            next_cp = cp
+            break
+            
+    eta_text = "N/A"
+    if next_cp:
+        dist_to_cp = (next_cp["cum_dist"] * 1000.0) - cum_dist
+        eta_sec = dist_to_cp / 1.38
+        eta_text = f"{int(eta_sec // 60)}m {int(eta_sec % 60)}s"
+        
+    alerts_html = "".join(active_alerts) if active_alerts else "<div style='color:var(--text-muted);'>No active proximity alerts.</div>"
+    
+    # Render updated folium map
+    map_html = generate_folium_map(points, checkpoints, pois, hiker_pos=current_pt)
+    map_iframe = get_map_iframe(map_html)
+    
+    # Live HUD Panel
+    hud_html = f"""
+    <div style='display: grid; grid-template-columns: repeat(auto-fit, minmax(130px, 1fr)); gap: 15px; margin-bottom: 20px;'>
+        <div class='hud-stat-box'>
+            <div class='hud-stat-val mono-display'>{pct_complete:.1f}%</div>
+            <div class='hud-stat-lbl'>Route Progress</div>
+        </div>
+        <div class='hud-stat-box'>
+            <div class='hud-stat-val mono-display'>{cum_dist/1000.0:.2f} km</div>
+            <div class='hud-stat-lbl'>Distance Hiked</div>
+        </div>
+        <div class='hud-stat-box'>
+            <div class='hud-stat-val mono-display'>{ele:.1f} m</div>
+            <div class='hud-stat-lbl'>Current Altitude</div>
+        </div>
+        <div class='hud-stat-box'>
+            <div class='hud-stat-val mono-display'>{eta_text}</div>
+            <div class='hud-stat-lbl'>ETA to Next Point</div>
+        </div>
+    </div>
+    """
+    
+    # Proximity narration brief
+    narration_html = ""
+    for cp in checkpoints:
+        cp_dist_m = cp["cum_dist"] * 1000.0
+        if abs(cum_dist - cp_dist_m) <= 150.0:
+            cautions = ""
+            if ele > 2400:
+                cautions = " WARNING: Altitude is above 2400m. Watch for AMS symptoms (headache, dizziness)."
+            narration_html = f"""
+            <div style='border-left: 4px solid var(--accent-primary); background: rgba(245,158,11,0.05); padding: 15px; border-radius: 0 8px 8px 0;'>
+                <b style='color:var(--accent-primary);'>📻 RADIO BRIEFING FOR {cp['name'].upper()}:</b>
+                <p style='margin-top: 5px; font-style: italic;'>
+                    "Hiker, you have arrived at {cp['name']}. Current altitude is {ele:.1f}m.{cautions}"
+                </p>
+            </div>
+            """
+            break
+            
+    return next_idx, hud_html, map_iframe, alerts_html, narration_html
+
+# --- First-Aid Manual Search ---
+def handle_first_aid_search(query):
+    if not query.strip():
+        return "Please enter symptoms or injury to search the manual."
+        
+    grounding_text, sources = rag.retrieve_first_aid(query)
+    if not grounding_text:
+        return "No matching first-aid sections found in the manual. (Please carry a PLB/satellite communicator on remote trails)."
+        
     system_prompt = (
-        "You are Trailhead Guide, a helpful and knowledgeable wilderness trekking expert.\n"
-        "You help hikers prepare for routes, review gear checklists, and learn wilderness first-aid.\n"
-        "Be professional, concise, and safety-oriented. Emphasize offline preparedness."
+        "You are Trailhead Guide, an expert wilderness medicine counselor.\n"
+        "Provide a concise, direct, and actionable step-by-step first-aid protocol based on the provided guide context.\n"
+        "Cite the section at the end."
     )
+    prompt = f"Context:\n{grounding_text}\n\nQuestion: {query}\n\nAnswer:"
+    response = llm.generate(prompt, system=system_prompt, stream=False)
+    
+    return f"### Retrieval Results ({', '.join(sources)})\n\n{response}"
+
+# --- Chatbot Integration ---
+def respond(message, history):
+    response_accumulator = ""
+    grounding_text, sources = rag.retrieve_first_aid(message)
+    
+    if grounding_text:
+        source_cite = "Sources: " + ", ".join(sources)
+        system_prompt = (
+            "You are Trailhead Guide, a wilderness first-aid advisor.\n"
+            "Answer the query using ONLY the provided guide context.\n"
+            f"Context:\n{grounding_text}\n"
+            "Keep the instructions clear, numbered, and precise.\n"
+            f"Cite: '{source_cite}'."
+        )
+    else:
+        system_prompt = (
+            "You are Trailhead Guide, an expert hiking guide.\n"
+            "Provide helpful, concise trekking advice."
+        )
+        
     for token in llm.generate(message, system=system_prompt, history=history, stream=True):
         response_accumulator += token
         yield response_accumulator
 
 # --- Gradio Blocks UI ---
 with gr.Blocks(css="assets/custom.css", title="Trailhead — Tactical Trail Computer") as demo:
+    # State management
+    route_state = gr.State({})
+    current_point_idx = gr.State(0)
+    
     gr.HTML("""
     <div style='text-align: center; padding: 10px 0;'>
         <h1>🌲 Trailhead 🌲</h1>
@@ -250,6 +462,9 @@ with gr.Blocks(css="assets/custom.css", title="Trailhead — Tactical Trail Comp
     </div>
     """)
     
+    # Timer loop for simulation
+    timer = gr.Timer(value=0.2, active=False)
+    
     with gr.Tabs():
         with gr.TabItem("🧭 Trek Planner & HUD"):
             with gr.Row():
@@ -259,7 +474,7 @@ with gr.Blocks(css="assets/custom.css", title="Trailhead — Tactical Trail Comp
                     preloaded_route = gr.Dropdown(
                         choices=["Preloaded Route: Trento Track"],
                         value="Preloaded Route: Trento Track",
-                        label="Preloaded Routes (Trento, Italy)"
+                        label="Preloaded Routes"
                     )
                     
                     upload_file = gr.File(
@@ -268,7 +483,6 @@ with gr.Blocks(css="assets/custom.css", title="Trailhead — Tactical Trail Comp
                     )
                     
                     with gr.Accordion("🔌 Fetch Online Route (Basecamp Mode)", open=False):
-                        gr.Markdown("Generate route paths between waypoints using OpenRouteService.")
                         start_pt = gr.Textbox(
                             value="46.0734974, 11.1717214",
                             label="Start Coordinates (Lat, Lon)"
@@ -278,17 +492,26 @@ with gr.Blocks(css="assets/custom.css", title="Trailhead — Tactical Trail Comp
                             label="End Coordinates (Lat, Lon)"
                         )
                         ors_profile = gr.Dropdown(
-                            choices=["foot-hiking", "foot-walking", "cycling-mountain"],
+                            choices=["foot-hiking", "foot-walking"],
                             value="foot-hiking",
                             label="Profile"
                         )
                         ors_api_key = gr.Textbox(
                             type="password",
-                            label="OpenRouteService API Key (Optional)",
-                            placeholder="Paste your API key here..."
+                            label="OpenRouteService API Key (Optional)"
                         )
                         fetch_route_btn = gr.Button("Fetch & Load Route", variant="secondary")
                         
+                    gr.Markdown("### 🎮 Trek Simulation Controls")
+                    with gr.Row():
+                        play_btn = gr.Button("▶ PLAY", variant="primary")
+                        pause_btn = gr.Button("⏸ PAUSE", variant="secondary")
+                        reset_btn = gr.Button("🔄 RESET", variant="secondary")
+                    speed_slider = gr.Slider(minimum=1, maximum=20, step=1, value=1, label="Simulation Speed (Points per tick)")
+                    
+                    gr.Markdown("### ⚠️ Active Proximity Alerts")
+                    alerts_output = gr.HTML(value="<div style='color:var(--text-muted);'>No active proximity alerts.</div>")
+                    
                 with gr.Column(scale=2):
                     # Stats display
                     stats_display = gr.HTML()
@@ -296,6 +519,9 @@ with gr.Blocks(css="assets/custom.css", title="Trailhead — Tactical Trail Comp
                     # Interactive Map display
                     map_display = gr.HTML()
                     
+                    # Narration briefing output
+                    narration_output = gr.HTML(value="")
+                    
             with gr.Accordion("📋 Route Checkpoint Briefing", open=True):
                 checkpoint_table = gr.DataFrame(
                     headers=["Checkpoint", "Coordinates", "Cumulative Distance", "Altitude"],
@@ -303,6 +529,16 @@ with gr.Blocks(css="assets/custom.css", title="Trailhead — Tactical Trail Comp
                     column_count=(4, "fixed")
                 )
                 
+        with gr.TabItem("🩺 Wilderness First-Aid"):
+            with gr.Row():
+                with gr.Column(scale=1):
+                    gr.HTML(EMERGENCY_CARD)
+                with gr.Column(scale=1):
+                    gr.Markdown("## 🔍 Wilderness First-Aid manual RAG Search")
+                    rag_query = gr.Textbox(placeholder="What symptoms or injury do you want to query?", label="Query Symptoms")
+                    rag_search_btn = gr.Button("Search manual", variant="primary")
+                    rag_output = gr.Markdown(value="*Manual results will be displayed here.*")
+                    
         with gr.TabItem("💬 Wilderness Guide AI"):
             gr.ChatInterface(
                 respond,
@@ -313,33 +549,73 @@ with gr.Blocks(css="assets/custom.css", title="Trailhead — Tactical Trail Comp
                 ]
             )
 
-    # --- Triggers ---
+    # --- Simulation player bindings ---
+    timer.tick(
+        fn=step_simulation,
+        inputs=[current_point_idx, route_state, speed_slider],
+        outputs=[current_point_idx, stats_display, map_display, alerts_output, narration_output]
+    )
+    
+    play_btn.click(
+        fn=lambda: gr.update(active=True),
+        inputs=[],
+        outputs=[timer]
+    )
+    
+    pause_btn.click(
+        fn=lambda: gr.update(active=False),
+        inputs=[],
+        outputs=[timer]
+    )
+    
+    def handle_reset(route):
+        pts = route.get("points", [])
+        if pts:
+            # Reformat map to reset pose
+            stats_html, map_iframe, checkpoint_table_data = format_route_view(route)
+            return 0, gr.update(active=False), map_iframe, stats_html, "", ""
+        return 0, gr.update(active=False), gr.update(), gr.update(), "", ""
+        
+    reset_btn.click(
+        fn=handle_reset,
+        inputs=[route_state],
+        outputs=[current_point_idx, timer, map_display, stats_display, alerts_output, narration_output]
+    )
+
+    # --- Route Ingestion Triggers ---
     # Load default route on startup
     demo.load(
         fn=handle_route_update,
         inputs=[preloaded_route, upload_file, gr.State(""), gr.State(""), gr.State(""), gr.State("")],
-        outputs=[stats_display, map_display, checkpoint_table]
+        outputs=[stats_display, map_display, checkpoint_table, route_state, current_point_idx, timer, alerts_output, narration_output]
     )
     
     # Preloaded selection change
     preloaded_route.change(
         fn=handle_route_update,
         inputs=[preloaded_route, gr.State(None), gr.State(""), gr.State(""), gr.State(""), gr.State("")],
-        outputs=[stats_display, map_display, checkpoint_table]
+        outputs=[stats_display, map_display, checkpoint_table, route_state, current_point_idx, timer, alerts_output, narration_output]
     )
     
     # Uploaded file change
     upload_file.change(
         fn=handle_route_update,
         inputs=[gr.State(None), upload_file, gr.State(""), gr.State(""), gr.State(""), gr.State("")],
-        outputs=[stats_display, map_display, checkpoint_table]
+        outputs=[stats_display, map_display, checkpoint_table, route_state, current_point_idx, timer, alerts_output, narration_output]
     )
     
     # Fetch route button click
     fetch_route_btn.click(
         fn=handle_ors_fetch_click,
         inputs=[start_pt, end_pt, ors_profile, ors_api_key],
-        outputs=[stats_display, map_display, checkpoint_table]
+        outputs=[stats_display, map_display, checkpoint_table, route_state, current_point_idx, timer, alerts_output, narration_output]
+    )
+    
+    # --- RAG Trigger ---
+    rag_search_btn.click(
+        fn=handle_first_aid_search,
+        inputs=[rag_query],
+        outputs=[rag_output]
     )
 
 if __name__ == "__main__":

src/data/first_aid_guide.json

@@ -0,0 +1,22 @@
+[
+  {
+    "section": "Section 1: Bleeding and Wound Management",
+    "text": "Control severe bleeding by applying direct pressure to the wound with a clean cloth or bandage. Keep the limb elevated. If bleeding does not stop after 10-15 minutes of continuous direct pressure, apply a tourniquet high and tight on the limb. Keep the wound clean using treated water. Cover with sterile dressings. Avoid direct contact with bodily fluids."
+  },
+  {
+    "section": "Section 2: Hypothermia and Frostbite",
+    "text": "Hypothermia occurs when the core body temperature drops below 35°C (95°F). Symptoms include shivering, confusion, and slurred speech. Treatment: Move the victim out of the wind/wet, replace wet clothing with dry layers, wrap in a space blanket or sleeping bag, and provide warm sweetened drinks if conscious. Frostbite: Do not rub the affected skin. Rewarm slowly in warm water (38-42°C)."
+  },
+  {
+    "section": "Section 3: Heat Exhaustion and Dehydration",
+    "text": "Heat exhaustion presents with heavy sweating, rapid pulse, dizziness, nausea, and headache. Dehydration worsens these symptoms. Treatment: Move the hiker to shade immediately, cool them down with wet cloths, and sip cool water with electrolytes. Do not allow rapid drinking. If they become confused or lose consciousness, it is Heat Stroke—a life-threatening emergency requiring rapid active cooling."
+  },
+  {
+    "section": "Section 4: Altitude Illnesses (AMS, HAPE, HACE)",
+    "text": "Acute Mountain Sickness (AMS) occurs above 2400 meters (8000 feet). Symptoms include headache, nausea, fatigue, and dizziness. Treatment: Stop ascending, rest, and hydrate. If symptoms do not improve within 24 hours, descend immediately. High Altitude Pulmonary Edema (HAPE) presents with breathlessness at rest and a cough. High Altitude Cerebral Edema (HACE) presents with confusion and loss of coordination (ataxia). Both HAPE and HACE are emergency conditions requiring immediate descent."
+  },
+  {
+    "section": "Section 5: Musculoskeletal Injuries (Sprains, Fractures)",
+    "text": "For ankle sprains or joint strains, follow the R.I.C.E. protocol: Rest the joint, Ice or apply cold pack (submerge in cold stream), Compress with elastic bandage, and Elevate the limb. For suspected fractures, immobilize the limb using splints (made of sticks, sleeping pads, or trekking poles) in the position found. Do not try to realign bones."
+  }
+]

src/gpx_parser.py

@@ -82,7 +82,190 @@ def calculate_elevation_gain_loss(elevations, threshold=2.0):
             last_val = val
     return gain, loss
 
-def parse_gpx_file(file_path, cache_dir="./temp"):
+def fetch_overpass_pois(min_lat, min_lon, max_lat, max_lon):
+    """
+    Fetch POIs (water, spring, huts, camps, shelter) from Overpass API in the bounding box.
+    """
+    url = "https://overpass-api.de/api/interpreter"
+    query = f"""
+    [out:json][timeout:20];
+    (
+      node["amenity"="drinking_water"]({min_lat:.5f},{min_lon:.5f},{max_lat:.5f},{max_lon:.5f});
+      node["natural"="spring"]({min_lat:.5f},{min_lon:.5f},{max_lat:.5f},{max_lon:.5f});
+      node["amenity"="water_point"]({min_lat:.5f},{min_lon:.5f},{max_lat:.5f},{max_lon:.5f});
+      node["tourism"="alpine_hut"]({min_lat:.5f},{min_lon:.5f},{max_lat:.5f},{max_lon:.5f});
+      node["tourism"="camp_site"]({min_lat:.5f},{min_lon:.5f},{max_lat:.5f},{max_lon:.5f});
+      node["amenity"="shelter"]({min_lat:.5f},{min_lon:.5f},{max_lat:.5f},{max_lon:.5f});
+    );
+    out body;
+    """
+    headers = {
+        'User-Agent': 'TrailheadTrekPlanner/1.0 (skushwaha@hckthn.com)'
+    }
+    try:
+        print(f"[gpx_parser] Querying Overpass API for POIs in bbox: [{min_lat:.5f}, {min_lon:.5f}, {max_lat:.5f}, {max_lon:.5f}]...")
+        response = requests.post(url, data={'data': query}, headers=headers, timeout=15)
+        if response.status_code == 200:
+            data = response.json()
+            elements = data.get("elements", [])
+            pois = []
+            for el in elements:
+                lat = el.get("lat")
+                lon = el.get("lon")
+                tags = el.get("tags", {})
+                
+                # Determine type
+                poi_type = "unknown"
+                if "amenity" in tags:
+                    poi_type = tags["amenity"]
+                elif "natural" in tags:
+                    poi_type = tags["natural"]
+                elif "tourism" in tags:
+                    poi_type = tags["tourism"]
+                    
+                name = tags.get("name", tags.get("water", poi_type.replace("_", " ").title()))
+                pois.append({
+                    "id": el.get("id"),
+                    "lat": lat,
+                    "lon": lon,
+                    "type": poi_type,
+                    "name": name
+                })
+            print(f"[gpx_parser] Overpass returned {len(pois)} raw POIs.")
+            return pois
+        else:
+            print(f"[gpx_parser] Overpass API returned status code {response.status_code}: {response.text}")
+            return []
+    except Exception as e:
+        print(f"[gpx_parser] Overpass query failed: {e}")
+        return []
+
+def filter_pois_near_track(points, pois, buffer_meters=150.0):
+    """
+    Filter POIs that are within buffer_meters of the track.
+    Returns list of POIs with distance and closest track point index.
+    """
+    enhanced_pois = []
+    if not points or not pois:
+        return enhanced_pois
+        
+    for poi in pois:
+        min_dist = float('inf')
+        closest_idx = -1
+        
+        for idx, pt in enumerate(points):
+            d = haversine(poi["lat"], poi["lon"], pt["lat"], pt["lon"])
+            if d < min_dist:
+                min_dist = d
+                closest_idx = idx
+                
+        if min_dist <= buffer_meters:
+            enhanced_pois.append({
+                "id": poi.get("id", 0),
+                "lat": poi["lat"],
+                "lon": poi["lon"],
+                "type": poi["type"],
+                "name": poi["name"],
+                "distance": round(min_dist, 1),
+                "track_index": closest_idx
+            })
+            
+    print(f"[gpx_parser] Filtered {len(enhanced_pois)} POIs within {buffer_meters}m buffer.")
+    return enhanced_pois
+
+def extract_pois_from_gpx(gpx):
+    """
+    Extract POIs from GPX waypoints and track point extensions.
+    Returns a list of POI dictionaries.
+    """
+    pois = []
+    # 1. Parse from waypoints
+    for wpt in gpx.waypoints:
+        desc = wpt.description or ""
+        poi_type = "unknown"
+        if "Type: " in desc:
+            parts = desc.split(",")
+            poi_type = parts[0].replace("Type: ", "").strip()
+        elif wpt.name:
+            # guess type from name/attributes
+            name_l = wpt.name.lower()
+            if "water" in name_l or "spring" in name_l or "fountain" in name_l:
+                poi_type = "drinking_water"
+            elif "camp" in name_l:
+                poi_type = "camp_site"
+            elif "hut" in name_l or "refuge" in name_l:
+                poi_type = "alpine_hut"
+            elif "shelter" in name_l:
+                poi_type = "shelter"
+                
+        pois.append({
+            "lat": wpt.latitude,
+            "lon": wpt.longitude,
+            "name": wpt.name or "Waypoint",
+            "type": poi_type,
+            "distance": 0.0
+        })
+        
+    # 2. Parse from track point extensions
+    idx = 0
+    for track in gpx.tracks:
+        for segment in track.segments:
+            for pt in segment.points:
+                if pt.extensions:
+                    for ext in pt.extensions:
+                        tag_name = ext.tag if hasattr(ext, 'tag') else ''
+                        if 'poi' in tag_name:
+                            poi_type = ext.attrib.get('type', 'unknown')
+                            poi_name = ext.attrib.get('name', 'Waypoint')
+                            try:
+                                dist = float(ext.attrib.get('distance', 0.0))
+                            except ValueError:
+                                dist = 0.0
+                            pois.append({
+                                "lat": pt.latitude,
+                                "lon": pt.longitude,
+                                "name": poi_name,
+                                "type": poi_type,
+                                "distance": dist,
+                                "track_index": idx
+                            })
+                idx += 1
+    return pois
+
+def save_enhanced_gpx(original_gpx_path, output_gpx_path, pois):
+    """
+    Save enhanced GPX file with POIs loaded as waypoints and extensions.
+    """
+    with open(original_gpx_path, "r", encoding="utf-8") as f:
+        gpx = gpxpy.parse(f)
+        
+    # Overwrite waypoints
+    gpx.waypoints = []
+    for poi in pois:
+        wpt = gpxpy.gpx.GPXWaypoint(latitude=poi['lat'], longitude=poi['lon'], name=poi['name'])
+        wpt.description = f"Type: {poi['type']}, Distance from track: {poi['distance']:.1f}m"
+        gpx.waypoints.append(wpt)
+        
+    # Add extensions to trackpoints
+    points = []
+    for track in gpx.tracks:
+        for segment in track.segments:
+            points.extend(segment.points)
+            
+    import xml.etree.ElementTree as ET
+    for poi in pois:
+        idx = poi.get('track_index')
+        if idx is not None and 0 <= idx < len(points):
+            pt = points[idx]
+            # Create sub-element under extensions
+            poi_el = ET.Element('poi', type=poi['type'], name=poi['name'], distance=f"{poi['distance']:.1f}")
+            pt.extensions.append(poi_el)
+            
+    with open(output_gpx_path, "w", encoding="utf-8") as f:
+        f.write(gpx.to_xml())
+    print(f"[gpx_parser] Saved enhanced GPX with {len(pois)} POIs to {output_gpx_path}")
+
+def parse_gpx_file(file_path, cache_dir="./temp", buffer_meters=150.0):
     """
     Parse a GPX file, fetch missing elevations, smooth the profile,
     and compute trek statistics. Caches results locally to allow offline usage.
@@ -192,9 +375,7 @@ def parse_gpx_file(file_path, cache_dir="./temp"):
     max_ele = max(smoothed_eles) if smoothed_eles else 0.0
     
     # Naismith's Rule: 5 km/h base speed + 1 hour per 600m ascent
-    # estimated_hours = (dist_km / 5.0) + (gain_m / 600.0)
     naismith_hours = (total_distance_km / 5.0) + (gain / 600.0)
-    # Estimate days assuming 8 hours hiking per day
     estimated_days = max(1.0, naismith_hours / 8.0)
     
     # Pre-parse waypoints if they exist in GPX
@@ -211,9 +392,7 @@ def parse_gpx_file(file_path, cache_dir="./temp"):
     # Generate checkpoints
     checkpoints = []
     if waypoints:
-        # Match waypoints to track points to find cumulative distance
         for wpt in waypoints:
-            # Find closest track point
             min_d = float('inf')
             closest_pt = points_data[0]
             for pt in points_data:
@@ -228,12 +407,23 @@ def parse_gpx_file(file_path, cache_dir="./temp"):
                 "ele": closest_pt["ele"],
                 "cum_dist": closest_pt["cum_dist"] / 1000.0
             })
-        # Sort by distance
         checkpoints.sort(key=lambda c: c["cum_dist"])
     else:
-        # Auto-generate checkpoints every 1000 meters
         checkpoints = generate_checkpoints(points_data, interval_meters=1000.0)
         
+    # Parse existing POIs from GPX
+    pois = extract_pois_from_gpx(gpx)
+    
+    # If no POIs exist (like raw user upload), fetch from Overpass API (planning mode online)
+    if not pois:
+        lats = [pt["lat"] for pt in points_data]
+        lons = [pt["lon"] for pt in points_data]
+        min_lat, max_lat = min(lats) - 0.002, max(lats) + 0.002
+        min_lon, max_lon = min(lons) - 0.002, max(lons) + 0.002
+        
+        raw_pois = fetch_overpass_pois(min_lat, min_lon, max_lat, max_lon)
+        pois = filter_pois_near_track(points_data, raw_pois, buffer_meters)
+        
     result = {
         "file_name": file_name,
         "total_distance_km": round(total_distance_km, 2),
@@ -244,7 +434,8 @@ def parse_gpx_file(file_path, cache_dir="./temp"):
         "estimated_days": round(estimated_days, 1),
         "naismith_hours": round(naismith_hours, 1),
         "points": points_data,
-        "checkpoints": checkpoints
+        "checkpoints": checkpoints,
+        "pois": pois
     }
     
     # Save cache

src/rag.py

@@ -0,0 +1,81 @@
+import os
+import json
+import re
+
+DATA_DIR = os.path.join(os.path.dirname(os.path.abspath(__file__)), "data")
+GUIDES_FILE = os.path.join(DATA_DIR, "first_aid_guide.json")
+
+def retrieve_first_aid(query_text):
+    """
+    Search first_aid_guide.json for sections relevant to the query.
+    Returns (markdown_grounding_text, source_list) or (None, [])
+    """
+    if not os.path.exists(GUIDES_FILE):
+        print(f"[rag.py] Guide file not found at {GUIDES_FILE}")
+        return None, []
+
+    try:
+        with open(GUIDES_FILE, "r", encoding="utf-8") as f:
+            guides = json.load(f)
+    except Exception as e:
+        print(f"[rag.py] Error reading guides: {e}")
+        return None, []
+
+    query_text_lower = query_text.lower()
+    query_words = set(re.findall(r"\w+", query_text_lower))
+    
+    matches = []
+    
+    # Pre-defined keyword map for high relevance scores
+    keywords_map = {
+        "section 1": ["bleed", "wound", "cut", "blood", "bandage", "tourniquet", "injury"],
+        "section 2": ["cold", "hypothermia", "freeze", "frostbite", "shiver", "rewarm"],
+        "section 3": ["heat", "exhaustion", "dehydration", "stroke", "hot", "sunstroke", "sweat"],
+        "section 4": ["altitude", "ams", "hape", "hace", "headache", "dizzy", "mountain sickness", "nausea", "pulmonary", "cerebral"],
+        "section 5": ["sprain", "fracture", "break", "splint", "ankle", "joint", "bone", "rice", "strain"]
+    }
+    
+    for guide in guides:
+        score = 0
+        section = guide.get("section", "")
+        text = guide.get("text", "")
+        section_lower = section.lower()
+        
+        # 1. Map based matching
+        for key, words in keywords_map.items():
+            if key in section_lower:
+                for w in words:
+                    if w in query_text_lower:
+                        score += 3
+                        
+        # 2. General overlap matching
+        combined_text = (section + " " + text).lower()
+        for word in query_words:
+            if len(word) > 2 and word in combined_text:
+                score += 1
+                
+        if score > 0:
+            matches.append((score, guide))
+            
+    # Sort matches by score descending
+    matches.sort(key=lambda x: x[0], reverse=True)
+    
+    if not matches:
+        return None, []
+        
+    grounding_parts = []
+    sources = []
+    
+    # Take top matching guide to ground the model response
+    for idx, (score, guide) in enumerate(matches[:1]):
+        sec = guide["section"]
+        txt = guide["text"]
+        
+        grounding_parts.append(
+            f"### {sec}\n"
+            f"{txt}\n"
+        )
+        sources.append(sec)
+        
+    grounding_text = "\n---\n".join(grounding_parts)
+    return grounding_text, sources

test_overpass.py

@@ -0,0 +1,48 @@
+import os
+import sys
+from src.gpx_parser import parse_gpx_file, fetch_overpass_pois, filter_pois_near_track
+
+def run_test():
+    gpx_path = r"C:\Users\skushwaha\Documents\hckthn\TrailHead\Routes\track_5-14724236830.gpx"
+    print(f"--- Testing GPX parsing and Overpass integration on: {gpx_path} ---")
+    
+    if not os.path.exists(gpx_path):
+        print(f"Error: GPX file not found at {gpx_path}")
+        sys.exit(1)
+        
+    # 1. Parse GPX file and see what's loaded
+    print("\n1. Running parse_gpx_file...")
+    result = parse_gpx_file(gpx_path)
+    
+    print(f"File Name: {result['file_name']}")
+    print(f"Total Distance: {result['total_distance_km']} km")
+    print(f"Elevation Gain: {result['elevation_gain_m']} m")
+    print(f"Elevation Loss: {result['elevation_loss_m']} m")
+    print(f"Min/Max Elevation: {result['min_elevation_m']}m / {result['max_elevation_m']}m")
+    print(f"Number of points: {len(result['points'])}")
+    print(f"Number of checkpoints: {len(result['checkpoints'])}")
+    
+    pois = result.get("pois", [])
+    print(f"Number of POIs parsed/fetched: {len(pois)}")
+    for i, poi in enumerate(pois[:10]):
+        print(f"  [{i+1}] Name: {poi['name']}, Type: {poi['type']}, Distance from route: {poi.get('distance', 0.0)}m, Lat/Lon: {poi['lat']}, {poi['lon']}")
+        
+    # 2. Test live Overpass API query directly using the bounding box of the track
+    print("\n2. Direct Test of Overpass API Query...")
+    points_data = result["points"]
+    lats = [pt["lat"] for pt in points_data]
+    lons = [pt["lon"] for pt in points_data]
+    min_lat, max_lat = min(lats) - 0.002, max(lats) + 0.002
+    min_lon, max_lon = min(lons) - 0.002, max(lons) + 0.002
+    
+    print(f"Bounding box: [{min_lat:.5f}, {min_lon:.5f}, {max_lat:.5f}, {max_lon:.5f}]")
+    raw_pois = fetch_overpass_pois(min_lat, min_lon, max_lat, max_lon)
+    print(f"Overpass returned {len(raw_pois)} raw POIs.")
+    
+    filtered_pois = filter_pois_near_track(points_data, raw_pois, buffer_meters=150.0)
+    print(f"Filtered {len(filtered_pois)} POIs within 150m buffer.")
+    for i, poi in enumerate(filtered_pois[:10]):
+         print(f"  [{i+1}] Name: {poi['name']}, Type: {poi['type']}, Buffer Dist: {poi['distance']}m")
+
+if __name__ == "__main__":
+    run_test()