README.md

---
title: Saarthi AI
emoji: 🚗
colorFrom: indigo
colorTo: green
sdk: docker
app_port: 7860
pinned: false
---

<div align="center">

# 🚗 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**

</div>

---

## 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.

---

<div align="center">

*Saarthi (साथी) means companion in Hindi — your commute companion that thinks ahead.*

</div>