Public Sentiment Collection Agent - Geographic Sentiment Analysis

📋 Project Overview & Problem Statement

Challenge: A coffee shop owner receives dozens of reviews per week across Twitter, Instagram, Facebook, and Google — thousands per quarter. The raw feed is impossible to read end-to-end, impossible to compare channel by channel, and impossible to prioritise. Was that bad week a Banana Bread problem, a Facebook problem, or neither? By the time the pattern becomes visible, a month of customer confidence has already leaked.

Solution: The Public Sentiment Collection Agent runs social-channel review data through a 5-agent AI pipeline — listening, sentiment classification, visualisation, export, and packaging. This showcase demonstrates the pipeline applied to 500 coffee shop reviews from Q1 2024. Output: ranked product list, channel-by-channel net-sentiment scores, flagged SKUs where negative outweighs positive, and a 60-day action plan — in under 10 minutes.

🚨 Why Channel-Level Analysis Matters

Example: a mid-sized Malaysian coffee shop, 500 reviews in Q1 2024

❌ WITHOUT channel segmentation: "50% positive" — sounds fine, hides which channel is bleeding reputation

✅ WITH channel segmentation:

Google: +27.6 net sentiment, 55% positive — strong
Facebook: +4.2 net sentiment, 41% negative — actively bleeding reputation
Two products (Banana Bread, Matcha Latte) have negative reviews outnumbering positive
The signal points to 2 SKUs and 1 channel to fix, not "the coffee shop is bad"

Key Benefits

Channel-level segmentation: Separate Google from Facebook — they report opposite stories
Product-level drill-down: Find the specific SKUs where negative sentiment exceeds positive
Net sentiment score per channel: Single KPI for monthly tracking and trend detection
Automatic flagging: Surfaces products / channels needing urgent attention
Comprehensive output: 10 files per run (1 markdown report, 4 charts, 5 CSV exports)

🤖 AI Capabilities & 5-Agent Architecture

🌍 Listening Agent

Scans social channels and collects reviews with metadata — customer, channel, product, timestamp. In the coffee shop case: pulled 500 reviews across Twitter (141), Instagram (123), Facebook (120), Google (116) from 334 unique customers.

🧠 Sentiment Agent

Classifies each review as positive / negative / neutral, then aggregates by channel, product, and category. In the coffee shop case: 252 positive, 171 negative, 77 neutral — 50.4% positive headline with strong channel-level variance.

📊 Visualization Agent

Builds 4 charts: channel comparison, product ranking, category heatmap, and monthly trend. In the coffee shop case: surfaced Facebook as harshest channel (+4.2 net sentiment) and Google as the kindest (+27.6).

💾 Export Agent

Exports 5 CSVs for downstream use in Excel, Google Sheets, or BI tools. In the coffee shop case: channel breakdown, category rankings, flagged products, monthly net-sentiment trend, and most-active reviewers.

📝 Packaging Agent

Produces an executive voice-of-customer report, top 3 action priorities, and a 60-day fix plan. In the coffee shop case: recommended fixing Banana Bread + Matcha Latte, activating Facebook reputation programme, and amplifying Sandwiches marketing.

AI Processing Pipeline — as applied to the coffee shop review case

Step 1: Ingest 500-review dataset and normalise metadata (customer, channel, product, timestamp)
Step 2: Classify each review (positive / negative / neutral) using Gemini AI
Step 3: Roll up sentiment by channel, product category, and individual SKU
Step 4: Compute net-sentiment KPIs and flag products where negative outweighs positive
Step 5: Generate 4 charts (channel, product, category, monthly trend)
Step 6: Export 5 CSVs (channel breakdown, category rankings, flagged products, net sentiment, top reviewers)
Step 7: Package executive report + top 3 priorities + 60-day action plan

🔍 Channel Behaviour & Net-Sentiment Scoring

Channel Behaviour Classification

The system automatically classifies each social channel's behavioural pattern — in the coffee shop case:

Google: Long-form, effort-required review — tends to reward positive experiences (55% positive, +27.6 net)
Instagram: Visual and casual — mostly positive (52% positive, +17.9 net)
Twitter: Short-form, polarised — balanced split (50% positive, +15.6 net)
Facebook: Complaint-friendly — harshest channel (45% positive, 41% negative, +4.2 net)

Automatic Issue Flags

The system issues warnings when a channel, category, or product signals distress — examples from the coffee shop case:

⚠️ Product negative outweighs positive: Banana Bread (50% neg, 33% pos)
⚠️ Product negative outweighs positive: Matcha Latte (47% neg, 40% pos)
⚠️ Channel net sentiment below +10: Facebook (+4.2 — active reputation repair needed)
⚠️ Category net sentiment below +15: Cold Coffee & Iced Drinks (+12)
            

Net Sentiment Score Calculation

Net Sentiment Score per channel =
    (Positive count − Negative count) / Total × 100

🟢 +20 and above: Healthy (channel ambassadors — amplify content)
🟡 +10 to +19: Monitor (watch the trend, respond to complaints)
🔴 Below +10: Active repair (reply daily, tactical recovery playbook)
            

📊 Output Package (10 Files Per Analysis)

1 Markdown Report

