Builders

The SDK provides builder namespaces that construct the correct serialization format for each API context. Builders are the primary developer ergonomics layer — they ensure type safety, prevent format mismatches, and provide IntelliSense guidance.

Which builder to use where

Context	Builder to use	Produces
Term CRUD features	Plain JS values or `Value.*`	Tagged `ValueDto`
Query features	Plain JS values or `Value.*`	Tagged `ValueDto`
Fuzzy operation features	Plain JS values or `Value.*`	Tagged `ValueDto`
Fuzzy membership shapes	`FuzzyShape.*`	`FuzzyShapeDto`
Inference rule/fact inputs	`psi()`, plain values	Untagged `TermInputDto`
Guard constraints	`guard()`	Untagged `TermInputDto`
Constrained variables	`constrained()`	`ConstrainedPlainVar`
Sort creation	`SortBuilder`	`CreateSortRequest`
Psi-term shorthand	`psi()`	`PsiTermInput`
Allen temporal constraints	`allen()`	Tagged `ConstraintInputDto`
LP optimization	`LP.*`	`LinearProgramDefinition`

Value

The Value namespace builds complex tagged ValueDto values that have no plain JS equivalent. For simple types, pass plain JS values directly — the SDK auto-converts them.

Plain JS values (no builder needed):

// These are auto-converted to tagged ValueDto by the SDK:
"hello"    // -> {"type": "String", "value": "hello"}
42         // -> {"type": "Integer", "value": 42}
3.14       // -> {"type": "Real", "value": 3.14}
true       // -> {"type": "Boolean", "value": true}
null       // -> {"type": "Uninstantiated"}
[...]      // -> {"type": "List", "value": [...]}

Use with: client.terms.*, client.query.*, fuzzy operations.

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

// Plain values (no builder needed):
const features = { name: "Alice", age: 30, active: true };

// Complex types (require Value.*):
Value.reference(termUuid)      // {"type": "Reference", "value": "uuid"}

// Fuzzy values
Value.fuzzyScalar(0.5, 0.8)   // {"type": "FuzzyScalar", "value": {"value": 0.5, "membership": 0.8}}
Value.fuzzyNumber(
  FuzzyShape.triangular(20, 22, 24)
)                              // {"type": "FuzzyNumber", "value": {"shape": {"kind": "Triangular", ...}}}

// Sets (Smyth powerdomain)
Value.set(
  ["uuid1"],                   // lower bound (definite members)
  ["uuid1", "uuid2", "uuid3"], // upper bound (possible members)
  "person_sort_id"             // optional sort constraint
)                              // {"type": "Set", "value": {"lower": [...], "upper": [...], ...}}

Complete variant reference

Method	Return type	JSON `"type"` value
`Value.reference(id)`	`ReferenceValue`	`"Reference"`
`Value.fuzzyScalar(v,m)`	`FuzzyScalarValue`	`"FuzzyScalar"`
`Value.fuzzyNumber(s)`	`FuzzyNumberValue`	`"FuzzyNumber"`
`Value.set(lo,hi,sort?)`	`SetValue`	`"Set"`

Simple types (string, number, boolean, null, arrays) are passed as plain JS values and auto-converted by the SDK.

FuzzyShape

The FuzzyShape namespace builds fuzzy membership function shapes. These use "kind" as the discriminator field, not "type":

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

// Triangular: peak at b, zero at a and c
FuzzyShape.triangular(20, 22, 24)
// {"kind": "Triangular", "a": 20, "b": 22, "c": 24}

// Trapezoidal: flat top between b and c
FuzzyShape.trapezoidal(18, 20, 24, 26)
// {"kind": "Trapezoidal", "a": 18, "b": 20, "c": 24, "d": 26}

// Gaussian: bell curve centered at mean
FuzzyShape.gaussian(100, 15)
// {"kind": "Gaussian", "mean": 100, "stdDev": 15}

// Cyclic Gaussian: wraps around a period (e.g., compass directions)
FuzzyShape.cyclicGaussian(180, 30, 360)
// {"kind": "CyclicGaussian", "mean": 180, "stdDev": 30, "period": 360}

