@higher.archi/boe 1.0.17 → 1.0.19

package/src/engines/ensemble/compiler.ts

@@ -0,0 +1,97 @@
+/**
+ * Ensemble Engine Compiler
+ *
+ * Validates and compiles an EnsembleRuleSet into a CompiledEnsembleRuleSet.
+ */
+
+import { CompilationError } from '../../core';
+
+import type { TierDefinition } from '../scoring/types';
+import type {
+  EnsembleRuleSet,
+  CompiledEnsembleRuleSet,
+  CompiledEnsembleMember
+} from './types';
+
+/**
+ * Compile an ensemble ruleset — validates members, weights, and config,
+ * then tags each member with its type for runtime dispatch.
+ */
+export function compileEnsembleRuleSet<T extends TierDefinition = TierDefinition>(
+  ruleSet: EnsembleRuleSet<T>
+): CompiledEnsembleRuleSet<T> {
+  const { members, config } = ruleSet;
+
+  // Members array must be non-empty
+  if (!members || members.length === 0) {
+    throw new CompilationError(
+      `Ensemble "${ruleSet.id}": must have at least one member`
+    );
+  }
+
+  // No duplicate member IDs
+  const ids = new Set<string>();
+  for (const member of members) {
+    if (ids.has(member.id)) {
+      throw new CompilationError(
+        `Ensemble "${ruleSet.id}": duplicate member id "${member.id}"`
+      );
+    }
+    ids.add(member.id);
+  }
+
+  // All weights must be > 0
+  for (const member of members) {
+    if (member.weight <= 0) {
+      throw new CompilationError(
+        `Ensemble "${ruleSet.id}": member "${member.id}" weight must be > 0 (got ${member.weight})`
+      );
+    }
+  }
+
+  // For weighted-average and voting: weights must sum to ~1.0
+  if (config.strategy === 'weighted-average' || config.strategy === 'voting') {
+    const total = members.reduce((sum, m) => sum + m.weight, 0);
+    if (Math.abs(total - 1.0) > 0.001) {
+      throw new CompilationError(
+        `Ensemble "${ruleSet.id}": member weights must sum to 1.0 for strategy "${config.strategy}" (got ${total})`
+      );
+    }
+  }
+
+  // For stacking: config.stacking must be provided
+  if (config.strategy === 'stacking' && !config.stacking) {
+    throw new CompilationError(
+      `Ensemble "${ruleSet.id}": strategy "stacking" requires config.stacking to be provided`
+    );
+  }
+
+  // Tier IDs must be unique if tiers are configured
+  if (config.tiers && config.tiers.length > 0) {
+    const tierIds = new Set<string>();
+    for (const tier of config.tiers) {
+      if (tierIds.has(tier.id)) {
+        throw new CompilationError(
+          `Ensemble "${ruleSet.id}": duplicate tier id "${tier.id}"`
+        );
+      }
+      tierIds.add(tier.id);
+    }
+  }
+
+  // Tag each member with type
+  const compiledMembers: CompiledEnsembleMember<T>[] = members.map(member => {
+    if ('ruleset' in member) {
+      return { ...member, type: 'scoring' as const };
+    }
+    return { ...member, type: 'custom' as const };
+  });
+
+  return {
+    id: ruleSet.id,
+    name: ruleSet.name,
+    mode: 'ensemble',
+    members: compiledMembers,
+    config
+  };
+}

package/src/engines/ensemble/engine.ts

