@higher.archi/boe 1.0.0

package/src/engines/bayesian/compiler.ts

@@ -0,0 +1,402 @@
+/**
+ * Bayesian Engine Compiler
+ *
+ * Compiles Bayesian rulesets, validating hypothesis references
+ * and normalizing likelihood values to numeric form.
+ */
+
+import {
+  compileCondition,
+  normalizeShape,
+  Expression,
+  parsePath
+} from '../../core';
+
+import {
+  BayesianRule,
+  BayesianRuleSet,
+  BayesianConfig,
+  CompiledBayesianRule,
+  CompiledBayesianRuleSet,
+  CompiledHypothesis,
+  CompiledLikelihoodMap,
+  Hypothesis,
+  LikelihoodValue,
+  LikelihoodMap,
+  PriorValue,
+  SEMANTIC_LIKELIHOODS,
+  SemanticLikelihood
+} from './types';
+
+// ========================================
+// Helper Functions
+// ========================================
+
+function countConditions(condition?: any): number {
+  if (!condition) return 0;
+  if (condition.children) {
+    return 1 + condition.children.reduce((sum: number, c: any) => sum + countConditions(c), 0);
+  }
+  return 1;
+}
+
+function calculateComplexity(inputs: any[], when?: any): number {
+  let score = 0;
+  score += inputs.length * 10;
+  score += countConditions(when) * 5;
+  for (const input of inputs) {
+    score += countConditions(input.where) * 2;
+  }
+  return score;
+}
+
+function compilePath(from: string) {
+  const str = from.startsWith('$') ? from.slice(1) : from;
+  const parts = str.split('.');
+  return {
+    param: parts[0],
+    path: parts.slice(1)
+  };
+}
+
+// ========================================
+// Parameter Compilation
+// ========================================
+
+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);
+  }
+
+  if (input.from) {
+    compiled.from = compilePath(input.from);
+  }
+
+  return compiled;
+}
+
+// ========================================
+// Likelihood Parsing
+// ========================================
+
+/**
+ * Parse a likelihood value to its numeric form
+ *
+ * Supports:
+ * - number: 4.0 -> 4.0
+ * - '+Nx': '+4x' -> 4.0
+ * - '-Nx': '-5x' -> 0.2 (1/5)
+ * - { favors: N }: { favors: 4 } -> 4.0
+ * - { against: N }: { against: 5 } -> 0.2 (1/5)
+ * - semantic: 'strongly-favors' -> 5.0
+ */
+export function parseLikelihood(value: LikelihoodValue): number {
+  // Raw number
+  if (typeof value === 'number') {
+    return value;
+  }
+
+  // String format
+  if (typeof value === 'string') {
+    // Check semantic labels first
+    if (value in SEMANTIC_LIKELIHOODS) {
+      return SEMANTIC_LIKELIHOODS[value as SemanticLikelihood];
+    }
+
+    // Check +Nx / -Nx format
+    const match = value.match(/^([+-])(\d+(?:\.\d+)?)x$/);
+    if (match) {
+      const [, sign, num] = match;
+      const n = parseFloat(num);
+      return sign === '+' ? n : 1 / n;
+    }
+
+    throw new Error(`Invalid likelihood string: ${value}`);
+  }
+
+  // Object format
+  if (typeof value === 'object' && value !== null) {
+    if ('favors' in value) {
+      return (value as { favors: number }).favors;
+    }
+    if ('against' in value) {
+      return 1 / (value as { against: number }).against;
+    }
+  }
+
+  throw new Error(`Invalid likelihood format: ${JSON.stringify(value)}`);
+}
+
+/**
+ * Compile a likelihood map, converting all values to numbers
+ */
+function compileLikelihoodMap(
+  likelihood: LikelihoodMap,
+  hypothesisNames: Set<string>,
+  ruleId: string
+): CompiledLikelihoodMap {
+  const compiled: CompiledLikelihoodMap = {};
+
+  for (const [hypothesis, value] of Object.entries(likelihood)) {
+    // Validate hypothesis exists
+    if (!hypothesisNames.has(hypothesis)) {
+      throw new Error(
+        `Rule "${ruleId}" references unknown hypothesis "${hypothesis}". ` +
+        `Available: ${Array.from(hypothesisNames).join(', ')}`
+      );
+    }
+
+    compiled[hypothesis] = parseLikelihood(value);
+  }
+
+  return compiled;
+}
+
+// ========================================
+// Hypothesis Compilation
+// ========================================
+
+/**
+ * Extract hypothesis name from definition
+ */
+function getHypothesisName(h: Hypothesis): string {
+  return typeof h === 'string' ? h : h.name;
+}
+
+/**
+ * Compile a prior value (static, fact ref, or expression)
+ */
+function compilePrior(prior: PriorValue | undefined): number | any {
+  if (prior === undefined) {
+    return undefined; // Will be auto-filled later
+  }
+
+  // Static number
+  if (typeof prior === 'number') {
+    return prior;
+  }
+
+  // Fact reference string: '$creditReport.defaultRate'
+  if (typeof prior === 'string' && prior.startsWith('$')) {
+    return parsePath(prior);  // Returns CompiledPath
+  }
+
+  // Expression array: ['if', ...], ['multiply', ...]
+  if (Array.isArray(prior)) {
+    return compileCondition(prior as Expression);
+  }
+
+  throw new Error(`Invalid prior value: ${JSON.stringify(prior)}`);
+}
+
+/**
+ * Compile hypotheses and auto-fill missing priors
+ */
+function compileHypotheses(
+  hypotheses: Hypothesis[],
+  priorDefault: string
+): CompiledHypothesis[] {
+  const compiled: CompiledHypothesis[] = [];
+  let totalStaticPrior = 0;
+  const missingPriorIndices: number[] = [];
+
+  // First pass: compile what we can
+  for (let i = 0; i < hypotheses.length; i++) {
+    const h = hypotheses[i];
+    const name = getHypothesisName(h);
+    const priorValue = typeof h === 'string' ? undefined : h.prior;
+    const compiledPrior = compilePrior(priorValue);
+
+    compiled.push({ name, prior: compiledPrior });
+
+    if (typeof compiledPrior === 'number') {
+      totalStaticPrior += compiledPrior;
+    } else if (compiledPrior === undefined) {
+      missingPriorIndices.push(i);
+    }
+    // Dynamic priors (expressions) can't be summed at compile time
+  }
+
+  // Second pass: fill missing priors based on strategy
+  if (missingPriorIndices.length > 0) {
+    const remaining = Math.max(0, 1 - totalStaticPrior);
+
+    switch (priorDefault) {
+      case 'uniform': {
+        // Split remaining equally among missing
+        const perMissing = remaining / missingPriorIndices.length;
+        for (const i of missingPriorIndices) {
+          compiled[i].prior = perMissing;
+        }
+        break;
+      }
+
+      case 'skeptical': {
+        // Last hypothesis gets most of remaining, rest split evenly
+        const lastMissingIdx = missingPriorIndices[missingPriorIndices.length - 1];
+        const othersCount = missingPriorIndices.length - 1;
+
+        if (othersCount > 0) {
+          const mainShare = remaining * 0.9;
+          const otherShare = (remaining * 0.1) / othersCount;
+
+          for (const i of missingPriorIndices) {
+            compiled[i].prior = i === lastMissingIdx ? mainShare : otherShare;
+          }
+        } else {
+          compiled[lastMissingIdx].prior = remaining;
+        }
+        break;
+      }
+
+      case 'optimistic': {
+        // First hypothesis gets most of remaining, rest split evenly
+        const firstMissingIdx = missingPriorIndices[0];
+        const othersCount = missingPriorIndices.length - 1;
+
+        if (othersCount > 0) {
+          const mainShare = remaining * 0.9;
+          const otherShare = (remaining * 0.1) / othersCount;
+
+          for (const i of missingPriorIndices) {
+            compiled[i].prior = i === firstMissingIdx ? mainShare : otherShare;
+          }
+        } else {
+          compiled[firstMissingIdx].prior = remaining;
+        }
+        break;
+      }
+
+      default:
+        throw new Error(`Unknown priorDefault strategy: ${priorDefault}`);
+    }
+  }
+
+  return compiled;
+}
+
+// ========================================
+// Validation
+// ========================================
+
+/**
+ * Extract all $references from hypothesis priors
+ */
+function extractPriorReferences(hypotheses: Hypothesis[]): string[] {
+  const refs: string[] = [];
+
+  function extractFromValue(value: any): void {
+    if (typeof value === 'string' && value.startsWith('$')) {
+      const rootName = value.slice(1).split('.')[0];
+      refs.push(rootName);
+    } else if (Array.isArray(value)) {
+      for (const item of value) {
+        extractFromValue(item);
+      }
+    }
+  }
+
+  for (const h of hypotheses) {
+    if (typeof h === 'object' && h.prior !== undefined) {
+      extractFromValue(h.prior);
+    }
+  }
+
+  return refs;
+}
+
+/**
+ * Validate that all prior references have declared inputs
+ */
+function validatePriorInputs(
+  hypotheses: Hypothesis[],
+  inputs: any[] | undefined,
+  ruleSetId: string
+): void {
+  const priorRefs = extractPriorReferences(hypotheses);
+  if (priorRefs.length === 0) return;
+
+  const declaredNames = new Set((inputs ?? []).map((i: any) => i.name));
+
+  for (const ref of priorRefs) {
+    if (!declaredNames.has(ref)) {
+      throw new Error(
+        `RuleSet "${ruleSetId}": Hypothesis prior references '$${ref}' but no input declared. ` +
+        `Add: inputs: [{ name: '${ref}', type: '...' }]`
+      );
+    }
+  }
+}
+
+// ========================================
+// Rule Compilation
+// ========================================
+
+export function compileBayesianRule(
+  rule: BayesianRule,
+  index: number,
+  hypothesisNames: Set<string>
+): CompiledBayesianRule {
+  const inputs = rule.inputs.map(compileInputParameter);
+  const when = rule.when ? compileCondition(rule.when) : undefined;
+
+  return {
+    id: rule.id,
+    name: rule.name,
+    salience: rule.salience ?? 0,
+    complexity: calculateComplexity(inputs, when),
+    index,
+    inputs,
+    when,
+    likelihood: compileLikelihoodMap(rule.likelihood, hypothesisNames, rule.id)
+  };
+}
+
+// ========================================
+// RuleSet Compilation
+// ========================================
+
+export function compileBayesianRuleSet(ruleSet: BayesianRuleSet): CompiledBayesianRuleSet {
+  // Validate prior inputs
+  validatePriorInputs(ruleSet.hypotheses, ruleSet.inputs, ruleSet.id);
+
+  // Build config with defaults
+  const config: BayesianConfig = {
+    mode: 'bayesian',
+    threshold: ruleSet.config?.threshold,
+    priorDefault: ruleSet.config?.priorDefault ?? 'uniform'
+  };
+
+  // Get hypothesis names for validation
+  const hypothesisNames = new Set(
+    ruleSet.hypotheses.map(h => typeof h === 'string' ? h : h.name)
+  );
+
+  // Compile hypotheses
+  const hypotheses = compileHypotheses(
+    ruleSet.hypotheses,
+    config.priorDefault!
+  );
+
+  // Compile rules
+  const rules = ruleSet.rules.map((rule, index) =>
+    compileBayesianRule(rule, index, hypothesisNames)
+  );
+
+  return {
+    id: ruleSet.id,
+    name: ruleSet.name,
+    mode: 'bayesian',
+    schema: ruleSet.shape ? normalizeShape(ruleSet.shape) : { type: 'object' },
+    inputs: ruleSet.inputs ?? [],
+    hypotheses,
+    rules,
+    config
+  };
+}

