@higher.archi/boe 1.0.0

package/src/engines/expert/README.md

@@ -0,0 +1,343 @@
+# Expert System Engine
+
+The Expert System engine provides **explainable AI** - decisions with full audit trails showing *why* each conclusion was reached.
+
+## What is an Expert System?
+
+Think of a doctor diagnosing a patient. They don't just say "you have the flu" - they explain their reasoning: "You have a fever (102°F), body aches, and it's flu season. These symptoms, combined with your recent exposure to someone with confirmed flu, lead me to conclude you likely have influenza."
+
+An Expert System captures this kind of reasoning. It's not just about reaching a conclusion - it's about showing the path to get there.
+
+## When to Use the Expert System
+
+Use this engine when you need:
+
+- **Auditable decisions** - Loan approvals, insurance claims, medical recommendations
+- **Regulatory compliance** - GDPR "right to explanation", fair lending requirements
+- **Debugging complex logic** - Understand why a decision was made
+- **User trust** - Show customers why they were approved/denied
+- **Knowledge capture** - Document decision-making logic with explanations
+
+## How It Differs from Forward Chaining
+
+| Aspect | Forward Chaining | Expert System |
+|--------|------------------|---------------|
+| **Question** | "What should I DO?" | "What can I CONCLUDE and WHY?" |
+| **Output** | Actions executed | Conclusions with explanations |
+| **Reasoning** | `fired: ['rule-1']` | Full inference chain |
+| **Explanations** | Not supported | Built-in per rule |
+| **Confidence** | Binary (yes/no) | 0.0 - 1.0 |
+
+**Important**: Forward Chaining transforms data and triggers actions. Expert System derives conclusions and explains them. Choose based on your primary need.
+
+## Core Concepts
+
+### Goals
+
+Goals are the conclusions you want the system to reach. Once all goals are satisfied, execution stops.
+
+```typescript
+config: {
+  goals: ['loanDecision', 'interestRate']
+}
+```
+
+### Assertions
+
+Rules assert facts (conclusions) instead of executing actions:
+
+```typescript
+then: {
+  assert: { creditTier: 'good', maxLoanAmount: 75000 },
+  confidence: 1.0
+}
+```
+
+### Inference Chain
+
+The inference chain shows every step of reasoning:
+
+```
+[Step 1] Rule: credit-tier-good
+  ├─ Facts: app.creditScore = 720
+  ├─ Conclusion: creditTier = "good"
+  └─ Explanation: Credit score 720 qualifies for good tier (700-749)
+
+[Step 2] Rule: income-adequate
+  ├─ Facts: app.income = 85000, app.loanAmount = 45000
+  ├─ Conclusion: incomeAdequate = true
+  └─ Explanation: Income $85000 exceeds 1.5x loan amount
+```
+
+### Explanations
+
+Every rule has an `explain` block with templates:
+
+```typescript
+explain: {
+  onFire: 'Credit score ${app.creditScore} qualifies for ${creditTier} tier',
+  onSkip: 'Credit score ${app.creditScore} does not meet threshold'
+}
+```
+
+## Rule Structure
+
+```typescript
+{
+  id: 'credit-tier-good',
+  description: 'Classify good credit scores (700-749)',  // Required
+
+  // Input pattern matching (same as Forward Chaining)
+  inputs: [{
+    name: 'app',
+    type: 'Applicant',
+    where: ['and',
+      ['greaterThanOrEquals', '$app.creditScore', 700],
+      ['lessThan', '$app.creditScore', 750]
+    ]
+  }],
+
+  // Optional: condition on derived facts
+  when: ['equals', '$previouslyApproved', true],
+
+  // Priority: higher runs later (can use derived facts)
+  priority: 10,
+
+  // Conclusion
+  then: {
+    assert: { creditTier: 'good' },
+    confidence: 1.0
+  },
+
+  // Explanation templates
+  explain: {
+    variables: {
+      scoreRange: ['concat', '$app.creditScore', ' (700-749)']
+    },
+    onFire: 'Credit score ${scoreRange} qualifies for good tier',
+    onSkip: 'Credit score ${app.creditScore} outside good tier range',
+    suggestion: 'Improve credit score to 700+ for better rates'
+  }
+}
+```
+
+## Template Interpolation
+
+Templates use `${...}` syntax:
+
+| Syntax | Description | Example |
+|--------|-------------|---------|
+| `${app.creditScore}` | Input binding property | `720` |
+| `${creditTier}` | Derived/asserted fact | `good` |
+| `${finalRate}` | Scoped variable | `5.25` |
+
+Regular `$` signs are preserved as-is (no escaping needed).
+
+**Compile-time validation**: Invalid references are caught when compiling the ruleset.
+
+### Scoped Variables
+
+Use `explain.variables` for computed values:
+
+```typescript
+explain: {
+  variables: {
+    finalRate: ['if', '$loyaltyBonus', 5.25, 5.5],
+    required: ['multiply', '$app.loanAmount', 1.5]
+  },
+  onFire: 'Rate: ${finalRate}%, Required income: $${required}'
+}
+// Output: "Rate: 5.25%, Required income: $67500"
+```
+
+## Confidence Levels
+
+Each rule specifies confidence (0.0 - 1.0):
+
+```typescript
+then: {
+  assert: { diagnosis: 'flu' },
+  confidence: 0.85  // 85% confident
+}
+```
+
+Query confidence at runtime:
+
+```typescript
+const result = engine.execute(rules);
+const q = result.query('diagnosis');
+
+console.log(q.value);       // 'flu'
+console.log(q.confidence);  // 0.85
+console.log(q.concludedBy); // 'diagnose-flu'
+```
+
+## Complete Example
+
+```typescript
+import {
+  ExpertEngine,
+  compileExpertRuleSet,
+  ExpertRuleSet
+} from '@higher.archi/boe';
+
+const loanRules: ExpertRuleSet = {
+  id: 'loan-approval',
+  name: 'Loan Application Expert System',
+  mode: 'expert',
+
+  config: {
+    goals: ['loanDecision'],
+    confidenceThreshold: 0.8
+  },
+
+  rules: [
+    {
+      id: 'credit-tier-good',
+      description: 'Classify good credit scores',
+      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',
+        onSkip: 'Credit score outside good tier range'
+      }
+    },
+    {
+      id: 'approve-good-credit',
+      description: 'Approve applicants with good credit',
+      priority: 10,  // Runs after tier classification
+      inputs: [{ name: 'app', type: 'Applicant' }],
+      when: ['equals', '$creditTier', 'good'],
+      then: {
+        assert: { loanDecision: 'approved' },
+        confidence: 0.95
+      },
+      explain: {
+        onFire: 'Application approved based on ${creditTier} credit tier',
+        suggestion: 'Maintain good payment history to keep rates low'
+      }
+    }
+  ]
+};
+
+// Compile and execute
+const compiled = compileExpertRuleSet(loanRules);
+const engine = new ExpertEngine();
+
+engine.add({
+  type: 'Applicant',
+  data: { creditScore: 720, income: 85000 }
+});
+
+const result = engine.execute(compiled);
+
+// Access results
+console.log(result.conclusions);
+// { creditTier: 'good', loanDecision: 'approved' }
+
+console.log(result.explanation);
+// Reached 2 conclusion(s) via 2 rule(s):
+//   creditTier = "good"
+//     ← Credit score 720 qualifies for good tier
+//   loanDecision = "approved" [GOAL]
+//     ← Application approved based on good credit tier
+
+// Query specific conclusion
+const decision = result.query('loanDecision');
+console.log(decision.value);       // 'approved'
+console.log(decision.confidence);  // 0.95
+console.log(decision.concludedBy); // 'approve-good-credit'
+```
+
+## Result Structure
+
+```typescript
+type ExpertResult = {
+  conclusions: Record<string, unknown>;  // All derived facts
+  inferenceChain: InferenceStep[];       // Step-by-step trace
+  explanation: string;                    // Human-readable summary
+  rulesFired: number;
+  rulesEvaluated: number;
+  processingTimeMs: number;
+  timestamp: string;
+  query: (factName: string) => ExpertQueryResult;
+};
+```
+
+## Options
+
+```typescript
+engine.execute(rules, {
+  // Callbacks
+  onFire: (ruleId, asserted, bindings) => { ... },
+  onEvaluate: (ruleId, fired) => { ... },
+
+  // Include skipped rules in inference chain
+  includeSkipped: false,
+
+  // Generate verbose explanations
+  verbose: true,
+
+  // Circuit breaker
+  maxEvaluations: 1000
+});
+```
+
+## Best Practices
+
+1. **Write descriptions for every rule** - They appear in the inference chain
+2. **Use meaningful rule IDs** - They're shown in explanations and query results
+3. **Set priorities for derived-fact rules** - Ensures correct evaluation order
+4. **Test template interpolation** - Invalid refs fail at compile time
+5. **Keep confidence meaningful** - 1.0 = certain, < 1.0 = uncertain
+6. **Define goals** - Execution stops when goals are reached (efficient)
+
+## Common Patterns
+
+### Tiered Classification
+
+```typescript
+// Low priority: classify into tiers
+{ id: 'tier-excellent', priority: 0, ... }
+{ id: 'tier-good', priority: 0, ... }
+{ id: 'tier-fair', priority: 0, ... }
+
+// High priority: decide based on tier
+{ id: 'approve', priority: 10, when: ['in', '$tier', ['excellent', 'good']], ... }
+{ id: 'deny', priority: 10, when: ['equals', '$tier', 'fair'], ... }
+```
+
+### Denial with Suggestions
+
+```typescript
+{
+  id: 'deny-high-debt',
+  then: { assert: { decision: 'denied', reason: 'D-103' }, confidence: 1.0 },
+  explain: {
+    onFire: 'Debt ratio ${app.debtRatio} exceeds 36% limit',
+    suggestion: 'Pay down existing debt before reapplying'
+  }
+}
+```
+
+### Computed Explanations
+
+```typescript
+explain: {
+  variables: {
+    required: ['multiply', '$app.loanAmount', 1.5],
+    shortfall: ['subtract', '$required', '$app.income']
+  },
+  onFire: 'Income $${app.income} is $${shortfall} below required $${required}'
+}
+```

