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.