Vibe — Discord Sentiment Intelligence Suite 📊✨

Know the mood. Own the room.

A full-stack suite for real-time and retrospective Discord sentiment analysis. Includes a live Discord bot, a premium web dashboard, and a powerful offline CLI analyzer with AI-powered deep analysis.

---

📦 Components

Component	File	Purpose
Live Bot	vibe_backend/bot.py	Monitors Discord channels in real-time, streams sentiment data to the dashboard
Web Dashboard	public/dashboard.html + vibe_backend/server.py	Flask/Socket.IO powered live analytics UI
Offline Analyzer	discord_analyzer.py	Historical analysis CLI with AI, comparisons, crisis detection, and more
Sentiment Engine	vibe_backend/sentiment_engine.py	VADER + Gemini/Ollama dual-engine sentiment core
Database	vibe_backend/database.py	SQLite async persistence layer with auto-cleanup
Health Monitor	/health	Live diagnostic endpoint for DB and engine status

---

🚀 Quick Start

1. Install Dependencies

pip install -r requirements.txt

2. Configure Environment

cp .env.example .env
# Edit .env with your tokens and API keys (see "Configuration" below)

3. Launch Everything

python run.py

Or start individually:

# Terminal 1: Dashboard server
python -m vibe_backend.server

# Terminal 2: Discord bot
python -m vibe_backend.bot

Open http://localhost:8000 in your browser.

---

🤖 Live Discord Bot (bot.py)

The bot sits in your Discord server, scores every message in real-time, and streams data to the web dashboard.

Bot Commands

Command	Description
!track / !vibe	Enable Vibe tracking for the current channel
!untrack	Disable tracking for the current channel
!ping	Test bot latency with a sentiment-aware response
!vibecheck	Catchy AI summary of the current chat mood
!stats	Sentiment statistics for the current channel
!report	Generate a brief AI sentiment report
!leaderboard	Show the most positive and active users
!topics	List trending topics and their sentiment
!recap #channel	Enable daily AI vibe recap in a specific channel
!recapoff	Disable the daily AI vibe recap
!vibeofday	Manually trigger today's AI recap right now
!vibetotal	View a channel-wide historical vibe legacy
!mood [@user]	Analyze a specific user's recent vibe snapshot
!personality [@user]	Generate Big Five traits for a user
!teach [word] [lore]	Teach the bot server-specific context/inside jokes
!summary [N]	Summarize the last N messages with AI (default: 15)
!deepdive [on/off]	Toggle Deep-Dive analysis mode
!viberoles [on/off]	Toggle automatic Vibe Roles assignment
!history [user]	View a user's recent mood journey
!help	Show all commands

Key Bot Features

• Sentiment Velocity Alerts: Automatically warns the channel if sentiment drops sharply (-0.5 pts) over a short window, allowing moderators to intervene before a crisis.
• Persistent Daily Snapshots: Saves daily leaderboard and topic data to the database, powering a 7-day historical trend view on the web dashboard.
• Enriched Daily Recap: Posts a comprehensive AI-generated summary every 24 hours including the "MVP of the day" and hot topics.
• Command Rate Limiting: Built-in per-user cooldowns for intensive commands to prevent API spam and ensure stability.
• Log Rotation: Automatic rotation of vibe_system.log (5MB limit, 3 backups) to prevent unbound disk usage.
• Adaptive Batching: Intelligently groups AI calls to minimize API usage.
• Vibe Roles: Automatically rewards consistent positive users with a "Positive Force" Discord role.
• Pulse Check: Periodically generates AI mood summaries for active channels.
• Edit Detection: Re-analyzes messages when edited in Discord.
• Delete Sync: Purges messages from the dashboard when deleted from Discord.
• Image Intelligence (Vision): Analyze image attachments and webp/png/jpg uploads using AI vision insights (if enabled).
• Lore Memory: Command !teach allows adding server-specific context that the AI uses to better understand internal jokes or history.
• Principal Systems Security: Hardened path resolution and file safety wrappers prevent directory traversal and injection attacks.
• Plugin System: Drop .py files into vibe_backend/plugins/ for custom commands.

