AI Notification Router

Overview

This project is an intelligent WhatsApp notification routing system developed for the HackerRank Orchestrate Challenge.

Instead of notifying users for every incoming message, the system analyzes message content, user context, business information, group metadata, images, and voice notes to decide whether a message should:

• Notify the user immediately
• Be included in a digest
• Be muted

The system combines rule-based filtering with Large Language Models (LLMs) to achieve accurate and explainable routing decisions.

---

Features

• Rule-based detection for scams, promotions, and chain forwards
• Context-aware message classification using an LLM
• Image understanding using Qwen2.5-VL
• Voice transcription using Whisper
• User history and group context integration
• Evidence-based decision making
• Confidence score for every prediction

---

Project Structure

.
├── code/
├── dataset/
├── src/
│   ├── context_builder.py
│   ├── data_loader.py
│   ├── decision_engine.py
│   ├── image_handler.py
│   ├── router.py
│   └── voice_handler.py
├── predict.py
├── output.csv
└── README.md

---

Approach

The routing pipeline follows this sequence:

Incoming Message
        │
        ▼
Rule Engine
(Scam / Promotions / Forward Detection)
        │
        ▼
Image Analysis (if image)
        │
        ▼
Voice Transcription (if voice note)
        │
        ▼
Context Builder
(User + Business + Group + History)
        │
        ▼
LLM Decision Engine
(Qwen2.5-VL via Ollama)
        │
        ▼
Final Action
Notify / Digest / Mute
        │
        ▼
output.csv

---

Models Used

LLM

• Qwen2.5-VL 7B
• Served locally using Ollama

Used for:

• Context-aware routing
• Message understanding
• Image understanding
• Reason generation

---

Speech Recognition

• OpenAI Whisper (Base)

Used for:

• Voice note transcription

---

Rule Engine

The system first performs fast deterministic classification for:

• OTP scams
• PIN/password requests
• Chain forwards
• Marketing promotions

Messages confidently classified by rules bypass the LLM for efficiency.

---

Context Used

Each message is enriched with:

User

• Opened messages
• Reply history
• Dismissed notifications
• DND window

Business

• Verification status
• Category
• User reports

Groups

• Muted status
• User role

History

Recent message history is attached as evidence for the LLM.

---

Output Format

The generated output.csv contains:

Column	Description
message_id	Input message ID
action	notify / digest / mute
message_type	Classified message category
reason	Explanation for decision
confidence	Confidence score
evidence_message_ids	Supporting historical messages

---

Installation

Install dependencies:

pip install pandas
pip install tqdm
pip install ollama
pip install openai-whisper

Install FFmpeg (required for Whisper).

Run the Ollama model:

ollama run qwen2.5vl:7b

---

Running

Generate predictions:

python predict.py

The final predictions are written to:

output.csv

---

Design Decisions

• Rules are used for obvious cases to reduce LLM calls.
• The LLM handles ambiguous and context-dependent messages.
• Images and voice notes are converted into text before routing.
• Every prediction includes a confidence score and supporting evidence where available.

---

Future Improvements

• Better confidence calibration
• Larger context windows
• OCR integration for image text extraction
• Faster speech transcription
• Learning from user feedback over time

---

Tech Stack

• Python
• Pandas
• Ollama
• Qwen2.5-VL 7B
• OpenAI Whisper
• tqdm

---

Author

Developed for the HackerRank Orchestrate Challenge.