@higher.archi/boe 1.0.0

package/src/engines/bayesian/strategy.ts

@@ -0,0 +1,273 @@
+/**
+ * Bayesian Engine Strategy
+ *
+ * Evaluates facts against Bayesian rules and updates belief in hypotheses
+ * using Bayes' theorem. Evidence from matching rules updates posteriors.
+ */
+
+import {
+  match,
+  evaluateCondition,
+  BindingContext,
+  CompiledPath,
+  Fact
+} from '../../core';
+import { IWorkingMemory } from '../../core/memory';
+
+import {
+  CompiledBayesianRuleSet,
+  CompiledLikelihoodMap,
+  CompiledPrior,
+  BayesianOptions,
+  BayesianResult,
+  EvidenceEntry
+} from './types';
+
+/**
+ * Check if value is a CompiledPath (fact reference)
+ */
+function isCompiledPath(value: any): value is CompiledPath {
+  return typeof value === 'object' &&
+         value !== null &&
+         'param' in value &&
+         'path' in value &&
+         Array.isArray(value.path);
+}
+
+/**
+ * Resolve a path from context to get a value
+ */
+function resolvePathValue(compiledPath: CompiledPath, context: BindingContext): any {
+  const fact = context[compiledPath.param] as Fact | undefined;
+  if (!fact) {
+    throw new Error(`No fact bound to '${compiledPath.param}' for prior resolution`);
+  }
+
+  let value: any = fact.data;
+  for (const key of compiledPath.path) {
+    if (value === undefined || value === null) {
+      throw new Error(`Cannot resolve path '${compiledPath.param}.${compiledPath.path.join('.')}': intermediate value is ${value}`);
+    }
+    value = value[key];
+  }
+
+  return value;
+}
+
+/**
+ * Resolve a prior value at runtime
+ *
+ * Priors can be:
+ * - Static numbers: 0.02
+ * - CompiledPath: fact reference { param: 'creditReport', path: ['defaultRate'] }
+ * - CompiledCondition: expression { op: 'if', ... }
+ */
+function resolvePrior(
+  prior: CompiledPrior,
+  context: BindingContext
+): number {
+  // Static number
+  if (typeof prior === 'number') {
+    return prior;
+  }
+
+  // CompiledPath (fact reference)
+  if (isCompiledPath(prior)) {
+    const value = resolvePathValue(prior, context);
+    if (typeof value !== 'number') {
+      throw new Error(`Prior path '${prior.param}.${prior.path.join('.')}' must resolve to a number, got: ${typeof value}`);
+    }
+    return value;
+  }
+
+  // CompiledCondition (expression)
+  if (typeof prior === 'object' && prior !== null && 'op' in prior) {
+    const result = evaluateCondition(prior, context);
+    if (typeof result !== 'number') {
+      throw new Error(`Prior expression must evaluate to a number, got: ${typeof result}`);
+    }
+    return result;
+  }
+
+  throw new Error(`Invalid prior value at runtime: ${JSON.stringify(prior)}`);
+}
+
+/**
+ * Build context for resolving hypothesis priors from ruleset inputs
+ */
+function buildPriorContext(
+  inputs: any[],
+  wm: IWorkingMemory
+): BindingContext {
+  const context: BindingContext = {};
+
+  for (const input of inputs) {
+    // Find first matching fact for each input
+    const facts = wm.getByType(input.type);
+    if (facts.length > 0) {
+      context[input.name] = facts[0];
+    }
+  }
+
+  return context;
+}
+
+/**
+ * Normalize posteriors so they sum to 1
+ */
+function normalizePosteriors(posteriors: Record<string, number>): Record<string, number> {
+  const total = Object.values(posteriors).reduce((sum, p) => sum + p, 0);
+
+  if (total === 0) {
+    // Avoid division by zero - return uniform
+    const n = Object.keys(posteriors).length;
+    const uniform: Record<string, number> = {};
+    for (const key of Object.keys(posteriors)) {
+      uniform[key] = 1 / n;
+    }
+    return uniform;
+  }
+
+  const normalized: Record<string, number> = {};
+  for (const [key, value] of Object.entries(posteriors)) {
+    normalized[key] = value / total;
+  }
+  return normalized;
+}
+
+/**
+ * Apply Bayes' theorem to update posteriors based on evidence
+ *
+ * For each hypothesis H:
+ *   P(H|E) ∝ P(E|H) * P(H)
+ *
+ * Where:
+ *   P(E|H) = likelihood of evidence given hypothesis
+ *   P(H) = prior probability of hypothesis
+ *
+ * After multiplying, we normalize so all posteriors sum to 1.
+ */
+function applyEvidence(
+  posteriors: Record<string, number>,
+  likelihoods: CompiledLikelihoodMap
+): Record<string, number> {
+  const updated: Record<string, number> = {};
+
+  for (const [hypothesis, prior] of Object.entries(posteriors)) {
+    // Get likelihood for this hypothesis (default to 1 = neutral)
+    const likelihood = likelihoods[hypothesis] ?? 1.0;
+
+    // Multiply prior by likelihood
+    updated[hypothesis] = prior * likelihood;
+  }
+
+  // Normalize so posteriors sum to 1
+  return normalizePosteriors(updated);
+}
+
+export class BayesianStrategy {
+  run(
+    ruleSet: CompiledBayesianRuleSet,
+    wm: IWorkingMemory,
+    options: BayesianOptions = {}
+  ): BayesianResult {
+    const startTime = performance.now();
+    const { onFire, threshold: optionThreshold } = options;
+    const config = ruleSet.config;
+    const threshold = optionThreshold ?? config.threshold;
+
+    // Build context for resolving dynamic priors
+    const priorContext = buildPriorContext(ruleSet.inputs, wm);
+
+    // Initialize priors
+    const priors: Record<string, number> = {};
+    for (const h of ruleSet.hypotheses) {
+      priors[h.name] = resolvePrior(h.prior, priorContext);
+    }
+
+    // Normalize priors to sum to 1 (in case user provided unnormalized values)
+    let posteriors = normalizePosteriors({ ...priors });
+
+    const fired: string[] = [];
+    const evidence: EvidenceEntry[] = [];
+    let thresholdExceeded: string | undefined;
+
+    // Track which hypotheses were below threshold initially
+    // (so we can detect when they cross it)
+    const belowThreshold = new Set<string>();
+    if (threshold !== undefined) {
+      for (const [hypothesis, posterior] of Object.entries(posteriors)) {
+        if (posterior < threshold) {
+          belowThreshold.add(hypothesis);
+        }
+      }
+    }
+
+    // Evaluate each rule
+    for (const rule of ruleSet.rules) {
+      const activations = match(rule, wm);
+
+      for (const activation of activations) {
+        // Rule matched - this is evidence
+        if (!fired.includes(rule.id)) {
+          fired.push(rule.id);
+        }
+
+        // Record evidence
+        evidence.push({
+          ruleId: rule.id,
+          ruleName: rule.name,
+          likelihoods: rule.likelihood
+        });
+
+        // Callback
+        if (onFire) {
+          onFire(rule.id, activation.facts, rule.likelihood);
+        }
+
+        // Update posteriors with this evidence
+        posteriors = applyEvidence(posteriors, rule.likelihood);
+
+        // Check if any hypothesis crossed the threshold (from below to above)
+        if (threshold !== undefined && thresholdExceeded === undefined) {
+          for (const [hypothesis, posterior] of Object.entries(posteriors)) {
+            if (belowThreshold.has(hypothesis) && posterior >= threshold) {
+              thresholdExceeded = hypothesis;
+              break;
+            }
+          }
+        }
+      }
+    }
+
+    // Find winner (highest posterior)
+    let winner = '';
+    let confidence = 0;
+    for (const [hypothesis, posterior] of Object.entries(posteriors)) {
+      if (posterior > confidence) {
+        winner = hypothesis;
+        confidence = posterior;
+      }
+    }
+
+    // Store normalized priors for result
+    const normalizedPriors = normalizePosteriors(priors);
+
+    const executionTimeMs = Math.round((performance.now() - startTime) * 100) / 100;
+
+    return {
+      priors: normalizedPriors,
+      posteriors,
+      winner,
+      confidence,
+      fired,
+      evidence,
+      thresholdExceeded,
+      iterations: 1,
+      executionTimeMs
+    };
+  }
+}
+
+// Export singleton instance for convenience
+export const bayesianStrategy = new BayesianStrategy();

