Ranno.ai

No Human is Limited.

Comment

The Ranno.ai Journey: Building a Smarter, Safer Run

What Sparked the Idea: Beyond the Beaten Path

The seed of Ranno.ai was deeply personal, planted during my own marathon preparation journey while studying at UC Berkeley. I remember countless training runs where the aspiration for a smooth, consistent pace would inevitably be shattered by Berkeley's relentless north-side hills. Every planned route felt like a gamble – a constant struggle to find genuinely flat terrain amidst the beautiful but challenging topography. The experience of constantly having my run “ruined” by unexpected inclines, or struggling to find routes that genuinely matched my training needs, was incredibly frustrating.

This personal struggle highlighted a critical gap: existing running apps, while great for logging miles or finding popular routes, often miss the human element. They tell us where to run, but rarely how we want to run, or more crucially, how safely we can run.

Imagine this: It's late evening, you're in a new city, eager for a refreshing 5k. You open your favorite app, and it suggests a route – perhaps along a major road, or through an area you know nothing about after dark. You crave a "quiet, well-lit path with some greenery, avoiding heavy traffic, and definitely safe," but expressing this feels like talking to a wall. You end up compromising, or worse, worrying about your safety.

This common frustration, coupled with the exciting emergence of on-device AI, became our muse. We envisioned a world where your running app truly listened to you, understood your nuanced preferences, and actively protected you. That's the dream Ranno.ai was born from.

The Architecture of Intelligence: How We Built It

Building Ranno.ai was like constructing a bridge between human intuition and machine precision. Our core idea was to translate the messy beauty of natural language into actionable, structured data that our mapping engine could understand.

The "Brain" (AI Intent Parser)

The heart of Ranno.ai is its Natural Language Understanding (NLU), powered by Chrome's experimental Prompt API with Gemini Nano. This was our first frontier. We didn't just want to pull out keywords; we aimed for deep comprehension.

We designed a robust RunGeniusIntent (our V2 JSON schema) – a detailed blueprint for every possible running preference: location context, distance_km, incline preference, surface type, safety requirements (like prefer_well_lit_streets), environment (e.g., prefer_shaded_paths), scenery (e.g., water_view), and even amenities like has_restrooms. The challenge was to craft a systemPrompt that could reliably coax Gemini Nano to populate this complex JSON from a simple user sentence.

The "Body" (Mapping & Routing)

Once Gemini Nano provided the structured intent, the next step was to bring it to life on a map. This is where Google Maps JavaScript API comes in. Using services like Directions Service and the Geometry Library, we plan to dynamically generate routes that adhere to every parsed constraint. This isn't just A to B; it's A to B via a specific type of terrain, avoiding certain areas, and including others.

The "Shield" (Safety & Amenities Layer)

Safety isn't an afterthought; it's foundational. We integrated publicly available data APIs for San Francisco crime statistics and amenities (bathrooms/water fountains). This allows us to overlay a dynamic safety heatmap on the map and, critically, to programmatically steer routes away from high-risk zones and towards desired facilities. It's about empowering runners with information and proactive protection.

The "Interface" (Frontend Experience)

All this intelligence is wrapped in a responsive and intuitive React (Vite) frontend with TypeScript. This ensures a snappy user experience and robust code quality, making the complex backend feel effortlessly simple to the user.

Lessons Learned: Navigating the Experimental Frontier

This project has been a masterclass in working with experimental technology and the art of prompt engineering.

  • Embracing the Experimental: Integrating Chrome's Prompt API was a journey through uncharted territory. We learned the nuances of chrome://flags, chrome://on-device-internals, and the delicate dance of user activation for on-device model downloads. It required persistence and a deep dive into browser-side AI paradigms.
  • The Nuance of Prompts: We quickly realized that talking to an AI is an art form. Crafting effective systemPrompt instructions for Gemini Nano to consistently output our precise RunGeniusIntent JSON was a continuous loop of trial, error, and refinement. We learned about clarity, specificity, and handling ambiguity in AI communication.
  • Data Integration Complexities: Merging disparate data sources – Google Maps' geographical data with city-specific crime and amenity APIs – presented fascinating challenges in data synchronization and spatial analysis.
  • The Power of On-Device AI: We gained immense appreciation for the privacy and performance benefits of on-device AI. Processing natural language locally, rather than sending it to a remote server, significantly enhances user trust and reduces latency.

Challenges Faced: Taming the Unknown

Like any ambitious project, Ranno.ai presented its share of formidable challenges:

  1. Gemini Nano Setup & Stability: This was by far the steepest initial climb. Getting the experimental Prompt API to reliably detect and download the Gemini Nano model across different Chrome Canary builds was a puzzle. We encountered:

    • Uncaught SyntaxError from missing export keywords.
    • "White screen of death" issues due to subtle JSX compilation errors.
    • API unavailability ("LOADING..." stuck states) requiring deep dives into browser internals.
    • Solving these required meticulous debugging, understanding Vite's compilation process, and a strong understanding of the browser's AI runtime.

  2. Prompt Engineering Precision: Achieving a high degree of accuracy for our RunGeniusIntent was, and continues to be, an iterative process. Users can express the same need in countless ways. Ensuring Gemini Nano consistently parses "flat roads," "no hills," and "gentle inclines" all into "incline": "low" is a continuous challenge. This involves:

    • Designing robust JSON schemas.
    • Crafting clear, unambiguous systemPrompt instructions.
    • Anticipating and testing for edge cases and synonyms.

  3. Hybrid Routing Complexity (Upcoming): The next major challenge lies in translating the rich RunGeniusIntent into a dynamic Google Maps route that simultaneously satisfies distance, incline, surface, safety, and amenity preferences. This will involve:

    • Sophisticated pathfinding algorithms.
    • Real-time spatial analysis of crime and amenity data.
    • Balancing conflicting preferences (e.g., "shortest distance" vs. "safest route").
    • We anticipate leveraging Google Maps' Directions Service along with custom geometry calculations to achieve this.

  4. Data Harmonization: Integrating disparate data sources (crime data, amenity data) with Google Maps' rich geospatial information for a unified safety and feature layer.

Conclusion: Our Vision for the Future

Building Ranno.ai has been an exhilarating journey into the future of personalized, privacy-first AI applications. We believe this project showcases the immense potential of on-device AI to solve real-world problems in intuitive and user-centric ways. We're excited to continue refining Ranno.ai, empowering every runner to find their perfect, safe path.

Built With

Share this project:

Updates