@henrychong-ai/mcp-neo4j-knowledge-graph 2.7.1 → 2.8.0

package/dist/server/handlers/toolHandlers/updateEntitiesBatch.js

@@ -4,6 +4,7 @@
  * Updates multiple entities in a single optimized batch operation.
  * Provides 10-50x performance improvement over individual updates.
  */
+import { attachWriteWarnings, collectWriteSizeWarnings, extractWrittenNames, } from './writeSizeWarnings.js';
 /**
  * Handle update_entities_batch tool calls
  *
@@ -15,11 +16,14 @@ export async function handleUpdateEntitiesBatch(args,
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 knowledgeGraphManager) {
     const result = await knowledgeGraphManager.updateEntitiesBatch(args.updates, args.config);
+    // Additive, fail-open: flag any entity this write pushed near the open_nodes cap.
+    const warnings = await collectWriteSizeWarnings(knowledgeGraphManager, extractWrittenNames(args));
+    const payload = attachWriteWarnings(result, warnings);
     return {
         content: [
             {
                 type: 'text',
-                text: JSON.stringify(result, null, 2),
+                text: JSON.stringify(payload, null, 2),
             },
         ],
     };

package/dist/server/handlers/toolHandlers/updateEntitiesBatch.js.map

@@ -1 +1 @@
-{"version":3,"file":"updateEntitiesBatch.js","sourceRoot":"","sources":["../../../../src/server/handlers/toolHandlers/updateEntitiesBatch.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC7C,IAA6B;AAC7B,8DAA8D;AAC9D,qBAA0B;IAE1B,MAAM,MAAM,GAAG,MAAM,qBAAqB,CAAC,mBAAmB,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;IAE1F,OAAO;QACL,OAAO,EAAE;YACP;gBACE,IAAI,EAAE,MAAM;gBACZ,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;aACtC;SACF;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"updateEntitiesBatch.js","sourceRoot":"","sources":["../../../../src/server/handlers/toolHandlers/updateEntitiesBatch.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,mBAAmB,EACnB,wBAAwB,EACxB,mBAAmB,GACpB,MAAM,wBAAwB,CAAC;AAEhC;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC7C,IAA6B;AAC7B,8DAA8D;AAC9D,qBAA0B;IAE1B,MAAM,MAAM,GAAG,MAAM,qBAAqB,CAAC,mBAAmB,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;IAE1F,kFAAkF;IAClF,MAAM,QAAQ,GAAG,MAAM,wBAAwB,CAAC,qBAAqB,EAAE,mBAAmB,CAAC,IAAI,CAAC,CAAC,CAAC;IAClG,MAAM,OAAO,GAAG,mBAAmB,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IAEtD,OAAO;QACL,OAAO,EAAE;YACP;gBACE,IAAI,EAAE,MAAM;gBACZ,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;aACvC;SACF;KACF,CAAC;AACJ,CAAC"}

package/dist/server/handlers/toolHandlers/writeSizeWarnings.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Shared helper: non-fatal entity-size warnings for write tools.
+ *
+ * After a batch write, the touched entities are sized with EntitySizeService and
+ * any that cross the WARN/CRITICAL thresholds are returned as an additive
+ * `warnings[]` field on the tool result. This is the earliest possible signal —
+ * it names the offending entity at the moment it grows.
+ *
+ * STRICTLY fail-open: a disabled feature, a sizing error, or a hydration failure
+ * yields an empty list and never disrupts or fails the write.
+ */
+/** A single non-fatal size warning for a written entity. */
+export interface WriteSizeWarning {
+    name: string;
+    estTokens: number;
+    ratio: number;
+    state: 'WARN' | 'CRITICAL';
+    message: string;
+}
+/**
+ * Extract candidate entity names from a write tool's arguments. Handles the
+ * three write shapes: add_observations_batch (observations[].entityName),
+ * update_entities_batch (updates[].name), create_entities_batch (entities[].name).
+ *
+ * @param args Tool arguments
+ * @returns Candidate entity names (possibly with duplicates)
+ */
+export declare function extractWrittenNames(args: Record<string, unknown>): string[];
+/**
+ * Compute non-fatal size warnings for the entities just written.
+ *
+ * @param knowledgeGraphManager Knowledge graph manager instance
+ * @param names Names of the entities that were written
+ * @returns WARN/CRITICAL warnings (empty when disabled or on any error)
+ */
+export declare function collectWriteSizeWarnings(knowledgeGraphManager: any, names: string[]): Promise<WriteSizeWarning[]>;
+/**
+ * Attach size warnings to a write result without mutating existing fields.
+ * Returns the original result unchanged when there are no warnings.
+ *
+ * @param result The batch write result
+ * @param warnings Size warnings to attach
+ * @returns The result, with an additive `warnings` field when applicable
+ */
+export declare function attachWriteWarnings(result: unknown, warnings: WriteSizeWarning[]): unknown;

