Tangier Explorer - Bringing Open-Source AI to the Alleyways of Tangier

#devchallenge #hf26challenge #gemma #ai

Screen Fatigue in the White City

When travelers and locals explore Tangier, a recurring pattern emerges: eyes glued to phone screens, blindly following generic mapping algorithms or crowdsourced listicles that lack local soul. In an ancient labyrinth like the Medina or Kasbah, mainstream maps often fail: GPS signals bounce off high white walls, cellular coverage drops in the narrowest alleyways, and generic AI recommendations feel sterile and disconnected from local culture.
Technology should encourage us to experience the world, not trap us behind glass. That is why I built Tangier Explorer for the Hacktoberfest Open-Source AI Challenge: Week 1 (Touch Grass).

What is Tangier Explorer?

Tangier Explorer is a 100% offline walking route generator tailored to the city of Tangier. Instead of relying on cloud APIs, it runs locally on a laptop using Google's Gemma 3 (4B) via Ollama.
The premise is straightforward:
Select your preferred vibe (History, Food, Hidden spots, Sea, Nature, Culture).
Choose your available duration (1 hour, 2 hours, or a half-day).
Tangier Explorer builds a personalized walking tour with an authentic Tangier local persona ("Tanjaoui"), giving you the exact path, estimated walking times, and historical context. Once generated, download the route, close your laptop and start walking.

Demo

Here is how the interface looks using Gradio:

)
The interface is designed to be minimal: pick your vibe, choose your time, click generate, and step outside.

How It Works: "Data is Truth, Gemma is Storyteller"
To avoid hallucinations while preserving creative narrative generation, I split the architecture into two distinct responsibilities:
Deterministic Ground Truth (spots.json): A curated database of 148 verified locations across Tangier (Kasbah, Marshan, Perdicaris Forest, Cap Spartel, Grand Socco). Each entry includes name, neighborhood, category, and curated descriptions.
Context Filtering: When a user selects a vibe, the app filters relevant spots locally and passes them into the prompt.
Local Inference with Gemma 3 (4B): Gemma receives the filtered subset alongside a strict system prompt instructing it to act as an authentic local guide. Gemma structures the walking route, calculates transitions, and injects local flavor without inventing fictitious landmarks.

import json
import gradio as gr
import ollama

# 1. Load curated dataset
with open("spots.json") as f:
    SPOTS = json.load(f)

SYSTEM = """Nta guide touristique tanjaoui 9dim, katfhem bzzaf f Tanja w katdwi b Darija tanjawiya drayfa.
3ti l'user circuit mtiye9, w 9ol lih fin ymchi khatwa b khatwa 3la 7ssab l'we9t w l'vibe li khtar, w sta3mel ghir l'amakin li m3tayin lik."""

def build_route(vibe, duration):
    filtered = [s for s in SPOTS if s["category"] == vibe]
    spots_text = "\n".join(
        f"- {s['name']} ({s['area']}): {s['description']}"
        for s in filtered[:30]
    )
    user_msg = f"Vibe: {vibe}\nDuration: {duration}\nUse ONLY these spots:\n{spots_text}\n\nBuild my walking route!"

    response = ollama.chat(
        model="gemma3:4b",
        messages=[
            {"role": "system", "content": SYSTEM},
            {"role": "user", "content": user_msg},
        ],
    )
    route = response["message"]["content"]
    with open("route.md", "w") as f:
        f.write(f"# Tangier Explorer - {vibe} ({duration})\n\n" + route)
    return route, "route.md"

Taking Tangier Explorer Outside

In the spirit of the "Touch Grass" theme, I tested the app on the ground in Tangier: walking a generated circuit, following the downloaded route where mobile data signal drops.
What worked well:
Zero latency and no signal anxiety: running Gemma locally meant generating the plan without worrying about 4G coverage inside thick stone walls.
Narrative quality: Gemma 3 produced concise transitions between stops and captured the authentic rhythm of walking through the Kasbah.
What needed tuning:
Time estimation: the model initially packed too many steep uphill segments into a 1-hour walk. Restricting the prompt to fewer candidate spots fixed pace expectations significantly.

Why Open-Source AI Matters

This project demonstrates why open-weight models are vital for real-world utility:
Zero internet requirement: ideal for outdoor exploration, remote hiking, and dense historic districts where mobile network connectivity is unreliable.
Privacy by default: travel patterns, interests, and schedules remain entirely on the local device without tracking or central data aggregation.
Accessible and extensible: free from recurring API billing or credit exhaustion. Anyone can fork the repository, swap spots.json with their own hometown data, and create an instant offline walking guide for any city in the world.

Prize Categories

I am submitting this project for:
Hacktoberfest Open-Source AI Challenge: Week 1 (Touch Grass)
Best Use of Gemma ($200 Featured Partner Category): leveraging Google's Gemma 3 4B locally via Ollama to create an edge-ready cultural walking guide.

Links and Code

GitHub repository: https://github.com/SoufianeZaari/tangier-explorer
Model: Google Gemma 3 (4B) via Ollama

DEV Community