---

🎨 Web Dashboard

Access via http://localhost:8000 (requires login with your configured SECRET_KEY).

Features

• Live Feed: Real-time message stream with sentiment badges, topic tags, and AI insights
• Sentiment Trend Chart: Scrolling compound score line chart with SMA smoothing
• Channel Switcher: Filter the entire dashboard view by Discord channel
• User Profiles: Per-author vibe scores, archetype labels, and message counts
• Pulse Panel: AI-generated channel mood summaries (updated automatically)
• Reanalyze: Manually trigger a full deep-AI re-scan of any channel's history
• Reports Tab: Topic frequency pie chart and per-author bar chart
• File Analysis: Drag-and-drop any .json or .txt log file to visualize offline data
• Light/Dark Mode: Full theme switching with system preference detection
• Lore Management: View and delete taught server context via the web API.
• AI Status Dashboard: Monitor the live state of the sentiment engine and circuit breakers.
• Export: Download the current channel's data as JSON

---

🛰️ Offline Analyzer (discord_analyzer.py)

A standalone CLI tool for deep historical analysis. Works on live Discord data (via token) or local log files.

Basic Usage

# Interactive channel picker (fetches live from Discord)
python discord_analyzer.py --token YOUR_TOKEN

# Analyze a specific channel
python discord_analyzer.py --token YOUR_TOKEN --channel-id 123456789

# Analyze a local file (Discord export, Twitch CSV, generic TXT)
python discord_analyzer.py --file export.txt

# Generate a beautiful standalone HTML report
python discord_analyzer.py --file export.txt --html

# View an existing JSON report
python discord_analyzer.py --report sentiment_general.json -v

# Launch ITA Interactive Agent after analysis
python discord_analyzer.py --token YOUR_TOKEN -ita

All CLI Flags

Flag	Default	Description
-t, --token	.env	Discord user or bot token
-c, --channel-id	—	Skip the channel picker
-l, --limit	1000	Max messages to fetch
-o, --out	auto	Output JSON filename
-v, --view	off	Print summary to terminal
-r, --report	—	Load and view an existing JSON
-f, --file	—	Parse a local log file
--html	off	Generate a standalone HTML report
-w, --watch	off	Re-sync every 10 minutes
-ita	off	Launch ITA interactive chat agent
-j, --concurrency	2	Parallel AI requests
-b, --batch-size	0 (auto)	AI messages per batch
--color	cyan	Terminal chart accent color

---

⚗️ Advanced Analysis Modes

--compare — A/B Community Diff

Compare two reports side-by-side with a full statistical breakdown.

python discord_analyzer.py --compare server_a.json server_b.json
python discord_analyzer.py --compare gaming.json study.json --compare-out diff.html

Output includes:

• Toxicity delta & healthier community verdict
• Side-by-side avg sentiment, message counts, std deviation
• Community archetype distribution (Anchor / Supporter / Chaos Agent / Lurker)
• Shared vs unique topics per community
• Divergent Vocabulary: same words carrying opposite emotional charge in each community

---

--merge — Temporal Multi-Report Fusion

Combine multiple time-period reports into a single chronological mega-report with week-over-week trend analysis.

python discord_analyzer.py --merge jan.json feb.json mar.json --merge-out q1.json

Output includes:

• Chronologically merged message timeline
• ASCII week-over-week sentiment bar chart
• A unified JSON, compatible with the dashboard drag-and-drop

---

--crises — Crisis Event Extractor

Automatically identify the worst moments in a channel's history using sliding-window detection.

python discord_analyzer.py --crises report.json
python discord_analyzer.py --crises report.json --html   # also saves an HTML report

Output includes:

• Top 10 crisis windows ranked by severity
• Timestamp range, average score, trigger author, trigger message, and topic for each
• Deduplication of overlapping windows