@@ -0,0 +1,130 @@
+/**
+ * Ensemble Engine
+ *
+ * Self-contained engine for multi-model score fusion.
+ * Orchestrates N member executions and fuses their results
+ * using configurable strategies.
+ */
+
+import {
+  WorkingMemory,
+  Fact,
+  FactInput,
+  FactChange
+} from '../../core';
+
+import type { TierDefinition } from '../scoring/types';
+
+import type {
+  CompiledEnsembleRuleSet,
+  EnsembleOptions,
+  EnsembleResult
+} from './types';
+
+import { EnsembleStrategy } from './strategy';
+
+/**
+ * Ensemble rule engine.
+ *
+ * Executes multiple member scoring rulesets (or custom executors) and fuses
+ * their results into a single composite score using configurable strategies.
+ *
+ * @example
+ * ```typescript
+ * const engine = new EnsembleEngine();
+ * engine.add({ type: 'Vendor', data: { revenue: 500000, compliance: true } });
+ *
+ * const result = engine.execute(compiledEnsemble);
+ * console.log(`Composite score: ${result.totalScore}`);
+ * console.log(`Agreement: ${result.agreement}`);
+ * ```
+ */
+export class EnsembleEngine {
+  private wm: WorkingMemory;
+  private strategy: EnsembleStrategy;
+
+  constructor(workingMemory?: WorkingMemory) {
+    this.wm = workingMemory ?? new WorkingMemory();
+    this.strategy = new EnsembleStrategy();
+  }
+
+  // ========================================
+  // IWorkingMemory Implementation
+  // ========================================
+
+  add<T = Record<string, any>>(input: FactInput<T>): Fact<T> {
+    return this.wm.add(input);
+  }
+
+  remove(factId: string): Fact | undefined {
+    return this.wm.remove(factId);
+  }
+
+  update<T = Record<string, any>>(input: FactInput<T>): Fact<T> {
+    return this.wm.update(input);
+  }
+
+  get(factId: string): Fact | undefined {
+    return this.wm.get(factId);
+  }
+
+  getByType(type: string): Fact[] {
+    return this.wm.getByType(type);
+  }
+
+  getAll(): Fact[] {
+    return this.wm.getAll();
+  }
+
+  has(factId: string): boolean {
+    return this.wm.has(factId);
+  }
+
+  size(): number {
+    return this.wm.size();
+  }
+
+  clear(): void {
+    this.wm.clear();
+  }
+
+  getChanges(): FactChange[] {
+    return this.wm.getChanges();
+  }
+
+  clearChanges(): void {
+    this.wm.clearChanges();
+  }
+
+  // ========================================
+  // Engine Execution
+  // ========================================
+
+  /**
+   * Execute an ensemble ruleset.
+   *
+   * Collects all facts from working memory, executes each member engine
+   * with its own independent working memory, and fuses results using
+   * the configured strategy.
+   *
+   * @param ruleSet - Compiled ensemble ruleset
+   * @param options - Runtime options (reserved for future use)
+   * @returns Ensemble result with fused score and per-member breakdown
+   */
+  execute<T extends TierDefinition = TierDefinition>(
+    ruleSet: CompiledEnsembleRuleSet<T>,
+    options: EnsembleOptions = {}
+  ): EnsembleResult<T> {
+    // Collect all facts from WM as FactInput[] so each sub-engine gets its own fresh WM
+    const facts = this.wm.getAll().map(f => ({ type: f.type, data: f.data, id: f.id }));
+    return this.strategy.run(ruleSet, facts, options);
+  }
+
+  // ========================================
+  // Utility Methods
+  // ========================================
+
+  getWorkingMemory(): WorkingMemory {
+    return this.wm;
+  }
+}

package/src/engines/ensemble/index.ts

@@ -0,0 +1,34 @@
+/**
+ * Ensemble Engine — Multi-Model Score Fusion
+ */
+
+// Types
+export type {
+  FusionStrategy,
+  ScoreExtractor,
+  ConfidenceExtractor,
+  ScoringMemberDef,
+  CustomMemberDef,
+  EnsembleMemberDef,
+  StackingConfig,
+  EnsembleConfig,
+  EnsembleRuleSet,
+  CompiledEnsembleMember,
+  CompiledEnsembleRuleSet,
+  EnsembleOptions,
+  MemberResult,
+  EnsembleResult,
+  EnsembleSummaryOptions
+} from './types';
+
+// Compiler
+export { compileEnsembleRuleSet } from './compiler';
+
+// Strategy
+export { EnsembleStrategy, ensembleStrategy } from './strategy';
+
+// Engine
+export { EnsembleEngine } from './engine';
+
+// Summary
+export { summarizeEnsemble } from './summary';

package/src/engines/ensemble/strategy.ts

