@higher.archi/boe 1.0.0

package/src/engines/expert/strategy.ts

@@ -0,0 +1,413 @@
+/**
+ * Expert System Strategy
+ *
+ * Executes expert rules against working memory, building an inference
+ * chain and generating explanations for each conclusion.
+ */
+
+import {
+  matchInputsOnly,
+  evaluateCondition,
+  resolveOperand,
+  BindingContext,
+  Fact
+} from '../../core';
+import { IWorkingMemory } from '../../core/memory';
+
+import {
+  CompiledExpertRuleSet,
+  CompiledExpertRule,
+  ExpertOptions,
+  ExpertResult,
+  ExpertQueryResult,
+  InferenceStep
+} from './types';
+
+import {
+  interpolate,
+  InterpolationContext
+} from './interpolation';
+
+import { formatResult } from './formatter';
+
+// ========================================
+// Helper Types
+// ========================================
+
+type DerivedFacts = Record<string, unknown>;
+
+type FactConfidence = Record<string, {
+  value: unknown;
+  confidence: number;
+  concludedBy: string;
+}>;
+
+// ========================================
+// Context Augmentation
+// ========================================
+
+/**
+ * Create an augmented binding context that includes derived facts.
+ * Derived facts are wrapped as pseudo-facts so they can be accessed
+ * with the same syntax as input bindings.
+ */
+function augmentBindingsWithFacts(
+  bindings: BindingContext,
+  derivedFacts: DerivedFacts
+): BindingContext {
+  const augmented: BindingContext = { ...bindings };
+
+  // Add derived facts as pseudo-facts
+  // This allows conditions like ['equals', '$creditTier', 'good']
+  // where creditTier is a derived fact, not an input binding
+  for (const [name, value] of Object.entries(derivedFacts)) {
+    if (!(name in augmented)) {
+      augmented[name] = {
+        id: `__derived_${name}`,
+        type: '__derived',
+        data: value
+      } as Fact;
+    }
+  }
+
+  return augmented;
+}
+
+// ========================================
+// Interpolation Helpers
+// ========================================
+
+/**
+ * Build interpolation context from bindings and derived facts.
+ */
+function buildInterpolationContext(
+  bindings: BindingContext,
+  derivedFacts: DerivedFacts,
+  explainVars?: Record<string, unknown>
+): InterpolationContext {
+  // Convert bindings to { name: data } format
+  const bindingsData: Record<string, Record<string, unknown>> = {};
+  for (const [name, fact] of Object.entries(bindings)) {
+    if (fact.type !== '__derived') {
+      bindingsData[name] = fact.data as Record<string, unknown>;
+    }
+  }
+
+  return {
+    bindings: bindingsData,
+    facts: derivedFacts,
+    variables: explainVars
+  };
+}
+
+/**
+ * Evaluate explain variables using the current context.
+ */
+function evaluateExplainVariables(
+  variables: Record<string, any> | undefined,
+  augmentedBindings: BindingContext
+): Record<string, unknown> | undefined {
+  if (!variables) return undefined;
+
+  const result: Record<string, unknown> = {};
+
+  for (const [name, compiled] of Object.entries(variables)) {
+    result[name] = resolveOperand(compiled, augmentedBindings);
+  }
+
+  return result;
+}
+
+// ========================================
+// Strategy Implementation
+// ========================================
+
+export class ExpertStrategy {
+  run(
+    ruleSet: CompiledExpertRuleSet,
+    wm: IWorkingMemory,
+    options: ExpertOptions = {}
+  ): ExpertResult {
+    const startTime = performance.now();
+    const config = ruleSet.config;
+
+    const {
+      onFire,
+      onEvaluate,
+      includeSkipped = false,
+      verbose = true,
+      maxEvaluations = 1000
+    } = options;
+
+    // State
+    const derivedFacts: DerivedFacts = {};
+    const factConfidence: FactConfidence = {};
+    const inferenceChain: InferenceStep[] = [];
+    let rulesFired = 0;
+    let rulesEvaluated = 0;
+
+    // Track which rules have fired to prevent re-firing
+    const firedRules = new Set<string>();
+
+    // Keep iterating until no new rules fire or goals reached
+    let changed = true;
+
+    while (changed && rulesEvaluated < maxEvaluations) {
+      changed = false;
+
+      for (const rule of ruleSet.rules) {
+        // Skip already-fired rules
+        if (firedRules.has(rule.id)) {
+          continue;
+        }
+
+        rulesEvaluated++;
+
+        // Check evaluation limit
+        if (rulesEvaluated >= maxEvaluations) {
+          break;
+        }
+
+        // Match against working memory (inputs only - we evaluate 'when' ourselves with derived facts)
+        const activations = matchInputsOnly(rule, wm);
+
+        for (const activation of activations) {
+          const bindings = activation.facts;
+
+          // Create augmented context with derived facts
+          const augmentedBindings = augmentBindingsWithFacts(bindings, derivedFacts);
+
+          // Evaluate 'when' condition if present (for derived facts)
+          if (rule.when) {
+            const whenResult = evaluateCondition(rule.when, augmentedBindings);
+
+            if (!whenResult) {
+              // Rule didn't match - record if includeSkipped
+              if (includeSkipped) {
+                const step = buildInferenceStep(
+                  rule,
+                  bindings,
+                  derivedFacts,
+                  augmentedBindings,
+                  false,
+                  undefined
+                );
+                inferenceChain.push(step);
+              }
+
+              onEvaluate?.(rule.id, false);
+              continue;
+            }
+          }
+
+          // Rule fires!
+          firedRules.add(rule.id);
+          changed = true;
+          rulesFired++;
+
+          // Capture derived facts state BEFORE this rule's assertions
+          const derivedFactsSnapshot = rule.when ? { ...derivedFacts } : undefined;
+
+          // Evaluate assertions
+          const asserted: Record<string, unknown> = {};
+          for (const [factName, compiledExpr] of Object.entries(rule.assert)) {
+            const value = resolveOperand(compiledExpr, augmentedBindings);
+            asserted[factName] = value;
+            derivedFacts[factName] = value;
+
+            // Track confidence
+            factConfidence[factName] = {
+              value,
+              confidence: rule.confidence,
+              concludedBy: rule.id
+            };
+          }
+
+          // Build inference step (use snapshot for derived facts)
+          const step = buildInferenceStep(
+            rule,
+            bindings,
+            derivedFactsSnapshot ?? derivedFacts,
+            augmentedBindings,
+            true,
+            asserted
+          );
+          inferenceChain.push(step);
+
+          // Callbacks
+          onFire?.(rule.id, asserted, bindings);
+          onEvaluate?.(rule.id, true);
+
+          // Check if all goals are satisfied
+          if (config.goals.length > 0) {
+            const allGoalsMet = config.goals.every(goal => goal in derivedFacts);
+            if (allGoalsMet) {
+              changed = false; // Stop processing
+              break;
+            }
+          }
+
+          // Only process first activation per rule
+          break;
+        }
+
+        // If goals met, stop outer loop too
+        if (config.goals.length > 0) {
+          const allGoalsMet = config.goals.every(goal => goal in derivedFacts);
+          if (allGoalsMet) {
+            changed = false;
+            break;
+          }
+        }
+      }
+    }
+
+    // Build explanation summary
+    const explanation = verbose
+      ? buildExplanationSummary(inferenceChain, derivedFacts, config.goals)
+      : '';
+
+    // Build query function
+    const query = (factName: string): ExpertQueryResult => {
+      const info = factConfidence[factName];
+      if (info) {
+        return {
+          exists: true,
+          value: info.value,
+          confidence: info.confidence,
+          status: 'concluded',
+          concludedBy: info.concludedBy
+        };
+      }
+
+      return {
+        exists: false,
+        value: undefined,
+        confidence: 0,
+        status: factName in derivedFacts ? 'concluded' : 'not-concluded'
+      };
+    };
+
+    const result: ExpertResult = {
+      conclusions: { ...derivedFacts },
+      inferenceChain,
+      explanation,
+      rulesFired,
+      rulesEvaluated,
+      executionTimeMs: Math.round((performance.now() - startTime) * 100) / 100,
+      timestamp: new Date().toISOString(),
+      query,
+      toString: () => formatResult(result, config.goals)
+    };
+
+    return result;
+  }
+}
+
+// ========================================
+// Helper Functions
+// ========================================
+
+/**
+ * Build an inference step from rule execution.
+ */
+function buildInferenceStep(
+  rule: CompiledExpertRule,
+  bindings: BindingContext,
+  derivedFacts: DerivedFacts,
+  augmentedBindings: BindingContext,
+  fired: boolean,
+  asserted: Record<string, unknown> | undefined
+): InferenceStep {
+  // Collect facts used (exclude derived pseudo-facts)
+  const factsUsed: string[] = [];
+  for (const [name, fact] of Object.entries(bindings)) {
+    if (fact.type !== '__derived') {
+      factsUsed.push(`${name}=${JSON.stringify(fact.data)}`);
+    }
+  }
+
+  // Capture derived facts used if rule has a `when` condition
+  // These are the derived facts that existed at the time this rule evaluated
+  let derivedFactsUsed: Record<string, unknown> | undefined;
+  if (rule.when && Object.keys(derivedFacts).length > 0) {
+    derivedFactsUsed = { ...derivedFacts };
+  }
+
+  // Evaluate explain variables
+  const explainVars = evaluateExplainVariables(
+    rule.explain.variables,
+    augmentedBindings
+  );
+
+  // Build interpolation context
+  const interpContext = buildInterpolationContext(bindings, derivedFacts, explainVars);
+
+  // Interpolate the appropriate template
+  const template = fired ? rule.explain.onFire : rule.explain.onSkip;
+  const explanation = template
+    ? interpolate(template, interpContext)
+    : fired ? 'Rule fired' : 'Rule skipped';
+
+  return {
+    ruleId: rule.id,
+    description: rule.description,
+    fired,
+    factsUsed,
+    derivedFactsUsed,
+    asserted,
+    confidence: fired ? rule.confidence : undefined,
+    explanation
+  };
+}
+
+/**
+ * Build a human-readable explanation summary.
+ */
+function buildExplanationSummary(
+  chain: InferenceStep[],
+  conclusions: DerivedFacts,
+  goals: string[]
+): string {
+  const lines: string[] = [];
+
+  // Count fired rules
+  const firedSteps = chain.filter(s => s.fired);
+
+  if (firedSteps.length === 0) {
+    lines.push('No rules fired. Unable to reach any conclusions.');
+    return lines.join('\n');
+  }
+
+  lines.push(`Reached ${Object.keys(conclusions).length} conclusion(s) via ${firedSteps.length} rule(s):`);
+  lines.push('');
+
+  // List key conclusions
+  for (const step of firedSteps) {
+    if (step.asserted) {
+      for (const [fact, value] of Object.entries(step.asserted)) {
+        const isGoal = goals.includes(fact);
+        const marker = isGoal ? ' [GOAL]' : '';
+        lines.push(`  ${fact} = ${JSON.stringify(value)}${marker}`);
+        lines.push(`    <- ${step.explanation}`);
+      }
+    }
+  }
+
+  // Check goal status
+  if (goals.length > 0) {
+    const unmetGoals = goals.filter(g => !(g in conclusions));
+
+    lines.push('');
+    if (unmetGoals.length === 0) {
+      lines.push(`All ${goals.length} goal(s) satisfied.`);
+    } else {
+      lines.push(`Goals not satisfied: ${unmetGoals.join(', ')}`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+// Export singleton instance
+export const expertStrategy = new ExpertStrategy();