@higher.archi/boe 1.0.22 → 1.0.24

package/src/engines/prediction/types.ts

@@ -0,0 +1,236 @@
+/**
+ * Prediction Engine Types
+ *
+ * Trajectory forecasting engine that takes historical score snapshots,
+ * fits a model, and projects forward. Supports linear regression,
+ * exponential smoothing, and weighted moving average strategies.
+ */
+
+// ========================================
+// Semantic Types
+// ========================================
+
+/** Prediction algorithm to use */
+export type PredictionStrategy = 'linear-regression' | 'exponential-smoothing' | 'weighted-moving-average';
+
+/** Trend direction derived from slope */
+export type TrendDirection = 'rising' | 'stable' | 'declining' | 'insufficient-data';
+
+/** Exponential smoothing sensitivity presets */
+export type SmoothingPreset = 'responsive' | 'balanced' | 'smooth';
+
+/** Forecast horizon presets */
+export type HorizonPreset = '1-day' | '1-week' | '1-month' | '3-months' | '6-months' | '1-year';
+
+/** Human-readable confidence bracket */
+export type ConfidenceBracket = 'high' | 'moderate' | 'low' | 'insufficient-data';
+
+// ========================================
+// Preset Value Maps
+// ========================================
+
+export const SMOOTHING_PRESET_VALUES: Record<SmoothingPreset, { alpha: number; beta: number }> = {
+  'responsive': { alpha: 0.8, beta: 0.3 },
+  'balanced':   { alpha: 0.5, beta: 0.2 },
+  'smooth':     { alpha: 0.2, beta: 0.1 }
+};
+
+export const HORIZON_PRESET_VALUES: Record<HorizonPreset, number> = {
+  '1-day':    86_400_000,
+  '1-week':   604_800_000,
+  '1-month':  2_592_000_000,
+  '3-months': 7_776_000_000,
+  '6-months': 15_552_000_000,
+  '1-year':   31_104_000_000
+};
+
+// ========================================
+// Type Guards
+// ========================================
+
+export function isSmoothingPreset(value: unknown): value is SmoothingPreset {
+  return typeof value === 'string' && value in SMOOTHING_PRESET_VALUES;
+}
+
+export function isHorizonPreset(value: unknown): value is HorizonPreset {
+  return typeof value === 'string' && value in HORIZON_PRESET_VALUES;
+}
+
+// ========================================
+// Resolver Functions
+// ========================================
+
+/** Map a confidence value (0-1) to a semantic bracket */
+export function resolveConfidenceBracket(confidence: number): ConfidenceBracket {
+  if (confidence >= 0.8) return 'high';
+  if (confidence >= 0.5) return 'moderate';
+  if (confidence > 0) return 'low';
+  return 'insufficient-data';
+}
+
+/** Map a slope (per ms) to a semantic trend direction */
+export function resolveTrendDirection(slopePerMs: number, stableThreshold: number): TrendDirection {
+  if (Math.abs(slopePerMs) <= stableThreshold) return 'stable';
+  return slopePerMs > 0 ? 'rising' : 'declining';
+}
+
+// ========================================
+// Field Mapping
+// ========================================
+
+/** Configurable dot-path field mapping into fact.data */
+export type FieldMapping = {
+  entityId: string;
+  score: string;
+  timestamp: string;
+};
+
+// ========================================
+// Threshold Definition
+// ========================================
+
+export type ThresholdDefinition = {
+  id: string;
+  name?: string;
+  value: number;
+  direction: 'above' | 'below';
+};
+
+// ========================================
+// Strategy-Specific Config Types
+// ========================================
+
+export type LinearRegressionConfig = {
+  stableThreshold?: number;     // default: 0.001
+};
+
+export type ExponentialSmoothingConfig = {
+  smoothing?: SmoothingPreset | { alpha: number; beta: number };  // default: 'balanced'
+};
+
+export type WeightedMovingAverageConfig = {
+  window?: number;              // default: 5
+};
+
+// ========================================
+// Source RuleSet Types (Discriminated Union)
+// ========================================
+
+type PredictionRuleSetBase = {
+  id: string;
+  name?: string;
+  mode: 'prediction';
+  snapshotType: string;
+  fields: FieldMapping;
+  horizon: HorizonPreset | number;
+  thresholds?: ThresholdDefinition[];
+  defaultTrend?: number;        // score units per month
+};
+
+export type LinearRegressionRuleSet = PredictionRuleSetBase & {
+  strategy: 'linear-regression';
+  config?: LinearRegressionConfig;
+};
+
+export type ExponentialSmoothingRuleSet = PredictionRuleSetBase & {
+  strategy: 'exponential-smoothing';
+  config?: ExponentialSmoothingConfig;
+};
+
+export type WeightedMovingAverageRuleSet = PredictionRuleSetBase & {
+  strategy: 'weighted-moving-average';
+  config?: WeightedMovingAverageConfig;
+};
+
+export type PredictionRuleSet =
+  | LinearRegressionRuleSet
+  | ExponentialSmoothingRuleSet
+  | WeightedMovingAverageRuleSet;
+
+// ========================================
+// Compiled RuleSet Types
+// ========================================
+
+type CompiledPredictionRuleSetBase = {
+  id: string;
+  name?: string;
+  mode: 'prediction';
+  snapshotType: string;
+  fields: FieldMapping;
+  horizonMs: number;
+  thresholds: ThresholdDefinition[];
+  defaultTrend?: number;        // score units per month
+};
+
+export type CompiledLinearRegressionRuleSet = CompiledPredictionRuleSetBase & {
+  strategy: 'linear-regression';
+  config: {
+    stableThreshold: number;
+  };
+};
+
+export type CompiledExponentialSmoothingRuleSet = CompiledPredictionRuleSetBase & {
+  strategy: 'exponential-smoothing';
+  config: {
+    alpha: number;
+    beta: number;
+  };
+};
+
+export type CompiledWeightedMovingAverageRuleSet = CompiledPredictionRuleSetBase & {
+  strategy: 'weighted-moving-average';
+  config: {
+    window: number;
+  };
+};
+
+export type CompiledPredictionRuleSet =
+  | CompiledLinearRegressionRuleSet
+  | CompiledExponentialSmoothingRuleSet
+  | CompiledWeightedMovingAverageRuleSet;
+
+// ========================================
+// Result Types
+// ========================================
+
+export type ThresholdCrossing = {
+  thresholdId: string;
+  thresholdName?: string;
+  value: number;
+  direction: 'above' | 'below';
+  estimatedAt: Date;
+  estimatedAtIso: string;
+};
+
+export type Forecast = {
+  date: Date;
+  dateIso: string;
+  predictedScore: number;
+  confidenceInterval?: { lower: number; upper: number };
+};
+
+export type EntityPrediction = {
+  entityId: string;
+  dataPoints: number;
+  trend: TrendDirection;
+  trendSlope: number;            // score units per day
+  confidence: number;            // 0-1
+  confidenceBracket: ConfidenceBracket;
+  currentScore: number;          // most recent observed score
+  forecast: Forecast;            // projected score at horizon
+  thresholdCrossings: ThresholdCrossing[];
+  model: { strategy: PredictionStrategy; params: Record<string, number> };
+};
+
+export type PredictionResult = {
+  predictions: EntityPrediction[];
+  totalEntities: number;
+  strategy: PredictionStrategy;
+  horizonMs: number;
+  executionTimeMs: number;
+};
+
+export type PredictionOptions = {
+  onPredict?: (prediction: EntityPrediction) => void;
+  asOf?: Date;
+};

