@higher.archi/boe 1.0.0

package/src/engines/expert/formatter.ts

@@ -0,0 +1,242 @@
+/**
+ * Expert System Result Formatter
+ *
+ * Utilities for formatting inference chains and results into
+ * human-readable ASCII output.
+ */
+
+import { ExpertResult } from './types';
+
+// ========================================
+// Constants
+// ========================================
+
+const LINE_WIDTH = 79;
+const DOUBLE_LINE = '═'.repeat(LINE_WIDTH);
+
+// ========================================
+// Inference Chain Formatter
+// ========================================
+
+/**
+ * Format options for inference chain output.
+ */
+export type FormatOptions = {
+  /**
+   * Whether to include the header/footer borders.
+   * @default true
+   */
+  includeBorders?: boolean;
+
+  /**
+   * Whether to show factors if available.
+   * @default true
+   */
+  showFactors?: boolean;
+
+  /**
+   * Width of the step number column.
+   * @default 50
+   */
+  stepWidth?: number;
+};
+
+/**
+ * Format the inference chain into a readable ASCII report.
+ *
+ * @param result - The expert system execution result
+ * @param options - Formatting options
+ * @returns Formatted string
+ *
+ * @example
+ * ```typescript
+ * const result = engine.execute(rules);
+ * console.log(formatInferenceChain(result));
+ * ```
+ */
+export function formatInferenceChain(
+  result: ExpertResult,
+  options: FormatOptions = {}
+): string {
+  const {
+    includeBorders = true
+  } = options;
+
+  const lines: string[] = [];
+  const firedSteps = result.inferenceChain.filter(s => s.fired);
+
+  if (firedSteps.length === 0) {
+    return 'No rules fired. Unable to reach any conclusions.';
+  }
+
+  // Header
+  if (includeBorders) {
+    lines.push(DOUBLE_LINE);
+    lines.push(centerText('INFERENCE CHAIN', LINE_WIDTH));
+    lines.push(DOUBLE_LINE);
+    lines.push('');
+  }
+
+  // Steps
+  firedSteps.forEach((step, index) => {
+    const stepNum = `[Step ${index + 1}]`;
+    const confidence = step.confidence !== undefined
+      ? `confidence: ${Math.round(step.confidence * 100)}%`
+      : '';
+
+    // Step header: [Step 1] rule-id                              confidence: 100%
+    const ruleIdPart = `${stepNum} ${step.ruleId}`;
+    const padding = Math.max(0, LINE_WIDTH - ruleIdPart.length - confidence.length);
+    lines.push(`${ruleIdPart}${' '.repeat(padding)}${confidence}`);
+
+    // Parse factsUsed to extract input bindings
+    const inputs = parseFactsUsed(step.factsUsed);
+    const hasDerived = step.derivedFactsUsed && Object.keys(step.derivedFactsUsed).length > 0;
+    const hasAssert = step.asserted && Object.keys(step.asserted).length > 0;
+
+    if (inputs.length > 0) {
+      lines.push(`├─ Input:  ${inputs.join(', ')}`);
+    }
+
+    // Show derived facts used (for rules with `when` conditions)
+    if (hasDerived) {
+      const derived = Object.entries(step.derivedFactsUsed!)
+        .map(([k, v]) => `${k} = ${formatValue(v)}`)
+        .join(', ');
+      lines.push(`├─ Derived: ${derived}`);
+    }
+
+    // Show asserted facts
+    if (hasAssert) {
+      const assertions = Object.entries(step.asserted!)
+        .map(([k, v]) => `${k} = ${formatValue(v)}`)
+        .join(', ');
+      lines.push(`├─ Assert: ${assertions}`);
+    }
+
+    // Reason (the explanation)
+    lines.push(`└─ Reason: ${step.explanation}`);
+
+    // Factors (if available and enabled) - would need to be added to InferenceStep
+    // For now, skip since InferenceStep doesn't include factors
+
+    lines.push('');
+  });
+
+  // Footer
+  if (includeBorders) {
+    lines.push(DOUBLE_LINE);
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Format the complete result including conclusions and statistics.
+ *
+ * @param result - The expert system execution result
+ * @param goals - Optional list of goal facts to highlight
+ * @returns Formatted string
+ *
+ * @example
+ * ```typescript
+ * const result = engine.execute(rules);
+ * console.log(formatResult(result, ['loanDecision']));
+ * ```
+ */
+export function formatResult(
+  result: ExpertResult,
+  goals: string[] = []
+): string {
+  const lines: string[] = [];
+
+  // Inference chain
+  lines.push(formatInferenceChain(result, { includeBorders: true }));
+
+  // Conclusions section
+  lines.push(centerText('CONCLUSIONS', LINE_WIDTH));
+  lines.push(DOUBLE_LINE);
+
+  const conclusionEntries = Object.entries(result.conclusions);
+  if (conclusionEntries.length === 0) {
+    lines.push('  (none)');
+  } else {
+    // Find max key length for alignment
+    const maxKeyLen = Math.max(...conclusionEntries.map(([k]) => k.length));
+
+    for (const [key, value] of conclusionEntries) {
+      const isGoal = goals.includes(key);
+      const marker = isGoal ? ' ← GOAL' : '';
+      const paddedKey = key.padEnd(maxKeyLen);
+      lines.push(`  ${paddedKey} = ${JSON.stringify(value)}${marker}`);
+    }
+  }
+
+  // Statistics footer
+  lines.push('');
+  lines.push(DOUBLE_LINE);
+  const stats = `Reached ${conclusionEntries.length} conclusion(s) via ${result.rulesFired} rule(s) in ${result.executionTimeMs.toFixed(1)}ms`;
+  lines.push(stats);
+  lines.push(DOUBLE_LINE);
+
+  return lines.join('\n');
+}
+
+// ========================================
+// Helper Functions
+// ========================================
+
+/**
+ * Center text within a given width.
+ */
+function centerText(text: string, width: number): string {
+  const padding = Math.max(0, Math.floor((width - text.length) / 2));
+  return ' '.repeat(padding) + text;
+}
+
+/**
+ * Parse factsUsed array into readable input strings.
+ * Input: ['app={"creditScore":780,"income":95000}']
+ * Output: ['app.creditScore = 780', 'app.income = 95000']
+ */
+function parseFactsUsed(factsUsed: string[], maxProps = 3): string[] {
+  const inputs: string[] = [];
+
+  for (const factStr of factsUsed) {
+    const eqIndex = factStr.indexOf('=');
+    if (eqIndex === -1) continue;
+
+    const bindingName = factStr.substring(0, eqIndex);
+    const jsonStr = factStr.substring(eqIndex + 1);
+
+    try {
+      const data = JSON.parse(jsonStr);
+      if (typeof data === 'object' && data !== null) {
+        // Extract key properties (limit to avoid huge output)
+        const entries = Object.entries(data).slice(0, maxProps);
+        const parts = entries.map(([key, value]) => `${bindingName}.${key} = ${formatValue(value)}`);
+        inputs.push(parts.join(', '));
+      } else {
+        inputs.push(`${bindingName} = ${formatValue(data)}`);
+      }
+    } catch {
+      // If parsing fails, use as-is
+      inputs.push(factStr);
+    }
+  }
+
+  return inputs;
+}
+
+/**
+ * Format a value for display (shorter than JSON.stringify for numbers).
+ */
+function formatValue(value: unknown): string {
+  if (typeof value === 'number') {
+    return String(value);
+  }
+  if (typeof value === 'boolean') {
+    return String(value);
+  }
+  return JSON.stringify(value);
+}

package/src/engines/expert/index.ts

@@ -0,0 +1,85 @@
+/**
+ * Expert System Engine
+ *
+ * Provides explainable AI - decisions with full audit trails showing
+ * WHY each conclusion was reached.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   ExpertEngine,
+ *   compileExpertRuleSet,
+ *   ExpertRuleSet
+ * } from '@higher.archi/boe';
+ *
+ * const ruleSet: ExpertRuleSet = {
+ *   id: 'loan-approval',
+ *   mode: 'expert',
+ *   config: { goals: ['loanDecision'] },
+ *   rules: [...]
+ * };
+ *
+ * const compiled = compileExpertRuleSet(ruleSet);
+ * const engine = new ExpertEngine();
+ * engine.add({ type: 'Applicant', data: { creditScore: 720 } });
+ *
+ * const result = engine.execute(compiled);
+ * console.log(result.conclusions);   // { creditTier: 'good', loanDecision: 'approved' }
+ * console.log(result.explanation);   // Human-readable reasoning
+ * ```
+ */
+
+// Types
+export {
+  // Semantic confidence
+  SemanticConfidence,
+  SEMANTIC_CONFIDENCES,
+  Confidence,
+
+  // Source types
+  ExplainBlock,
+  ExpertRule,
+  ExpertConfig,
+  FactDefinitions,
+  ExpertRuleSet,
+
+  // Compiled types
+  CompiledTemplate,
+  CompiledTemplateRef,
+  CompiledExplainBlock,
+  CompiledExpertRule,
+  CompiledExpertRuleSet,
+
+  // Runtime types
+  InferenceStep,
+  ExpertOptions,
+  ExpertResult,
+  ExpertQueryResult
+} from './types';
+
+// Compiler
+export { compileExpertRuleSet } from './compiler';
+
+// Engine
+export { ExpertEngine } from './engine';
+
+// Strategy (for advanced use cases)
+export { ExpertStrategy, expertStrategy } from './strategy';
+
+// Interpolation utilities (for extensions)
+export {
+  compileTemplate,
+  hasInterpolation,
+  extractRefs,
+  interpolate,
+  buildAvailableRefs,
+  validateExplainTemplates,
+  InterpolationContext
+} from './interpolation';
+
+// Formatter utilities
+export {
+  formatInferenceChain,
+  formatResult,
+  FormatOptions
+} from './formatter';

package/src/engines/expert/interpolation.ts

@@ -0,0 +1,278 @@
+/**
+ * Template Interpolation for Expert System
+ *
+ * Provides compile-time template parsing and runtime interpolation
+ * for explanation strings.
+ *
+ * Syntax:
+ * - ${app.creditScore} - Reference input binding property
+ * - ${creditTier} - Reference derived/asserted fact
+ * - ${finalRate} - Reference scoped variable
+ *
+ * The ${...} syntax is unambiguous, so no escaping is needed.
+ * Regular $ signs outside of ${...} are preserved as-is.
+ */
+
+import { CompiledTemplate, CompiledTemplateRef } from './types';
+
+/**
+ * Regular expression to match template interpolations.
+ * Only matches ${...} patterns - standalone $ is left alone.
+ */
+const INTERPOLATION_REGEX = /\$\{([^}]+)\}/g;
+
+/**
+ * Parse a template string into a compiled template.
+ *
+ * @param template - Template string with ${...} interpolations
+ * @param availableRefs - Set of valid reference names for validation
+ * @param ruleId - Rule ID for error messages
+ * @returns Compiled template ready for interpolation
+ * @throws Error if template contains invalid references
+ */
+export function compileTemplate(
+  template: string,
+  availableRefs?: Set<string>,
+  ruleId?: string
+): CompiledTemplate {
+  const parts: string[] = [];
+  const refs: CompiledTemplateRef[] = [];
+
+  let lastIndex = 0;
+  let match: RegExpExecArray | null;
+
+  // Reset regex state
+  INTERPOLATION_REGEX.lastIndex = 0;
+
+  // Structure: parts[0] + refs[0] + parts[1] + refs[1] + ... + parts[n]
+  // parts.length = refs.length + 1
+
+  while ((match = INTERPOLATION_REGEX.exec(template)) !== null) {
+    // Add static part before this match
+    parts.push(template.slice(lastIndex, match.index));
+
+    const refStr = match[1].trim();
+    const path = refStr.split('.');
+
+    // Validate reference if availableRefs provided
+    if (availableRefs) {
+      const rootRef = path[0];
+      if (!availableRefs.has(rootRef)) {
+        const ruleContext = ruleId ? ` in rule '${ruleId}'` : '';
+        throw new Error(
+          `Invalid template reference '${refStr}'${ruleContext}. ` +
+          `'${rootRef}' is not a valid input binding, derived fact, or explain variable. ` +
+          `Available: ${Array.from(availableRefs).join(', ')}`
+        );
+      }
+    }
+
+    // Determine if this is a binding reference (has dot path) or derived fact
+    const isBinding = path.length > 1;
+
+    refs.push({ path, isBinding });
+    lastIndex = match.index + match[0].length;
+  }
+
+  // Add remaining static part
+  parts.push(template.slice(lastIndex));
+
+  return { source: template, parts, refs };
+}
+
+/**
+ * Check if a string contains interpolation syntax.
+ *
+ * @param str - String to check
+ * @returns True if string contains ${...} patterns
+ */
+export function hasInterpolation(str: string): boolean {
+  return str.includes('${');
+}
+
+/**
+ * Extract all reference names from a template.
+ * Useful for building the set of available references.
+ *
+ * @param template - Template string
+ * @returns Array of root reference names
+ */
+export function extractRefs(template: string): string[] {
+  const refs: string[] = [];
+  let match: RegExpExecArray | null;
+
+  INTERPOLATION_REGEX.lastIndex = 0;
+
+  while ((match = INTERPOLATION_REGEX.exec(template)) !== null) {
+    if (match[1]) {
+      const path = match[1].trim().split('.');
+      refs.push(path[0]);
+    }
+  }
+
+  return refs;
+}
+
+/**
+ * Interpolation context containing all available values.
+ */
+export type InterpolationContext = {
+  /** Input binding values (e.g., { app: { creditScore: 720 } }) */
+  bindings: Record<string, Record<string, unknown>>;
+  /** Derived/asserted facts (e.g., { creditTier: 'good' }) */
+  facts: Record<string, unknown>;
+  /** Scoped explain variables (e.g., { finalRate: 5.25 }) */
+  variables?: Record<string, unknown>;
+};
+
+/**
+ * Interpolate a compiled template with runtime values.
+ *
+ * @param compiled - Compiled template
+ * @param context - Values to interpolate
+ * @returns Interpolated string
+ */
+export function interpolate(
+  compiled: CompiledTemplate,
+  context: InterpolationContext
+): string {
+  if (compiled.refs.length === 0) {
+    // No interpolations - return joined static parts
+    return compiled.parts.join('');
+  }
+
+  const result: string[] = [];
+
+  for (let i = 0; i < compiled.parts.length; i++) {
+    result.push(compiled.parts[i]);
+
+    if (i < compiled.refs.length) {
+      const ref = compiled.refs[i];
+      const value = resolveRef(ref, context);
+      result.push(formatValue(value));
+    }
+  }
+
+  return result.join('');
+}
+
+/**
+ * Resolve a reference to its value.
+ */
+function resolveRef(
+  ref: CompiledTemplateRef,
+  context: InterpolationContext
+): unknown {
+  const [root, ...rest] = ref.path;
+
+  // Check explain variables first (highest priority)
+  if (context.variables && root in context.variables) {
+    return rest.length === 0
+      ? context.variables[root]
+      : getNestedValue(context.variables[root], rest);
+  }
+
+  // Check bindings (for input.property references)
+  if (root in context.bindings) {
+    const binding = context.bindings[root];
+    return rest.length === 0
+      ? binding
+      : getNestedValue(binding, rest);
+  }
+
+  // Check facts (for derived/asserted facts)
+  if (root in context.facts) {
+    return rest.length === 0
+      ? context.facts[root]
+      : getNestedValue(context.facts[root], rest);
+  }
+
+  // Not found - return placeholder
+  return `<${ref.path.join('.')}>`;
+}
+
+/**
+ * Get a nested value from an object using a path array.
+ */
+function getNestedValue(obj: unknown, path: string[]): unknown {
+  let current = obj;
+
+  for (const key of path) {
+    if (current == null || typeof current !== 'object') {
+      return undefined;
+    }
+    current = (current as Record<string, unknown>)[key];
+  }
+
+  return current;
+}
+
+/**
+ * Format a value for display in an explanation.
+ */
+function formatValue(value: unknown): string {
+  if (value === null) return 'null';
+  if (value === undefined) return 'undefined';
+  if (typeof value === 'string') return value;
+  if (typeof value === 'number') {
+    // Format numbers nicely (avoid excessive decimals)
+    return Number.isInteger(value) ? String(value) : value.toFixed(2);
+  }
+  if (typeof value === 'boolean') return String(value);
+  if (Array.isArray(value)) return JSON.stringify(value);
+  if (typeof value === 'object') return JSON.stringify(value);
+  return String(value);
+}
+
+/**
+ * Build a set of available references for validation.
+ *
+ * @param inputNames - Names of input bindings (e.g., ['app', 'customer'])
+ * @param derivedFacts - Names of potentially derived facts
+ * @param explainVars - Names of explain.variables
+ * @returns Set of valid root reference names
+ */
+export function buildAvailableRefs(
+  inputNames: string[],
+  derivedFacts: string[],
+  explainVars: string[]
+): Set<string> {
+  return new Set([...inputNames, ...derivedFacts, ...explainVars]);
+}
+
+/**
+ * Validate all templates in an explain block.
+ *
+ * @param explain - Explain block with templates
+ * @param availableRefs - Set of valid references
+ * @param ruleId - Rule ID for error messages
+ * @throws Error if any template has invalid references
+ */
+export function validateExplainTemplates(
+  explain: {
+    onFire: string;
+    onSkip?: string;
+    factors?: string[];
+    suggestion?: string;
+  },
+  availableRefs: Set<string>,
+  ruleId: string
+): void {
+  // Validate onFire (required)
+  compileTemplate(explain.onFire, availableRefs, ruleId);
+
+  // Validate optional templates
+  if (explain.onSkip) {
+    compileTemplate(explain.onSkip, availableRefs, ruleId);
+  }
+
+  if (explain.factors) {
+    for (const factor of explain.factors) {
+      compileTemplate(factor, availableRefs, ruleId);
+    }
+  }
+
+  if (explain.suggestion) {
+    compileTemplate(explain.suggestion, availableRefs, ruleId);
+  }
+}