Implementation Guide: Monitor online reviews across platforms and summarize sentiment themes

python3 -m venv review-sentiment-env
source review-sentiment-env/bin/activate
pip install openai pandas python-dotenv requests jinja2

mkdir -p ~/review-sentiment/{config,data,output,templates,logs}
cd ~/review-sentiment

echo 'OPENAI_API_KEY=sk-your-api-key-here' > .env
echo 'CLIENT_NAME=Restaurant_Name' >> .env
echo 'REVIEWTRACKERS_API_KEY=your-rt-key-here' >> .env

# writes analyze_reviews.py to the review-sentiment directory

cat > ~/review-sentiment/analyze_reviews.py << 'SCRIPT_EOF'
import os, json, csv, datetime, logging
from pathlib import Path
from openai import OpenAI
from dotenv import load_dotenv
from jinja2 import Template

load_dotenv()
client = OpenAI(api_key=os.getenv('OPENAI_API_KEY'))

logging.basicConfig(
    filename='logs/sentiment_analysis.log',
    level=logging.INFO,
    format='%(asctime)s - %(levelname)s - %(message)s'
)

SENTIMENT_SYSTEM_PROMPT = open('config/system_prompt.txt').read()

def load_reviews_from_csv(filepath):
    reviews = []
    with open(filepath, 'r', encoding='utf-8') as f:
        reader = csv.DictReader(f)
        for row in reader:
            reviews.append({
                'source': row.get('source', 'Unknown'),
                'rating': row.get('rating', 'N/A'),
                'date': row.get('date', ''),
                'text': row.get('review_text', row.get('content', ''))
            })
    return reviews

def chunk_reviews(reviews, chunk_size=25):
    for i in range(0, len(reviews), chunk_size):
        yield reviews[i:i + chunk_size]

def analyze_chunk(reviews_chunk, location_name):
    reviews_text = ''
    for i, r in enumerate(reviews_chunk, 1):
        reviews_text += f"Review {i} [{r['source']}, {r['rating']} stars, {r['date']}]:\n{r['text']}\n\n"
    response = client.chat.completions.create(
        model='gpt-5.4-mini',
        messages=[
            {'role': 'system', 'content': SENTIMENT_SYSTEM_PROMPT},
            {'role': 'user', 'content': f'Location: {location_name}\n\nReviews to analyze:\n\n{reviews_text}'}
        ],
        response_format={'type': 'json_object'},
        temperature=0.3,
        max_tokens=2000
    )
    return json.loads(response.choices[0].message.content)

def generate_report(all_results, location_name, period):
    template = Template(open('templates/report_template.html').read())
    html = template.render(
        location=location_name,
        period=period,
        results=all_results,
        generated_at=datetime.datetime.now().strftime('%Y-%m-%d %H:%M')
    )
    output_path = f"output/{location_name.replace(' ', '_')}_{period}.html"
    with open(output_path, 'w') as f:
        f.write(html)
    logging.info(f'Report generated: {output_path}')
    return output_path

if __name__ == '__main__':
    import sys
    csv_path = sys.argv[1] if len(sys.argv) > 1 else 'data/reviews_export.csv'
    location = os.getenv('CLIENT_NAME', 'Restaurant')
    period = datetime.date.today().strftime('%Y-W%U')
    reviews = load_reviews_from_csv(csv_path)
    logging.info(f'Loaded {len(reviews)} reviews for {location}')
    all_results = []
    for chunk in chunk_reviews(reviews, 25):
        result = analyze_chunk(chunk, location)
        all_results.append(result)
        logging.info(f'Analyzed chunk of {len(chunk)} reviews')
    report_path = generate_report(all_results, location, period)
    print(f'Report saved to: {report_path}')
SCRIPT_EOF

cat > ~/review-sentiment/config/system_prompt.txt << 'PROMPT_EOF'
You are a restaurant review sentiment analyst working for a restaurant management consulting firm. Analyze the provided customer reviews and extract structured sentiment insights.

For each batch of reviews, return a JSON object with the following structure:

