@higher.archi/boe 1.0.0

package/src/engines/expert/doc/expert-loan-approval.ts

@@ -0,0 +1,458 @@
+/**
+ * Expert System Example: Loan Approval
+ *
+ * Demonstrates an expert system that evaluates loan applications
+ * with full explanation and audit trail capabilities.
+ *
+ * This example shows:
+ * - Tiered classification (credit tiers)
+ * - Derived fact conditions (using `when`)
+ * - Template interpolation with scoped variables
+ * - Goal-directed execution
+ * - Confidence levels
+ * - Denial explanations with suggestions
+ */
+
+import { ExpertRuleSet } from '../types';
+import { ExpertEngine } from '../engine';
+import { compileExpertRuleSet } from '../compiler';
+import { formatInferenceChain } from '../formatter';
+
+export const loanApprovalRuleSet: ExpertRuleSet = {
+  id: 'loan-approval',
+  name: 'Loan Application Expert System',
+  mode: 'expert',
+
+  config: {
+    trackInference: true,
+    generateExplanations: true,
+    goals: ['loanDecision'],
+    confidenceThreshold: 0.8
+  },
+
+  rules: [
+    // ========================================
+    // TIER 1: Credit Classification (priority 0)
+    // These rules run first and classify the applicant
+    // ========================================
+
+    {
+      id: 'credit-tier-excellent',
+      description: 'Classify excellent credit scores (750+)',
+      inputs: [{
+        name: 'app',
+        type: 'Applicant',
+        where: ['greaterThanOrEquals', '$app.creditScore', 750]
+      }],
+      then: {
+        assert: { creditTier: 'excellent' },
+        confidence: 1.0
+      },
+      explain: {
+        onFire: 'Credit score ${app.creditScore} qualifies for excellent tier (750+)',
+        onSkip: 'Credit score ${app.creditScore} below excellent threshold (750+)'
+      }
+    },
+
+    {
+      id: 'credit-tier-good',
+      description: 'Classify good credit scores (700-749)',
+      inputs: [{
+        name: 'app',
+        type: 'Applicant',
+        where: ['and',
+          ['greaterThanOrEquals', '$app.creditScore', 700],
+          ['lessThan', '$app.creditScore', 750]
+        ]
+      }],
+      then: {
+        assert: { creditTier: 'good' },
+        confidence: 1.0
+      },
+      explain: {
+        onFire: 'Credit score ${app.creditScore} qualifies for good tier (700-749)',
+        onSkip: 'Credit score ${app.creditScore} outside good tier range'
+      }
+    },
+
+    {
+      id: 'credit-tier-fair',
+      description: 'Classify fair credit scores (650-699)',
+      inputs: [{
+        name: 'app',
+        type: 'Applicant',
+        where: ['and',
+          ['greaterThanOrEquals', '$app.creditScore', 650],
+          ['lessThan', '$app.creditScore', 700]
+        ]
+      }],
+      then: {
+        assert: { creditTier: 'fair' },
+        confidence: 1.0
+      },
+      explain: {
+        onFire: 'Credit score ${app.creditScore} qualifies for fair tier (650-699)',
+        onSkip: 'Credit score ${app.creditScore} outside fair tier range'
+      }
+    },
+
+    {
+      id: 'credit-tier-poor',
+      description: 'Classify poor credit scores (below 650)',
+      inputs: [{
+        name: 'app',
+        type: 'Applicant',
+        where: ['lessThan', '$app.creditScore', 650]
+      }],
+      then: {
+        assert: { creditTier: 'poor' },
+        confidence: 1.0
+      },
+      explain: {
+        onFire: 'Credit score ${app.creditScore} falls in poor tier (below 650)',
+        onSkip: 'Credit score ${app.creditScore} is 650 or above'
+      }
+    },
+
+    // ========================================
+    // TIER 1: Income Assessment (priority 0)
+    // ========================================
+
+    {
+      id: 'income-adequate',
+      description: 'Check if income is at least 1.5x loan amount',
+      inputs: [{
+        name: 'app',
+        type: 'Applicant',
+        where: ['greaterThanOrEquals',
+          '$app.annualIncome',
+          ['multiply', '$app.requestedAmount', 1.5]
+        ]
+      }],
+      then: {
+        assert: { incomeAdequate: true },
+        confidence: 1.0
+      },
+      explain: {
+        variables: {
+          required: ['multiply', '$app.requestedAmount', 1.5]
+        },
+        onFire: 'Annual income $${app.annualIncome} exceeds required $${required}',
+        onSkip: 'Annual income $${app.annualIncome} below required minimum'
+      }
+    },
+
+    {
+      id: 'income-inadequate',
+      description: 'Flag inadequate income',
+      inputs: [{
+        name: 'app',
+        type: 'Applicant',
+        where: ['lessThan',
+          '$app.annualIncome',
+          ['multiply', '$app.requestedAmount', 1.5]
+        ]
+      }],
+      then: {
+        assert: { incomeAdequate: false },
+        confidence: 1.0
+      },
+      explain: {
+        variables: {
+          required: ['multiply', '$app.requestedAmount', 1.5]
+        },
+        onFire: 'Income $${app.annualIncome} is below required $${required}',
+        onSkip: 'Income check passed'
+      }
+    },
+
+    // ========================================
+    // TIER 1: Debt Assessment (priority 0)
+    // ========================================
+
+    {
+      id: 'debt-ratio-acceptable',
+      description: 'Check if debt-to-income ratio is below 36%',
+      inputs: [{
+        name: 'app',
+        type: 'Applicant',
+        where: ['lessThan', '$app.debtToIncomeRatio', 0.36]
+      }],
+      then: {
+        assert: { debtAcceptable: true },
+        confidence: 1.0
+      },
+      explain: {
+        onFire: 'Debt-to-income ratio ${app.debtToIncomeRatio} is below 36% threshold',
+        onSkip: 'Debt-to-income ratio ${app.debtToIncomeRatio} exceeds threshold'
+      }
+    },
+
+    {
+      id: 'debt-ratio-high',
+      description: 'Flag high debt-to-income ratio',
+      inputs: [{
+        name: 'app',
+        type: 'Applicant',
+        where: ['greaterThanOrEquals', '$app.debtToIncomeRatio', 0.36]
+      }],
+      then: {
+        assert: { debtAcceptable: false },
+        confidence: 1.0
+      },
+      explain: {
+        onFire: 'Debt-to-income ratio ${app.debtToIncomeRatio} exceeds 36% limit',
+        onSkip: 'Debt ratio is acceptable'
+      }
+    },
+
+    // ========================================
+    // TIER 2: Final Decision Rules (priority 10)
+    // These use derived facts from tier 1
+    // ========================================
+
+    {
+      id: 'approve-excellent',
+      description: 'Approve applicants with excellent credit',
+      priority: 10,
+      inputs: [{ name: 'app', type: 'Applicant' }],
+      when: ['and',
+        ['equals', '$creditTier', 'excellent'],
+        ['equals', '$incomeAdequate', true],
+        ['equals', '$debtAcceptable', true]
+      ],
+      then: {
+        assert: {
+          loanDecision: 'approved',
+          reasonCode: 'A-100',
+          baseRate: 5.5
+        },
+        confidence: 0.98
+      },
+      explain: {
+        onFire: 'Approved with excellent credit tier. Base rate: 5.5%',
+        factors: [
+          'Credit tier: ${creditTier}',
+          'Income adequate: ${incomeAdequate}',
+          'Debt acceptable: ${debtAcceptable}'
+        ]
+      }
+    },
+
+    {
+      id: 'approve-good',
+      description: 'Approve applicants with good credit',
+      priority: 10,
+      inputs: [{ name: 'app', type: 'Applicant' }],
+      when: ['and',
+        ['equals', '$creditTier', 'good'],
+        ['equals', '$incomeAdequate', true],
+        ['equals', '$debtAcceptable', true]
+      ],
+      then: {
+        assert: {
+          loanDecision: 'approved',
+          reasonCode: 'A-101',
+          baseRate: 6.75
+        },
+        confidence: 0.95
+      },
+      explain: {
+        onFire: 'Approved with good credit tier. Base rate: 6.75%',
+        factors: [
+          'Credit tier: ${creditTier}',
+          'Income adequate: ${incomeAdequate}',
+          'Debt acceptable: ${debtAcceptable}'
+        ]
+      }
+    },
+
+    {
+      id: 'approve-fair',
+      description: 'Approve applicants with fair credit (higher rate)',
+      priority: 10,
+      inputs: [{ name: 'app', type: 'Applicant' }],
+      when: ['and',
+        ['equals', '$creditTier', 'fair'],
+        ['equals', '$incomeAdequate', true],
+        ['equals', '$debtAcceptable', true]
+      ],
+      then: {
+        assert: {
+          loanDecision: 'approved',
+          reasonCode: 'A-102',
+          baseRate: 8.5
+        },
+        confidence: 0.90
+      },
+      explain: {
+        onFire: 'Approved with fair credit tier. Base rate: 8.5%',
+        suggestion: 'Improve credit score to 700+ for better rates'
+      }
+    },
+
+    // ========================================
+    // TIER 2: Denial Rules (priority 10)
+    // ========================================
+
+    {
+      id: 'deny-poor-credit',
+      description: 'Deny applicants with poor credit',
+      priority: 10,
+      inputs: [{ name: 'app', type: 'Applicant' }],
+      when: ['equals', '$creditTier', 'poor'],
+      then: {
+        assert: {
+          loanDecision: 'denied',
+          reasonCode: 'D-100',
+          primaryFactor: 'Credit score below minimum'
+        },
+        confidence: 1.0
+      },
+      explain: {
+        onFire: 'Denied: Credit score ${app.creditScore} is below minimum threshold (650)',
+        suggestion: 'Work on improving credit score before reapplying'
+      }
+    },
+
+    {
+      id: 'deny-low-income',
+      description: 'Deny applicants with insufficient income',
+      priority: 10,
+      inputs: [{ name: 'app', type: 'Applicant' }],
+      when: ['and',
+        ['notEquals', '$creditTier', 'poor'],
+        ['equals', '$incomeAdequate', false]
+      ],
+      then: {
+        assert: {
+          loanDecision: 'denied',
+          reasonCode: 'D-101',
+          primaryFactor: 'Insufficient income'
+        },
+        confidence: 1.0
+      },
+      explain: {
+        variables: {
+          required: ['multiply', '$app.requestedAmount', 1.5]
+        },
+        onFire: 'Denied: Income $${app.annualIncome} below required $${required}',
+        suggestion: 'Consider applying for a smaller loan amount'
+      }
+    },
+
+    {
+      id: 'deny-high-debt',
+      description: 'Deny applicants with high debt ratio',
+      priority: 10,
+      inputs: [{ name: 'app', type: 'Applicant' }],
+      when: ['and',
+        ['notEquals', '$creditTier', 'poor'],
+        ['equals', '$incomeAdequate', true],
+        ['equals', '$debtAcceptable', false]
+      ],
+      then: {
+        assert: {
+          loanDecision: 'denied',
+          reasonCode: 'D-102',
+          primaryFactor: 'High debt-to-income ratio'
+        },
+        confidence: 1.0
+      },
+      explain: {
+        onFire: 'Denied: Debt-to-income ratio ${app.debtToIncomeRatio} exceeds 36% limit',
+        suggestion: 'Pay down existing debt before reapplying'
+      }
+    },
+
+    // ========================================
+    // TIER 3: Rate Adjustments (priority 20)
+    // Applied after approval decision
+    // ========================================
+
+    {
+      id: 'loyalty-discount',
+      description: 'Apply loyalty discount for existing customers',
+      priority: 20,
+      inputs: [{
+        name: 'app',
+        type: 'Applicant',
+        where: ['and',
+          ['equals', '$app.existingCustomer', true],
+          ['greaterThanOrEquals', '$app.accountAge', 3]
+        ]
+      }],
+      when: ['equals', '$loanDecision', 'approved'],
+      then: {
+        assert: {
+          loyaltyDiscount: 0.25,
+          finalRate: ['subtract', '$baseRate', 0.25]
+        },
+        confidence: 1.0
+      },
+      explain: {
+        variables: {
+          discountedRate: ['subtract', '$baseRate', 0.25]
+        },
+        onFire: 'Loyalty discount applied: ${discountedRate}% (0.25% off base rate)',
+        onSkip: 'Not eligible for loyalty discount'
+      }
+    },
+
+    {
+      id: 'standard-rate',
+      description: 'Apply standard rate (no loyalty discount)',
+      priority: 20,
+      inputs: [{ name: 'app', type: 'Applicant' }],
+      when: ['and',
+        ['equals', '$loanDecision', 'approved'],
+        ['or',
+          ['equals', '$app.existingCustomer', false],
+          ['lessThan', '$app.accountAge', 3]
+        ]
+      ],
+      then: {
+        assert: {
+          loyaltyDiscount: 0,
+          finalRate: '$baseRate'
+        },
+        confidence: 1.0
+      },
+      explain: {
+        onFire: 'Standard rate applied: ${baseRate}%',
+        onSkip: 'Loyalty discount applied instead'
+      }
+    }
+  ]
+};
+
+// ========================================
+// Demo: Run the Expert System
+// ========================================
+
+if (require.main === module) {
+  const compiled = compileExpertRuleSet(loanApprovalRuleSet);
+  const engine = new ExpertEngine();
+
+  // Test case: Excellent credit, existing customer
+  engine.add({
+    type: 'Applicant',
+    data: {
+      creditScore: 780,
+      annualIncome: 95000,
+      requestedAmount: 50000,
+      debtToIncomeRatio: 0.28,
+      existingCustomer: true,
+      accountAge: 5
+    }
+  });
+
+  const result = engine.execute(compiled);
+
+  // Using toString() for full formatted output
+  console.log(result.toString());
+
+  // Or just the inference chain
+  console.log('\n--- Using formatInferenceChain() ---\n');
+  console.log(formatInferenceChain(result));
+}

