@higher.archi/boe 1.0.0

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

@@ -0,0 +1,320 @@
+/**
+ * Monte Carlo Engine Types
+ *
+ * Provides uncertainty quantification through random sampling.
+ * Run thousands of simulations with probabilistic inputs to get
+ * statistical distributions of possible outcomes.
+ */
+
+import {
+  BaseRuleSet,
+  CompiledBaseRuleSet,
+  CompiledCondition,
+  InputParameter,
+  CompiledInputParameter,
+  Expression,
+  Condition
+} from '../../core';
+
+// ========================================
+// Iteration Presets & Constants
+// ========================================
+
+/**
+ * Iteration presets for Monte Carlo simulations.
+ *
+ * Monte Carlo error follows: Error ∝ 1/√n
+ *
+ * | Preset   | Iterations | Relative Error | Use Case                      |
+ * |----------|------------|----------------|-------------------------------|
+ * | quick    | 2,500      | 2.00%          | Development, quick estimates  |
+ * | standard | 5,000      | 1.41%          | Production default            |
+ * | precise  | 10,000     | 1.00%          | Final reports, tail analysis  |
+ *
+ * Why cap at 10,000? Diminishing returns:
+ * - 50k iterations: only ~2.2x more accurate than 10k, but 5x slower
+ * - To halve the error, must quadruple iterations
+ */
+export const ITERATIONS_QUICK = 2500;
+export const ITERATIONS_STANDARD = 5000;
+export const ITERATIONS_PRECISE = 10000;
+
+export const ITERATIONS_MIN = ITERATIONS_QUICK;
+export const ITERATIONS_MAX = ITERATIONS_PRECISE;
+export const ITERATIONS_DEFAULT = ITERATIONS_STANDARD;
+
+export type IterationPreset = 'quick' | 'standard' | 'precise';
+
+export const ITERATION_PRESETS: Record<IterationPreset, number> = {
+  quick: ITERATIONS_QUICK,
+  standard: ITERATIONS_STANDARD,
+  precise: ITERATIONS_PRECISE
+};
+
+// ========================================
+// Estimate Type Aliases (for readability)
+// ========================================
+
+/**
+ * Estimate type determines the probability distribution shape.
+ * Multiple aliases supported for different audiences.
+ */
+export type EstimateType =
+  // Triangular distribution (three-point estimate)
+  | 'best-likely-worst'           // Project management terminology
+  | 'low-mid-high'                // Simple/casual
+  | 'min-expected-max'            // Statistical terminology
+  | 'optimistic-realistic-pessimistic'  // Risk analysis terminology
+
+  // Normal distribution (bell curve)
+  | 'typically-around'            // Layperson-friendly
+  | 'bell-curve'                  // Technical
+  | 'normal'                      // Statistical
+
+  // Uniform distribution (equal probability)
+  | 'anywhere-from'               // Layperson-friendly
+  | 'uniform'                     // Technical
+  | 'any-between'                 // Alternative
+
+  // Discrete distribution (weighted choices)
+  | 'one-of'                      // Layperson-friendly
+  | 'weighted'                    // Technical
+  | 'choice';                     // Alternative
+
+// ========================================
+// Variable Definitions
+// ========================================
+
+/**
+ * Percent or number value
+ * Strings ending in '%' are parsed: '50%' -> 0.50
+ */
+export type PercentOrNumber = number | string;
+
+/**
+ * Triangular distribution variable (three-point estimate)
+ */
+export type TriangularVariable = {
+  name: string;
+  estimate: 'best-likely-worst' | 'low-mid-high' | 'min-expected-max' | 'optimistic-realistic-pessimistic';
+} & (
+  | { best: PercentOrNumber; likely: PercentOrNumber; worst: PercentOrNumber }
+  | { low: PercentOrNumber; mid: PercentOrNumber; high: PercentOrNumber }
+  | { min: PercentOrNumber; expected: PercentOrNumber; max: PercentOrNumber }
+  | { optimistic: PercentOrNumber; realistic: PercentOrNumber; pessimistic: PercentOrNumber }
+);
+
+/**
+ * Normal distribution variable (bell curve)
+ */
+export type NormalVariable = {
+  name: string;
+  estimate: 'typically-around' | 'bell-curve' | 'normal';
+  value?: PercentOrNumber;   // alias for mean (typically-around)
+  mean?: PercentOrNumber;    // center of distribution
+  varies?: PercentOrNumber;  // alias for stdDev (typically-around)
+  spread?: PercentOrNumber;  // alias for stdDev
+  stdDev?: PercentOrNumber;  // standard deviation
+};
+
+/**
+ * Uniform distribution variable (equal probability in range)
+ */
+export type UniformVariable = {
+  name: string;
+  estimate: 'anywhere-from' | 'uniform' | 'any-between';
+  low?: PercentOrNumber;     // alias for min
+  high?: PercentOrNumber;    // alias for max
+  min?: PercentOrNumber;
+  max?: PercentOrNumber;
+};
+
+/**
+ * Discrete distribution variable (weighted choices)
+ */
+export type DiscreteVariable = {
+  name: string;
+  estimate: 'one-of' | 'weighted' | 'choice';
+  options: number[];
+  weights?: number[];  // Optional - defaults to equal probability
+};
+
+/**
+ * Union of all variable types
+ */
+export type MonteCarloVariable =
+  | TriangularVariable
+  | NormalVariable
+  | UniformVariable
+  | DiscreteVariable;
+
+// ========================================
+// Output Definitions
+// ========================================
+
+/**
+ * Output definition - computed value tracked across simulations
+ */
+export type MonteCarloOutput = {
+  name: string;
+  formula: Expression;
+};
+
+// ========================================
+// Source Types (User-Defined)
+// ========================================
+
+/**
+ * Monte Carlo ruleset - defines inputs, variables, and outputs
+ */
+export type MonteCarloRuleSet = BaseRuleSet & {
+  mode: 'monte-carlo';
+  iterations?: number | IterationPreset;  // Default: 5000 ('standard'). Options: 2500-10000 or 'quick'|'standard'|'precise'
+
+  // Facts from working memory
+  inputs?: InputParameter[];
+
+  // Probabilistic variables
+  variables: MonteCarloVariable[];
+
+  // Computed outputs to track
+  outputs: MonteCarloOutput[];
+
+  config?: Partial<MonteCarloConfig>;
+};
+
+/**
+ * Monte Carlo configuration
+ */
+export type MonteCarloConfig = {
+  mode: 'monte-carlo';
+  iterations: number;
+  seed?: number;  // For reproducible results
+  percentiles?: number[];  // Which percentiles to calculate (default: [5, 10, 25, 50, 75, 90, 95])
+  includeSensitivity?: boolean;  // Include sensitivity analysis (default: false for performance)
+};
+
+// ========================================
+// Compiled Types
+// ========================================
+
+/**
+ * Normalized variable (all aliases resolved to canonical form)
+ */
+export type CompiledVariable = {
+  name: string;
+  distribution: 'triangular' | 'normal' | 'uniform' | 'discrete';
+  params: {
+    // Triangular
+    min?: number;
+    mode?: number;  // "likely" value
+    max?: number;
+    // Normal
+    mean?: number;
+    stdDev?: number;
+    // Discrete
+    options?: number[];
+    weights?: number[];
+  };
+};
+
+/**
+ * Context for formula evaluation - flat key-value lookup
+ */
+export type FormulaContext = Record<string, number>;
+
+/**
+ * Pre-compiled formula function for fast evaluation
+ */
+export type CompiledFormulaFn = (ctx: FormulaContext) => number;
+
+/**
+ * Compiled output
+ */
+export type CompiledOutput = {
+  name: string;
+  formula: CompiledCondition;
+  evaluate?: CompiledFormulaFn;  // Pre-compiled function for fast evaluation
+};
+
+/**
+ * Compiled Monte Carlo ruleset
+ */
+export type CompiledMonteCarloRuleSet = CompiledBaseRuleSet & {
+  mode: 'monte-carlo';
+  inputs: CompiledInputParameter[];
+  variables: CompiledVariable[];
+  outputs: CompiledOutput[];
+  config: MonteCarloConfig;
+};
+
+// ========================================
+// Runtime Types
+// ========================================
+
+/**
+ * Runtime options for simulation
+ */
+export type MonteCarloOptions = {
+  onIteration?: (iteration: number, values: Record<string, number>) => void;
+  onProgress?: (percent: number) => void;
+};
+
+/**
+ * Statistics for a single output variable
+ */
+export type OutputStatistics = {
+  mean: number;
+  median: number;
+  stdDev: number;
+  min: number;
+  max: number;
+  percentiles: Record<string, number>;  // p5, p10, p25, p50, p75, p90, p95
+  histogram: HistogramBin[];
+};
+
+/**
+ * Histogram bin
+ */
+export type HistogramBin = {
+  min: number;
+  max: number;
+  count: number;
+  probability: number;
+};
+
+/**
+ * Sensitivity analysis result
+ */
+export type SensitivityAnalysis = {
+  [outputName: string]: {
+    [variableName: string]: number;  // Absolute correlation (0 to 1)
+  };
+};
+
+/**
+ * Execution result
+ */
+export type MonteCarloResult = {
+  iterations: number;
+  outputs: Record<string, OutputStatistics>;
+  sensitivity: SensitivityAnalysis;
+  executionTimeMs: number;  // Processing time in milliseconds
+
+  /**
+   * Helper method for probability queries
+   *
+   * Accepts array condition: ['greaterThan', '$totalCost', 500000]
+   *
+   * Examples:
+   *   probability(['greaterThan', '$totalCost', 500000])
+   *   probability(['and', ['lessThan', '$weeks', 10], ['lessThanOrEquals', '$budget', 100000]])
+   */
+  probability: (query: Condition) => number;
+
+  // Raw data for custom analysis
+  rawData?: {
+    variables: Record<string, number[]>;
+    outputs: Record<string, number[]>;
+  };
+};

