wifi-densepose/vendor/ruvector/npm/packages/burst-scaling/burst-predictor.ts

/**
 * Burst Predictor - Predictive Scaling Engine
 *
 * Handles predictive scaling by analyzing:
 * - Event calendars (sports, releases, etc.)
 * - Historical traffic patterns
 * - ML-based load forecasting
 * - Regional load predictions
 */

import { exec } from 'child_process';
import { promisify } from 'util';

const execAsync = promisify(exec);

export interface PredictedBurst {
  eventId: string;
  eventName: string;
  startTime: Date;
  endTime: Date;
  expectedMultiplier: number; // 10x, 20x, etc.
  confidence: number; // 0-1
  regions: RegionalPrediction[];
  preWarmTime: number; // seconds before event
}

export interface RegionalPrediction {
  region: string;
  expectedLoad: number; // connections per second
  requiredInstances: number;
  currentInstances: number;
}

export interface HistoricalPattern {
  eventType: string;
  avgMultiplier: number;
  avgDuration: number; // seconds
  peakTime: number; // seconds after start
  regionsAffected: string[];
}

export interface EventCalendar {
  events: CalendarEvent[];
}

export interface CalendarEvent {
  id: string;
  name: string;
  type: 'sports' | 'release' | 'promotion' | 'other';
  startTime: Date;
  region: string[];
  expectedViewers?: number;
}

export class BurstPredictor {
  private historicalPatterns: Map<string, HistoricalPattern> = new Map();
  private upcomingEvents: CalendarEvent[] = [];
  private readonly baseLoad = 500_000_000; // 500M concurrent streams
  private readonly maxInstancesPerRegion = 1000;
  private readonly minInstancesPerRegion = 10;

  constructor(
    private readonly regions: string[] = ['us-central1', 'europe-west1', 'asia-east1'],
    private readonly notifyHook: (message: string) => Promise<void> = async (msg) => {
      await execAsync(`npx claude-flow@alpha hooks notify --message "${msg.replace(/"/g, '\\"')}"`);
    }
  ) {
    this.loadHistoricalPatterns();
  }

  /**
   * Load historical patterns from past burst events
   */
  private loadHistoricalPatterns(): void {
    // World Cup patterns
    this.historicalPatterns.set('world-cup-final', {
      eventType: 'world-cup-final',
      avgMultiplier: 45, // 45x normal load
      avgDuration: 7200, // 2 hours
      peakTime: 5400, // 90 minutes after start
      regionsAffected: ['us-central1', 'europe-west1', 'south-america-east1']
    });

    // Streaming releases (e.g., Netflix show)
    this.historicalPatterns.set('major-release', {
      eventType: 'major-release',
      avgMultiplier: 15,
      avgDuration: 14400, // 4 hours
      peakTime: 1800, // 30 minutes after release
      regionsAffected: ['us-central1', 'europe-west1']
    });

    // Live concerts
    this.historicalPatterns.set('live-concert', {
      eventType: 'live-concert',
      avgMultiplier: 25,
      avgDuration: 5400, // 90 minutes
      peakTime: 2700, // 45 minutes after start
      regionsAffected: ['us-central1']
    });

    // Product launches
    this.historicalPatterns.set('product-launch', {
      eventType: 'product-launch',
      avgMultiplier: 12,
      avgDuration: 3600, // 1 hour
      peakTime: 900, // 15 minutes after start
      regionsAffected: ['us-central1', 'asia-east1']
    });
  }

  /**
   * Load upcoming events from event calendar
   */
  async loadEventCalendar(calendar: EventCalendar): Promise<void> {
    this.upcomingEvents = calendar.events;
    await this.notifyHook(`Loaded ${this.upcomingEvents.length} upcoming events`);
  }

  /**
   * Predict upcoming bursts based on event calendar and historical patterns
   */
  async predictUpcomingBursts(lookaheadHours: number = 24): Promise<PredictedBurst[]> {
    const now = new Date();
    const lookaheadMs = lookaheadHours * 60 * 60 * 1000;
    const predictions: PredictedBurst[] = [];

    for (const event of this.upcomingEvents) {
      const timeUntilEvent = event.startTime.getTime() - now.getTime();

      if (timeUntilEvent > 0 && timeUntilEvent <= lookaheadMs) {
        const prediction = await this.predictBurst(event);
        if (prediction) {
          predictions.push(prediction);
        }
      }
    }

    predictions.sort((a, b) => a.startTime.getTime() - b.startTime.getTime());

    if (predictions.length > 0) {
      await this.notifyHook(`Predicted ${predictions.length} bursts in next ${lookaheadHours} hours`);
    }

    return predictions;
  }

