Values and Formats

The Reasoning Layer backend uses two different serialization formats for values depending on the endpoint. Understanding when to use each format is the single most important thing to get right when working with this SDK.

The two formats

Tagged format (ValueDto)

Used by term CRUD, queries, and fuzzy operations. Values carry an explicit "type" discriminator:

{"type": "String", "value": "hello"}
{"type": "Integer", "value": 42}
{"type": "Real", "value": 3.14}
{"type": "Boolean", "value": true}
{"type": "Uninstantiated"}
{"type": "Reference", "value": "550e8400-e29b-41d4-a716-446655440000"}
{"type": "List", "value": [{"type": "Integer", "value": 1}, {"type": "Integer", "value": 2}]}

For simple types, pass plain JS values directly — the SDK auto-converts them:

// Plain values (no builder needed — auto-converted by SDK):
const features = {
  name: "Alice",                   // -> {"type": "String", "value": "Alice"}
  age: 30,                         // -> {"type": "Integer", "value": 30}
  score: 0.95,                     // -> {"type": "Real", "value": 0.95}
  active: true,                    // -> {"type": "Boolean", "value": true}
  pending: null,                   // -> {"type": "Uninstantiated"}
};

For complex types that have no plain JS equivalent, use the Value namespace:

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

const complexFeatures = {
  mentor: Value.reference(mentorId), // {"type": "Reference", "value": "uuid"}
};

Untagged format (FeatureInputValueDto)

Used by homoiconic inference endpoints (backward chaining, forward chaining, fuzzy proving, etc.). Values are raw JSON primitives with no discriminator:

"hello"
42
3.14
true
null
["550e8400-...", "660f9500-..."]

Build untagged inputs with psi() and plain JS values:

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

// Plain values used directly inside psi():
const fact = psi("person", {
  name: "Alice",          // "Alice"
  age: 30,                // 30
  score: 0.95,            // 0.95
  active: true,           // true
});

// Variables — strings starting with "?" are auto-detected:
const query = psi("person", {
  name: "?Name",          // {name: "?Name"}
  role: "?Role",          // {name: "?Role"}
});

// Term references — strings starting with "!" are auto-detected:
const withRef = psi("team", {
  lead: "!550e8400-...",  // {termId: "550e8400-..."}
});

The untagged format also supports structural variants:

// Constrained variable
constrained("?Salary", guard("gt", 50000))
// {name: "?Salary", constraint: {sortName: "guard_constraint", features: {op: "gt", right: 50000}}}

// Inline term by sort name (nested psi-terms)
psi("address", {
  city: "Paris",
})
// {sortName: "address", features: {city: "Paris"}}

// List
["a", "b"]
// ["a", "b"]

Which format for which endpoint

Endpoint domain	Format	Builder	Type
Term CRUD	Tagged	Plain values or `Value.*`	`ValueDto`
Queries	Tagged	Plain values or `Value.*`	`ValueDto`
Fuzzy operations	Tagged	Plain values or `Value.*`	`ValueDto`
Backward chaining	Untagged	`psi()`, plain values	`FeatureInputValueDto`
Forward chaining	Untagged	`psi()`, plain values	`FeatureInputValueDto`
Add rule	Untagged	`psi()`, plain values	`FeatureInputValueDto`
Add fact	Untagged	`psi()`, plain values	`FeatureInputValueDto`
Fuzzy proving	Untagged	`psi()`, plain values	`FeatureInputValueDto`
Bayesian prediction	Untagged	`psi()`, plain values	`FeatureInputValueDto`
NAF proving	Untagged	`psi()`, plain values	`FeatureInputValueDto`

The rule of thumb: client.terms.* and client.query.* use plain values or Value.*. client.inference.* uses psi() with plain values.

FuzzyShapeDto uses “kind”, not “type”

Fuzzy membership function shapes use "kind" as their discriminator field, not "type". This is different from every other tagged union in the API:

{"kind": "Triangular", "a": 20, "b": 22, "c": 24}
{"kind": "Trapezoidal", "a": 18, "b": 20, "c": 24, "d": 26}
{"kind": "Gaussian", "mean": 100, "stdDev": 15}
{"kind": "CyclicGaussian", "mean": 180, "stdDev": 30, "period": 360}

Build fuzzy shapes with the FuzzyShape namespace and combine with Value.fuzzyNumber():

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

const temperature = Value.fuzzyNumber(FuzzyShape.triangular(20, 22, 24));
// {"type": "FuzzyNumber", "value": {"shape": {"kind": "Triangular", "a": 20, "b": 22, "c": 24}}}

