@higher.archi/boe 1.0.0

package/dist/engines/expert/engine.js

@@ -0,0 +1,201 @@
+"use strict";
+/**
+ * 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);
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExpertEngine = void 0;
+const core_1 = require("../../core");
+const strategy_1 = require("./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);
+ * ```
+ */
+class ExpertEngine {
+    wm;
+    strategy;
+    /**
+     * Create a new ExpertEngine.
+     *
+     * @param workingMemory - Optional shared WorkingMemory. If not provided, creates its own.
+     */
+    constructor(workingMemory) {
+        this.wm = workingMemory ?? new core_1.WorkingMemory();
+        this.strategy = new strategy_1.ExpertStrategy();
+    }
+    // ========================================
+    // IWorkingMemory Implementation
+    // ========================================
+    /**
+     * Add a fact to working memory.
+     */
+    add(input) {
+        return this.wm.add(input);
+    }
+    /**
+     * Remove a fact from working memory.
+     */
+    remove(factId) {
+        return this.wm.remove(factId);
+    }
+    /**
+     * Update a fact in working memory.
+     */
+    update(input) {
+        return this.wm.update(input);
+    }
+    /**
+     * Get a fact by ID.
+     */
+    get(factId) {
+        return this.wm.get(factId);
+    }
+    /**
+     * Get all facts of a specific type.
+     */
+    getByType(type) {
+        return this.wm.getByType(type);
+    }
+    /**
+     * Get all facts in working memory.
+     */
+    getAll() {
+        return this.wm.getAll();
+    }
+    /**
+     * Check if a fact exists.
+     */
+    has(factId) {
+        return this.wm.has(factId);
+    }
+    /**
+     * Get the number of facts in working memory.
+     */
+    size() {
+        return this.wm.size();
+    }
+    /**
+     * Clear all facts from working memory.
+     */
+    clear() {
+        this.wm.clear();
+    }
+    /**
+     * Get pending changes since last check.
+     */
+    getChanges() {
+        return this.wm.getChanges();
+    }
+    /**
+     * Clear pending changes.
+     */
+    clearChanges() {
+        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, options = {}) {
+        return this.strategy.run(ruleSet, this.wm, options);
+    }
+    // ========================================
+    // Utility Methods
+    // ========================================
+    /**
+     * Get the underlying WorkingMemory instance.
+     * Useful for sharing memory between multiple engines.
+     */
+    getWorkingMemory() {
+        return this.wm;
+    }
+}
+exports.ExpertEngine = ExpertEngine;
+//# sourceMappingURL=engine.js.map

package/dist/engines/expert/engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.js","sourceRoot":"","sources":["../../../src/engines/expert/engine.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;;;AAEH,qCAMoB;AAQpB,yCAA4C;AAE5C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAa,YAAY;IACf,EAAE,CAAgB;IAClB,QAAQ,CAAiB;IAEjC;;;;OAIG;IACH,YAAY,aAA6B;QACvC,IAAI,CAAC,EAAE,GAAG,aAAa,IAAI,IAAI,oBAAa,EAAE,CAAC;QAC/C,IAAI,CAAC,QAAQ,GAAG,IAAI,yBAAc,EAAE,CAAC;IACvC,CAAC;IAED,2CAA2C;IAC3C,gCAAgC;IAChC,2CAA2C;IAE3C;;OAEG;IACH,GAAG,CAAC,KAAgB;QAClB,OAAO,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IAC5B,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,MAAc;QACnB,OAAO,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAChC,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,KAAgB;QACrB,OAAO,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC/B,CAAC;IAED;;OAEG;IACH,GAAG,CAAC,MAAc;QAChB,OAAO,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAC7B,CAAC;IAED;;OAEG;IACH,SAAS,CAAC,IAAY;QACpB,OAAO,IAAI,CAAC,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IACjC,CAAC;IAED;;OAEG;IACH,MAAM;QACJ,OAAO,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC;IAC1B,CAAC;IAED;;OAEG;IACH,GAAG,CAAC,MAAc;QAChB,OAAO,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAC7B,CAAC;IAED;;OAEG;IACH,IAAI;QACF,OAAO,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC;IACxB,CAAC;IAED;;OAEG;IACH,KAAK;QACH,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC;IAClB,CAAC;IAED;;OAEG;IACH,UAAU;QACR,OAAO,IAAI,CAAC,EAAE,CAAC,UAAU,EAAE,CAAC;IAC9B,CAAC;IAED;;OAEG;IACH,YAAY;QACV,IAAI,CAAC,EAAE,CAAC,YAAY,EAAE,CAAC;IACzB,CAAC;IAED,2CAA2C;IAC3C,6BAA6B;IAC7B,2CAA2C;IAE3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkCG;IACH,OAAO,CAAC,OAA8B,EAAE,UAAyB,EAAE;QACjE,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;IACtD,CAAC;IAED,2CAA2C;IAC3C,kBAAkB;IAClB,2CAA2C;IAE3C;;;OAGG;IACH,gBAAgB;QACd,OAAO,IAAI,CAAC,EAAE,CAAC;IACjB,CAAC;CACF;AArJD,oCAqJC"}

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

