{"slug": "ghostrunner-turning-every-street-into-a-story", "title": "GhostRunner: Turning Every Street into a Story", "summary": "A developer built GhostRunner, an open-source, local-first audio drama engine that plans routes over real streets, identifies landmarks via Valhalla routing and Overpass POIs, and generates location-aware thriller narration that plays through a mobile PWA. The system splits work into a LangGraph compile graph (LLM story generation, beat writing, validation, TTS pre-rendering) and a millisecond-scale deterministic runtime graph, allowing it to run on a laptop with a 4 GB GPU. The developer positions it as a one-person side hustle selling themed mission packs, though no paid pilot or pricing validation has been done yet.", "body_md": "*This is a submission for the [Hacktoberfest Open-Source AI Challenge Week 2: Side Hustle](https://dev.to/challenges/hacktoberfest-week2-2026-10-12)*\n\n**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.*\n\nGhostRunner 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**:\n\n\"Turn right onto Oak Street. See that old brick building on your left? That's where the drop is hidden.\"\n\nThen 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.\n\nThree things make it more than a prompt wrapped around a map:\n\nAnd it runs on a laptop with a **4 GB GPU**.\n\nThe 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.\n\nWho I think would pay for one:\n\n`demo_pois.json` file) and a branded voice.\nTo 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.\n\n**Repository:** [https://github.com/Nishchal-29/GhostRunner](https://github.com/Nishchal-29/GhostRunner)\n\n```\nengine/     routing, chainage math, corridor POIs, tracker, trigger engine, pacing, safety\npipeline/   LangGraph compile_graph and runtime_graph\nllm/        Ollama client (structured output)\naudio/      TTS providers and clip cache\nclient/     mobile-first PWA (vanilla JS, Web Audio API, Leaflet)\ntools/      LLM benchmark, GPX replayer, demo launcher\n```\n\nRun it locally:\n\n```\nconda activate agents-env\ndocker compose up -d                 # Valhalla (routing) + Postgres\npython tools/setup_valhalla.py\nollama serve\npython tools/demo.py                 # compiles a demo loop and starts the app\n# open http://localhost:8000\n```\n\nA 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.\n\nSo I split the system by *when* work happens:\n\n```\nCOMPILE (before and during the run)\nPlan → Valhalla route → Overpass corridor POIs → route model (chainage)\n     → Director (LLM, 1 call) → Beat planner → Beat writer (LLM, 3 variants/beat)\n     → Validator → TTS pre-render (rolling window)\n\nRUN (every tick, no LLM on the happy path)\nGPS → pace classifier (TabPFN) → locate on route → trigger check → variant select → play\n```\n\nTwo 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.\n\nI 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.\n\nEverything 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:\n\n`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.\nSome details I designed around, because they fail silently:\n\n`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%.\nOne **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.\n\nOSM 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.\n\nSmall 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:\n\nA **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.\n\nThe 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.\n\nFor 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:\n\n``` python\ndef due(beat, chainage_est, speed, variant):\n    dur = beat.duration_s.get(variant) or est_duration(beat.variants[variant])\n    lead_m = max(speed, 0.5) * (dur + 2.0)           # finish speaking as the runner arrives\n    start_at = beat.anchor_chainage_m - lead_m\n    return start_at <= chainage_est < beat.expires_chainage_m\n```\n\nDurations 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.\n\nI 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.\n\nOne 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.\n\n**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.\n\nI tried to be honest with myself about the unit economics, because \"free\" is rarely the whole story.\n\nThat shape is what makes a side hustle plausible: fixed cost per route, near-zero cost per run.\n\nA 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.\n\nPython, 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.\n\nFor a project someone might pay for, the open pieces decide whether the business works at all, not just whether it's a nice demo.\n\n`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.\nI 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.\n\n**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.\n\n**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.", "url": "https://wpnews.pro/news/ghostrunner-turning-every-street-into-a-story", "canonical_source": "https://dev.to/nishchal-29/ghostrunner-turning-every-street-into-a-story-5g9o", "published_at": "2026-10-15 21:42:48+00:00", "updated_at": "2026-10-15 21:56:22.947286+00:00", "lang": "en", "topics": ["generative-ai", "large-language-models", "ai-agents", "ai-tools", "developer-tools"], "entities": ["GhostRunner", "Valhalla", "Overpass", "LangGraph", "Ollama", "TabPFN", "Nishchal-29", "GitHub"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/ghostrunner-turning-every-street-into-a-story", "markdown": "https://wpnews.pro/news/ghostrunner-turning-every-street-into-a-story.md", "text": "https://wpnews.pro/news/ghostrunner-turning-every-street-into-a-story.txt", "jsonld": "https://wpnews.pro/news/ghostrunner-turning-every-street-into-a-story.jsonld"}}