CLAUDE.md - Project Guide for Claude Code

Project Overview

Eugen is an intelligent Twitch chat bot for gaming and 3D printing topics. The bot uses the Perplexity Sonar API for AI-powered responses and features persistent conversation memory per user.

Core Functionality

Responds when mentioned in chat (@Eugen, Eugen:, etc.)
Maintains conversation history per user (max 25 messages)
Integrates with Perplexity API for intelligent responses
Provides a GUI dashboard for live monitoring

Primary Topics

Gaming: World of Warcraft, Elden Ring, Gamedev
3D Printing: Prusa i3, Bambu, Creality
Tech: Python, Linux, Home Automation

Tech Stack

Language: Python 3.9+ (recommended 3.11+)
AI Provider: Perplexity API (sonar-pro model)
Chat Protocol: Twitch IRC
GUI Framework: FreeSimpleGUI 5.1+ (community fork, no license required)
Platform: Windows-native (no Linux tools required)

Project Structure

eugen/
├── chatbot.py              # Main entry point
├── config.py               # Configuration management
├── gui.py                  # Dashboard GUI
├── ai_provider.py          # Perplexity API integration
├── memory.py               # Conversation memory storage
├── utils.py                # Helper functions (MentionDetector, Logger)
├── requirements.txt        # Python dependencies
├── .env                    # Secrets (DO NOT COMMIT)
│
├── data/
│   ├── conversations/      # Per-user chat histories (*.json)
│   └── config.json         # Saved configuration
│
└── logs/
    ├── eugen.log           # Main log file
    └── api_debug.log       # API debug logs

Key Components

Classes

EugenBot - Main orchestrator for IRC, Memory, AI, and GUI
MentionDetector - Detects bot mentions in chat messages
ConversationMemory - Stores/loads chat history per user
PerplexityProvider - Handles Perplexity API communication
Dashboard - PySimpleGUI-based live monitoring interface
Config - Loads configuration from .env and config.json

Message Flow

Chat message received via IRC
MentionDetector checks if bot was addressed
ConversationMemory loads user's last 5 messages
Prompt built with system prompt + history + current message
API call to Perplexity Sonar
Response saved to memory and sent to chat
Dashboard updated with event

Development Guidelines

Dependencies

irc==20.1.0
python-dotenv==1.0.0
FreeSimpleGUI==5.1.1
requests==2.31.0
httpx==0.25.0

Environment Variables (.env)

TWITCH_OAUTH_TOKEN=oauth:xxxxx
TWITCH_BOT_NICKNAME=Eugen
TWITCH_CHANNEL=#channel_name
PERPLEXITY_API_KEY=pplx-xxxxx
PERPLEXITY_MODEL=sonar-pro
MAX_TOKENS=450
DEBUG_MODE=true

Important Notes

Never commit .env or files containing API keys
User conversation files are stored as JSON in data/conversations/
Context retention is limited to 1 hour by default
Max tokens for responses: 450 (Twitch chat limit consideration)

Common Commands

# Setup virtual environment
python -m venv venv
.\venv\Scripts\Activate.ps1  # Windows PowerShell

# Install dependencies
pip install -r requirements.txt

# Run the bot
python chatbot.py

Testing API Keys

Twitch: Test IRC connection to irc.chat.twitch.tv:6667
Perplexity: POST to https://api.perplexity.ai/chat/completions with a simple test message

Error Handling

Common issues:

Invalid Twitch Token: Regenerate at twitchtokengenerator.com
Perplexity API 401: Check API key validity and account credits
IRC Connection Failed: Check firewall rules for port 6667
Rate Limiting: Built-in auto-retry after 60 seconds

Language Note

This project's documentation (eugen_claude.md) is in German. The bot is designed for German-speaking Twitch communities but can be adapted for other languages.

3.8 KiB Raw Blame History