KI-Chat-Bot-Eugen/README.md

Eugen - Intelligent Twitch Chat Bot

An AI-powered Twitch chat bot specializing in Gaming and 3D Printing topics, powered by Perplexity Sonar API.

Features

• Smart Name Recognition: Automatically responds when mentioned (@Eugen, Eugen:, etc.)
• Persistent Memory: Maintains conversation history per user (max 25 messages)
• Context-Aware: Remembers previous conversations for up to 1 hour
• Perplexity Integration: Uses Perplexity Sonar API for intelligent, real-time responses
• Live Dashboard: GUI monitoring interface showing all activity in real-time
• Topics: Gaming (WoW, Elden Ring), 3D Printing (Prusa, Bambu, Creality), Tech (Python, Linux)

Quick Start

Prerequisites

• Python 3.9+ (3.11+ recommended)
• Twitch account for the bot
• Perplexity API key

Installation

# Clone the repository
git clone https://github.com/Kenearos/KI-Chat-Bot-Eugen.git
cd KI-Chat-Bot-Eugen

# Create virtual environment
python -m venv venv

# Activate virtual environment
# On Windows:
.\venv\Scripts\Activate.ps1
# On Linux/Mac:
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

Configuration

Option 1: Setup Wizard (Recommended)

Run the interactive setup wizard to configure the bot:

python setup_wizard.py

The wizard will:

• Guide you through getting Twitch OAuth token
• Help you set up Perplexity API key
• Validate your credentials
• Create necessary directories and config files

Option 2: Manual Configuration

Copy .env.example to .env and fill in your credentials:

cp .env.example .env

Edit .env with your values:

TWITCH_OAUTH_TOKEN=oauth:your_token_here
TWITCH_BOT_NICKNAME=Eugen
TWITCH_CHANNEL=#your_channel_here
PERPLEXITY_API_KEY=pplx-your_key_here

Getting API Keys

Twitch OAuth Token:

1. Visit twitchtokengenerator.com
2. Generate token with chat:read and chat:edit scopes
3. Copy the token (should start with oauth:)

Perplexity API Key:

1. Visit perplexity.ai/api
2. Sign up/Login
3. Generate new API key
4. Copy the key (should start with pplx-)

Testing Credentials (Recommended)

Before running the bot, test your credentials:

python test_credentials.py

This will:

• Validate your Twitch OAuth token with detailed diagnostics
• Test your Perplexity API key and check model access
• Provide specific error messages and fixes for common issues
• Automatically detect if sonar-pro is unavailable and suggest sonar fallback

Example output:

✓ Twitch IRC:      PASS
✓ Perplexity API:  PASS
🎉 All credentials valid! Bot is ready to run.

Running the Bot

python chatbot.py

The dashboard will open automatically showing live activity.

Usage

Once running, the bot responds when mentioned in Twitch chat:

User: @Eugen what's the best class in WoW?
Eugen: @User The best class depends on your playstyle...

User: Eugen, how do I level my 3D printer?
Eugen: @User For bed leveling, start by...

Project Structure

eugen/
├── chatbot.py          # Main entry point
├── setup_wizard.py     # Interactive setup tool
├── test_credentials.py # Credential validator
├── config.py           # Configuration management
├── gui.py              # Dashboard GUI
├── ai_provider.py      # Perplexity API integration
├── memory.py           # Conversation memory
├── utils.py            # Helper functions
├── requirements.txt    # Python dependencies
├── .env               # Your secrets (DO NOT COMMIT)
├── data/
│   └── conversations/ # User chat histories
└── logs/
    ├── eugen.log      # Main log
    └── api_debug.log  # API debug logs

Documentation

• CLAUDE.md: Quick reference guide for Claude Code
• eugen_claude.md: Detailed German documentation with architecture and implementation details

Development

The bot is built with:

• Python 3.9+
• Perplexity Sonar API for AI responses
• Twitch IRC for chat integration
• PySimpleGUI for dashboard
• Async/await for concurrent operations

Troubleshooting

Quick Diagnosis

First step: Run the credential validator

python test_credentials.py

This will identify exactly what's wrong and provide specific fixes.

Common Issues

Twitch OAuth Token Invalid:

• ✗ Error: Login authentication failed
• Fix:
  1. Go to https://twitchtokengenerator.com
  2. Select "Bot Chat Token"
  3. Make sure you're logged in as the bot account
  4. Copy the new token (including oauth: prefix)
  5. Update TWITCH_OAUTH_TOKEN in .env

Bot nickname mismatch:

• Token must be generated by the same account as TWITCH_BOT_NICKNAME
• If bot nickname is EugenBot, you must be logged into Twitch as EugenBot when generating the token

Perplexity Model Not Available:

• ✗ Error: 400 Bad Request or model not accessible
• Fix:
  • Your API key might not have access to sonar-pro
  • The setup wizard will automatically suggest sonar as fallback
  • Or manually change PERPLEXITY_MODEL=sonar in .env

Bot doesn't respond in chat:

• Run python test_credentials.py to verify credentials
• Check that bot is in the correct channel
• Check logs/eugen.log for errors
• Verify bot was mentioned correctly (@Eugen or Eugen:)

IRC connection failed:

• Check internet connection
• Verify firewall allows port 6667
• Run credential validator for detailed diagnostics

API rate limits:

• Check your Perplexity API credits at https://www.perplexity.ai/settings/api
• Enable DEBUG_MODE=true in .env for detailed API logs

License

See LICENSE file for details.

Contributing

Contributions welcome! Please open an issue or pull request.