package/src/engines/bayesian/engine.ts

@@ -0,0 +1,122 @@
+/**
+ * Bayesian Engine
+ *
+ * Self-contained engine for Bayesian probabilistic inference.
+ * Implements IRuleEngine with strongly-typed ruleset, options, and result.
+ */
+
+import {
+  IRuleEngine,
+  WorkingMemory,
+  Fact,
+  FactInput,
+  FactChange
+} from '../../core';
+
+import {
+  CompiledBayesianRuleSet,
+  BayesianOptions,
+  BayesianResult
+} from './types';
+
+import { BayesianStrategy } from './strategy';
+
+/**
+ * Bayesian rule engine.
+ *
+ * Updates belief in hypotheses based on evidence from matching rules.
+ * Uses Bayes' theorem to compute posterior probabilities.
+ *
+ * @example
+ * ```typescript
+ * const engine = new BayesianEngine();
+ * engine.add({ type: 'Transaction', data: { amount: 5000, foreignIp: true } });
+ *
+ * const result = engine.execute(compiledRules);
+ * console.log(`P(fraud): ${(result.posteriors.fraud * 100).toFixed(1)}%`);
+ * console.log(`Winner: ${result.winner}`);
+ * ```
+ */
+export class BayesianEngine implements IRuleEngine<CompiledBayesianRuleSet, BayesianOptions, BayesianResult> {
+  private wm: WorkingMemory;
+  private strategy: BayesianStrategy;
+
+  constructor(workingMemory?: WorkingMemory) {
+    this.wm = workingMemory ?? new WorkingMemory();
+    this.strategy = new BayesianStrategy();
+  }
+
+  // ========================================
+  // 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 a Bayesian ruleset.
+   *
+   * Matching rules provide evidence that updates belief in hypotheses.
+   * Posterior probabilities are computed using Bayes' theorem.
+   *
+   * @param ruleSet - Compiled Bayesian ruleset
+   * @param options - Runtime options (callbacks, threshold override)
+   * @returns Result with priors, posteriors, winner, and evidence trail
+   */
+  execute(ruleSet: CompiledBayesianRuleSet, options: BayesianOptions = {}): BayesianResult {
+    return this.strategy.run(ruleSet, this.wm, options);
+  }
+
+  // ========================================
+  // Utility Methods
+  // ========================================
+
+  getWorkingMemory(): WorkingMemory {
+    return this.wm;
+  }
+}

