discord_rcd_ai_bot/README.md

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