@higher.archi/boe 1.0.20 → 1.0.22

package/src/engines/ensemble/members.ts

@@ -0,0 +1,156 @@
+/**
+ * Ensemble Member Adapter Factories
+ *
+ * Factory functions that wrap non-scoring engines (Bayesian, Fuzzy, etc.)
+ * into CustomMemberDef or ScoringMemberDef for use in ensemble rulesets.
+ */
+
+import type { FactInput } from '../../core';
+import type { ScoreExtractor, ConfidenceExtractor, CustomMemberDef, ScoringMemberDef } from './types';
+import type { CompiledBayesianRuleSet, BayesianOptions, BayesianResult } from '../bayesian';
+import type { CompiledFuzzyRuleSet, FuzzyOptions, FuzzyResult } from '../fuzzy';
+import type { CompiledMonteCarloRuleSet, MonteCarloOptions, MonteCarloResult } from '../monte-carlo';
+import type { CompiledExpertRuleSet, ExpertOptions, ExpertResult } from '../expert';
+import type { CompiledScoringRuleSet, ScoringOptions } from '../scoring/types';
+import { BayesianEngine } from '../bayesian';
+import { FuzzyEngine } from '../fuzzy';
+import { MonteCarloEngine } from '../monte-carlo';
+import { ExpertEngine } from '../expert';
+
+// ========================================
+// Config Types
+// ========================================
+
+export type BayesianMemberConfig = {
+  id: string;
+  name?: string;
+  weight: number;
+  ruleset: CompiledBayesianRuleSet;
+  extractScore: ScoreExtractor<BayesianResult>;
+  extractConfidence?: ConfidenceExtractor<BayesianResult>;
+  options?: BayesianOptions;
+};
+
+export type FuzzyMemberConfig = {
+  id: string;
+  name?: string;
+  weight: number;
+  ruleset: CompiledFuzzyRuleSet;
+  extractScore: ScoreExtractor<FuzzyResult>;
+  extractConfidence?: ConfidenceExtractor<FuzzyResult>;
+  options?: FuzzyOptions;
+};
+
+export type MonteCarloMemberConfig = {
+  id: string;
+  name?: string;
+  weight: number;
+  ruleset: CompiledMonteCarloRuleSet;
+  extractScore: ScoreExtractor<MonteCarloResult>;
+  extractConfidence?: ConfidenceExtractor<MonteCarloResult>;
+  options?: MonteCarloOptions;
+};
+
+export type ExpertMemberConfig = {
+  id: string;
+  name?: string;
+  weight: number;
+  ruleset: CompiledExpertRuleSet;
+  extractScore: ScoreExtractor<ExpertResult>;
+  extractConfidence?: ConfidenceExtractor<ExpertResult>;
+  options?: ExpertOptions;
+};
+
+export type ScoringMemberConfig = {
+  id: string;
+  name?: string;
+  weight: number;
+  ruleset: CompiledScoringRuleSet;
+  options?: ScoringOptions;
+};
+
+// ========================================
+// Factory Functions
+// ========================================
+
+/** Wrap a Bayesian engine as an ensemble member. Default confidence uses result.confidence. */
+export function bayesianMember(config: BayesianMemberConfig): CustomMemberDef {
+  const {
+    id, name, weight, ruleset, extractScore,
+    extractConfidence = (r: BayesianResult) => r.confidence,
+    options
+  } = config;
+  return {
+    id, name, weight,
+    execute: (facts: FactInput[]) => {
+      const engine = new BayesianEngine();
+      for (const f of facts) engine.add(f);
+      return engine.execute(ruleset, options);
+    },
+    extractScore,
+    extractConfidence
+  };
+}
+
+/** Wrap a Fuzzy engine as an ensemble member. Default confidence is 1.0 (outputs are crisp). */
+export function fuzzyMember(config: FuzzyMemberConfig): CustomMemberDef {
+  const {
+    id, name, weight, ruleset, extractScore,
+    extractConfidence = () => 1.0,
+    options
+  } = config;
+  return {
+    id, name, weight,
+    execute: (facts: FactInput[]) => {
+      const engine = new FuzzyEngine();
+      for (const f of facts) engine.add(f);
+      return engine.execute(ruleset, options);
+    },
+    extractScore,
+    extractConfidence
+  };
+}
+
+/** Wrap a Monte Carlo engine as an ensemble member. Default confidence is 1.0 (domain-specific). */
+export function monteCarloMember(config: MonteCarloMemberConfig): CustomMemberDef {
+  const {
+    id, name, weight, ruleset, extractScore,
+    extractConfidence = () => 1.0,
+    options
+  } = config;
+  return {
+    id, name, weight,
+    execute: (facts: FactInput[]) => {
+      const engine = new MonteCarloEngine();
+      for (const f of facts) engine.add(f);
+      return engine.execute(ruleset, options);
+    },
+    extractScore,
+    extractConfidence
+  };
+}
+
+/** Wrap an Expert engine as an ensemble member. Default confidence is 1.0 (per-conclusion only). */
+export function expertMember(config: ExpertMemberConfig): CustomMemberDef {
+  const {
+    id, name, weight, ruleset, extractScore,
+    extractConfidence = () => 1.0,
+    options
+  } = config;
+  return {
+    id, name, weight,
+    execute: (facts: FactInput[]) => {
+      const engine = new ExpertEngine();
+      for (const f of facts) engine.add(f);
+      return engine.execute(ruleset, options);
+    },
+    extractScore,
+    extractConfidence
+  };
+}
+
+/** Shorthand for creating a ScoringMemberDef. Consistency helper, no wrapping needed. */
+export function scoringMember(config: ScoringMemberConfig): ScoringMemberDef {
+  const { id, name, weight, ruleset, options } = config;
+  return { id, name, weight, ruleset, options };
+}