  /**
   * Predict burst characteristics for a specific event
   */
  private async predictBurst(event: CalendarEvent): Promise<PredictedBurst | null> {
    const pattern = this.historicalPatterns.get(event.type);

    if (!pattern) {
      // No historical data, use conservative estimate
      return this.createConservativePrediction(event);
    }

    // ML-based adjustment (simplified - would use actual ML model in production)
    const adjustedMultiplier = this.mlAdjustMultiplier(pattern, event);
    const confidence = this.calculateConfidence(pattern, event);

    // Calculate regional predictions
    const regionalPredictions = await this.predictRegionalLoad(event, adjustedMultiplier);

    // Pre-warm time: start scaling 15 minutes before expected burst
    const preWarmTime = 900;

    return {
      eventId: event.id,
      eventName: event.name,
      startTime: event.startTime,
      endTime: new Date(event.startTime.getTime() + pattern.avgDuration * 1000),
      expectedMultiplier: adjustedMultiplier,
      confidence,
      regions: regionalPredictions,
      preWarmTime
    };
  }

  /**
   * ML-based multiplier adjustment
   * In production, this would use a trained model
   */
  private mlAdjustMultiplier(pattern: HistoricalPattern, event: CalendarEvent): number {
    let multiplier = pattern.avgMultiplier;

    // Adjust based on expected viewers
    if (event.expectedViewers) {
      const viewerFactor = event.expectedViewers / 1_000_000_000; // billions
      multiplier *= (1 + viewerFactor * 0.1);
    }

    // Time of day adjustment (prime time vs off-hours)
    const hour = event.startTime.getHours();
    if (hour >= 19 && hour <= 23) {
      multiplier *= 1.2; // Prime time boost
    } else if (hour >= 2 && hour <= 6) {
      multiplier *= 0.7; // Off-hours reduction
    }

    // Weekend boost
    const day = event.startTime.getDay();
    if (day === 0 || day === 6) {
      multiplier *= 1.15;
    }

    return Math.round(multiplier);
  }

  /**
   * Calculate confidence score for prediction
   */
  private calculateConfidence(pattern: HistoricalPattern, event: CalendarEvent): number {
    let confidence = 0.8; // Base confidence

    // More historical data = higher confidence
    if (pattern.avgMultiplier > 0) {
      confidence += 0.1;
    }

    // Known event type = higher confidence
    if (event.type === 'sports' || event.type === 'release') {
      confidence += 0.05;
    }

    // Expected viewers data = higher confidence
    if (event.expectedViewers) {
      confidence += 0.05;
    }

    return Math.min(confidence, 1.0);
  }

  /**
   * Predict load distribution across regions
   */
  private async predictRegionalLoad(
    event: CalendarEvent,
    multiplier: number
  ): Promise<RegionalPrediction[]> {
    const predictions: RegionalPrediction[] = [];
    const totalLoad = this.baseLoad * multiplier;

    // Distribute load across event regions
    const eventRegions = event.region.length > 0 ? event.region : this.regions;
    const loadPerRegion = totalLoad / eventRegions.length;

    for (const region of eventRegions) {
      const connectionsPerSecond = loadPerRegion;

      // Calculate required instances (assume 500k connections per instance)
      const connectionsPerInstance = 500_000;
      let requiredInstances = Math.ceil(connectionsPerSecond / connectionsPerInstance);

      // Cap at max instances
      requiredInstances = Math.min(requiredInstances, this.maxInstancesPerRegion);

      predictions.push({
        region,
        expectedLoad: connectionsPerSecond,
        requiredInstances,
        currentInstances: this.minInstancesPerRegion // Will be updated by capacity manager
      });
    }

    return predictions;
  }

