TruthTrace
Inspiration
In today's fast-paced digital world, understanding public sentiment and identifying emerging trends is crucial for businesses, researchers, and decision-makers. We noticed that while people can see what's trending, they often struggle to understand why trends emerge, who drives them, and when sentiment shifts occur. We were inspired to create a tool that not only surfaces trends but provides deep, actionable insights backed by AI analysis and robust statistical methods.
What it does
TruthTrace is an intelligent trend analysis platform that transforms natural language queries into comprehensive sentiment analysis over time. It reveals:
The trends over time: Track sentiment changes across multiple time periods with weighted metrics based on tweet impressions. The platform generates beautiful visualizations showing how public opinion evolves, complete with standard deviation to measure volatility.
What is driving each trend: Using the CUSUM (Cumulative Sum Control Chart) algorithm, TruthTrace automatically detects significant trend changes and identifies the most influential tweets at each shift point. It shows you the exact content that drove sentiment changes, ranked by engagement metrics (impressions, retweets, likes).
Actionable insights to ride the trends: Grok AI analyzes the data and generates concise summaries highlighting key patterns, sentiment direction, and the nature of trend changes. The real-time streaming interface provides insights as they're discovered and provides actionable suggestions to improve the products based on the trends.
Core Features:
- Natural Language Queries: Ask questions in plain English like "What do people think about AI?"
- Statistical Trend Detection: CUSUM algorithm automatically identifies significant sentiment shifts
- Influential Content Tracking: Identifies tweets with the highest impact on sentiment changes
- AI-Powered Insights: Grok provides sentiment scores and generates actionable insights to catch the trend
- Weighted Metrics: Sentiment calculations weighted by tweet impressions for more accurate representation
How we built it
Architecture
Backend (Python/Flask):
- Flask Server: RESTful API with CORS support for frontend communication
- Server-Sent Events (SSE): Real-time streaming of analysis results
- Modular Design: Separate modules for each major component
Key Components:
Query Optimization (
grok_client.py): - Grok AI converts natural language to optimized X API search queriesData Collection (
x_client.py): - Uses X SDK for tweet retrieval - Searches within specific date ranges - Sorts by engagement metrics (impressions, retweets, likes)Sentiment Analysis (
sentiment_analyzer.py): - Batch processing (30 tweets per batch) for efficiency - Grok AI assigns sentiment scores from -1 (negative) to +1 (positive)Metrics Calculation (
app.py): - Weighted Mean: Sentiment weighted by tweet impressions (more viral = more weight) - Standard Deviation: Measures sentiment volatility - Tracks changes over timeTrend Detection (
cusum_detector.py): - Implements CUSUM algorithm with configurable threshold and drift - Detects both positive and negative sentiment shifts - Automatically adapts target mean after changes - Initialization period of 3 timesteps for stabilitySummary Generation (
grok_client.py): - Grok AI analyzes aggregate metrics - Generates concise 2-3 sentence summaries - Highlights overall sentiment direction and major changes
Frontend (React):
- Built with React, Framer Motion (animations), and Recharts (visualizations)
- Real-time updates via SSE
- Interactive sentiment charts
- Animated typing effects for AI narration
- Dark-themed modern UI
Analysis Pipeline:
User Query → Grok AI (Query Optimization) → X API (Tweet Retrieval) →
Grok AI (Batch Sentiment) → Weighted Metrics → CUSUM Detection →
Influential Tweets → Grok AI (Summary) → Frontend Visualization
Tech Stack:
- Backend: Flask, NumPy, Python, Requests
- Frontend: React, Framer Motion, Recharts, Lucide React
- APIs: Grok API (xAI), X API
- Algorithm: CUSUM (Cumulative Sum Control Chart)
Challenges we ran into
X API Limitations
The biggest challenge was dealing with X API restrictions and balancing our approach accordingly:
Problem: The non-enterprise API only allows searching tweets from the last week. This drastically limited our historical analysis capabilities.
Accomplishments that we're proud of
Building a metric that coherently captures the trends
Our proudest achievement is creating a weighted sentiment metric that accurately reflects public opinion:
Impression-Weighted Mean: Unlike simple averages, we weight each tweet's sentiment by its impression count. A tweet with 1 million impressions has proportionally more influence than one with 1,000. This creates a metric that truly represents how sentiment is perceived by the masses.
*CUSUM Algorithm *: We utilized the Cumulative Sum Control Chart algorithm to automatically detect trend changes. The algorithm: - Adapts to baseline sentiment levels - Detects both positive and negative shifts - Filters out noise while catching significant changes - Automatically updates target means after shifts - Has configurable sensitivity (threshold and drift parameters)
End-to-End Real-time Pipeline: Built a complete streaming architecture using Server-Sent Events that provides live updates as analysis progresses. Users see: - Timestep-wise sentiment scores - Trend changes as they're detected - Final summary and insights
Robust Error Handling: Despite API limitations and potential failures, the system gracefully continues analysis, using smart fallbacks.
Production-Ready Code: Clean modular architecture, comprehensive documentation, and automated setup scripts.
What we learned
Technical Learnings:
API Integration Complexity: Working with multiple APIs (Grok, X) taught us the importance of: - Understanding tier limitations before building - Graceful degradation when services fail - Efficient batching to minimize API calls
Statistical Algorithms in Practice: Implementing CUSUM showed us: - The importance of initialization periods - How parameter tuning (threshold, drift) affects sensitivity - The value of adaptive algorithms that adjust to data characteristics
Real-time Data Streaming: Server-Sent Events are powerful for: - Providing feedback during long-running operations - Building responsive UIs without complex WebSocket setup - Handling errors mid-stream gracefully
Weighted Statistics: Simple averages don't tell the full story: - Impression-weighted metrics better represent actual influence - Volatility (standard deviation) is as important as mean sentiment - Outlier handling is crucial in social media data
Domain Learnings:
Sentiment Analysis Nuances: AI models are good at sentiment but: - Sarcasm and irony remain challenging - Context matters - Batch processing balances performance and speed
Social Media Dynamics: - Impression counts are the best proxy for influence - Recent data can still reveal meaningful trends - High-volume topics are more suitable for short time windows
User Experience: - Real-time feedback is essential for long operations - Clear progress indicators reduce perceived wait time - Error messages should suggest solutions, not just describe problems
What's next for TruthTrace
Immediate Enhancements:
- Caching Layer: Store results to avoid redundant API calls
- Batch Optimization: Parallel processing for multiple timesteps
Feature Roadmap:
v2.0 - Enhanced Analysis:
- [ ] Multiple sentiment models (compare the use of other sentiment models)
- [ ] Demographic breakdown (if author data available)
- [ ] Topic clustering to identify sub-themes within trends
- [ ] Anomaly detection beyond CUSUM (isolation forests, etc.)
- [ ] Comparative analysis (compare sentiment across multiple queries)
v3.0 - Platform Features:
- [ ] User authentication and accounts
- [ ] Saved searches and alerts
- [ ] Historical data storage (PostgreSQL/MongoDB)
- [ ] Export to CSV, PDF, or presentation format
- [ ] Custom dashboards with multiple widgets
- [ ] API for third-party integrations
v4.0 - Advanced Capabilities:
- [ ] Image and video sentiment analysis
- [ ] Multi-language support
- [ ] Predictive analytics (forecast future sentiment)
- [ ] Competitor comparison
- [ ] Brand monitoring and reputation tracking
- [ ] Integration with other social platforms
v5.0 - Enterprise:
- [ ] Team collaboration features
- [ ] Role-based access control
- [ ] White-label solution
- [ ] SLA guarantees and support
- [ ] Custom model training on user data
- [ ] Regulatory compliance (GDPR, etc.)
Research Directions:
- Explore other change point detection algorithms (e.g., Bayesian methods)
- Investigate causal inference (what causes sentiment changes, not just correlation)
- Develop better impression count estimation when data is missing