package/dist/server/handlers/toolHandlers/writeSizeWarnings.js

@@ -0,0 +1,106 @@
+/**
+ * Shared helper: non-fatal entity-size warnings for write tools.
+ *
+ * After a batch write, the touched entities are sized with EntitySizeService and
+ * any that cross the WARN/CRITICAL thresholds are returned as an additive
+ * `warnings[]` field on the tool result. This is the earliest possible signal —
+ * it names the offending entity at the moment it grows.
+ *
+ * STRICTLY fail-open: a disabled feature, a sizing error, or a hydration failure
+ * yields an empty list and never disrupts or fails the write.
+ */
+import { getEntitySizeConfig } from '../../../config/entitySize.js';
+import { estimateEntitySize } from '../../../maintenance/EntitySizeService.js';
+import { logger } from '../../../utils/logger.js';
+/**
+ * Extract candidate entity names from a write tool's arguments. Handles the
+ * three write shapes: add_observations_batch (observations[].entityName),
+ * update_entities_batch (updates[].name), create_entities_batch (entities[].name).
+ *
+ * @param args Tool arguments
+ * @returns Candidate entity names (possibly with duplicates)
+ */
+export function extractWrittenNames(args) {
+    const names = [];
+    const push = (item) => {
+        if (!item || typeof item !== 'object') {
+            return;
+        }
+        const record = item;
+        if (typeof record.name === 'string') {
+            names.push(record.name);
+        }
+        if (typeof record.entityName === 'string') {
+            names.push(record.entityName);
+        }
+    };
+    for (const key of ['observations', 'updates', 'entities']) {
+        const arr = args[key];
+        if (Array.isArray(arr)) {
+            for (const item of arr) {
+                push(item);
+            }
+        }
+    }
+    return names;
+}
+/**
+ * Compute non-fatal size warnings for the entities just written.
+ *
+ * @param knowledgeGraphManager Knowledge graph manager instance
+ * @param names Names of the entities that were written
+ * @returns WARN/CRITICAL warnings (empty when disabled or on any error)
+ */
+export async function collectWriteSizeWarnings(
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+knowledgeGraphManager, names) {
+    try {
+        const cfg = getEntitySizeConfig();
+        if (!cfg.warnOnWrite) {
+            return [];
+        }
+        const unique = [...new Set(names.filter(n => typeof n === 'string' && n.length > 0))];
+        if (unique.length === 0) {
+            return [];
+        }
+        const graph = await knowledgeGraphManager.openNodes(unique);
+        const entities = graph?.entities ?? [];
+        const warnings = [];
+        for (const entity of entities) {
+            const report = estimateEntitySize(entity, cfg);
+            if (report.state === 'OK') {
+                continue;
+            }
+            const pct = Math.round(report.ratio * 100);
+            warnings.push({
+                name: report.name,
+                estTokens: report.estTokens,
+                ratio: Number(report.ratio.toFixed(3)),
+                state: report.state,
+                message: report.state === 'CRITICAL'
+                    ? `Entity "${report.name}" is ~${report.estTokens} tokens, at/above the ~${cfg.maxTokens}-token open_nodes cap — split it into sibling entities now; it may already be unretrievable whole.`
+                    : `Entity "${report.name}" is ~${report.estTokens} tokens (${pct}% of the ~${cfg.maxTokens}-token open_nodes cap) — consider splitting it soon.`,
+            });
+        }
+        return warnings;
+    }
+    catch (error) {
+        logger.warn('collectWriteSizeWarnings failed (non-fatal)', error);
+        return [];
+    }
+}
+/**
+ * Attach size warnings to a write result without mutating existing fields.
+ * Returns the original result unchanged when there are no warnings.
+ *
+ * @param result The batch write result
+ * @param warnings Size warnings to attach
+ * @returns The result, with an additive `warnings` field when applicable
+ */
+export function attachWriteWarnings(result, warnings) {
+    if (warnings.length === 0 || !result || typeof result !== 'object') {
+        return result;
+    }
+    return { ...result, warnings };
+}
+//# sourceMappingURL=writeSizeWarnings.js.map