package/src/engines/ranking/compiler.ts

@@ -0,0 +1,194 @@
+/**
+ * Ranking Engine Compiler
+ *
+ * Validates ranking rulesets and resolves defaults.
+ */
+
+import { CompilationError } from '../../core/errors';
+import { SEMANTIC_PRIORITY_VALUES, isSemanticPriority, type SemanticPriority } from '../utility/types';
+
+import type { TierDefinition } from '../scoring/types';
+import type {
+  RankingRuleSet,
+  CompiledRankingRuleSet,
+  CompiledScoreRankingRuleSet,
+  CompiledEloRankingRuleSet,
+  CompiledHeadToHeadRankingRuleSet,
+  CompiledRankingCriterion,
+  KFactorPreset
+} from './types';
+import { K_FACTOR_VALUES, isKFactorPreset } from './types';
+
+/**
+ * Compile and validate a ranking ruleset.
+ */
+export function compileRankingRuleSet<T extends TierDefinition = TierDefinition>(
+  ruleSet: RankingRuleSet<T>
+): CompiledRankingRuleSet<T> {
+  if (!ruleSet.id) {
+    throw new CompilationError('Ranking ruleset requires an id');
+  }
+
+  if (ruleSet.mode !== 'ranking') {
+    throw new CompilationError(`Expected mode 'ranking', got '${ruleSet.mode}'`);
+  }
+
+  if (!ruleSet.entityType || ruleSet.entityType.trim() === '') {
+    throw new CompilationError('entityType is required and must be non-empty');
+  }
+
+  switch (ruleSet.strategy) {
+    case 'score':
+      return compileScore(ruleSet) as CompiledRankingRuleSet<T>;
+    case 'elo':
+      return compileElo(ruleSet as any) as CompiledRankingRuleSet<T>;
+    case 'head-to-head':
+      return compileHeadToHead(ruleSet as any) as CompiledRankingRuleSet<T>;
+    default:
+      throw new CompilationError(`Unknown ranking strategy: '${(ruleSet as any).strategy}'`);
+  }
+}
+
+function compileScore<T extends TierDefinition>(
+  ruleSet: RankingRuleSet<T> & { strategy: 'score' }
+): CompiledScoreRankingRuleSet<T> {
+  if (!ruleSet.scoringRuleset) {
+    throw new CompilationError('Score strategy requires a scoringRuleset');
+  }
+
+  if (ruleSet.scoringRuleset.mode !== 'scoring') {
+    throw new CompilationError(`scoringRuleset must have mode 'scoring', got '${ruleSet.scoringRuleset.mode}'`);
+  }
+
+  // Validate tier IDs are unique
+  const tiers = ruleSet.config?.tiers;
+  if (tiers) {
+    const tierIds = new Set<string>();
+    for (const tier of tiers) {
+      if (tierIds.has(tier.id)) {
+        throw new CompilationError(`Duplicate tier id: '${tier.id}'`);
+      }
+      tierIds.add(tier.id);
+    }
+  }
+
+  return {
+    id: ruleSet.id,
+    name: ruleSet.name,
+    mode: 'ranking',
+    strategy: 'score',
+    scoringRuleset: ruleSet.scoringRuleset,
+    scoringOptions: ruleSet.scoringOptions,
+    entityType: ruleSet.entityType,
+    config: {
+      direction: ruleSet.config?.direction ?? 'highest-first',
+      tiers: ruleSet.config?.tiers
+    }
+  };
+}
+
+function compileElo(
+  ruleSet: RankingRuleSet & { strategy: 'elo' }
+): CompiledEloRankingRuleSet {
+  const config = ruleSet.config ?? {};
+
+  // Resolve kFactor
+  let kFactor: number;
+  if (config.kFactor === undefined) {
+    kFactor = K_FACTOR_VALUES['standard'];
+  } else if (isKFactorPreset(config.kFactor)) {
+    kFactor = K_FACTOR_VALUES[config.kFactor as KFactorPreset];
+  } else if (typeof config.kFactor === 'number') {
+    if (config.kFactor <= 0) {
+      throw new CompilationError('kFactor must be a positive number');
+    }
+    kFactor = config.kFactor;
+  } else {
+    throw new CompilationError(`Invalid kFactor: '${config.kFactor}'`);
+  }
+
+  const initialRating = config.initialRating ?? 1500;
+  if (initialRating <= 0) {
+    throw new CompilationError('initialRating must be a positive number');
+  }
+
+  return {
+    id: ruleSet.id,
+    name: ruleSet.name,
+    mode: 'ranking',
+    strategy: 'elo',
+    entityType: ruleSet.entityType,
+    matchType: (ruleSet as any).matchType ?? 'MatchResult',
+    config: {
+      initialRating,
+      kFactor,
+      direction: config.direction ?? 'highest-first'
+    }
+  };
+}
+
+function compileHeadToHead(
+  ruleSet: RankingRuleSet & { strategy: 'head-to-head' }
+): CompiledHeadToHeadRankingRuleSet {
+  const criteria = (ruleSet as any).criteria;
+
+  if (!criteria || !Array.isArray(criteria) || criteria.length === 0) {
+    throw new CompilationError('Head-to-head strategy requires at least one criterion');
+  }
+
+  // Validate no duplicate criterion IDs
+  const criterionIds = new Set<string>();
+  for (const c of criteria) {
+    if (!c.id) {
+      throw new CompilationError('Each criterion requires an id');
+    }
+    if (criterionIds.has(c.id)) {
+      throw new CompilationError(`Duplicate criterion id: '${c.id}'`);
+    }
+    criterionIds.add(c.id);
+  }
+
+  // Resolve semantic weights to numeric
+  const resolvedCriteria: CompiledRankingCriterion[] = criteria.map((c: any) => {
+    let weight: number;
+    if (isSemanticPriority(c.weight)) {
+      weight = SEMANTIC_PRIORITY_VALUES[c.weight as SemanticPriority];
+    } else if (typeof c.weight === 'number') {
+      weight = c.weight;
+    } else {
+      throw new CompilationError(`Invalid weight for criterion '${c.id}': '${c.weight}'`);
+    }
+
+    if (!c.direction) {
+      throw new CompilationError(`Criterion '${c.id}' requires a direction`);
+    }
+
+    return {
+      id: c.id,
+      name: c.name,
+      weight,
+      direction: c.direction
+    };
+  });
+
+  // Normalize weights to sum to 1.0
+  const totalWeight = resolvedCriteria.reduce((sum, c) => sum + c.weight, 0);
+  if (totalWeight === 0) {
+    throw new CompilationError('Criteria weights must not all be zero');
+  }
+  for (const c of resolvedCriteria) {
+    c.weight = c.weight / totalWeight;
+  }
+
+  return {
+    id: ruleSet.id,
+    name: ruleSet.name,
+    mode: 'ranking',
+    strategy: 'head-to-head',
+    entityType: ruleSet.entityType,
+    criteria: resolvedCriteria,
+    config: {
+      direction: (ruleSet as any).config?.direction ?? 'highest-first'
+    }
+  };
+}