Combine with Value.fuzzyNumber() for use in term features:

const features = {
  temperature: Value.fuzzyNumber(FuzzyShape.triangular(20, 22, 24)),
  iqScore: Value.fuzzyNumber(FuzzyShape.gaussian(100, 15)),
};

psi

The psi() function creates format-agnostic psi-terms that the SDK converts to the correct wire format automatically. It is the primary way to build term inputs for inference.

Use with: client.inference.* for goals, rules, facts.

import { psi, constrained, guard } from '@kortexya/reasoninglayer';

// Simple term — plain JS values are used directly
psi("person", { name: "Alice", age: 30, active: true })
// {"sortName": "person", "features": {"name": "Alice", "age": 30, "active": true}}

// Variables — strings starting with "?" are auto-detected as variables
psi("person", { name: "?Name", age: "?Age" })

// Nested psi-terms
psi("employee", {
  person: psi("person", { name: "Bob" }),
  salary: 100000,
})

// With constrained variable
psi("employee", {
  salary: constrained("?Salary", guard("gt", 50000)),
})

// Term reference — strings starting with "!" are auto-detected as references
psi("department", { manager: "!550e8400-..." })

// Uninstantiated values — null is accepted
psi("employee", { name: "Alice", salary: null })

// No features
psi("person")
// {"sortName": "person"}

Coercion rules

JavaScript value	Coerced to
`string`	Raw string
`"?X"` (starts with `?`)	Variable (auto-detected)
`"!uuid"` (starts with `!`)	Term reference (auto-detected)
`number`	Raw number
`boolean`	Raw boolean
`null`	Uninstantiated
`psi("sort", features)`	Nested psi-term (recursive)
`constrained("?X", guard)`	Constrained variable
`{termId: "uuid"}`	Term reference
`{sortName: "x", features}`	Inline term by name (recursive)
`{sortId: "x", features}`	Inline term by sort ID (recursive)
`{name: "?X", constraint}`	Constrained variable
`{name: "?X"}`	Variable
`[...]`	List (each element is coerced)

constrained

The constrained() function creates a constrained variable for use in psi() features. It pairs a variable name with a guard or type constraint.

import { psi, constrained, guard } from '@kortexya/reasoninglayer';

// Constrained variable with a guard
constrained("?Salary", guard("gt", 100000))

// Use within psi():
psi("employee", {
  name: "?Name",
  salary: constrained("?Salary", guard("gt", 100000)),
  age: constrained("?Age", guard("gte", 40)),
})

guard

The guard() function creates a TermInputDto representing a guard constraint. It is the primary way to create value constraints for variables.

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

// Create a guard constraint
guard("gt", 100000)
// {"sortName": "guard_constraint", "features": {"op": "gt", "right": 100000}}

Available operators (GuardOp):

Op	Meaning
`"lt"`	Less than
`"lte"`	Less than or equal
`"gt"`	Greater than
`"gte"`	Greater than or equal
`"eq"`	Equal
`"ne"`	Not equal

The right argument accepts number, string, or boolean:

guard("gt", 100000)          // numeric comparison
guard("eq", "active")        // string comparison
guard("ne", false)           // boolean comparison

Combining guard with inference

import { psi, constrained, guard } from '@kortexya/reasoninglayer';

// Find high earners over 40
const goal = psi("employee", {
  name: "?Name",
  salary: constrained("?Salary", guard("gt", 100000)),
  age: constrained("?Age", guard("gte", 40)),
});

const result = await client.inference.backwardChain({ goal });

SortBuilder

The SortBuilder class provides a fluent API for constructing CreateSortRequest objects.

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

