@higher.archi/boe 1.0.0

package/src/engines/utility/strategy.ts

@@ -0,0 +1,315 @@
+/**
+ * Utility/MCDM Engine Strategy
+ *
+ * Compares alternatives across weighted criteria using Multi-Criteria
+ * Decision Making (MCDM) methodology.
+ *
+ * Algorithm:
+ * 1. Identify all alternatives in working memory (by type)
+ * 2. For each alternative, evaluate all criterion rules to get raw scores
+ * 3. Normalize scores across alternatives (min-max or z-score)
+ * 4. Apply direction (flip scores for 'minimize' criteria)
+ * 5. Aggregate weighted scores per alternative
+ * 6. Rank alternatives by utility score
+ */
+
+import {
+  evaluateCondition
+} from '../../core';
+import { IWorkingMemory } from '../../core/memory';
+import { Fact } from '../../core/types/fact';
+
+import {
+  CompiledUtilityRuleSet,
+  CompiledUtilityCriterion,
+  UtilityOptions,
+  UtilityResult,
+  AlternativeResult,
+  SensitivityInfo
+} from './types';
+
+export class UtilityStrategy {
+  run(
+    ruleSet: CompiledUtilityRuleSet,
+    wm: IWorkingMemory,
+    alternativeType: string,
+    options: UtilityOptions = {}
+  ): UtilityResult {
+    const startTime = performance.now();
+    const { onEvaluate, onScore, computeSensitivity = false } = options;
+    const config = ruleSet.config;
+    const criteria = ruleSet.criteria;
+
+    // Get all alternatives of the specified type
+    const alternatives = wm.getByType(alternativeType);
+
+    if (alternatives.length === 0) {
+      const executionTimeMs = Math.round((performance.now() - startTime) * 100) / 100;
+      return {
+        alternatives: [],
+        ranking: [],
+        winner: null,
+        executionTimeMs
+      };
+    }
+
+    // Phase 1: Compute raw scores for each alternative-criterion pair
+    const rawScores: Map<string, Record<string, number>> = new Map();
+
+    for (const alt of alternatives) {
+      const altId = alt.id;
+      const scores: Record<string, number> = {};
+
+      for (const criterion of criteria) {
+        // Find rules that compute this criterion
+        const criterionRules = ruleSet.rules.filter(r => r.criterion === criterion.id);
+
+        for (const rule of criterionRules) {
+          // Create a temporary working memory with just this alternative
+          // to match against the rule
+          const activations = this.matchAlternative(rule, alt, wm);
+
+          for (const activation of activations) {
+            // Evaluate the compute expression
+            const result = evaluateCondition(rule.compute as any, activation.facts);
+            const value = typeof result === 'number' ? result : 0;
+
+            // Store the score (last one wins if multiple rules match)
+            scores[criterion.id] = value;
+
+            if (onEvaluate) {
+              onEvaluate(altId, criterion.id, value);
+            }
+          }
+        }
+
+        // Default to 0 if no rule matched
+        if (scores[criterion.id] === undefined) {
+          scores[criterion.id] = 0;
+        }
+      }
+
+      rawScores.set(altId, scores);
+    }
+
+    // Phase 2: Normalize scores across alternatives
+    const normalizedScores: Map<string, Record<string, number>> = new Map();
+
+    for (const criterion of criteria) {
+      const allValues = alternatives.map(alt => rawScores.get(alt.id)![criterion.id]);
+
+      if (config.normalization === 'min-max') {
+        const min = Math.min(...allValues);
+        const max = Math.max(...allValues);
+        const range = max - min;
+
+        for (const alt of alternatives) {
+          if (!normalizedScores.has(alt.id)) {
+            normalizedScores.set(alt.id, {});
+          }
+
+          const raw = rawScores.get(alt.id)![criterion.id];
+          let normalized = range > 0 ? (raw - min) / range : 0.5;
+
+          // Flip for minimize criteria (lower raw = higher normalized)
+          if (criterion.direction === 'minimize') {
+            normalized = 1 - normalized;
+          }
+
+          normalizedScores.get(alt.id)![criterion.id] = normalized;
+        }
+      } else if (config.normalization === 'z-score') {
+        const mean = allValues.reduce((a, b) => a + b, 0) / allValues.length;
+        const variance = allValues.reduce((sum, v) => sum + Math.pow(v - mean, 2), 0) / allValues.length;
+        const stdDev = Math.sqrt(variance);
+
+        for (const alt of alternatives) {
+          if (!normalizedScores.has(alt.id)) {
+            normalizedScores.set(alt.id, {});
+          }
+
+          const raw = rawScores.get(alt.id)![criterion.id];
+          let normalized = stdDev > 0 ? (raw - mean) / stdDev : 0;
+
+          // Convert z-score to 0-1 range (approximately)
+          // Using sigmoid-like transformation
+          normalized = 1 / (1 + Math.exp(-normalized));
+
+          // Flip for minimize criteria
+          if (criterion.direction === 'minimize') {
+            normalized = 1 - normalized;
+          }
+
+          normalizedScores.get(alt.id)![criterion.id] = normalized;
+        }
+      } else {
+        // No normalization - just copy raw scores (and flip for minimize)
+        for (const alt of alternatives) {
+          if (!normalizedScores.has(alt.id)) {
+            normalizedScores.set(alt.id, {});
+          }
+
+          let value = rawScores.get(alt.id)![criterion.id];
+
+          if (criterion.direction === 'minimize') {
+            // For no normalization with minimize, invert the value
+            value = value !== 0 ? 1 / value : Infinity;
+          }
+
+          normalizedScores.get(alt.id)![criterion.id] = value;
+        }
+      }
+    }
+
+    // Phase 3: Compute weighted scores and aggregate
+    const results: AlternativeResult[] = [];
+
+    for (const alt of alternatives) {
+      const normalized = normalizedScores.get(alt.id)!;
+      const weighted: Record<string, number> = {};
+      let utilityScore: number;
+
+      if (config.aggregation === 'weighted-sum') {
+        utilityScore = 0;
+        for (const criterion of criteria) {
+          const weightedValue = normalized[criterion.id] * criterion.weight;
+          weighted[criterion.id] = weightedValue;
+          utilityScore += weightedValue;
+        }
+      } else {
+        // weighted-product
+        utilityScore = 1;
+        for (const criterion of criteria) {
+          const weightedValue = Math.pow(normalized[criterion.id], criterion.weight);
+          weighted[criterion.id] = weightedValue;
+          utilityScore *= weightedValue;
+        }
+      }
+
+      const result: AlternativeResult = {
+        id: alt.id,
+        name: alt.data.name || alt.id,
+        rawScores: rawScores.get(alt.id)!,
+        normalizedScores: normalized,
+        weightedScores: weighted,
+        utilityScore
+      };
+
+      results.push(result);
+
+      if (onScore) {
+        onScore(result);
+      }
+    }
+
+    // Phase 4: Rank by utility score (descending)
+    const ranking = [...results].sort((a, b) => b.utilityScore - a.utilityScore);
+    const winner = ranking.length > 0 ? ranking[0] : null;
+
+    // Phase 5: Sensitivity analysis (optional)
+    let sensitivity: Record<string, SensitivityInfo> | undefined;
+
+    if (computeSensitivity && winner && ranking.length > 1) {
+      sensitivity = this.computeSensitivity(ranking, criteria);
+    }
+
+    const executionTimeMs = Math.round((performance.now() - startTime) * 100) / 100;
+
+    return {
+      alternatives: results,
+      ranking,
+      winner,
+      sensitivity,
+      executionTimeMs
+    };
+  }
+
+  /**
+   * Match a rule against a single alternative fact
+   */
+  private matchAlternative(rule: any, alternative: Fact, wm: IWorkingMemory): Array<{ facts: Record<string, any> }> {
+    // Simple matching: if the rule's first input type matches the alternative type
+    const firstInput = rule.inputs[0];
+    if (!firstInput) return [];
+
+    if (firstInput.type !== alternative.type) {
+      return [];
+    }
+
+    // Build bindings with fact-like objects (condition evaluator expects { data: ... })
+    const bindings: Record<string, any> = {
+      [firstInput.name]: { data: alternative.data }
+    };
+
+    // Handle additional inputs (join with other facts in working memory)
+    for (let i = 1; i < rule.inputs.length; i++) {
+      const input = rule.inputs[i];
+      const facts = wm.getByType(input.type);
+
+      if (facts.length === 0) {
+        return []; // Required input type not found
+      }
+
+      // For simplicity, take the first matching fact
+      // A more sophisticated implementation would handle all combinations
+      const fact = facts[0];
+      bindings[input.name] = { data: fact.data };
+    }
+
+    // Check when condition
+    if (rule.when) {
+      const result = evaluateCondition(rule.when, bindings);
+      if (!result) {
+        return [];
+      }
+    }
+
+    return [{ facts: bindings }];
+  }
+
+  /**
+   * Compute sensitivity analysis: how much would weights need to change
+   * for the ranking to change?
+   */
+  private computeSensitivity(
+    ranking: AlternativeResult[],
+    criteria: CompiledUtilityCriterion[]
+  ): Record<string, SensitivityInfo> {
+    const winner = ranking[0];
+    const runnerUp = ranking[1];
+    const sensitivity: Record<string, SensitivityInfo> = {};
+
+    for (const criterion of criteria) {
+      const info: SensitivityInfo = {
+        currentTop: winner.name
+      };
+
+      // Calculate the weight change needed to flip the ranking
+      const winnerNorm = winner.normalizedScores[criterion.id];
+      const runnerNorm = runnerUp.normalizedScores[criterion.id];
+
+      // Only interesting if runner-up scores better on this criterion
+      if (runnerNorm > winnerNorm) {
+        // Simplified sensitivity: would need significant weight increase
+        // to flip (actual calculation is more complex)
+        const gap = winner.utilityScore - runnerUp.utilityScore;
+        const scoreDiff = runnerNorm - winnerNorm;
+
+        if (scoreDiff > 0) {
+          const weightNeeded = gap / scoreDiff + criterion.weight;
+          if (weightNeeded <= 1) {
+            info.topChangeAt = weightNeeded;
+            info.wouldBecome = runnerUp.name;
+          }
+        }
+      }
+
+      sensitivity[criterion.id] = info;
+    }
+
+    return sensitivity;
+  }
+}
+
+// Export a singleton instance for convenience
+export const utilityStrategy = new UtilityStrategy();

