Initial commit: Set up Trailhead structure, Docker, README, and .gitignore

.gitignore

@@ -0,0 +1,158 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+#  Usually these files are written by a python script, from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.log
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or app, you might want to share your .python-version.
+#   See https://github.com/pyenv/pyenv/blob/master/COMMANDS.md#pyenv-version-file
+#.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if delegates have different platforms or python versions,
+#   Pipfile.lock might be conflictual.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+
+# virtualenv
+.venv/
+venv/
+ENV/
+env/
+/bin/
+/include/
+/lib/
+/share/
+
+# pipenv
+#   Alternative places for virtualenv
+.venv
+venv
+ENV
+env
+
+# Spyder project settings
+.spyderproject
+.spyder-py3
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site/
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# Model files
+model/
+*.gguf
+
+# Trailhead specific cache & temp files
+temp/
+*.cache.json
+*.wav
+*.mp3
+
+# Operating System Files
+Thumbs.db
+desktop.ini
+.DS_Store

Dockerfile

@@ -0,0 +1,36 @@
+# Use a slim Python image
+FROM python:3.11-slim
+
+# Set environment variables
+ENV PYTHONUNBUFFERED=1 \
+    PORT=7860 \
+    BACKEND=llama_cpp \
+    MODEL_DIR=/code/model
+
+# Set working directory
+WORKDIR /code
+
+# Install basic runtime dependencies (git is useful for huggingface_hub downloads)
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    git \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install llama-cpp-python using the pre-compiled CPU wheels index
+RUN pip install --no-cache-dir llama-cpp-python --extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cpu
+
+# Copy requirements and install remaining python packages
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Pre-download the Gemma 4 E2B model GGUF so the container boots instantly
+RUN mkdir -p /code/model && \
+    python -c "from huggingface_hub import hf_hub_download; hf_hub_download(repo_id='bartowski/google_gemma-4-E2B-it-GGUF', filename='google_gemma-4-E2B-it-Q4_K_M.gguf', local_dir='/code/model')"
+
+# Copy the application source code
+COPY . .
+
+# Expose Gradio's port
+EXPOSE 7860
+
+# Launch the Gradio app
+CMD ["python", "app.py"]

README.md

