# 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**: PySimpleGUI
- **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
1. Chat message received via IRC
2. MentionDetector checks if bot was addressed
3. ConversationMemory loads user's last 5 messages
4. Prompt built with system prompt + history + current message
5. API call to Perplexity Sonar
6. Response saved to memory and sent to chat
7. Dashboard updated with event

## Development Guidelines

### Dependencies
```
perplexity-python-client==1.0.0
irc==20.1.0
python-dotenv==1.0.0
PySimpleGUI==4.60.0
requests==2.31.0
httpx  # For async API calls
```

### 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

```bash
# 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.