package/src/engines/utility/types.ts

@@ -0,0 +1,225 @@
+/**
+ * Utility/MCDM Engine Types
+ *
+ * Multi-Criteria Decision Making engine for comparing alternatives
+ * across weighted criteria. Unlike Scoring (which evaluates one item),
+ * MCDM explicitly models trade-offs between multiple options.
+ */
+
+import {
+  BaseRule,
+  BaseRuleSet,
+  CompiledBaseRule,
+  CompiledBaseRuleSet,
+  CompiledCondition,
+  Expression
+} from '../../core';
+
+// ========================================
+// Semantic Priority Types
+// ========================================
+
+/**
+ * Semantic priority levels for expressing criterion importance in human-readable terms.
+ * The compiler converts these to numeric weights and auto-normalizes.
+ *
+ * @example
+ * ```typescript
+ * {
+ *   id: 'low-fees',
+ *   name: 'Low Agency Fees',
+ *   weight: 'critical',  // Instead of 0.25
+ *   direction: 'maximize'
+ * }
+ * ```
+ */
+export type SemanticPriority = 'critical' | 'high' | 'medium' | 'low' | 'not-important';
+
+/**
+ * Base numeric values for semantic priorities (before normalization).
+ * These are relative weights that get normalized to sum to 1.0.
+ *
+ * - critical: 5 (highest priority)
+ * - high: 3
+ * - medium: 2
+ * - low: 1
+ * - not-important: 0 (excluded from calculation)
+ */
+export const SEMANTIC_PRIORITY_VALUES: Record<SemanticPriority, number> = {
+  'critical': 5,
+  'high': 3,
+  'medium': 2,
+  'low': 1,
+  'not-important': 0
+};
+
+/**
+ * Check if a value is a semantic priority string
+ */
+export function isSemanticPriority(value: unknown): value is SemanticPriority {
+  return typeof value === 'string' && value in SEMANTIC_PRIORITY_VALUES;
+}
+
+// ========================================
+// Criterion Types
+// ========================================
+
+/**
+ * A criterion (dimension) for evaluating alternatives.
+ *
+ * Weight can be specified as:
+ * - A number (0-1): Traditional numeric weight, all weights should sum to 1
+ * - A SemanticPriority: Human-readable priority that gets auto-normalized
+ *
+ * @example Numeric weight
+ * ```typescript
+ * {
+ *   id: 'compensation',
+ *   name: 'Total Compensation',
+ *   weight: 0.30,
+ *   direction: 'maximize'
+ * }
+ * ```
+ *
+ * @example Semantic weight (auto-normalized)
+ * ```typescript
+ * {
+ *   id: 'low-fees',
+ *   name: 'Low Agency Fees',
+ *   weight: 'critical',
+ *   direction: 'maximize'
+ * }
+ * ```
+ */
+export type UtilityCriterion = {
+  id: string;
+  name?: string;
+  weight: number | SemanticPriority;  // Numeric (0-1) or semantic priority
+  direction: 'maximize' | 'minimize';
+};
+
+/**
+ * Compiled criterion with validated weight
+ */
+export type CompiledUtilityCriterion = {
+  id: string;
+  name?: string;
+  weight: number;
+  direction: 'maximize' | 'minimize';
+};
+
+// ========================================
+// Source Types (User-Defined)
+// ========================================
+
+/**
+ * Utility rule - computes a criterion value for an alternative
+ *
+ * @example
+ * ```typescript
+ * {
+ *   id: 'calc-compensation',
+ *   criterion: 'compensation',
+ *   inputs: [{ name: 'offer', type: 'JobOffer' }],
+ *   compute: ['add', '$offer.baseSalary', '$offer.bonus']
+ * }
+ * ```
+ */
+export type UtilityRule = BaseRule & {
+  criterion: string;  // ID of the criterion this rule computes
+  compute: Expression;  // Expression to calculate the raw value
+};
+
+/**
+ * Utility ruleset configuration
+ */
+export type UtilityConfig = {
+  mode: 'utility';
+  normalization: 'min-max' | 'z-score' | 'none';
+  aggregation: 'weighted-sum' | 'weighted-product';
+};
+
+/**
+ * Utility ruleset
+ */
+export type UtilityRuleSet = BaseRuleSet & {
+  mode: 'utility';
+  criteria: UtilityCriterion[];
+  rules: UtilityRule[];
+  config?: Partial<Omit<UtilityConfig, 'mode'>>;
+};
+
+// ========================================
+// Compiled Types
+// ========================================
+
+/**
+ * Compiled utility rule
+ */
+export type CompiledUtilityRule = CompiledBaseRule & {
+  criterion: string;
+  compute: CompiledCondition;
+};
+
+/**
+ * Compiled utility ruleset
+ */
+export type CompiledUtilityRuleSet = CompiledBaseRuleSet & {
+  mode: 'utility';
+  criteria: CompiledUtilityCriterion[];
+  rules: CompiledUtilityRule[];
+  config: UtilityConfig;
+};
+
+// ========================================
+// Runtime Types
+// ========================================
+
+/**
+ * Result for a single alternative
+ */
+export type AlternativeResult = {
+  id: string;
+  name: string;
+  rawScores: Record<string, number>;        // Criterion ID -> raw value
+  normalizedScores: Record<string, number>; // Criterion ID -> 0-1 normalized
+  weightedScores: Record<string, number>;   // Criterion ID -> weighted contribution
+  utilityScore: number;                     // Final aggregated score
+};
+
+/**
+ * Sensitivity analysis for a criterion
+ */
+export type SensitivityInfo = {
+  currentTop: string;        // Current top alternative
+  topChangeAt?: number;      // Weight at which top would change
+  wouldBecome?: string;      // Alternative that would become top
+};
+
+/**
+ * Runtime options for utility execution
+ */
+export type UtilityOptions = {
+  /** Callback when evaluating a criterion for an alternative */
+  onEvaluate?: (alternativeId: string, criterion: string, rawValue: number) => void;
+  /** Callback when an alternative is fully scored */
+  onScore?: (alternative: AlternativeResult) => void;
+  /** Whether to compute sensitivity analysis (default: false) */
+  computeSensitivity?: boolean;
+};
+
+/**
+ * Execution result
+ */
+export type UtilityResult = {
+  /** All alternatives with their scores */
+  alternatives: AlternativeResult[];
+  /** Alternatives sorted by utility score (descending) */
+  ranking: AlternativeResult[];
+  /** Winner (highest utility) */
+  winner: AlternativeResult | null;
+  /** Sensitivity analysis per criterion (if requested) */
+  sensitivity?: Record<string, SensitivityInfo>;
+  /** Processing time in milliseconds */
+  executionTimeMs: number;
+};

