feat: implement notification routing pipeline

[javagovindsharma]

Notification Routing Pipeline Implementation

Overview

This change implements the initial end-to-end notification routing pipeline for the HackerRank Orchestrate challenge. The implementation processes incoming messages, enriches them with available user and contextual information, analyzes message content, retrieves relevant historical messages, determines the appropriate notification action, selects supporting evidence, and generates the final output CSV.

The pipeline supports three notification actions:

• notify — For messages that require immediate user attention.
• digest — For useful messages that do not require immediate notification.
• mute — For spam, scam, or low-value messages that should not generate notifications.

Implementation Details

1. Data Loading

Implemented a centralized DataLoader to load all relevant CSV datasets from the repository's dataset directory.

The loader supports:

• messages.csv
• sample_messages.csv
• users.csv
• groups.csv
• group_members.csv
• business_accounts.csv
• user_business_history.csv
• message_history.csv
• message_events.csv
• images.csv
• voice_notes.csv
• daily_notification_summary.csv

The implementation also handles missing files gracefully and logs the loading status of each dataset.

2. Context Building

Added ContextBuilder to construct a contextual representation for every incoming message.

The context includes, where available:

• Message details
• User information
• Sender information
• Group information
• Group membership
• Business account information
• User-business relationship history
• Historical messages
• Previous message events
• Notification summary
• Media metadata

This provides the foundation for personalized notification decisions.

3. Message Analysis

Implemented MessageAnalyzer to classify incoming messages based on their content.

Supported message categories include:

• personal
• urgent
• event
• payment
• business_update
• promotion
• greeting
• forward
• spam
• scam
• unknown

The analyzer also calculates:

• Urgency score
• Spam risk
• Scam risk
• Promotion score

Rule-based keyword detection is currently used as the baseline classification mechanism.

4. Historical Message Retrieval

Added a Retriever component using TF-IDF and cosine similarity to identify historically relevant messages.

The retrieval process:

1. Takes the current message as a query.
2. Searches historical messages.
3. Prioritizes messages associated with the same user where available.
4. Calculates textual similarity using TF-IDF.
5. Returns the top relevant historical messages.

This enables historical context and evidence to be incorporated into notification decisions.

5. Evidence Selection

Implemented EvidenceSelector to extract relevant historical message_id values from retrieved messages.

The selected evidence is included in the final output through the evidence_message_ids field.

6. Notification Decision Engine

Implemented DecisionEngine to determine the final notification action.

The decision engine currently evaluates:

• Scam risk
• Spam risk
• Message urgency
• Message type
• Promotion indicators
• Payment-related content
• Conversation type
• Forwarded content
• Event-related content

The engine produces one of:

• notify
• digest
• mute

It also generates:

• Message type
• Reason for the decision
• Confidence score
• Supporting evidence IDs

7. Output Generation

Added OutputGenerator to generate the final prediction CSV.

The output follows the required schema:

message_id
action
message_type
reason
confidence
evidence_message_ids

The output is generated as:

dataset/output_generated.csv

8. End-to-End Pipeline

The complete processing flow is:

CSV Datasets
    ↓
Data Loader
    ↓
Context Builder
    ↓
Message Analyzer
    ↓
Historical Message Retriever
    ↓
Evidence Selector
    ↓
Notification Decision Engine
    ↓
Output Generator
    ↓
output_generated.csv

9. Prompt Template

Added a reusable notification routing prompt template under:

code/prompts/notification_prompt.txt

The prompt defines the notification routing task, supported message categories, available actions, contextual signals, and expected JSON output format.

This provides a foundation for integrating an LLM-based decision engine in a future iteration.

Current Implementation Approach

The current version uses a hybrid baseline approach:

• Pandas for data processing
• TF-IDF and cosine similarity for historical retrieval
• Rule-based message classification
• Context-based decision rules
• Evidence extraction from historical data

This approach provides a deterministic and explainable baseline while keeping the architecture modular for future AI/LLM integration.

Future Enhancements

The following improvements can be added in subsequent iterations:

• LLM-based message classification and decision making
• RAG-based contextual retrieval
• Better personalization using user notification behavior
• Image content analysis
• Voice note transcription and analysis
• Advanced spam and scam detection
• Improved sender and business trust scoring
• User-specific notification preferences
• More sophisticated confidence scoring
• Evaluation against sample/ground-truth data
• Performance optimization for large datasets
• LLM-generated explanations and evidence reasoning

Validation

The pipeline can be executed using:

cd code
pip install -r requirements.txt
py main.py

The generated predictions are written to:

dataset/output_generated.csv

This implementation establishes the initial modular architecture required to evolve the notification routing system into a fully personalized, multimodal, and LLM-powered notification agent.