A three-part system that captures Discord conversations, analyzes them for themes, and displays real-time insights.

Discord → Part 1 (Bot) → Redis → Part 2 (Intelligence) → Redis → Part 3 (Dashboard)
                ↓                         ↓                          ↓
          Audio + Text              Theme Analysis            Web Interface

• Python 3.10+
• Docker & Docker Compose (optional but handy for long-lived services)
• Discord Bot Token with voice permissions (Connect, Speak, Use Voice Activity, Send Messages)
• OpenAI API key (required for the LangChain synthesis step; optional for transcription if you run Whisper locally)

1. Go to the Discord Developer Portal and create a new application.
2. Add a Bot, reset the token, and copy it for your .env.
3. Enable MESSAGE CONTENT INTENT so the bot can see chat text.
4. Under OAuth2 → URL Generator, check bot scope and grant the permissions listed above, then invite the bot to your server.
5. Create one voice channel per table so Chromebooks can join independently during the session.

git clone <repository>
cd clearness

cp .env.example .env
# edit .env with at least:
# DISCORD_BOT_TOKEN=...
# OPENAI_API_KEY=...
# TRANSCRIPTION_PROVIDER=openai|local

• TRANSCRIPTION_PROVIDER=openai keeps transcription in the cloud. Only the server needs the API key.
• TRANSCRIPTION_PROVIDER=local loads Whisper on this machine. Set WHISPER_MODEL=tiny|base|small|medium depending on available GPU.

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# Terminal 1: Discord ingestion
python bot/transcription_bot.py

# Terminal 2: Intelligence processor
python synthesis/intelligence_processor.py

# Terminal 3: Dashboard UI
python dashboard.py

Prefer containers? docker-compose up -d launches Redis, the bot, the processor, and the dashboard together.

1. Join each table’s Discord voice channel from its Chromebook.
2. In every channel, type !join so the bot starts recording. Use !status to confirm chunks are flowing.
3. Open http://localhost:8000 on the facilitator machine. The Table Updates card shows one summary per channel alongside the global synthesis and bridge concepts.
4. When a table is done, use !leave in that channel to disconnect.

• File: transcription_bot.py
• Function: Captures voice and text from Discord
• Output: Sends to transcription_queue in Redis
• Providers: Local Whisper, OpenAI API, or Ollama

• File: intelligence_processor.py
• Function: Analyzes messages for themes using LangChain
• Input: Reads from transcription_queue
• Output: Sends to intelligence_queue
• Features: Theme identification, bridge concepts, synthesis

• File: dashboard.py
• Function: Web interface for viewing insights
• Input: Reads from intelligence_queue
• Features: Live updates, theme visualization, Discord notifications

# Test Part 1 (Discord Bot)
python test_suite.py discord

# Test Part 2 (Intelligence)
python test_suite.py intelligence

# Test Part 3 (Dashboard)
python test_suite.py dashboard

# Test Complete Pipeline
python test_suite.py pipeline

All configuration is done through .env file:

# Discord
DISCORD_BOT_TOKEN=your_token_here

# OpenAI (optional)
OPENAI_API_KEY=your_key_here

# Transcription
TRANSCRIPTION_PROVIDER=local  # local, openai, ollama
WHISPER_MODEL=base            # tiny, base, small, medium, large

# Intelligence Processing
LLM_PROVIDER=openai           # openai, local
EMBEDDING_PROVIDER=openai     # openai, local
SYNTHESIS_INTERVAL=30         # seconds
MAX_THEMES=5

# Dashboard (optional)
DISCORD_WEBHOOK_URL=your_webhook_url

• Dashboard: http://localhost:8000
• API Health: http://localhost:8000/api/health
• Logs: docker-compose logs -f [service-name]

1. Discord → Redis

   • Text messages and voice transcriptions
   • Format: {type, content, username, channel, timestamp}

2. Redis → Intelligence

   • Processes every 30 seconds
   • Identifies themes and connections
   • Format: {themes, bridge_concepts, summary}

3. Redis → Dashboard

   • Real-time WebSocket updates
   • REST API for historical data

From Discord Bot:

{
  "type": "voice_transcription",
  "content": "I think we should use AI for code reviews",
  "username": "Alice",
  "channel": "dev-talk",
  "timestamp": "2024-01-20T10:30:00Z"
}

From Intelligence Processor:

{
  "themes": [
    {
      "title": "AI in Development",
      "description": "Discussion about AI tools for coding",
      "keywords": ["AI", "code review", "automation"],
      "confidence": 0.85
    }
  ],
  "bridge_concepts": [...],
  "summary": "Active discussion about integrating AI into development workflows"
}

• Check bot has voice permissions in Discord
• Verify !join command in a voice channel

• Check !status shows recording
• Verify transcription provider is configured
• Check logs: docker-compose logs discord-bot

• Ensure enough messages (minimum 5)
• Check intelligence processor logs
• Verify OpenAI API key if using OpenAI

• Check WebSocket connection in browser console
• Verify Redis is running: docker-compose ps
• Check dashboard logs

• Reduce Whisper model size for faster transcription
• Increase SYNTHESIS_INTERVAL to reduce processing frequency
• Use local embeddings to avoid API costs
• Adjust MESSAGE_BUFFER_SIZE based on activity level

# Run services individually for development
docker-compose up redis
python transcription_bot.py
python intelligence_processor.py
python dashboard.py

# Or use development mode
docker-compose -f docker-compose.dev.yml up

MIT