@kortexya/reasoninglayer 0.12.1 → 0.13.0

package/dist/index.d.cts

@@ -109,7 +109,7 @@ type JsonValue$1 = string | number | boolean | null | JsonValue$1[] | object;
  * This is the single source of truth for the version constant.
  * The `scripts/release.sh` script updates this value alongside `package.json`.
  */
-declare const SDK_VERSION = "0.12.1";
+declare const SDK_VERSION = "0.13.0";
 /**
  * Configuration for the Reasoning Layer client.
  *
@@ -18582,14 +18582,50 @@ declare namespace homoiconic {
  * await client.inference.addFact({ term: psi("person", { name: "Alice" }) });
  * ```
  */
-interface PsiTermInput {
+/**
+ * A psi-term identified by sort name.
+ */
+interface PsiTermInputByName {
     /** @internal Brand field to distinguish from plain objects. Stripped before serialization. */
     readonly __psiTerm: true;
-    /** Sort name for this term. */
+    /** Sort name for this term (resolved server-side). */
     readonly sortName: string;
     /** Features using plain JavaScript values. */
     readonly features?: PlainFeatureMap;
 }
+/**
+ * A psi-term identified by sort ID (UUID).
+ */
+interface PsiTermInputById {
+    /** @internal Brand field to distinguish from plain objects. Stripped before serialization. */
+    readonly __psiTerm: true;
+    /** Sort ID (UUID) for this term. */
+    readonly sortId: string;
+    /** Features using plain JavaScript values. */
+    readonly features?: PlainFeatureMap;
+}
+/**
+ * A format-agnostic psi-term produced by the `psi()` builder.
+ *
+ * @remarks
+ * Exactly one of `sortName` or `sortId` is present — enforced by the union type.
+ * Can be passed to both term CRUD methods (converted to tagged `ValueDto` format)
+ * and inference methods (converted to untagged `TermInputDto` format).
+ * The SDK handles the conversion automatically based on which method receives it.
+ *
+ * Distinguished from plain objects by the `__psiTerm` brand field, which is
+ * stripped before serialization.
+ *
+ * @example
+ * ```typescript
+ * // Works with term CRUD:
+ * await client.terms.createTerm({ sortId, ownerId, features: { name: "Alice" } });
+ *
+ * // Works with inference:
+ * await client.inference.addFact({ term: psi("person", { name: "Alice" }) });
+ * ```
+ */
+type PsiTermInput = PsiTermInputByName | PsiTermInputById;
 /**
  * A constrained variable for use in inference contexts.
  *
@@ -18662,9 +18698,11 @@ type plainValues_ConstrainedPlainVar = ConstrainedPlainVar;
 type plainValues_PlainFeatureMap = PlainFeatureMap;
 type plainValues_PlainFeatureValue = PlainFeatureValue;
 type plainValues_PsiTermInput = PsiTermInput;
+type plainValues_PsiTermInputById = PsiTermInputById;
+type plainValues_PsiTermInputByName = PsiTermInputByName;
 type plainValues_TermInputArg = TermInputArg;
 declare namespace plainValues {
-  export type { plainValues_ConstrainedPlainVar as ConstrainedPlainVar, plainValues_PlainFeatureMap as PlainFeatureMap, plainValues_PlainFeatureValue as PlainFeatureValue, plainValues_PsiTermInput as PsiTermInput, plainValues_TermInputArg as TermInputArg };
+  export type { plainValues_ConstrainedPlainVar as ConstrainedPlainVar, plainValues_PlainFeatureMap as PlainFeatureMap, plainValues_PlainFeatureValue as PlainFeatureValue, plainValues_PsiTermInput as PsiTermInput, plainValues_PsiTermInputById as PsiTermInputById, plainValues_PsiTermInputByName as PsiTermInputByName, plainValues_TermInputArg as TermInputArg };
 }
 
 /**
@@ -40745,7 +40783,7 @@ declare class SortBuilder {
 }
 
 /**
- * Create a format-agnostic psi-term that the SDK converts to the correct wire format.
+ * Create a format-agnostic psi-term identified by sort name.
  *
  * @param sortName - The sort name (resolved server-side).
  * @param features - Optional features map using plain JavaScript values.
@@ -40773,12 +40811,6 @@ declare class SortBuilder {
  * // With variable (auto-detected "?" prefix):
  * const query = psi("person", { name: "?Name", age: "?Age" });
  *
- * // With constrained variable:
- * const eligible = psi("eligible", {
- *   applicant: "?A",
- *   score: constrained("?S", guard("gt", 700)),
- * });
- *
  * // Nested psi-terms:
  * const company = psi("company", {
  *   name: "Acme",
@@ -40791,10 +40823,35 @@ declare class SortBuilder {
  * // Term reference (auto-detected "!" prefix):
  * const withRef = psi("department", { manager: "!550e8400-..." });
  * ```
+ */
+declare function psi(sortName: string, features?: Record<string, unknown>): PsiTermInputByName;
+/**
+ * Create a format-agnostic psi-term identified by sort ID.
  *
- * @throws {ValidationError} If the sort name is empty.
+ * @param sort - Object with `sortId` (UUID).
+ * @param features - Optional features map using plain JavaScript values.
+ * @returns A `PsiTermInput` that can be used with both term CRUD and inference methods.
+ *
+ * @remarks
+ * Use this overload when you have a sort ID from a runtime lookup (e.g., `listSorts()`
+ * after LLM-based ingestion) and don't have the sort name.
+ *
+ * @example
+ * ```typescript
+ * import { psi } from '@kortexya/reasoninglayer';
+ *
+ * // By sort ID:
+ * const term = psi({ sortId: "550e8400-e29b-41d4-a716-446655440000" }, { name: "Alice" });
+ *
+ * // From a runtime lookup:
+ * const sorts = await client.sorts.listSorts();
+ * const personSort = sorts.items.find(s => s.name === "person");
+ * const query = psi({ sortId: personSort.sortId }, { name: "?Name" });
+ * ```
  */
-declare function psi(sortName: string, features?: Record<string, unknown>): PsiTermInput;
+declare function psi(sort: {
+    sortId: string;
+}, features?: Record<string, unknown>): PsiTermInputById;
 /**
  * Create a constrained variable for use in `psi()` features.
  *

package/dist/index.d.ts

@@ -109,7 +109,7 @@ type JsonValue$1 = string | number | boolean | null | JsonValue$1[] | object;
  * This is the single source of truth for the version constant.
  * The `scripts/release.sh` script updates this value alongside `package.json`.
  */
-declare const SDK_VERSION = "0.12.1";
+declare const SDK_VERSION = "0.13.0";
 /**
  * Configuration for the Reasoning Layer client.
  *
@@ -18582,14 +18582,50 @@ declare namespace homoiconic {
  * await client.inference.addFact({ term: psi("person", { name: "Alice" }) });
  * ```
  */
-interface PsiTermInput {
+/**
+ * A psi-term identified by sort name.
+ */
+interface PsiTermInputByName {
     /** @internal Brand field to distinguish from plain objects. Stripped before serialization. */
     readonly __psiTerm: true;
-    /** Sort name for this term. */
+    /** Sort name for this term (resolved server-side). */
     readonly sortName: string;
     /** Features using plain JavaScript values. */
     readonly features?: PlainFeatureMap;
 }
+/**
+ * A psi-term identified by sort ID (UUID).
+ */
+interface PsiTermInputById {
+    /** @internal Brand field to distinguish from plain objects. Stripped before serialization. */
+    readonly __psiTerm: true;
+    /** Sort ID (UUID) for this term. */
+    readonly sortId: string;
+    /** Features using plain JavaScript values. */
+    readonly features?: PlainFeatureMap;
+}
+/**
+ * A format-agnostic psi-term produced by the `psi()` builder.
+ *
+ * @remarks
+ * Exactly one of `sortName` or `sortId` is present — enforced by the union type.
+ * Can be passed to both term CRUD methods (converted to tagged `ValueDto` format)
+ * and inference methods (converted to untagged `TermInputDto` format).
+ * The SDK handles the conversion automatically based on which method receives it.
+ *
+ * Distinguished from plain objects by the `__psiTerm` brand field, which is
+ * stripped before serialization.
+ *
+ * @example
+ * ```typescript
+ * // Works with term CRUD:
+ * await client.terms.createTerm({ sortId, ownerId, features: { name: "Alice" } });
+ *
+ * // Works with inference:
+ * await client.inference.addFact({ term: psi("person", { name: "Alice" }) });
+ * ```
+ */
+type PsiTermInput = PsiTermInputByName | PsiTermInputById;
 /**
  * A constrained variable for use in inference contexts.
  *
@@ -18662,9 +18698,11 @@ type plainValues_ConstrainedPlainVar = ConstrainedPlainVar;
 type plainValues_PlainFeatureMap = PlainFeatureMap;
 type plainValues_PlainFeatureValue = PlainFeatureValue;
 type plainValues_PsiTermInput = PsiTermInput;
+type plainValues_PsiTermInputById = PsiTermInputById;
+type plainValues_PsiTermInputByName = PsiTermInputByName;
 type plainValues_TermInputArg = TermInputArg;
 declare namespace plainValues {
-  export type { plainValues_ConstrainedPlainVar as ConstrainedPlainVar, plainValues_PlainFeatureMap as PlainFeatureMap, plainValues_PlainFeatureValue as PlainFeatureValue, plainValues_PsiTermInput as PsiTermInput, plainValues_TermInputArg as TermInputArg };
+  export type { plainValues_ConstrainedPlainVar as ConstrainedPlainVar, plainValues_PlainFeatureMap as PlainFeatureMap, plainValues_PlainFeatureValue as PlainFeatureValue, plainValues_PsiTermInput as PsiTermInput, plainValues_PsiTermInputById as PsiTermInputById, plainValues_PsiTermInputByName as PsiTermInputByName, plainValues_TermInputArg as TermInputArg };
 }
 
 /**
@@ -40745,7 +40783,7 @@ declare class SortBuilder {
 }
 
 /**
- * Create a format-agnostic psi-term that the SDK converts to the correct wire format.
+ * Create a format-agnostic psi-term identified by sort name.
  *
  * @param sortName - The sort name (resolved server-side).
  * @param features - Optional features map using plain JavaScript values.
@@ -40773,12 +40811,6 @@ declare class SortBuilder {
  * // With variable (auto-detected "?" prefix):
  * const query = psi("person", { name: "?Name", age: "?Age" });
  *
- * // With constrained variable:
- * const eligible = psi("eligible", {
- *   applicant: "?A",
- *   score: constrained("?S", guard("gt", 700)),
- * });
- *
  * // Nested psi-terms:
  * const company = psi("company", {
  *   name: "Acme",
@@ -40791,10 +40823,35 @@ declare class SortBuilder {
  * // Term reference (auto-detected "!" prefix):
  * const withRef = psi("department", { manager: "!550e8400-..." });
  * ```
+ */
+declare function psi(sortName: string, features?: Record<string, unknown>): PsiTermInputByName;
+/**
+ * Create a format-agnostic psi-term identified by sort ID.
  *
- * @throws {ValidationError} If the sort name is empty.
+ * @param sort - Object with `sortId` (UUID).
+ * @param features - Optional features map using plain JavaScript values.
+ * @returns A `PsiTermInput` that can be used with both term CRUD and inference methods.
+ *
+ * @remarks
+ * Use this overload when you have a sort ID from a runtime lookup (e.g., `listSorts()`
+ * after LLM-based ingestion) and don't have the sort name.
+ *
+ * @example
+ * ```typescript
+ * import { psi } from '@kortexya/reasoninglayer';
+ *
+ * // By sort ID:
+ * const term = psi({ sortId: "550e8400-e29b-41d4-a716-446655440000" }, { name: "Alice" });
+ *
+ * // From a runtime lookup:
+ * const sorts = await client.sorts.listSorts();
+ * const personSort = sorts.items.find(s => s.name === "person");
+ * const query = psi({ sortId: personSort.sortId }, { name: "?Name" });
+ * ```
  */
-declare function psi(sortName: string, features?: Record<string, unknown>): PsiTermInput;
+declare function psi(sort: {
+    sortId: string;
+}, features?: Record<string, unknown>): PsiTermInputById;
 /**
  * Create a constrained variable for use in `psi()` features.
  *

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/config.ts
-var SDK_VERSION = "0.12.1";
+var SDK_VERSION = "0.13.0";
 function resolveConfig(config) {
   if (!config.baseUrl) {
     throw new Error("ClientConfig.baseUrl is required");
@@ -8521,11 +8521,12 @@ function toUntaggedValue(value) {
     return { name: value.name, constraint };
   }
   if (isPsiTermInput(value)) {
+    const sortKey = "sortId" in value && value.sortId ? { sortId: value.sortId } : { sortName: value.sortName };
     if (!value.features) {
-      return { sortName: value.sortName };
+      return sortKey;
     }
     return {
-      sortName: value.sortName,
+      ...sortKey,
       features: toUntaggedFeatures(value.features)
     };
   }
@@ -8545,13 +8546,12 @@ function toTermInputDto(input) {
   if (!isPsiTermInput(input)) {
     return input;
   }
-  if (!input.features) {
-    return { sortName: input.sortName };
+  const features = input.features ? toUntaggedFeatures(input.features) : void 0;
+  if ("sortId" in input && input.sortId) {
+    return { sortId: input.sortId, features: features ?? {} };
   }
-  return {
-    sortName: input.sortName,
-    features: toUntaggedFeatures(input.features)
-  };
+  const { sortName } = input;
+  return features ? { sortName, features } : { sortName };
 }
 
 // src/normalizers/values.ts
@@ -22466,13 +22466,23 @@ var SortBuilder = class _SortBuilder {
 };
 
 // src/builders/psi.ts
-function psi(sortName, features) {
+function psi(sortOrName, features) {
+  if (typeof sortOrName === "string") {
+    if (!features) {
+      return { __psiTerm: true, sortName: sortOrName };
+    }
+    return {
+      __psiTerm: true,
+      sortName: sortOrName,
+      features
+    };
+  }
   if (!features) {
-    return { __psiTerm: true, sortName };
+    return { __psiTerm: true, sortId: sortOrName.sortId };
   }
   return {
     __psiTerm: true,
-    sortName,
+    sortId: sortOrName.sortId,
     features
   };
 }