adaptive-memory-multi-model-router 2.3.0 → 2.4.0

package/src/providers/providerHealth.ts

@@ -1,397 +0,0 @@
-/**
- * A3M Router - Provider Health Score
- *
- * Probabilistic health scoring (not binary up/down).
- * Uses latency history, error rate, partial failure patterns, queue depth estimates.
- *
- * Usage:
- *   const healthMonitor = new ProviderHealthMonitor();
- *   healthMonitor.recordLatency('groq', 250);
- *   healthMonitor.recordError('groq', 'rate_limit');
- *   const score = healthMonitor.getHealthScore('groq');
- *   console.log(score); // { score: 0.85, confidence: 0.7, status: 'healthy' }
- */
-
-import { ProviderTier } from '../providers/providerConfig';
-
-// ============================================================
-// Types
-// ============================================================
-
-export type HealthStatus = 'healthy' | 'degraded' | 'critical';
-
-export interface HealthScore {
-  /** Overall health score 0-1 */
-  score: number;
-  /** Confidence in the score 0-1 */
-  confidence: number;
-  /** Human-readable status */
-  status: HealthStatus;
-  /** Component scores */
-  components: {
-    latency: number;
-    errorRate: number;
-    recentTrend: number;
-  };
-  /** Last updated timestamp */
-  lastUpdated: number;
-  /** Metadata about current state */
-  metadata: {
-    sampleSize: number;
-    isAnomaly: boolean;
-    anomalyReason?: string;
-  };
-}
-
-export interface HealthRecord {
-  timestamp: number;
-  latency?: number;
-  success?: boolean;
-  errorType?: string;
-  partialFailure?: boolean;
-}
-
-export interface HealthConfig {
-  /** EWMA alpha for latency smoothing */
-  latencyAlpha?: number;
-  /** EWMA alpha for error rate smoothing */
-  errorAlpha?: number;
-  /** Window size for anomaly detection */
-  anomalyWindow?: number;
-  /** Standard deviation threshold for anomaly */
-  anomalyThreshold?: number;
-  /** Health score thresholds */
-  healthyThreshold?: number;
-  /** Degraded threshold */
-  degradedThreshold?: number;
-}
-
-const DEFAULT_CONFIG: Required<HealthConfig> = {
-  latencyAlpha: 0.3,
-  errorAlpha: 0.2,
-  anomalyWindow: 20,
-  anomalyThreshold: 2.0,
-  healthyThreshold: 0.75,
-  degradedThreshold: 0.4,
-};
-
-// ============================================================
-// ProviderHealthMonitor
-// ============================================================
-
-export class ProviderHealthMonitor {
-  private records: Map<string, HealthRecord[]> = new Map();
-  private config: Required<HealthConfig>;
-  private ewmaLatency: Map<string, number> = new Map();
-  private ewmaErrorRate: Map<string, number> = new Map();
-  private anomalyScores: Map<string, number> = new Map();
-
-  constructor(config: HealthConfig = {}) {
-    this.config = { ...DEFAULT_CONFIG, ...config };
-  }
-
-  /**
-   * Record a successful request with latency.
-   */
-  recordSuccess(providerId: string, latencyMs: number): void {
-    this.addRecord(providerId, {
-      timestamp: Date.now(),
-      latency: latencyMs,
-      success: true,
-    });
-    this.updateEwmaLatency(providerId, latencyMs);
-    this.updateEwmaErrorRate(providerId, false);
-    this.updateAnomalyScore(providerId, latencyMs);
-  }
-
-  /**
-   * Record a failed request.
-   */
-  recordError(providerId: string, errorType: string = 'unknown'): void {
-    this.addRecord(providerId, {
-      timestamp: Date.now(),
-      success: false,
-      errorType,
-    });
-    this.updateEwmaErrorRate(providerId, true);
-  }
-
-  /**
-   * Record a partial failure (slow response, incomplete output, etc).
-   */
-  recordPartialFailure(providerId: string, latencyMs?: number): void {
-    this.addRecord(providerId, {
-      timestamp: Date.now(),
-      latency: latencyMs,
-      success: false,
-      partialFailure: true,
-    });
-    if (latencyMs !== undefined) {
-      this.updateEwmaLatency(providerId, latencyMs);
-      this.updateAnomalyScore(providerId, latencyMs);
-    }
-    // Partial failures count as half an error
-    this.updateEwmaErrorRate(providerId, false, 0.5);
-  }
-
-  /**
-   * Record queue depth estimate (when available from provider metadata).
-   */
-  recordQueueDepth(providerId: string, depth: number): void {
-    // Queue depth affects latency estimation but doesn't directly
-    // impact the health score unless it's extremely high
-    const maxQueueDepth = 100;
-    const queueFactor = 1 + Math.min(depth / maxQueueDepth, 1.0) * 0.5;
-    const currentLatency = this.ewmaLatency.get(providerId) || 0;
-    if (currentLatency > 0) {
-      this.ewmaLatency.set(providerId, currentLatency * queueFactor);
-    }
-  }
-
-  /**
-   * Get the current health score for a provider.
-   */
-  getHealthScore(providerId: string): HealthScore {
-    const records = this.getRecords(providerId);
-    const sampleSize = records.length;
-    const now = Date.now();
-
-    // Not enough data
-    if (sampleSize < 3) {
-      return {
-        score: sampleSize === 0 ? 1.0 : 0.8,
-        confidence: sampleSize / 10, // 0 at 0 samples, 0.3 at 3 samples
-        status: sampleSize === 0 ? 'healthy' : 'degraded',
-        components: { latency: 1.0, errorRate: 1.0, recentTrend: 1.0 },
-        lastUpdated: now,
-        metadata: { sampleSize, isAnomaly: false },
-      };
-    }
-
-    const latencyScore = this.calculateLatencyScore(providerId);
-    const errorScore = this.calculateErrorScore(providerId);
-    const trendScore = this.calculateTrendScore(providerId);
-
-    // Weighted combination
-    const score =
-      latencyScore * 0.35 +
-      errorScore * 0.45 +
-      trendScore * 0.20;
-
-    // Determine status
-    let status: HealthStatus;
-    if (score >= this.config.healthyThreshold) {
-      status = 'healthy';
-    } else if (score >= this.config.degradedThreshold) {
-      status = 'degraded';
-    } else {
-      status = 'critical';
-    }
-
-    // Anomaly detection
-    const anomalyScore = this.anomalyScores.get(providerId) || 0;
-    const isAnomaly = anomalyScore > this.config.anomalyThreshold;
-    const anomalyReason = isAnomaly
-      ? `Anomaly detected: score ${anomalyScore.toFixed(2)} > threshold ${this.config.anomalyThreshold}`
-      : undefined;
-
-    // Confidence based on sample size and anomaly status
-    const baseConfidence = Math.min(sampleSize / 30, 1.0);
-    const confidence = isAnomaly
-      ? Math.min(baseConfidence * 0.5, 0.5) // Lower confidence when anomalous
-      : baseConfidence;
-
-    return {
-      score: Math.round(score * 1000) / 1000,
-      confidence: Math.round(confidence * 1000) / 1000,
-      status,
-      components: {
-        latency: Math.round(latencyScore * 1000) / 1000,
-        errorRate: Math.round(errorScore * 1000) / 1000,
-        recentTrend: Math.round(trendScore * 1000) / 1000,
-      },
-      lastUpdated: now,
-      metadata: {
-        sampleSize,
-        isAnomaly,
-        anomalyReason,
-      },
-    };
-  }
-
-  /**
-   * Get health scores for all tracked providers.
-   */
-  getAllHealthScores(): Record<string, HealthScore> {
-    const result: Record<string, HealthScore> = {};
-    for (const providerId of this.records.keys()) {
-      result[providerId] = this.getHealthScore(providerId);
-    }
-    return result;
-  }
-
-  /**
-   * Get the recommended provider based on health scores.
-   * Excludes providers that are 'critical'.
-   */
-  getRecommendedProvider(
-    providers: Array<{ id: string; tier?: ProviderTier; priority?: number }>
-  ): string | null {
-    const candidates = providers.filter(p => {
-      const score = this.getHealthScore(p.id);
-      return score.status !== 'critical';
-    });
-
-    if (candidates.length === 0) return null;
-
-    // Sort by health score, then by priority (if available)
-    candidates.sort((a, b) => {
-      const scoreA = this.getHealthScore(a.id).score;
-      const scoreB = this.getHealthScore(b.id).score;
-      if (Math.abs(scoreA - scoreB) > 0.1) {
-        return scoreB - scoreA; // Higher score first
-      }
-      return (a.priority || 50) - (b.priority || 50); // Lower priority first
-    });
-
-    return candidates[0].id;
-  }
-
-  /**
-   * Clear all records for a provider.
-   */
-  clearProvider(providerId: string): void {
-    this.records.delete(providerId);
-    this.ewmaLatency.delete(providerId);
-    this.ewmaErrorRate.delete(providerId);
-    this.anomalyScores.delete(providerId);
-  }
-
-  /**
-   * Clear all records for all providers.
-   */
-  clearAll(): void {
-    this.records.clear();
-    this.ewmaLatency.clear();
-    this.ewmaErrorRate.clear();
-    this.anomalyScores.clear();
-  }
-
-  // ---- Private methods ----
-
-  private addRecord(providerId: string, record: HealthRecord): void {
-    if (!this.records.has(providerId)) {
-      this.records.set(providerId, []);
-    }
-    const records = this.records.get(providerId)!;
-    records.push(record);
-
-    // Keep only recent records (last hour)
-    const oneHourAgo = Date.now() - 3600000;
-    const filtered = records.filter(r => r.timestamp >= oneHourAgo);
-    this.records.set(providerId, filtered);
-  }
-
-  private getRecords(providerId: string): HealthRecord[] {
-    return this.records.get(providerId) || [];
-  }
-
-  private updateEwmaLatency(providerId: string, latency: number): void {
-    const current = this.ewmaLatency.get(providerId);
-    if (current === undefined) {
-      this.ewmaLatency.set(providerId, latency);
-    } else {
-      this.ewmaLatency.set(
-        providerId,
-        this.config.latencyAlpha * latency + (1 - this.config.latencyAlpha) * current
-      );
-    }
-  }
-
-  private updateEwmaErrorRate(providerId: string, isError: boolean, weight = 1.0): void {
-    const current = this.ewmaErrorRate.get(providerId) || 0;
-    const errorValue = isError ? 1.0 * weight : 0;
-    if (current === 0 && !isError) {
-      this.ewmaErrorRate.set(providerId, 0);
-    } else {
-      this.ewmaErrorRate.set(
-        providerId,
-        this.config.errorAlpha * errorValue + (1 - this.config.errorAlpha) * current
-      );
-    }
-  }
-
-  private updateAnomalyScore(providerId: string, latency: number): void {
-    const records = this.getRecords(providerId).filter(r => r.latency !== undefined);
-    if (records.length < 3) return;
-
-    // Calculate standard deviation of recent latencies
-    const recentLatencies = records
-      .slice(-this.config.anomalyWindow)
-      .map(r => r.latency!)
-      .filter(l => l !== undefined);
-
-    if (recentLatencies.length < 3) return;
-
-    const mean = recentLatencies.reduce((a, b) => a + b, 0) / recentLatencies.length;
-    const variance =
-      recentLatencies.reduce((sum, l) => sum + Math.pow(l - mean, 2), 0) /
-      recentLatencies.length;
-    const stdDev = Math.sqrt(variance);
-
-    // Z-score of current latency
-    const zScore = stdDev > 0 ? Math.abs(latency - mean) / stdDev : 0;
-
-    // Update anomaly score with decay
-    const currentScore = this.anomalyScores.get(providerId) || 0;
-    const newScore = currentScore * 0.9 + zScore * 0.1;
-    this.anomalyScores.set(providerId, newScore);
-  }
-
-  private calculateLatencyScore(providerId: string): number {
-    const latency = this.ewmaLatency.get(providerId);
-    if (latency === undefined) return 1.0;
-
-    // Score based on latency brackets (ms)
-    // Tier-appropriate expectations
-    if (latency < 200) return 1.0;
-    if (latency < 500) return 0.95;
-    if (latency < 800) return 0.85;
-    if (latency < 1500) return 0.7;
-    if (latency < 3000) return 0.5;
-    return Math.max(0.1, 1 - latency / 10000);
-  }
-
-  private calculateErrorScore(providerId: string): number {
-    const errorRate = this.ewmaErrorRate.get(providerId) || 0;
-    // Score: 1 - errorRate, but with floor
-    return Math.max(0.05, 1 - errorRate);
-  }
-
-  private calculateTrendScore(providerId: string): number {
-    const records = this.getRecords(providerId).filter(r => r.latency !== undefined);
-    if (records.length < 5) return 1.0;
-
-    // Compare recent 5 vs previous 5
-    const recent = records.slice(-5);
-    const previous = records.slice(-10, -5);
-
-    if (previous.length === 0) return 1.0;
-
-    const recentAvg = recent.reduce((sum, r) => sum + (r.latency || 0), 0) / recent.length;
-    const previousAvg = previous.reduce((sum, r) => sum + (r.latency || 0), 0) / previous.length;
-
-    // If improving (lower latency), score > 1
-    // If degrading, score < 1
-    const ratio = previousAvg / recentAvg;
-    return Math.min(1.2, Math.max(0.6, ratio));
-  }
-}
-
-// ============================================================
-// Factory
-// ============================================================
-
-export function createProviderHealthMonitor(config?: HealthConfig): ProviderHealthMonitor {
-  return new ProviderHealthMonitor(config);
-}