package/src/engines/expert/engine.ts

@@ -0,0 +1,228 @@
+/**
+ * Expert System Engine
+ *
+ * A rule engine that provides explainable AI - decisions with full audit
+ * trails showing WHY each conclusion was reached.
+ *
+ * Unlike Forward Chaining which focuses on executing actions, the Expert
+ * System captures the reasoning process itself as a first-class output.
+ *
+ * Key Capabilities:
+ * - Inference chains showing step-by-step reasoning
+ * - Template-based explanations with variable interpolation
+ * - Confidence levels for conclusions
+ * - Goal-directed execution
+ * - Query interface for checking conclusions
+ *
+ * @example
+ * ```typescript
+ * const engine = new ExpertEngine();
+ *
+ * engine.add({
+ *   type: 'Applicant',
+ *   data: { creditScore: 720, income: 85000 }
+ * });
+ *
+ * const result = engine.execute(compiledRules, {
+ *   onFire: (ruleId, asserted) => {
+ *     console.log(`Rule ${ruleId} concluded:`, asserted);
+ *   }
+ * });
+ *
+ * // Check specific conclusions
+ * const decision = result.query('loanDecision');
+ * console.log(`Decision: ${decision.value}, Confidence: ${decision.confidence}`);
+ *
+ * // Get full explanation
+ * console.log(result.explanation);
+ * ```
+ */
+
+import {
+  IRuleEngine,
+  WorkingMemory,
+  Fact,
+  FactInput,
+  FactChange
+} from '../../core';
+
+import {
+  CompiledExpertRuleSet,
+  ExpertOptions,
+  ExpertResult
+} from './types';
+
+import { ExpertStrategy } from './strategy';
+
+/**
+ * Expert System Engine.
+ *
+ * Executes rules to derive conclusions with full explanation capabilities.
+ * Each rule can assert facts and provide human-readable explanations.
+ *
+ * @example Basic Usage
+ * ```typescript
+ * const engine = new ExpertEngine();
+ * engine.add({ type: 'Patient', data: { symptoms: ['fever', 'cough'] } });
+ *
+ * const result = engine.execute(diagnosticRules);
+ * console.log(result.conclusions);  // { diagnosis: 'flu', severity: 'moderate' }
+ * console.log(result.explanation);  // Human-readable reasoning
+ * ```
+ *
+ * @example Shared WorkingMemory
+ * ```typescript
+ * const wm = new WorkingMemory();
+ * const engine = new ExpertEngine(wm);
+ * ```
+ */
+export class ExpertEngine implements IRuleEngine<CompiledExpertRuleSet, ExpertOptions, ExpertResult> {
+  private wm: WorkingMemory;
+  private strategy: ExpertStrategy;
+
+  /**
+   * Create a new ExpertEngine.
+   *
+   * @param workingMemory - Optional shared WorkingMemory. If not provided, creates its own.
+   */
+  constructor(workingMemory?: WorkingMemory) {
+    this.wm = workingMemory ?? new WorkingMemory();
+    this.strategy = new ExpertStrategy();
+  }
+
+  // ========================================
+  // IWorkingMemory Implementation
+  // ========================================
+
+  /**
+   * Add a fact to working memory.
+   */
+  add(input: FactInput): Fact {
+    return this.wm.add(input);
+  }
+
+  /**
+   * Remove a fact from working memory.
+   */
+  remove(factId: string): Fact | undefined {
+    return this.wm.remove(factId);
+  }
+
+  /**
+   * Update a fact in working memory.
+   */
+  update(input: FactInput): Fact {
+    return this.wm.update(input);
+  }
+
+  /**
+   * Get a fact by ID.
+   */
+  get(factId: string): Fact | undefined {
+    return this.wm.get(factId);
+  }
+
+  /**
+   * Get all facts of a specific type.
+   */
+  getByType(type: string): Fact[] {
+    return this.wm.getByType(type);
+  }
+
+  /**
+   * Get all facts in working memory.
+   */
+  getAll(): Fact[] {
+    return this.wm.getAll();
+  }
+
+  /**
+   * Check if a fact exists.
+   */
+  has(factId: string): boolean {
+    return this.wm.has(factId);
+  }
+
+  /**
+   * Get the number of facts in working memory.
+   */
+  size(): number {
+    return this.wm.size();
+  }
+
+  /**
+   * Clear all facts from working memory.
+   */
+  clear(): void {
+    this.wm.clear();
+  }
+
+  /**
+   * Get pending changes since last check.
+   */
+  getChanges(): FactChange[] {
+    return this.wm.getChanges();
+  }
+
+  /**
+   * Clear pending changes.
+   */
+  clearChanges(): void {
+    this.wm.clearChanges();
+  }
+
+  // ========================================
+  // IRuleEngine Implementation
+  // ========================================
+
+  /**
+   * Execute an expert system ruleset.
+   *
+   * Rules are evaluated against working memory, with higher-priority rules
+   * evaluated later (so they can use derived facts from lower-priority rules).
+   *
+   * Execution continues until:
+   * - All goals are satisfied (if goals specified in config)
+   * - No more rules can fire
+   * - Maximum evaluations reached
+   *
+   * @param ruleSet - Compiled expert ruleset
+   * @param options - Runtime options (callbacks, verbosity, limits)
+   * @returns Execution result with conclusions, inference chain, and explanations
+   *
+   * @example
+   * ```typescript
+   * const result = engine.execute(ruleSet, {
+   *   onFire: (ruleId, asserted) => console.log(`${ruleId}:`, asserted),
+   *   verbose: true,
+   *   includeSkipped: false
+   * });
+   *
+   * // Access results
+   * console.log(result.conclusions);     // All derived facts
+   * console.log(result.inferenceChain);  // Step-by-step reasoning
+   * console.log(result.explanation);     // Human-readable summary
+   *
+   * // Query specific conclusions
+   * const q = result.query('approved');
+   * if (q.exists) {
+   *   console.log(`Approved: ${q.value}, confidence: ${q.confidence}`);
+   * }
+   * ```
+   */
+  execute(ruleSet: CompiledExpertRuleSet, options: ExpertOptions = {}): ExpertResult {
+    return this.strategy.run(ruleSet, this.wm, options);
+  }
+
+  // ========================================
+  // Utility Methods
+  // ========================================
+
+  /**
+   * Get the underlying WorkingMemory instance.
+   * Useful for sharing memory between multiple engines.
+   */
+  getWorkingMemory(): WorkingMemory {
+    return this.wm;
+  }
+}