const iq = Value.fuzzyNumber(FuzzyShape.gaussian(100, 15));
// {"type": "FuzzyNumber", "value": {"shape": {"kind": "Gaussian", "mean": 100, "stdDev": 15}}}

Common mistakes

Mistake 1: Using Value builders in inference requests

// WRONG: Value.reference() produces tagged format, but inference expects untagged
await client.inference.addFact({
  term: psi("person", {
    name: Value.reference("some-uuid"),  // This produces {"type": "Reference", "value": "uuid"}
  }),                                     // The backend expects just {termId: "uuid"}
});

// CORRECT: Use plain values or "!" prefix for inference
await client.inference.addFact({
  term: psi("person", {
    name: "Alice",  // Plain string is used directly
  }),
});

Mistake 2: Using psi() in term CRUD

// WRONG: psi() is for inference, not term CRUD
await client.terms.createTerm({
  sortId: personSortId,
  ownerId: userId,
  features: {
    name: psi("person"),  // This is a PsiTermInput, not a ValueDto
  },
});

// CORRECT: Use plain values for term CRUD
await client.terms.createTerm({
  sortId: personSortId,
  ownerId: userId,
  features: {
    name: "Alice",  // Auto-converted to {"type": "String", "value": "Alice"}
  },
});

Mistake 3: Confusing “kind” with “type” on fuzzy shapes

// WRONG: Using "type" instead of "kind" for fuzzy shapes
const shape = { type: "Triangular", a: 20, b: 22, c: 24 };

// CORRECT: FuzzyShapeDto uses "kind" discriminator
const shape = FuzzyShape.triangular(20, 22, 24);
// Produces: { kind: "Triangular", a: 20, b: 22, c: 24 }

Value fallback stringification

The backend may convert domain-internal value types (BigInteger, DateTime, Geometry, Measurement, etc.) to ValueDto::String using Rust’s debug format. When reading term features, you may encounter strings like:

"DateTime(2024-01-15T10:30:00Z)"
"BigInteger(99999999999999999999)"
"Geometry(Point(1.0, 2.0))"

These are not first-class ValueDto variants. They are the result of a fallback String(format!("{:?}", value)) conversion in the backend. If you encounter these patterns, the underlying value was a domain type that the SDK does not model with a dedicated variant.

All ValueDto variants

The tagged ValueDto union has 10 variants:

Variant	Builder	JSON output
String	`"hello"` (plain)	`{"type": "String", "value": "hello"}`
Integer	`42` (plain)	`{"type": "Integer", "value": 42}`
Real	`3.14` (plain)	`{"type": "Real", "value": 3.14}`
Boolean	`true` (plain)	`{"type": "Boolean", "value": true}`
Uninstantiated	`null` (plain)	`{"type": "Uninstantiated"}`
Reference	`Value.reference(uuid)`	`{"type": "Reference", "value": "uuid"}`
List	`[...]` (plain)	`{"type": "List", "value": [...]}`
FuzzyScalar	`Value.fuzzyScalar(0.5, 0.8)`	`{"type": "FuzzyScalar", "value": {"value": 0.5, "membership": 0.8}}`
FuzzyNumber	`Value.fuzzyNumber(shape)`	`{"type": "FuzzyNumber", "value": {"shape": {...}}}`
Set	`Value.set(lower, upper, sort?)`	`{"type": "Set", "value": {"lower": [...], "upper": [...], "sortConstraint": ...}}`

All FeatureInputValueDto variants

The untagged FeatureInputValueDto union has 10 structural variants. The ordering matches the Rust serde(untagged) deserialization order:

#	Variant	Builder / value	JSON output
1	TermRef	`"!uuid"` in `psi()` or `{termId: "uuid"}`	`{"termId": "uuid"}`
2	ConstrainedVariable	`constrained("?X", constraint)`	`{"name": "?X", "constraint": {...}}`
3	Variable	`"?X"` in `psi()`	`{"name": "?X"}`
4	InlineTerm	`{sortId: "uuid", features: {...}}`	`{"sortId": "uuid", "features": {...}}`
5	InlineTermByName	`psi("person", features)`	`{"sortName": "person", "features": {...}}`
6	List	`[...]`	`[...]`
7	String	`"hello"`	`"hello"`
8	Integer	`42`	`42`
9	Real	`3.14`	`3.14`
10	Boolean	`true`	`true`

The ConstrainedVariable variant must come before Variable in the deserialization order because both have a name field, but the constrained version also has constraint. The SDK builders ensure correct construction.