@higher.archi/boe 1.0.0

package/src/engines/fuzzy/fuzzy.types.ts

@@ -0,0 +1,357 @@
+/**
+ * Fuzzy Engine Types
+ *
+ * Complete fuzzy logic types for membership functions, defuzzification,
+ * and fuzzy inference. Self-contained within the fuzzy engine.
+ */
+
+import { BindingContext } from '../../core';
+
+// ========================================
+// Membership Shape Types
+// ========================================
+
+/**
+ * Membership function shapes
+ * These define how membership degree (0-1) is calculated from a crisp value
+ */
+export type MembershipShape = 'triangle' | 'trapezoid' | 'gaussian' | 'shoulder' | 'block';
+
+/**
+ * Semantic position within domain (compiles to numeric center)
+ */
+export type PositionSemantic = 'very-low' | 'low' | 'medium' | 'high' | 'very-high';
+
+/**
+ * Semantic width/spread (compiles to numeric spread as % of domain)
+ */
+export type WidthSemantic = 'tight' | 'narrow' | 'medium' | 'wide' | 'very-wide';
+
+/**
+ * Edge behavior for shoulder/block shapes
+ */
+export type EdgeSemantic = 'open-left' | 'open-right' | 'closed';
+
+// ========================================
+// Fuzzy Term Definitions
+// ========================================
+
+/**
+ * Semantic fuzzy term - uses intuitive descriptors
+ * Compiles to explicit numeric parameters at compile time
+ */
+export type SemanticFuzzyTerm = {
+  name: string;
+  shape: MembershipShape;
+  position: PositionSemantic;
+  width: WidthSemantic;
+  edge?: EdgeSemantic;  // Required for 'shoulder', optional for others
+};
+
+/**
+ * Explicit fuzzy term - direct numeric parameters
+ * For advanced users who need precise control
+ */
+export type ExplicitFuzzyTerm = {
+  name: string;
+  shape: MembershipShape;
+  params: number[];  // Shape-specific parameters
+};
+
+/**
+ * Union of term definition types
+ */
+export type FuzzyTerm = SemanticFuzzyTerm | ExplicitFuzzyTerm;
+
+/**
+ * Type guard for semantic terms
+ */
+export function isSemanticTerm(term: FuzzyTerm): term is SemanticFuzzyTerm {
+  return 'position' in term && 'width' in term;
+}
+
+/**
+ * Type guard for explicit terms
+ */
+export function isExplicitTerm(term: FuzzyTerm): term is ExplicitFuzzyTerm {
+  return 'params' in term;
+}
+
+// ========================================
+// Fuzzy Variable Definition
+// ========================================
+
+/**
+ * A fuzzy linguistic variable with its domain and terms
+ */
+export type FuzzyVariable = {
+  name: string;
+  domain: [number, number];  // [min, max] range
+  terms: FuzzyTerm[];
+};
+
+// ========================================
+// Compiled Membership Types
+// ========================================
+
+/**
+ * Compiled membership function - all terms resolved to numeric params
+ */
+export type CompiledMembershipFunction = {
+  shape: MembershipShape;
+  params: number[];  // Shape-specific parameters (always numeric after compilation)
+};
+
+/**
+ * Compiled fuzzy term
+ */
+export type CompiledFuzzyTerm = {
+  name: string;
+  membership: CompiledMembershipFunction;
+};
+
+/**
+ * Compiled fuzzy variable
+ */
+export type CompiledFuzzyVariable = {
+  name: string;
+  domain: [number, number];
+  terms: CompiledFuzzyTerm[];
+  termIndex: Map<string, CompiledFuzzyTerm>;  // Fast lookup by term name
+};
+
+// ========================================
+// Defuzzification Pipeline Types
+// ========================================
+
+/**
+ * Aggregation methods - combine multiple rule activations for same output
+ */
+export type AggregationMethod =
+  | 'max'     // Maximum membership (standard fuzzy OR)
+  | 'sum'     // Sum memberships (can exceed 1)
+  | 'probor'  // Probabilistic OR: a + b - ab
+  | 'bound'   // Bounded sum: min(1, a + b)
+  | 'min';    // Intersection (rare)
+
+/**
+ * Defuzzification methods - convert fuzzy output to crisp value
+ */
+export type DefuzzifyMethod =
+  | 'centroid'  // Center of gravity (most common)
+  | 'bisector'  // Line that divides area in half
+  | 'mom'       // Mean of maximum
+  | 'som'       // Smallest of maximum
+  | 'lom'       // Largest of maximum
+  | 'wtaver';   // Weighted average of term centers
+
+/**
+ * Transform methods - post-process the crisp output
+ */
+export type TransformMethod =
+  | 'clamp'     // Enforce output bounds
+  | 'round'     // Round to integer
+  | 'deadband'  // Zero out small values
+  | 'scale'     // Scale to different range
+  | 'quantize'; // Snap to discrete steps
+
+/**
+ * Any defuzzification pipeline stage
+ */
+export type DefuzzifyStage = AggregationMethod | DefuzzifyMethod | TransformMethod;
+
+/**
+ * Named presets that expand to full pipelines
+ */
+export type DefuzzifyPreset =
+  | 'balanced'    // ['max', 'centroid', 'clamp'] - general purpose
+  | 'smooth'      // ['probor', 'centroid', 'clamp'] - gradual transitions
+  | 'decisive'    // ['max', 'mom'] - snappy response
+  | 'cautious'    // ['max', 'som', 'clamp'] - conservative
+  | 'aggressive'  // ['max', 'lom', 'clamp'] - responsive
+  | 'discrete'    // ['max', 'centroid', 'clamp', 'round'] - integer outputs
+  | 'stable';     // ['max', 'centroid', 'deadband', 'clamp'] - reduce chatter
+
+/**
+ * Defuzzification pipeline configuration
+ */
+export type DefuzzifyConfig = DefuzzifyPreset | DefuzzifyStage[];
+
+// ========================================
+// Fuzzy Rule Output Types
+// ========================================
+
+/**
+ * Simple output - just the term reference
+ */
+export type FuzzyOutputSimple = string;  // 'variable.term'
+
+/**
+ * Explicit output with optional degree override
+ */
+export type FuzzyOutputExplicit = {
+  output: string;  // 'variable.term'
+  degree?: number; // Override membership degree (0-1)
+};
+
+/**
+ * Fuzzy rule output
+ */
+export type FuzzyOutput = FuzzyOutputSimple | FuzzyOutputExplicit;
+
+// ========================================
+// Compiled Fuzzy Action Type
+// ========================================
+
+/**
+ * Compiled fuzzy action
+ */
+export type CompiledFuzzyAction = {
+  mode: 'fuzzy';
+  output: {
+    variable: string;  // Variable name
+    term: string;      // Term name
+  };
+  degree?: number;  // Optional fixed degree override
+};
+
+// ========================================
+// Fuzzy Configuration
+// ========================================
+
+/**
+ * Coverage auto-adjustment options
+ */
+export type CoverageOptions = {
+  /** Target minimum coverage (default 0.3) */
+  targetMinCoverage?: number;
+  /** Maximum width multiplier to apply (default 2.0) */
+  maxWidthMultiplier?: number;
+  /** Resolution for coverage analysis (default 100) */
+  resolution?: number;
+};
+
+/**
+ * Fuzzy strategy configuration
+ */
+export type FuzzyConfig = {
+  mode: 'fuzzy';
+  threshold?: number;               // Min membership to activate (default 0.01)
+  defuzzify?: DefuzzifyConfig;      // Pipeline or preset (default 'balanced')
+  coverage?: CoverageOptions | boolean;  // Auto-adjust coverage (default true with defaults, false to disable)
+};
+
+// ========================================
+// Runtime Options
+// ========================================
+
+/**
+ * Runtime options for fuzzy execution
+ */
+export type FuzzyOptions = {
+  onFire?: (ruleId: string, context: BindingContext, degree: number) => void;
+};
+
+// ========================================
+// Execution Result
+// ========================================
+
+/**
+ * Membership values for a single variable
+ */
+export type VariableMemberships = Record<string, number>;  // { 'cold': 0.3, 'hot': 0.7 }
+
+/**
+ * All input memberships calculated during fuzzification
+ */
+export type FuzzificationResult = Record<string, VariableMemberships>;  // { 'temperature': {...} }
+
+/**
+ * Rule activation during inference
+ */
+export type FuzzyActivation = {
+  ruleId: string;
+  outputVariable: string;
+  outputTerm: string;
+  degree: number;
+};
+
+/**
+ * Aggregated outputs before defuzzification
+ */
+export type AggregatedOutputs = Record<string, VariableMemberships>;
+
+/**
+ * Final crisp output values
+ */
+export type CrispOutputs = Record<string, number>;
+
+/**
+ * Full fuzzy execution result
+ */
+export type FuzzyResult = {
+  // Debug/introspection
+  memberships: FuzzificationResult;   // Input fuzzification results
+  activations: FuzzyActivation[];     // Which rules fired with what degree
+  aggregated: AggregatedOutputs;      // Pre-defuzzification aggregated values
+
+  // Standard result fields
+  fired: string[];                    // Rule IDs that activated
+  iterations: 1;                      // Fuzzy is always one-pass
+
+  // Final outputs
+  outputs: CrispOutputs;              // Defuzzified crisp values
+
+  // Performance
+  executionTimeMs: number;            // Processing time in milliseconds
+};
+
+// ========================================
+// Preset Expansions
+// ========================================
+
+/**
+ * Expand a defuzzify preset to its pipeline stages
+ */
+export function expandDefuzzifyPreset(preset: DefuzzifyPreset): DefuzzifyStage[] {
+  switch (preset) {
+    case 'balanced':
+      return ['max', 'centroid', 'clamp'];
+    case 'smooth':
+      return ['probor', 'centroid', 'clamp'];
+    case 'decisive':
+      return ['max', 'mom'];
+    case 'cautious':
+      return ['max', 'som', 'clamp'];
+    case 'aggressive':
+      return ['max', 'lom', 'clamp'];
+    case 'discrete':
+      return ['max', 'centroid', 'clamp', 'round'];
+    case 'stable':
+      return ['max', 'centroid', 'deadband', 'clamp'];
+    default:
+      throw new Error(`Unknown defuzzify preset: ${preset}`);
+  }
+}
+
+/**
+ * Semantic position to numeric value (0-1 within domain)
+ */
+export const POSITION_VALUES: Record<PositionSemantic, number> = {
+  'very-low': 0.10,
+  'low': 0.25,
+  'medium': 0.50,
+  'high': 0.75,
+  'very-high': 0.90
+};
+
+/**
+ * Semantic width to numeric spread (as fraction of domain range)
+ */
+export const WIDTH_VALUES: Record<WidthSemantic, number> = {
+  'tight': 0.02,
+  'narrow': 0.05,
+  'medium': 0.10,
+  'wide': 0.20,
+  'very-wide': 0.35
+};

