Hugging Face's logo

Spaces:
parthmax
/
SaarthiAI
Sleeping

App Files Community
SaarthiAI / README.md
parthmax24's picture
parthmax24
working proto 5
8b96826
preview code
|
Raw
History Blame Contribute Delete
10.5 kB
metadata 
title: Saarthi AI
emoji: πŸš—
colorFrom: indigo
colorTo: green
sdk: docker
app_port: 7860
pinned: false

πŸš— Saarthi AI

Proactive Commute Planning Agent for Lucknow, India

Stop reacting to traffic. Start predicting it.

Live Demo GitHub Hackathon Track

Built for the Google Cloud Rapid Agent Hackathon Β· MongoDB Partner Track

The Problem

Every Lucknow commuter knows the feeling: you check Google Maps at 8:25 AM, it says 28 minutes, you leave β€” and arrive 40 minutes late because of a Bada Mangal bhandara that blocked the lane, rain you didn't account for, and a last-minute diversion near Hazratganj.

Navigation apps are reactive. Saarthi is proactive.

Google Maps Saarthi AI
"Take this route, 28 min" "Leave by 8:10 AM or you'll be 18 min late"
Real-time, reactive Predictive, before you leave
Shows current traffic Simulates route at 6 future departure times
No local event awareness Knows Bada Mangal, Muharram, IPL match days
No memory Remembers your past commutes, learns your patterns

What Saarthi Does

  1. Simulates your route at multiple departure times β€” uses TomTom's departAt API to generate a full ETA curve (8:00, 8:15, 8:30, 8:45 AM) and finds the last safe departure window
  2. Layers in every risk factor in parallel β€” live traffic, rain forecast, Lucknow festivals, public events, and police advisories, all gathered simultaneously
  3. Synthesizes a verdict with Gemini via Google ADK β€” risk score (0–100), recommended leave-by time, and a plain-language explanation of why
  4. Remembers your history in MongoDB Atlas β€” every commute result is stored; the agent can answer "which day is worst for my Charbagh run?" from real data
  5. Lets you ask follow-up questions β€” a full tool-calling agent powered by Google ADK + MongoDB MCP server answers anything about your route

Tech Stack

Layer Technology
Agent Framework Google ADK 2.x (google-adk) β€” LlmAgent + InMemoryRunner
LLM Gemini 2.5 Flash (primary) Β· Groq Llama-3.3-70b (fallback)
Partner Integration MongoDB Atlas Β· MongoDB MCP Server (@mongodb-js/mongodb-mcp-server)
Traffic TomTom Routing API β€” departAt sweep for ETA curve
Weather Open-Meteo (free, no key)
Festivals / Events Calendarific API + curated Lucknow calendar + Ticketmaster
Geocoding TomTom + Geoapify (Lucknow-biased, handles local acronyms)
Police Advisories DuckDuckGo HTML scraping β€” no key needed
Backend FastAPI + Python 3.11 Β· Server-Sent Events for live streaming
Frontend Jinja2 + Vanilla JS + Leaflet.js (OpenStreetMap)
Deployment Hugging Face Spaces (Docker)

Architecture 

User: "Reach Hazratganj from Gomti Nagar by 9:30 AM"
                    β”‚
        β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
        β”‚   Google ADK Agent     β”‚  ← Gemini 2.5 Flash
        β”‚   (LlmAgent + Runner)  β”‚  ← 9 tools available
        β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                    β”‚ parallel fan-out
     β”Œβ”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
     β–Ό      β–Ό       β–Ό       β–Ό          β–Ό
  Traffic Weather Festivals Events  Advisories
 (TomTom (Open-  (Calenda- (Ticket- (DDG scrape)
 departAt Meteo)  rific +   master)
  sweep)          curated)
     β””β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                    β–Ό
          Risk formula (deterministic, auditable)
          traffic(40) + rain(20) + festival(20)
          + events(15) + advisories(10) = 0–100
                    β–Ό
          Gemini synthesis β†’ JSON verdict
          risk_score Β· leave_by Β· factors Β· tips
                    β–Ό
          MongoDB Atlas ← saved to commute_history
                    β–Ό
          SSE stream β†’ browser
          Risk gauge Β· Map Β· ETA curve Β· Agent chat

MongoDB Integration (Partner Track)

Saarthi uses MongoDB Atlas for two purposes:

  • api_cache β€” TTL collection replacing SQLite; auto-expiry via index prevents hammering paid APIs
  • commute_history β€” every plan result is stored; the ADK agent queries this via the MongoDB MCP Server to answer questions like "Which day is worst for my commute to KGMU?" from real historical data

The agent has 3 Python history tools (get_route_history, get_route_patterns) plus direct Atlas access via MongoDB MCP β€” so it can run arbitrary find and aggregate queries against your stored commutes.

Demo Scenarios (try these)

1 Β· Bada Mangal Tuesday (most dramatic)

  • From: Gomti Nagar Β· To: Hazratganj Β· Arrive by: 9:30 AM
  • Any Tuesday in June 2026 (2nd, 9th, 16th, 23rd)
  • Festival factor dominates the risk score β€” agent explains bhandara road blocks

