---

Hacktoberfest Open-Source AI Challenge Week 1: Touch Grass Submission 🌿

Trailhead: a hiking planner that works where the internet doesn't

Two months ago I stood at a trailhead with one bar of signal, a dead
cloud-AI app spinning on "thinking…", and a paper map I couldn't read in
the wind. The chatbot that happily plans my week in the city is a brick
exactly where I need it most: outside.

So for Week 1 I built Trailhead — a hiking trip planner that runs a
real open-weight model entirely on your own machine. No API key, no
signal required, no per-query meter running. You tell it where you are,
how far you want to walk, and who's coming; it gives you a route, a gear
checklist, timing, and safety notes — generated locally, on the trailhead
bench, with zero bars.

The screen is the shortest part of the experience. That's the whole point.

Repo: https://github.com/muse-quest/trailhead

What it does

$ trailhead plan --near "Centereach, NY" --distance 6 --group "2 adults, 1 dog"

✓ Found 1 matching trail(s) (offline dataset)
✓ Selected: Blydenburgh County Park - Stump Pond Loop (6.1 mi, easy)

⚠ Ollama not reachable at localhost:11434 — using offline template (no LLM).
✓ Plan generated in 0.00s (engine: offline-template)

## Your hike: Blydenburgh County Park - Stump Pond Loop
**Distance:** 6.1 mi loop · **Elevation:** ~177 ft · **Est. time:** 3h 02m (conservative; add breaks)

## Route
1. Start at the Smithtown trailhead — arrive before 9 AM on weekends; lots fill.
2. Walk the loop in whichever direction the blazes suggest at the trailhead; loops need no shuttle and you finish at your car.
3. Features along the way: lake, historic mill, dog-friendly, bridle path.
4. Note: Loop around Stump Pond past the 1798 mill district; mostly flat dirt/sand with some roots. Dogs on leash.

## Timing
- Moving estimate: 3h 02m (conservative; add breaks) at a conservative pace.
- Start early enough to finish with 1 hour of daylight to spare.
- I don't have current trail-closure or hunting-season data — check the park office before you go.

## Gear checklist
- [ ] Water: at least 0.5 L per person per hour of hiking (more in heat)
- [ ] Sturdy closed-toe shoes — some sections have roots and rocks
- [ ] Tick protection: long pants, repellent, full tick check after
- [ ] Charged phone + a downloaded offline map (this planner works offline; maps should too)
- [ ] Snacks, small first-aid kit, rain layer
- [ ] Dog: leash (required), water + collapsible bowl, poop bags, tick preventative

## Safety notes
- Tell someone your route and expected return time.
- Long Island trails mean ticks: check yourself (and the dog) thoroughly after.
- If thunderheads build, turn back — no summit is worth lightning.
- Carry more water than you think you need; there is no potable water on-trail.

## Leave No Trace
- Pack out everything, including dog waste bags — don't leave them 'for later'.
- Stay on marked trail; the pine barrens and wetlands recover slowly.

_Generated offline with the built-in template (no LLM reachable). Install Ollama and pull a model for AI-generated plans._

Above: real terminal output from a verified run (Oct 5, 2026). No Ollama
daemon was available in the build environment, so this run exercised the
built-in offline template — the entire pipeline (CSV retrieval, filtering,
ranking, plan assembly) ran with zero network access, which is the point.

Trailhead is a small Python CLI with three moving parts:

• Retrieval (planner.py) — filters a bundled offline trail dataset (data/trails.csv: name, town, distance, elevation gain, difficulty, features like "dog-friendly" or "lake") against your constraints. No network call. This grounds the model in real trails instead of letting it hallucinate trailheads.
• Generation (model.py) — a thin wrapper around Ollama's local HTTP API that feeds the filtered trails plus your parameters into a local open-weight model and returns a structured markdown plan: route, timing estimate, gear checklist, safety notes, and Leave No Trace reminders. If no Ollama daemon is reachable, it falls back to a built-in deterministic template (clearly labeled) so the CLI never bricks offline.
• Prompting (prompts.py) — a system prompt that bakes in hiking sense: conservative timing estimates, explicit uncertainty ("I don't have current trail-closure data — check the park office"), and a bias toward telling you what to bring, not just where to walk.

The model is swappable with one flag (--model qwen2.5); the dataset is
a CSV you can extend with your own local knowledge. Nothing phones home.

The open-source AI at its core

Trailhead's brain is an open-weight model running locally through Ollama.
That isn't a deployment detail — it's the entire reason the project
exists:

