--- 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](https://img.shields.io/badge/πŸ€—%20Live%20Demo-Hugging%20Face-yellow)](https://parthmax-saarthi-ai.hf.space) [![GitHub](https://img.shields.io/badge/GitHub-parthmax2%2Fsaarthi--ai-black?logo=github)](https://github.com/parthmax2/saarthi-ai) [![Hackathon](https://img.shields.io/badge/Google%20Cloud-Rapid%20Agent%20Hackathon-blue?logo=google-cloud)](https://devpost.com) [![Track](https://img.shields.io/badge/Partner%20Track-MongoDB-green?logo=mongodb)](https://www.mongodb.com) **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 ```bash # 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](https://aistudio.google.com) | βœ… Yes | | `TomTom_api_key` | [developer.tomtom.com](https://developer.tomtom.com) | βœ… 2,500 req/day | | `MONGODB_URI` | [cloud.mongodb.com](https://cloud.mongodb.com) (M0 free cluster) | βœ… Forever free | | `GROQ_API_KEY` | [console.groq.com](https://console.groq.com) | βœ… Yes (LLM fallback) | | `calendarific_api_key` | [calendarific.com](https://calendarific.com) | βœ… 1,000/month | | `Geoapify_API` | [myprojects.geoapify.com](https://myprojects.geoapify.com) | βœ… 3,000/day | | `Ticketmaster_API` | [developer.ticketmaster.com](https://developer.ticketmaster.com) | βœ… Yes | The app degrades gracefully β€” only `GEMINI_API_KEY` + `TomTom_api_key` + `MONGODB_URI` are required to run. ### Run Tests ```bash 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](https://huggingface.co/parthmax) | | **Urmila Saini** | Research Β· Data Β· Testing | [@us17620](https://huggingface.co/us17620) | | **Aishrica Dhiman** | Frontend Β· UI/UX Β· Demo | [@aishricadhiman](https://huggingface.co/aishricadhiman) | | **Sameer Singh** | Tools Β· API Integration Β· DevOps | [@ssingh383](https://huggingface.co/ssingh383) | --- ## License MIT License β€” see [LICENSE](LICENSE) for details. ---
*Saarthi (ΰ€Έΰ€Ύΰ€₯ΰ₯€) means companion in Hindi β€” your commute companion that thinks ahead.*