This is a submission for the Hacktoberfest Open-Source AI Challenge Week 2: Side Hustle
GhostRunner: An open-source, local-first audio drama engine that turns the real streets under your feet into the set of a thriller, and a one-laptop side hustle for anyone who wants to sell themed run and walking experiences.
GhostRunner is a generative audio companion for runners and walkers. You pick a genre (zombie escape, cyberpunk courier, spy exfiltration), a distance and an intensity. GhostRunner plans a route over real streets, finds the real landmarks along it, and writes an audio drama in which your surroundings are the set:
"Turn right onto Oak Street. See that old brick building on your left? That's where the drop is hidden."
Then you put your phone away and run. The right line plays at the right place, in a radio-dispatcher voice, just before the turn it describes. If you speed up, the tone turns urgent and a pursuer closes in. If you flag, the story hands you a breather. If you take a wrong turn, the dispatcher notices, re-routes you and rewrites the rest of the mission.
Three things make it more than a prompt wrapped around a map:
And it runs on a laptop with a 4 GB GPU.
The expensive part of an audio drama has always been making it. A writer, a voice actor and a studio for every route does not scale to "your neighbourhood". GhostRunner turns that into a few minutes of laptop time per route, and that makes a small one-person service possible. The unit of sale is a mission pack: a route, a compiled story and voiced audio, made once and replayed any number of times.
Who I think would pay for one:
demo_pois.json file) and a branded voice.
To be straight about where this stands: I haven't run a paid pilot or validated pricing, and today a saved mission replays from my own machine. The pieces that make it sellable (compile once, replay forever, no per-listener cost, landmarks and voice swapped per client) are built. Exporting a pack as a standalone bundle a customer's phone can play without my server is the next step.
Repository: https://github.com/Nishchal-29/GhostRunner
engine/ routing, chainage math, corridor POIs, tracker, trigger engine, pacing, safety
pipeline/ LangGraph compile_graph and runtime_graph
llm/ Ollama client (structured output)
audio/ TTS providers and clip cache
client/ mobile-first PWA (vanilla JS, Web Audio API, Leaflet)
tools/ LLM benchmark, GPX replayer, demo launcher
Run it locally:
conda activate agents-env
docker compose up -d # Valhalla (routing) + Postgres
python tools/setup_valhalla.py
ollama serve
python tools/demo.py # compiles a demo loop and starts the app
A story that plays late is wrong, and a story that invents landmarks is worse. A runner moves roughly 3 m/s. An LLM on a small GPU takes seconds per line, and text-to-speech adds more. If you generate reactively, the line about the clocktower arrives after you have passed it. And small models hallucinate confidently.
So I split the system by when work happens:
COMPILE (before and during the run)
Plan → Valhalla route → Overpass corridor POIs → route model (chainage)
→ Director (LLM, 1 call) → Beat planner → Beat writer (LLM, 3 variants/beat)
→ Validator → TTS pre-render (rolling window)
RUN (every tick, no LLM on the happy path)
GPS → pace classifier (TabPFN) → locate on route → trigger check → variant select → play
Two LangGraph graphs: compile_graph carries the heavy work, runtime_graph is a handful of deterministic nodes that finish in milliseconds. This split is also what makes the business model work: everything expensive happens once, at compile time, and the result is reusable.
I use Valhalla with pedestrian costing for routing. It returns an encoded polyline plus maneuvers with street names. I decode it (precision 6), project into the local UTM zone with pyproj, and densify to one point every ~5 m.
Everything on the route is then addressed by chainage: meters along the path. A turn is at 1,240 m. A fountain is at 1,310 m, on the left. This one choice does most of the work in the project:
Tx·Ly − Ty·Lx says left or right.[last_chainage − 30 m, last_chainage + 200 m] of the densified path, so loops and out-and-back routes can't snap the runner onto the wrong leg.
Some details I designed around, because they fail silently:
begin_shape_index is relative to each leg, so multi-leg routes need a running offset or every maneuver lands in the wrong place.D/4 is ~0.93·D before detours). I generate three candidate loops from waypoints at 60°/180°/300°, score them by distance error and self-overlap, and recalibrate the radius once if the first pass is off by more than 15%.
One Overpass query along a simplified (≤150 point) buffer of the route pulls historic sites, artwork, fountains, places of worship, named buildings, parks, waterways, bridges and steps. I score each by kind and distance from the path, then apply greedy non-maximum suppression so no two story landmarks sit within 150 m of each other. Results are cached per H3 cell in Postgres, so a second run makes no Overpass calls.
OSM coverage varies. When a route is landmark-poor, the story degrades gracefully into street names, turns, parks and water, and a hand-curated demo_pois.json can add landmarks. That file is also how a client's own landmarks (a club's meeting point, a hotel, a campus building) get into a pack.
Small models are unreliable at tool calling, and every tool-call round trip costs latency a runner can't spare. So all decisions are plain Python: which beat goes where, which landmark, what maneuver text, how far ahead to trigger. The LLM does two jobs only:
A validator enforces word count, an allowlist of landmark names, and safety rules (no crossing roads, no trespassing). On failure it retries once with the violation named, then falls back to a deterministic template.
The model sits behind a small LLMClient interface, so swapping it is a one-line config change. That matters for a business: a model or a price I depend on can change without breaking the product.
For each beat, the line should finish as the runner reaches the anchor. The engine dead-reckons position between 3-5 s GPS fixes and fires a beat when:
def due(beat, chainage_est, speed, variant):
dur = beat.duration_s.get(variant) or est_duration(beat.variants[variant])
lead_m = max(speed, 0.5) * (dur + 2.0) # finish speaking as the runner arrives
start_at = beat.anchor_chainage_m - lead_m
return start_at <= chainage_est < beat.expires_chainage_m
Durations come from the measured length of the rendered audio clip, so the lead distance is accurate to the clip. A priority queue (navigation > checkpoint > landmark > challenge > tension) plays one beat at a time, enforces a minimum gap between non-navigation beats, and skips expired ones.
I treat pace as a small tabular classification problem. Each tick builds features: rolling speed over 30 s / 2 min / 5 min, speed delta and variance, grade, time since last stop, and current speed relative to a personal baseline from the first two minutes. TabPFN classifies the runner as CRUISING, ACCELERATING, EXHAUSTED or STOPPED, with a 3-tick hysteresis filter so the story doesn't flip-flop. It runs on CPU, throttled to once every 5 s, leaving all VRAM to the LLM.
One honest caveat: there is no labeled dataset for this, so the training labels come from a transparent heuristic over simulated run profiles. TabPFN's value here is a fast, calibrated, retrain-in-seconds classifier. If it fails to load, a rules classifier takes over automatically.
ElevenLabs voices every line, rendered ahead of the runner through a rolling window of the next three triggers. Clips are content-addressed (sha256(voice + text)), so repeated lines are free. Reactive moments (off route, pick up the pace, checkpoint countdown) use a pre-rendered tier-C bank that plays from disk in under 50 ms while any dynamic line renders in the background. On the client, Web Audio adds a bandpass-and-distortion radio effect, and the ambient drones and sirens are synthesized procedurally, so there are no audio assets to ship.
I tried to be honest with myself about the unit economics, because "free" is rarely the whole story.
That shape is what makes a side hustle plausible: fixed cost per route, near-zero cost per run.
A mobile-first PWA with a briefing screen (route preview, premise, objectives, safety acknowledgement, headphone check), a countdown, a run HUD, and a debrief with a shareable card. Every compiled mission is saved, so any mission replays with the LLM, router and TTS all switched off. Wi-Fi at a venue, or a trail with no signal, is the one thing a demo or a customer can't count on, so a saved mission needs none of it.
Python, FastAPI, WebSockets, LangGraph (Postgres checkpointer), Valhalla, Overpass/OpenStreetMap, shapely, pyproj, H3, Ollama with an open-weight model ([model]), TabPFN, ElevenLabs, Sentry, Postgres, vanilla JS with the Web Audio API and Leaflet.
For a project someone might pay for, the open pieces decide whether the business works at all, not just whether it's a nice demo.
LLMClient interface and the voice is behind a TTSProvider interface, with a mock provider so the full pipeline runs with no vendor at all. I picked the model by benchmark, and I can re-pick it. If a provider changes pricing or retires a model, I change a config value, not the product.
I also want to be straight about the closed piece. Voice is ElevenLabs, because it was the best option for a convincing radio dispatcher and I wasn't going to pretend otherwise. It is isolated behind an interface and cached aggressively, so it is the one swappable, bounded cost instead of something the whole product depends on.
Best Use of ElevenLabs. Every line is voiced in a per-genre radio-dispatcher voice, with an optional second voice for the antagonist. Rolling pre-rendering, content-hash caching and measured clip durations are what let the audio land at the right place, and a pre-rendered reactive bank gives sub-50 ms responses to off-route and pace events.
Best Use of TabPFN. A TabPFN classifier turns streaming telemetry features into a runner state (cruising / accelerating / exhausted / stopped) that selects the story variant in real time, with hysteresis and a rules fallback.