@higher.archi/boe 1.0.0

package/src/engines/monte-carlo/compiler.ts

@@ -0,0 +1,459 @@
+/**
+ * Monte Carlo Engine Compiler
+ *
+ * Compiles user-friendly ruleset definitions into normalized internal format.
+ * Handles alias resolution and percent string parsing.
+ */
+
+import {
+  compileCondition,
+  normalizeShape,
+  Expression
+} from '../../core';
+
+import {
+  MonteCarloRuleSet,
+  MonteCarloVariable,
+  MonteCarloOutput,
+  MonteCarloConfig,
+  CompiledMonteCarloRuleSet,
+  CompiledVariable,
+  CompiledOutput,
+  CompiledFormulaFn,
+  PercentOrNumber,
+  ITERATIONS_DEFAULT,
+  ITERATIONS_MIN,
+  ITERATIONS_MAX,
+  ITERATION_PRESETS,
+  IterationPreset
+} from './types';
+
+// ========================================
+// Helper Functions
+// ========================================
+
+/**
+ * Parse percent string or return number as-is
+ * '50%' -> 0.50
+ * '5%' -> 0.05
+ * 0.5 -> 0.5
+ */
+function parsePercentOrNumber(value: PercentOrNumber): number {
+  if (typeof value === 'number') {
+    return value;
+  }
+
+  const str = value.trim();
+  if (str.endsWith('%')) {
+    const num = parseFloat(str.slice(0, -1));
+    return num / 100;
+  }
+
+  return parseFloat(str);
+}
+
+/**
+ * Compile input parameter (same as other engines)
+ */
+function compileInputParameter(input: any) {
+  const compiled: any = {
+    name: input.name,
+    type: input.type,
+    schema: input.shape ? normalizeShape(input.shape) : { type: 'object' }
+  };
+
+  if (input.where) {
+    compiled.where = compileCondition(input.where);
+  }
+
+  return compiled;
+}
+
+// ========================================
+// Variable Compilation
+// ========================================
+
+/**
+ * Determine distribution type from estimate alias
+ */
+function getDistributionType(estimate: string): 'triangular' | 'normal' | 'uniform' | 'discrete' {
+  switch (estimate) {
+    // Triangular aliases
+    case 'best-likely-worst':
+    case 'low-mid-high':
+    case 'min-expected-max':
+    case 'optimistic-realistic-pessimistic':
+      return 'triangular';
+
+    // Normal aliases
+    case 'typically-around':
+    case 'bell-curve':
+    case 'normal':
+      return 'normal';
+
+    // Uniform aliases
+    case 'anywhere-from':
+    case 'uniform':
+    case 'any-between':
+      return 'uniform';
+
+    // Discrete aliases
+    case 'one-of':
+    case 'weighted':
+    case 'choice':
+      return 'discrete';
+
+    default:
+      throw new Error(`Unknown estimate type: ${estimate}`);
+  }
+}
+
+/**
+ * Compile a triangular variable
+ */
+function compileTriangularVariable(variable: MonteCarloVariable): CompiledVariable {
+  const v = variable as any;
+
+  // Resolve aliases to canonical min/mode/max
+  let min: number, mode: number, max: number;
+
+  if ('best' in v) {
+    min = parsePercentOrNumber(v.best);
+    mode = parsePercentOrNumber(v.likely);
+    max = parsePercentOrNumber(v.worst);
+  } else if ('low' in v && 'mid' in v) {
+    min = parsePercentOrNumber(v.low);
+    mode = parsePercentOrNumber(v.mid);
+    max = parsePercentOrNumber(v.high);
+  } else if ('min' in v && 'expected' in v) {
+    min = parsePercentOrNumber(v.min);
+    mode = parsePercentOrNumber(v.expected);
+    max = parsePercentOrNumber(v.max);
+  } else if ('optimistic' in v) {
+    min = parsePercentOrNumber(v.optimistic);
+    mode = parsePercentOrNumber(v.realistic);
+    max = parsePercentOrNumber(v.pessimistic);
+  } else {
+    throw new Error(`Invalid triangular variable: ${variable.name}`);
+  }
+
+  return {
+    name: variable.name,
+    distribution: 'triangular',
+    params: { min, mode, max }
+  };
+}
+
+/**
+ * Compile a normal variable
+ */
+function compileNormalVariable(variable: MonteCarloVariable): CompiledVariable {
+  const v = variable as any;
+
+  // Resolve aliases to canonical mean/stdDev
+  const mean = parsePercentOrNumber(v.mean ?? v.value);
+  const stdDev = parsePercentOrNumber(v.stdDev ?? v.spread ?? v.varies);
+
+  if (mean === undefined || isNaN(mean)) {
+    throw new Error(`Normal variable '${variable.name}' requires mean or value`);
+  }
+  if (stdDev === undefined || isNaN(stdDev)) {
+    throw new Error(`Normal variable '${variable.name}' requires stdDev, spread, or varies`);
+  }
+
+  return {
+    name: variable.name,
+    distribution: 'normal',
+    params: { mean, stdDev }
+  };
+}
+
+/**
+ * Compile a uniform variable
+ */
+function compileUniformVariable(variable: MonteCarloVariable): CompiledVariable {
+  const v = variable as any;
+
+  // Resolve aliases to canonical min/max
+  const min = parsePercentOrNumber(v.min ?? v.low);
+  const max = parsePercentOrNumber(v.max ?? v.high);
+
+  if (min === undefined || isNaN(min)) {
+    throw new Error(`Uniform variable '${variable.name}' requires min or low`);
+  }
+  if (max === undefined || isNaN(max)) {
+    throw new Error(`Uniform variable '${variable.name}' requires max or high`);
+  }
+
+  return {
+    name: variable.name,
+    distribution: 'uniform',
+    params: { min, max }
+  };
+}
+
+/**
+ * Compile a discrete variable
+ */
+function compileDiscreteVariable(variable: MonteCarloVariable): CompiledVariable {
+  const v = variable as any;
+
+  if (!v.options || !Array.isArray(v.options)) {
+    throw new Error(`Discrete variable '${variable.name}' requires options array`);
+  }
+
+  // Default to equal weights if not specified
+  const weights = v.weights ?? v.options.map(() => 1 / v.options.length);
+
+  // Normalize weights to sum to 1
+  const totalWeight = weights.reduce((sum: number, w: number) => sum + w, 0);
+  const normalizedWeights = weights.map((w: number) => w / totalWeight);
+
+  return {
+    name: variable.name,
+    distribution: 'discrete',
+    params: {
+      options: v.options,
+      weights: normalizedWeights
+    }
+  };
+}
+
+/**
+ * Compile a single variable
+ */
+function compileVariable(variable: MonteCarloVariable): CompiledVariable {
+  const distribution = getDistributionType(variable.estimate);
+
+  switch (distribution) {
+    case 'triangular':
+      return compileTriangularVariable(variable);
+    case 'normal':
+      return compileNormalVariable(variable);
+    case 'uniform':
+      return compileUniformVariable(variable);
+    case 'discrete':
+      return compileDiscreteVariable(variable);
+    default:
+      throw new Error(`Unknown distribution: ${distribution}`);
+  }
+}
+
+// ========================================
+// Formula to Function Compilation
+// ========================================
+
+/**
+ * Compile a formula expression into a JavaScript function for fast evaluation.
+ * This avoids the overhead of interpreted evaluation during simulation.
+ */
+function compileFormulaToFunction(formula: Expression): CompiledFormulaFn {
+  const code = generateFormulaCode(formula);
+  // Create function from generated code
+  // Using Function constructor for performance (eval alternative)
+  try {
+    return new Function('ctx', `return ${code};`) as CompiledFormulaFn;
+  } catch (e) {
+    // Fall back to null if code generation fails
+    console.warn(`Failed to compile formula: ${code}`, e);
+    return null as any;
+  }
+}
+
+/**
+ * Generate JavaScript code from a formula expression
+ * Uses 'any' type to avoid complex type narrowing issues with Expression union type
+ */
+function generateFormulaCode(expr: any): string {
+  // Handle primitive values
+  if (typeof expr === 'number') {
+    return String(expr);
+  }
+
+  if (typeof expr === 'string') {
+    // Variable reference: $varName or $input.field
+    if (expr.startsWith('$')) {
+      const path = expr.slice(1);  // Remove $
+      return `(ctx["${path}"] ?? 0)`;
+    }
+    // String literal (shouldn't happen in formulas, but handle it)
+    return JSON.stringify(expr);
+  }
+
+  if (typeof expr === 'boolean') {
+    return expr ? '1' : '0';
+  }
+
+  // Handle array expressions (operators)
+  if (Array.isArray(expr)) {
+    const [operator, ...args] = expr;
+
+    switch (operator) {
+      // Arithmetic operators
+      case 'add':
+        if (args.length === 0) return '0';
+        return `(${args.map(generateFormulaCode).join(' + ')})`;
+
+      case 'subtract':
+        if (args.length === 0) return '0';
+        if (args.length === 1) return `(-${generateFormulaCode(args[0])})`;
+        return `(${args.map(generateFormulaCode).join(' - ')})`;
+
+      case 'multiply':
+        if (args.length === 0) return '1';
+        return `(${args.map(generateFormulaCode).join(' * ')})`;
+
+      case 'divide':
+        if (args.length < 2) return '0';
+        return `(${generateFormulaCode(args[0])} / (${generateFormulaCode(args[1])} || 1))`;
+
+      case 'power':
+      case 'pow':
+        if (args.length < 2) return '1';
+        return `Math.pow(${generateFormulaCode(args[0])}, ${generateFormulaCode(args[1])})`;
+
+      case 'sqrt':
+        return `Math.sqrt(${generateFormulaCode(args[0])})`;
+
+      case 'abs':
+        return `Math.abs(${generateFormulaCode(args[0])})`;
+
+      case 'min':
+        return `Math.min(${args.map(generateFormulaCode).join(', ')})`;
+
+      case 'max':
+        return `Math.max(${args.map(generateFormulaCode).join(', ')})`;
+
+      case 'floor':
+        return `Math.floor(${generateFormulaCode(args[0])})`;
+
+      case 'ceil':
+        return `Math.ceil(${generateFormulaCode(args[0])})`;
+
+      case 'round':
+        return `Math.round(${generateFormulaCode(args[0])})`;
+
+      case 'log':
+        return `Math.log(${generateFormulaCode(args[0])})`;
+
+      case 'exp':
+        return `Math.exp(${generateFormulaCode(args[0])})`;
+
+      // Comparison operators (return 1 or 0)
+      case 'greaterThan':
+        return `(${generateFormulaCode(args[0])} > ${generateFormulaCode(args[1])} ? 1 : 0)`;
+
+      case 'greaterThanOrEquals':
+        return `(${generateFormulaCode(args[0])} >= ${generateFormulaCode(args[1])} ? 1 : 0)`;
+
+      case 'lessThan':
+        return `(${generateFormulaCode(args[0])} < ${generateFormulaCode(args[1])} ? 1 : 0)`;
+
+      case 'lessThanOrEquals':
+        return `(${generateFormulaCode(args[0])} <= ${generateFormulaCode(args[1])} ? 1 : 0)`;
+
+      case 'equals':
+        return `(${generateFormulaCode(args[0])} === ${generateFormulaCode(args[1])} ? 1 : 0)`;
+
+      case 'notEquals':
+        return `(${generateFormulaCode(args[0])} !== ${generateFormulaCode(args[1])} ? 1 : 0)`;
+
+      // Logical operators
+      case 'and':
+        return `((${args.map(generateFormulaCode).join(' && ')}) ? 1 : 0)`;
+
+      case 'or':
+        return `((${args.map(generateFormulaCode).join(' || ')}) ? 1 : 0)`;
+
+      case 'not':
+        return `(${generateFormulaCode(args[0])} ? 0 : 1)`;
+
+      // Conditional
+      case 'if':
+        return `(${generateFormulaCode(args[0])} ? ${generateFormulaCode(args[1])} : ${generateFormulaCode(args[2] ?? 0)})`;
+
+      // Clamp
+      case 'clamp':
+        return `Math.min(Math.max(${generateFormulaCode(args[0])}, ${generateFormulaCode(args[1])}), ${generateFormulaCode(args[2])})`;
+
+      default:
+        // Unknown operator - return 0
+        console.warn(`Unknown formula operator: ${operator}`);
+        return '0';
+    }
+  }
+
+  // Unknown type
+  return '0';
+}
+
+// ========================================
+// Output Compilation
+// ========================================
+
+/**
+ * Compile an output definition
+ */
+function compileOutput(output: MonteCarloOutput): CompiledOutput {
+  const compiledFormula = compileCondition(output.formula as Expression);
+  const evaluateFn = compileFormulaToFunction(output.formula);
+
+  return {
+    name: output.name,
+    formula: compiledFormula,
+    evaluate: evaluateFn || undefined
+  };
+}
+
+// ========================================
+// RuleSet Compilation
+// ========================================
+
+/**
+ * Resolve iterations from number, preset name, or default
+ */
+function resolveIterations(iterations: number | IterationPreset | undefined, configIterations: number | undefined): number {
+  // Try ruleset.iterations first
+  if (iterations !== undefined) {
+    if (typeof iterations === 'string') {
+      // Preset name: 'quick', 'standard', 'precise'
+      return ITERATION_PRESETS[iterations] ?? ITERATIONS_DEFAULT;
+    }
+    // Clamp numeric value to valid range
+    return Math.min(ITERATIONS_MAX, Math.max(ITERATIONS_MIN, iterations));
+  }
+
+  // Try config.iterations
+  if (configIterations !== undefined) {
+    return Math.min(ITERATIONS_MAX, Math.max(ITERATIONS_MIN, configIterations));
+  }
+
+  // Default
+  return ITERATIONS_DEFAULT;
+}
+
+/**
+ * Compile a Monte Carlo ruleset
+ */
+export function compileMonteCarloRuleSet(ruleSet: MonteCarloRuleSet): CompiledMonteCarloRuleSet {
+  const iterations = resolveIterations(ruleSet.iterations, ruleSet.config?.iterations);
+
+  const config: MonteCarloConfig = {
+    mode: 'monte-carlo',
+    iterations,
+    seed: ruleSet.config?.seed,
+    percentiles: ruleSet.config?.percentiles ?? [5, 10, 25, 50, 75, 90, 95],
+    includeSensitivity: ruleSet.config?.includeSensitivity ?? true  // Default ON for key driver insights
+  };
+
+  return {
+    id: ruleSet.id,
+    name: ruleSet.name,
+    mode: 'monte-carlo',
+    schema: ruleSet.shape ? normalizeShape(ruleSet.shape) : { type: 'object' },
+    inputs: (ruleSet.inputs ?? []).map(compileInputParameter),
+    variables: ruleSet.variables.map(compileVariable),
+    outputs: ruleSet.outputs.map(compileOutput),
+    config
+  };
+}