@@ -0,0 +1,263 @@
+/**
+ * Ensemble Engine Strategy
+ *
+ * Executes N member engines and fuses their results using configurable
+ * fusion strategies (weighted-average, median, min, max, voting, stacking).
+ */
+
+import { ScoringEngine } from '../scoring/engine';
+import type { ScoringTierMatch, TierDefinition, OutputBounds } from '../scoring/types';
+import type { FactInput } from '../../core';
+
+import type {
+  CompiledEnsembleRuleSet,
+  EnsembleOptions,
+  EnsembleResult,
+  MemberResult
+} from './types';
+
+// ========================================
+// Output Bounds (reused from scoring)
+// ========================================
+
+function resolveOutputBounds(bounds: OutputBounds): { min: number; max: number } {
+  if (typeof bounds === 'object') return bounds;
+  switch (bounds) {
+    case 'percentage':  return { min: 0, max: 100 };
+    case 'points':      return { min: 0, max: 1000 };
+    case 'rating':      return { min: 0, max: 10 };
+    case 'stars':       return { min: 0, max: 5 };
+    case 'normalized':  return { min: 0, max: 1 };
+  }
+}
+
+// ========================================
+// Strategy
+// ========================================
+
+export class EnsembleStrategy {
+  run<T extends TierDefinition = TierDefinition>(
+    ruleSet: CompiledEnsembleRuleSet<T>,
+    facts: FactInput[],
+    _options: EnsembleOptions
+  ): EnsembleResult<T> {
+    const startTime = performance.now();
+    const { members, config } = ruleSet;
+
+    // 1. Execute all members
+    const memberResults: MemberResult[] = [];
+    const allFired: string[] = [];
+
+    for (const member of members) {
+      const memberStart = performance.now();
+      let score: number;
+      let confidence: number;
+
+      if (member.type === 'scoring') {
+        const engine = new ScoringEngine();
+        for (const fact of facts) {
+          engine.add(fact);
+        }
+        const result = engine.execute(member.ruleset, member.options);
+        score = result.totalScore;
+        confidence = result.confidence;
+
+        // Collect fired rules
+        for (const ruleId of result.fired) {
+          if (!allFired.includes(ruleId)) {
+            allFired.push(ruleId);
+          }
+        }
+      } else {
+        const result = member.execute(facts);
+        score = member.extractScore(result);
+        confidence = member.extractConfidence ? member.extractConfidence(result) : 1.0;
+      }
+
+      const memberTime = Math.round((performance.now() - memberStart) * 100) / 100;
+
+      memberResults.push({
+        memberId: member.id,
+        memberName: member.name,
+        score,
+        confidence,
+        weight: member.weight,
+        weightedScore: score * member.weight,
+        executionTimeMs: memberTime
+      });
+    }
+
+    // 2. Fuse by strategy
+    let fusedScore: number;
+    let fusedConfidence: number;
+
+    switch (config.strategy) {
+      case 'weighted-average': {
+        fusedScore = memberResults.reduce((sum, m) => sum + m.score * m.weight, 0);
+        fusedConfidence = memberResults.reduce((sum, m) => sum + m.confidence * m.weight, 0);
+        break;
+      }
+
+      case 'median': {
+        const sortedScores = [...memberResults].sort((a, b) => a.score - b.score);
+        const sortedConfidences = [...memberResults].sort((a, b) => a.confidence - b.confidence);
+        const mid = Math.floor(sortedScores.length / 2);
+
+        if (sortedScores.length % 2 === 0) {
+          fusedScore = (sortedScores[mid - 1].score + sortedScores[mid].score) / 2;
+          fusedConfidence = (sortedConfidences[mid - 1].confidence + sortedConfidences[mid].confidence) / 2;
+        } else {
+          fusedScore = sortedScores[mid].score;
+          fusedConfidence = sortedConfidences[mid].confidence;
+        }
+        break;
+      }
+
+      case 'min': {
+        let minIdx = 0;
+        for (let i = 1; i < memberResults.length; i++) {
+          if (memberResults[i].score < memberResults[minIdx].score) {
+            minIdx = i;
+          }
+        }
+        fusedScore = memberResults[minIdx].score;
+        fusedConfidence = memberResults[minIdx].confidence;
+        break;
+      }
+
+      case 'max': {
+        let maxIdx = 0;
+        for (let i = 1; i < memberResults.length; i++) {
+          if (memberResults[i].score > memberResults[maxIdx].score) {
+            maxIdx = i;
+          }
+        }
+        fusedScore = memberResults[maxIdx].score;
+        fusedConfidence = memberResults[maxIdx].confidence;
+        break;
+      }
+
+      case 'voting': {
+        let winnerIdx = 0;
+        let maxProduct = memberResults[0].confidence * memberResults[0].weight;
+        for (let i = 1; i < memberResults.length; i++) {
+          const product = memberResults[i].confidence * memberResults[i].weight;
+          if (product > maxProduct) {
+            maxProduct = product;
+            winnerIdx = i;
+          }
+        }
+        fusedScore = memberResults[winnerIdx].score;
+        fusedConfidence = memberResults[winnerIdx].confidence;
+        break;
+      }
+
+      case 'stacking': {
+        const stackingConfig = config.stacking!;
+        const stackEngine = new ScoringEngine();
+
+        // Add member scores as facts
+        for (const mr of memberResults) {
+          stackEngine.add({
+            type: 'EnsembleMemberScore',
+            data: {
+              memberId: mr.memberId,
+              score: mr.score,
+              confidence: mr.confidence
+            }
+          });
+        }
+
+        const stackResult = stackEngine.execute(stackingConfig.ruleset, stackingConfig.options);
+        fusedScore = stackResult.totalScore;
+        fusedConfidence = stackResult.confidence;
+        break;
+      }
+    }
+
+    // 3. Compute agreement: 1 - (stddev / (range / 2)), clamped to [0, 1]
+    const scores = memberResults.map(m => m.score);
+    const agreement = computeAgreement(scores, config.outputBounds);
+
+    // 4. Apply output bounds
+    if (config.outputBounds) {
+      const bounds = resolveOutputBounds(config.outputBounds);
+      fusedScore = Math.max(bounds.min, Math.min(bounds.max, fusedScore));
+    }
+
+    // 5. Match tier
+    let tier: ScoringTierMatch<T> | undefined;
+    if (config.tiers && config.tiers.length > 0) {
+      const resolveThreshold = (t: number | '-Infinity'): number =>
+        t === '-Infinity' ? Number.NEGATIVE_INFINITY : t;
+
+      const sortedTiers = [...config.tiers].sort(
+        (a, b) => resolveThreshold(b.threshold) - resolveThreshold(a.threshold)
+      );
+
+      for (const tierDef of sortedTiers) {
+        const threshold = resolveThreshold(tierDef.threshold);
+        if (fusedScore >= threshold) {
+          tier = {
+            ...tierDef,
+            threshold
+          } as ScoringTierMatch<T>;
+          break;
+        }
+      }
+    }
+
+    // 6. Build contributions map
+    const contributions: Record<string, number> = {};
+    for (const mr of memberResults) {
+      contributions[mr.memberId] = mr.score;
+    }
+
+    const executionTimeMs = Math.round((performance.now() - startTime) * 100) / 100;
+
+    return {
+      totalScore: fusedScore,
+      confidence: fusedConfidence,
+      tier,
+      strategy: config.strategy,
+      memberResults,
+      agreement,
+      fired: allFired,
+      contributions,
+      executionTimeMs
+    };
+  }
+}
+
+// ========================================
+// Agreement Calculation
+// ========================================
+
+function computeAgreement(scores: number[], outputBounds?: OutputBounds): number {
+  if (scores.length <= 1) return 1;
+
+  // Compute stddev
+  const mean = scores.reduce((sum, s) => sum + s, 0) / scores.length;
+  const variance = scores.reduce((sum, s) => sum + (s - mean) ** 2, 0) / scores.length;
+  const stddev = Math.sqrt(variance);
+
+  // Determine range
+  let range: number;
+  if (outputBounds) {
+    const bounds = resolveOutputBounds(outputBounds);
+    range = bounds.max - bounds.min;
+  } else {
+    const minScore = Math.min(...scores);
+    const maxScore = Math.max(...scores);
+    range = maxScore - minScore;
+  }
+
+  // Avoid division by zero — all scores identical
+  if (range === 0) return 1;
+
+  const halfRange = range / 2;
+  return Math.max(0, Math.min(1, 1 - (stddev / halfRange)));
+}
+
+// Export a singleton instance for convenience
+export const ensembleStrategy = new EnsembleStrategy();

