274 lines
6.2 KiB
Markdown
274 lines
6.2 KiB
Markdown
# Discord GLHF Bot
|
|
|
|
A robust, bug-free Discord bot using OpenAI-compatible APIs with comprehensive fallback systems and message queueing.
|
|
|
|
## Core Features
|
|
|
|
- Full OpenAI API compatibility
|
|
- Image analysis capabilities
|
|
- Multiple fallback APIs (4 backup APIs)
|
|
- Automatic health checks every 10 minutes
|
|
- Dynamic API switching based on health status
|
|
- Message queueing with context preservation
|
|
- Complete data sanitization
|
|
- Comprehensive error handling
|
|
- Zero data loss guarantees
|
|
|
|
### Image Analysis
|
|
- Support for image attachments and URLs
|
|
- Detailed image content analysis
|
|
- Grumpy personality with judgmental observations
|
|
- Automatic vision model selection
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
# Clone the repository
|
|
git clone [repository-url]
|
|
cd discord_glhf
|
|
|
|
# Install dependencies using uv
|
|
uv pip install -r requirements.txt
|
|
```
|
|
|
|
## Configuration
|
|
|
|
All configuration is done through environment variables. Create a `.env` file:
|
|
|
|
```env
|
|
# Required Environment Variables
|
|
DISCORD_TOKEN=your_discord_bot_token
|
|
GLHF_API_KEY=your_primary_api_key
|
|
BOT_OWNER_ID=your_discord_user_id
|
|
|
|
# Primary API Configuration (Required)
|
|
API_KEY=your_api_key # Your API key
|
|
API_BASE_URL=https://api.example.com/v1 # API base URL
|
|
API_MODEL=gpt-3.5-turbo # Default model to use
|
|
API_TIMEOUT=30.0 # Request timeout (optional)
|
|
API_MAX_RETRIES=3 # Number of retries (optional)
|
|
|
|
# Vision API Configuration (Required for image analysis)
|
|
VISION_API_KEY=your_vision_api_key # Separate API key for vision
|
|
VISION_API_BASE_URL=https://api.example.com/v1 # Vision API endpoint
|
|
VISION_MODEL=gpt-4-vision-preview # Vision-capable model
|
|
VISION_TIMEOUT=30.0 # Vision timeout (optional)
|
|
VISION_MAX_RETRIES=3 # Vision retries (optional)
|
|
MAX_VISION_TOKENS=1000 # Max tokens (optional)
|
|
|
|
# Fallback APIs (Optional)
|
|
FALLBACK{n}_API_KEY=your_fallback_api_key
|
|
FALLBACK{n}_BASE_URL=https://fallback.api.url/v1
|
|
FALLBACK{n}_MODEL=gpt-3.5-turbo
|
|
|
|
# Optional Configuration with Defaults
|
|
API_HEALTH_CHECK_INTERVAL=600 # 10 minutes
|
|
CIRCUIT_BREAKER_FAILURE_THRESHOLD=5
|
|
CIRCUIT_BREAKER_RECOVERY_TIMEOUT=60.0
|
|
CIRCUIT_BREAKER_HALF_OPEN_TIMEOUT=30.0
|
|
STREAM_REQUEST_TIMEOUT=60.0
|
|
MAX_STREAMING_ATTEMPTS=2
|
|
RATE_LIMIT_BACKOFF_TIME=60
|
|
```
|
|
|
|
## Safety Features
|
|
|
|
### 1. Message Sanitization
|
|
- HTML escaping for all content
|
|
- Markdown sanitization
|
|
- Mention sanitization
|
|
- Control character removal
|
|
- Length validation
|
|
- Content validation
|
|
|
|
### 2. Database Safety
|
|
- Connection pooling with automatic cleanup
|
|
- Transaction safety with rollback
|
|
- Prepared statements for all queries
|
|
- Input validation
|
|
- UUID validation
|
|
- Data integrity checks
|
|
- Automatic cleanup of old data
|
|
|
|
### 3. Queue Safety
|
|
- Priority-based message ordering
|
|
- Message deduplication
|
|
- Abandoned message cleanup
|
|
- Rate limiting per user
|
|
- Queue size limits
|
|
- Error recovery
|
|
- Request timeout handling
|
|
|
|
### 4. API Safety
|
|
- Health checks every 10 minutes
|
|
- Automatic failover to healthy APIs
|
|
- Circuit breaker pattern
|
|
- Rate limit handling
|
|
- Error recovery
|
|
- Request timeout handling
|
|
- Response validation
|
|
|
|
### 5. Context Preservation
|
|
- Complete message context storage
|
|
- Thread tracking
|
|
- User context preservation
|
|
- Channel context preservation
|
|
- Metadata storage
|
|
- Reference tracking
|
|
|
|
## Message Flow
|
|
|
|
1. Message Reception
|
|
- Content sanitization
|
|
- Mention resolution
|
|
- Context capture
|
|
- Priority assignment
|
|
|
|
2. Queue Processing
|
|
- Priority-based ordering
|
|
- Rate limiting
|
|
- User quota management
|
|
- Abandoned message cleanup
|
|
|
|
3. Database Operations
|
|
- Transaction safety
|
|
- Data validation
|
|
- Context storage
|
|
- Thread tracking
|
|
|
|
4. API Interaction
|
|
- Health checking
|
|
- Automatic failover
|
|
- Circuit breaking
|
|
- Error handling
|
|
|
|
5. Response Handling
|
|
- Content sanitization
|
|
- Context preservation
|
|
- Safe delivery
|
|
- Error recovery
|
|
|
|
## Error Handling
|
|
|
|
1. Database Errors
|
|
- Transaction rollback
|
|
- Connection recovery
|
|
- Data validation errors
|
|
- Constraint violations
|
|
|
|
2. API Errors
|
|
- Rate limits
|
|
- Timeouts
|
|
- Invalid responses
|
|
- Network errors
|
|
|
|
3. Discord Errors
|
|
- Permission issues
|
|
- Network problems
|
|
- Rate limits
|
|
- Message delivery failures
|
|
|
|
4. Queue Errors
|
|
- Overflow handling
|
|
- Timeout recovery
|
|
- Priority conflicts
|
|
- Resource exhaustion
|
|
|
|
## Monitoring
|
|
|
|
The bot includes comprehensive monitoring:
|
|
|
|
1. Health Metrics
|
|
- API status
|
|
- Queue length
|
|
- Processing times
|
|
- Error rates
|
|
|
|
2. Error Reporting
|
|
- Detailed error context
|
|
- Stack traces
|
|
- User context
|
|
- System state
|
|
|
|
3. Performance Metrics
|
|
- Response times
|
|
- Queue latency
|
|
- API latency
|
|
- Database performance
|
|
|
|
## Running the Bot
|
|
|
|
```bash
|
|
# Start the bot
|
|
uv run discord_glhf.py
|
|
```
|
|
|
|
The bot will:
|
|
1. Initialize database connections
|
|
2. Start health check system
|
|
3. Initialize message queue
|
|
4. Connect to Discord
|
|
5. Begin processing messages
|
|
|
|
## Shutdown Process
|
|
|
|
The bot implements a graceful shutdown process:
|
|
|
|
1. Stop accepting new messages
|
|
2. Complete processing of queued messages
|
|
3. Close API connections
|
|
4. Close database connections
|
|
5. Clean up resources
|
|
|
|
## Debugging
|
|
|
|
For debugging, the bot provides:
|
|
|
|
1. Detailed logging
|
|
2. Error reporting to bot owner
|
|
3. State inspection
|
|
4. Queue inspection
|
|
5. Database inspection
|
|
|
|
## Best Practices
|
|
|
|
1. Always use environment variables for configuration
|
|
2. Never hardcode sensitive values
|
|
3. Keep the database clean with regular maintenance
|
|
4. Monitor error logs
|
|
5. Update API configurations as needed
|
|
|
|
## Requirements
|
|
|
|
- Python 3.8+
|
|
- Discord.py
|
|
- SQLite 3
|
|
- UV package manager
|
|
- Environment variables properly configured
|
|
|
|
## Safety Checklist
|
|
|
|
Before deploying:
|
|
|
|
1. ✓ Environment variables set
|
|
2. ✓ Database initialized
|
|
3. ✓ API keys validated
|
|
4. ✓ Permissions configured
|
|
5. ✓ Error reporting configured
|
|
6. ✓ Monitoring set up
|
|
7. ✓ Backup APIs configured
|
|
8. ✓ Rate limits configured
|
|
9. ✓ Queue limits set
|
|
10. ✓ Cleanup intervals configured
|
|
|
|
## Maintenance
|
|
|
|
Regular maintenance tasks:
|
|
|
|
1. Database cleanup (automatic)
|
|
2. Log rotation (automatic)
|
|
3. API health checks (automatic)
|
|
4. Queue monitoring (automatic)
|
|
5. Error log review (manual)
|
|
|
|
The bot is designed to be completely bug-free and production-ready, with comprehensive safety features and error handling at every level. |