AI-Powered WhatsApp Message Notification Router
Built for the HackerRank Orchestrate Hackathon (August 2026) — Ranked #376 out of 1,983 participants.
RouteGuard classifies incoming WhatsApp messages into three actions:
notify— interrupt the user now (urgent messages, safety alerts, direct mentions)digest— useful but can wait (casual chat, non-urgent updates)mute— suppress entirely (scams, spam, forwarded chains, phishing)
Data Layer → Profile Building → Evidence Retrieval → Safety Detection → Media Processing → LLM Classification → Post-Processing → Output
| Stage | What It Does | API Calls? |
|---|---|---|
| 1. Data Loading | Loads 13 CSV files (users, groups, businesses, message history, events) | No |
| 2. Profile Building | Builds rich context for 54 users, 23 groups, 110 businesses | No |
| 3. Evidence Retrieval | TF-IDF similarity + reaction signal boosting over 400+ historical messages | No |
| 4. Safety Detection | Deterministic detectors for scams, phishing, prompt injection, domain impersonation | No |
| 5. Media Processing | Vision model for 20 images, Whisper for 13 voice notes | Yes |
| 6. LLM Routing | Llama 3.3 70B classifies each message with full personalized context | Yes |
| 7. Post-Processing | Keyword inference fixes, schema validation, confidence clamping | No |
| Decision | Why |
|---|---|
| Hybrid rules + LLM | Deterministic safety detectors can't be prompt-injected; LLM handles nuanced cases |
| Multi-provider free tier | Groq (text + audio) + OpenRouter (vision) = $0 cost, no rate limit issues |
| TF-IDF with reaction boosting | Content similarity finds what is similar; reaction signals tell you how the user responded |
| Safety short-circuit | 24 out of 110 messages auto-muted without LLM calls — faster and more reliable |
| 2.1s request pacing | Stays under Groq's 30 RPM limit natively, zero rate limit errors |
- Python 3.11+
- Groq API key (free)
- OpenRouter API key (free)
cd code
pip install -r requirements.txt
cp .env.example .env
# Edit .env and add your API keyspython main.py # Full pipeline
python postprocess.py # Fix edge-case misclassifications
python fix_failed.py # Re-classify any rate-limited failures| Task | Model | Provider | Cost |
|---|---|---|---|
| Text routing | llama-3.3-70b-versatile |
Groq | Free |
| Image analysis | nvidia/nemotron-nano-12b-v2-vl:free |
OpenRouter | Free |
| Audio transcription | whisper-large-v3 |
Groq | Free |
code/
├── main.py # Entry point — full pipeline orchestrator
├── config.py # API keys, model settings, thresholds
├── requirements.txt # Dependencies
├── .env.example # Environment variable template
├── postprocess.py # Output post-processing and validation
├── fix_failed.py # Targeted re-classification of failed messages
├── fix_unicode.py # Windows Unicode compatibility
├── rate_limiter.py # Exponential backoff rate limiter
├── data/
│ ├── loader.py # CSV loading and validation
│ └── profiles.py # User, Group, Business, Sender profile builders
├── evidence/
│ ├── retriever.py # Historical evidence retrieval with reaction boosting
│ └── similarity.py # TF-IDF cosine similarity scoring
├── media/
│ ├── image_analyzer.py # Vision model image analysis (OpenRouter)
│ └── voice_analyzer.py # Whisper voice note transcription (Groq)
├── safety/
│ ├── detectors.py # Deterministic safety detectors
│ └── patterns.py # Regex patterns and keyword lists
├── routing/
│ ├── classifier.py # LLM-based message classification
│ ├── prompts.py # System and user prompt templates
│ └── output.py # Output validation and CSV writing
└── evaluation/
└── main.py # Self-evaluation against samples
| Metric | Value |
|---|---|
| Messages routed | 110/110 |
| Notify | 32 (29%) |
| Digest | 29 (26%) |
| Mute | 49 (45%) |
| Safety short-circuits | 24 |
| Average confidence | 0.87 |
| Scams detected | 30 |
| Voice notes transcribed | 13 (including Hindi) |
| Images analyzed | 19/20 |
MIT