@higher.archi/boe 1.0.0

package/src/engines/expert/types.ts

@@ -0,0 +1,442 @@
+/**
+ * Expert System Engine Types
+ *
+ * The Expert System engine provides explainable AI - decisions with full audit
+ * trails showing WHY each conclusion was reached. Unlike Forward Chaining which
+ * focuses on actions, the Expert System captures reasoning as a first-class output.
+ *
+ * Key Concepts:
+ * - Goals: What the system tries to conclude (e.g., 'loanDecision')
+ * - Assertions: Facts derived by rules (e.g., { creditTier: 'good' })
+ * - Inference Chain: Step-by-step reasoning trace
+ * - Explanations: Human-readable descriptions per rule
+ */
+
+import {
+  BaseRule,
+  BaseRuleSet,
+  CompiledBaseRule,
+  CompiledBaseRuleSet,
+  Condition,
+  Operand,
+  CompiledCondition,
+  CompiledOperand,
+  BindingContext
+} from '../../core';
+
+// ========================================
+// Semantic Confidence Types
+// ========================================
+
+/**
+ * Semantic confidence labels for human-readable rule authoring.
+ * Maps to numeric values between 0.0 and 1.0.
+ */
+export type SemanticConfidence =
+  | 'certain'     // 1.0 - Absolute certainty (e.g., mathematical facts)
+  | 'very-high'   // 0.95 - Near certain (e.g., well-established patterns)
+  | 'high'        // 0.85 - Strong confidence (e.g., clear evidence)
+  | 'likely'      // 0.75 - Probable (e.g., good indicators)
+  | 'moderate'    // 0.65 - Moderate confidence (e.g., partial evidence)
+  | 'possible'    // 0.50 - Even odds (e.g., uncertain)
+  | 'unlikely'    // 0.35 - Improbable (e.g., weak evidence)
+  | 'low';        // 0.20 - Low confidence (e.g., minimal support)
+
+/**
+ * Mapping from semantic labels to numeric confidence values.
+ */
+export const SEMANTIC_CONFIDENCES: Record<SemanticConfidence, number> = {
+  'certain': 1.0,
+  'very-high': 0.95,
+  'high': 0.85,
+  'likely': 0.75,
+  'moderate': 0.65,
+  'possible': 0.50,
+  'unlikely': 0.35,
+  'low': 0.20
+};
+
+/**
+ * Confidence value - either numeric (0.0-1.0) or semantic label.
+ */
+export type Confidence = number | SemanticConfidence;
+
+// ========================================
+// Source Types (User-Defined)
+// ========================================
+
+/**
+ * Explanation block for a rule.
+ *
+ * Templates support ${...} interpolation:
+ * - ${app.creditScore} - Input binding property
+ * - ${creditTier} - Derived/asserted fact
+ * - ${finalRate} - Scoped variable from 'variables'
+ *
+ * Regular $ signs are preserved as-is (no escaping needed).
+ * Example: "$${amount}" -> "$50000"
+ */
+export type ExplainBlock = {
+  /**
+   * Scoped variables computed at explanation time.
+   * Uses standard expression syntax (operators, references).
+   *
+   * @example
+   * variables: {
+   *   finalRate: ['if', '$loyaltyBonus', 5.25, 5.5],
+   *   formattedIncome: ['concat', '$', '$app.annualIncome']
+   * }
+   */
+  variables?: Record<string, Operand>;
+
+  /**
+   * Template shown when rule fires.
+   * Supports ${...} interpolation.
+   */
+  onFire: string;
+
+  /**
+   * Template shown when rule is evaluated but doesn't fire.
+   * Useful for explaining why a rule was skipped.
+   */
+  onSkip?: string;
+
+  /**
+   * Contributing factors for summary generation.
+   * Array of templates that explain what led to the conclusion.
+   */
+  factors?: string[];
+
+  /**
+   * Actionable suggestion (typically for denials).
+   * Shown in the explanation to guide next steps.
+   */
+  suggestion?: string;
+};
+
+/**
+ * Expert System rule.
+ *
+ * Unlike Forward Chaining rules that execute actions, Expert System rules
+ * assert conclusions and provide explanations for auditing.
+ */
+export type ExpertRule = BaseRule & {
+  /**
+   * Human-readable description of what this rule does.
+   * Required for expert rules to support explanation generation.
+   */
+  description: string;
+
+  /**
+   * Additional condition evaluated after input matching.
+   * Can reference derived facts from previously fired rules.
+   *
+   * Use this when your condition depends on facts asserted by other rules,
+   * not just the input facts from working memory.
+   */
+  when?: Condition;
+
+  /**
+   * Priority for rule ordering.
+   * Higher values run later, allowing rules to depend on derived facts.
+   */
+  priority?: number;
+
+  /**
+   * Conclusion asserted when rule fires.
+   */
+  then: {
+    /**
+     * Facts to assert when rule fires.
+     * Keys are fact names, values are constants or expressions.
+     *
+     * @example
+     * assert: {
+     *   creditTier: 'good',
+     *   interestRate: ['subtract', '$baseRate', 0.25]
+     * }
+     */
+    assert: Record<string, Operand>;
+
+    /**
+     * Confidence level for this conclusion.
+     *
+     * Accepts either:
+     * - Numeric value (0.0 - 1.0)
+     * - Semantic label: 'certain', 'very-high', 'high', 'likely',
+     *   'moderate', 'possible', 'unlikely', 'low'
+     *
+     * @example
+     * // Numeric
+     * confidence: 0.85
+     *
+     * // Semantic
+     * confidence: 'high'
+     */
+    confidence: Confidence;
+  };
+
+  /**
+   * Explanation templates for this rule.
+   * Required for expert rules.
+   */
+  explain: ExplainBlock;
+};
+
+/**
+ * Expert System configuration.
+ */
+export type ExpertConfig = {
+  /**
+   * Whether to track full inference chain.
+   * @default true
+   */
+  trackInference?: boolean;
+
+  /**
+   * Whether to generate human-readable explanations.
+   * @default true
+   */
+  generateExplanations?: boolean;
+
+  /**
+   * Goal facts the system tries to conclude.
+   * Execution stops when all goals are determined.
+   */
+  goals?: string[];
+
+  /**
+   * Minimum confidence threshold for a conclusion to "hold".
+   * @default 0.8
+   */
+  confidenceThreshold?: number;
+};
+
+/**
+ * Fact type definitions for validation.
+ * Maps type names to their property schemas.
+ */
+export type FactDefinitions = Record<string, Record<string, string>>;
+
+/**
+ * Expert System ruleset.
+ */
+export type ExpertRuleSet = BaseRuleSet & {
+  mode: 'expert';
+  rules: ExpertRule[];
+  config?: ExpertConfig;
+
+  /**
+   * Optional fact type definitions for compile-time validation.
+   */
+  facts?: FactDefinitions;
+};
+
+// ========================================
+// Compiled Types
+// ========================================
+
+/**
+ * Compiled template for efficient interpolation.
+ */
+export type CompiledTemplate = {
+  /** Original template string */
+  source: string;
+  /** Static parts between interpolations */
+  parts: string[];
+  /** Variable references to interpolate */
+  refs: CompiledTemplateRef[];
+};
+
+/**
+ * Reference within a template.
+ */
+export type CompiledTemplateRef = {
+  /** Full reference path (e.g., 'app.creditScore' or 'creditTier') */
+  path: string[];
+  /** Whether this references an input binding vs derived fact */
+  isBinding: boolean;
+};
+
+/**
+ * Compiled explanation block.
+ */
+export type CompiledExplainBlock = {
+  variables?: Record<string, CompiledOperand>;
+  onFire: CompiledTemplate;
+  onSkip?: CompiledTemplate;
+  factors?: CompiledTemplate[];
+  suggestion?: CompiledTemplate;
+};
+
+/**
+ * Compiled expert rule.
+ */
+export type CompiledExpertRule = CompiledBaseRule & {
+  description: string;
+  priority: number;
+  when?: CompiledCondition;
+  assert: Record<string, CompiledOperand>;
+  confidence: number;
+  explain: CompiledExplainBlock;
+};
+
+/**
+ * Compiled expert ruleset.
+ */
+export type CompiledExpertRuleSet = CompiledBaseRuleSet & {
+  mode: 'expert';
+  rules: CompiledExpertRule[];
+  config: Required<ExpertConfig>;
+};
+
+// ========================================
+// Runtime Types
+// ========================================
+
+/**
+ * Single step in the inference chain.
+ * Captures what happened when a rule was evaluated.
+ */
+export type InferenceStep = {
+  /** Rule that was evaluated */
+  ruleId: string;
+
+  /** Rule description */
+  description: string;
+
+  /** Whether the rule fired */
+  fired: boolean;
+
+  /** Input facts that were examined during evaluation */
+  factsUsed: string[];
+
+  /** Derived facts referenced in the `when` condition */
+  derivedFactsUsed?: Record<string, unknown>;
+
+  /** Facts asserted if rule fired */
+  asserted?: Record<string, unknown>;
+
+  /** Confidence of assertions */
+  confidence?: number;
+
+  /** Interpolated explanation (onFire or onSkip) */
+  explanation: string;
+};
+
+/**
+ * Runtime options for expert system execution.
+ */
+export type ExpertOptions = {
+  /**
+   * Callback when a rule fires.
+   */
+  onFire?: (ruleId: string, asserted: Record<string, unknown>, context: BindingContext) => void;
+
+  /**
+   * Callback when a rule is evaluated.
+   */
+  onEvaluate?: (ruleId: string, fired: boolean) => void;
+
+  /**
+   * Whether to include skipped rules in inference chain.
+   * @default false
+   */
+  includeSkipped?: boolean;
+
+  /**
+   * Whether to generate verbose explanations.
+   * @default true
+   */
+  verbose?: boolean;
+
+  /**
+   * Maximum rules to evaluate (circuit breaker).
+   * @default 1000
+   */
+  maxEvaluations?: number;
+};
+
+/**
+ * Execution result from the expert system.
+ */
+export type ExpertResult = {
+  /**
+   * All conclusions reached (asserted facts).
+   */
+  conclusions: Record<string, unknown>;
+
+  /**
+   * Step-by-step reasoning trace.
+   */
+  inferenceChain: InferenceStep[];
+
+  /**
+   * Human-readable explanation summary.
+   */
+  explanation: string;
+
+  /**
+   * Number of rules that fired.
+   */
+  rulesFired: number;
+
+  /**
+   * Number of rules evaluated (including non-firing).
+   */
+  rulesEvaluated: number;
+
+  /**
+   * Processing time in milliseconds.
+   */
+  executionTimeMs: number;
+
+  /**
+   * Timestamp of execution.
+   */
+  timestamp: string;
+
+  /**
+   * Query a specific conclusion.
+   *
+   * @param factName - Name of the fact to query
+   * @returns Query result with value, confidence, and status
+   */
+  query: (factName: string) => ExpertQueryResult;
+
+  /**
+   * Format the result as a human-readable string.
+   * Includes the inference chain, conclusions, and statistics.
+   *
+   * @returns Formatted ASCII report
+   *
+   * @example
+   * ```typescript
+   * const result = engine.execute(rules);
+   * console.log(result.toString());
+   * // or simply:
+   * console.log(`${result}`);
+   * ```
+   */
+  toString: () => string;
+};
+
+/**
+ * Result of querying a specific conclusion.
+ */
+export type ExpertQueryResult = {
+  /** Whether the fact was concluded */
+  exists: boolean;
+
+  /** The concluded value (if exists) */
+  value: unknown;
+
+  /** Confidence level of the conclusion */
+  confidence: number;
+
+  /** How the fact was determined */
+  status: 'concluded' | 'not-concluded' | 'unknown';
+
+  /** Rule that concluded this fact (if any) */
+  concludedBy?: string;
+};