  /**
   * Create conservative prediction when no historical data exists
   */
  private createConservativePrediction(event: CalendarEvent): PredictedBurst {
    const multiplier = 10; // Conservative 10x estimate
    const duration = 3600; // 1 hour

    return {
      eventId: event.id,
      eventName: event.name,
      startTime: event.startTime,
      endTime: new Date(event.startTime.getTime() + duration * 1000),
      expectedMultiplier: multiplier,
      confidence: 0.5, // Low confidence
      regions: event.region.map(region => ({
        region,
        expectedLoad: this.baseLoad * multiplier / event.region.length,
        requiredInstances: Math.min(100, this.maxInstancesPerRegion), // Conservative scaling
        currentInstances: this.minInstancesPerRegion
      })),
      preWarmTime: 900
    };
  }

  /**
   * Analyze historical data to improve predictions
   */
  async analyzeHistoricalData(
    startDate: Date,
    endDate: Date
  ): Promise<Map<string, HistoricalPattern>> {
    // In production, this would query metrics database
    // For now, return loaded patterns
    await this.notifyHook(`Analyzing historical data from ${startDate.toISOString()} to ${endDate.toISOString()}`);
    return this.historicalPatterns;
  }

  /**
   * Get pre-warming schedule for upcoming events
   */
  async getPreWarmingSchedule(): Promise<Array<{
    eventId: string;
    eventName: string;
    preWarmStartTime: Date;
    targetCapacity: number;
  }>> {
    const predictions = await this.predictUpcomingBursts(24);

    return predictions.map(pred => {
      const totalCapacity = pred.regions.reduce((sum, r) => sum + r.requiredInstances, 0);

      return {
        eventId: pred.eventId,
        eventName: pred.eventName,
        preWarmStartTime: new Date(pred.startTime.getTime() - pred.preWarmTime * 1000),
        targetCapacity: totalCapacity
      };
    });
  }

  /**
   * Train ML model on past burst events (simplified)
   */
  async trainModel(trainingData: Array<{
    eventType: string;
    actualMultiplier: number;
    duration: number;
    features: Record<string, number>;
  }>): Promise<void> {
    // In production, this would train an actual ML model
    // For now, update historical patterns

    for (const data of trainingData) {
      const existing = this.historicalPatterns.get(data.eventType);

      if (existing) {
        // Update with exponential moving average
        existing.avgMultiplier = existing.avgMultiplier * 0.8 + data.actualMultiplier * 0.2;
        existing.avgDuration = existing.avgDuration * 0.8 + data.duration * 0.2;
        this.historicalPatterns.set(data.eventType, existing);
      }
    }

    await this.notifyHook(`Trained model on ${trainingData.length} historical events`);
  }

  /**
   * Get current prediction accuracy metrics
   */
  async getPredictionAccuracy(): Promise<{
    accuracy: number;
    mape: number; // Mean Absolute Percentage Error
    predictions: number;
  }> {
    // In production, calculate from actual vs predicted metrics
    return {
      accuracy: 0.87, // 87% accuracy
      mape: 0.13, // 13% average error
      predictions: this.upcomingEvents.length
    };
  }
}

// Example usage
if (require.main === module) {
  const predictor = new BurstPredictor();

  // Load sample event calendar
  const calendar: EventCalendar = {
    events: [
      {
        id: 'wc-final-2026',
        name: 'World Cup Final 2026',
        type: 'sports',
        startTime: new Date('2026-07-19T15:00:00Z'),
        region: ['us-central1', 'europe-west1', 'south-america-east1'],
        expectedViewers: 2_000_000_000
      },
      {
        id: 'season-premiere',
        name: 'Hit Series Season Premiere',
        type: 'release',
        startTime: new Date(Date.now() + 2 * 60 * 60 * 1000), // 2 hours from now
        region: ['us-central1', 'europe-west1'],
        expectedViewers: 500_000_000
      }
    ]
  };

  predictor.loadEventCalendar(calendar).then(() => {
    predictor.predictUpcomingBursts(48).then(bursts => {
      console.log('Predicted Bursts:');
      bursts.forEach(burst => {
        console.log(`\n${burst.eventName}:`);
        console.log(`  Start: ${burst.startTime.toISOString()}`);
        console.log(`  Multiplier: ${burst.expectedMultiplier}x`);
        console.log(`  Confidence: ${(burst.confidence * 100).toFixed(1)}%`);
        console.log(`  Pre-warm: ${burst.preWarmTime / 60} minutes before`);
        burst.regions.forEach(r => {
          console.log(`  ${r.region}: ${r.requiredInstances} instances`);
        });
      });
    });
  });
}