package/src/engines/bayesian/types.ts

@@ -0,0 +1,219 @@
+/**
+ * Bayesian Engine Types
+ *
+ * Goal-driven probabilistic inference using Bayes' theorem.
+ * Updates belief in hypotheses based on evidence from rules.
+ */
+
+import {
+  BaseRule,
+  BaseRuleSet,
+  InputParameter,
+  CompiledBaseRule,
+  CompiledBaseRuleSet,
+  CompiledCondition,
+  CompiledPath,
+  Expression,
+  BindingContext
+} from '../../core';
+
+// ========================================
+// Likelihood Value Types
+// ========================================
+
+/**
+ * Semantic likelihood labels - human-readable strength indicators
+ */
+export type SemanticLikelihood =
+  | 'most-likely'            // 5x more likely
+  | 'more-likely'            // 3x more likely
+  | 'slightly-more-likely'   // 1.5x more likely
+  | 'neutral'                // 1x (no effect)
+  | 'slightly-less-likely'   // 1.5x less likely
+  | 'less-likely'            // 3x less likely
+  | 'least-likely';          // 5x less likely
+
+/**
+ * Likelihood value - multiple formats supported
+ *
+ * Examples:
+ * - 4.0                    // Raw number (4x more likely)
+ * - '+4x'                  // String shorthand (favors by 4x)
+ * - '-5x'                  // String shorthand (against by 5x)
+ * - { favors: 4 }          // Explicit object (4x more likely)
+ * - { against: 5 }         // Explicit object (5x less likely = 0.2x)
+ * - 'most-likely'          // Semantic label (5x)
+ */
+export type LikelihoodValue =
+  | number                              // Raw: 4.0, 0.2
+  | `+${number}x`                       // Favor: '+4x', '+1.5x'
+  | `-${number}x`                       // Against: '-5x', '-2x'
+  | { favors: number }                  // Object: { favors: 4 }
+  | { against: number }                 // Object: { against: 5 }
+  | SemanticLikelihood;                 // Semantic: 'strongly-favors'
+
+/**
+ * Map of hypothesis name to likelihood value
+ */
+export type LikelihoodMap = Record<string, LikelihoodValue>;
+
+// ========================================
+// Hypothesis Types
+// ========================================
+
+/**
+ * Prior value - can be static, fact reference, or expression
+ *
+ * Examples:
+ * - 0.02                                    // Static: 2% base rate
+ * - '$stats.fraudRate'                      // Fact reference
+ * - ['if', ['equals', '$m.cat', 'high-risk'], 0.08, 0.02]  // Expression
+ */
+export type PriorValue =
+  | number                    // Static: 0.02
+  | `$${string}`              // Fact: '$stats.fraudRate'
+  | Expression;               // Expression: ['if', ...], ['multiply', ...]
+
+/**
+ * Hypothesis definition
+ *
+ * Can be just a name (prior auto-filled) or full definition with prior
+ */
+export type Hypothesis =
+  | string                                    // Name only: 'fraud'
+  | { name: string; prior?: PriorValue };     // With optional prior
+
+/**
+ * Strategy for auto-filling missing priors
+ */
+export type PriorDefault =
+  | 'uniform'       // Equal split: 1/n each
+  | 'skeptical'     // Last hypothesis favored (0.9), rest split remainder
+  | 'optimistic';   // First hypothesis favored (0.9), rest split remainder
+
+// ========================================
+// Source Types (User-Defined)
+// ========================================
+
+/**
+ * Bayesian rule - provides evidence for/against hypotheses
+ */
+export type BayesianRule = BaseRule & {
+  likelihood: LikelihoodMap;  // How this evidence affects each hypothesis
+};
+
+/**
+ * Bayesian ruleset configuration
+ */
+export type BayesianConfig = {
+  mode: 'bayesian';
+  threshold?: number;           // Flag if any posterior exceeds this (e.g., 0.5)
+  priorDefault?: PriorDefault;  // How to fill missing priors (default: 'uniform')
+};
+
+/**
+ * Bayesian ruleset
+ */
+export type BayesianRuleSet = BaseRuleSet & {
+  mode: 'bayesian';
+  inputs?: InputParameter[];    // Facts used by hypothesis priors
+  hypotheses: Hypothesis[];     // The hypotheses to evaluate
+  rules: BayesianRule[];
+  config?: Partial<BayesianConfig>;
+};
+
+// ========================================
+// Compiled Types
+// ========================================
+
+/**
+ * Compiled prior value - can be:
+ * - number: static value
+ * - CompiledPath: fact reference ($foo.bar)
+ * - CompiledCondition: expression (['if', ...])
+ */
+export type CompiledPrior = number | CompiledPath | CompiledCondition;
+
+/**
+ * Compiled hypothesis - prior resolved to expression or static
+ */
+export type CompiledHypothesis = {
+  name: string;
+  prior: CompiledPrior;
+};
+
+/**
+ * Compiled likelihood map - all values normalized to numbers
+ */
+export type CompiledLikelihoodMap = Record<string, number>;
+
+/**
+ * Compiled Bayesian rule
+ */
+export type CompiledBayesianRule = CompiledBaseRule & {
+  likelihood: CompiledLikelihoodMap;
+};
+
+/**
+ * Compiled Bayesian ruleset
+ */
+export type CompiledBayesianRuleSet = CompiledBaseRuleSet & {
+  mode: 'bayesian';
+  inputs: InputParameter[];
+  hypotheses: CompiledHypothesis[];
+  rules: CompiledBayesianRule[];
+  config: BayesianConfig;
+};
+
+// ========================================
+// Runtime Types
+// ========================================
+
+/**
+ * Evidence entry - audit trail of what rules fired
+ */
+export type EvidenceEntry = {
+  ruleId: string;
+  ruleName?: string;
+  likelihoods: CompiledLikelihoodMap;
+};
+
+/**
+ * Runtime options for Bayesian execution
+ */
+export type BayesianOptions = {
+  onFire?: (ruleId: string, context: BindingContext, likelihoods: CompiledLikelihoodMap) => void;
+  threshold?: number;  // Override ruleset threshold
+};
+
+/**
+ * Bayesian execution result
+ */
+export type BayesianResult = {
+  priors: Record<string, number>;       // Initial priors used
+  posteriors: Record<string, number>;   // Final posteriors after evidence
+  winner: string;                        // Hypothesis with highest posterior
+  confidence: number;                    // Winning posterior value
+  fired: string[];                       // Rules that matched and provided evidence
+  evidence: EvidenceEntry[];             // Audit trail
+  thresholdExceeded?: string;            // First hypothesis to exceed threshold (if any)
+  iterations: 1;                         // Bayesian is always one-pass
+  executionTimeMs: number;               // Processing time in milliseconds
+};
+
+// ========================================
+// Semantic Likelihood Mappings
+// ========================================
+
+/**
+ * Default mappings for semantic likelihood labels
+ */
+export const SEMANTIC_LIKELIHOODS: Record<SemanticLikelihood, number> = {
+  'most-likely': 5.0,
+  'more-likely': 3.0,
+  'slightly-more-likely': 1.5,
+  'neutral': 1.0,
+  'slightly-less-likely': 1 / 1.5,  // ~0.667
+  'less-likely': 1 / 3.0,           // ~0.333
+  'least-likely': 1 / 5.0           // 0.2
+};