@higher.archi/boe 1.0.0

package/src/engines/fuzzy/compiler.ts

@@ -0,0 +1,182 @@
+/**
+ * Fuzzy Engine Compiler
+ *
+ * Compiles fuzzy rulesets into executable form.
+ */
+
+import {
+  compileCondition,
+  normalizeShape,
+  CompiledBaseRuleSet,
+  CompiledBaseRule
+} from '../../core';
+
+import { FuzzyRuleSet, FuzzyRule, FuzzyConfig, CompiledFuzzyAction, FuzzyOutput, CompiledFuzzyVariable } from './types';
+import {
+  compileFuzzyVariable,
+  parseTermRef,
+  autoAdjustCoverage,
+  AutoAdjustOptions
+} from './fuzzy.membership';
+
+// ========================================
+// Compiled RuleSet Type
+// ========================================
+
+export type CompiledFuzzyRuleSet = CompiledBaseRuleSet & {
+  mode: 'fuzzy';
+  variables: CompiledFuzzyVariable[];
+  variableIndex: Map<string, CompiledFuzzyVariable>;
+  config: FuzzyConfig;
+  rules: CompiledFuzzyRule[];
+};
+
+export type CompiledFuzzyRule = CompiledBaseRule & {
+  action: CompiledFuzzyAction;
+};
+
+// ========================================
+// 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;
+}
+
+// ========================================
+// Action Compilation
+// ========================================
+
+function compileFuzzyAction(thenValue: FuzzyOutput): CompiledFuzzyAction {
+  // Simple string form: 'variable.term'
+  if (typeof thenValue === 'string') {
+    const [variable, term] = parseTermRef(thenValue);
+    return {
+      mode: 'fuzzy',
+      output: { variable, term }
+    };
+  }
+
+  // Explicit form: { output: 'variable.term', degree?: number }
+  const [variable, term] = parseTermRef(thenValue.output);
+  const action: CompiledFuzzyAction = {
+    mode: 'fuzzy',
+    output: { variable, term }
+  };
+
+  if (thenValue.degree !== undefined) {
+    action.degree = thenValue.degree;
+  }
+
+  return action;
+}
+
+// ========================================
+// Rule Compilation
+// ========================================
+
+export function compileFuzzyRule(rule: FuzzyRule, index: number = 0) {
+  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: compileFuzzyAction(rule.then)
+  };
+}
+
+// ========================================
+// RuleSet Compilation
+// ========================================
+
+export function compileFuzzyRuleSet(ruleSet: FuzzyRuleSet): CompiledFuzzyRuleSet {
+  const config: FuzzyConfig = {
+    mode: 'fuzzy',
+    threshold: ruleSet.config?.threshold ?? 0.01,
+    defuzzify: ruleSet.config?.defuzzify ?? 'balanced',
+    coverage: ruleSet.config?.coverage
+  };
+
+  // Determine coverage options
+  const coverageConfig = ruleSet.config?.coverage;
+  const shouldAutoAdjust = coverageConfig !== false;
+  const coverageOptions: AutoAdjustOptions | false = shouldAutoAdjust
+    ? (typeof coverageConfig === 'object' ? coverageConfig : {})
+    : false;
+
+  // Compile all fuzzy variables (with optional coverage adjustment)
+  const variables = ruleSet.variables.map(variable => {
+    const adjusted = coverageOptions === false
+      ? variable
+      : autoAdjustCoverage(variable, coverageOptions);
+    return compileFuzzyVariable(adjusted);
+  });
+
+  // Build variable index for fast lookup
+  const variableIndex = new Map();
+  for (const variable of variables) {
+    variableIndex.set(variable.name, variable);
+  }
+
+  return {
+    id: ruleSet.id,
+    name: ruleSet.name,
+    mode: 'fuzzy',
+    schema: ruleSet.shape ? normalizeShape(ruleSet.shape) : { type: 'object' },
+    rules: ruleSet.rules.map((rule, index) => compileFuzzyRule(rule, index)),
+    config,
+    variables,
+    variableIndex
+  };
+}

package/src/engines/fuzzy/defuzzify.ts

@@ -0,0 +1,39 @@
+/**
+ * Fuzzy Engine Defuzzification
+ *
+ * Re-exports defuzzification functions from local fuzzy.defuzzify module.
+ */
+
+export {
+  // Aggregation methods
+  aggregate,
+  aggregateMax,
+  aggregateSum,
+  aggregateProbor,
+  aggregateBound,
+  aggregateMin,
+
+  // Defuzzification methods
+  defuzzify,
+  defuzzifyCentroid,
+  defuzzifyBisector,
+  defuzzifyMom,
+  defuzzifySom,
+  defuzzifyLom,
+  defuzzifyWtaver,
+
+  // Transform methods
+  transform,
+  transformClamp,
+  transformRound,
+  transformDeadband,
+  transformScale,
+  transformQuantize,
+
+  // Pipeline
+  executePipeline,
+
+  // Types
+  DefuzzifyInput,
+  PipelineContext
+} from './fuzzy.defuzzify';

package/src/engines/fuzzy/engine.ts

@@ -0,0 +1,124 @@
+/**
+ * Fuzzy Logic Engine
+ *
+ * Self-contained engine for fuzzy logic rule execution.
+ * Implements IRuleEngine with strongly-typed ruleset, options, and result.
+ */
+
+import {
+  IRuleEngine,
+  WorkingMemory,
+  Fact,
+  FactInput,
+  FactChange
+} from '../../core';
+
+import {
+  FuzzyOptions,
+  FuzzyResult
+} from './types';
+
+import { CompiledFuzzyRuleSet } from './compiler';
+
+import { FuzzyStrategy } from './strategy';
+
+/**
+ * Fuzzy logic rule engine.
+ *
+ * Evaluates rules using fuzzy membership functions and defuzzification.
+ * Produces crisp output values from linguistic rules.
+ *
+ * @example
+ * ```typescript
+ * const engine = new FuzzyEngine();
+ * engine.add({ type: 'TemperatureSensor', data: { temp: 72 } });
+ *
+ * const result = engine.execute(compiledRules);
+ * console.log(`Heater: ${result.outputs.heater}%`);
+ * console.log(`AC: ${result.outputs.ac}%`);
+ * ```
+ */
+export class FuzzyEngine implements IRuleEngine<CompiledFuzzyRuleSet, FuzzyOptions, FuzzyResult> {
+  private wm: WorkingMemory;
+  private strategy: FuzzyStrategy;
+
+  constructor(workingMemory?: WorkingMemory) {
+    this.wm = workingMemory ?? new WorkingMemory();
+    this.strategy = new FuzzyStrategy();
+  }
+
+  // ========================================
+  // 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 fuzzy ruleset.
+   *
+   * Input values are fuzzified using membership functions,
+   * rules are evaluated with fuzzy logic, and outputs are
+   * defuzzified to produce crisp values.
+   *
+   * @param ruleSet - Compiled fuzzy ruleset
+   * @param options - Runtime options (callbacks)
+   * @returns Result with memberships and defuzzified outputs
+   */
+  execute(ruleSet: CompiledFuzzyRuleSet, options: FuzzyOptions = {}): FuzzyResult {
+    return this.strategy.run(ruleSet, this.wm, options);
+  }
+
+  // ========================================
+  // Utility Methods
+  // ========================================
+
+  getWorkingMemory(): WorkingMemory {
+    return this.wm;
+  }
+}