Resources/roadmap.md

# 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.