package/dist/server/handlers/toolHandlers/writeSizeWarnings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"writeSizeWarnings.js","sourceRoot":"","sources":["../../../../src/server/handlers/toolHandlers/writeSizeWarnings.ts"],"names":[],"mappings":"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"}

package/dist/storage/StorageProvider.d.ts

@@ -28,6 +28,23 @@ export interface SearchOptions {
      */
     includeNullDomain?: boolean;
 }
+/**
+ * Compact, cap-safe projection of one entity's approximate serialized size.
+ * Returned by {@link StorageProvider.scanEntitySizes}; never carries full
+ * observation text, so the scan itself can never breach the MCP output cap.
+ */
+export interface EntitySizeScanRow {
+    name: string;
+    entityType: string;
+    /** Approximate serialized characters (observations + structural overhead + relations term). */
+    approxChars: number;
+    /** Approximate characters contributed by observations alone. */
+    obsChars: number;
+    /** Number of observations on the entity. */
+    obsCount: number;
+    /** Number of current relations attached to the entity. */
+    relCount: number;
+}
 /**
  * Interface for storage providers that can load and save knowledge graphs
  */
@@ -56,6 +73,16 @@ export interface StorageProvider {
      * @returns Promise resolving to a KnowledgeGraph containing the specified nodes
      */
     openNodes(names: string[]): Promise<KnowledgeGraph>;
+    /**
+     * Scan current entities ranked by approximate serialized size, largest first.
+     * Computes size in the storage layer and returns only a compact projection
+     * (never full entities), so the scan is immune to the MCP output cap it
+     * polices. Optional — providers that cannot scan efficiently may omit it, and
+     * callers fall back to an in-memory pass.
+     * @param limit Maximum number of (largest) entities to return
+     * @returns Promise resolving to ranked size rows, largest first
+     */
+    scanEntitySizes?(limit: number): Promise<EntitySizeScanRow[]>;
     /**
      * Create new entities in the knowledge graph
      * @param entities Array of entities to create

package/dist/storage/StorageProvider.js.map

@@ -1 +1 @@
-{"version":3,"file":"StorageProvider.js","sourceRoot":"","sources":["../../src/storage/StorageProvider.ts"],"names":[],"mappings":"AAqPA,2EAA2E;AAC3E,6EAA6E;AAC7E,2DAA2D;AAC3D,MAAM,KAAW,eAAe,CAK/B;AALD,WAAiB,eAAe;IAC9B,8DAA8D;IAC9D,SAAgB,iBAAiB,CAAC,GAAQ;QACxC,OAAO,wBAAwB,CAAC,iBAAiB,CAAC,GAAG,CAAC,CAAC;IACzD,CAAC;IAFe,iCAAiB,oBAEhC,CAAA;AACH,CAAC,EALgB,eAAe,KAAf,eAAe,QAK/B;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG;IACtC,kFAAkF;IAClF,qDAAqD;IACrD,8DAA8D;IAC9D,iBAAiB,CAAC,GAAQ;QACxB,MAAM,kBAAkB,GACtB,GAAG;YACH,OAAO,GAAG,CAAC,SAAS,KAAK,UAAU;YACnC,OAAO,GAAG,CAAC,SAAS,KAAK,UAAU;YACnC,OAAO,GAAG,CAAC,WAAW,KAAK,UAAU;YACrC,OAAO,GAAG,CAAC,SAAS,KAAK,UAAU;YACnC,OAAO,GAAG,CAAC,cAAc,KAAK,UAAU;YACxC,OAAO,GAAG,CAAC,eAAe,KAAK,UAAU;YACzC,OAAO,GAAG,CAAC,eAAe,KAAK,UAAU;YACzC,OAAO,GAAG,CAAC,cAAc,KAAK,UAAU;YACxC,OAAO,GAAG,CAAC,kBAAkB,KAAK,UAAU;YAC5C,OAAO,GAAG,CAAC,eAAe,KAAK,UAAU;YACzC,OAAO,GAAG,CAAC,SAAS,KAAK,UAAU,CAAC;QAEtC,6DAA6D;QAC7D,MAAM,oBAAoB,GACxB,CAAC,CAAC,GAAG,CAAC,WAAW,IAAI,OAAO,GAAG,CAAC,WAAW,KAAK,UAAU,CAAC;YAC3D,CAAC,CAAC,GAAG,CAAC,cAAc,IAAI,OAAO,GAAG,CAAC,cAAc,KAAK,UAAU,CAAC;YACjE,CAAC,CAAC,GAAG,CAAC,gBAAgB,IAAI,OAAO,GAAG,CAAC,gBAAgB,KAAK,UAAU,CAAC;YACrE,CAAC,CAAC,GAAG,CAAC,kBAAkB,IAAI,OAAO,GAAG,CAAC,kBAAkB,KAAK,UAAU,CAAC;YACzE,CAAC,CAAC,GAAG,CAAC,cAAc,IAAI,OAAO,GAAG,CAAC,cAAc,KAAK,UAAU,CAAC;YACjE,CAAC,CAAC,GAAG,CAAC,eAAe,IAAI,OAAO,GAAG,CAAC,eAAe,KAAK,UAAU,CAAC;YACnE,CAAC,CAAC,GAAG,CAAC,qBAAqB,IAAI,OAAO,GAAG,CAAC,qBAAqB,KAAK,UAAU,CAAC;YAC/E,CAAC,CAAC,GAAG,CAAC,mBAAmB,IAAI,OAAO,GAAG,CAAC,mBAAmB,KAAK,UAAU,CAAC;YAC3E,CAAC,CAAC,GAAG,CAAC,cAAc,IAAI,OAAO,GAAG,CAAC,cAAc,KAAK,UAAU,CAAC,CAAC;QAEpE,OAAO,kBAAkB,IAAI,oBAAoB,CAAC;IACpD,CAAC;CACF,CAAC"}
+{"version":3,"file":"StorageProvider.js","sourceRoot":"","sources":["../../src/storage/StorageProvider.ts"],"names":[],"mappings":"AAkRA,2EAA2E;AAC3E,6EAA6E;AAC7E,2DAA2D;AAC3D,MAAM,KAAW,eAAe,CAK/B;AALD,WAAiB,eAAe;IAC9B,8DAA8D;IAC9D,SAAgB,iBAAiB,CAAC,GAAQ;QACxC,OAAO,wBAAwB,CAAC,iBAAiB,CAAC,GAAG,CAAC,CAAC;IACzD,CAAC;IAFe,iCAAiB,oBAEhC,CAAA;AACH,CAAC,EALgB,eAAe,KAAf,eAAe,QAK/B;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG;IACtC,kFAAkF;IAClF,qDAAqD;IACrD,8DAA8D;IAC9D,iBAAiB,CAAC,GAAQ;QACxB,MAAM,kBAAkB,GACtB,GAAG;YACH,OAAO,GAAG,CAAC,SAAS,KAAK,UAAU;YACnC,OAAO,GAAG,CAAC,SAAS,KAAK,UAAU;YACnC,OAAO,GAAG,CAAC,WAAW,KAAK,UAAU;YACrC,OAAO,GAAG,CAAC,SAAS,KAAK,UAAU;YACnC,OAAO,GAAG,CAAC,cAAc,KAAK,UAAU;YACxC,OAAO,GAAG,CAAC,eAAe,KAAK,UAAU;YACzC,OAAO,GAAG,CAAC,eAAe,KAAK,UAAU;YACzC,OAAO,GAAG,CAAC,cAAc,KAAK,UAAU;YACxC,OAAO,GAAG,CAAC,kBAAkB,KAAK,UAAU;YAC5C,OAAO,GAAG,CAAC,eAAe,KAAK,UAAU;YACzC,OAAO,GAAG,CAAC,SAAS,KAAK,UAAU,CAAC;QAEtC,6DAA6D;QAC7D,MAAM,oBAAoB,GACxB,CAAC,CAAC,GAAG,CAAC,WAAW,IAAI,OAAO,GAAG,CAAC,WAAW,KAAK,UAAU,CAAC;YAC3D,CAAC,CAAC,GAAG,CAAC,cAAc,IAAI,OAAO,GAAG,CAAC,cAAc,KAAK,UAAU,CAAC;YACjE,CAAC,CAAC,GAAG,CAAC,gBAAgB,IAAI,OAAO,GAAG,CAAC,gBAAgB,KAAK,UAAU,CAAC;YACrE,CAAC,CAAC,GAAG,CAAC,kBAAkB,IAAI,OAAO,GAAG,CAAC,kBAAkB,KAAK,UAAU,CAAC;YACzE,CAAC,CAAC,GAAG,CAAC,cAAc,IAAI,OAAO,GAAG,CAAC,cAAc,KAAK,UAAU,CAAC;YACjE,CAAC,CAAC,GAAG,CAAC,eAAe,IAAI,OAAO,GAAG,CAAC,eAAe,KAAK,UAAU,CAAC;YACnE,CAAC,CAAC,GAAG,CAAC,qBAAqB,IAAI,OAAO,GAAG,CAAC,qBAAqB,KAAK,UAAU,CAAC;YAC/E,CAAC,CAAC,GAAG,CAAC,mBAAmB,IAAI,OAAO,GAAG,CAAC,mBAAmB,KAAK,UAAU,CAAC;YAC3E,CAAC,CAAC,GAAG,CAAC,cAAc,IAAI,OAAO,GAAG,CAAC,cAAc,KAAK,UAAU,CAAC,CAAC;QAEpE,OAAO,kBAAkB,IAAI,oBAAoB,CAAC;IACpD,CAAC;CACF,CAAC"}

package/dist/storage/neo4j/Neo4jStorageProvider.d.ts

@@ -3,7 +3,7 @@ import { type HybridSearchConfig } from '../../retrieval/index.js';
 import type { BatchConfig, BatchResult, ObservationBatch, EntityUpdate } from '../../types/batch-operations.js';
 import type { EntityEmbedding, SemanticSearchOptions } from '../../types/entity-embedding.js';
 import type { Relation } from '../../types/relation.js';
-import type { StorageProvider, SearchOptions } from '../StorageProvider.js';
+import type { StorageProvider, SearchOptions, EntitySizeScanRow } from '../StorageProvider.js';
 import { type Neo4jConfig } from './Neo4jConfig.js';
 import { Neo4jConnectionManager } from './Neo4jConnectionManager.js';
 /**
@@ -141,6 +141,19 @@ export declare class Neo4jStorageProvider implements StorageProvider {
      * @param names Array of node names to open
      */
     openNodes(names: string[]): Promise<KnowledgeGraph>;
+    /**
+     * Scan current entities ranked by approximate serialized size, largest first.
+     *
+     * Size is computed entirely in Cypher and only a compact projection is
+     * returned (name, type, char/observation/relation counts) — never full
+     * entities — so this scan can never itself breach the MCP output cap it
+     * exists to police. Observations may be stored as a JSON string or a list;
+     * both forms are handled via valueType() (Neo4j 5.13+).
+     *
+     * @param limit Maximum number of (largest) entities to return
+     * @returns Ranked size rows, largest approxChars first
+     */
+    scanEntitySizes(limit: number): Promise<EntitySizeScanRow[]>;
     /**
      * Create new entities in the knowledge graph
      * @param entities Array of entities to create

package/dist/storage/neo4j/Neo4jStorageProvider.js

@@ -596,6 +596,76 @@ export class Neo4jStorageProvider {
             throw error;
         }
     }
+    /**
+     * Scan current entities ranked by approximate serialized size, largest first.
+     *
+     * Size is computed entirely in Cypher and only a compact projection is
+     * returned (name, type, char/observation/relation counts) — never full
+     * entities — so this scan can never itself breach the MCP output cap it
+     * exists to police. Observations may be stored as a JSON string or a list;
+     * both forms are handled via valueType() (Neo4j 5.13+).
+     *
+     * @param limit Maximum number of (largest) entities to return
+     * @returns Ranked size rows, largest approxChars first
+     */
+    async scanEntitySizes(limit) {
+        const safeLimit = Number.isFinite(limit) && limit > 0 ? Math.floor(limit) : 50;
+        // obsChars: characters contributed by observations, deliberately biased HIGH
+        //   so a many-short-observation entity (whose real open_nodes JSON carries
+        //   large per-line indentation overhead) is not ranked below the top-N and
+        //   missed. String form => its JSON length + ~10 chars/element for the
+        //   pretty-print indentation the raw string omits; list form => sum of
+        //   element lengths + ~12 chars/element (8-space indent + quotes + comma).
+        //   coalesce guards a null element (which would null the whole rank, and
+        //   Neo4j sorts nulls FIRST, spuriously promoting it). obsCount is the
+        //   element count for both forms (string form approximated via split).
+        // approxChars: obsChars + a fixed structural/metadata overhead + a small
+        //   per-relation term. Only used for RANKING; precise sizing is refined
+        //   against the real entity for the returned top-N.
+        const query = `
+      MATCH (e:Entity)
+      WHERE e.validTo IS NULL
+      WITH e,
+        CASE
+          WHEN e.observations IS NULL THEN 0
+          WHEN valueType(e.observations) STARTS WITH 'STRING'
+            THEN size(e.observations) + (size(split(e.observations, '","')) * 10)
+          WHEN valueType(e.observations) STARTS WITH 'LIST'
+            THEN reduce(s = 0, o IN e.observations | s + size(coalesce(toString(o), '')) + 12)
+          ELSE 0
+        END AS obsChars,
+        CASE
+          WHEN e.observations IS NULL THEN 0
+          WHEN valueType(e.observations) STARTS WITH 'LIST' THEN size(e.observations)
+          WHEN valueType(e.observations) STARTS WITH 'STRING' THEN size(split(e.observations, '","'))
+          ELSE 0
+        END AS obsCount
+      OPTIONAL MATCH (e)-[r:RELATES_TO]-(:Entity)
+      WHERE r.validTo IS NULL
+      WITH e, obsChars, obsCount, count(DISTINCT r) AS relCount
+      RETURN
+        e.name AS name,
+        e.entityType AS entityType,
+        obsChars AS obsChars,
+        obsCount AS obsCount,
+        relCount AS relCount,
+        (obsChars + 200 + relCount * 8) AS approxChars
+      ORDER BY approxChars DESC
+      LIMIT toInteger($limit)
+    `;
+        const result = await this.connectionManager.executeQuery(query, { limit: safeLimit });
+        return result.records.map(record => {
+            const toNum = (value) => Number(this.convertNeo4jInt(value) ?? 0);
+            return {
+                name: record.get('name'),
+                entityType: record.get('entityType') ?? '',
+                approxChars: toNum(record.get('approxChars')),
+                obsChars: toNum(record.get('obsChars')),
+                obsCount: toNum(record.get('obsCount')),
+                relCount: toNum(record.get('relCount')),
+            };
+        });
+    }
     /**
      * Create new entities in the knowledge graph
      * @param entities Array of entities to create