package/src/engines/monte-carlo/engine.ts

@@ -0,0 +1,134 @@
+/**
+ * Monte Carlo Engine
+ *
+ * Self-contained engine for Monte Carlo simulation.
+ * Implements IRuleEngine with strongly-typed ruleset, options, and result.
+ */
+
+import {
+  IRuleEngine,
+  WorkingMemory,
+  Fact,
+  FactInput,
+  FactChange
+} from '../../core';
+
+import {
+  CompiledMonteCarloRuleSet,
+  MonteCarloOptions,
+  MonteCarloResult
+} from './types';
+
+import { MonteCarloStrategy } from './strategy';
+
+/**
+ * Monte Carlo simulation engine.
+ *
+ * Runs thousands of iterations with probabilistic inputs to generate
+ * statistical distributions of possible outcomes.
+ *
+ * @example
+ * ```typescript
+ * const engine = new MonteCarloEngine();
+ *
+ * // Add known facts
+ * engine.add({ type: 'Project', data: { hoursPerWeek: 40 } });
+ *
+ * // Run simulation
+ * const result = engine.simulate(compiledRules);
+ *
+ * console.log(`Mean cost: $${result.outputs.totalCost.mean}`);
+ * console.log(`90th percentile: $${result.outputs.totalCost.percentiles.p90}`);
+ * console.log(`Probability under budget: ${result.probability('totalCost < 300000')}`);
+ * ```
+ */
+export class MonteCarloEngine implements IRuleEngine<CompiledMonteCarloRuleSet, MonteCarloOptions, MonteCarloResult> {
+  private wm: WorkingMemory;
+  private strategy: MonteCarloStrategy;
+
+  constructor(workingMemory?: WorkingMemory) {
+    this.wm = workingMemory ?? new WorkingMemory();
+    this.strategy = new MonteCarloStrategy();
+  }
+
+  // ========================================
+  // IWorkingMemory Implementation
+  // ========================================
+
+  add(input: FactInput): Fact {
+    return this.wm.add(input);
+  }
+
+  remove(factId: string): Fact | undefined {
+    return this.wm.remove(factId);
+  }
+
+  update(input: FactInput): Fact {
+    return this.wm.update(input);
+  }
+
+  get(factId: string): Fact | undefined {
+    return this.wm.get(factId);
+  }
+
+  getByType(type: string): Fact[] {
+    return this.wm.getByType(type);
+  }
+
+  getAll(): Fact[] {
+    return this.wm.getAll();
+  }
+
+  has(factId: string): boolean {
+    return this.wm.has(factId);
+  }
+
+  size(): number {
+    return this.wm.size();
+  }
+
+  clear(): void {
+    this.wm.clear();
+  }
+
+  getChanges(): FactChange[] {
+    return this.wm.getChanges();
+  }
+
+  clearChanges(): void {
+    this.wm.clearChanges();
+  }
+
+  // ========================================
+  // IRuleEngine Implementation
+  // ========================================
+
+  /**
+   * Execute Monte Carlo simulation.
+   *
+   * Runs the configured number of iterations, sampling from
+   * probabilistic variables and computing output formulas.
+   *
+   * @param ruleSet - Compiled Monte Carlo ruleset
+   * @param options - Runtime options (callbacks)
+   * @returns Result with statistics, sensitivity analysis, and probability queries
+   */
+  execute(ruleSet: CompiledMonteCarloRuleSet, options: MonteCarloOptions = {}): MonteCarloResult {
+    return this.strategy.run(ruleSet, this.wm, options);
+  }
+
+  /**
+   * Alias for execute - more semantically clear for Monte Carlo
+   */
+  simulate(ruleSet: CompiledMonteCarloRuleSet, options: MonteCarloOptions = {}): MonteCarloResult {
+    return this.execute(ruleSet, options);
+  }
+
+  // ========================================
+  // Utility Methods
+  // ========================================
+
+  getWorkingMemory(): WorkingMemory {
+    return this.wm;
+  }
+}

package/src/engines/monte-carlo/index.ts

@@ -0,0 +1,44 @@
+/**
+ * Monte Carlo Engine
+ *
+ * Provides uncertainty quantification through random sampling.
+ * Run thousands of simulations with probabilistic inputs to get
+ * statistical distributions of possible outcomes.
+ */
+
+// Types
+export {
+  // Estimate types
+  EstimateType,
+  PercentOrNumber,
+  // Variable types
+  TriangularVariable,
+  NormalVariable,
+  UniformVariable,
+  DiscreteVariable,
+  MonteCarloVariable,
+  // Output types
+  MonteCarloOutput,
+  // Source types
+  MonteCarloRuleSet,
+  MonteCarloConfig,
+  // Compiled types
+  CompiledVariable,
+  CompiledOutput,
+  CompiledMonteCarloRuleSet,
+  // Runtime types
+  MonteCarloOptions,
+  OutputStatistics,
+  HistogramBin,
+  SensitivityAnalysis,
+  MonteCarloResult
+} from './types';
+
+// Compiler
+export { compileMonteCarloRuleSet } from './compiler';
+
+// Strategy
+export { MonteCarloStrategy, monteCarloStrategy } from './strategy';
+
+// Engine
+export { MonteCarloEngine } from './engine';