package/src/engines/ranking/engine.ts

@@ -0,0 +1,120 @@
+/**
+ * Ranking Engine
+ *
+ * Comparative scoring engine that ranks N entities relative to each other.
+ * Supports score-based ranking, Elo ratings, and head-to-head comparison.
+ *
+ * @example
+ * ```typescript
+ * const engine = new RankingEngine();
+ * engine.add({ type: 'Vendor', data: { id: 'v1', revenue: 500000 } });
+ * engine.add({ type: 'Vendor', data: { id: 'v2', revenue: 120000 } });
+ *
+ * const result = engine.execute(compiledRanking);
+ * console.log(result.rankings[0]); // { rank: 1, entityId: 'v1', percentileLabel: 'top-1%', ... }
+ * ```
+ */
+
+import {
+  WorkingMemory,
+  Fact,
+  FactInput,
+  FactChange
+} from '../../core';
+
+import type { TierDefinition } from '../scoring/types';
+
+import type {
+  CompiledRankingRuleSet,
+  RankingOptions,
+  RankingResult
+} from './types';
+
+import { RankingExecutor } from './strategy';
+
+export class RankingEngine {
+  private wm: WorkingMemory;
+  private strategy: RankingExecutor;
+
+  constructor(workingMemory?: WorkingMemory) {
+    this.wm = workingMemory ?? new WorkingMemory();
+    this.strategy = new RankingExecutor();
+  }
+
+  // ========================================
+  // 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 a ranking ruleset.
+   *
+   * Scores all entities of the configured type and produces
+   * a ranked list with percentiles and optional tier/movement tracking.
+   *
+   * @param ruleSet - Compiled ranking ruleset
+   * @param options - Runtime options (previousRankings for movement, onRank callback)
+   * @returns Ranking result with sorted entities
+   */
+  execute<T extends TierDefinition = TierDefinition>(
+    ruleSet: CompiledRankingRuleSet<T>,
+    options: RankingOptions = {}
+  ): RankingResult<T> {
+    return this.strategy.run(ruleSet, this.wm, options);
+  }
+
+  // ========================================
+  // Utility Methods
+  // ========================================
+
+  getWorkingMemory(): WorkingMemory {
+    return this.wm;
+  }
+}