package/src/engines/fuzzy/index.ts

@@ -0,0 +1,38 @@
+/**
+ * Fuzzy Engine
+ *
+ * Provides fuzzy logic rule execution with:
+ * - Linguistic variables and membership functions
+ * - Fuzzy conditions (is/isNot operators)
+ * - Defuzzification pipelines
+ * - Coverage auto-adjustment
+ */
+
+// Types
+export * from './types';
+
+// Compiler
+export {
+  compileFuzzyRule,
+  compileFuzzyRuleSet,
+  CompiledFuzzyRuleSet,
+  CompiledFuzzyRule
+} from './compiler';
+
+// Strategy
+export {
+  FuzzyStrategy,
+  fuzzyStrategy,
+  evaluateFuzzyIs,
+  evaluateFuzzyIsNot,
+  FuzzyEvaluationContext
+} from './strategy';
+
+// Membership functions
+export * from './membership';
+
+// Defuzzification
+export * from './defuzzify';
+
+// Engine
+export { FuzzyEngine } from './engine';

package/src/engines/fuzzy/membership.ts

@@ -0,0 +1,22 @@
+/**
+ * Fuzzy Engine Membership Functions
+ *
+ * Re-exports membership functions from local fuzzy.membership module.
+ */
+
+export {
+  // Core functions
+  compileFuzzyVariable,
+  parseTermRef,
+  fuzzifyValue,
+  getMembershipDegree,
+  evaluateMembership,
+
+  // Coverage analysis and adjustment
+  analyzeCoverage,
+  autoAdjustCoverage,
+
+  // Types
+  AutoAdjustOptions,
+  CoverageAnalysis
+} from './fuzzy.membership';