package/src/index.ts

@@ -445,6 +445,45 @@ export type {
   RankingResult
 } from './engines/ranking';
 
+// Prediction
+export {
+  PredictionEngine,
+  PredictionExecutor,
+  compilePredictionRuleSet,
+  predictionStrategy,
+  SMOOTHING_PRESET_VALUES,
+  HORIZON_PRESET_VALUES,
+  isSmoothingPreset,
+  isHorizonPreset,
+  resolveConfidenceBracket,
+  resolveTrendDirection
+} from './engines/prediction';
+export type {
+  PredictionStrategy,
+  TrendDirection,
+  SmoothingPreset,
+  HorizonPreset,
+  ConfidenceBracket,
+  FieldMapping,
+  ThresholdDefinition,
+  LinearRegressionConfig,
+  ExponentialSmoothingConfig,
+  WeightedMovingAverageConfig,
+  LinearRegressionRuleSet,
+  ExponentialSmoothingRuleSet,
+  WeightedMovingAverageRuleSet,
+  PredictionRuleSet,
+  CompiledLinearRegressionRuleSet,
+  CompiledExponentialSmoothingRuleSet,
+  CompiledWeightedMovingAverageRuleSet,
+  CompiledPredictionRuleSet,
+  ThresholdCrossing,
+  Forecast,
+  EntityPrediction,
+  PredictionResult,
+  PredictionOptions
+} from './engines/prediction';
+
 // ========================================
 // Utility Functions (from old modules, re-exported for convenience)
 // ========================================