1. It works with no signal. This is the load-bearing feature. A closed API model is unavailable precisely where a hiking planner is useful. Local inference turns "no bars" from a failure mode into the normal operating condition.
2. Your location data stays yours. A hiking planner ingests where you are, when, and with whom — a tidy little surveillance dossier. Running the model on-device means that data never crosses a network boundary.
3. It costs nothing per query. Re-plan the hike four times while your coffee cools. A metered API makes you ration curiosity; a local model makes iteration free.
4. You can change its mind. Don't like the default model's judgment on difficulty ratings? Swap the weights, edit the system prompt, add your region's trails to the CSV. Try doing that with a closed endpoint.

Why open innovation matters here

The prompt asks where the open approach worked better than a closed
one, so let me be specific about the design constraint. A hiking planner is
needed exactly where cloud AI is unavailable: the trailhead with no bars.
A closed-API version of this tool would be a design contradiction —
unavailable precisely where it's useful. Trailhead's pipeline (offline
retrieval plus a local model, with a built-in template fallback) answers
with zero network round-trips: in the verified run above, the full plan
generated in under a second with nothing but localhost available.

Open weights don't just make Trailhead cheaper or more private, although
they're both. They make the core scenario possible. The closed
alternative isn't a worse hiking planner; it's a hiking planner that
doesn't work while hiking. When your product's core scenario is "no
infrastructure," depending on someone else's infrastructure is the bug —
and only open models resolve it.

There's a second, quieter win: inspectability. When the model
suggests a route, I can read the exact prompt that produced it, diff it
against yesterday's prompt, and version-control the whole reasoning
pipeline next to the code. With a closed model, the most important part
of my application would be a black box I rent by the token.

Demo

Real terminal output from verified runs (Oct 5, 2026, zero network access).
The full plan run is shown in "What it does" above; here's the dataset
browser:

$ trailhead list --region Suffolk --max-distance 3

11 trail(s) in offline dataset:

1. West Hills County Park - Jayne's Hill — Huntington (Suffolk Co.)
   2.8 mi out-and-back, 350 ft gain, moderate 🐕
   Climb to Jayne's Hill (401 ft), the highest natural point on Long Island, via the Walt Whitman Trail.

2. Sunken Meadow State Park - Bluff & Boardwalk — Kings Park (Suffolk Co.)
   2.5 mi loop, 150 ft gain, easy 🚫🐕
   Boardwalk plus bluff trails overlooking the Sound. No dogs on trails.

[... 8 more trails ...]

11. Terrell River County Park - Wetlands Loop — Center Moriches (Suffolk Co.)
   2.8 mi loop, 60 ft gain, easy 🐕
   Wetland loop with bay views. Dogs on leash.

What's verified and what isn't (honesty section, because the
challenge grades technical execution):

• ✅ Offline retrieval, filtering, ranking, and plan assembly: exercised end-to-end in the runs above.
• ✅ Ollama client HTTP layer (GET /api/tags, POST /api/generate, request/response format, unreachable-daemon fallback): verified against a mock Ollama API plus the real "daemon not reachable" path, which degrades gracefully to the labeled offline template.
• ⚠️ No live LLM inference in the build environment: the box had ~1 GB of free RAM — not enough to load even a 1B model — so the demo plans above used the built-in offline template (the CLI says so on screen). The --model flag is real and swappable (--model qwen2.5 is accepted and would be used when a daemon has that model); the model simply wasn't there to call. On a laptop with Ollama running, plan uses the local model with no code changes.
• Timing: the offline-template plan generated in under a second. I make no timing claims for local LLM inference — that depends on your model and hardware.

How it was built

Full disclosure, since the challenge explicitly welcomes it: this project
was built with AI agent assistance — scaffold, code, prompts, dataset
curation, and this write-up were all produced working with an AI coding
agent, with a human directing architecture and verifying outputs. The
model that powers Trailhead, though, is 100% open weights running
locally. The irony is intentional: it takes a cloud-scale model to build
the thing that frees you from cloud-scale models.

What's next

• Expand the bundled dataset (crowdsourced regional CSVs, OpenStreetMap extracts with an offline tile cache for simple route maps).
• A --checklist-only mode for the parking lot: gear list in 10 seconds.
• Fine-tune a small model on trail-guide text for better local advice.

If you hike: try it, break it, tell me what your local trails need.
The screen should be the shortest part of your hike — Trailhead just

makes sure it's a useful one.