@@ -0,0 +1,56 @@
+/**
+ * Expert System Result Formatter
+ *
+ * Utilities for formatting inference chains and results into
+ * human-readable ASCII output.
+ */
+import { ExpertResult } from './types';
+/**
+ * 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 declare function formatInferenceChain(result: ExpertResult, options?: FormatOptions): string;
+/**
+ * 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 declare function formatResult(result: ExpertResult, goals?: string[]): string;
+//# sourceMappingURL=formatter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"formatter.d.ts","sourceRoot":"","sources":["../../../src/engines/expert/formatter.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAavC;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IAEzB;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IAEtB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,YAAY,EACpB,OAAO,GAAE,aAAkB,GAC1B,MAAM,CAwER;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,YAAY,EACpB,KAAK,GAAE,MAAM,EAAO,GACnB,MAAM,CAiCR"}

package/dist/engines/expert/formatter.js

@@ -0,0 +1,182 @@
+"use strict";
+/**
+ * Expert System Result Formatter
+ *
+ * Utilities for formatting inference chains and results into
+ * human-readable ASCII output.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatInferenceChain = formatInferenceChain;
+exports.formatResult = formatResult;
+// ========================================
+// Constants
+// ========================================
+const LINE_WIDTH = 79;
+const DOUBLE_LINE = '═'.repeat(LINE_WIDTH);
+/**
+ * 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));
+ * ```
+ */
+function formatInferenceChain(result, options = {}) {
+    const { includeBorders = true } = options;
+    const lines = [];
+    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']));
+ * ```
+ */
+function formatResult(result, goals = []) {
+    const lines = [];
+    // 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, width) {
+    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, maxProps = 3) {
+    const inputs = [];
+    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) {
+    if (typeof value === 'number') {
+        return String(value);
+    }
+    if (typeof value === 'boolean') {
+        return String(value);
+    }
+    return JSON.stringify(value);
+}
+//# sourceMappingURL=formatter.js.map

package/dist/engines/expert/formatter.js.map

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

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

@@ -0,0 +1,37 @@
+/**
+ * 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
+ * ```
+ */
+export { SemanticConfidence, SEMANTIC_CONFIDENCES, Confidence, ExplainBlock, ExpertRule, ExpertConfig, FactDefinitions, ExpertRuleSet, CompiledTemplate, CompiledTemplateRef, CompiledExplainBlock, CompiledExpertRule, CompiledExpertRuleSet, InferenceStep, ExpertOptions, ExpertResult, ExpertQueryResult } from './types';
+export { compileExpertRuleSet } from './compiler';
+export { ExpertEngine } from './engine';
+export { ExpertStrategy, expertStrategy } from './strategy';
+export { compileTemplate, hasInterpolation, extractRefs, interpolate, buildAvailableRefs, validateExplainTemplates, InterpolationContext } from './interpolation';
+export { formatInferenceChain, formatResult, FormatOptions } from './formatter';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/engines/expert/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAGH,OAAO,EAEL,kBAAkB,EAClB,oBAAoB,EACpB,UAAU,EAGV,YAAY,EACZ,UAAU,EACV,YAAY,EACZ,eAAe,EACf,aAAa,EAGb,gBAAgB,EAChB,mBAAmB,EACnB,oBAAoB,EACpB,kBAAkB,EAClB,qBAAqB,EAGrB,aAAa,EACb,aAAa,EACb,YAAY,EACZ,iBAAiB,EAClB,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAGlD,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAGxC,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAG5D,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,WAAW,EACX,WAAW,EACX,kBAAkB,EAClB,wBAAwB,EACxB,oBAAoB,EACrB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,oBAAoB,EACpB,YAAY,EACZ,aAAa,EACd,MAAM,aAAa,CAAC"}

package/dist/engines/expert/index.js

@@ -0,0 +1,59 @@
+"use strict";
+/**
+ * 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
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatResult = exports.formatInferenceChain = exports.validateExplainTemplates = exports.buildAvailableRefs = exports.interpolate = exports.extractRefs = exports.hasInterpolation = exports.compileTemplate = exports.expertStrategy = exports.ExpertStrategy = exports.ExpertEngine = exports.compileExpertRuleSet = exports.SEMANTIC_CONFIDENCES = void 0;
+// Types
+var types_1 = require("./types");
+Object.defineProperty(exports, "SEMANTIC_CONFIDENCES", { enumerable: true, get: function () { return types_1.SEMANTIC_CONFIDENCES; } });
+// Compiler
+var compiler_1 = require("./compiler");
+Object.defineProperty(exports, "compileExpertRuleSet", { enumerable: true, get: function () { return compiler_1.compileExpertRuleSet; } });
+// Engine
+var engine_1 = require("./engine");
+Object.defineProperty(exports, "ExpertEngine", { enumerable: true, get: function () { return engine_1.ExpertEngine; } });
+// Strategy (for advanced use cases)
+var strategy_1 = require("./strategy");
+Object.defineProperty(exports, "ExpertStrategy", { enumerable: true, get: function () { return strategy_1.ExpertStrategy; } });
+Object.defineProperty(exports, "expertStrategy", { enumerable: true, get: function () { return strategy_1.expertStrategy; } });
+// Interpolation utilities (for extensions)
+var interpolation_1 = require("./interpolation");
+Object.defineProperty(exports, "compileTemplate", { enumerable: true, get: function () { return interpolation_1.compileTemplate; } });
+Object.defineProperty(exports, "hasInterpolation", { enumerable: true, get: function () { return interpolation_1.hasInterpolation; } });
+Object.defineProperty(exports, "extractRefs", { enumerable: true, get: function () { return interpolation_1.extractRefs; } });
+Object.defineProperty(exports, "interpolate", { enumerable: true, get: function () { return interpolation_1.interpolate; } });
+Object.defineProperty(exports, "buildAvailableRefs", { enumerable: true, get: function () { return interpolation_1.buildAvailableRefs; } });
+Object.defineProperty(exports, "validateExplainTemplates", { enumerable: true, get: function () { return interpolation_1.validateExplainTemplates; } });
+// Formatter utilities
+var formatter_1 = require("./formatter");
+Object.defineProperty(exports, "formatInferenceChain", { enumerable: true, get: function () { return formatter_1.formatInferenceChain; } });
+Object.defineProperty(exports, "formatResult", { enumerable: true, get: function () { return formatter_1.formatResult; } });
+//# sourceMappingURL=index.js.map

package/dist/engines/expert/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/engines/expert/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;;;AAEH,QAAQ;AACR,iCAyBiB;AAtBf,6GAAA,oBAAoB,OAAA;AAwBtB,WAAW;AACX,uCAAkD;AAAzC,gHAAA,oBAAoB,OAAA;AAE7B,SAAS;AACT,mCAAwC;AAA/B,sGAAA,YAAY,OAAA;AAErB,oCAAoC;AACpC,uCAA4D;AAAnD,0GAAA,cAAc,OAAA;AAAE,0GAAA,cAAc,OAAA;AAEvC,2CAA2C;AAC3C,iDAQyB;AAPvB,gHAAA,eAAe,OAAA;AACf,iHAAA,gBAAgB,OAAA;AAChB,4GAAA,WAAW,OAAA;AACX,4GAAA,WAAW,OAAA;AACX,mHAAA,kBAAkB,OAAA;AAClB,yHAAA,wBAAwB,OAAA;AAI1B,sBAAsB;AACtB,yCAIqB;AAHnB,iHAAA,oBAAoB,OAAA;AACpB,yGAAA,YAAY,OAAA"}

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

@@ -0,0 +1,83 @@
+/**
+ * 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 } from './types';
+/**
+ * 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 declare function compileTemplate(template: string, availableRefs?: Set<string>, ruleId?: string): CompiledTemplate;
+/**
+ * Check if a string contains interpolation syntax.
+ *
+ * @param str - String to check
+ * @returns True if string contains ${...} patterns
+ */
+export declare function hasInterpolation(str: string): boolean;
+/**
+ * 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 declare function extractRefs(template: string): string[];
+/**
+ * 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 declare function interpolate(compiled: CompiledTemplate, context: InterpolationContext): string;
+/**
+ * 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 declare function buildAvailableRefs(inputNames: string[], derivedFacts: string[], explainVars: string[]): Set<string>;
+/**
+ * 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 declare function validateExplainTemplates(explain: {
+    onFire: string;
+    onSkip?: string;
+    factors?: string[];
+    suggestion?: string;
+}, availableRefs: Set<string>, ruleId: string): void;
+//# sourceMappingURL=interpolation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"interpolation.d.ts","sourceRoot":"","sources":["../../../src/engines/expert/interpolation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,gBAAgB,EAAuB,MAAM,SAAS,CAAC;AAQhE;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,aAAa,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,EAC3B,MAAM,CAAC,EAAE,MAAM,GACd,gBAAgB,CA4ClB;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAErD;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CActD;AAED;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,iEAAiE;IACjE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAClD,4DAA4D;IAC5D,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,2DAA2D;IAC3D,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,QAAQ,EAAE,gBAAgB,EAC1B,OAAO,EAAE,oBAAoB,GAC5B,MAAM,CAmBR;AAsED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,MAAM,EAAE,EACpB,YAAY,EAAE,MAAM,EAAE,EACtB,WAAW,EAAE,MAAM,EAAE,GACpB,GAAG,CAAC,MAAM,CAAC,CAEb;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE;IACP,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,EACD,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,EAC1B,MAAM,EAAE,MAAM,GACb,IAAI,CAkBN"}