@higher.archi/boe 1.0.0

package/src/engines/scoring/compiler.ts

@@ -0,0 +1,139 @@
+/**
+ * Scoring Engine Compiler
+ */
+
+import {
+  compileCondition,
+  normalizeShape,
+  Condition
+} from '../../core';
+
+import {
+  ScoringRule,
+  ScoringRuleSet,
+  ScoringConfig,
+  CompiledScoringRule,
+  CompiledScoringRuleSet,
+  CompiledScoringAction
+} from './types';
+
+// ========================================
+// 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)
+  };
+}
+
+// ========================================
+// Parameter 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;
+}
+
+// ========================================
+// Rule Compilation
+// ========================================
+
+function compileScoringAction(action: any): CompiledScoringAction {
+  const { score, weight, normalize, reason } = action;
+
+  // Handle expression scores
+  if (Array.isArray(score)) {
+    return {
+      mode: 'scoring',
+      score: compileCondition(score as Condition),
+      weight,
+      normalize,
+      reason
+    };
+  }
+
+  // Static or function name score
+  return {
+    mode: 'scoring',
+    score,
+    weight,
+    normalize,
+    reason
+  };
+}
+
+export function compileScoringRule(rule: ScoringRule, index: number = 0): CompiledScoringRule {
+  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: compileScoringAction(rule.then)
+  };
+}
+
+// ========================================
+// RuleSet Compilation
+// ========================================
+
+export function compileScoringRuleSet(ruleSet: ScoringRuleSet): CompiledScoringRuleSet {
+  const config: ScoringConfig = {
+    mode: 'scoring',
+    strategies: ruleSet.config?.strategies ?? ['raw'],
+    caps: ruleSet.config?.caps,
+    outputBounds: ruleSet.config?.outputBounds,
+    baseScore: ruleSet.config?.baseScore,
+    tiers: ruleSet.config?.tiers
+  };
+
+  return {
+    id: ruleSet.id,
+    name: ruleSet.name,
+    mode: 'scoring',
+    schema: ruleSet.shape ? normalizeShape(ruleSet.shape) : { type: 'object' },
+    rules: ruleSet.rules.map((rule, index) => compileScoringRule(rule, index)),
+    config
+  };
+}

package/src/engines/scoring/engine.ts

@@ -0,0 +1,121 @@
+/**
+ * Scoring Engine
+ *
+ * Self-contained engine for scoring-based rule execution.
+ * Implements IRuleEngine with strongly-typed ruleset, options, and result.
+ */
+
+import {
+  IRuleEngine,
+  WorkingMemory,
+  Fact,
+  FactInput,
+  FactChange
+} from '../../core';
+
+import {
+  CompiledScoringRuleSet,
+  ScoringOptions,
+  ScoringResult
+} from './types';
+
+import { ScoringStrategy } from './strategy';
+
+/**
+ * Scoring rule engine.
+ *
+ * Evaluates all matching rules and accumulates their scores into a total.
+ * Supports normalization, weighting, and output bounds.
+ *
+ * @example
+ * ```typescript
+ * const engine = new ScoringEngine();
+ * engine.add({ type: 'Applicant', data: { income: 75000, creditScore: 720 } });
+ *
+ * const result = engine.execute(compiledRules);
+ * console.log(`Total score: ${result.totalScore}`);
+ * ```
+ */
+export class ScoringEngine implements IRuleEngine<CompiledScoringRuleSet, ScoringOptions, ScoringResult> {
+  private wm: WorkingMemory;
+  private strategy: ScoringStrategy;
+
+  constructor(workingMemory?: WorkingMemory) {
+    this.wm = workingMemory ?? new WorkingMemory();
+    this.strategy = new ScoringStrategy();
+  }
+
+  // ========================================
+  // IWorkingMemory Implementation
+  // ========================================
+
+  add(input: FactInput): Fact {
+    return this.wm.add(input);
+  }
+
+  remove(factId: string): Fact | undefined {
+    return this.wm.remove(factId);
+  }
+
+  update(input: FactInput): Fact {
+    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();
+  }
+
+  // ========================================
+  // IRuleEngine Implementation
+  // ========================================
+
+  /**
+   * Execute a scoring ruleset.
+   *
+   * All matching rules contribute their scores to the total.
+   * Scores can be normalized, weighted, and scaled to output bounds.
+   *
+   * @param ruleSet - Compiled scoring ruleset
+   * @param options - Runtime options (score functions, callbacks)
+   * @returns Result with total score and per-rule contributions
+   */
+  execute(ruleSet: CompiledScoringRuleSet, options: ScoringOptions = {}): ScoringResult {
+    return this.strategy.run(ruleSet, this.wm, options);
+  }
+
+  // ========================================
+  // Utility Methods
+  // ========================================
+
+  getWorkingMemory(): WorkingMemory {
+    return this.wm;
+  }
+}