{
  "summary": "2-3 sentence executive summary of overall sentiment in this batch",
  "total_reviews_analyzed": <number>,
  "average_sentiment_score": <float from -1.0 to 1.0>,
  "themes": [
    {
      "theme_name": "<category name>",
      "sentiment": "positive|negative|mixed",
      "mention_count": <number of reviews mentioning this theme>,
      "score": <float from -1.0 to 1.0>,
      "representative_quotes": ["<direct quote 1>", "<direct quote 2>"],
      "actionable_insight": "<specific, actionable recommendation for the restaurant>"
    }
  ],
  "urgent_issues": [
    {
      "issue": "<description of urgent issue>",
      "severity": "critical|high|medium",
      "source_review_numbers": [<review numbers>],
      "recommended_action": "<immediate action to take>"
    }
  ],
  "trending": {
    "improving": ["<themes showing improvement>"],
    "declining": ["<themes showing decline>"],
    "new_this_period": ["<themes not previously seen>"]
  },
  "platform_comparison": {
    "<platform_name>": {
      "avg_rating": <float>,
      "primary_sentiment": "<summary>"
    }
  }
}

Categorize mentions into these restaurant-specific themes:
- Food Quality (taste, freshness, temperature, presentation, portion size)
- Service Speed (wait times, seating time, food delivery time, order accuracy timing)
- Staff Friendliness (hospitality, attentiveness, professionalism, knowledge)
- Ambiance (decor, noise level, cleanliness, comfort, music, lighting)
- Value/Pricing (value for money, portion-to-price ratio, specials, happy hour)
- Menu Variety (options, dietary accommodations, specials, seasonal items)
- Cleanliness/Hygiene (restrooms, dining area, visible kitchen, utensils)
- Delivery Experience (packaging, temperature on arrival, order accuracy, delivery time)
- Online Ordering (app/website usability, order accuracy, payment issues)
- Reservations/Seating (booking process, wait times, host interaction)
- Management Response (how restaurant handles complaints, recovery efforts)

Rules:
1. Only include themes that are actually mentioned in the reviews — do not fabricate themes with zero mentions
2. Extract EXACT quotes from reviews — do not paraphrase
3. Sentiment scores: -1.0 = extremely negative, 0 = neutral, 1.0 = extremely positive
4. Flag any mention of food safety, illness, allergen issues, or discrimination as CRITICAL urgent issues
5. If reviews mention specific dishes, staff names, or time periods, include those details
6. Compare sentiment across platforms if multiple sources are present
PROMPT_EOF