package/src/engines/forward/compiler.ts

@@ -0,0 +1,205 @@
+/**
+ * Forward Chaining Engine Compiler
+ */
+
+import {
+  compileCondition,
+  compileOperand,
+  parsePath,
+  normalizeShape,
+  DEFAULT_STRATEGIES,
+  Condition,
+  PropertyRef
+} from '../../core';
+
+import {
+  ForwardRule,
+  ForwardRuleSet,
+  ForwardConfig,
+  CompiledForwardRule,
+  CompiledForwardRuleSet,
+  CompiledForwardAction,
+  CompiledActionItem,
+  CompiledSetAction,
+  ActionItem,
+  ThenValue
+} from './types';
+
+const DEFAULT_MAX_ITERATIONS = 1000;
+
+// ========================================
+// Helper Functions
+// ========================================
+
+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[], where?: any): number {
+  let score = 0;
+  score += inputs.length * 10;
+  score += countConditions(where) * 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)
+  };
+}
+
+function isPropertyRef(value: unknown): value is PropertyRef {
+  return typeof value === 'string' && value.startsWith('$');
+}
+
+function isExpression(value: unknown): value is Condition {
+  return Array.isArray(value) && value.length >= 2 && typeof value[0] === 'string';
+}
+
+// ========================================
+// Action Compilation
+// ========================================
+
+function compileActionItem(item: ActionItem): CompiledActionItem {
+  // Set action: compile target paths and value expressions
+  if ('set' in item) {
+    const compiledSets: CompiledSetAction['set'] = [];
+
+    for (const [targetPath, value] of Object.entries(item.set)) {
+      if (!isPropertyRef(targetPath)) {
+        throw new Error(`Set target must be a property reference (e.g., '$person.status'), got: ${targetPath}`);
+      }
+
+      // Check if value is an expression that needs to be compiled as a condition
+      if (isExpression(value)) {
+        compiledSets.push({
+          target: parsePath(targetPath),
+          value: { type: 'constant', value: null },  // Placeholder
+          expr: compileCondition(value)
+        });
+      } else {
+        compiledSets.push({
+          target: parsePath(targetPath),
+          value: compileOperand(value)
+        });
+      }
+    }
+
+    return { set: compiledSets };
+  }
+
+  // Retract action: extract parameter name from property ref
+  if ('retract' in item) {
+    const ref = item.retract;
+    if (!isPropertyRef(ref)) {
+      throw new Error(`Retract must be a property reference (e.g., '$duplicate'), got: ${ref}`);
+    }
+    // Extract just the parameter name (first part after $)
+    const paramName = ref.slice(1).split('.')[0];
+    return { retract: paramName };
+  }
+
+  // Call action: pass through unchanged
+  if ('call' in item) {
+    return { call: item.call };
+  }
+
+  // Halt action: pass through unchanged
+  if ('halt' in item) {
+    return { halt: true };
+  }
+
+  throw new Error(`Unknown action item type: ${JSON.stringify(item)}`);
+}
+
+function normalizeThenValue(value: ThenValue): ActionItem[] {
+  // String shorthand: 'handlerName' -> [{ call: 'handlerName' }]
+  if (typeof value === 'string') {
+    return [{ call: value }];
+  }
+
+  // Array: already in correct format
+  if (Array.isArray(value)) {
+    return value;
+  }
+
+  // Single ActionItem: wrap in array
+  return [value];
+}
+
+function compileThenAction(thenValue: ThenValue): CompiledForwardAction {
+  const items = normalizeThenValue(thenValue);
+  return {
+    mode: 'forward',
+    actions: items.map(compileActionItem)
+  };
+}
+
+// ========================================
+// Rule 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;
+}
+
+export function compileForwardRule(rule: ForwardRule, index: number = 0): CompiledForwardRule {
+  const inputs = rule.inputs.map(compileInputParameter);
+  const when = rule.when ? compileCondition(rule.when) : undefined;
+
+  return {
+    id: rule.id,
+    name: rule.name,
+    salience: rule.salience ?? 0,
+    complexity: calculateComplexity(inputs, when),
+    index,
+    inputs,
+    when,
+    action: compileThenAction(rule.then)
+  };
+}
+
+// ========================================
+// RuleSet Compilation
+// ========================================
+
+export function compileForwardRuleSet(ruleSet: ForwardRuleSet): CompiledForwardRuleSet {
+  const config: ForwardConfig = {
+    mode: 'forward',
+    maxIterations: ruleSet.config?.maxIterations ?? DEFAULT_MAX_ITERATIONS,
+    strategies: ruleSet.config?.strategies ?? DEFAULT_STRATEGIES
+  };
+
+  return {
+    id: ruleSet.id,
+    name: ruleSet.name,
+    mode: 'forward',
+    schema: ruleSet.shape ? normalizeShape(ruleSet.shape) : { type: 'object' },
+    rules: ruleSet.rules.map((rule, index) => compileForwardRule(rule, index)),
+    config
+  };
+}