package/src/engines/scoring/index.ts

@@ -0,0 +1,46 @@
+/**
+ * Scoring Engine
+ *
+ * Provides scoring-based rule execution where rules contribute
+ * scores that are accumulated into a total score.
+ */
+
+// Types
+export {
+  // Scoring methods
+  ScoringMethod,
+  ScoringCaps,
+  OutputBounds,
+  // Tier types
+  TierDefinition,
+  ScoringTierMatch,
+  // Source types
+  ScoringAction,
+  ScoringRule,
+  ScoringRuleSet,
+  ScoringConfig,
+  // Compiled types
+  CompiledScoringAction,
+  CompiledScoringRule,
+  CompiledScoringRuleSet,
+  // Runtime types
+  ScoreFunction,
+  ScoreFunctionRegistry,
+  ScoringOptions,
+  ScoringResult
+} from './types';
+
+// Compiler
+export {
+  compileScoringRule,
+  compileScoringRuleSet
+} from './compiler';
+
+// Strategy
+export {
+  ScoringStrategy,
+  scoringStrategy
+} from './strategy';
+
+// Engine
+export { ScoringEngine } from './engine';

package/src/engines/scoring/strategy.ts

@@ -0,0 +1,190 @@
+/**
+ * Scoring Engine Strategy
+ *
+ * Evaluates facts against scoring rules and produces a total score
+ * with individual rule contributions.
+ */
+
+import {
+  match,
+  evaluateCondition
+} from '../../core';
+import { IWorkingMemory } from '../../core/memory';
+
+import {
+  CompiledScoringRuleSet,
+  CompiledScoringAction,
+  ScoringOptions,
+  ScoringResult,
+  ScoringTierMatch
+} from './types';
+
+export class ScoringStrategy {
+  run(
+    ruleSet: CompiledScoringRuleSet,
+    wm: IWorkingMemory,
+    options: ScoringOptions = {}
+  ): ScoringResult {
+    const startTime = performance.now();
+    const { scoreFunctions = {}, onFire } = options;
+    const config = ruleSet.config;
+    const strategies = config.strategies ?? ['raw'];
+
+    const contributions: Record<string, number> = {};
+    const weights: Record<string, number> = {};
+    const fired: string[] = [];
+    const rawScores: Record<string, number[]> = {}; // Track raw scores for adaptive
+
+    // Phase 1: Calculate base scores
+    for (const rule of ruleSet.rules) {
+      const activations = match(rule, wm);
+
+      for (const activation of activations) {
+        const ruleAction = rule.action as CompiledScoringAction;
+        let baseScore: number;
+
+        // Determine base score value
+        if (typeof ruleAction.score === 'number') {
+          baseScore = ruleAction.score;
+        } else if (typeof ruleAction.score === 'string') {
+          const scoreFunc = scoreFunctions[ruleAction.score];
+          if (!scoreFunc) {
+            throw new Error(`Score function not found: ${ruleAction.score}`);
+          }
+          baseScore = scoreFunc(activation.facts);
+        } else if (typeof ruleAction.score === 'object' && 'op' in ruleAction.score) {
+          const result = evaluateCondition(ruleAction.score as any, activation.facts);
+          baseScore = typeof result === 'number' ? result : 0;
+        } else {
+          throw new Error(`Invalid score type: ${typeof ruleAction.score}`);
+        }
+
+        // Store raw scores for adaptive strategy
+        if (!rawScores[rule.id]) {
+          rawScores[rule.id] = [];
+        }
+        rawScores[rule.id].push(baseScore);
+
+        // Store weight for later
+        const weight = ruleAction.weight ?? 1;
+        weights[rule.id] = weight;
+
+        if (!fired.includes(rule.id)) {
+          fired.push(rule.id);
+        }
+      }
+    }
+
+    // Phase 2: Normalize and accumulate
+    for (const rule of ruleSet.rules) {
+      const ruleAction = rule.action as CompiledScoringAction;
+      const ruleRawScores = rawScores[rule.id] || [];
+      let accumulatedScore = 0;
+
+      for (const baseScore of ruleRawScores) {
+        let processedScore = baseScore;
+
+        // Apply normalization strategies
+        if (strategies.includes('normalized') && ruleAction.normalize) {
+          const { min, max } = ruleAction.normalize;
+          processedScore = (processedScore - min) / (max - min);
+          processedScore = Math.max(0, Math.min(1, processedScore)); // Clamp to 0-1
+        } else if (strategies.includes('adaptive')) {
+          // Adaptive: use provided bounds or auto-detect
+          if (ruleAction.normalize) {
+            // Use explicit bounds
+            const { min, max } = ruleAction.normalize;
+            processedScore = (processedScore - min) / (max - min);
+            processedScore = Math.max(0, Math.min(1, processedScore));
+          } else {
+            // Auto-detect from observed max
+            const maxObserved = Math.max(...ruleRawScores);
+            if (maxObserved > 0) {
+              processedScore = baseScore / maxObserved;
+            }
+          }
+        }
+
+        // Apply capping strategy
+        if (strategies.includes('capped')) {
+          const cap = config.caps?.[rule.id];
+          if (cap !== undefined) {
+            processedScore = Math.min(processedScore, cap);
+          }
+        }
+
+        accumulatedScore += processedScore;
+      }
+
+      contributions[rule.id] = accumulatedScore;
+    }
+
+    // Phase 3: Apply global strategies (weighted-percent)
+    if (strategies.includes('weighted-percent')) {
+      const totalWeight = Object.values(weights).reduce((sum, w) => sum + w, 0);
+      if (totalWeight > 0) {
+        for (const ruleId in contributions) {
+          const normalizedWeight = weights[ruleId] / totalWeight;
+          contributions[ruleId] = contributions[ruleId] * normalizedWeight;
+        }
+      }
+    } else {
+      // Apply weights normally
+      for (const ruleId in contributions) {
+        contributions[ruleId] = contributions[ruleId] * (weights[ruleId] ?? 1);
+      }
+    }
+
+    // Fire callbacks with final weighted scores
+    if (onFire) {
+      for (const ruleId of fired) {
+        const finalScore = contributions[ruleId];
+        onFire(ruleId, {} as any, finalScore);
+      }
+    }
+
+    // Calculate total score (base score + contributions)
+    const baseScore = config.baseScore ?? 0;
+    const totalScore = baseScore + Object.values(contributions).reduce((sum, score) => sum + score, 0);
+
+    // Match tier if tiers are configured
+    let tier: ScoringTierMatch | undefined;
+    if (config.tiers && config.tiers.length > 0) {
+      // Helper to resolve threshold value (handles '-Infinity' string)
+      const resolveThreshold = (t: number | '-Infinity'): number =>
+        t === '-Infinity' ? Number.NEGATIVE_INFINITY : t;
+
+      // Sort tiers by threshold descending (highest first)
+      const sortedTiers = [...config.tiers].sort(
+        (a, b) => resolveThreshold(b.threshold) - resolveThreshold(a.threshold)
+      );
+
+      for (const tierDef of sortedTiers) {
+        const threshold = resolveThreshold(tierDef.threshold);
+        if (totalScore >= threshold) {
+          tier = {
+            id: tierDef.id,
+            name: tierDef.name,
+            description: tierDef.description,
+            threshold
+          };
+          break;
+        }
+      }
+    }
+
+    const executionTimeMs = Math.round((performance.now() - startTime) * 100) / 100;
+
+    return {
+      totalScore,
+      contributions,
+      fired,
+      iterations: 1,
+      tier,
+      executionTimeMs
+    };
+  }
+}
+
+// Export a singleton instance for convenience
+export const scoringStrategy = new ScoringStrategy();

