@higher.archi/boe 1.0.21 → 1.0.22

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';

package/src/engines/ranking/strategy.ts

@@ -0,0 +1,333 @@
+/**
+ * Ranking Engine Strategy
+ *
+ * Core execution logic for all ranking strategies:
+ * - score: Delegates to ScoringEngine, ranks by totalScore
+ * - elo: Processes match history, computes Elo ratings
+ * - head-to-head: Pairwise comparison on weighted criteria
+ */
+
+import type { IWorkingMemory, Fact } from '../../core';
+import { ScoringEngine } from '../scoring/engine';
+import type { TierDefinition, ScoringTierMatch } from '../scoring/types';
+
+import type {
+  CompiledRankingRuleSet,
+  CompiledScoreRankingRuleSet,
+  CompiledEloRankingRuleSet,
+  CompiledHeadToHeadRankingRuleSet,
+  RankingOptions,
+  RankingResult,
+  RankedEntity,
+  RankingDirection,
+  Movement
+} from './types';
+import { resolvePercentileLabel, resolveMovement } from './types';
+
+export class RankingExecutor {
+  run<T extends TierDefinition = TierDefinition>(
+    ruleSet: CompiledRankingRuleSet<T>,
+    wm: IWorkingMemory,
+    options: RankingOptions = {}
+  ): RankingResult<T> {
+    const startTime = performance.now();
+
+    let rankings: RankedEntity<T>[];
+
+    switch (ruleSet.strategy) {
+      case 'score':
+        rankings = this.runScore(ruleSet as CompiledScoreRankingRuleSet<T>, wm, options);
+        break;
+      case 'elo':
+        rankings = this.runElo(ruleSet as unknown as CompiledEloRankingRuleSet, wm, options) as RankedEntity<T>[];
+        break;
+      case 'head-to-head':
+        rankings = this.runHeadToHead(ruleSet as unknown as CompiledHeadToHeadRankingRuleSet, wm, options) as RankedEntity<T>[];
+        break;
+      default:
+        throw new Error(`Unknown ranking strategy: '${(ruleSet as any).strategy}'`);
+    }
+
+    const executionTimeMs = Math.round((performance.now() - startTime) * 100) / 100;
+
+    return {
+      rankings,
+      totalEntities: rankings.length,
+      strategy: ruleSet.strategy,
+      executionTimeMs
+    };
+  }
+
+  // ========================================
+  // Score Strategy
+  // ========================================
+
+  private runScore<T extends TierDefinition>(
+    ruleSet: CompiledScoreRankingRuleSet<T>,
+    wm: IWorkingMemory,
+    options: RankingOptions
+  ): RankedEntity<T>[] {
+    const entityFacts = wm.getByType(ruleSet.entityType);
+    if (entityFacts.length === 0) return [];
+
+    // Collect context facts (everything that isn't the entity type)
+    const allFacts = wm.getAll();
+    const contextFacts = allFacts.filter(f => f.type !== ruleSet.entityType);
+
+    // Score each entity independently
+    const scored: { entityId: string; score: number }[] = [];
+    for (const entity of entityFacts) {
+      const engine = new ScoringEngine();
+
+      // Add context facts first
+      for (const ctx of contextFacts) {
+        engine.add({ type: ctx.type, data: ctx.data, id: ctx.id });
+      }
+
+      // Add this entity
+      engine.add({ type: entity.type, data: entity.data, id: entity.id });
+
+      const result = engine.execute(ruleSet.scoringRuleset, ruleSet.scoringOptions);
+      const entityId = resolveEntityId(entity);
+
+      scored.push({ entityId, score: result.totalScore });
+    }
+
+    // Sort by score
+    sortByScore(scored, ruleSet.config.direction);
+
+    // Build ranked entities
+    return this.buildRankedEntities(scored, entityFacts.length, options, ruleSet.config.tiers);
+  }
+
+  // ========================================
+  // Elo Strategy
+  // ========================================
+
+  private runElo(
+    ruleSet: CompiledEloRankingRuleSet,
+    wm: IWorkingMemory,
+    options: RankingOptions
+  ): RankedEntity[] {
+    const entityFacts = wm.getByType(ruleSet.entityType);
+    if (entityFacts.length === 0) return [];
+
+    const { initialRating, kFactor } = ruleSet.config;
+
+    // Initialize ratings
+    const ratings = new Map<string, number>();
+    for (const entity of entityFacts) {
+      ratings.set(resolveEntityId(entity), initialRating);
+    }
+
+    // Process match results in insertion order
+    const matches = wm.getByType(ruleSet.matchType);
+    for (const match of matches) {
+      const { winnerId, loserId, draw } = match.data;
+
+      const ratingA = ratings.get(winnerId);
+      const ratingB = ratings.get(loserId);
+
+      // Skip matches with unknown entities
+      if (ratingA === undefined || ratingB === undefined) continue;
+
+      // Expected scores
+      const expectedA = 1 / (1 + Math.pow(10, (ratingB - ratingA) / 400));
+      const expectedB = 1 - expectedA;
+
+      // Actual scores
+      const actualA = draw ? 0.5 : 1;
+      const actualB = draw ? 0.5 : 0;
+
+      // Update ratings
+      ratings.set(winnerId, ratingA + kFactor * (actualA - expectedA));
+      ratings.set(loserId, ratingB + kFactor * (actualB - expectedB));
+    }
+
+    // Convert to scored array
+    const scored: { entityId: string; score: number }[] = [];
+    for (const [entityId, rating] of ratings) {
+      scored.push({ entityId, score: Math.round(rating * 100) / 100 });
+    }
+
+    sortByScore(scored, ruleSet.config.direction);
+
+    return this.buildRankedEntities(scored, entityFacts.length, options);
+  }
+
+  // ========================================
+  // Head-to-Head Strategy
+  // ========================================
+
+  private runHeadToHead(
+    ruleSet: CompiledHeadToHeadRankingRuleSet,
+    wm: IWorkingMemory,
+    options: RankingOptions
+  ): RankedEntity[] {
+    const entityFacts = wm.getByType(ruleSet.entityType);
+    if (entityFacts.length === 0) return [];
+
+    const { criteria } = ruleSet;
+
+    // Extract criterion values per entity
+    const entities: { entityId: string; values: Record<string, number> }[] = [];
+    for (const entity of entityFacts) {
+      const values: Record<string, number> = {};
+      for (const c of criteria) {
+        values[c.id] = typeof entity.data[c.id] === 'number' ? entity.data[c.id] : 0;
+      }
+      entities.push({ entityId: resolveEntityId(entity), values });
+    }
+
+    // Round-robin pairwise comparison
+    const scores = new Map<string, number>();
+    for (const e of entities) {
+      scores.set(e.entityId, 0);
+    }
+
+    for (let i = 0; i < entities.length; i++) {
+      for (let j = i + 1; j < entities.length; j++) {
+        const a = entities[i];
+        const b = entities[j];
+
+        for (const c of criteria) {
+          const valA = a.values[c.id];
+          const valB = b.values[c.id];
+
+          const betterIsHigher = c.direction === 'highest-first';
+
+          if (valA === valB) {
+            // Tie: split the weight
+            scores.set(a.entityId, scores.get(a.entityId)! + c.weight / 2);
+            scores.set(b.entityId, scores.get(b.entityId)! + c.weight / 2);
+          } else if ((betterIsHigher && valA > valB) || (!betterIsHigher && valA < valB)) {
+            scores.set(a.entityId, scores.get(a.entityId)! + c.weight);
+          } else {
+            scores.set(b.entityId, scores.get(b.entityId)! + c.weight);
+          }
+        }
+      }
+    }
+
+    // Convert to scored array
+    const scored: { entityId: string; score: number }[] = [];
+    for (const [entityId, score] of scores) {
+      scored.push({ entityId, score: Math.round(score * 1000) / 1000 });
+    }
+
+    sortByScore(scored, ruleSet.config.direction);
+
+    return this.buildRankedEntities(scored, entityFacts.length, options);
+  }
+
+  // ========================================
+  // Shared Helpers
+  // ========================================
+
+  private buildRankedEntities<T extends TierDefinition>(
+    scored: { entityId: string; score: number }[],
+    totalEntities: number,
+    options: RankingOptions,
+    tiers?: T[]
+  ): RankedEntity<T>[] {
+    // Build previous ranking lookup
+    const previousMap = new Map<string, number>();
+    if (options.previousRankings) {
+      for (const prev of options.previousRankings) {
+        previousMap.set(prev.entityId, prev.rank);
+      }
+    }
+
+    // Prepare sorted tiers for matching
+    const sortedTiers = tiers
+      ? [...tiers].sort((a, b) => {
+          const ta = a.threshold === '-Infinity' ? Number.NEGATIVE_INFINITY : a.threshold as number;
+          const tb = b.threshold === '-Infinity' ? Number.NEGATIVE_INFINITY : b.threshold as number;
+          return tb - ta;
+        })
+      : undefined;
+
+    // Assign ranks (competition ranking: ties get same rank, next skips)
+    const rankings: RankedEntity<T>[] = [];
+    let currentRank = 1;
+
+    for (let i = 0; i < scored.length; i++) {
+      // If this entity has the same score as the previous, use the same rank
+      if (i > 0 && scored[i].score === scored[i - 1].score) {
+        // Same rank as previous
+      } else {
+        currentRank = i + 1;
+      }
+
+      const percentile = totalEntities <= 1
+        ? 100
+        : ((totalEntities - currentRank) / (totalEntities - 1)) * 100;
+
+      const percentileLabel = resolvePercentileLabel(percentile);
+
+      // Match tier
+      let tier: ScoringTierMatch<T> | undefined;
+      if (sortedTiers) {
+        for (const tierDef of sortedTiers) {
+          const threshold = tierDef.threshold === '-Infinity'
+            ? Number.NEGATIVE_INFINITY
+            : tierDef.threshold as number;
+          if (scored[i].score >= threshold) {
+            tier = { ...tierDef, threshold } as ScoringTierMatch<T>;
+            break;
+          }
+        }
+      }
+
+      // Movement
+      let movement: Movement | undefined;
+      let delta: number | undefined;
+      const previousRank = previousMap.get(scored[i].entityId);
+      if (previousRank !== undefined) {
+        movement = resolveMovement(previousRank, currentRank);
+        delta = previousRank - currentRank;  // positive = climbed
+      }
+
+      const entity: RankedEntity<T> = {
+        entityId: scored[i].entityId,
+        rank: currentRank,
+        score: scored[i].score,
+        percentile: Math.round(percentile * 100) / 100,
+        percentileLabel,
+        ...(tier !== undefined && { tier }),
+        ...(movement !== undefined && { movement }),
+        ...(delta !== undefined && { delta })
+      };
+
+      if (options.onRank) {
+        options.onRank(entity);
+      }
+
+      rankings.push(entity);
+    }
+
+    return rankings;
+  }
+}
+
+// ========================================
+// Module-Level Helpers
+// ========================================
+
+function resolveEntityId(fact: Fact): string {
+  return fact.data?.id ?? fact.id;
+}
+
+function sortByScore(
+  scored: { entityId: string; score: number }[],
+  direction: RankingDirection
+): void {
+  if (direction === 'highest-first') {
+    scored.sort((a, b) => b.score - a.score);
+  } else {
+    scored.sort((a, b) => a.score - b.score);
+  }
+}
+
+/** Singleton instance */
+export const rankingStrategy = new RankingExecutor();