package/src/engines/pricing/calculator.ts

@@ -0,0 +1,272 @@
+/**
+ * Pricing Calculator Utilities
+ *
+ * Core calculation functions for different pricing modes:
+ * - Flat: Simple quantity * price
+ * - Graduated: Each tier priced separately
+ * - Volume: Total volume determines single rate for all units
+ */
+
+import {
+  TierBreakdown,
+  CompiledGraduatedTier,
+  CompiledVolumeBracket
+} from './types';
+
+import { CompiledOperand } from '../../core';
+
+/**
+ * Context for resolving operand values.
+ */
+export type CalculatorContext = {
+  /** Resolve a compiled operand to its value */
+  resolve: (operand: CompiledOperand) => number;
+};
+
+/**
+ * Result from a tier calculation.
+ */
+export type TierCalculationResult = {
+  /** Total calculated price */
+  total: number;
+  /** Breakdown by tier */
+  breakdown: TierBreakdown[];
+};
+
+/**
+ * Calculate flat pricing.
+ *
+ * @param quantity - Number of units
+ * @param pricePerUnit - Price per unit operand
+ * @param context - Context for resolving operands
+ * @returns Calculation result
+ */
+export function calculateFlat(
+  quantity: number,
+  pricePerUnit: CompiledOperand,
+  context: CalculatorContext
+): TierCalculationResult {
+  const rate = context.resolve(pricePerUnit);
+  const total = quantity * rate;
+
+  return {
+    total,
+    breakdown: [{
+      tier: 'Flat',
+      range: `All units`,
+      units: quantity,
+      rate,
+      subtotal: total
+    }]
+  };
+}
+
+/**
+ * Calculate graduated pricing.
+ *
+ * In graduated pricing, each tier applies only to units within its range.
+ * Example: First 1M at $0.20, next 4M at $0.10
+ * For 3M units: (1M * $0.20) + (2M * $0.10) = $400
+ *
+ * @param quantity - Total number of units
+ * @param tiers - Graduated tiers (must be sorted by upTo ascending)
+ * @param context - Context for resolving operands
+ * @returns Calculation result with breakdown
+ */
+export function calculateGraduated(
+  quantity: number,
+  tiers: CompiledGraduatedTier[],
+  context: CalculatorContext
+): TierCalculationResult {
+  const breakdown: TierBreakdown[] = [];
+  let remaining = quantity;
+  let total = 0;
+  let previousUpTo = 0;
+
+  for (let i = 0; i < tiers.length && remaining > 0; i++) {
+    const tier = tiers[i];
+    const rate = context.resolve(tier.pricePerUnit);
+
+    // Calculate units in this tier
+    const tierCapacity = tier.upTo === Infinity
+      ? remaining
+      : tier.upTo - previousUpTo;
+    const unitsInTier = Math.min(remaining, tierCapacity);
+
+    if (unitsInTier > 0) {
+      const subtotal = unitsInTier * rate;
+      total += subtotal;
+
+      // Format range string
+      const rangeStart = formatNumber(previousUpTo + 1);
+      const rangeEnd = tier.upTo === Infinity
+        ? 'Unlimited'
+        : formatNumber(tier.upTo);
+
+      breakdown.push({
+        tier: `Tier ${i + 1}`,
+        range: `${rangeStart} - ${rangeEnd}`,
+        units: unitsInTier,
+        rate,
+        subtotal
+      });
+
+      remaining -= unitsInTier;
+    }
+
+    previousUpTo = tier.upTo;
+  }
+
+  return { total, breakdown };
+}
+
+/**
+ * Calculate volume pricing.
+ *
+ * In volume pricing, total volume determines a single rate applied to ALL units.
+ * Example: <1M at $0.20, 1M-5M at $0.15, >5M at $0.10
+ * For 3M units: 3M * $0.15 = $450 (single rate)
+ *
+ * @param quantity - Total number of units
+ * @param brackets - Volume brackets (must be sorted by minVolume ascending)
+ * @param context - Context for resolving operands
+ * @returns Calculation result
+ */
+export function calculateVolume(
+  quantity: number,
+  brackets: CompiledVolumeBracket[],
+  context: CalculatorContext
+): TierCalculationResult {
+  // Find applicable bracket (last one where minVolume <= quantity)
+  let applicableBracket = brackets[0];
+  let bracketIndex = 0;
+
+  for (let i = 0; i < brackets.length; i++) {
+    if (brackets[i].minVolume <= quantity) {
+      applicableBracket = brackets[i];
+      bracketIndex = i;
+    } else {
+      break;
+    }
+  }
+
+  const rate = context.resolve(applicableBracket.pricePerUnit);
+  const total = quantity * rate;
+
+  // Format bracket range
+  const nextBracket = brackets[bracketIndex + 1];
+  const rangeStart = formatNumber(applicableBracket.minVolume);
+  const rangeEnd = nextBracket
+    ? formatNumber(nextBracket.minVolume - 1)
+    : 'Unlimited';
+
+  return {
+    total,
+    breakdown: [{
+      tier: `Volume Bracket`,
+      range: `${rangeStart} - ${rangeEnd}`,
+      units: quantity,
+      rate,
+      subtotal: total
+    }]
+  };
+}
+
+/**
+ * Format a number with thousands separators.
+ */
+export function formatNumber(n: number): string {
+  if (n === 0) return '0';
+  if (n === Infinity) return 'Unlimited';
+  return n.toLocaleString('en-US');
+}
+
+/**
+ * Format currency value.
+ */
+export function formatCurrency(
+  value: number,
+  currency: string = 'USD',
+  precision: number = 2
+): string {
+  return new Intl.NumberFormat('en-US', {
+    style: 'currency',
+    currency,
+    minimumFractionDigits: precision,
+    maximumFractionDigits: precision
+  }).format(value);
+}
+
+/**
+ * Format percentage value.
+ */
+export function formatPercent(value: number, precision: number = 2): string {
+  return `${value.toFixed(precision)}%`;
+}
+
+/**
+ * Round to specified precision.
+ */
+export function round(value: number, precision: number): number {
+  const factor = Math.pow(10, precision);
+  return Math.round(value * factor) / factor;
+}
+
+/**
+ * Calculate discount amount.
+ *
+ * @param total - Base amount
+ * @param percent - Percentage discount (0-100)
+ * @param fixedAmount - Fixed amount discount
+ * @returns Discount amount (positive value to subtract)
+ */
+export function calculateDiscount(
+  total: number,
+  percent?: number,
+  fixedAmount?: number
+): number {
+  let discount = 0;
+
+  if (percent !== undefined && percent > 0) {
+    discount += total * (percent / 100);
+  }
+
+  if (fixedAmount !== undefined && fixedAmount > 0) {
+    discount += fixedAmount;
+  }
+
+  // Don't allow discount greater than total
+  return Math.min(discount, total);
+}
+
+/**
+ * Apply minimum/maximum caps.
+ *
+ * @param value - Current value
+ * @param min - Minimum value (optional)
+ * @param max - Maximum value (optional)
+ * @returns Capped value
+ */
+export function applyMinMax(
+  value: number,
+  min?: number,
+  max?: number
+): { value: number; adjustment: number; type?: 'minimum' | 'maximum' } {
+  if (min !== undefined && value < min) {
+    return {
+      value: min,
+      adjustment: min - value,
+      type: 'minimum'
+    };
+  }
+
+  if (max !== undefined && value > max) {
+    return {
+      value: max,
+      adjustment: value - max,
+      type: 'maximum'
+    };
+  }
+
+  return { value, adjustment: 0 };
+}