2 Β· Morning Station Rush

  • From: Indira Nagar Β· To: Charbagh Railway Station Β· Arrive by: 9:00 AM
  • Classic departure-curve demo β€” leaving 20 min later costs 40 min of delay

3 Β· Match Day Traffic

  • From: Hazratganj Β· To: Ekana Cricket Stadium Β· Arrive by: 7:00 PM
  • Detects IPL match, warns about Ekana area gridlock

4 Β· Ask the Agent (chat)

After running a plan, try asking:

  • "What if I leave 30 minutes later?"
  • "Is there a faster route avoiding Faizabad Road?"
  • "Which day this week has the lowest risk for this trip?" ← queries MongoDB history

Local Setup 

# 1. Clone
git clone https://github.com/parthmax2/saarthi-ai.git
cd saarthi-ai

# 2. Install
pip install -r requirements.txt

# 3. Configure
cp .env.example .env
# Edit .env with your API keys (see table below)

# 4. Run
uvicorn main:app --reload

# 5. Open
# http://127.0.0.1:8000

Required API Keys

Key Where to get Free tier
GEMINI_API_KEY aistudio.google.com βœ… Yes
TomTom_api_key developer.tomtom.com βœ… 2,500 req/day
MONGODB_URI cloud.mongodb.com (M0 free cluster) βœ… Forever free
GROQ_API_KEY console.groq.com βœ… Yes (LLM fallback)
calendarific_api_key calendarific.com βœ… 1,000/month
Geoapify_API myprojects.geoapify.com βœ… 3,000/day
Ticketmaster_API developer.ticketmaster.com βœ… Yes

The app degrades gracefully β€” only GEMINI_API_KEY + TomTom_api_key + MONGODB_URI are required to run.

Run Tests 

pytest tests/ -v
# All 14 test files, fully mocked β€” no network calls, no API keys needed

Project Structure 

saarthi-ai/
β”œβ”€β”€ main.py                    # FastAPI entry point
β”œβ”€β”€ app/
β”‚   β”œβ”€β”€ agents/
β”‚   β”‚   β”œβ”€β”€ adk_agent.py       # Google ADK LlmAgent + MongoDB MCP toolset
β”‚   β”‚   β”œβ”€β”€ orchestrator.py    # Planning pipeline (parallel data gather + history save)
β”‚   β”‚   β”œβ”€β”€ synthesizer.py     # Risk formula β†’ Gemini β†’ structured verdict
β”‚   β”‚   └── prompts.py         # System prompts
β”‚   β”œβ”€β”€ tools/
β”‚   β”‚   β”œβ”€β”€ traffic.py         # TomTom departAt sweep ← star tool
β”‚   β”‚   β”œβ”€β”€ weather.py         # Open-Meteo
β”‚   β”‚   β”œβ”€β”€ festivals.py       # Calendarific + curated Lucknow calendar
β”‚   β”‚   β”œβ”€β”€ events.py          # Ticketmaster
β”‚   β”‚   β”œβ”€β”€ advisories.py      # DuckDuckGo police advisory scraper
β”‚   β”‚   └── geocode.py         # TomTom + Geoapify, Lucknow-biased
β”‚   β”œβ”€β”€ db.py                  # MongoDB Atlas client singleton
β”‚   β”œβ”€β”€ cache.py               # MongoDB TTL cache (replaces SQLite)
β”‚   β”œβ”€β”€ history.py             # Commute history CRUD + pattern aggregation
β”‚   β”œβ”€β”€ risk.py                # Deterministic 0–100 risk formula
β”‚   └── lucknow_events.py      # Curated local calendar (Bada Mangal, Muharram, Ekana)
β”œβ”€β”€ templates/                 # Jinja2 HTML (splash, map, chat UI)
β”œβ”€β”€ static/                    # CSS + JS (Leaflet map, SSE stream, autocomplete)
β”œβ”€β”€ tests/                     # 14 pytest files, all mocked
β”œβ”€β”€ Dockerfile                 # Node.js + Python 3.11 for HF Spaces
└── requirements.txt

Lucknow-Specific Intelligence

What makes Saarthi genuinely useful for this city:

Event Traffic Impact When
Bada Mangal Very High β€” bhandaras block lanes city-wide Every Tuesday of Jyeshtha (May–June)
Muharram processions Very High β€” Old Lucknow roads closed 9th–10th Muharram
IPL at Ekana Stadium High β€” entire Ekana area gridlocked Match days
Charbagh morning rush Always High 8–10 AM daily
Eid congregations High β€” Rumi Darwaza, Aishbagh Eidgah Eid ul-Fitr, Eid ul-Adha

The Team

Built in 48 hours for the Google Cloud Rapid Agent Hackathon Β· MongoDB Partner Track.

Name Role Handle
Saksham Pathak Team Lead Β· Backend Β· Agent Architecture @parthmax
Urmila Saini Research Β· Data Β· Testing @us17620
Aishrica Dhiman Frontend Β· UI/UX Β· Demo @aishricadhiman
Sameer Singh Tools Β· API Integration Β· DevOps @ssingh383

License

MIT License β€” see LICENSE for details.

Saarthi (ΰ€Έΰ€Ύΰ€₯ΰ₯€) means companion in Hindi β€” your commute companion that thinks ahead.