package/src/functions/README.md

@@ -0,0 +1,63 @@
+# Functions Library
+
+Specialized functions for use in rule engine expressions.
+
+## Structure
+
+```
+src/functions/
+├── phonetic/          # Phonetic encoding algorithms
+│   ├── soundex.ts     # Classic Soundex (4-char codes)
+│   ├── nysiis.ts      # NYSIIS (6-char codes)
+│   └── caverphone2.ts # Caverphone2 (10-char codes)
+├── similarity/        # Text similarity measures
+│   └── cosine-similarity.ts # Cosine similarity (0-1 score)
+└── index.ts           # Main exports
+```
+
+## Usage
+
+```typescript
+import { soundex, nysiis, caverphone2, cosineSimilarity } from '../src/functions';
+
+// Phonetic matching
+soundex('Smith');      // "S530"
+nysiis('Schmidt');     // "SNAD"
+caverphone2('Peter');  // "PT11111111"
+
+// Text similarity
+cosineSimilarity('hello world', 'hello there');  // 0.50
+```
+
+## Categories
+
+### Phonetic Encoding
+
+Functions that encode names into phonetic codes for matching similar-sounding names:
+
+- **Soundex** - Classic algorithm, widely used, 4-character codes
+- **NYSIIS** - More accurate than Soundex, handles spelling variations, 6-character codes
+- **Caverphone2** - Complex algorithm optimized for NZ/Australian accents, 10-character codes
+
+### Text Similarity
+
+Functions that measure similarity between text strings:
+
+- **Cosine Similarity** - Vector-based text similarity measure (0-1 score)
+
+## Adding New Functions
+
+When adding new functions:
+
+1. Create the function in the appropriate category folder (or create a new category)
+2. Export from the category's `index.ts`
+3. The main `src/functions/index.ts` will re-export automatically via `export *`
+4. Add examples to `examples/` directory
+
+### Suggested Future Categories
+
+- `distance/` - String distance metrics (Levenshtein, Hamming, Jaro-Winkler)
+- `math/` - Mathematical functions (statistics, financial calculations)
+- `datetime/` - Date/time utilities
+- `validation/` - Validation functions (email, phone, credit card)
+- `crypto/` - Cryptographic functions (hashing, encryption)

package/src/functions/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Niche Functions for Rule Engine
+ *
+ * Collection of specialized functions for use in rule expressions.
+ * Organized by category for easy discovery and maintenance.
+ */
+
+// Text Similarity Functions
+export * from './similarity';
+
+// Phonetic Encoding Functions
+export * from './phonetic';