# AI Job Queue System Implementation

## Overview

This implementation adds an asynchronous job queue system for AI content and image generation in Essential Blocks to prevent AJAX timeout issues when OpenAI API responses take too long.

## Architecture

### 1. JobManager Class (`includes/Integrations/AI/JobManager.php`)

**Purpose**: Manages background jobs for AI generation tasks

**Key Features**:
- Job creation with unique UUIDs
- Status tracking (pending, processing, completed, failed, expired)
- WordPress options table storage
- Automatic cleanup of expired jobs
- Background processing via WordPress cron

**Job Statuses**:
- `pending`: Job created, waiting to be processed
- `processing`: Job is currently being executed
- `completed`: Job finished successfully
- `failed`: Job encountered an error
- `expired`: Job exceeded maximum lifetime (5 minutes)

### 2. AJAX Handlers (`includes/Integrations/AI/AI.php`)

**New Endpoints**:
- `start_ai_job`: Creates and schedules a new AI job
- `check_ai_job_status`: Polls job status and returns results

**Security**: Both endpoints use WordPress nonce verification and capability checks

### 3. Frontend Components

#### AIContentPopover.js
- Modified to use job-based workflow
- Implements polling every 3 seconds
- Maximum polling time: 5 minutes
- Handles all job statuses appropriately

#### AIImagePopover.js
- Modified to use job-based workflow
- Implements polling every 5 seconds (longer for image generation)
- Maximum polling time: 5 minutes
- Maintains existing image processing logic

## Workflow

### Content Generation
1. User clicks "Generate Now"
2. Frontend calls `start_ai_job` with `job_type: 'content'`
3. Backend creates job and schedules immediate processing
4. Frontend starts polling `check_ai_job_status` every 3 seconds
5. When job completes, result is returned and job is cleaned up

### Image Generation
1. User clicks "Generate Images"
2. Frontend calls `start_ai_job` with `job_type: 'image'`
3. Backend creates job and schedules immediate processing
4. Frontend starts polling `check_ai_job_status` every 5 seconds
5. When job completes, images are returned and job is cleaned up

## Error Handling

### Timeout Management
- Jobs expire after 5 minutes maximum
- Stuck jobs are cleaned up hourly
- Frontend stops polling after 5 minutes

### Error Recovery
- Failed jobs store error messages
- Network errors during polling are handled gracefully
- User-friendly error messages displayed

### Cleanup
- Completed jobs are deleted after 5 seconds
- Expired jobs are cleaned up daily
- Stuck processing jobs are cleaned up hourly
- Plugin deactivation clears all scheduled events

## Installation & Setup

### 1. Files Added/Modified

**New Files**:
- `includes/Integrations/AI/JobManager.php` - Job management utility class
- `includes/Integrations/AI/AI.php` - AI integration class with AJAX handlers
- `includes/Integrations/AI/OpenAI.php` - OpenAI API integration class
- `test-ai-job-system.php` - Test script for validation

**Modified Files**:
- `includes/Plugin.php` - Initialize AI integration
- `includes/Core/Maintenance.php` - Added deactivation cleanup
- `src/controls/src/components/AI/AIContentPopover.js` - Job-based workflow
- `src/controls/src/components/AI/AIImagePopover.js` - Job-based workflow

### 2. WordPress Hooks

**Cron Events**:
- `eb_process_ai_job` - Process individual jobs (immediate)
- `eb_cleanup_ai_jobs` - Clean expired jobs (daily)
- `eb_cleanup_stuck_ai_jobs` - Clean stuck jobs (hourly)
- `eb_cleanup_completed_job` - Clean completed jobs (5 seconds delay)

**Plugin Hooks**:
- `register_deactivation_hook` - Clean up scheduled events

## Testing

### Manual Testing
1. Navigate to Essential Blocks admin
2. Go to "Test AI Jobs" submenu
3. Click "Run Tests" to validate job system

### Browser Testing
1. Open browser console
2. Use provided AJAX examples to test endpoints
3. Monitor network requests and responses

## Benefits

### Performance
- Eliminates AJAX timeouts for long-running AI requests
- Non-blocking user interface during generation
- Efficient polling with reasonable intervals

### Reliability
- Automatic retry capability through job system
- Proper error handling and user feedback
- Cleanup prevents database bloat

### User Experience
- Same interface and functionality as before
- Better loading states and error messages
- No interruption from timeout issues

## Backward Compatibility

- Original AJAX endpoints remain functional
- Frontend gracefully falls back on errors
- No changes to existing AI generation logic
- All existing features preserved

## Future Enhancements

### Possible Improvements
- Queue prioritization for different job types
- Progress indicators for long-running jobs
- Job history and analytics
- Batch processing capabilities
- WebSocket integration for real-time updates

### Monitoring
- Add logging for job performance metrics
- Track success/failure rates
- Monitor average processing times
- Alert on high failure rates