upskill-event-manager/docs/AI_EVENT_POPULATION_IMPLEMENTATION_PLAN.md

AI-Assisted Event Population Implementation Plan

Overview

This plan implements AI-powered event form population using Anthropic Claude API, integrating seamlessly with the existing HVAC event creation system while maintaining WordPress security standards and TEC compatibility.

Architecture Strategy

INPUT SOURCES          PROCESSING PIPELINE         OUTPUT INTEGRATION
┌─────────────────┐    ┌─────────────────┐        ┌─────────────────┐
│ • URLs          │    │ HVAC_AI_Event   │        │ Form Field      │
│ • Pasted Text   │───>│ _Populator      │──────>│ Population      │
│ • Descriptions  │    │ • Claude API    │        │ • TEC Meta      │
└─────────────────┘    │ • Validation    │        │ • Confidence    │
                       │ • Mapping       │        │ • User Review   │
                       └─────────────────┘        └─────────────────┘

Phase 1: MVP Implementation

1.1 Core Infrastructure Setup

API Configuration

• Add define('ANTHROPIC_API_KEY', 'your-key-here'); to wp-config.php
• Create HVAC_AI_Config class for secure API settings management
• Implement connectivity validation and error handling

Core Service Implementation

// includes/class-hvac-ai-event-populator.php
class HVAC_AI_Event_Populator {
    use HVAC_Singleton_Trait;

    public function populate_from_input($input, $input_type) {
        // Structured Claude API call with web search enabled
        // Return standardized JSON with confidence scores
    }

    private function build_prompt($input, $context) {
        // Dynamic prompt with venue/organizer context
    }

    private function validate_response($response) {
        // Schema validation and sanitization
    }
}

AJAX Endpoint Development

• Extend existing HVAC_Ajax_Handlers class with hvac_ai_populate_event
• Integrate with HVAC_Ajax_Security framework
• Implement role validation: hvac_trainer or hvac_master_trainer
• Input validation and sanitization pipeline

1.2 Essential Field Mapping

TEC Integration Points

private array $field_mapping = [
    'title' => 'event_title',
    'description' => 'event_description',
    'start_date' => 'event_start_datetime',
    'end_date' => 'event_end_datetime',
    'venue' => '_EventVenueID',
    'organizer' => '_EventOrganizerID',
    'cost' => 'event_cost',
    'capacity' => 'event_capacity'
];

Data Processing Pipeline

• Input sanitization using sanitize_textarea_field()
• URL validation for web sources
• Response parsing with JSON schema validation
• Basic venue/organizer duplicate detection

1.3 Minimum Viable Frontend

Modal Interface Integration

• Enhance existing template system in templates/page-tec-create-event.php
• Convert placeholder "AI Assist" button to functional interface
• Single input field supporting both URLs and text
• Basic loading states and error messaging

JavaScript Integration

// assets/js/hvac-ai-assist.js
jQuery(document).ready(function($) {
    $('#ai-assist-btn').on('click', function() {
        showAIModal();
    });

    function processAIInput(input) {
        // AJAX call to backend endpoint
        // Handle loading states
        // Populate form fields on success
    }
});

Phase 2: Enhanced UX & Validation

2.1 Advanced Modal Interface

Three-Tab Input System

• URL Tab: EventBrite, Facebook Events, custom sites
• Text Tab: Email/PDF content, formatted or unformatted
• Description Tab: Natural language event details

Enhanced User Experience

• Input type auto-detection with visual feedback
• Progressive loading states with detailed status messages
• Enhanced error handling with recovery suggestions

2.2 Robust Data Processing

Venue/Organizer Intelligence

private function find_matching_venue($extracted_venue) {
    // Fuzzy matching against existing venues
    // Similarity scoring above 80% threshold
    // Return existing ID or create new venue
}

private function detect_duplicates($event_data) {
    // Check date + similar title combinations
    // Return warnings for potential duplicates
}

Confidence Scoring System

private function calculate_confidence($field_value, $source_context) {
    // Per-field confidence scoring (0.0-1.0)
    // Overall extraction confidence
    // Completeness matrix for missing fields
}

2.3 Integration Polish

Form Field Enhancement

• Field-level confidence indicators (color-coded borders)
• Confidence matrix display modal
• Review and adjust workflow before final submission
• Seamless autosave integration