package/src/engines/ensemble/summary.ts

@@ -0,0 +1,58 @@
+/**
+ * Ensemble Summary
+ *
+ * Generates human-readable summary strings from ensemble results.
+ */
+
+import type { EnsembleResult, EnsembleSummaryOptions } from './types';
+
+/**
+ * Generate a human-readable summary string from an EnsembleResult.
+ *
+ * @param result - The ensemble result to summarize
+ * @param options - Optional display settings
+ * @returns Formatted multi-line summary string
+ *
+ * @example
+ * ```typescript
+ * const result = engine.execute(compiledEnsemble);
+ * console.log(summarizeEnsemble(result));
+ * ```
+ */
+export function summarizeEnsemble(
+  result: EnsembleResult,
+  options?: EnsembleSummaryOptions
+): string {
+  const { maxMembers } = options ?? {};
+  const lines: string[] = [];
+
+  // Header
+  lines.push(`Ensemble: ${result.strategy}`);
+
+  const tierLabel = result.tier ? ` (${result.tier.name ?? result.tier.id})` : '';
+  lines.push(`Score:      ${result.totalScore}${tierLabel}`);
+  lines.push(`Confidence: ${result.confidence.toFixed(2)}`);
+  lines.push(`Agreement:  ${result.agreement.toFixed(2)}`);
+
+  // Members
+  const members = maxMembers != null
+    ? result.memberResults.slice(0, maxMembers)
+    : result.memberResults;
+
+  if (members.length > 0) {
+    lines.push('');
+    lines.push('Members:');
+    for (const m of members) {
+      const label = m.memberName ?? m.memberId;
+      const weightStr = m.weight.toFixed(2);
+      lines.push(`  [${weightStr}] ${label.padEnd(25)} → ${m.score} (confidence: ${m.confidence.toFixed(2)})`);
+    }
+
+    if (maxMembers != null && result.memberResults.length > maxMembers) {
+      const remaining = result.memberResults.length - maxMembers;
+      lines.push(`  ... and ${remaining} more`);
+    }
+  }
+
+  return lines.join('\n');
+}