Executive summary with headline net sentiment
Channel-by-channel sentiment breakdown
Product category rankings by net score
Flagged products (negative outweighs positive)
Top reviewers / repeat customer patterns
60-day action plan with phased milestones
Top 3 priorities for the operator

4 Visualization Charts (PNG)

Channel Sentiment Comparison: Stacked bar chart — positive / negative / neutral per channel
Product Performance Ranking: Horizontal bar chart — top-positive products and most-flagged SKUs
Category Heatmap: Product category × sentiment grid, net score per cell
Monthly Volume & Trend: Review count per month with net-sentiment trend line

5 CSV Data Exports

channel_sentiment.csv: Net sentiment breakdown per channel (Twitter / IG / FB / Google)
category_performance.csv: Product categories ranked by net sentiment
flagged_products.csv: SKUs where negative reviews outnumber positive
customer_reviewers.csv: Most active reviewers (4+ reviews) — VIP / detractor candidates
monthly_volume.csv: Review count and net sentiment by month

🛠️ Technical Architecture & Implementation

AI & Analytics Stack

Google Gemini 2.0 Flash Tavily Search API Python 3.9+ Pandas 2.0+ Matplotlib Seaborn

Multi-Agent Framework

5 Specialized Agents Web Search Integration NLP Sentiment Analysis Data Quality Scoring Auto Visualization

Deployment Options

Google Colab Jupyter Notebook Local Python Streamlit (Optional)

System Architecture

Pipeline Flow:
Geographic Listening → Web search with location filters
Source Analysis → Diversity tracking & bias detection
Sentiment Analysis → Gemini AI with cultural context
Credibility Scoring → Quality assessment (0-100)
Visualization → 4 professional charts
Data Export → 5 CSV files for Excel/Sheets
Report Packaging → Executive markdown report
            

📖 Development Setup & Usage Guide

Quick Start

Try the AI Assistant Demo: Click "Launch AI Assistant Demo" button above — zero-setup interactive walkthrough of the 5-agent pipeline
Run the full pipeline locally: Clone the repo, add GOOGLE_API_KEY and TAVILY_API_KEY to a .env file
Install dependencies: pip install -r requirements.txt
Run Analysis: python public_sentiment_collection_agent.py
Download Results: Get markdown report, 4 charts, and 5 CSV files

Example Usage — coffee shop review case

# Example: Analyse coffee shop reviews across 4 social channels
results = run_enhanced_sentiment_pipeline(
    review_dataset="coffee_shop_reviews_q1_2024.csv",
    channels=["Twitter", "Instagram", "Facebook", "Google"],
    period="Q1 2024",
    output_dir="."
)

# Output:
# - voice_of_customer_report_q1_2024.md
# - channel_sentiment_comparison.png
# - product_performance_ranking.png
# - category_heatmap.png
# - monthly_volume_trend.png
# - channel_sentiment.csv
# - category_performance.csv
# - flagged_products.csv
# - customer_reviewers.csv
# - monthly_volume.csv
            

Required API Keys

Google AI Studio API: Get from Google AI Studio (free tier available)
Tavily Search API: Get from Tavily (free 1,000 searches/month)

📊 Performance Metrics & Business Impact

10-15 min

Full Analysis Time

10

Files Generated

5

Specialized Agents

−100 to +100

Net Sentiment Score

Business Value Demonstration

Separates channel from product signal: Distinguishes a bad channel (Facebook) from a bad product (Banana Bread) — different fixes
Surfaces the 2–3 SKUs that really need attention: Instead of "50% positive" headline, pinpoints where negative outweighs positive
Single KPI per channel: Net sentiment score makes monthly tracking trivial
Production-ready output: Markdown report + 4 charts + 5 CSV exports for BI/Sheets
Cost-effective: ~RM2 per run vs. RM15,000+ for a traditional customer-experience audit

Use Cases

F&B voice-of-customer: Monthly review of Google/IG/FB/Twitter feedback across the menu
Product recipe / supplier review: Flag SKUs where negative reviews justify a kitchen or vendor audit
Channel reputation management: Identify which platform needs active reply programmes
New product launch tracking: Compare launch-month sentiment against baseline after 30/60/90 days
Competitive benchmark: Run the same pipeline on a competitor's public reviews to compare

⚠️ Limitations & Disclaimers

Data Collection Limitations

Self-selection bias: Reviewers are customers motivated to post — silent majority is not represented
Channel skew: Each platform has its own review culture (Google rewards effort, Facebook rewards complaint)
Temporal snapshot: Sentiment reflects the period captured — can shift quickly after menu changes or incidents
Language coverage: Primarily English/Malay reviews — non-English opinions underrepresented in the demo dataset
Product attribution: Reviews without a specified product roll up to "general" — limits SKU-level precision

Sentiment Classification Challenges

Sarcasm and irony can flip classification (e.g. "Great, just what I wanted" read as positive)
Short reviews (< 5 words) give lower-confidence signals
Reviews about service vs product can conflate — the demo pipeline tracks product but not service explicitly

Recommended Use

✅ Good for: Trend detection, SKU flagging, channel health monitoring, monthly voice-of-customer reporting

⚠️ Caution for: Attributing cause to single reviews, punishing individual staff based on reviews, forecasting revenue from sentiment alone

❌ Not for: Statistical inference about silent non-reviewing customers

🌍 Public Sentiment Collection Agent