package/src/engines/ranking/index.ts

@@ -0,0 +1,46 @@
+/**
+ * Ranking Engine — Comparative Entity Ranking
+ */
+
+// Types
+export type {
+  RankingStrategy,
+  RankingDirection,
+  PercentileLabel,
+  Movement,
+  KFactorPreset,
+  RankingCriterion,
+  CompiledRankingCriterion,
+  ScoreRankingConfig,
+  EloConfig,
+  HeadToHeadConfig,
+  ScoreRankingRuleSet,
+  EloRankingRuleSet,
+  HeadToHeadRankingRuleSet,
+  RankingRuleSet,
+  CompiledScoreRankingRuleSet,
+  CompiledEloRankingRuleSet,
+  CompiledHeadToHeadRankingRuleSet,
+  CompiledRankingRuleSet,
+  PreviousRanking,
+  RankingOptions,
+  RankedEntity,
+  RankingResult
+} from './types';
+
+// Constants & utilities
+export {
+  K_FACTOR_VALUES,
+  isKFactorPreset,
+  resolvePercentileLabel,
+  resolveMovement
+} from './types';
+
+// Compiler
+export { compileRankingRuleSet } from './compiler';
+
+// Strategy
+export { RankingExecutor, rankingStrategy } from './strategy';
+
+// Engine
+export { RankingEngine } from './engine';