@higher.archi/boe 1.0.0

package/dist/engines/expert/doc/expert-loan-approval.js

@@ -0,0 +1,430 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loanApprovalRuleSet = void 0;
+const engine_1 = require("../engine");
+const compiler_1 = require("../compiler");
+const formatter_1 = require("../formatter");
+exports.loanApprovalRuleSet = {
+    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 = (0, compiler_1.compileExpertRuleSet)(exports.loanApprovalRuleSet);
+    const engine = new engine_1.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((0, formatter_1.formatInferenceChain)(result));
+}
+//# sourceMappingURL=expert-loan-approval.js.map

package/dist/engines/expert/doc/expert-loan-approval.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"expert-loan-approval.js","sourceRoot":"","sources":["../../../../src/engines/expert/doc/expert-loan-approval.ts"],"names":[],"mappings":"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"}

package/dist/engines/expert/engine.d.ts

@@ -0,0 +1,159 @@
+/**
+ * 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';
+/**
+ * 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 declare class ExpertEngine implements IRuleEngine<CompiledExpertRuleSet, ExpertOptions, ExpertResult> {
+    private wm;
+    private strategy;
+    /**
+     * Create a new ExpertEngine.
+     *
+     * @param workingMemory - Optional shared WorkingMemory. If not provided, creates its own.
+     */
+    constructor(workingMemory?: WorkingMemory);
+    /**
+     * Add a fact to working memory.
+     */
+    add(input: FactInput): Fact;
+    /**
+     * Remove a fact from working memory.
+     */
+    remove(factId: string): Fact | undefined;
+    /**
+     * Update a fact in working memory.
+     */
+    update(input: FactInput): Fact;
+    /**
+     * Get a fact by ID.
+     */
+    get(factId: string): Fact | undefined;
+    /**
+     * Get all facts of a specific type.
+     */
+    getByType(type: string): Fact[];
+    /**
+     * Get all facts in working memory.
+     */
+    getAll(): Fact[];
+    /**
+     * Check if a fact exists.
+     */
+    has(factId: string): boolean;
+    /**
+     * Get the number of facts in working memory.
+     */
+    size(): number;
+    /**
+     * Clear all facts from working memory.
+     */
+    clear(): void;
+    /**
+     * Get pending changes since last check.
+     */
+    getChanges(): FactChange[];
+    /**
+     * Clear pending changes.
+     */
+    clearChanges(): void;
+    /**
+     * 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;
+    /**
+     * Get the underlying WorkingMemory instance.
+     * Useful for sharing memory between multiple engines.
+     */
+    getWorkingMemory(): WorkingMemory;
+}
+//# sourceMappingURL=engine.d.ts.map

package/dist/engines/expert/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../../src/engines/expert/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,OAAO,EACL,WAAW,EACX,aAAa,EACb,IAAI,EACJ,SAAS,EACT,UAAU,EACX,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,qBAAqB,EACrB,aAAa,EACb,YAAY,EACb,MAAM,SAAS,CAAC;AAIjB;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,YAAa,YAAW,WAAW,CAAC,qBAAqB,EAAE,aAAa,EAAE,YAAY,CAAC;IAClG,OAAO,CAAC,EAAE,CAAgB;IAC1B,OAAO,CAAC,QAAQ,CAAiB;IAEjC;;;;OAIG;gBACS,aAAa,CAAC,EAAE,aAAa;IASzC;;OAEG;IACH,GAAG,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI;IAI3B;;OAEG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS;IAIxC;;OAEG;IACH,MAAM,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI;IAI9B;;OAEG;IACH,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS;IAIrC;;OAEG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE;IAI/B;;OAEG;IACH,MAAM,IAAI,IAAI,EAAE;IAIhB;;OAEG;IACH,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAI5B;;OAEG;IACH,IAAI,IAAI,MAAM;IAId;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;OAEG;IACH,UAAU,IAAI,UAAU,EAAE;IAI1B;;OAEG;IACH,YAAY,IAAI,IAAI;IAQpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkCG;IACH,OAAO,CAAC,OAAO,EAAE,qBAAqB,EAAE,OAAO,GAAE,aAAkB,GAAG,YAAY;IAQlF;;;OAGG;IACH,gBAAgB,IAAI,aAAa;CAGlC"}