Real-time sentiment monitoring for social media mentions using state-of-the-art AI models
Agent Saad is an intelligent AI agent that continuously monitors Twitter/X and Reddit for brand mentions, automatically analyzes sentiment using advanced AI models, and sends real-time alerts via Slack and Email when negative sentiment is detected.
Problem: Support teams miss early warning signs of negative sentiment spreading across social media platforms, leading to:
- Delayed responses to customer complaints
- Viral negative feedback going unnoticed
- Lost opportunities to turn unhappy customers around
- Difficulty prioritizing which issues need immediate attention
Solution: Agent Saad automatically:
- ✅ Monitors multiple social platforms 24/7
- ✅ Analyzes sentiment using AI (not just keywords)
- ✅ Prioritizes alerts by urgency (Critical → Low)
- ✅ Provides AI-generated response recommendations
- ✅ Sends real-time notifications to your team
- ✅ Tracks all feedback in a beautiful dashboard
Model Name: distilbert-base-uncased-finetuned-sst-2-english
Why This Model?
- ✅ Fast: Inference time ~100ms per text on CPU
- ✅ Accurate: 90%+ accuracy on sentiment classification
- ✅ Free: No API costs, runs locally
- ✅ Lightweight: 250MB model size
- ✅ Battle-tested: Used by thousands of companies in production
Architecture:
- Base Model: DistilBERT (66M parameters)
- Training: Fine-tuned on Stanford Sentiment Treebank v2 (SST-2)
- Task: Binary sentiment classification (Positive/Negative)
- Framework: PyTorch via HuggingFace Transformers
Performance Metrics:
- Accuracy: 91.3% on SST-2 test set
- F1 Score: 0.913
- Inference Speed: ~100ms per text (CPU)
- Memory Usage: ~500MB RAM during operation
How It Works:
- Text is tokenized using WordPiece tokenization
- DistilBERT processes the tokens through 6 transformer layers
- Classification head outputs probability distribution
- Score is normalized to range [-1, 1] for urgency calculation
Input Text → Tokenization → DistilBERT Encoder → Classification Head → Sentiment Score
↓
[-1.0 to +1.0]
↓
Urgency: CRITICAL/HIGH/MEDIUM/LOW
Threshold System:
- Score ≤ -0.7 → CRITICAL (Very negative with strong language)
- Score ≤ -0.3 → HIGH (Clearly negative sentiment)
- Score ≤ 0.0 → MEDIUM (Slightly negative)
- Score > 0.0 → LOW (Neutral or positive)
- Python 3.8+ - Core programming language
- Flask 3.0 - Web framework for API and dashboard
- PyTorch 2.8 - Deep learning framework
- HuggingFace Transformers 4.40+ - AI model library
- APScheduler 3.10 - Background job scheduling
- DistilBERT - Sentiment analysis model
- Transformers Pipeline - High-level inference API
- Tokenizers - Fast text tokenization
- Tweepy 4.15+ - Twitter/X API client
- PRAW 7.7 - Reddit API wrapper
- Slack SDK 3.26 - Slack bot integration
- SMTP (smtplib) - Email notifications
- SQLite - Local database for alerts
- Thread-safe connections - Concurrent access handling
- HTML5 - Semantic markup
- CSS3 - Modern styling with variables
- Vanilla JavaScript - No framework overhead
- Inter Font - Modern typography
- CSS Grid & Flexbox - Responsive layouts
- 🎨 Dark/Light Mode - Automatic theme switching
- ✨ Smooth Animations - CSS transitions and keyframes
- 📱 Fully Responsive - Mobile-first design
- 🎯 Interactive - Ripple effects, hover states
- 🔔 Toast Notifications - Real-time feedback
- 📊 Animated Charts - Progress bars and stats
- Continuous scanning of Twitter and Reddit
- Configurable check intervals (default: 15 minutes)
- Keyword-based search across multiple platforms
- State-of-the-art sentiment analysis
- Context-aware urgency detection
- Engagement metrics consideration
- Multi-channel notifications (Slack + Email)
- Priority-based alert routing
- Duplicate detection and prevention
- AI-generated response suggestions
- Issue-specific guidance
- Escalation recommendations
- Modern, gradient-based design
- Real-time statistics
- Filterable alert feed
- Dark/Light mode toggle
- Smooth animations and transitions
# Clone the repository
git clone https://github.com/yourusername/Agent-Saad.git
cd Agent-Saad
# Install dependencies
pip install -r requirements.txtCreate a .env file with your credentials:
# Twitter/X API
TWITTER_BEARER_TOKEN=your_bearer_token
# Reddit API
REDDIT_CLIENT_ID=your_client_id
REDDIT_CLIENT_SECRET=your_client_secret
REDDIT_USER_AGENT=SaadMonitoring/1.0.0
# Email
SMTP_USERNAME=your_email@gmail.com
SMTP_PASSWORD=your_app_password
ALERT_EMAIL_TO=alerts@yourcompany.com
# Slack
SLACK_BOT_TOKEN=xoxb-your-bot-token
SLACK_CHANNEL=#alerts
# Monitoring
KEYWORDS=your_brand,your_product
SENTIMENT_THRESHOLD=-0.3
CHECK_INTERVAL_MINUTES=15python run.pyOpen http://localhost:5000 in your browser.
- Total Alerts: Cumulative count with trend indicator
- Critical Alerts: High-priority issues requiring immediate action
- High Priority: Important negative feedback
- Last 24 Hours: Recent activity tracking
- Color-coded urgency levels for quick identification
- Source badges (Twitter/Reddit)
- Sentiment scores with visual indicators
- Recommended responses for each alert
- Direct links to original posts
- Filtering by urgency and source
- Run Monitor Now: Manual monitoring trigger
- Test Alerts: Verify Slack/Email integration
- Refresh: Update dashboard data
- Auto-refresh: Every 30 seconds
def determine_urgency(sentiment_score: float, engagement: int) -> str:
"""
sentiment_score: Range from -1.0 (very negative) to +1.0 (very positive)
engagement: Sum of likes, retweets, comments, upvotes
"""
if sentiment_score <= -0.7:
return 'CRITICAL' if engagement > 100 else 'HIGH'
elif sentiment_score <= -0.3:
return 'HIGH' if engagement > 50 else 'MEDIUM'
elif sentiment_score <= 0:
return 'LOW'
else:
return 'LOW' # Positive sentimentFactors Considered:
- Sentiment Score - Primary factor from AI model
- Engagement Metrics - Viral potential (likes, shares, upvotes)
- Content Analysis - Specific issue detection (bug, billing, etc.)
| Endpoint | Method | Description |
|---|---|---|
/ |
GET | Dashboard UI |
/api/alerts |
GET | Fetch recent alerts |
/api/stats |
GET | Get statistics |
/api/alert/<id>/status |
PUT | Update alert status |
/api/test/sentiment |
POST | Test sentiment analysis |
/api/test/alerts |
POST | Send test notifications |
/api/monitor/run |
POST | Trigger manual monitoring |
/health |
GET | Health check |
- Memory: ~500MB (AI model loaded)
- CPU: Low idle, spikes during analysis
- Disk: ~300MB (model cache) + database
- Network: API calls every 15 minutes (configurable)
- Sentiment Analysis: ~10 texts/second on CPU
- Monitoring Capacity: 100-1000 mentions/day
- Alert Processing: Real-time (<1 second)
- Current setup handles small to medium brands
- Can process 100+ mentions per monitoring cycle
- SQLite sufficient for <10K alerts
- Upgrade to PostgreSQL for higher volumes
- ✅ No data sent to external APIs (except social media)
- ✅ Credentials stored locally in
.env - ✅
.gitignoreprevents credential exposure - ✅ SQL injection protection (parameterized queries)
- ✅ Duplicate detection prevents re-processing
- Use environment variables for secrets
- Rotate API tokens regularly
- Enable HTTPS in production
- Set up proper authentication for dashboard
- Monitor logs for suspicious activity
- Catch escalating issues early
- Prioritize responses by urgency
- Track sentiment trends over time
- Reduce response time to complaints
- Identify bugs and UX issues quickly
- Understand customer pain points
- Track feature feedback
- Monitor competitor mentions
- Monitor brand reputation
- Track campaign sentiment
- Identify influencer complaints
- Respond to viral negative content
MIT License - see LICENSE file for details.
Contributions welcome! This project can be extended with:
- More social platforms (Facebook, Instagram, TikTok)
- Advanced analytics and trend visualization
- Automated response generation
- Multi-language sentiment analysis
- Custom model fine-tuning
- Integration with CRM systems
For issues or questions:
- Check the logs in
agent_saad.log - Review SETUP_GUIDE.md for detailed instructions
- Test each component using built-in test endpoints
- Verify all credentials in
.env
- HuggingFace for Transformers library and pre-trained models
- DistilBERT authors for the efficient transformer architecture
- SST-2 dataset for sentiment training data
- Open source community for amazing tools and libraries
Built with ❤️ for customer support teams worldwide
Protect your brand reputation with AI-powered sentiment monitoring