const request = SortBuilder.create("employee")
  .withId("550e8400-e29b-41d4-a716-446655440000")  // optional deterministic UUID
  .parent(personSortId)                              // add a parent sort
  .parents([organizationMemberSortId])               // add multiple parents
  .feature({
    name: "salary",
    required: true,
    constraint: { type: "IntegerRange", value: { min: 0, max: 10000000 } },
  })
  .feature({ name: "department", required: true })
  .boundConstraint({
    constraintType: "upper",
    target: "end_date",
    sourcePath: "company.dissolution_date",
  })
  .description("An employee at a company")
  .build();

const sort = await client.sorts.createSort(request);

SortBuilder methods

Method	Description
`SortBuilder.create(name)`	Start building a sort with the given name
`.withId(uuid)`	Set a deterministic UUID
`.parent(parentId)`	Add a single parent sort UUID
`.parents(parentIds)`	Add multiple parent sort UUIDs
`.feature(descriptor)`	Add a feature descriptor
`.boundConstraint(constraint)`	Add an inter-feature bound constraint
`.description(text)`	Set a human-readable description
`.build()`	Build the `CreateSortRequest`

allen

The allen() function creates Allen temporal constraint inputs (ConstraintInputDto of type "Allen").

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

// Event A must happen before Event B
allen("before", "event_a_time", "event-b-term-uuid")
// {"type": "Allen", "intervalA": "event_a_time", "intervalBTermId": "event-b-term-uuid", "relation": "before"}

// Meeting overlaps with work hours
allen("overlaps", "meeting_time", "work-hours-term-uuid")

// Lecture starts at the same time as the exam
allen("starts", "lecture_time", "exam-term-uuid")

The 13 Allen relations

Relation	Inverse	Meaning
`before`	`after`	A ends before B starts
`meets`	`met_by`	A ends exactly when B starts
`overlaps`	`overlapped_by`	A starts before B, ends during B
`starts`	`started_by`	Same start time, A ends first
`during`	`contains`	A entirely within B
`finishes`	`finished_by`	Same end time, A starts later
`equals`	`equals`	Same start and end

Using Allen constraints in backward chaining

Allen constraints can be passed in the constraints field of a BackwardChainRequest:

const result = await client.inference.backwardChain({
  goal: psi("scheduled_event", {
    name: "?Event",
    time: "?Time",
  }),
  constraints: [
    allen("before", "?Time", meetingTermId),
    allen("after", "?Time", lunchTermId),
  ],
});

Complete example: combining builders

Here is a complete example that uses multiple builder namespaces together:

import {
  ReasoningLayerClient,
  SortBuilder,
  Value,
  FuzzyShape,
  psi,
  constrained,
  guard,
} from '@kortexya/reasoninglayer';

const client = new ReasoningLayerClient({
  baseUrl: 'https://platform.ovh.reasoninglayer.ai',
  tenantId: 'your-tenant-uuid',
  auth: { mode: 'cookie' },
});

// 1. Create sorts (using SortBuilder)
const personSort = await client.sorts.createSort(
  SortBuilder.create("person")
    .feature({ name: "name", required: true })
    .feature({ name: "age", required: false, constraint: { type: "Integer" } })
    .build()
);

const employeeSort = await client.sorts.createSort(
  SortBuilder.create("employee")
    .parent(personSort.id)
    .feature({
      name: "salary",
      required: true,
      constraint: { type: "IntegerRange", value: { min: 0, max: 10000000 } },
    })
    .build()
);

// 2. Create terms (using plain values — tagged format auto-converted)
await client.terms.createTerm({
  sortId: personSort.id,
  ownerId: "user-uuid",
  features: {
    name: "Alice",
    age: 30,
  },
});

// 3. Add inference facts (using psi() — untagged format)
await client.inference.addFact({
  term: psi("employee", {
    name: "Alice",
    salary: 120000,
  }),
});

// 4. Add rules with guards
await client.inference.addRule({
  term: psi("high_earner", {
    name: "?Name",
  }),
  antecedents: [
    psi("employee", {
      name: "?Name",
      salary: constrained("?Salary", guard("gt", 100000)),
    }),
  ],
});

// 5. Query (using backward chaining)
const result = await client.inference.backwardChain({
  goal: psi("high_earner", {
    name: "?Name",
  }),
});

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