What I Built

TrailQuest is a screen-free, audio-guided outdoor exploration app designed for runners and walkers. Once you select your desired distance and preferences (parks, green spaces, landmarks), the backend generates a closed-loop route originating from your current location. It translates OSRM turn-by-turn navigation into spoken audio cues, keeping your attention off your phone and focused on your surroundings.

During each route, participants encounter interactive activities:

Visual Quests: Capture a photo of designated landmarks; an open-weight vision model validates presence and alignment.

Social Quests: Greet individuals encountered along the trail to earn completion points.

Navigation Accuracy: Maintain alignment with the generated route for consistency bonuses.

Audio feedback is available in two distinct styles: friendly encouragement or a humorous full_savage coach persona that highlights pace changes and schedules mid-route pauses. The landmark harvester is tailored for India, beginning with Kolkata.

Demo

Note: The hosted build operates in offline-fallback mode due to hosting constraints on static pages. The full architecture (routing engine, synchronisation, Hermes evaluation, and Gemma verification) operates locally via Docker Compose as outlined in the repository documentation.

Code

srinjoyeegoswami / TrailQuest

<<<<<<< HEAD

TrailQuest Backend & Agent Service

Screen-free, audio-guided outdoor exploration running platform powered by open-weight AI (Gemma), Hermes Agent, PostGIS, and OSRM. Built for the Hacktoberfest "Touch Grass" challenge.

Architecture Overview

Screen-Free Audio Guidance: Routes are compiled into natural-language speech prompts on the backend and voiced using device-native TTS with music ducking, keeping runners off their screens.
Dual Voice Profiles: Switchable between friendly and full_savage personas, including automatic pace-drop alerts and a halfway 2-minute fatigue break trigger (config/voice_profiles.json).
Offline-First Synchronization: Telemetry coordinates and quest photos are buffered on the device during runs with zero cellular dependency, then synced within 24 hours of reconnecting.
Open-Weight AI Pipeline: Gemma serves as the multimodal vision evaluator on DigitalOcean Serverless Inference / Ollama, orchestrated by Hermes Agent.
Two-Tiered Landmark Storage: Separates verified baseline locations (data/landmarks/curated_landmarks.json) from dynamically mined regional discoveries (data/landmarks/mined_landmarks.json).

Quickstart

…

View on GitHub

How I Built It

Open-Source AI Architecture

Gemma 3: Utilized via DigitalOcean Serverless Inference or local Ollama execution as a multimodal vision validation engine. It evaluates user-submitted photos against landmark attributes to yield structured JSON output (is_match, confidence, identified_objects, and coach feedback). Validations require a confidence score of $\ge 0.70$.

Hermes Agent: Handles evaluation orchestration through a custom skill module (route_and_quest_director) integrating three primary tools:

evaluate_run_navigation_accuracy: Computes PostGIS Hausdorff distance between planned and tracked paths (adherence target $\le 75\text{ m}$).
run_gemma_vision_verifier: Assesses visual submissions.
tally_quest_score: Aggregates distance points, route fidelity bonuses, visual confirmations, and social interactions.

Technical Stack

Backend: FastAPI, asyncpg, Shapely, Pydantic

Spatial Engine: PostgreSQL 16 with PostGIS, coupled with OSRM (foot profile)

Data Sourcing: Baseline registries augmented with OpenStreetMap (Overpass) queries and local recommendations, deduplicated within a 50-meter radius

Frontends: React, Vite, and Three.js interface alongside a React Native tracking application featuring GPS pathing

Infrastructure: Docker Compose orchestration for PostGIS and OSRM

Offline-First Architecture

GPS points and quest captures buffer locally during activity without requiring active cellular coverage. Once connectivity is restored, telemetry packages submit to /api/v1/sync/run-payload. The backend logs the raw payload, flags the session for review, triggers Hermes evaluation pipelines in the background, and updates the status to complete.

Why Does Open Innovation Matter?

Sustainable Economics: Vision verification per image remains cost-effective by executing Gemma across cost-efficient cloud compute or local Ollama instances rather than accumulating proprietary per-call API fees.

Inference Portability: The backend connects to either hosted endpoints or local Ollama deployments simply through configuration toggles, preventing lock-in to single-vendor API specifications.

Community Data & Tooling: OpenStreetMap and OSRM allow localized routing and point-of-interest discovery to expand into new areas without recurring geospatial map licensing fees.

Extensible Agent Design: Hermes skill declarations and tooling remain transparent, allowing straightforward auditing, extension of quest varieties, and addition of new audio personas.

DEV Community

TrailQuest: Screen-Free, Audio-Guided Outdoor Exploration with Gemma & Hermes