package/src/engines/expert/compiler.ts

@@ -0,0 +1,277 @@
+/**
+ * Expert System Compiler
+ *
+ * Compiles ExpertRuleSet into optimized form for execution.
+ * Validates templates at compile time to catch errors early.
+ */
+
+import {
+  compileCondition,
+  compileOperand,
+  normalizeShape
+} from '../../core';
+
+import {
+  ExpertRule,
+  ExpertRuleSet,
+  ExpertConfig,
+  CompiledExpertRule,
+  CompiledExpertRuleSet,
+  CompiledExplainBlock,
+  Confidence,
+  SEMANTIC_CONFIDENCES,
+  SemanticConfidence
+} from './types';
+
+import {
+  compileTemplate,
+  buildAvailableRefs
+} from './interpolation';
+
+// ========================================
+// Helper Functions
+// ========================================
+
+/**
+ * Normalize confidence to a numeric value (0.0 - 1.0).
+ * Accepts numeric values or semantic labels.
+ */
+function normalizeConfidence(confidence: Confidence): number {
+  if (typeof confidence === 'number') {
+    return Math.max(0, Math.min(1, confidence));
+  }
+  const value = SEMANTIC_CONFIDENCES[confidence as SemanticConfidence];
+  if (value === undefined) {
+    throw new Error(`Invalid semantic confidence: '${confidence}'. Valid values: ${Object.keys(SEMANTIC_CONFIDENCES).join(', ')}`);
+  }
+  return value;
+}
+
+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;
+}
+
+// ========================================
+// Explain Block Compilation
+// ========================================
+
+/**
+ * Collect all fact names that could be asserted by rules.
+ * Used to build available references for template validation.
+ */
+function collectDerivedFacts(rules: ExpertRule[]): string[] {
+  const facts = new Set<string>();
+
+  for (const rule of rules) {
+    for (const factName of Object.keys(rule.then.assert)) {
+      facts.add(factName);
+    }
+  }
+
+  return Array.from(facts);
+}
+
+/**
+ * Compile an explain block with template validation.
+ */
+function compileExplainBlock(
+  explain: ExpertRule['explain'],
+  inputNames: string[],
+  derivedFacts: string[],
+  ruleId: string
+): CompiledExplainBlock {
+  // Get variable names from explain.variables
+  const explainVars = explain.variables ? Object.keys(explain.variables) : [];
+
+  // Build set of available references
+  const availableRefs = buildAvailableRefs(inputNames, derivedFacts, explainVars);
+
+  // Compile variables expressions
+  const compiledVariables = explain.variables
+    ? Object.fromEntries(
+        Object.entries(explain.variables).map(([name, expr]) => [
+          name,
+          compileOperand(expr)
+        ])
+      )
+    : undefined;
+
+  // Compile templates with validation
+  const compiledOnFire = compileTemplate(explain.onFire, availableRefs, ruleId);
+
+  const compiledOnSkip = explain.onSkip
+    ? compileTemplate(explain.onSkip, availableRefs, ruleId)
+    : undefined;
+
+  const compiledFactors = explain.factors
+    ? explain.factors.map(f => compileTemplate(f, availableRefs, ruleId))
+    : undefined;
+
+  const compiledSuggestion = explain.suggestion
+    ? compileTemplate(explain.suggestion, availableRefs, ruleId)
+    : undefined;
+
+  return {
+    variables: compiledVariables,
+    onFire: compiledOnFire,
+    onSkip: compiledOnSkip,
+    factors: compiledFactors,
+    suggestion: compiledSuggestion
+  };
+}
+
+// ========================================
+// Rule Compilation
+// ========================================
+
+/**
+ * Compile a single expert rule.
+ */
+function compileExpertRule(
+  rule: ExpertRule,
+  index: number,
+  derivedFacts: string[]
+): CompiledExpertRule {
+  // Validate required fields
+  if (!rule.description) {
+    throw new Error(`Rule '${rule.id}' is missing required 'description' field`);
+  }
+  if (!rule.explain) {
+    throw new Error(`Rule '${rule.id}' is missing required 'explain' block`);
+  }
+  if (!rule.explain.onFire) {
+    throw new Error(`Rule '${rule.id}' explain block is missing required 'onFire' template`);
+  }
+
+  // Normalize confidence (handles both numeric and semantic values)
+  const confidence = normalizeConfidence(rule.then.confidence);
+
+  // Compile inputs
+  const inputs = rule.inputs.map(compileInputParameter);
+  const inputNames = rule.inputs.map(i => i.name);
+
+  // Compile when condition (for derived facts)
+  const when = rule.when ? compileCondition(rule.when) : undefined;
+
+  // Compile assert expressions
+  const assert = Object.fromEntries(
+    Object.entries(rule.then.assert).map(([name, expr]) => [
+      name,
+      compileOperand(expr)
+    ])
+  );
+
+  // Compile explain block
+  const explain = compileExplainBlock(
+    rule.explain,
+    inputNames,
+    derivedFacts,
+    rule.id
+  );
+
+  return {
+    id: rule.id,
+    name: rule.name,
+    description: rule.description,
+    salience: rule.salience ?? 0,
+    priority: rule.priority ?? 0,
+    complexity: calculateComplexity(inputs, when),
+    index,
+    inputs,
+    when,
+    assert,
+    confidence,
+    explain
+  };
+}
+
+// ========================================
+// RuleSet Compilation
+// ========================================
+
+/**
+ * Compile an expert ruleset.
+ *
+ * @param ruleSet - Source ruleset definition
+ * @returns Compiled ruleset ready for execution
+ * @throws Error if validation fails
+ */
+export function compileExpertRuleSet(ruleSet: ExpertRuleSet): CompiledExpertRuleSet {
+  // Validate mode
+  if (ruleSet.mode !== 'expert') {
+    throw new Error(`Invalid mode '${ruleSet.mode}' for expert ruleset`);
+  }
+
+  // Collect all derived facts for reference validation
+  const derivedFacts = collectDerivedFacts(ruleSet.rules);
+
+  // Compile all rules
+  const compiledRules = ruleSet.rules.map((rule, index) =>
+    compileExpertRule(rule, index, derivedFacts)
+  );
+
+  // Sort by priority (higher priority runs later)
+  compiledRules.sort((a, b) => a.priority - b.priority);
+
+  // Build config with defaults
+  const config: Required<ExpertConfig> = {
+    trackInference: ruleSet.config?.trackInference ?? true,
+    generateExplanations: ruleSet.config?.generateExplanations ?? true,
+    goals: ruleSet.config?.goals ?? [],
+    confidenceThreshold: ruleSet.config?.confidenceThreshold ?? 0.8
+  };
+
+  return {
+    id: ruleSet.id,
+    name: ruleSet.name,
+    mode: 'expert',
+    schema: ruleSet.shape ? normalizeShape(ruleSet.shape) : { type: 'object' },
+    rules: compiledRules,
+    config
+  };
+}