cat > ~/review-sentiment/templates/report_template.html << 'TPL_EOF'
<!DOCTYPE html>
<html><head><meta charset='utf-8'><title>Weekly Sentiment Report - {{ location }}</title>
<style>
body{font-family:'Segoe UI',Arial,sans-serif;max-width:900px;margin:0 auto;padding:20px;color:#333}
h1{color:#1a5276;border-bottom:3px solid #2e86c1;padding-bottom:10px}
h2{color:#2e86c1;margin-top:30px}
.summary{background:#eaf2f8;padding:15px;border-radius:8px;margin:20px 0;border-left:4px solid #2e86c1}
.theme-card{background:#fff;border:1px solid #ddd;border-radius:8px;padding:15px;margin:10px 0;box-shadow:0 2px 4px rgba(0,0,0,0.1)}
.positive{border-left:4px solid #27ae60}.negative{border-left:4px solid #e74c3c}.mixed{border-left:4px solid #f39c12}
.urgent{background:#fdedec;border:2px solid #e74c3c;border-radius:8px;padding:15px;margin:10px 0}
.score{font-size:24px;font-weight:bold;float:right}
.quote{font-style:italic;color:#666;margin:5px 0;padding-left:15px;border-left:2px solid #ccc}
.insight{background:#eafaf1;padding:10px;border-radius:5px;margin-top:10px}
.meta{color:#999;font-size:12px;text-align:right;margin-top:40px}
table{width:100%;border-collapse:collapse}td,th{padding:8px;border:1px solid #ddd;text-align:left}th{background:#f5f5f5}
</style></head><body>
<h1>📊 Weekly Review Sentiment Report</h1>
<p><strong>Location:</strong> {{ location }} | <strong>Period:</strong> {{ period }}</p>
{% for result in results %}
<div class='summary'><h3>Summary</h3><p>{{ result.summary }}</p>
<p>Reviews Analyzed: {{ result.total_reviews_analyzed }} | Average Sentiment: {{ '%.2f'|format(result.average_sentiment_score) }}</p></div>
{% if result.urgent_issues %}<h2>🚨 Urgent Issues</h2>
{% for issue in result.urgent_issues %}<div class='urgent'><strong>[{{ issue.severity|upper }}]</strong> {{ issue.issue }}<br><em>Action: {{ issue.recommended_action }}</em></div>{% endfor %}{% endif %}
<h2>📋 Sentiment Themes</h2>
{% for theme in result.themes|sort(attribute='score', reverse=true) %}
<div class='theme-card {{ theme.sentiment }}'><span class='score'>{{ '%.1f'|format(theme.score) }}</span>
<h3>{{ theme.theme_name }}</h3><p>Mentions: {{ theme.mention_count }} | Sentiment: {{ theme.sentiment }}</p>
{% for q in theme.representative_quotes %}<p class='quote'>"{{ q }}"</p>{% endfor %}
<div class='insight'>💡 {{ theme.actionable_insight }}</div></div>{% endfor %}
{% if result.platform_comparison %}<h2>📱 Platform Comparison</h2><table><tr><th>Platform</th><th>Avg Rating</th><th>Primary Sentiment</th></tr>
{% for platform, data in result.platform_comparison.items() %}<tr><td>{{ platform }}</td><td>{{ data.avg_rating }}</td><td>{{ data.primary_sentiment }}</td></tr>{% endfor %}</table>{% endif %}
{% endfor %}
<p class='meta'>Generated: {{ generated_at }} | Powered by AI Sentiment Analysis</p>
</body></html>
TPL_EOF

GET https://api.reviewtrackers.com/v2/reviews
Authorization: Bearer {RT_API_KEY}
Params: filter[created_after]={7 days ago ISO date}

To: owner@restaurant.com, gm@restaurant.com
Subject: Weekly Review Sentiment Report - {Location} - Week of {date}
Body: {HTML report content}

Channel: #review-alerts
Message: 🚨 *New {rating}-star review on {source}*
         "{review_text_preview}..."
         <{review_url}|Respond Now>

crontab -e
0 6 * * 1 cd /home/user/review-sentiment && python analyze_reviews.py data/weekly_export.csv 2>&1 >> logs/cron.log

cd ~/review-sentiment
source review-sentiment-env/bin/activate
python analyze_reviews.py data/baseline_export.csv

ls -la output/

open output/Restaurant_Name_*.html  # macOS
# or: xdg-open output/Restaurant_Name_*.html  # Linux

pip install weasyprint
python -c "from weasyprint import HTML; HTML('output/Restaurant_Name_2025-WXX.html').write_pdf('output/baseline_report.pdf')"

You are a restaurant review sentiment analyst working for a restaurant management consulting firm. Analyze the provided customer reviews and extract structured sentiment insights.

For each batch of reviews, return a JSON object with the following structure:

{
  "summary": "2-3 sentence executive summary of overall sentiment in this batch",
  "total_reviews_analyzed": <number>,
  "average_sentiment_score": <float from -1.0 to 1.0>,
  "themes": [
    {
      "theme_name": "<category name>",
      "sentiment": "positive|negative|mixed",
      "mention_count": <number of reviews mentioning this theme>,
      "score": <float from -1.0 to 1.0>,
      "representative_quotes": ["<direct quote 1>", "<direct quote 2>"],
      "actionable_insight": "<specific, actionable recommendation for the restaurant>"
    }
  ],
  "urgent_issues": [
    {
      "issue": "<description of urgent issue>",
      "severity": "critical|high|medium",
      "source_review_numbers": [<review numbers>],
      "recommended_action": "<immediate action to take>"
    }
  ],
  "trending": {
    "improving": ["<themes showing improvement>"],
    "declining": ["<themes showing decline>"],
    "new_this_period": ["<themes not previously seen>"]
  },
  "platform_comparison": {
    "<platform_name>": {
      "avg_rating": <float>,
      "primary_sentiment": "<summary>"
    }
  }
}

import os
from openai import OpenAI
from dotenv import load_dotenv

load_dotenv()
client = OpenAI(api_key=os.getenv('OPENAI_API_KEY'))

RESPONSE_SYSTEM_PROMPT = """You are a professional restaurant manager drafting a public response to a negative customer review. Your tone must be:
- Empathetic and apologetic (never defensive)
- Professional and warm
- Specific to the issues raised (reference their exact complaints)
- Brief (3-5 sentences maximum)
- Ending with an invitation to return and a way to reach management directly

Format your response as JSON:
{
  "response_text": "<the draft response>",
  "key_issues_addressed": ["<issue 1>", "<issue 2>"],
  "suggested_recovery_action": "<internal action for the GM, not included in public response>",
  "urgency": "immediate|within_24h|standard"
}

Rules:
1. Never admit legal liability or specific fault for food safety issues
2. Never offer specific compensation in the public response (handle offline)
3. Always include a direct contact method (email or phone)
4. Use the restaurant name naturally if provided
5. Never be sarcastic, dismissive, or confrontational
6. If the review mentions a specific employee by name, do NOT name them in the response
7. Keep under 150 words for the public response"""

def draft_response(review_text, rating, source_platform, restaurant_name, manager_name='Management', contact_email=''):
    user_prompt = f"""Restaurant: {restaurant_name}
Manager Name: {manager_name}
Contact Email: {contact_email}
Platform: {source_platform}
Rating: {rating} stars
Review Text: {review_text}

Draft a professional response to this review."""
    
    response = client.chat.completions.create(
        model='gpt-5.4-mini',
        messages=[
            {'role': 'system', 'content': RESPONSE_SYSTEM_PROMPT},
            {'role': 'user', 'content': user_prompt}
        ],
        response_format={'type': 'json_object'},
        temperature=0.4,
        max_tokens=500
    )
    return json.loads(response.choices[0].message.content)

# Usage example:
# result = draft_response(
#     review_text='Waited 45 minutes for cold food. Server never checked on us.',
#     rating=1,
#     source_platform='Google',
#     restaurant_name='Bella Cucina',
#     manager_name='Maria',
#     contact_email='maria@bellacucina.com'
# )
# print(result['response_text'])

# core module for loading historical results and calling GPT for
# longitudinal trend analysis

import json
import os
from pathlib import Path
from datetime import datetime, timedelta
from openai import OpenAI
from dotenv import load_dotenv

load_dotenv()
client = OpenAI(api_key=os.getenv('OPENAI_API_KEY'))

def load_historical_results(output_dir='output', weeks=4):
    """Load the JSON analysis results from the past N weeks."""
    results = []
    json_files = sorted(Path(output_dir).glob('*_analysis.json'), reverse=True)
    for f in json_files[:weeks]:
        with open(f) as fh:
            data = json.load(fh)
            data['_filename'] = f.name
            results.append(data)
    return results

def compare_trends(current_results, historical_results, location_name):
    """Use GPT-5.4 mini to compare current week vs historical trend."""
    prompt = f"""You are analyzing sentiment trends for {location_name} restaurant.

Current week analysis:
{json.dumps(current_results, indent=2)}

Previous {len(historical_results)} weeks (most recent first):
{json.dumps(historical_results, indent=2)}

Provide a trend analysis as JSON:
{{
  "overall_trend": "improving|stable|declining",
  "overall_trend_explanation": "<2-3 sentences explaining the overall trajectory>",
  "theme_trends": [
    {{
      "theme": "<theme name>",
      "direction": "improving|stable|declining|new",
      "current_score": <float>,
      "previous_avg_score": <float>,
      "change": <float>,
      "explanation": "<why this theme is trending this way>",
      "action_needed": true|false
    }}
  ],
  "notable_changes": ["<significant changes worth highlighting to the owner>"],
  "predicted_next_week": "<brief prediction based on trends>"
}}"""
    
    response = client.chat.completions.create(
        model='gpt-5.4-mini',
        messages=[
            {'role': 'system', 'content': 'You are a restaurant analytics expert providing trend analysis. Return valid JSON only.'},
            {'role': 'user', 'content': prompt}
        ],
        response_format={'type': 'json_object'},
        temperature=0.3,
        max_tokens=1500
    )
    return json.loads(response.choices[0].message.content)

json_output_path = f"output/{location.replace(' ', '_')}_{period}_analysis.json"
with open(json_output_path, 'w') as jf:
    json.dump({'period': period, 'results': all_results}, jf, indent=2)

# Core competitive benchmarking function

import json
from openai import OpenAI
from dotenv import load_dotenv
import os

load_dotenv()
client = OpenAI(api_key=os.getenv('OPENAI_API_KEY'))

COMPETITOR_PROMPT = """You are a competitive intelligence analyst for restaurants. Given review sentiment data for a client restaurant and its local competitors, produce a competitive benchmarking report.

Return JSON:
{
  "competitive_position": "leader|competitive|lagging",
  "executive_summary": "<3-4 sentences on competitive standing>",
  "advantages": [
    {
      "theme": "<theme where client outperforms>",
      "client_score": <float>,
      "competitor_avg_score": <float>,
      "gap": <float>,
      "recommendation": "<how to leverage this advantage in marketing>"
    }
  ],
  "vulnerabilities": [
    {
      "theme": "<theme where competitors outperform>",
      "client_score": <float>,
      "competitor_avg_score": <float>,
      "gap": <float>,
      "recommendation": "<specific action to close the gap>"
    }
  ],
  "competitor_highlights": [
    {
      "competitor_name": "<name>",
      "strongest_theme": "<their best area>",
      "weakest_theme": "<their worst area>",
      "opportunity": "<how client can capitalize on competitor weakness>"
    }
  ],
  "market_trends": ["<trends observed across all restaurants in the local market>"]
}"""

def analyze_competitive_landscape(client_data, competitor_data_list, client_name):
    user_prompt = f"""Client Restaurant: {client_name}
Client Sentiment Data (past 30 days):
{json.dumps(client_data, indent=2)}

Competitor Data:
{json.dumps(competitor_data_list, indent=2)}

Produce a competitive benchmarking analysis."""
    
    response = client.chat.completions.create(
        model='gpt-5.4-mini',
        messages=[
            {'role': 'system', 'content': COMPETITOR_PROMPT},
            {'role': 'user', 'content': user_prompt}
        ],
        response_format={'type': 'json_object'},
        temperature=0.3,
        max_tokens=2000
    )
    return json.loads(response.choices[0].message.content)

// Input: ReviewTrackers webhook payload via Zapier
const review = inputData;

// Determine emoji and color based on rating
const ratingEmojis = { 1: '🔴', 2: '🟠', 3: '🟡', 4: '🟢', 5: '🌟' };
const ratingColors = { 1: '#e74c3c', 2: '#e67e22', 3: '#f1c40f', 4: '#27ae60', 5: '#2ecc71' };
const rating = parseInt(review.rating) || 3;
const emoji = ratingEmojis[rating] || '⚪';

// Truncate review text for Slack
const maxLength = 300;
const reviewText = review.review_text || review.content || 'No text provided';
const truncated = reviewText.length > maxLength ? reviewText.substring(0, maxLength) + '...' : reviewText;

// Build Slack Block Kit message
const isUrgent = rating <= 2;
const headerText = isUrgent 
  ? `🚨 URGENT: New ${rating}-Star Review on ${review.source || 'Unknown Platform'}`
  : `${emoji} New ${rating}-Star Review on ${review.source || 'Unknown Platform'}`;

const slackMessage = {
  text: headerText,
  blocks: [
    {
      type: 'header',
      text: { type: 'plain_text', text: headerText, emoji: true }
    },
    {
      type: 'section',
      fields: [
        { type: 'mrkdwn', text: `*Rating:* ${emoji} ${rating}/5` },
        { type: 'mrkdwn', text: `*Platform:* ${review.source || 'N/A'}` },
        { type: 'mrkdwn', text: `*Date:* ${review.date || new Date().toLocaleDateString()}` },
        { type: 'mrkdwn', text: `*Location:* ${review.location || 'Primary'}` }
      ]
    },
    {
      type: 'section',
      text: { type: 'mrkdwn', text: `>_\"${truncated}\"_` }
    }
  ]
};

if (isUrgent) {
  slackMessage.blocks.push({
    type: 'section',
    text: { type: 'mrkdwn', text: '⏰ *This review requires a response within 4 hours.* Please review and respond promptly.' }
  });
}

if (review.review_url) {
  slackMessage.blocks.push({
    type: 'actions',
    elements: [{
      type: 'button',
      text: { type: 'plain_text', text: '📝 Respond to Review', emoji: true },
      url: review.review_url,
      style: isUrgent ? 'danger' : 'primary'
    }]
  });
}

output = [{ slack_message: JSON.stringify(slackMessage) }];

python -c "import json; json.load(open('output/analysis.json'))"