Phase 3: Performance & Caching

3.1 Caching Implementation

WordPress Transients Strategy

private function get_cached_response($input_hash) {
    return get_transient("hvac_ai_cache_{$input_hash}");
}

private function cache_response($input_hash, $response) {
    set_transient("hvac_ai_cache_{$input_hash}", $response, 24 * HOUR_IN_SECONDS);
}

Cache Management

• Content-based cache key generation
• 24-hour TTL for successful extractions
• Cache invalidation on venue/organizer updates
• Memory-optimized for shared hosting

3.2 Performance Optimization

Request Management

• Per-user rate limiting (configurable limits)
• Request timeout handling (30-second maximum)
• Error rate monitoring and alerting
• Prompt optimization for accuracy and speed

Phase 4: Production Readiness

4.1 Testing Strategy

Comprehensive Test Coverage

• Unit tests for API response parsing
• Integration tests with various input formats
• Security testing for AJAX endpoints
• Performance validation on Cloudways environment

Test Scenarios

• EventBrite URLs, Facebook Events, custom sites
• Email formats, PDF content, unstructured text
• Minimal descriptions, detailed specifications
• Non-English content, past events, recurring events

4.2 Edge Case Handling

Robust Error Management

• Network timeout recovery with retry logic
• Malformed API response handling
• Rate limit exceeded graceful degradation
• Multiple event extraction (first event only)

Security Hardening

• Input validation against injection attacks
• API key security audit
• OWASP compliance verification
• WordPress security best practices

Technical Specifications

Prompt Engineering Strategy

System: You are an HVAC event extraction specialist for professional training calendar.

Context:
- Current date: {current_date}
- Existing venues: {venue_list}
- Existing organizers: {organizer_list}

Input: {user_input}

Extract event information and output ONLY valid JSON:
{
  "title": "string",
  "description": "string",
  "start_date": "YYYY-MM-DD",
  "start_time": "HH:MM",
  "end_date": "YYYY-MM-DD",
  "end_time": "HH:MM",
  "venue": {
    "name": "string",
    "address": "string",
    "confidence": 0.0-1.0
  },
  "organizer": {
    "name": "string",
    "email": "string",
    "confidence": 0.0-1.0
  },
  "cost": number,
  "capacity": number|null,
  "confidence": {
    "overall": 0.0-1.0,
    "per_field": {
      "title": 0.0-1.0,
      "dates": 0.0-1.0,
      "venue": 0.0-1.0
    }
  }
}

Rules:
1. Match venues/organizers to existing when similarity > 80%
2. Convert relative dates to absolute dates
3. Use null for missing fields, not empty strings
4. If multiple events found, extract primary event only

File Structure

includes/
├── class-hvac-ai-event-populator.php    # Main AI service
├── class-hvac-ai-modal.php              # Modal interface handler
└── class-hvac-ai-config.php             # API configuration

assets/
├── js/hvac-ai-assist.js                 # Frontend JavaScript
└── css/hvac-ai-assist.css               # Modal styling

templates/
└── page-tec-create-event.php            # Enhanced with AI button

Success Metrics

Technical Performance

• API response time < 10 seconds (target: 5 seconds)
• Field population accuracy > 85% against test dataset
• Zero security vulnerabilities in penetration testing
• 99.9% uptime for feature availability

User Experience

• 50% reduction in event submission time
• 75% of submissions use AI assistance
• Error rate < 5% requiring manual intervention
• User satisfaction score > 4/5

Risk Mitigation

Operational Risks

• API Failures: Graceful degradation with clear error messages
• Performance Issues: Request queuing and rate limiting
• Security Vulnerabilities: Multi-layer validation and WordPress best practices

Adoption Risks

• User Training: Comprehensive documentation and tutorials
• Feature Discovery: Prominent UI placement and onboarding
• Trust Building: Confidence indicators and manual review workflow

Next Steps

This implementation plan provides a clear roadmap from MVP to production-ready AI-assisted event population. The phased approach allows for early user feedback while maintaining the existing plugin's architecture and security standards.

The plan can be executed incrementally, with each phase building upon the previous foundation while delivering immediate value to HVAC trainers through reduced event submission friction.