---

--ghosts — Silent After Crisis Detector

Find active community members who completely disappeared following a crisis event — the ones you lost.

python discord_analyzer.py --ghosts report.json

Output includes:

• All previously active users (3+ messages) with zero post-crisis activity
• Their last seen timestamp, last message score, last topic
• Their average sentiment during the crisis period (how they were feeling when they left)

---

🧠 AI Intelligence

The VADER + AI dual-engine approach provides both speed and depth.

Engine	When Used	Capability
VADER	Always (fallback)	Fast rule-based lexical scoring
Google Gemini (default)	When GOOGLE_API_KEY is set	Context-aware, sarcasm-aware, hyperbole-aware
Ollama	When Gemini unavailable	Local LLM fallback

Prompt Engineering Built-In

The AI analyzer follows a set of community-calibrated rules:

• Resolution Rule: A problem-then-fix sequence scores the fix as dominant
• Gaming Hyperbole: "I'll murder you in PvP" is scored NEUTRAL, not NEGATIVE
• Contextual ok: "ok" after a victory → positive. "ok" after a complaint → neutral.

---

⚙️ Configuration (.env)

# Copy this to .env and fill in your values
DISCORD_TOKEN=your_bot_token
USER_TOKEN=your_user_token_for_analyzer   # optional, for analyzing DMs if you don't want to use -t in analyzer
DASHBOARD_URL=http://localhost:8000
PORT=8000
SECRET_KEY=change-me-in-production
GOOGLE_API_KEY=your_google_ai_key
GEMINI_MODEL=gemma-3-27b-it
USE_GEMINI_AS_DEFAULT=True
OLLAMA_MODEL=gemma:2b

# ── Bot Settings ─────────────────────────────────────────────────────────────
BOT_PREFIX=!
PULSE_INTERVAL_MINS=5
HISTORY_LIMIT=50

---

📁 Supported Input Formats (-f)

Format	Extension	Notes
Discord JSON Export	.json	Via DiscordChatExporter
Vibe Report JSON	.json	Output from this tool
Twitch CSV	.csv	Via TwitchDownloader
Generic Chat TXT	.txt	[Timestamp] Author: Message format
Discord TXT Export	.txt	Multi-line message blocks

---

🔑 Getting Tokens

Bot Token (for bot.py and analyzer with bot permissions)

1. Go to the Discord Developer Portal
2. Select your app → Bot tab → Reset Token
3. Enable Message Content Intent under Privileged Gateway Intents
4. Invite the bot with Send Messages, Read Message History, and Manage Roles permissions

User Token (for analyzing DMs — personal research use only)

⚠️ Self-botting is against Discord ToS. Use only for personal research on your own accounts.

1. Open Discord in a browser → F12 → Network tab
2. Send any message → find the messages request
3. Copy the Authorization header value → paste into .env as USER_TOKEN

---

🔌 Plugin System

Drop a .py file into vibe_backend/plugins/ to add custom bot commands. The bot auto-loads any file in that directory on startup.

---

📊 Report JSON Schema

All analysis outputs produce a standard JSON report:

{
  "channel": { "id": "...", "name": "...", "type": "server|dm|group|merged" },
  "generated_at": "2026-03-06T12:00:00Z",
  "total_messages": 1000,
  "avg_compound": 0.1234,
  "label_counts": { "positive": 400, "neutral": 500, "negative": 100 },
  "top_authors": [ { "author": "...", "messages": 50, "avg_compound": 0.3 } ],
  "alerts": [ { "author": "...", "text": "...", "score": -0.9, "reason": "Intensity" } ],
  "messages": [ { "author": "...", "text": "...", "compound": -0.5, "label": "negative", "topic": "...", "drivers": "...", "ai_analysis": "..." } ]
}

Any report file can be dragged directly into the web dashboard's File Analysis tab.

---

Built with ❤️ using Discord.py, Flask, Socket.IO, VADER, Google Gemini, and Rich.