@higher.archi/boe 1.0.22 → 1.0.24

package/src/engines/prediction/strategy.ts

@@ -0,0 +1,573 @@
+/**
+ * Prediction Engine Strategy
+ *
+ * Core execution logic for all prediction strategies:
+ * - linear-regression: Least-squares line fit with R² confidence
+ * - exponential-smoothing: Holt's double exponential (level + trend)
+ * - weighted-moving-average: Rolling window with recency weighting
+ */
+
+import type { IWorkingMemory, Fact } from '../../core';
+
+import type {
+  CompiledPredictionRuleSet,
+  CompiledLinearRegressionRuleSet,
+  CompiledExponentialSmoothingRuleSet,
+  CompiledWeightedMovingAverageRuleSet,
+  PredictionOptions,
+  PredictionResult,
+  EntityPrediction,
+  ThresholdCrossing,
+  ThresholdDefinition
+} from './types';
+import { resolveConfidenceBracket, resolveTrendDirection } from './types';
+
+// ========================================
+// Internal Types
+// ========================================
+
+type DataPoint = { score: number; timestamp: number };
+
+// Milliseconds per day / per month (30 days)
+const MS_PER_DAY = 86_400_000;
+const MS_PER_MONTH = 2_592_000_000;   // 30 days
+
+export class PredictionExecutor {
+  run(
+    ruleSet: CompiledPredictionRuleSet,
+    wm: IWorkingMemory,
+    options: PredictionOptions = {}
+  ): PredictionResult {
+    const startTime = performance.now();
+    const asOf = options.asOf ? options.asOf.getTime() : Date.now();
+
+    // Group snapshots by entity
+    const entityGroups = groupByEntity(wm.getByType(ruleSet.snapshotType), ruleSet.fields);
+
+    const predictions: EntityPrediction[] = [];
+
+    for (const [entityId, points] of entityGroups) {
+      let prediction: EntityPrediction;
+
+      switch (ruleSet.strategy) {
+        case 'linear-regression':
+          prediction = this.runLinearRegression(
+            ruleSet as CompiledLinearRegressionRuleSet,
+            entityId, points, asOf
+          );
+          break;
+        case 'exponential-smoothing':
+          prediction = this.runExponentialSmoothing(
+            ruleSet as CompiledExponentialSmoothingRuleSet,
+            entityId, points, asOf
+          );
+          break;
+        case 'weighted-moving-average':
+          prediction = this.runWeightedMovingAverage(
+            ruleSet as CompiledWeightedMovingAverageRuleSet,
+            entityId, points, asOf
+          );
+          break;
+        default:
+          throw new Error(`Unknown prediction strategy: '${(ruleSet as any).strategy}'`);
+      }
+
+      if (options.onPredict) {
+        options.onPredict(prediction);
+      }
+
+      predictions.push(prediction);
+    }
+
+    const executionTimeMs = Math.round((performance.now() - startTime) * 100) / 100;
+
+    return {
+      predictions,
+      totalEntities: predictions.length,
+      strategy: ruleSet.strategy,
+      horizonMs: ruleSet.horizonMs,
+      executionTimeMs
+    };
+  }
+
+  // ========================================
+  // Linear Regression
+  // ========================================
+
+  private runLinearRegression(
+    ruleSet: CompiledLinearRegressionRuleSet,
+    entityId: string,
+    points: DataPoint[],
+    asOf: number
+  ): EntityPrediction {
+    const currentScore = points[points.length - 1].score;
+    const forecastTime = asOf + ruleSet.horizonMs;
+    const forecastDate = new Date(forecastTime);
+
+    // 1 data point
+    if (points.length === 1) {
+      return this.buildSinglePointPrediction(
+        ruleSet, entityId, currentScore, asOf, forecastDate, 'linear-regression'
+      );
+    }
+
+    // 2 data points
+    if (points.length === 2) {
+      const dt = points[1].timestamp - points[0].timestamp;
+      const ds = points[1].score - points[0].score;
+      const slopePerMs = dt > 0 ? ds / dt : 0;
+      const predicted = currentScore + slopePerMs * ruleSet.horizonMs;
+      const stableThreshold = ruleSet.config.stableThreshold / MS_PER_DAY; // convert to per-ms
+
+      return {
+        entityId,
+        dataPoints: 2,
+        trend: resolveTrendDirection(slopePerMs, stableThreshold),
+        trendSlope: round(slopePerMs * MS_PER_DAY, 4),
+        confidence: 0.3,
+        confidenceBracket: resolveConfidenceBracket(0.3),
+        currentScore,
+        forecast: {
+          date: forecastDate,
+          dateIso: forecastDate.toISOString(),
+          predictedScore: round(predicted, 2)
+        },
+        thresholdCrossings: computeThresholdCrossings(currentScore, slopePerMs, asOf, ruleSet.thresholds),
+        model: {
+          strategy: 'linear-regression',
+          params: { slopePerDay: round(slopePerMs * MS_PER_DAY, 6), intercept: 0, rSquared: 0 }
+        }
+      };
+    }
+
+    // 3+ data points: full least-squares
+    const n = points.length;
+    const tMin = points[0].timestamp;
+
+    // Normalize timestamps to avoid precision loss
+    const xs = points.map(p => p.timestamp - tMin);
+    const ys = points.map(p => p.score);
+
+    const xMean = xs.reduce((a, b) => a + b, 0) / n;
+    const yMean = ys.reduce((a, b) => a + b, 0) / n;
+
+    let sXX = 0;
+    let sXY = 0;
+    for (let i = 0; i < n; i++) {
+      const dx = xs[i] - xMean;
+      sXX += dx * dx;
+      sXY += dx * (ys[i] - yMean);
+    }
+
+    const slope = sXX > 0 ? sXY / sXX : 0;
+    const intercept = yMean - slope * xMean;
+
+    // R²
+    let ssTot = 0;
+    let ssRes = 0;
+    for (let i = 0; i < n; i++) {
+      const yHat = slope * xs[i] + intercept;
+      ssTot += (ys[i] - yMean) * (ys[i] - yMean);
+      ssRes += (ys[i] - yHat) * (ys[i] - yHat);
+    }
+    const rSquared = ssTot > 0 ? Math.max(0, Math.min(1, 1 - ssRes / ssTot)) : 0;
+
+    // Prediction at horizon
+    const xPred = forecastTime - tMin;
+    const predicted = slope * xPred + intercept;
+
+    // 95% confidence interval
+    const se = n > 2 ? Math.sqrt(ssRes / (n - 2)) : 0;
+    const margin = 1.96 * se * Math.sqrt(1 + 1 / n + ((xPred - xMean) * (xPred - xMean)) / sXX);
+
+    const stableThreshold = ruleSet.config.stableThreshold / MS_PER_DAY;
+
+    return {
+      entityId,
+      dataPoints: n,
+      trend: resolveTrendDirection(slope, stableThreshold),
+      trendSlope: round(slope * MS_PER_DAY, 4),
+      confidence: round(rSquared, 4),
+      confidenceBracket: resolveConfidenceBracket(rSquared),
+      currentScore,
+      forecast: {
+        date: forecastDate,
+        dateIso: forecastDate.toISOString(),
+        predictedScore: round(predicted, 2),
+        confidenceInterval: margin > 0
+          ? { lower: round(predicted - margin, 2), upper: round(predicted + margin, 2) }
+          : undefined
+      },
+      thresholdCrossings: computeThresholdCrossings(currentScore, slope, asOf - tMin, ruleSet.thresholds, tMin),
+      model: {
+        strategy: 'linear-regression',
+        params: {
+          slopePerDay: round(slope * MS_PER_DAY, 6),
+          intercept: round(intercept, 4),
+          rSquared: round(rSquared, 4)
+        }
+      }
+    };
+  }
+
+  // ========================================
+  // Exponential Smoothing (Holt's Double)
+  // ========================================
+
+  private runExponentialSmoothing(
+    ruleSet: CompiledExponentialSmoothingRuleSet,
+    entityId: string,
+    points: DataPoint[],
+    asOf: number
+  ): EntityPrediction {
+    const currentScore = points[points.length - 1].score;
+    const forecastTime = asOf + ruleSet.horizonMs;
+    const forecastDate = new Date(forecastTime);
+
+    // 1 data point
+    if (points.length === 1) {
+      return this.buildSinglePointPrediction(
+        ruleSet, entityId, currentScore, asOf, forecastDate, 'exponential-smoothing'
+      );
+    }
+
+    // 2 data points
+    if (points.length === 2) {
+      const dt = points[1].timestamp - points[0].timestamp;
+      const ds = points[1].score - points[0].score;
+      const slopePerMs = dt > 0 ? ds / dt : 0;
+      const predicted = currentScore + slopePerMs * ruleSet.horizonMs;
+
+      // Use a default stable threshold for exponential smoothing
+      const stableThreshold = 0.001 / MS_PER_DAY;
+
+      return {
+        entityId,
+        dataPoints: 2,
+        trend: resolveTrendDirection(slopePerMs, stableThreshold),
+        trendSlope: round(slopePerMs * MS_PER_DAY, 4),
+        confidence: 0.3,
+        confidenceBracket: resolveConfidenceBracket(0.3),
+        currentScore,
+        forecast: {
+          date: forecastDate,
+          dateIso: forecastDate.toISOString(),
+          predictedScore: round(predicted, 2)
+        },
+        thresholdCrossings: computeThresholdCrossings(currentScore, slopePerMs, asOf, ruleSet.thresholds),
+        model: {
+          strategy: 'exponential-smoothing',
+          params: {
+            level: currentScore,
+            trendPerDay: round(slopePerMs * MS_PER_DAY, 6),
+            alpha: ruleSet.config.alpha,
+            beta: ruleSet.config.beta
+          }
+        }
+      };
+    }
+
+    // 3+ points: Holt's double exponential smoothing
+    const { alpha, beta } = ruleSet.config;
+
+    let level = points[0].score;
+    let trend = points[1].score - points[0].score;
+
+    // Track errors for MAE-based confidence
+    let totalAbsError = 0;
+    let minScore = points[0].score;
+    let maxScore = points[0].score;
+
+    for (let i = 1; i < points.length; i++) {
+      const score = points[i].score;
+      minScore = Math.min(minScore, score);
+      maxScore = Math.max(maxScore, score);
+
+      const predicted = level + trend;
+      totalAbsError += Math.abs(score - predicted);
+
+      const prevLevel = level;
+      level = alpha * score + (1 - alpha) * (prevLevel + trend);
+      trend = beta * (level - prevLevel) + (1 - beta) * trend;
+    }
+
+    const avgInterval = (points[points.length - 1].timestamp - points[0].timestamp) / (points.length - 1);
+    const stepsAhead = avgInterval > 0 ? ruleSet.horizonMs / avgInterval : 0;
+    const predicted = level + trend * stepsAhead;
+
+    // Confidence: 1 - (MAE / range), clamped [0, 1]
+    const mae = totalAbsError / (points.length - 1);
+    const range = maxScore - minScore;
+    const confidence = range > 0 ? Math.max(0, Math.min(1, 1 - mae / range)) : (mae === 0 ? 1 : 0);
+
+    // Convert trend per interval to per ms
+    const trendPerMs = avgInterval > 0 ? trend / avgInterval : 0;
+    const stableThreshold = 0.001 / MS_PER_DAY;
+
+    return {
+      entityId,
+      dataPoints: points.length,
+      trend: resolveTrendDirection(trendPerMs, stableThreshold),
+      trendSlope: round(trendPerMs * MS_PER_DAY, 4),
+      confidence: round(confidence, 4),
+      confidenceBracket: resolveConfidenceBracket(confidence),
+      currentScore,
+      forecast: {
+        date: forecastDate,
+        dateIso: forecastDate.toISOString(),
+        predictedScore: round(predicted, 2)
+      },
+      thresholdCrossings: computeThresholdCrossings(currentScore, trendPerMs, asOf, ruleSet.thresholds),
+      model: {
+        strategy: 'exponential-smoothing',
+        params: {
+          level: round(level, 4),
+          trendPerDay: round(trendPerMs * MS_PER_DAY, 6),
+          alpha,
+          beta
+        }
+      }
+    };
+  }
+
+  // ========================================
+  // Weighted Moving Average
+  // ========================================
+
+  private runWeightedMovingAverage(
+    ruleSet: CompiledWeightedMovingAverageRuleSet,
+    entityId: string,
+    points: DataPoint[],
+    asOf: number
+  ): EntityPrediction {
+    const currentScore = points[points.length - 1].score;
+    const forecastTime = asOf + ruleSet.horizonMs;
+    const forecastDate = new Date(forecastTime);
+
+    // 1 data point
+    if (points.length === 1) {
+      return this.buildSinglePointPrediction(
+        ruleSet, entityId, currentScore, asOf, forecastDate, 'weighted-moving-average'
+      );
+    }
+
+    // 2+ points
+    const windowSize = Math.min(ruleSet.config.window, points.length);
+    const recent = points.slice(-windowSize);
+
+    // Weighted average: weights = [1, 2, ..., N]
+    let weightedSum = 0;
+    let totalWeight = 0;
+    for (let i = 0; i < recent.length; i++) {
+      const w = i + 1;
+      weightedSum += recent[i].score * w;
+      totalWeight += w;
+    }
+    const weightedAvg = weightedSum / totalWeight;
+
+    // Weighted slope from consecutive diffs
+    let slopeWeightedSum = 0;
+    let slopeTotalWeight = 0;
+    for (let i = 1; i < recent.length; i++) {
+      const dt = recent[i].timestamp - recent[i - 1].timestamp;
+      if (dt > 0) {
+        const diff = (recent[i].score - recent[i - 1].score) / dt;
+        const w = i; // more weight on recent diffs
+        slopeWeightedSum += diff * w;
+        slopeTotalWeight += w;
+      }
+    }
+    const slopePerMs = slopeTotalWeight > 0 ? slopeWeightedSum / slopeTotalWeight : 0;
+
+    const predicted = weightedAvg + slopePerMs * ruleSet.horizonMs;
+
+    // Confidence: max(0, 1 - CV) where CV = stdDev / |mean|
+    const mean = recent.reduce((a, b) => a + b.score, 0) / recent.length;
+    const variance = recent.reduce((a, b) => a + (b.score - mean) * (b.score - mean), 0) / recent.length;
+    const stdDev = Math.sqrt(variance);
+    const cv = Math.abs(mean) > 0 ? stdDev / Math.abs(mean) : 0;
+    const confidence = Math.max(0, Math.min(1, 1 - cv));
+
+    const stableThreshold = 0.001 / MS_PER_DAY;
+
+    return {
+      entityId,
+      dataPoints: points.length,
+      trend: resolveTrendDirection(slopePerMs, stableThreshold),
+      trendSlope: round(slopePerMs * MS_PER_DAY, 4),
+      confidence: round(confidence, 4),
+      confidenceBracket: resolveConfidenceBracket(confidence),
+      currentScore,
+      forecast: {
+        date: forecastDate,
+        dateIso: forecastDate.toISOString(),
+        predictedScore: round(predicted, 2)
+      },
+      thresholdCrossings: computeThresholdCrossings(currentScore, slopePerMs, asOf, ruleSet.thresholds),
+      model: {
+        strategy: 'weighted-moving-average',
+        params: {
+          weightedAverage: round(weightedAvg, 4),
+          window: windowSize,
+          slopePerDay: round(slopePerMs * MS_PER_DAY, 6)
+        }
+      }
+    };
+  }
+
+  // ========================================
+  // Shared Helpers
+  // ========================================
+
+  private buildSinglePointPrediction(
+    ruleSet: CompiledPredictionRuleSet,
+    entityId: string,
+    currentScore: number,
+    asOf: number,
+    forecastDate: Date,
+    strategy: EntityPrediction['model']['strategy']
+  ): EntityPrediction {
+    // If defaultTrend is configured, use it as slope (per month -> per ms)
+    let slopePerMs = 0;
+    let trend: EntityPrediction['trend'] = 'insufficient-data';
+    let predicted = currentScore;
+
+    if (ruleSet.defaultTrend !== undefined) {
+      slopePerMs = ruleSet.defaultTrend / MS_PER_MONTH;
+      predicted = currentScore + slopePerMs * ruleSet.horizonMs;
+      const stableThreshold = 0.001 / MS_PER_DAY;
+      trend = resolveTrendDirection(slopePerMs, stableThreshold);
+    }
+
+    return {
+      entityId,
+      dataPoints: 1,
+      trend,
+      trendSlope: round(slopePerMs * MS_PER_DAY, 4),
+      confidence: 0,
+      confidenceBracket: 'insufficient-data',
+      currentScore,
+      forecast: {
+        date: forecastDate,
+        dateIso: forecastDate.toISOString(),
+        predictedScore: round(predicted, 2)
+      },
+      thresholdCrossings: slopePerMs !== 0
+        ? computeThresholdCrossings(currentScore, slopePerMs, asOf, ruleSet.thresholds)
+        : [],
+      model: {
+        strategy,
+        params: {}
+      }
+    };
+  }
+}
+
+// ========================================
+// Module-Level Helpers
+// ========================================
+
+function resolveDotPath(obj: any, path: string): any {
+  const parts = path.split('.');
+  let current = obj;
+  for (const part of parts) {
+    if (current == null) return undefined;
+    current = current[part];
+  }
+  return current;
+}
+
+function groupByEntity(
+  facts: Fact[],
+  fields: { entityId: string; score: string; timestamp: string }
+): Map<string, DataPoint[]> {
+  const groups = new Map<string, DataPoint[]>();
+
+  for (const fact of facts) {
+    const entityId = resolveDotPath(fact.data, fields.entityId);
+    const score = resolveDotPath(fact.data, fields.score);
+    const timestampRaw = resolveDotPath(fact.data, fields.timestamp);
+
+    if (entityId == null || score == null || timestampRaw == null) continue;
+
+    const timestamp = typeof timestampRaw === 'string'
+      ? new Date(timestampRaw).getTime()
+      : typeof timestampRaw === 'number'
+        ? timestampRaw
+        : NaN;
+
+    if (isNaN(timestamp)) continue;
+
+    if (!groups.has(entityId)) {
+      groups.set(entityId, []);
+    }
+    groups.get(entityId)!.push({ score: Number(score), timestamp });
+  }
+
+  // Sort each group by timestamp ascending
+  for (const points of groups.values()) {
+    points.sort((a, b) => a.timestamp - b.timestamp);
+  }
+
+  return groups;
+}
+
+function computeThresholdCrossings(
+  currentScore: number,
+  slopePerMs: number,
+  asOf: number,
+  thresholds: ThresholdDefinition[],
+  tMin: number = 0
+): ThresholdCrossing[] {
+  if (slopePerMs === 0 || thresholds.length === 0) return [];
+
+  const crossings: ThresholdCrossing[] = [];
+  const now = tMin > 0 ? asOf + tMin : asOf; // adjust if tMin is a normalization offset
+
+  for (const threshold of thresholds) {
+    const diff = threshold.value - currentScore;
+
+    // Check if crossing is possible given direction of slope
+    if (threshold.direction === 'above') {
+      // Currently below threshold, trending up
+      if (currentScore < threshold.value && slopePerMs > 0) {
+        const msToThreshold = diff / slopePerMs;
+        const crossTime = now + msToThreshold;
+        const crossDate = new Date(crossTime);
+        crossings.push({
+          thresholdId: threshold.id,
+          thresholdName: threshold.name,
+          value: threshold.value,
+          direction: 'above',
+          estimatedAt: crossDate,
+          estimatedAtIso: crossDate.toISOString()
+        });
+      }
+    } else {
+      // direction === 'below': currently above threshold, trending down
+      if (currentScore > threshold.value && slopePerMs < 0) {
+        const msToThreshold = diff / slopePerMs;
+        const crossTime = now + msToThreshold;
+        const crossDate = new Date(crossTime);
+        crossings.push({
+          thresholdId: threshold.id,
+          thresholdName: threshold.name,
+          value: threshold.value,
+          direction: 'below',
+          estimatedAt: crossDate,
+          estimatedAtIso: crossDate.toISOString()
+        });
+      }
+    }
+  }
+
+  return crossings;
+}
+
+function round(value: number, decimals: number): number {
+  const factor = Math.pow(10, decimals);
+  return Math.round(value * factor) / factor;
+}
+
+/** Singleton instance */
+export const predictionStrategy = new PredictionExecutor();