@@ -0,0 +1,130 @@
+# 🌲 Trailhead — Tactical Trail Computer & Route Planner
+
+[![Hugging Face Space](https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-Space-blue)](https://huggingface.co/spaces)
+[![Docker](https://img.shields.io/badge/Docker-Enabled-blue.svg)](./Dockerfile)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+> **"Plan online at basecamp, trek offline on the trail."**
+
+**Trailhead** is an offline-first, mobile-friendly trail computer and navigation assistant designed for wilderness hiking and backpacking. It parses GPX files, calculates smoothed elevation profiles, generates interactive offline maps, and leverages an in-process Large Language Model (LLM) and Speech-to-Text (ASR) to guide you safely through the backcountry without relying on cellular connection.
+
+---
+
+## 🧭 System Architecture
+
+```mermaid
+graph TD
+    A[Basecamp: Signal / Wifi] -->|Download Map Tiles & Route| B(GPX Upload / ORS Fetch)
+    B --> C{Trailhead App}
+    C --> D[Deterministic Engine]
+    C --> E[AI Navigation Layer]
+    C --> F[Offline Journaling]
+    
+    D -->|Naismith's Rule & Smoothing| G[Distance / Pace / smoothed Elevation / ETA]
+    E -->|Gemma-4 GGUF via llama.cpp| H[Contextual Checkpoint Briefing & RAG First-Aid]
+    F -->|whisper.cpp ASR| I[SQLite Database + Post-Trek Shareable Reports]
+    
+    G --> J[Tactical HUD UI]
+    H --> J
+    I --> J
+```
+
+---
+
+## ✨ Key Features
+
+### 1. Ingest & Planning (Basecamp Mode)
+* **GPX Upload:** Directly upload any standard GPX route containing track points or waypoints.
+* **OpenRouteService (ORS) Routing:** Generate custom route segments between coordinates using the OSM-based ORS API (requires API key, planning phase only).
+
+### 2. Tactical HUD & Route Metrics
+* **Elevation Profile Smoothing:** Applies a moving-average window and noise threshold to eliminate GPX vertical jitter and provide realistic elevation gain/loss sums.
+* **Naismith's Rule Estimator:** Calculates estimated trekking time assuming a 5 km/h base speed plus 1 hour per 600m of ascent, helping you plan realistic daily splits.
+* **Interactive Map:** Built using `folium`, mapping out the route, checkpoints, and waypoints securely inside a sandboxed iframe.
+
+### 3. Contextual Wilderness Guide AI
+* **In-Process LLM:** Powered by `google_gemma-4-E2B-it-GGUF` running locally on your device or server CPU via `llama-cpp-python`.
+* **Proximity Checkpoint Narration:** Provides real-time terrain updates, safety advice, and target destination briefings as you approach waypoints.
+* **First-Aid RAG Field Guide:** Retreives localized wilderness first-aid procedures and references corresponding guide sections under extreme constraints.
+* **Rule-Based Risk Advisory:** Analyzes remaining daylight, current altitude (AMS detection), and weather to prompt warnings (e.g. recommending alternative campsites if pace degrades).
+
+### 4. Offline Voice Journal & Post-Trek Reports
+* **ASR Voice Logs:** Dictate logs hands-free in the cold using `pywhispercpp` (whisper.cpp tiny). Logs transcribing audio, time, and coordinates are saved directly to SQLite.
+* **Post-Trek Storyteller:** Converts your journal entries and raw GPS points into an AI-narrated story artifact.
+
+---
+
+## 🚀 Quick Start
+
+### Prerequisites
+Make sure you have Python 3.11+ installed.
+
+### Installation
+
+1. **Clone the repository:**
+   ```bash
+   git clone <your-github-repo-url>
+   cd TrailHead
+   ```
+
+2. **Create and activate a virtual environment:**
+   ```bash
+   python -m venv .venv
+   # Windows:
+   .venv\Scripts\activate
+   # macOS/Linux:
+   source .venv/bin/activate
+   ```
+
+3. **Install dependencies:**
+   For local LLM inference on CPU, install `llama-cpp-python` first (using precompiled wheels is recommended for Windows):
+   ```bash
+   pip install llama-cpp-python --extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cpu
+   pip install -r requirements.txt
+   ```
+
+4. **Run the Application:**
+   ```bash
+   python app.py
+   ```
+   Open `http://localhost:7860` in your web browser.
+
+---
+
+## 🐳 Docker Setup & Hugging Face Spaces
+
+This project is fully ready to be deployed as a Docker container or hosted directly as a Hugging Face Space.
+
+### Run locally with Docker
+Build and run the Docker container:
+```bash
+docker build -t trailhead-computer .
+docker run -p 7860:7860 trailhead-computer
+```
+
+### Deploy to Hugging Face Spaces
+1. Create a new Space on [Hugging Face](https://huggingface.co/new-space) using the **Docker** SDK.
+2. Select the **Blank** template or copy the `Dockerfile` directly.
+3. Push the codebase to your Hugging Face Space repository.
+4. The container automatically downloads the `google_gemma-4-E2B-it-Q4_K_M.gguf` model during build time, ensuring the Space starts up instantly without any downloading delays on first launch.
+
+---
+
+## 🛠️ Technical Details & Algorithms
+
+### Elevation Smoothing Filter
+Raw GPX files suffer from GPS vertical drift, leading to massive over-reporting of elevation gain. Trailhead resolves this by:
+1. Batch-querying missing elevations via the **Open-Meteo API** (when GPX coordinates lack altitude).
+2. Applying a **Moving Average window (size 5)** to smooth out high-frequency noise.
+3. Using a **threshold delta (default 2.0 meters)**, only summing elevation changes that exceed the threshold:
+   $$\Delta E = \sum |e_i - e_{i-1}| \quad \text{for} \quad |e_i - e_{i-1}| \ge 2.0\text{m}$$
+
+### Time Estimation (Naismith's Rule)
+We estimate trail times dynamically using the classic Naismith's formula:
+$$\text{Time (hours)} = \frac{\text{Distance (km)}}{5.0} + \frac{\text{Elevation Gain (m)}}{600.0}$$
+This represents a conservative baseline for an average loaded hiker on established trails.
+
+---
+
+## 📄 License
+This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.

Resources/roadmap.md

@@ -0,0 +1,109 @@
+# Trailhead — Three-Phase Roadmap (v3)
+**Track: Backyard AI · Owner: Person D · ~5 days to June 15**
+
+**Affirmed core assumption:** *plan online at basecamp, trek offline.* Online work (route fetch, tile download) is allowed during planning; everything during the trek degrades gracefully to offline.
+
+**Keystone — the Position Abstraction.** All contextual features read position from one interface with two sources:
+- **Simulated playback** — steps along the uploaded GPX. Always works; demo with this; doubles as a "preview your trek" feature.
+- **Live `watchPosition`** (optional, on-device, screen-on only).
+
+Continuous browser GPS on a multi-day offline trek is unreliable (assisted-GPS cold start wants network; backgrounded tabs suspend). Demo on simulation; offer live as a bonus; never promise live tracking as a guarantee.
+
+---
+
+## Online data sources — PLANNING PHASE ONLY
+External calls happen at basecamp with signal, never on the trail.
+
+- **Primary input: upload your own GPX** — it's the hiker's real route; most reliable.
+- **OpenRouteService (ORS)** — free OSM-based routing, `foot-hiking` profile, direct GPX out: `GET https://api.openrouteservice.org/v2/directions/{profile}/gpx`. **Caveats:** needs an API key + has rate limits (online-only); it *routes between coordinates*, it does **not** look up a named trek's established trail; OSM trail coverage in remote/high terrain is patchy. Use it to *generate* a route from waypoints, then validate it. Not authoritative for serious treks.
+- **GPX repositories** (e.g. the track sites you've identified) — fine as a source of pre-made GPX to download at basecamp; then proceed exactly as the upload path.
+
+> Design rule: any online fetch produces a local GPX that the rest of the app treats identically to an uploaded one. Nothing downstream depends on connectivity.
+
+---
+
+## Reconsiderations — verdicts
+
+| Proposed feature | Verdict | Why |
+|---|---|---|
+| GPX upload | **Keep (primary)** | The real route; most reliable. |
+| Online route fetch (ORS / GPX repos) | **Keep — planning phase only** | Convenience at basecamp. Routing ≠ named-trek lookup; validate output; never called offline. |
+| Proximity checkpoint narration | **Keep — headline AI moment** | Driven by the position abstraction. |
+| Progress: % complete / ETA / pace | **Keep** | Deterministic. |
+| Deviation (off-route) alert | **Keep, advisory** | Distance-to-polyline. |
+| Pace-adjusted ETA | **Keep** | Deterministic; recompute from actual elapsed vs distance. |
+| Risk note (pace + daylight + altitude) | **Adapt + constrain** | Rule-based, conservative, **advisory only**. LLM phrases it; rules decide. |
+| Voice via whisper.cpp | **Keep (bonus)** | Reuse Kisan-Sathi; value with gloves/cold. |
+| Voice trek journaling → SQLite (w/ location) | **Keep (should-have)** | Speak → transcribe → log transcript + position + time. Offline. Feeds the post-trek report. **Raw transcript is the record of truth.** |
+| Audio landmark alerts (TTS) | **Optional, low priority** | Fine if position + TTS work. |
+| Post-trek report (stats + AI story) | **Promote (should-have)** | Safe, delightful, shareable; ideal honest-fit LLM use. |
+| Offline map tiles (MBTiles) | **Keep (should-have)** | Map works with no signal; strengthens Off the Grid. |
+| Storage (SQLite/files on disk) | **Backend owns it** | Model + persistence on disk; browser only does UI + geolocation. No weights in IndexedDB. |
+| Battery-aware low-power mode | **Keep** | Lower `n_ctx` + GPS poll interval. Good Field Notes detail. |
+
+---
+
+## PHASE 1 — MVP: "The Route Brief"
+**Goal: the grounded planning loop works end-to-end on the hiker's real GPX. Understandable in 10 seconds.**
+
+- [ ] **GPX ingest:** accept an uploaded GPX *or* a basecamp ORS/repo fetch that lands as a local GPX; from here everything is offline-identical.
+- [ ] **GPX parse** (`gpxpy`): tracks/segments/waypoints; concatenate segments; handle missing elevation/timestamps without crashing.
+- [ ] **Route stats (deterministic):** haversine distance; **elevation gain with smoothing** (moving average / min-change threshold — raw sums are badly inflated); min/max; estimated days (Naismith ÷ realistic hours/day, assumption shown).
+- [ ] **Interactive map — use `folium`, not Plotly mapbox.** Render polyline + waypoint markers; embed as HTML; verify on a phone. **Avoid Plotly's `open-street-map` style — it pulls tiles online and goes blank in airplane mode.** (Reserve Plotly for the elevation chart in Phase 3, where there are no tiles.)
+- [ ] **Static checkpoint readout:** first waypoint — cumulative distance + elevation. No AI yet; prove the data pipeline.
+- [ ] **Deploy to HF Space** (Docker + llama-cpp-python GGUF, reuse Kisan-Sathi Dockerfile); open on a phone.
+
+**Gate:** the hiker's actual GPX yields correct distance, sane (smoothed) elevation gain, estimated days, and a map. Test on the real file — synthetic GPX hides the edge cases.
+
+---
+
+## PHASE 2 — Functional: All Basic Hackathon Criteria Met
+**Goal: full demo-able loop incl. the contextual AI layer; real hiker has used it; all hard constraints met. The 60-second video is recordable from here.**
+
+- [ ] **Position abstraction:** simulated GPX playback ("play" advances along the route) + optional live `watchPosition`. Everything below consumes it.
+- [ ] **Proximity checkpoint narration (load-bearing moment):** as position nears a waypoint, the LLM narrates grounded advice — distance/ascent to next point, altitude caution from the loaded guide, water/hazard **only from tagged waypoints/data** (never invented).
+- [ ] **Progress + pace + ETA + deviation:** % complete, pace vs Naismith, ETA to next checkpoint, off-route alert. Deterministic.
+- [ ] **Advisory risk note:** rule-based — daylight remaining vs distance/ascent to next safe camp → "you'll arrive ~late, consider the alternate camp." Conservative, advisory, not a guarantee. LLM phrases; rules decide.
+- [ ] **Gear list:** rule engine (distance + elevation + days + max altitude + season) → LLM narrates.
+- [ ] **First-aid RAG:** MiniLM over the wilderness first-aid guide; retrieve + **cite section**; static no-signal emergency card; "this is a field guide — carry a PLB/satellite messenger."
+- [ ] **Mobile-first UI** (reuse your FastAPI custom frontend): large targets, outdoor-readable, high contrast.
+- [ ] **Dual deploy + offline verify:** Pixel 10 via Termux; **airplane mode, full loop works.**
+- [ ] **Real hiker uses it + record footage** reviewing their actual route.
+- [ ] **README + social post:** track, real hiker + trek, model + param count, honest-fit rationale, run instructions, teammates' HF usernames.
+
+**Gate:** record the full 60s demo from this phase — ingest GPX → map + stats → press play → proximity narration + pace/ETA fire → gear list → first-aid query — **offline**. Constraints: Gradio ✓ · HF Space ✓ · ≤32B ✓ · video + social ✓ · real user ✓.
+
+---
+
+## PHASE 3 — Final Touch & Bonus Quests
+**Goal: polish + badges. None of this blocks the video.**
+
+- [ ] **🎨 Off-Brand — trail-computer HUD:** amber/green tactical theme; **elevation profile chart** under the map (Plotly is great here — no tiles, deterministic, looks great on camera).
+- [ ] **🦙 Llama Champion:** document GGUF + llama.cpp; battery-saver mode (lower `n_ctx`, slower GPS poll).
+- [ ] **🔌 Off the Grid:** make the airplane-mode run the hero shot; add **offline map tiles (MBTiles)** so the folium map works with no signal.
+- [ ] **🎙 Voice trek journaling:** speak → whisper.cpp → log transcript + position + timestamp to SQLite. Offline. Raw transcript is the record of truth.
+- [ ] **📓 Post-trek report (should-have):** route + stats + an AI-narrated story built from the journal logs — a shareable artifact that feeds your social post. LLM summarizes/tags; never rewrites the logged facts.
+- [ ] **📓 Field Notes:** the build story — elevation smoothing, simulation vs real GPS, offline tiles, offline edge LLM on a phone (Kisan-Sathi Termux notes carry over).
+- [ ] **Local waypoint tagging (bonus):** hiker marks water/camp/hazard, saved to SQLite — enriches checkpoint advice without inventing anything.
+- [ ] **Live `watchPosition` (bonus):** wire the real-GPS source into the abstraction; screen-on demo only.
+- [ ] **Final checklist:** Space public under the org; loads cleanly; no keys; `.gitignore` excludes weights + uploaded GPX; video + social published before June 15.
+
+---
+
+## What to Hand the Vibe-Coding LLM
+1. **The real GPX file** — build/test against it, not synthetic.
+2. **First-aid corpus** (chunked) + **static emergency card** text — model can't originate medical content.
+3. **Altitude/AMS thresholds + gear rules + seasonal averages** — verified data files, not invented.
+4. Reused Kisan-Sathi contracts: `src/llm.py` backend interface, Dockerfile, RAG setup, SQLite layer, whisper.cpp ASR.
+5. The **position abstraction** interface (simulated + live) so every contextual feature is source-agnostic.
+6. **ORS integration note:** planning-phase only; output is a local GPX treated identically to an upload; validate routes.
+7. **Acceptance tests:** distance ±2% on a known GPX; smoothed (not raw) elevation gain; map renders offline (no online tiles); first-aid answers always cite a section; checkpoint advice never names a water source absent from waypoints; risk note advisory-only; journal entries store the raw transcript + position.
+
+## Carry-Through Gotchas
+- Smooth elevation before summing (the #1 GPX error).
+- **No online map tiles** — folium + local MBTiles, or the demo dies in airplane mode.
+- ORS is planning-phase routing, not named-trek lookup — validate it.
+- No invented water/hazards — grounded in waypoints/data only.
+- First-aid + risk are high-stakes — ground, cite, advisory framing, static emergency floor.
+- Demo on simulated position; live GPS is a bonus.
+- Test on the real GPX early; verify `folium` on-device.

Routes/track_5-14724236830.gpx

@@ -0,0 +1,266 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<gpx version="1.1" creator="gpx-tracks.org" xmlns="http://www.topografix.com/GPX/1/1">
+<metadata>
+  <desc>Generated using OpenStreetMap data</desc>
+  <author>OpenStreetMap contributors</author>
+  <link href="https://www.openstreetmap.org/copyright">
+    <text>OpenStreetMap License</text>
+  </link>
+</metadata>
+  <trk>
+    <trkseg>
+      <trkpt lat="46.0734974" lon="11.1717214"></trkpt>
+      <trkpt lat="46.0737836" lon="11.1727025"></trkpt>
+      <trkpt lat="46.0740203" lon="11.1731432"></trkpt>
+      <trkpt lat="46.0740168" lon="11.173328"></trkpt>
+      <trkpt lat="46.0737622" lon="11.173827"></trkpt>
+      <trkpt lat="46.0734375" lon="11.1738863"></trkpt>
+      <trkpt lat="46.0731624" lon="11.1743486"></trkpt>
+      <trkpt lat="46.0730316" lon="11.1748916"></trkpt>
+      <trkpt lat="46.0728944" lon="11.175002"></trkpt>
+      <trkpt lat="46.0728165" lon="11.1750598"></trkpt>
+      <trkpt lat="46.0725141" lon="11.1752516"></trkpt>
+      <trkpt lat="46.0724562" lon="11.1752923"></trkpt>
+      <trkpt lat="46.072404" lon="11.1755511"></trkpt>
+      <trkpt lat="46.0723352" lon="11.1757355"></trkpt>
+      <trkpt lat="46.072069" lon="11.1762407"></trkpt>
+      <trkpt lat="46.0717648" lon="11.1767315"></trkpt>
+      <trkpt lat="46.0719912" lon="11.1768785"></trkpt>
+      <trkpt lat="46.0720172" lon="11.1772164"></trkpt>
+      <trkpt lat="46.0720284" lon="11.1788472"></trkpt>
+      <trkpt lat="46.0720172" lon="11.1800435"></trkpt>
+      <trkpt lat="46.0721118" lon="11.1805194"></trkpt>
+      <trkpt lat="46.0722225" lon="11.1802648"></trkpt>
+      <trkpt lat="46.0722136" lon="11.1799061"></trkpt>
+      <trkpt lat="46.0722908" lon="11.1798927"></trkpt>
+      <trkpt lat="46.0723185" lon="11.1801444"></trkpt>
+      <trkpt lat="46.0723926" lon="11.1799338"></trkpt>
+      <trkpt lat="46.0726239" lon="11.17992"></trkpt>
+      <trkpt lat="46.0726283" lon="11.1807755"></trkpt>
+      <trkpt lat="46.0727848" lon="11.1808579"></trkpt>
+      <trkpt lat="46.0728563" lon="11.1806364"></trkpt>
+      <trkpt lat="46.0729224" lon="11.1806719"></trkpt>
+      <trkpt lat="46.0730825" lon="11.1810204"></trkpt>
+      <trkpt lat="46.0734128" lon="11.1811378"></trkpt>
+      <trkpt lat="46.0738276" lon="11.1810573"></trkpt>
+      <trkpt lat="46.0741403" lon="11.1811643"></trkpt>
+      <trkpt lat="46.0743251" lon="11.1812466"></trkpt>
+      <trkpt lat="46.0745456" lon="11.1815105"></trkpt>
+      <trkpt lat="46.0745694" lon="11.1814247"></trkpt>
+      <trkpt lat="46.0746536" lon="11.1813296"></trkpt>
+      <trkpt lat="46.0747034" lon="11.1812759"></trkpt>
+      <trkpt lat="46.0747419" lon="11.1812238"></trkpt>
+      <trkpt lat="46.0747674" lon="11.1811396"></trkpt>
+      <trkpt lat="46.0748016" lon="11.1810041"></trkpt>
+      <trkpt lat="46.0748958" lon="11.180834"></trkpt>
+      <trkpt lat="46.0749676" lon="11.1808063"></trkpt>
+      <trkpt lat="46.0750275" lon="11.1808043"></trkpt>
+      <trkpt lat="46.0750713" lon="11.1808199"></trkpt>
+      <trkpt lat="46.0751227" lon="11.1808581"></trkpt>
+      <trkpt lat="46.0751844" lon="11.1809787"></trkpt>
+      <trkpt lat="46.075376" lon="11.181141"></trkpt>
+      <trkpt lat="46.0754095" lon="11.1811423"></trkpt>
+      <trkpt lat="46.0753928" lon="11.1810619"></trkpt>
+      <trkpt lat="46.0754012" lon="11.1808969"></trkpt>
+      <trkpt lat="46.0754328" lon="11.1808433"></trkpt>
+      <trkpt lat="46.0754784" lon="11.1808151"></trkpt>
+      <trkpt lat="46.075496" lon="11.1807588"></trkpt>
+      <trkpt lat="46.0755334" lon="11.1807545"></trkpt>
+      <trkpt lat="46.0756347" lon="11.180862"></trkpt>
+      <trkpt lat="46.0756635" lon="11.1809009"></trkpt>
+      <trkpt lat="46.0757185" lon="11.180853"></trkpt>
+      <trkpt lat="46.0757277" lon="11.1805978"></trkpt>
+      <trkpt lat="46.0757454" lon="11.1805563"></trkpt>
+      <trkpt lat="46.0757621" lon="11.1805402"></trkpt>
+      <trkpt lat="46.0758459" lon="11.1805174"></trkpt>
+      <trkpt lat="46.0758589" lon="11.1804436"></trkpt>
+      <trkpt lat="46.0758686" lon="11.1803745"></trkpt>
+      <trkpt lat="46.0759105" lon="11.1803893"></trkpt>
+      <trkpt lat="46.0759901" lon="11.1806227"></trkpt>
+      <trkpt lat="46.0760556" lon="11.1807366"></trkpt>
+      <trkpt lat="46.0761226" lon="11.1808131"></trkpt>
+      <trkpt lat="46.0762064" lon="11.1810364"></trkpt>
+      <trkpt lat="46.0763157" lon="11.1811725"></trkpt>
+      <trkpt lat="46.0763519" lon="11.1812443"></trkpt>
+      <trkpt lat="46.0763864" lon="11.1813696"></trkpt>
+      <trkpt lat="46.0764278" lon="11.18155"></trkpt>
+      <trkpt lat="46.0764552" lon="11.1816278"></trkpt>
+      <trkpt lat="46.0764687" lon="11.1817311"></trkpt>
+      <trkpt lat="46.0764668" lon="11.1818739"></trkpt>
+      <trkpt lat="46.0764854" lon="11.1820818"></trkpt>
+      <trkpt lat="46.0765036" lon="11.1820791"></trkpt>
+      <trkpt lat="46.0765227" lon="11.1820858"></trkpt>
+      <trkpt lat="46.0765534" lon="11.1821227"></trkpt>
+      <trkpt lat="46.076571" lon="11.1821428"></trkpt>
+      <trkpt lat="46.0766593" lon="11.1821455"></trkpt>
+      <trkpt lat="46.0767188" lon="11.1821541"></trkpt>
+      <trkpt lat="46.0767724" lon="11.182137"></trkpt>
+      <trkpt lat="46.076832" lon="11.182094"></trkpt>
+      <trkpt lat="46.0768736" lon="11.182094"></trkpt>
+      <trkpt lat="46.076926" lon="11.1820234"></trkpt>
+      <trkpt lat="46.0770264" lon="11.181951"></trkpt>
+      <trkpt lat="46.0770761" lon="11.1818795"></trkpt>
+      <trkpt lat="46.0771146" lon="11.1818551"></trkpt>
+      <trkpt lat="46.0771341" lon="11.181782"></trkpt>
+      <trkpt lat="46.0772011" lon="11.181726"></trkpt>
+      <trkpt lat="46.0772602" lon="11.1816238"></trkpt>
+      <trkpt lat="46.0772797" lon="11.1815286"></trkpt>
+      <trkpt lat="46.0773192" lon="11.1814008"></trkpt>
+      <trkpt lat="46.0773448" lon="11.1813569"></trkpt>
+      <trkpt lat="46.0773667" lon="11.1813566"></trkpt>
+      <trkpt lat="46.0774069" lon="11.1814213"></trkpt>
+      <trkpt lat="46.0774299" lon="11.1815192"></trkpt>
+      <trkpt lat="46.0774686" lon="11.1816053"></trkpt>
+      <trkpt lat="46.0775411" lon="11.1816791"></trkpt>
+      <trkpt lat="46.0775388" lon="11.181726"></trkpt>
+      <trkpt lat="46.0775304" lon="11.1817693"></trkpt>
+      <trkpt lat="46.0775539" lon="11.1818146"></trkpt>
+      <trkpt lat="46.0775432" lon="11.1819547"></trkpt>
+      <trkpt lat="46.0775551" lon="11.1820271"></trkpt>
+      <trkpt lat="46.0775541" lon="11.1820861"></trkpt>
+      <trkpt lat="46.0775679" lon="11.1820969"></trkpt>
+      <trkpt lat="46.0775997" lon="11.1820389"></trkpt>
+      <trkpt lat="46.0776139" lon="11.1820727"></trkpt>
+      <trkpt lat="46.0776579" lon="11.1820741"></trkpt>
+      <trkpt lat="46.0776969" lon="11.1820305"></trkpt>
+      <trkpt lat="46.0777239" lon="11.1819842"></trkpt>
+      <trkpt lat="46.0778093" lon="11.18194"></trkpt>
+      <trkpt lat="46.0778486" lon="11.1818819"></trkpt>
+      <trkpt lat="46.0778639" lon="11.1818494"></trkpt>
+      <trkpt lat="46.0778981" lon="11.181775"></trkpt>
+      <trkpt lat="46.0779265" lon="11.181716"></trkpt>
+      <trkpt lat="46.077946" lon="11.1816342"></trkpt>
+      <trkpt lat="46.0779177" lon="11.1815296"></trkpt>
+      <trkpt lat="46.0778335" lon="11.1814002"></trkpt>
+      <trkpt lat="46.0778267" lon="11.1813629"></trkpt>
+      <trkpt lat="46.0778358" lon="11.1813422"></trkpt>
+      <trkpt lat="46.0778809" lon="11.1813593"></trkpt>
+      <trkpt lat="46.0778616" lon="11.181319"></trkpt>
+      <trkpt lat="46.0778525" lon="11.1812818"></trkpt>
+      <trkpt lat="46.0778458" lon="11.1812563"></trkpt>
+      <trkpt lat="46.0778409" lon="11.1812158"></trkpt>
+      <trkpt lat="46.077839" lon="11.1811453"></trkpt>
+      <trkpt lat="46.0778256" lon="11.181094"></trkpt>
+      <trkpt lat="46.0778302" lon="11.1810444"></trkpt>
+      <trkpt lat="46.0778497" lon="11.1810324"></trkpt>
+      <trkpt lat="46.0778711" lon="11.1810431"></trkpt>
+      <trkpt lat="46.0779009" lon="11.1810753"></trkpt>
+      <trkpt lat="46.077927" lon="11.1811544"></trkpt>
+      <trkpt lat="46.0780051" lon="11.1811987"></trkpt>
+      <trkpt lat="46.0780256" lon="11.1812268"></trkpt>
+      <trkpt lat="46.0780488" lon="11.1813167"></trkpt>
+      <trkpt lat="46.0780926" lon="11.1813314"></trkpt>
+      <trkpt lat="46.0781961" lon="11.1815243"></trkpt>
+      <trkpt lat="46.0782544" lon="11.1816743"></trkpt>
+      <trkpt lat="46.0782983" lon="11.1817455"></trkpt>
+      <trkpt lat="46.0783595" lon="11.1818089"></trkpt>
+      <trkpt lat="46.0783972" lon="11.1818846"></trkpt>
+      <trkpt lat="46.078414" lon="11.1819524"></trkpt>
+      <trkpt lat="46.0785307" lon="11.1819718"></trkpt>
+      <trkpt lat="46.0785335" lon="11.1819282"></trkpt>
+      <trkpt lat="46.0785065" lon="11.181827"></trkpt>
+      <trkpt lat="46.0784665" lon="11.1816969"></trkpt>
+      <trkpt lat="46.0784665" lon="11.1816385"></trkpt>
+      <trkpt lat="46.0784833" lon="11.1816533"></trkpt>
+      <trkpt lat="46.0785372" lon="11.1817002"></trkpt>
+      <trkpt lat="46.0785489" lon="11.1816848"></trkpt>
+      <trkpt lat="46.0785493" lon="11.1816446"></trkpt>
+      <trkpt lat="46.0785368" lon="11.1815608"></trkpt>
+      <trkpt lat="46.0785516" lon="11.1814865"></trkpt>
+      <trkpt lat="46.0785824" lon="11.1813216"></trkpt>
+      <trkpt lat="46.0785586" lon="11.1812014"></trkpt>
+      <trkpt lat="46.0785149" lon="11.1811034"></trkpt>
+      <trkpt lat="46.0785182" lon="11.1810022"></trkpt>
+      <trkpt lat="46.0785517" lon="11.1809231"></trkpt>
+      <trkpt lat="46.0785521" lon="11.1808567"></trkpt>
+      <trkpt lat="46.0785265" lon="11.1807474"></trkpt>
+      <trkpt lat="46.0785424" lon="11.180689"></trkpt>
+      <trkpt lat="46.0785879" lon="11.1806582"></trkpt>
+      <trkpt lat="46.0786135" lon="11.1805616"></trkpt>
+      <trkpt lat="46.0786238" lon="11.1804657"></trkpt>
+      <trkpt lat="46.0785847" lon="11.1803544"></trkpt>
+      <trkpt lat="46.0785461" lon="11.1802988"></trkpt>
+      <trkpt lat="46.0785382" lon="11.1801915"></trkpt>
+      <trkpt lat="46.0785558" lon="11.1800064"></trkpt>
+      <trkpt lat="46.0785679" lon="11.1798093"></trkpt>
+      <trkpt lat="46.078553" lon="11.1796369"></trkpt>
+      <trkpt lat="46.078567" lon="11.1795799"></trkpt>
+      <trkpt lat="46.0785819" lon="11.1793613"></trkpt>
+      <trkpt lat="46.078587" lon="11.1793003"></trkpt>
+      <trkpt lat="46.0785847" lon="11.179189"></trkpt>
+      <trkpt lat="46.07862" lon="11.1790321"></trkpt>
+      <trkpt lat="46.0786242" lon="11.1787511"></trkpt>
+      <trkpt lat="46.0786196" lon="11.1786492"></trkpt>
+      <trkpt lat="46.0786447" lon="11.1785379"></trkpt>
+      <trkpt lat="46.07868" lon="11.1783374"></trkpt>
+      <trkpt lat="46.0786963" lon="11.1781503"></trkpt>
+      <trkpt lat="46.0787963" lon="11.1779109"></trkpt>
+      <trkpt lat="46.0788196" lon="11.1778526"></trkpt>
+      <trkpt lat="46.0788233" lon="11.1777218"></trkpt>
+      <trkpt lat="46.0790385" lon="11.1777575"></trkpt>
+      <trkpt lat="46.0788233" lon="11.1777218"></trkpt>
+      <trkpt lat="46.0788061" lon="11.1776608"></trkpt>
+      <trkpt lat="46.0787759" lon="11.1776025"></trkpt>
+      <trkpt lat="46.0787563" lon="11.1774925"></trkpt>
+      <trkpt lat="46.0787438" lon="11.1773356"></trkpt>
+      <trkpt lat="46.0787307" lon="11.1772605"></trkpt>
+      <trkpt lat="46.0787326" lon="11.1771244"></trkpt>
+      <trkpt lat="46.0787084" lon="11.177007"></trkpt>
+      <trkpt lat="46.0787052" lon="11.1769152"></trkpt>
+      <trkpt lat="46.0787089" lon="11.1768146"></trkpt>
+      <trkpt lat="46.0787228" lon="11.1767039"></trkpt>
+      <trkpt lat="46.0787275" lon="11.1765967"></trkpt>
+      <trkpt lat="46.07872" lon="11.1764585"></trkpt>
+      <trkpt lat="46.0787028" lon="11.1763646"></trkpt>
+      <trkpt lat="46.0786931" lon="11.1763016"></trkpt>
+      <trkpt lat="46.078601" lon="11.1760743"></trkpt>
+      <trkpt lat="46.0785712" lon="11.1759757"></trkpt>
+      <trkpt lat="46.0785512" lon="11.1758805"></trkpt>
+      <trkpt lat="46.0785484" lon="11.1758215"></trkpt>
+      <trkpt lat="46.07854" lon="11.1757893"></trkpt>
+      <trkpt lat="46.0785056" lon="11.1757209"></trkpt>
+      <trkpt lat="46.0784298" lon="11.1755888"></trkpt>
+      <trkpt lat="46.078254" lon="11.1753266"></trkpt>
+      <trkpt lat="46.0781302" lon="11.175167"></trkpt>
+      <trkpt lat="46.0780882" lon="11.1751074"></trkpt>
+      <trkpt lat="46.0780474" lon="11.1750403"></trkpt>
+      <trkpt lat="46.0779777" lon="11.1749028"></trkpt>
+      <trkpt lat="46.0779811" lon="11.1748328"></trkpt>
+      <trkpt lat="46.0779763" lon="11.1748002"></trkpt>
+      <trkpt lat="46.077947" lon="11.1747473"></trkpt>
+      <trkpt lat="46.0779046" lon="11.1746809"></trkpt>
+      <trkpt lat="46.0777967" lon="11.1744864"></trkpt>
+      <trkpt lat="46.0777428" lon="11.1744308"></trkpt>
+      <trkpt lat="46.0776577" lon="11.1743088"></trkpt>
+      <trkpt lat="46.0776162" lon="11.1743094"></trkpt>
+      <trkpt lat="46.0775548" lon="11.1743148"></trkpt>
+      <trkpt lat="46.0774125" lon="11.1743456"></trkpt>
+      <trkpt lat="46.0772981" lon="11.1743966"></trkpt>
+      <trkpt lat="46.0769855" lon="11.1745763"></trkpt>
+      <trkpt lat="46.0768152" lon="11.1746366"></trkpt>
+      <trkpt lat="46.0767036" lon="11.1746822"></trkpt>
+      <trkpt lat="46.076591" lon="11.1747238"></trkpt>
+      <trkpt lat="46.0764757" lon="11.1747064"></trkpt>
+      <trkpt lat="46.0764171" lon="11.1747345"></trkpt>
+      <trkpt lat="46.0763036" lon="11.174752"></trkpt>
+      <trkpt lat="46.076218" lon="11.1748029"></trkpt>
+      <trkpt lat="46.0760784" lon="11.1748512"></trkpt>
+      <trkpt lat="46.0760031" lon="11.1748955"></trkpt>
+      <trkpt lat="46.0758477" lon="11.174929"></trkpt>
+      <trkpt lat="46.0757668" lon="11.1749732"></trkpt>
+      <trkpt lat="46.0755068" lon="11.1749063"></trkpt>
+      <trkpt lat="46.0751974" lon="11.1749093"></trkpt>
+      <trkpt lat="46.0748717" lon="11.1743811"></trkpt>
+      <trkpt lat="46.0746653" lon="11.1743811"></trkpt>
+      <trkpt lat="46.0746002" lon="11.1743811"></trkpt>
+      <trkpt lat="46.0742637" lon="11.1743798"></trkpt>
+      <trkpt lat="46.07403" lon="11.174376"></trkpt>
+      <trkpt lat="46.0739346" lon="11.1741839"></trkpt>
+      <trkpt lat="46.0737622" lon="11.173827"></trkpt>
+      <trkpt lat="46.0740168" lon="11.173328"></trkpt>
+      <trkpt lat="46.0740203" lon="11.1731432"></trkpt>
+      <trkpt lat="46.0737836" lon="11.1727025"></trkpt>
+      <trkpt lat="46.0734974" lon="11.1717214"></trkpt>
+    </trkseg>
+  </trk>
+</gpx>

app.py

@@ -0,0 +1,351 @@
+import os
+import base64
+import requests
+import gradio as gr
+import pandas as pd
+import folium
+from src.gpx_parser import parse_gpx_file
+import src.llm as llm
+
+# Initialize cache and temp folders
+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):
+    """
+    Generate interactive folium map.
+    """
+    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)
+    
+    # Draw track polyline
+    locations = [(p["lat"], p["lon"]) for p in points]
+    folium.PolyLine(locations, color="#f59e0b", weight=5, opacity=0.85).add_to(m)
+    
+    # Draw checkpoints
+    for cp in checkpoints:
+        name = cp["name"]
+        lat = cp["lat"]
+        lon = cp["lon"]
+        ele = cp["ele"]
+        dist = cp["cum_dist"]
+        
+        # Color code markers
+        if name == "Start":
+            color = "green"
+            icon = "play"
+        elif name == "End":
+            color = "red"
+            icon = "flag"
+        else:
+            color = "cadetblue"
+            icon = "info-sign"
+            
+        popup_text = f"""
+        <div style="font-family: 'Outfit', sans-serif; font-size: 11px;">
+            <b>{name}</b><br>
+            Distance: {dist:.2f} km<br>
+            Elevation: {ele:.1f} m
+        </div>
+        """
+        
+        folium.Marker(
+            location=[lat, lon],
+            popup=popup_text,
+            tooltip=name,
+            icon=folium.Icon(color=color, icon=icon)
+        ).add_to(m)
+        
+    return m._repr_html_()
+
+def get_map_iframe(map_html):
+    """
+    Helper to bundle raw HTML into a secure, sandboxed base64 data URI iframe.
+    """
+    b64_html = base64.b64encode(map_html.encode('utf-8')).decode('utf-8')
+    iframe_src = f"data:text/html;base64,{b64_html}"
+    return f'<iframe src="{iframe_src}" width="100%" height="520px" style="border:1px solid rgba(245,158,11,0.2); border-radius: 12px;"></iframe>'
+
+def fetch_ors_route(start_coords, end_coords, profile, api_key):
+    """
+    Fetches hiking route between coordinates using OpenRouteService.
+    Falls back to a straight-line GPX segment if API key is empty or request fails.
+    """
+    try:
+        start_lat, start_lon = map(float, start_coords.split(","))
+        end_lat, end_lon = map(float, end_coords.split(","))
+    except Exception:
+        raise gr.Error("Invalid coordinate format. Ensure format is 'lat, lon'.")
+        
+    temp_dir = "./temp"
+    os.makedirs(temp_dir, exist_ok=True)
+    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"?>
+<gpx version="1.1" creator="Trailhead Mock" xmlns="http://www.topografix.com/GPX/1/1">
+  <trk>
+    <trkseg>
+      <trkpt lat="{start_lat}" lon="{start_lon}"></trkpt>
+      <trkpt lat="{mid_lat}" lon="{mid_lon}"></trkpt>
+      <trkpt lat="{end_lat}" lon="{end_lon}"></trkpt>
+    </trkseg>
+  </trk>
+</gpx>"""
+        with open(file_path, "w", encoding="utf-8") as f:
+            f.write(gpx_content)
+        gr.Warning("No ORS API Key provided. Generated a mock direct route segment.")
+        return file_path
+        
+    url = f"https://api.openrouteservice.org/v2/directions/{profile}/gpx"
+    headers = {
+        'Accept': 'application/gpx+xml',
+        'Authorization': api_key,
+        'Content-Type': 'application/json'
+    }
+    body = {
+        "coordinates": [[start_lon, start_lat], [end_lon, end_lat]]
+    }
+    
+    try:
+        response = requests.post(url, json=body, headers=headers, timeout=12)
+        if response.status_code == 200:
+            with open(file_path, "wb") as f:
+                f.write(response.content)
+            gr.Info("Successfully fetched route from OpenRouteService!")
+            return file_path
+        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"?>
+<gpx version="1.1" creator="Trailhead Fallback" xmlns="http://www.topografix.com/GPX/1/1">
+  <trk>
+    <trkseg>
+      <trkpt lat="{start_lat}" lon="{start_lon}"></trkpt>
+      <trkpt lat="{mid_lat}" lon="{mid_lon}"></trkpt>
+      <trkpt lat="{end_lat}" lon="{end_lon}"></trkpt>
+    </trkseg>
+  </trk>
+</gpx>"""
+        with open(file_path, "w", encoding="utf-8") as f:
+            f.write(gpx_content)
+        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
+    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'>
+            <div class='hud-stat-val'>{data['total_distance_km']:.2f}</div>
+            <div class='hud-stat-lbl'>Distance (km)</div>
+        </div>
+        <div class='hud-stat-box'>
+            <div class='hud-stat-val'>{data['elevation_gain_m']:.1f}</div>
+            <div class='hud-stat-lbl'>Elevation Gain (m)</div>
+        </div>
+        <div class='hud-stat-box'>
+            <div class='hud-stat-val'>{data['elevation_loss_m']:.1f}</div>
+            <div class='hud-stat-lbl'>Elevation Loss (m)</div>
+        </div>
+        <div class='hud-stat-box'>
+            <div class='hud-stat-val'>{data['min_elevation_m']:.0f} - {data['max_elevation_m']:.0f}</div>
+            <div class='hud-stat-lbl'>Altitude Range (m)</div>
+        </div>
+        <div class='hud-stat-box'>
+            <div class='hud-stat-val'>{data['estimated_days']:.1f}</div>
+            <div class='hud-stat-lbl'>Est. Hiking Days</div>
+        </div>
+    </div>
+    """
+    
+    # Generate Folium Map
+    map_html = generate_folium_map(data["points"], data["checkpoints"])
+    map_iframe = get_map_iframe(map_html)
+    
+    # Format Checkpoint List for Dataframe
+    checkpoint_table_data = []
+    for cp in data["checkpoints"]:
+        checkpoint_table_data.append([
+            cp["name"],
+            f"{cp['lat']:.5f}, {cp['lon']:.5f}",
+            f"{cp['cum_dist']:.2f} km",
+            f"{cp['ele']:.1f} m"
+        ])
+        
+    return stats_html, map_iframe, checkpoint_table_data
+
+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)
+    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()
+        )
+
+# --- Gradio Chatbot Integration ---
+def respond(message, history):
+    # Enforce streaming for better UX
+    response_accumulator = ""
+    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."
+    )
+    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:
+    gr.HTML("""
+    <div style='text-align: center; padding: 10px 0;'>
+        <h1>🌲 Trailhead 🌲</h1>
+        <p style='color: #f59e0b; font-family: "Share Tech Mono", monospace; letter-spacing: 0.1em; text-transform: uppercase; font-size: 1rem; margin-top: -5px;'>
+            Off-the-Grid Trail Computer & Route Planner
+        </p>
+    </div>
+    """)
+    
+    with gr.Tabs():
+        with gr.TabItem("🧭 Trek Planner & HUD"):
+            with gr.Row():
+                with gr.Column(scale=1):
+                    gr.Markdown("### 📂 Route Ingestion")
+                    
+                    preloaded_route = gr.Dropdown(
+                        choices=["Preloaded Route: Trento Track"],
+                        value="Preloaded Route: Trento Track",
+                        label="Preloaded Routes (Trento, Italy)"
+                    )
+                    
+                    upload_file = gr.File(
+                        file_types=[".gpx"],
+                        label="Upload GPX Route File"
+                    )
+                    
+                    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)"
+                        )
+                        end_pt = gr.Textbox(
+                            value="46.0788233, 11.1777218",
+                            label="End Coordinates (Lat, Lon)"
+                        )
+                        ors_profile = gr.Dropdown(
+                            choices=["foot-hiking", "foot-walking", "cycling-mountain"],
+                            value="foot-hiking",
+                            label="Profile"
+                        )
+                        ors_api_key = gr.Textbox(
+                            type="password",
+                            label="OpenRouteService API Key (Optional)",
+                            placeholder="Paste your API key here..."
+                        )
+                        fetch_route_btn = gr.Button("Fetch & Load Route", variant="secondary")
+                        
+                with gr.Column(scale=2):
+                    # Stats display
+                    stats_display = gr.HTML()
+                    
+                    # Interactive Map display
+                    map_display = gr.HTML()
+                    
+            with gr.Accordion("📋 Route Checkpoint Briefing", open=True):
+                checkpoint_table = gr.DataFrame(
+                    headers=["Checkpoint", "Coordinates", "Cumulative Distance", "Altitude"],
+                    datatype=["str", "str", "str", "str"],
+                    column_count=(4, "fixed")
+                )
+                
+        with gr.TabItem("💬 Wilderness Guide AI"):
+            gr.ChatInterface(
+                respond,
+                examples=[
+                    "What gear checklist do I need for a 3-day high-altitude trek?",
+                    "How do I treat a sprained ankle on the trail?",
+                    "What is Naismith's Rule for calculating hiking time?"
+                ]
+            )
+
+    # --- 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]
+    )
+    
+    # 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]
+    )
+    
+    # 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]
+    )
+    
+    # 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]
+    )
+
+if __name__ == "__main__":
+    port = int(os.environ.get("PORT", 7860))
+    try:
+        demo.launch(server_name="0.0.0.0", server_port=port)
+    except OSError:
+        print(f"[app] Port {port} is busy. Falling back to automatic port selection...")
+        demo.launch(server_name="127.0.0.1")

assets/custom.css

@@ -0,0 +1,158 @@
+/* Trailhead Premium Tactical HUD Theme */
+
+@import url('https://fonts.googleapis.com/css2?family=Share+Tech+Mono&family=Outfit:wght@300;400;500;600;700&display=swap');
+
+:root {
+    --bg-gradient: linear-gradient(135deg, #0a0e12 0%, #050709 100%);
+    --card-bg: rgba(13, 20, 26, 0.75);
+    --card-border: rgba(245, 158, 11, 0.18); /* Amber border */
+    --accent-primary: #f59e0b; /* Amber */
+    --accent-hover: #d97706;
+    --accent-green: #10b981; /* Safe path green */
+    --text-primary: #f3f4f6;
+    --text-muted: #9ca3af;
+    --danger-red: #ef4444;
+}
+
+body, .gradio-container {
+    background: var(--bg-gradient) !important;
+    font-family: 'Outfit', -apple-system, sans-serif !important;
+    color: var(--text-primary) !important;
+}
+
+/* Share Tech Mono for digital stats & coordinates */
+.mono-display {
+    font-family: 'Share Tech Mono', monospace !important;
+}
+
+/* Glassmorphism Cards */
+.gradio-container .gr-box, 
+.gradio-container .gr-panel,
+.gradio-container .gr-card {
+    background: var(--card-bg) !important;
+    border: 1px solid var(--card-border) !important;
+    backdrop-filter: blur(12px) !important;
+    border-radius: 16px !important;
+    box-shadow: 0 8px 32px 0 rgba(0, 0, 0, 0.5) !important;
+}
+
+/* Typography settings */
+h1 {
+    font-family: 'Share Tech Mono', monospace !important;
+    font-weight: 700 !important;
+    letter-spacing: 0.05em !important;
+    background: linear-gradient(to right, #f59e0b, #fbbf24, #10b981) !important;
+    -webkit-background-clip: text !important;
+    -webkit-text-fill-color: transparent !important;
+    font-size: 2.5rem !important;
+    margin-bottom: 0.5rem !important;
+    text-align: center !important;
+    text-transform: uppercase !important;
+    text-shadow: 0 0 15px rgba(245, 158, 11, 0.2) !important;
+}
+
+p, span, label {
+    color: var(--text-primary) !important;
+}
+
+/* Buttons Styling */
+.gradio-container button.primary {
+    background: linear-gradient(135deg, #f59e0b 0%, #d97706 100%) !important;
+    border: 1px solid rgba(251, 191, 36, 0.3) !important;
+    color: black !important;
+    font-family: 'Share Tech Mono', monospace !important;
+    font-weight: 700 !important;
+    text-transform: uppercase !important;
+    font-size: 1.1rem !important;
+    border-radius: 12px !important;
+    padding: 14px 24px !important;
+    min-height: 54px !important; /* Touch target */
+    cursor: pointer !important;
+    transition: all 0.3s ease !important;
+    box-shadow: 0 4px 15px rgba(245, 158, 11, 0.25) !important;
+}
+
+.gradio-container button.primary:hover {
+    transform: translateY(-2px) !important;
+    box-shadow: 0 6px 20px rgba(245, 158, 11, 0.4) !important;
+}
+
+.gradio-container button.secondary {
+    background: rgba(255, 255, 255, 0.05) !important;
+    border: 1px solid var(--card-border) !important;
+    color: var(--text-primary) !important;
+    font-family: 'Share Tech Mono', monospace !important;
+    font-weight: 500;
+    text-transform: uppercase !important;
+    border-radius: 12px !important;
+    padding: 12px 20px !important;
+    min-height: 50px !important;
+    transition: all 0.3s ease !important;
+}
+
+.gradio-container button.secondary:hover {
+    background: rgba(245, 158, 11, 0.1) !important;
+    border-color: var(--accent-primary) !important;
+}
+
+/* Large Input Targets */
+.gradio-container input, 
+.gradio-container textarea, 
+.gradio-container select {
+    background: rgba(0, 0, 0, 0.4) !important;
+    border: 1px solid var(--card-border) !important;
+    border-radius: 10px !important;
+    color: var(--text-primary) !important;
+    padding: 12px !important;
+    font-size: 1.05rem !important;
+}
+
+.gradio-container input:focus, 
+.gradio-container textarea:focus, 
+.gradio-container select:focus {
+    border-color: var(--accent-green) !important;
+    box-shadow: 0 0 0 2px rgba(16, 185, 129, 0.2) !important;
+}
+
+/* Custom Table/DataFrame styling */
+.gradio-container table {
+    background: transparent !important;
+}
+
+.gradio-container th {
+    background: rgba(245, 158, 11, 0.1) !important;
+    color: var(--accent-primary) !important;
+    font-weight: 600 !important;
+    font-family: 'Share Tech Mono', monospace !important;
+    text-transform: uppercase !important;
+}
+
+.gradio-container td {
+    border-bottom: 1px solid rgba(255, 255, 255, 0.05) !important;
+}
+
+/* HUD Stat Indicators */
+.hud-stat-box {
+    border: 1px solid var(--card-border);
+    background: rgba(13, 20, 26, 0.8);
+    border-radius: 12px;
+    padding: 15px;
+    text-align: center;
+    box-shadow: inset 0 0 10px rgba(245, 158, 11, 0.05);
+}
+
+.hud-stat-val {
+    font-family: 'Share Tech Mono', monospace;
+    font-size: 2.2rem;
+    font-weight: 700;
+    color: var(--accent-primary);
+    text-shadow: 0 0 8px rgba(245, 158, 11, 0.3);
+}
+
+.hud-stat-lbl {
+    font-size: 0.8rem;
+    text-transform: uppercase;
+    color: var(--text-muted);
+    letter-spacing: 0.1em;
+    margin-top: 5px;
+}

requirements.txt

@@ -0,0 +1,7 @@
+gradio>=5.0.0
+pandas
+numpy
+requests
+huggingface_hub
+gpxpy
+folium

src/gpx_parser.py

@@ -0,0 +1,314 @@
+import os
+import math
+import json
+import requests
+import gpxpy
+
+def haversine(lat1, lon1, lat2, lon2):
+    """Calculate the great-circle distance between two points on the Earth in meters."""
+    R = 6371000.0  # Radius of Earth in meters
+    phi1 = math.radians(lat1)
+    phi2 = math.radians(lat2)
+    delta_phi = math.radians(lat2 - lat1)
+    delta_lambda = math.radians(lon2 - lon1)
+    
+    a = math.sin(delta_phi / 2.0)**2 + math.cos(phi1) * math.cos(phi2) * math.sin(delta_lambda / 2.0)**2
+    c = 2.0 * math.atan2(math.sqrt(a), math.sqrt(1.0 - a))
+    return R * c
+
+def fetch_elevations_open_meteo(coords):
+    """
+    Fetch elevation coordinates in batches of 100 from the Open-Meteo elevation API.
+    Returns a list of floats representing elevation in meters.
+    """
+    elevations = []
+    batch_size = 100
+    for i in range(0, len(coords), batch_size):
+        batch = coords[i:i+batch_size]
+        lats = ",".join(f"{c[0]:.6f}" for c in batch)
+        lons = ",".join(f"{c[1]:.6f}" for c in batch)
+        url = f"https://api.open-meteo.com/v1/elevation?latitude={lats}&longitude={lons}"
+        
+        try:
+            print(f"[gpx_parser] Fetching elevation batch {i//batch_size + 1}...")
+            response = requests.get(url, timeout=10)
+            if response.status_code == 200:
+                data = response.json()
+                batch_elevations = data.get("elevation", [])
+                if len(batch_elevations) == len(batch):
+                    elevations.extend(batch_elevations)
+                else:
+                    print("[gpx_parser] Elevation list size mismatch. Filling with 0.0")
+                    elevations.extend([0.0] * len(batch))
+            else:
+                print(f"[gpx_parser] API error {response.status_code}. Using 0.0 for batch.")
+                elevations.extend([0.0] * len(batch))
+        except Exception as e:
+            print(f"[gpx_parser] Network/parsing exception: {e}. Using 0.0 for batch.")
+            elevations.extend([0.0] * len(batch))
+            
+    return elevations
+
+def smooth_elevations(elevations, window_size=5):
+    """Apply a simple moving average window to smooth out elevation profile data."""
+    if not elevations:
+        return []
+    smoothed = []
+    for i in range(len(elevations)):
+        start = max(0, i - window_size // 2)
+        end = min(len(elevations), i + window_size // 2 + 1)
+        window = elevations[start:end]
+        smoothed.append(sum(window) / len(window))
+    return smoothed
+
+def calculate_elevation_gain_loss(elevations, threshold=2.0):
+    """
+    Calculate cumulative elevation gain and loss in meters.
+    Filters out noise using a threshold value (minimum elevation delta).
+    """
+    gain = 0.0
+    loss = 0.0
+    if len(elevations) < 2:
+        return gain, loss
+        
+    last_val = elevations[0]
+    for val in elevations[1:]:
+        diff = val - last_val
+        if abs(diff) >= threshold:
+            if diff > 0:
+                gain += diff
+            else:
+                loss += abs(diff)
+            last_val = val
+    return gain, loss
+
+def parse_gpx_file(file_path, cache_dir="./temp"):
+    """
+    Parse a GPX file, fetch missing elevations, smooth the profile,
+    and compute trek statistics. Caches results locally to allow offline usage.
+    """
+    # Create cache directory if needed
+    os.makedirs(cache_dir, exist_ok=True)
+    
+    # Check cache first
+    file_name = os.path.basename(file_path)
+    cache_path = os.path.join(cache_dir, f"{file_name}.cache.json")
+    if os.path.exists(cache_path):
+        try:
+            with open(cache_path, "r", encoding="utf-8") as f:
+                print(f"[gpx_parser] Loading cached GPX data from {cache_path}")
+                return json.load(f)
+        except Exception as e:
+            print(f"[gpx_parser] Cache read error: {e}, parsing raw file...")
+
+    print(f"[gpx_parser] Parsing raw GPX file: {file_path}")
+    with open(file_path, "r", encoding="utf-8") as f:
+        gpx = gpxpy.parse(f)
+        
+    # Extract track points
+    points_raw = []
+    for track in gpx.tracks:
+        for segment in track.segments:
+            for pt in segment.points:
+                points_raw.append({
+                    "lat": pt.latitude,
+                    "lon": pt.longitude,
+                    "ele": pt.elevation
+                })
+                
+    # If GPX had no track points, look in waypoints or route points
+    if not points_raw:
+        for route in gpx.routes:
+            for pt in route.points:
+                points_raw.append({
+                    "lat": pt.latitude,
+                    "lon": pt.longitude,
+                    "ele": pt.elevation
+                })
+                
+    # Still empty? Check waypoints
+    if not points_raw and gpx.waypoints:
+        for wpt in gpx.waypoints:
+            points_raw.append({
+                "lat": wpt.latitude,
+                "lon": wpt.longitude,
+                "ele": wpt.elevation
+            })
+            
+    if not points_raw:
+        raise ValueError("No trackpoints, routepoints, or waypoints found in GPX file.")
+        
+    # Check if elevations are missing (all None or 0.0)
+    has_elevation = any(pt["ele"] is not None for pt in points_raw)
+    
+    if not has_elevation:
+        print("[gpx_parser] GPX has no elevation data. Fetching from Open-Meteo elevation API...")
+        coords = [(pt["lat"], pt["lon"]) for pt in points_raw]
+        elevations = fetch_elevations_open_meteo(coords)
+        for i, ele in enumerate(elevations):
+            points_raw[i]["ele"] = ele
+    else:
+        # Fill in any scattered missing elevations
+        for pt in points_raw:
+            if pt["ele"] is None:
+                pt["ele"] = 0.0
+                
+    # Smooth elevations
+    raw_elevations = [pt["ele"] for pt in points_raw]
+    smoothed_eles = smooth_elevations(raw_elevations)
+    for i, ele in enumerate(smoothed_eles):
+        points_raw[i]["ele"] = ele
+        
+    # Calculate cumulative distances (in meters) and build final points list
+    points_data = []
+    cum_dist = 0.0
+    
+    points_data.append({
+        "lat": points_raw[0]["lat"],
+        "lon": points_raw[0]["lon"],
+        "ele": points_raw[0]["ele"],
+        "cum_dist": 0.0
+    })
+    
+    for i in range(1, len(points_raw)):
+        p1 = points_raw[i-1]
+        p2 = points_raw[i]
+        d = haversine(p1["lat"], p1["lon"], p2["lat"], p2["lon"])
+        cum_dist += d
+        points_data.append({
+            "lat": p2["lat"],
+            "lon": p2["lon"],
+            "ele": p2["ele"],
+            "cum_dist": cum_dist
+        })
+        
+    # Calculate statistics
+    total_distance_m = cum_dist
+    total_distance_km = total_distance_m / 1000.0
+    
+    gain, loss = calculate_elevation_gain_loss(smoothed_eles)
+    
+    min_ele = min(smoothed_eles) if smoothed_eles else 0.0
+    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
+    waypoints = []
+    for wpt in gpx.waypoints:
+        waypoints.append({
+            "name": wpt.name or "Waypoint",
+            "lat": wpt.latitude,
+            "lon": wpt.longitude,
+            "ele": wpt.elevation or 0.0,
+            "desc": wpt.description or ""
+        })
+        
+    # 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:
+                d = haversine(wpt["lat"], wpt["lon"], pt["lat"], pt["lon"])
+                if d < min_d:
+                    min_d = d
+                    closest_pt = pt
+            checkpoints.append({
+                "name": wpt["name"],
+                "lat": wpt["lat"],
+                "lon": wpt["lon"],
+                "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)
+        
+    result = {
+        "file_name": file_name,
+        "total_distance_km": round(total_distance_km, 2),
+        "elevation_gain_m": round(gain, 1),
+        "elevation_loss_m": round(loss, 1),
+        "min_elevation_m": round(min_ele, 1),
+        "max_elevation_m": round(max_ele, 1),
+        "estimated_days": round(estimated_days, 1),
+        "naismith_hours": round(naismith_hours, 1),
+        "points": points_data,
+        "checkpoints": checkpoints
+    }
+    
+    # Save cache
+    try:
+        with open(cache_path, "w", encoding="utf-8") as f:
+            json.dump(result, f, indent=2)
+            print(f"[gpx_parser] Saved parsed GPX data cache to {cache_path}")
+    except Exception as e:
+        print(f"[gpx_parser] Cache write error: {e}")
+        
+    return result
+
+def generate_checkpoints(points_data, interval_meters=1000.0):
+    """Helper to partition track into regular distance checkpoints."""
+    if not points_data:
+        return []
+        
+    checkpoints = []
+    start_pt = points_data[0]
+    checkpoints.append({
+        "name": "Start",
+        "lat": start_pt["lat"],
+        "lon": start_pt["lon"],
+        "ele": start_pt["ele"],
+        "cum_dist": 0.0
+    })
+    
+    total_dist = points_data[-1]["cum_dist"]
+    next_checkpoint_dist = interval_meters
+    pt_idx = 1
+    
+    while next_checkpoint_dist < total_dist:
+        while pt_idx < len(points_data) and points_data[pt_idx]["cum_dist"] < next_checkpoint_dist:
+            pt_idx += 1
+            
+        if pt_idx >= len(points_data):
+            break
+            
+        p1 = points_data[pt_idx - 1]
+        p2 = points_data[pt_idx]
+        
+        if abs(p1["cum_dist"] - next_checkpoint_dist) < abs(p2["cum_dist"] - next_checkpoint_dist):
+            chosen = p1
+        else:
+            chosen = p2
+            
+        checkpoints.append({
+            "name": f"Km {next_checkpoint_dist / 1000.0:.1f}",
+            "lat": chosen["lat"],
+            "lon": chosen["lon"],
+            "ele": chosen["ele"],
+            "cum_dist": round(chosen["cum_dist"] / 1000.0, 2)
+        })
+        
+        next_checkpoint_dist += interval_meters
+        
+    end_pt = points_data[-1]
+    if len(checkpoints) == 1 or (total_dist / 1000.0 - checkpoints[-1]["cum_dist"]) > 0.1:
+        checkpoints.append({
+            "name": "End",
+            "lat": end_pt["lat"],
+            "lon": end_pt["lon"],
+            "ele": end_pt["ele"],
+            "cum_dist": round(total_dist / 1000.0, 2)
+        })
+        
+    return checkpoints

src/llm.py

@@ -0,0 +1,355 @@
+import os
+import time
+import requests
+import json
+import base64
+import threading
+from PIL import Image
+
+_model_lock = threading.Lock()
+
+# Backend configuration via environment variable. Defaults to auto-detected or "mock"
+try:
+    import llama_cpp
+    default_backend = "llama_cpp"
+except ImportError:
+    default_backend = "mock"
+BACKEND = os.environ.get("BACKEND", default_backend).lower()
+
+# Constants for Hugging Face Space model loading
+MODEL_REPO = "bartowski/google_gemma-4-E2B-it-GGUF"
+MODEL_FILE = "google_gemma-4-E2B-it-Q4_K_M.gguf"
+LOCAL_MODEL_DIR = os.environ.get("MODEL_DIR", "./model")
+
+_llama_model = None
+
+def _download_gguf():
+    """Download GGUF model from Hugging Face if not already present."""
+    os.makedirs(LOCAL_MODEL_DIR, exist_ok=True)
+    local_path = os.path.join(LOCAL_MODEL_DIR, MODEL_FILE)
+    if os.path.exists(local_path):
+        print(f"[llm.py] Model GGUF already exists at {local_path}")
+        return local_path
+
+    print(f"[llm.py] Downloading {MODEL_FILE} from HF repo {MODEL_REPO}...")
+    try:
+        from huggingface_hub import hf_hub_download
+        downloaded_path = hf_hub_download(
+            repo_id=MODEL_REPO,
+            filename=MODEL_FILE,
+            local_dir=LOCAL_MODEL_DIR,
+            local_dir_use_symlinks=False
+        )
+        print(f"[llm.py] Model downloaded successfully to {downloaded_path}")
+        return downloaded_path
+    except Exception as e:
+        print(f"[llm.py] Error downloading model from Hugging Face: {e}")
+        return None
+
+def init_llama_cpp():
+    """Lazy initialization of llama_cpp model."""
+    global _llama_model
+    if _llama_model is not None:
+        return _llama_model
+
+    try:
+        from llama_cpp import Llama
+    except ImportError:
+        print("[llm.py] Warning: llama-cpp-python is not installed. Falling back to mock backend.")
+        return None
+
+    model_path = _download_gguf()
+    if not model_path or not os.path.exists(model_path):
+        print("[llm.py] Error: Model file not found. Cannot load llama_cpp.")
+        return None
+
+    print(f"[llm.py] Loading model into memory: {model_path}")
+    num_threads = 1 if os.environ.get("SPACE_ID") else 4
+    try:
+        _llama_model = Llama(
+            model_path=model_path,
+            n_ctx=2048,
+            n_threads=num_threads,
+            verbose=False
+        )
+        print("[llm.py] llama_cpp model loaded successfully!")
+        return _llama_model
+    except Exception as e:
+        print(f"[llm.py] Error loading llama_cpp: {e}")
+        return None
+
+# --- Whisper.cpp ASR (Speech-to-Text) ---
+_whisper_model = None
+
+def _init_whisper():
+    """Lazy initialization of whisper.cpp model for offline ASR."""
+    global _whisper_model
+    if _whisper_model is not None:
+        return _whisper_model
+    
+    try:
+        from pywhispercpp.model import Model as WhisperModel
+        print("[llm.py] Loading whisper.cpp 'tiny' model for ASR...")
+        _whisper_model = WhisperModel(
+            'tiny',
+            n_threads=2 if not os.environ.get("SPACE_ID") else 1
+        )
+        print("[llm.py] whisper.cpp ASR model loaded successfully!")
+        return _whisper_model
+    except ImportError:
+        print("[llm.py] pywhispercpp not installed. ASR will use mock fallback.")
+        return None
+    except Exception as e:
+        print(f"[llm.py] Error loading whisper.cpp ASR model: {e}")
+        return None
+
+def transcribe_audio(audio_path, prompt=""):
+    """
+    Transcribe audio file to text using whisper.cpp (offline, lightweight).
+    Falls back to mock transcription if whisper.cpp is unavailable.
+    """
+    if not audio_path or not os.path.exists(audio_path):
+        print("[llm.py] Audio file not found, using mock ASR.")
+        return _mock_transcribe_audio(prompt)
+    
+    whisper = _init_whisper()
+    if whisper is None:
+        print("[llm.py] whisper.cpp unavailable, using mock ASR fallback.")
+        return _mock_transcribe_audio(prompt)
+    
+    temp_wav_path = None
+    try:
+        try:
+            import miniaudio
+            import wave
+            print(f"[llm.py] Decoding and resampling audio to 16kHz mono WAV using miniaudio...")
+            sound = miniaudio.decode_file(audio_path, nchannels=1, sample_rate=16000)
+            
+            # Save to temp WAV file
+            temp_wav_path = audio_path + ".temp_16k.wav"
+            with wave.open(temp_wav_path, "wb") as wav_file:
+                wav_file.setnchannels(1)
+                wav_file.setsampwidth(2)  # 16-bit PCM
+                wav_file.setframerate(16000)
+                wav_file.writeframes(sound.samples)
+            
+            audio_path = temp_wav_path
+            print(f"[llm.py] Resampled audio saved to: {audio_path}")
+        except ImportError:
+            print("[llm.py] miniaudio not installed. Passing audio file directly to whisper.cpp.")
+        except Exception as e:
+            print(f"[llm.py] miniaudio transcoding failed: {e}. Passing original file directly.")
+
+        print(f"[llm.py] Transcribing audio: {audio_path}")
+        segments = whisper.transcribe(audio_path)
+        transcription = " ".join([seg.text.strip() for seg in segments]).strip()
+        
+        if temp_wav_path and os.path.exists(temp_wav_path):
+            try: os.remove(temp_wav_path)
+            except: pass
+            
+        if not transcription:
+            print("[llm.py] Whisper returned empty transcription, using mock fallback.")
+            return _mock_transcribe_audio(prompt)
+        
+        print(f"[llm.py] ASR Transcription: \"{transcription}\"")
+        return transcription
+    except Exception as e:
+        if temp_wav_path and os.path.exists(temp_wav_path):
+            try: os.remove(temp_wav_path)
+            except: pass
+        print(f"[llm.py] Error during whisper.cpp transcription: {e}")
+        return _mock_transcribe_audio(prompt)
+
+def _mock_transcribe_audio(prompt=""):
+    """Mock ASR fallback when whisper.cpp is not available."""
+    prompt_lower = str(prompt).lower() if prompt else ""
+    if "first" in prompt_lower or "injury" in prompt_lower or "ems" in prompt_lower:
+        return "How do I treat a sprained ankle on the trail?"
+    elif "gear" in prompt_lower or "backpack" in prompt_lower:
+        return "What gear list do I need for a 3-day high-altitude trek?"
+    else:
+        return "Am I on the correct route right now?"
+
+# Keep backward-compatible alias
+mock_transcribe_audio = _mock_transcribe_audio
+
+def generate_mock(prompt, system="", image_path=None, audio_path=None, history=None):
+    """Simulate streaming for the mock backend tailored for Trailhead."""
+    response = ""
+    
+    # 0. Handle Voice Audio ASR
+    if audio_path:
+        transcription = transcribe_audio(audio_path, prompt)
+        response += f"[🎙️ **Voice Journal Transcription:** \"{transcription}\"]\n\n"
+        prompt = transcription
+        
+    prompt_lower = prompt.lower()
+    
+    # 1. Checkpoint / Narration Queries
+    if "checkpoint" in prompt_lower or "narration" in prompt_lower or "current position" in prompt_lower:
+        response += (
+            "🧭 **Trailhead Contextual Guide:**\n"
+            "You are approaching **Km 2.0 Checkpoint**. The terrain ahead is moderately steep with an elevation gain of ~45m over the next kilometer.\n\n"
+            "⚠️ **Advisory:** Watch your water supply; the next reliable spring is at Km 3.5. Ensure you reach the shelter before 17:00 as temperatures drop rapidly to 5°C."
+        )
+    # 2. Gear Checklist Queries
+    elif "gear" in prompt_lower or "checklist" in prompt_lower or "pack" in prompt_lower:
+        response += (
+            "🎒 **Suggested Gear Checklist (Pace- & Altitude-Adjusted):**\n"
+            "Based on your 1-day trek details, here is a highly tailored packing guide:\n\n"
+            "- **Navigation:** Offline map download, compass, backup physical map.\n"
+            "- **Hydration:** 2.5L water capacity + iodine tablets (water sources tagged at Km 3.5).\n"
+            "- **Apparel:** Windbreaker/rain shell, moisture-wicking base layers, wool socks.\n"
+            "- **Safety:** First-aid kit (with blister care), whistle, multi-tool, space blanket.\n"
+            "- **Nutrition:** 2500 kcal high-density trail snacks (nuts, bars, jerky)."
+        )
+    # 3. Wilderness First-Aid / RAG Queries
+    elif "first-aid" in prompt_lower or "first aid" in prompt_lower or "medical" in prompt_lower or "injury" in prompt_lower or "sprain" in prompt_lower or "ams" in prompt_lower or "sick" in prompt_lower:
+        response += (
+            "🩹 **Wilderness First-Aid Protocol (CITED):**\n"
+            "For managing a **Sprained Ankle / Strain** in the backcountry, use the **R.I.C.E.** protocol:\n\n"
+            "1. **Rest:** Stop hiking immediately. Remove weight from the injured limb.\n"
+            "2. **Ice / Cold:** Apply a cold pack or submerge in cold trail stream for 20 mins to reduce swelling.\n"
+            "3. **Compression:** Wrap firmly with an elastic bandage (do not restrict circulation).\n"
+            "4. **Elevation:** Elevate the ankle above the heart level whenever resting.\n\n"
+            "📖 *CITED SOURCE: Wilderness Medicine Field Guide, Section 7: Musculoskeletal Injuries.*"
+        )
+    # 4. Off-Route / Deviation Queries
+    elif "route" in prompt_lower or "off-route" in prompt_lower or "deviate" in prompt_lower or "map" in prompt_lower:
+        response += (
+            "⚠️ **Navigation Warning:**\n"
+            "You have deviated from the planned polyline by **42 meters**. \n\n"
+            "**Action:** Look for physical trail markers or backtrack to your last known coordinate. Do not proceed off-trail through dense underbrush."
+        )
+    # 5. Default Response
+    else:
+        response += (
+            "🌲 **Welcome to Trailhead Navigation Assistant!**\n"
+            "I am your offline-first trail computer. I can analyze your uploaded GPX files, estimate Naismith trekking durations, auto-partition checkpoints, and offer grounded AI advice.\n\n"
+            "Ask me about gear checklists, route narration, deviation warnings, or wilderness first-aid emergency protocols."
+        )
+        
+    for word in response.split(" "):
+        yield word + " "
+        time.sleep(0.03)
+
+def generate_llama_cpp(prompt, system="", image_path=None, audio_path=None, history=None):
+    """Query the in-process llama-cpp-python model with a timeout fallback to mock."""
+    if getattr(generate_llama_cpp, "disabled", False):
+        print("[llm.py] llama_cpp is disabled (too slow or failed). Using mock backend.")
+        for chunk in generate_mock(prompt, system, image_path, audio_path, history):
+            yield chunk
+        return
+
+    acquired = _model_lock.acquire(blocking=True)
+    if not acquired:
+        print("[llm.py] Could not acquire model lock. Falling back to mock.")
+        for chunk in generate_mock(prompt, system, image_path, audio_path, history):
+            yield chunk
+        return
+
+    try:
+        start_time = time.time()
+        model = None
+        try:
+            model = init_llama_cpp()
+        except Exception as e:
+            print(f"[llm.py] Exception during init_llama_cpp: {e}")
+            
+        if model is None:
+            print("[llm.py] Fallback to mock backend.")
+            for chunk in generate_mock(prompt, system, image_path, audio_path, history):
+                yield chunk
+            return
+
+        init_duration = time.time() - start_time
+        if init_duration > 35.0:
+            print(f"[llm.py] Warning: Model loading took {init_duration:.2f}s (exceeded 35s limit). Disabling llama_cpp and falling back to mock backend.")
+            generate_llama_cpp.disabled = True
+            for chunk in generate_mock(prompt, system, image_path, audio_path, history):
+                yield chunk
+            return
+
+        voice_prefix = ""
+        if audio_path:
+            transcription = transcribe_audio(audio_path, prompt)
+            voice_prefix = f"[🎙️ **ASR Transcribed:** \"{transcription}\"]\n\n"
+            prompt = f"The hiker asked by voice: '{transcription}'. Respond directly to this query."
+
+        if image_path:
+            prompt = f"[📸 Image uploaded] {prompt}"
+
+        formatted_prompt = f"<|im_start|>system\n{system}<|im_end|>\n"
+        if history:
+            for msg in history:
+                role = msg.get("role", "user")
+                content = msg.get("content", "")
+                formatted_prompt += f"<|im_start|>{role}\n{content}<|im_end|>\n"
+        formatted_prompt += f"<|im_start|>user\n{prompt}<|im_end|>\n<|im_start|>assistant\n"
+        
+        print(f"\n--- [llama.cpp INPUT PROMPT] ---\n{formatted_prompt}\n--------------------------------")
+        print("--- [llama.cpp STREAMING RESPONSE] ---")
+        try:
+            response = model(
+                formatted_prompt,
+                max_tokens=512,
+                temperature=0.3,
+                top_p=0.9,
+                stream=True
+            )
+            
+            first_token_timeout = 30.0
+            response_iter = iter(response)
+            
+            first_chunk_start = time.time()
+            try:
+                first_chunk = next(response_iter)
+            except StopIteration:
+                first_chunk = None
+                
+            prefill_duration = time.time() - first_chunk_start
+            if prefill_duration > first_token_timeout:
+                print(f"[llm.py] Prompt evaluation took {prefill_duration:.2f}s (exceeded {first_token_timeout}s limit). Disabling llama_cpp and falling back to mock.")
+                generate_llama_cpp.disabled = True
+                for chunk in generate_mock(prompt, system, image_path, audio_path, history):
+                    yield chunk
+                return
+
+            if voice_prefix:
+                yield voice_prefix
+                
+            if first_chunk:
+                text = first_chunk['choices'][0]['text']
+                cleaned = text.replace("<|im_end|>", "")
+                print(cleaned, end="", flush=True)
+                yield cleaned
+
+            for chunk in response_iter:
+                text = chunk['choices'][0]['text']
+                cleaned = text.replace("<|im_end|>", "")
+                print(cleaned, end="", flush=True)
+                yield cleaned
+            print("\n--------------------------------------")
+        except Exception as e:
+            print(f"[llm.py] Error running llama.cpp: {e}. Falling back to mock.")
+            for chunk in generate_mock(prompt, system, image_path, audio_path, history):
+                yield chunk
+    finally:
+        _model_lock.release()
+
+def generate(prompt, system="", image_path=None, audio_path=None, history=None, stream=True):
+    """Entry point for LLM generation supporting text, image, and voice inputs."""
+    print(f"[llm.py] Using backend: {BACKEND}")
+    if BACKEND == "llama_cpp":
+        generator = generate_llama_cpp(prompt, system, image_path, audio_path, history)
+    else: # mock
+        generator = generate_mock(prompt, system, image_path, audio_path, history)
+        
+    if stream:
+        return generator
+    else:
+        res = ""
+        for chunk in generator:
+            res += chunk
+        return res