TrailPacer AI — An Offline, Privacy-First Outdoor Pacing Engine

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 1: Touch Grass

What I Built

TrailPacer AI is an offline-first, local AI outdoor workout companion designed to do one thing ruthlessly well: get you off your screen and out into the dirt in under 15 seconds.

Modern fitness apps often demand constant screen time—tracking infinite metrics, loading social feeds, and requiring reliable cellular connectivity that disappears the moment you hit a real trail.

TrailPacer AI flips this dynamic. It leverages lightweight open-weight models running 100% locally on your machine to synthesize structured, phased outdoor workouts (Trail Walk, Fartlek Run, Rucking, and Interval Sprints) in under 3.5 seconds.

Once generated, TrailPacer switches to an outdoor Heads-Up Display (HUD) with high-contrast timers, target RPE (Rate of Perceived Exertion) gauges, terrain cues, and offline audio chimes—allowing you to pocket your phone, listen for pace transitions, and focus on the trail ahead.

---

Demo

• Local Web UI & Companion Pacer: Runs locally at http://localhost:8000 with 0 external cloud dependencies.
• Speed to Trail: Under 15 seconds from launching the app to lacing up your shoes.
• Offline Audio Cues: Embedded Web Audio API chimes signal phase changes without requiring screen checks.

(Include your repo link, screenshots of the dashboard and HUD pacer, or a quick Loom / GIF demo here)

---

Code

ankan2526 / TrailPacer-AI

TrailPacer AI 🌲🏃‍♂️

TrailPacer AI is an offline outdoor workout companion powered by local AI. It synthesizes structured, adaptive training sessions for trail runners, hikers, and outdoor fitness enthusiasts in under 5 seconds—with zero internet connectivity required and minimal screen interaction time (< 15 seconds).

---

✨ Features

• 100% Offline: Runs completely on your device using open-weight local models (Llama 3.2 via Ollama). No cloud servers, no subscriptions, and absolute privacy.
• Fast Generation: Generates complete phased workouts in under 5 seconds on modern laptops and Apple Silicon.
• Structured Phases: Every session is broken down into structured warmup, main effort, and cooldown blocks with target RPE (Rate of Perceived Exertion) and terrain cues.
• Built-in Offline Resilience: Automatically serves pre-calibrated workouts from local cache if the AI model is offline or busy.

---

🏃 Supported Activities

• Trail Walk (trail_walk): Low-impact aerobic power walking and recovery hikes on variable terrain.
• Fartlek Run…

View on GitHub

Key Project Architecture:

• specs/: Formal JSON Schema contracts (workout_schema.json), functional requirements, and pre-compiled fallback caches.
• src/agent.py: Local LLM prompt harness with temperature-constrained retry loops (0.1) and grammar-based structured schema enforcement.
• src/validator.py: Strict schema validation engine.
• src/app.py & src/static/: Vanilla zero-dependency dark-mode outdoor HUD with real-time audio chimes.
• tests/test_workout_spec.py: Automated compliance test suite ensuring 100% schema adherence.

---

How I Built It

TrailPacer AI was developed using Spec-Driven Development (SDD):

1. The Contract First (specs/workout_schema.json): Defined a rigid Draft-07 JSON Schema enforcing activity types, phased duration blocks (warmup, main set, cooldown), target RPE ratings (1–10), and terrain suggestions.
2. Local Inference Engine: Powered by Ollama running open-weight quantized models (qwen2.5:0.5b for ultra-fast ~3s inference on CPU/Apple Silicon, with seamless configuration support for llama3.2:1b / llama3.2:3b).
3. Grammar-Constrained Structured Output: Instead of unconstrained generation, the schema is passed directly into Ollama's format parameter, leveraging GBNF grammar sampling to mathematically guarantee valid JSON output.
4. Resilience & Fallback Layer: If an inference daemon times out or fails schema validation, the agent automatically triggers a constrained retry at temperature=0.1. If offline without an active model server, it transparently serves verified, pre-cached routines from disk without breaking the runner's flow.
5. Zero-Dependency Companion Web App: A clean Python standard library HTTP server paired with a high-contrast outdoor UI (Vanilla HTML/CSS/JS) featuring Web Audio API chimes for auditory pacing.

---

Why Does Open Innovation Matter?

Open innovation is what makes TrailPacer AI possible. Here's why closed APIs couldn't solve this:

1. Trails Don't Have Cell Towers: Closed proprietary AI APIs (OpenAI, Claude, etc.) require an active internet connection. If you're at a remote trailhead, high in the mountains, or traveling in airplane mode, closed APIs are useless. Open-weight models run 100% offline directly on user hardware.
2. Zero Surveillance & True Privacy: Health and outdoor fitness data belongs to the athlete. Running open-source models locally guarantees zero telemetry, zero analytics tracking, and zero subscription paywalls.
3. Instant Latency: By pairing small open-weight models (qwen2.5:0.5b) with local quantization, workout generation takes ~3 seconds—faster than waiting for an API roundtrip over a spotty LTE connection.

Open-source AI transforms generative models from cloud services into dependable, local utility software that empowers people in the physical world.