package/src/engines/bayesian/index.ts

@@ -0,0 +1,50 @@
+/**
+ * Bayesian Engine
+ *
+ * Provides probabilistic inference using Bayes' theorem.
+ * Rules provide evidence that updates belief in hypotheses.
+ */
+
+// Types
+export {
+  // Likelihood types
+  SemanticLikelihood,
+  LikelihoodValue,
+  LikelihoodMap,
+  // Hypothesis types
+  PriorValue,
+  Hypothesis,
+  PriorDefault,
+  // Source types
+  BayesianRule,
+  BayesianConfig,
+  BayesianRuleSet,
+  // Compiled types
+  CompiledPrior,
+  CompiledHypothesis,
+  CompiledLikelihoodMap,
+  CompiledBayesianRule,
+  CompiledBayesianRuleSet,
+  // Runtime types
+  EvidenceEntry,
+  BayesianOptions,
+  BayesianResult,
+  // Constants
+  SEMANTIC_LIKELIHOODS
+} from './types';
+
+// Compiler
+export {
+  parseLikelihood,
+  compileBayesianRule,
+  compileBayesianRuleSet
+} from './compiler';
+
+// Strategy
+export {
+  BayesianStrategy,
+  bayesianStrategy
+} from './strategy';
+
+// Engine
+export { BayesianEngine } from './engine';