Fuzzy Logic

The Fuzzy client provides operations for reasoning under uncertainty. Terms with fuzzy values can be unified, merged, compared, and searched with graded similarity degrees.

FuzzyShape builders

Fuzzy membership functions define how a value maps to a truth degree (0.0 to 1.0). The SDK provides builders for four shape types.

import { FuzzyShape, Value } from '@kortexya/reasoninglayer';

// Triangular: ramps up from a to peak b, ramps down to c
const tri = FuzzyShape.triangular(20, 22, 24);
// {"kind": "Triangular", "a": 20, "b": 22, "c": 24}

// Trapezoidal: ramps up a->b, flat b->c, ramps down c->d
const trap = FuzzyShape.trapezoidal(18, 20, 24, 26);
// {"kind": "Trapezoidal", "a": 18, "b": 20, "c": 24, "d": 26}

// Gaussian: bell curve centered at mean with stdDev width
const gauss = FuzzyShape.gaussian(100, 15);
// {"kind": "Gaussian", "mean": 100, "stdDev": 15}

// Cyclic Gaussian: periodic wrapping (e.g., angles, time-of-day)
const cyclic = FuzzyShape.cyclicGaussian(180, 30, 360);
// {"kind": "CyclicGaussian", "mean": 180, "stdDev": 30, "period": 360}

Using fuzzy values in terms

Attach fuzzy shapes to term features using the Value builders:

// Fuzzy number (membership function)
const temp = Value.fuzzyNumber(FuzzyShape.triangular(20, 22, 24));

// Fuzzy scalar (specific value with membership degree)
const reading = Value.fuzzyScalar(22.5, 0.85);

// Create a term with fuzzy features
const term = await client.terms.createTerm({
  sortId: sensorReadingSortId,
  ownerId: 'user-uuid',
  features: {
    location: 'lab-1',
    temperature: temp,
    humidity: Value.fuzzyNumber(FuzzyShape.gaussian(60, 10)),
    pressure: reading,
  },
});

Fuzzy unification

Fuzzy unification computes a similarity degree between two terms and produces a unified term if the degree exceeds the threshold.

const result = await client.fuzzy.fuzzyUnify({
  term1Id: termA,
  term2Id: termB,
  threshold: 0.5,
  similarityMode: 'hybrid',
});

console.log(`Degree: ${result.degree}`);             // 0.0 to 1.0
console.log(`Confidence: ${result.confidencePercent}%`); // 0 to 100
console.log(`Unified term:`, result.term);

Similarity modes control how string features are compared:

Mode	Strategy
`fast`	Exact match, normalized, Jaccard (no embeddings)
`hybrid`	Exact, normalized, Jaccard, then embeddings (default)
`semantic`	Exact, normalized, then embeddings (skip Jaccard)

fuzzyUnify is also available as compareSimilarity(term1Id, term2Id, options?) for a simpler calling convention:

const result = await client.fuzzy.compareSimilarity(termA, termB, {
  threshold: 0.5,
  similarityMode: 'hybrid',
});

Residuation on unknown values

By default, uninstantiated (unknown) values cause residuation rather than failure. Set failOnUnknown to change this behavior:

const result = await client.fuzzy.fuzzyUnify({
  term1Id: termA,
  term2Id: termB,
  failOnUnknown: true, // fail instead of residuating
});

Fuzzy merge

Merge two terms by combining their features using a merge strategy.

const result = await client.fuzzy.fuzzyMerge({
  term1Id: termA,
  term2Id: termB,
  strategy: 'max',
});

console.log(`Merged features: ${result.mergedFeatures}`);
console.log(`Strategy: ${result.strategy}`);
console.log(`Time: ${result.computationTimeMs}ms`);

Available strategies:

Strategy	Description
`max`	Take the maximum membership degree
`min`	Take the minimum membership degree
`probabilistic_sum`	P(A or B) = P(A) + P(B) - P(A)P(B)
`product`	P(A and B) = P(A) * P(B)

Fuzzy subsumption

Check whether one term is subsumed by (more specific than) another.

const result = await client.fuzzy.fuzzySubsumption({
  generalTermId: abstractTermId,
  specificTermId: concreteTermId,
  threshold: 0.7,
});

console.log(`Degree: ${result.degree}`);
console.log(`Subsumes: ${result.subsumes}`); // true if degree >= threshold
console.log(`Time: ${result.computationTimeMs}ms`);

Top-K similarity search

Find the K most similar terms to a query term.

Search by existing term

const result = await client.fuzzy.searchTopK({
  type: 'by_id',
  termId: queryTermId,
  k: 10,
  minDegree: 0.3,
  similarityMode: 'hybrid',
});

for (const item of result.results) {
  console.log(`${item.term.id}: degree=${item.degree}`);
  console.log('  features:', item.term.features);
}

Search by inline term

const result = await client.fuzzy.searchTopK({
  type: 'inline',
  sortId: sensorSortId,
  features: {
    temperature: Value.fuzzyNumber(FuzzyShape.triangular(20, 22, 24)),
    location: { type: 'String', value: 'lab-1' },
  },
  k: 5,
  minDegree: 0.5,
});

Effect prediction

Predict an effect by aggregating fuzzy number features from similar terms using Bayesian merging.

const result = await client.fuzzy.predictEffect({
  type: 'by_id',
  termId: queryTermId,
  effectVar: 'potency',
  minDegree: 0.3,
  robust: true,
  conformal: 0.9, // 90% coverage interval
  similarityMode: 'hybrid',
});

if (result.success) {
  console.log(`Degree: ${result.degree}`);
  console.log(`Sources merged: ${result.sourcesMerged}`);
  console.log(`Time: ${result.queryTimeMs}ms`);

  // Primary effect
  if (result.effect) {
    console.log('Effect:', result.effect);
  }

  // All effects (multi-parameter)
  if (result.allEffects) {
    for (const [name, effect] of Object.entries(result.allEffects)) {
      console.log(`  ${name}:`, effect);
    }
  }

  // Proof trace for debugging
  for (const step of result.proofTrace) {
    console.log(`  trace: ${step}`);
  }
}

Gating methods

Control how similarity is computed for effect prediction:

// Default fuzzy gating
await client.fuzzy.predictEffect({
  type: 'by_id',
  termId: termId,
  effectVar: 'potency',
});

// Learned metric-gated similarity
await client.fuzzy.predictEffect({
  type: 'by_id',
  termId: termId,
  effectVar: 'potency',
  gating: 'learned',
});

Fuzzy proving (via inference)

For goal-directed fuzzy reasoning with truth degree propagation, use the inference client’s fuzzyProve method:

import { psi } from '@kortexya/reasoninglayer';

const result = await client.inference.fuzzyProve({
  goal: psi('drug_interaction', {
    drug: 'aspirin',
    effect: '?Effect',
  }),
  minDegree: 0.3,
  maxSolutions: 10,
  tnorm: 'product', // "min", "product", or "lukasiewicz"
});

for (const solution of result.solutions) {
  console.log(`Certainty: ${solution.certainty}`);
  for (const binding of solution.substitution.bindings) {
    console.log(`  ${binding.variableName} = ${binding.boundToDisplay}`);
  }
}

T-norm strategies control how truth degrees combine:

T-norm	Formula	Behavior
`min`	min(a, b)	Conservative, pessimistic
`product`	a * b	Probabilistic, moderate
`lukasiewicz`	max(0, a + b - 1)	Strict, penalizes low degrees