package/src/engines/scoring/types.ts

@@ -0,0 +1,201 @@
+/**
+ * Scoring Engine Types
+ */
+
+import {
+  BaseRule,
+  BaseRuleSet,
+  CompiledBaseRule,
+  CompiledBaseRuleSet,
+  CompiledCondition,
+  Expression,
+  BindingContext
+} from '../../core';
+
+// ========================================
+// Scoring Method Types
+// ========================================
+
+/**
+ * Scoring methods control how scores are normalized and combined
+ *
+ * Methods are applied in sequence:
+ * - Per-rule methods (normalized, capped, adaptive): Applied to each rule's score
+ * - Global methods (weighted-percent): Applied across all rules
+ */
+export type ScoringMethod =
+  | 'raw'              // No normalization (pass-through)
+  | 'normalized'       // Normalize scores to 0-1 range using min/max bounds (strict - requires normalize field)
+  | 'adaptive'         // Smart normalization: use provided bounds or auto-detect from observed max
+  | 'weighted-percent' // Auto-normalize weights to sum to 1.0
+  | 'capped';          // Apply max caps to rule contributions
+
+/**
+ * Max contribution caps for each rule
+ * Maps ruleId -> max score to prevent any single rule from dominating
+ */
+export type ScoringCaps = {
+  [ruleId: string]: number;
+};
+
+/**
+ * Output bounds for scaling final score to a target range
+ *
+ * Common presets:
+ * - 'percentage': 0-100 (e.g., 75%)
+ * - 'points': 0-1000 (e.g., 750 points)
+ * - 'rating': 0-10 (e.g., 7.5/10)
+ * - 'stars': 0-5 (e.g., 3.75/5 stars)
+ * - 'normalized': 0-1 (e.g., 0.75 - same as no outputBounds)
+ *
+ * Or specify custom range:
+ * - { min: 300, max: 850 } (e.g., FICO score)
+ */
+export type OutputBounds =
+  | { min: number; max: number }  // Custom range
+  | 'percentage'                   // 0-100
+  | 'points'                      // 0-1000
+  | 'rating'                      // 0-10
+  | 'stars'                       // 0-5
+  | 'normalized';                 // 0-1 (explicit)
+
+/**
+ * Tier definition for classifying scores into categories
+ *
+ * Tiers are matched in descending threshold order - the first tier
+ * where totalScore >= threshold is selected.
+ *
+ * Use '-Infinity' (string) for a catch-all tier that matches any score.
+ *
+ * @example
+ * ```typescript
+ * const tiers: TierDefinition[] = [
+ *   { id: 'preferred', name: 'Preferred', threshold: 80, description: 'Best rates' },
+ *   { id: 'standard', name: 'Standard', threshold: 60, description: 'Normal rates' },
+ *   { id: 'high-risk', name: 'High Risk', threshold: '-Infinity', description: 'Catch-all' }
+ * ];
+ * ```
+ */
+export type TierDefinition = {
+  id: string;                      // Unique identifier (e.g., 'preferred', 'standard')
+  name?: string;                   // Display name (e.g., 'Preferred Tier')
+  description?: string;            // Description (e.g., 'Excellent risk profile')
+  threshold: number | '-Infinity'; // Minimum score to qualify (inclusive), or '-Infinity' for catch-all
+};
+
+/**
+ * Matched tier in scoring result
+ */
+export type ScoringTierMatch = {
+  id: string;
+  name?: string;
+  description?: string;
+  threshold: number;
+};
+
+// ========================================
+// Source Types (User-Defined)
+// ========================================
+
+/**
+ * Scoring action - contributes a score when rule matches
+ */
+export type ScoringAction = {
+  score: number | string | Expression;  // number = static, string = function name, Expression = calculated
+  weight?: number;  // Optional weight multiplier (defaults to 1)
+  normalize?: { min: number; max: number };  // Optional normalization bounds
+  reason?: string;  // Optional human-readable explanation for the score
+};
+
+/**
+ * Scoring rule - uses 'then' for scoring properties
+ */
+export type ScoringRule = BaseRule & {
+  then: ScoringAction;
+};
+
+/**
+ * Scoring ruleset
+ */
+export type ScoringRuleSet = BaseRuleSet & {
+  mode: 'scoring';
+  rules: ScoringRule[];
+  config?: Partial<ScoringConfig>;
+};
+
+/**
+ * Scoring configuration
+ */
+export type ScoringConfig = {
+  mode: 'scoring';
+  strategies: ScoringMethod[];  // Default: ['raw'] - methods applied in sequence
+  caps?: ScoringCaps;            // Optional global caps (used with 'capped' method)
+  outputBounds?: OutputBounds;   // Optional output scaling
+  baseScore?: number;            // Starting score before rule contributions (default: 0)
+  tiers?: TierDefinition[];      // Optional tier definitions for score classification
+};
+
+// ========================================
+// Compiled Types
+// ========================================
+
+/**
+ * Compiled scoring action
+ */
+export type CompiledScoringAction = {
+  mode: 'scoring';
+  score: number | string | CompiledCondition;  // Expression becomes CompiledCondition
+  weight?: number;
+  normalize?: { min: number; max: number };
+  reason?: string;  // Preserved from source for reporting
+};
+
+/**
+ * Compiled scoring rule
+ */
+export type CompiledScoringRule = CompiledBaseRule & {
+  action: CompiledScoringAction;
+};
+
+/**
+ * Compiled scoring ruleset
+ */
+export type CompiledScoringRuleSet = CompiledBaseRuleSet & {
+  mode: 'scoring';
+  rules: CompiledScoringRule[];
+  config: ScoringConfig;
+};
+
+// ========================================
+// Runtime Types
+// ========================================
+
+/**
+ * Score function for dynamic scoring
+ */
+export type ScoreFunction = (context: BindingContext) => number;
+
+/**
+ * Registry of score functions
+ */
+export type ScoreFunctionRegistry = Record<string, ScoreFunction>;
+
+/**
+ * Runtime options for scoring execution
+ */
+export type ScoringOptions = {
+  scoreFunctions?: ScoreFunctionRegistry;  // Optional dynamic score functions
+  onFire?: (ruleId: string, context: BindingContext, score: number) => void;
+};
+
+/**
+ * Execution result
+ */
+export type ScoringResult = {
+  totalScore: number;
+  contributions: Record<string, number>;  // Which rules contributed what scores
+  fired: string[];  // Rules that matched and contributed
+  iterations: 1;  // Scoring is always one-pass
+  tier?: ScoringTierMatch;  // Matched tier (if tiers configured)
+  executionTimeMs: number;  // Processing time in milliseconds
+};