@pyxmate/memory 1.17.15 → 1.17.16

package/dist/chunk-34MTVIYK.mjs

@@ -0,0 +1,109 @@
+// ../shared/src/graph/extraction.ts
+function normalizeGraphLabel(value, fallback) {
+  const normalized = value.trim().toUpperCase().replace(/[^A-Z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+  return normalized.length > 0 ? normalized : fallback;
+}
+function normalizeNameKey(name) {
+  return name.trim().toLowerCase().replace(/\s+/g, " ");
+}
+function requireGraphRecord(value, field) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${field} must be an object`);
+  }
+  return value;
+}
+function requireNonemptyGraphString(value, field) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(`${field} must be a non-empty string`);
+  }
+  return value;
+}
+function assertGraphExtractionPayload(value, field = "graph extraction payload") {
+  const record = requireGraphRecord(value, field);
+  if (!Array.isArray(record.entities)) throw new Error(`${field}.entities must be an array`);
+  if (!Array.isArray(record.relationships)) {
+    throw new Error(`${field}.relationships must be an array`);
+  }
+  const entities = record.entities.map((item, index) => {
+    const entity = requireGraphRecord(item, `${field}.entities[${index}]`);
+    requireNonemptyGraphString(entity.name, `${field}.entities[${index}].name`);
+    requireNonemptyGraphString(entity.type, `${field}.entities[${index}].type`);
+    if (entity.properties !== void 0 && (!entity.properties || typeof entity.properties !== "object" || Array.isArray(entity.properties))) {
+      throw new Error(`${field}.entities[${index}].properties must be an object`);
+    }
+    return item;
+  });
+  const entityNames = new Set(entities.map((entity) => normalizeNameKey(entity.name)));
+  const relationships = record.relationships.map((item, index) => {
+    const relationship = requireGraphRecord(item, `${field}.relationships[${index}]`);
+    const source = requireNonemptyGraphString(
+      relationship.source,
+      `${field}.relationships[${index}].source`
+    );
+    const target = requireNonemptyGraphString(
+      relationship.target,
+      `${field}.relationships[${index}].target`
+    );
+    requireNonemptyGraphString(relationship.type, `${field}.relationships[${index}].type`);
+    if (!entityNames.has(normalizeNameKey(source)) || !entityNames.has(normalizeNameKey(target))) {
+      throw new Error(
+        `${field}.relationships[${index}] endpoints must reference declared entity names`
+      );
+    }
+    if (relationship.properties !== void 0 && (!relationship.properties || typeof relationship.properties !== "object" || Array.isArray(relationship.properties))) {
+      throw new Error(`${field}.relationships[${index}].properties must be an object`);
+    }
+    return item;
+  });
+  return { entities, relationships };
+}
+function relationshipKey(relationship) {
+  return [
+    relationship.source.trim().toLowerCase(),
+    relationship.target.trim().toLowerCase(),
+    normalizeGraphLabel(relationship.type, "RELATED_TO")
+  ].join("\0");
+}
+function mergeExtractedEntities(callerEntities, callerRelationships, extracted) {
+  const entities = [...callerEntities ?? []];
+  const relationships = [...callerRelationships ?? []];
+  const nameByLowercase = /* @__PURE__ */ new Map();
+  for (const entity of entities) {
+    const key = entity.name.toLowerCase();
+    if (!nameByLowercase.has(key)) nameByLowercase.set(key, entity.name);
+  }
+  for (const entity of extracted.entities) {
+    const key = entity.name.toLowerCase();
+    if (nameByLowercase.has(key)) continue;
+    entities.push({ ...entity, type: normalizeGraphLabel(entity.type, "CONCEPT") });
+    nameByLowercase.set(key, entity.name);
+  }
+  for (const relationship of extracted.relations) {
+    const source = nameByLowercase.get(relationship.source.toLowerCase());
+    const target = nameByLowercase.get(relationship.target.toLowerCase());
+    if (source && target) {
+      relationships.push({
+        ...relationship,
+        source,
+        target,
+        type: normalizeGraphLabel(relationship.type, "RELATED_TO")
+      });
+    }
+  }
+  const seenRelationships = /* @__PURE__ */ new Set();
+  const dedupedRelationships = [];
+  for (const relationship of relationships) {
+    const key = relationshipKey(relationship);
+    if (seenRelationships.has(key)) continue;
+    seenRelationships.add(key);
+    dedupedRelationships.push(relationship);
+  }
+  return { entities, relationships: dedupedRelationships };
+}
+
+export {
+  normalizeGraphLabel,
+  normalizeNameKey,
+  assertGraphExtractionPayload,
+  mergeExtractedEntities
+};

package/dist/{chunk-LGNSLDGB.mjs → chunk-MDFUZ3V2.mjs}

@@ -1,6 +1,7 @@
 import {
+  assertGraphExtractionPayload,
   mergeExtractedEntities
-} from "./chunk-A3L46P2G.mjs";
+} from "./chunk-34MTVIYK.mjs";
 
 // ../shared/src/constants/defaults.ts
 var DEFAULTS = {
@@ -424,7 +425,6 @@ var MemoryClient = class {
    * collect the terminal event; there is no separate `ingestFile()` Promise
    * method by design (one wire format, one SDK method).
    */
-  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: NDJSON dispatch + SDK enrichment fan-out is two cooperating paths; documented inline and tested in memory-client-events.test.ts.
   async *ingestFileEvents(file, options) {
     const controller = new AbortController();
     const relayAbort = () => controller.abort(options?.signal?.reason);
@@ -441,237 +441,371 @@ var MemoryClient = class {
         ...this._authHeaders
       };
       if (wantsTextWindows) headers["X-Pyx-Enrichment-Capabilities"] = "text_windows_v1";
-      let res;
+      const raw = yield* this.streamNdjsonUpload(
+        "/api/memory/ingest/file",
+        formData,
+        headers,
+        controller.signal
+      );
+      if (!raw) return;
+      const serverResult = this.fileIngestResultFromEvent({
+        ...raw,
+        schemaVersion: 1,
+        type: "result",
+        stage: "complete"
+      });
+      yield* this.completeIngestFileEvents(file, serverResult, options, controller.signal);
+    } finally {
+      options?.signal?.removeEventListener("abort", relayAbort);
+      controller.abort();
+    }
+  }
+  /**
+   * Graph-only re-enrichment for a document whose chunks are already stored
+   * and searchable but whose graph build failed. Uploads the original to
+   * `/api/memory/graph/enrich/file` (prepare-only — the server performs zero
+   * store/delete before the final graph write), runs the SAME enrichment
+   * callback engine as {@link ingestFileEvents}, then finalizes into one
+   * stable graph anchor keyed by `documentKey`. Repeating the same key
+   * replaces the document's graph references idempotently.
+   *
+   * The terminal `result` is a {@link GraphEnrichResult} event carrying the
+   * ACTUAL persisted graph counts; abort and failures yield a terminal
+   * `error` event instead (the server retains the pending session for retry).
+   */
+  async *graphEnrichFileEvents(file, options) {
+    if (typeof options?.documentKey !== "string" || options.documentKey.trim().length === 0) {
+      throw new Error("graphEnrichFileEvents requires a non-empty documentKey");
+    }
+    if (!options.enrichment?.extractEntitiesV2) {
+      throw new Error(
+        "graphEnrichFileEvents requires enrichment.extractEntitiesV2 \u2014 graph-only re-enrichment is caller-extraction by definition"
+      );
+    }
+    const controller = new AbortController();
+    const relayAbort = () => controller.abort(options.signal?.reason);
+    if (options.signal?.aborted) relayAbort();
+    options.signal?.addEventListener("abort", relayAbort, { once: true });
+    try {
+      const formData = new FormData();
+      formData.append("file", file);
+      formData.append("documentKey", options.documentKey);
+      if (options.namespaceId) formData.append("namespaceId", options.namespaceId);
+      const headers = {
+        Accept: "application/x-ndjson",
+        "X-Pyx-Enrichment-Capabilities": "text_windows_v1",
+        ...this._authHeaders
+      };
+      const raw = yield* this.streamNdjsonUpload(
+        "/api/memory/graph/enrich/file",
+        formData,
+        headers,
+        controller.signal
+      );
+      if (!raw) return;
       try {
-        res = await fetch(`${this.baseUrl}/api/memory/ingest/file`, {
-          method: "POST",
-          body: formData,
-          headers,
-          signal: controller.signal
-        });
-      } catch (err) {
-        yield this.ingestErrorEvent(
-          this.translateFetchError(err, "/api/memory/ingest/file"),
-          "parsing"
-        );
-        return;
-      }
-      const contentType = res.headers.get("content-type") ?? "";
-      if (!contentType.includes("application/x-ndjson")) {
-        yield this.ingestErrorEvent(
-          new MemoryServerError(
-            `Memory server returned ${contentType || "unknown content-type"} instead of application/x-ndjson \u2014 server is older than v0.15.0`,
-            res.status
-          ),
-          "parsing"
-        );
-        return;
-      }
-      if (!res.body) {
-        yield this.ingestErrorEvent(
-          new MemoryServerError("Memory server returned an empty stream", res.status),
-          "parsing"
+        const prepared = raw;
+        if (prepared.purpose !== "graph-only" || !prepared.enrichment) {
+          throw new MemoryServerError(
+            "Graph enrichment prepare returned an unexpected terminal result",
+            0
+          );
+        }
+        const outcome = yield* this.runEnrichmentCallbacks(
+          file,
+          prepared.enrichment,
+          options.enrichment,
+          controller.signal,
+          "graph-only"
         );
-        return;
-      }
-      const reader = res.body.getReader();
-      const decoder = new TextDecoder();
-      let buffer = "";
-      let currentStage = "parsing";
-      let serverResult = null;
-      try {
-        while (true) {
-          const { done, value } = await reader.read();
-          if (done) break;
-          buffer += decoder.decode(value, { stream: true });
-          const lines = buffer.split("\n");
-          buffer = lines.pop() ?? "";
-          for (const line of lines) {
-            if (!line.trim()) continue;
-            const raw = JSON.parse(line);
-            const type = raw.type;
-            if (type === "progress" || type === "heartbeat") {
-              const stage = this.normalizeActiveIngestStage(raw.stage);
-              if (!stage) continue;
-              currentStage = stage;
-              yield { ...raw, schemaVersion: 1, type, stage };
-              continue;
-            }
-            if (type === "result") {
-              serverResult = this.fileIngestResultFromEvent({
-                ...raw,
-                schemaVersion: 1,
-                type: "result",
-                stage: "complete"
-              });
-              break;
-            }
-            if (type === "error") {
-              yield {
-                schemaVersion: 1,
-                type: "error",
-                stage: this.normalizeActiveIngestStage(raw.stage) ?? currentStage,
-                error: typeof raw.error === "string" ? raw.error : "File ingest failed",
-                message: typeof raw.message === "string" ? raw.message : void 0,
-                code: typeof raw.code === "string" || typeof raw.code === "number" ? raw.code : void 0,
-                status: typeof raw.status === "number" ? raw.status : void 0
-              };
-              return;
-            }
-          }
-          if (serverResult) break;
+        const data = outcome.data;
+        if (data?.purpose !== "graph-only" || !Array.isArray(data.entryIds)) {
+          throw new MemoryServerError(
+            "Graph enrichment finalization returned an unexpected result",
+            0
+          );
         }
+        yield { schemaVersion: 1, type: "result", stage: "complete", ...data };
       } catch (err) {
-        yield this.ingestErrorEvent(err, currentStage);
-        return;
-      } finally {
-        reader.releaseLock();
+        yield this.ingestErrorEvent(err, "enrichment");
       }
-      if (!serverResult) {
-        yield this.ingestErrorEvent(
-          new MemoryServerError("File ingest stream ended without a server result", 0),
-          currentStage
-        );
-        return;
-      }
-      yield* this.completeIngestFileEvents(file, serverResult, options, controller.signal);
     } finally {
-      options?.signal?.removeEventListener("abort", relayAbort);
+      options.signal?.removeEventListener("abort", relayAbort);
       controller.abort();
     }
   }
   /**
-   * Run the SDK-side enrichment phase (image-describe → entity-extract →
-   * `/enrich` POST) for a server result, emitting progress + heartbeat
-   * events around the slow steps and yielding the single terminal
-   * {@link IngestResultEvent} at the end. Skips work cleanly when the
-   * server emitted no enrichment block or the caller wired no callbacks.
+   * POST a multipart body to an NDJSON streaming endpoint and relay its
+   * progress/heartbeat events. Returns the raw terminal `result` record, or
+   * null after yielding a terminal error (transport failure, server error
+   * event, non-NDJSON response, stream ending without a result). One
+   * implementation for both streaming surfaces so the wire protocol cannot
+   * fork.
+   */
+  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: one stateful NDJSON reader validates and relays both ingest and graph-only stream envelopes
+  async *streamNdjsonUpload(path, formData, headers, signal) {
+    let res;
+    try {
+      res = await fetch(`${this.baseUrl}${path}`, {
+        method: "POST",
+        body: formData,
+        headers,
+        signal
+      });
+    } catch (err) {
+      yield this.ingestErrorEvent(this.translateFetchError(err, path), "parsing");
+      return null;
+    }
+    const contentType = res.headers.get("content-type") ?? "";
+    if (!contentType.includes("application/x-ndjson")) {
+      yield this.ingestErrorEvent(
+        new MemoryServerError(
+          `Memory server returned ${contentType || "unknown content-type"} instead of application/x-ndjson \u2014 server is older than v0.15.0`,
+          res.status
+        ),
+        "parsing"
+      );
+      return null;
+    }
+    if (!res.body) {
+      yield this.ingestErrorEvent(
+        new MemoryServerError("Memory server returned an empty stream", res.status),
+        "parsing"
+      );
+      return null;
+    }
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    let currentStage = "parsing";
+    let serverResult = null;
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split("\n");
+        buffer = lines.pop() ?? "";
+        for (const line of lines) {
+          if (!line.trim()) continue;
+          const raw = JSON.parse(line);
+          const type = raw.type;
+          if (type === "progress" || type === "heartbeat") {
+            const stage = this.normalizeActiveIngestStage(raw.stage);
+            if (!stage) continue;
+            currentStage = stage;
+            yield { ...raw, schemaVersion: 1, type, stage };
+            continue;
+          }
+          if (type === "result") {
+            serverResult = raw;
+            break;
+          }
+          if (type === "error") {
+            yield {
+              schemaVersion: 1,
+              type: "error",
+              stage: this.normalizeActiveIngestStage(raw.stage) ?? currentStage,
+              error: typeof raw.error === "string" ? raw.error : "File ingest failed",
+              message: typeof raw.message === "string" ? raw.message : void 0,
+              code: typeof raw.code === "string" || typeof raw.code === "number" ? raw.code : void 0,
+              status: typeof raw.status === "number" ? raw.status : void 0
+            };
+            return null;
+          }
+        }
+        if (serverResult) break;
+      }
+    } catch (err) {
+      yield this.ingestErrorEvent(err, currentStage);
+      return null;
+    } finally {
+      reader.releaseLock();
+    }
+    if (!serverResult) {
+      yield this.ingestErrorEvent(
+        new MemoryServerError("File ingest stream ended without a server result", 0),
+        currentStage
+      );
+      return null;
+    }
+    return serverResult;
+  }
+  /**
+   * Run the SDK-side enrichment phase for an ingest result and yield the
+   * single terminal {@link IngestResultEvent} at the end. Skips work cleanly
+   * when the server emitted no enrichment block or the caller wired no
+   * callbacks. The callback work itself lives in
+   * {@link runEnrichmentCallbacks} — shared with the graph-only surface.
    */
-  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: image-describe / extract-entities-v2 / no-op are documented decision branches; the fan-out covers the v0.15.0 enrichment phase + heartbeat plumbing.
   async *completeIngestFileEvents(file, result, options, signal) {
     try {
       if (!result.enrichment || !options?.enrichment) {
         yield { schemaVersion: 1, type: "result", stage: "complete", ...result };
         return;
       }
-      const enrichment = result.enrichment;
-      const { fileId, token, expiresAt, images } = enrichment;
-      const isV2 = "version" in enrichment;
-      const textWindows = isV2 ? enrichment.textWindows : [];
-      const descriptions = [];
-      const describeImage = options.enrichment.describeImage;
-      if (describeImage && images.length > 0) {
-        yield {
-          schemaVersion: 1,
-          type: "progress",
-          stage: "enrichment",
-          filename: file.name,
-          imagesTotal: images.length,
-          imagesDescribed: 0,
-          message: `Describing extracted images (0/${images.length})`
-        };
-        const CONCURRENCY = 5;
-        for (let i = 0; i < images.length; i += CONCURRENCY) {
-          const batch = images.slice(i, i + CONCURRENCY);
-          const batchResults = yield* this.withSdkHeartbeats(
-            "enrichment",
-            Promise.all(
-              batch.map(async (imageMeta) => {
-                const imageRes = await fetch(
-                  `${this.baseUrl}/api/memory/files/${fileId}/images/${imageMeta.imageId}?token=${encodeURIComponent(token)}`,
-                  { headers: this._authHeaders, signal }
-                );
-                if (!imageRes.ok) {
-                  throw new MemoryServerError(
-                    `Failed to fetch image ${imageMeta.imageId}: ${imageRes.status}`,
-                    imageRes.status
-                  );
-                }
-                const imageBuffer = await imageRes.arrayBuffer();
-                const description = await describeImage(imageBuffer, imageMeta);
-                return { imageId: imageMeta.imageId, description };
-              })
-            ),
-            signal
-          );
-          descriptions.push(...batchResults.filter((d) => d.description.trim().length > 0));
-          yield {
-            schemaVersion: 1,
-            type: "progress",
-            stage: "enrichment",
-            filename: file.name,
-            imagesTotal: images.length,
-            imagesDescribed: descriptions.length,
-            message: `Described ${descriptions.length}/${images.length} images`
-          };
-        }
+      const outcome = yield* this.runEnrichmentCallbacks(
+        file,
+        result.enrichment,
+        options.enrichment,
+        signal,
+        "ingest"
+      );
+      if (outcome.posted) {
+        const enrichData = outcome.data;
+        result.entryIds.push(...enrichData.entryIds);
+        result.chunks += outcome.descriptions.length;
+        result.totalCharacters += outcome.descriptions.reduce(
+          (sum, d) => sum + d.description.length,
+          0
+        );
       }
-      let entities;
-      let relationships;
-      const imageDescriptionTexts = descriptions.map((d) => d.description);
-      if (options.enrichment.extractEntitiesV2 && (textWindows.length > 0 || imageDescriptionTexts.length > 0)) {
+      yield { schemaVersion: 1, type: "result", stage: "complete", ...result };
+    } catch (err) {
+      yield this.ingestErrorEvent(err, "enrichment", result);
+    }
+  }
+  /**
+   * The ONE enrichment callback engine, shared by {@link ingestFileEvents}
+   * and {@link graphEnrichFileEvents}: fetches extracted images, invokes
+   * `describeImage` with bounded concurrency, invokes `extractEntitiesV2`
+   * exactly once, and POSTs `/files/{fileId}/enrich` — emitting progress and
+   * heartbeat events around each slow step. Throws on any failure; the
+   * purpose-specific wrappers translate that into their terminal error.
+   *
+   * The purpose controls empty-output semantics: ingest skips an optional
+   * empty add-on; graph-only finalizes an extractor that ran and found zero
+   * entities, but refuses to erase prior graph state when no extractable input
+   * reached the callback at all.
+   */
+  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: image-describe / extract-entities-v2 / no-op are documented decision branches; the fan-out covers the v0.15.0 enrichment phase + heartbeat plumbing.
+  async *runEnrichmentCallbacks(file, enrichment, callbacks, signal, purpose) {
+    const { fileId, token, expiresAt, images } = enrichment;
+    const isV2 = "version" in enrichment;
+    const textWindows = isV2 ? enrichment.textWindows : [];
+    const descriptions = [];
+    const describeImage = callbacks.describeImage;
+    if (describeImage && images.length > 0) {
+      yield {
+        schemaVersion: 1,
+        type: "progress",
+        stage: "enrichment",
+        filename: file.name,
+        imagesTotal: images.length,
+        imagesDescribed: 0,
+        message: `Describing extracted images (0/${images.length})`
+      };
+      const CONCURRENCY = 5;
+      for (let i = 0; i < images.length; i += CONCURRENCY) {
+        const batch = images.slice(i, i + CONCURRENCY);
+        const batchResults = yield* this.withSdkHeartbeats(
+          "enrichment",
+          Promise.all(
+            batch.map(async (imageMeta) => {
+              const imageRes = await fetch(
+                `${this.baseUrl}/api/memory/files/${fileId}/images/${imageMeta.imageId}?token=${encodeURIComponent(token)}`,
+                { headers: this._authHeaders, signal }
+              );
+              if (!imageRes.ok) {
+                throw new MemoryServerError(
+                  `Failed to fetch image ${imageMeta.imageId}: ${imageRes.status}`,
+                  imageRes.status
+                );
+              }
+              const imageBuffer = await imageRes.arrayBuffer();
+              const description = await describeImage(imageBuffer, imageMeta);
+              return { imageId: imageMeta.imageId, description };
+            })
+          ),
+          signal
+        );
+        descriptions.push(...batchResults.filter((d) => d.description.trim().length > 0));
         yield {
           schemaVersion: 1,
           type: "progress",
           stage: "enrichment",
           filename: file.name,
-          message: "Extracting entities"
+          imagesTotal: images.length,
+          imagesDescribed: descriptions.length,
+          message: `Described ${descriptions.length}/${images.length} images`
         };
-        const extracted = yield* this.withSdkHeartbeats(
-          "enrichment",
-          options.enrichment.extractEntitiesV2({
-            textWindows,
-            imageDescriptions: imageDescriptionTexts,
-            mimeType: file.type,
-            filename: file.name
-          }),
-          signal
-        );
-        entities = extracted.entities;
-        relationships = extracted.relationships;
-      }
-      const hasGraph = (entities?.length ?? 0) > 0;
-      const hasImages = descriptions.length > 0;
-      if (!hasGraph && !hasImages) {
-        yield { schemaVersion: 1, type: "result", stage: "complete", ...result };
-        return;
       }
+    }
+    let entities;
+    let relationships;
+    const imageDescriptionTexts = descriptions.map((d) => d.description);
+    if (callbacks.extractEntitiesV2 && (textWindows.length > 0 || imageDescriptionTexts.length > 0)) {
       yield {
         schemaVersion: 1,
         type: "progress",
         stage: "enrichment",
         filename: file.name,
-        message: "Persisting enrichment"
+        message: "Extracting entities"
       };
-      const enrichRes = yield* this.withSdkHeartbeats(
+      const rawExtracted = yield* this.withSdkHeartbeats(
         "enrichment",
-        fetch(`${this.baseUrl}/api/memory/files/${fileId}/enrich`, {
-          method: "POST",
-          headers: {
-            "Content-Type": "application/json",
-            "X-Enrichment-Token": `${token}:${expiresAt}`,
-            ...this._authHeaders
-          },
-          signal,
-          body: JSON.stringify({ imageDescriptions: descriptions, entities, relationships })
+        callbacks.extractEntitiesV2({
+          textWindows,
+          imageDescriptions: imageDescriptionTexts,
+          mimeType: file.type,
+          filename: file.name
         }),
         signal
       );
-      if (!enrichRes.ok) {
-        const body = await enrichRes.json().catch(() => ({}));
+      let extracted;
+      try {
+        extracted = assertGraphExtractionPayload(rawExtracted, "extractEntitiesV2 result");
+      } catch (error) {
         throw new MemoryServerError(
-          body.error ?? `Enrichment failed: ${enrichRes.status}`,
-          enrichRes.status
+          error instanceof Error ? error.message : "extractEntitiesV2 returned an invalid result",
+          422
         );
       }
-      const enrichData = await this.parseApiResponse(enrichRes);
-      result.entryIds.push(...enrichData.entryIds);
-      result.chunks += descriptions.length;
-      result.totalCharacters += descriptions.reduce((sum, d) => sum + d.description.length, 0);
-      yield { schemaVersion: 1, type: "result", stage: "complete", ...result };
-    } catch (err) {
-      yield this.ingestErrorEvent(err, "enrichment", result);
+      entities = extracted.entities;
+      relationships = extracted.relationships;
+    }
+    const hadExtractionInput = textWindows.length > 0 || imageDescriptionTexts.length > 0;
+    if (purpose === "graph-only" && !hadExtractionInput) {
+      throw new MemoryServerError(
+        "Graph enrichment produced no extractable text or image descriptions; prior graph state was preserved",
+        422
+      );
+    }
+    const hasGraph = (entities?.length ?? 0) > 0;
+    const hasImages = descriptions.length > 0;
+    if (!hasGraph && !hasImages && purpose === "ingest") {
+      return { posted: false, data: null, descriptions };
+    }
+    yield {
+      schemaVersion: 1,
+      type: "progress",
+      stage: "enrichment",
+      filename: file.name,
+      message: "Persisting enrichment"
+    };
+    const enrichRes = yield* this.withSdkHeartbeats(
+      "enrichment",
+      fetch(`${this.baseUrl}/api/memory/files/${fileId}/enrich`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "X-Enrichment-Token": `${token}:${expiresAt}`,
+          ...this._authHeaders
+        },
+        signal,
+        body: JSON.stringify({ imageDescriptions: descriptions, entities, relationships })
+      }),
+      signal
+    );
+    if (!enrichRes.ok) {
+      const body = await enrichRes.json().catch(() => ({}));
+      throw new MemoryServerError(
+        body.error ?? `Enrichment failed: ${enrichRes.status}`,
+        enrichRes.status
+      );
     }
+    const data = await this.parseApiResponse(enrichRes);
+    return { posted: true, data, descriptions };
   }
   /**
    * Race a Promise against a periodic heartbeat tick. Yields a heartbeat

package/dist/{chunk-WDF5LAZS.mjs → chunk-ZVI7DCB4.mjs}

@@ -1,6 +1,6 @@
 import {
   MemoryClient
-} from "./chunk-LGNSLDGB.mjs";
+} from "./chunk-MDFUZ3V2.mjs";
 
 // ../dashboard/src/aggregations/consolidation-analytics.ts
 function analyzeConsolidationLog(entries) {

package/dist/cli/pyx-mem.mjs

@@ -835,7 +835,7 @@ function createProxyServer(client, version, uploadLocalFile) {
   return server;
 }
 async function runMcpProxyServer(opts) {
-  const version = opts.version ?? (true ? "1.17.15" : "0.0.0-dev");
+  const version = opts.version ?? (true ? "1.17.16" : "0.0.0-dev");
   const read = await opts.readCredentials();
   if (!read.ok) {
     const text = read.result.content.map((c) => c.type === "text" ? c.text : "").join(" ").trim();

package/dist/dashboard.mjs

@@ -11,9 +11,9 @@ import {
   toGraphologyFormat,
   transformGraphData,
   unreachableHealth
-} from "./chunk-WDF5LAZS.mjs";
-import "./chunk-LGNSLDGB.mjs";
-import "./chunk-A3L46P2G.mjs";
+} from "./chunk-ZVI7DCB4.mjs";
+import "./chunk-MDFUZ3V2.mjs";
+import "./chunk-34MTVIYK.mjs";
 export {
   DashboardClient,
   Poller,

package/dist/data-plane-contract.mjs

@@ -1,7 +1,7 @@
 import {
   normalizeGraphLabel,
   normalizeNameKey
-} from "./chunk-A3L46P2G.mjs";
+} from "./chunk-34MTVIYK.mjs";
 
 // ../shared/src/data-plane-contract.ts
 import { createHash } from "crypto";

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { StoreInput as StoreInput$1, MemoryEntry as MemoryEntry$1, MemorySearchParams as MemorySearchParams$1, MemorySearchResult as MemorySearchResult$1, MemoryType as MemoryType$1, PrincipalContext as PrincipalContext$1, SensitivityLevel as SensitivityLevel$1, MemoryStats as MemoryStats$1, LineageParams as LineageParams$1, LineageResult as LineageResult$1, ReinforceParams as ReinforceParams$1, ReinforceResult as ReinforceResult$1, WikiLintReport as WikiLintReport$1, GraphRepairResult as GraphRepairResult$1, ExtractedImageMeta as ExtractedImageMeta$1, IngestEntity as IngestEntity$1, IngestRelationship as IngestRelationship$1, EntityExtractionResult as EntityExtractionResult$1, Topology as Topology$1, IngestEvent as IngestEvent$1, GraphNode as GraphNode$1, GraphTraversalResult as GraphTraversalResult$1, CorrectionRecord as CorrectionRecord$1 } from '@pyx-memory/shared';
+import { StoreInput as StoreInput$1, MemoryEntry as MemoryEntry$1, MemorySearchParams as MemorySearchParams$1, MemorySearchResult as MemorySearchResult$1, MemoryType as MemoryType$1, PrincipalContext as PrincipalContext$1, SensitivityLevel as SensitivityLevel$1, MemoryStats as MemoryStats$1, LineageParams as LineageParams$1, LineageResult as LineageResult$1, ReinforceParams as ReinforceParams$1, ReinforceResult as ReinforceResult$1, WikiLintReport as WikiLintReport$1, GraphRepairResult as GraphRepairResult$1, ExtractedImageMeta as ExtractedImageMeta$1, IngestEntity as IngestEntity$1, IngestRelationship as IngestRelationship$1, EntityExtractionResult as EntityExtractionResult$1, Topology as Topology$1, IngestEvent as IngestEvent$1, GraphEnrichEvent as GraphEnrichEvent$1, GraphNode as GraphNode$1, GraphTraversalResult as GraphTraversalResult$1, CorrectionRecord as CorrectionRecord$1 } from '@pyx-memory/shared';
 
 /** Parameters for paginated entry listing. */
 interface MemoryListParams {
@@ -247,6 +247,22 @@ interface IngestFileOptions {
     signal?: AbortSignal;
     namespaceId?: string;
 }
+/**
+ * Options for {@link MemoryClient.graphEnrichFileEvents}. `documentKey` is the
+ * caller's stable logical identity for the document whose graph is being
+ * rebuilt — the server derives the graph anchor id from
+ * (tenant, namespace, documentKey), so repeating the same key replaces the
+ * document's graph references instead of multiplying them.
+ *
+ * `enrichment.extractEntitiesV2` is required: graph-only re-enrichment is
+ * caller-extraction by definition (there is no server-side fallback).
+ */
+interface GraphEnrichFileOptions {
+    documentKey: string;
+    namespaceId?: string;
+    signal?: AbortSignal;
+    enrichment: EnrichmentCallbacks;
+}
 /**
  * Caller-supplied enrichment for the per-call store path. Mirrors
  * {@link EnrichmentCallbacks} for file ingest. When supplied, the SDK invokes
@@ -360,13 +376,50 @@ declare class MemoryClient implements ExtendedMemoryInterface {
      */
     ingestFileEvents(file: File, options?: IngestFileOptions): AsyncIterable<IngestEvent$1>;
     /**
-     * Run the SDK-side enrichment phase (image-describe → entity-extract →
-     * `/enrich` POST) for a server result, emitting progress + heartbeat
-     * events around the slow steps and yielding the single terminal
-     * {@link IngestResultEvent} at the end. Skips work cleanly when the
-     * server emitted no enrichment block or the caller wired no callbacks.
+     * Graph-only re-enrichment for a document whose chunks are already stored
+     * and searchable but whose graph build failed. Uploads the original to
+     * `/api/memory/graph/enrich/file` (prepare-only — the server performs zero
+     * store/delete before the final graph write), runs the SAME enrichment
+     * callback engine as {@link ingestFileEvents}, then finalizes into one
+     * stable graph anchor keyed by `documentKey`. Repeating the same key
+     * replaces the document's graph references idempotently.
+     *
+     * The terminal `result` is a {@link GraphEnrichResult} event carrying the
+     * ACTUAL persisted graph counts; abort and failures yield a terminal
+     * `error` event instead (the server retains the pending session for retry).
+     */
+    graphEnrichFileEvents(file: File, options: GraphEnrichFileOptions): AsyncIterable<GraphEnrichEvent$1>;
+    /**
+     * POST a multipart body to an NDJSON streaming endpoint and relay its
+     * progress/heartbeat events. Returns the raw terminal `result` record, or
+     * null after yielding a terminal error (transport failure, server error
+     * event, non-NDJSON response, stream ending without a result). One
+     * implementation for both streaming surfaces so the wire protocol cannot
+     * fork.
+     */
+    private streamNdjsonUpload;
+    /**
+     * Run the SDK-side enrichment phase for an ingest result and yield the
+     * single terminal {@link IngestResultEvent} at the end. Skips work cleanly
+     * when the server emitted no enrichment block or the caller wired no
+     * callbacks. The callback work itself lives in
+     * {@link runEnrichmentCallbacks} — shared with the graph-only surface.
      */
     private completeIngestFileEvents;
+    /**
+     * The ONE enrichment callback engine, shared by {@link ingestFileEvents}
+     * and {@link graphEnrichFileEvents}: fetches extracted images, invokes
+     * `describeImage` with bounded concurrency, invokes `extractEntitiesV2`
+     * exactly once, and POSTs `/files/{fileId}/enrich` — emitting progress and
+     * heartbeat events around each slow step. Throws on any failure; the
+     * purpose-specific wrappers translate that into their terminal error.
+     *
+     * The purpose controls empty-output semantics: ingest skips an optional
+     * empty add-on; graph-only finalizes an extractor that ran and found zero
+     * entities, but refuses to erase prior graph state when no extractable input
+     * reached the callback at all.
+     */
+    private runEnrichmentCallbacks;
     /**
      * Race a Promise against a periodic heartbeat tick. Yields a heartbeat
      * IngestEvent every {@link INGEST_EVENT_HEARTBEAT_MS} until the promise
@@ -1274,6 +1327,10 @@ interface EntityExtractionResult {
         type: string;
     }>;
 }
+interface GraphExtractionPayload {
+    entities: IngestEntity[];
+    relationships: IngestRelationship[];
+}
 declare function normalizeGraphLabel(value: string, fallback: string): string;
 /**
  * Identity key for a graph node: the normalized name alone. `type` is a node
@@ -1287,6 +1344,16 @@ declare function normalizeGraphLabel(value: string, fallback: string): string;
  * edge resolvability with it — all three MUST agree, so they import this one fn.
  */
 declare function normalizeNameKey(name: string): string;
+/**
+ * Runtime contract for destructive graph replacement payloads. TypeScript
+ * callback types do not protect JavaScript callers or malformed LLM adapter
+ * results; accepting a missing `entities` field as an empty extraction would
+ * erase the prior graph. Both arrays are therefore required, every item is
+ * structurally validated, and every relationship endpoint must resolve to a
+ * declared entity under the graph store's exact name identity normalizer.
+ * A genuinely empty `{ entities: [], relationships: [] }` remains valid.
+ */
+declare function assertGraphExtractionPayload(value: unknown, field?: string): GraphExtractionPayload;
 /**
  * Merge caller-provided entities/relationships with LLM-extracted ones.
  *
@@ -1522,6 +1589,56 @@ interface IngestErrorEvent {
     partialResult?: FileIngestResult;
 }
 type IngestEvent = IngestProgressEvent | IngestHeartbeatEvent | IngestResultEvent | IngestErrorEvent;
+/** What a pending enrichment session finalizes into. Sessions created before
+ *  graph-only support carry no purpose and behave as `'ingest'`. */
+type EnrichmentPurpose = 'ingest' | 'graph-only';
+/**
+ * Terminal server event for POST /api/memory/graph/enrich/file. Deliberately
+ * NOT an {@link IngestResultEvent}: the prepare phase stores nothing, so there
+ * are no chunk counters to report — fabricating `chunks: 0` would make the
+ * result indistinguishable from a real empty ingest.
+ */
+interface GraphEnrichPreparedEvent {
+    schemaVersion: 1;
+    type: 'result';
+    stage: 'complete';
+    purpose: 'graph-only';
+    filename: string;
+    fileType: string;
+    enrichment: EnrichmentPendingV2;
+    message?: string;
+}
+/**
+ * Terminal result of a graph-only re-enrichment run — also the response body
+ * of POST /files/{fileId}/enrich when the pending session's purpose is
+ * `'graph-only'`. Counts reflect ACTUAL graph persistence (mirrors
+ * {@link EnrichResult}), never the submitted payload sizes.
+ */
+interface GraphEnrichResult {
+    purpose: 'graph-only';
+    filename: string;
+    fileType: string;
+    /** The single stable anchor entry id, including a successful zero-entity replacement. */
+    entryIds: string[];
+    entitiesStored: number;
+    relationshipsStored: number;
+    /** Present (and >0) only when edges were dropped — see {@link EnrichResult}. */
+    relationshipsDropped?: number;
+    droppedRelationships?: DroppedGraphRelationship[];
+}
+/** Terminal success of the SDK's graph-only stream — exactly one per run. */
+interface GraphEnrichResultEvent extends GraphEnrichResult {
+    schemaVersion: 1;
+    type: 'result';
+    stage: 'complete';
+    message?: string;
+}
+/**
+ * Typed view of the SDK's `graphEnrichFileEvents()` stream. Progress /
+ * heartbeat / error envelopes are shared with the ingest stream (same wire
+ * protocol); only the terminal result differs.
+ */
+type GraphEnrichEvent = IngestProgressEvent | IngestHeartbeatEvent | GraphEnrichResultEvent | IngestErrorEvent;
 
 /**
  * Namespace topology-isolation modes for v0.17.0.
@@ -1636,4 +1753,4 @@ interface CreatePyxMemoryOptions {
 }
 declare function createPyxMemory(opts?: CreatePyxMemoryOptions): MemoryClient;
 
-export { type AgentId, type ApiResponse, type ConsolidationRunResult, type CorrectionInput, type CorrectionRecord, type CreatePyxMemoryOptions, DEFAULTS, DEPRECATED_RAG_STRATEGIES, DisabledMemory, type DroppedGraphRelationship, type DueScanInput, EmbeddingProviderName, type EnrichmentCallbacks, type EntityExtractionResult, type ExtendedMemoryInterface, type FetchCorrectionsInput, type GraphEnrichment, type GraphEnrichmentStatus, type GraphFailureMode, type GraphNode, type GraphRelationship, type GraphRepairResult, type GraphTelemetrySnapshot, type GraphTraversalResult, type IngestEntity, type IngestErrorEvent, type IngestEvent, type IngestFileOptions, type IngestHeartbeatEvent, type IngestProgressEvent, type IngestRelationship, type IngestResultEvent, type IngestStage, type IngestionResult, type LineageParams, type LineageResult, type LineageVersion, MemoryClient, type MemoryClientOptions, type MemoryEntry, type MemoryIngestRequest, type MemoryInterface, type MemoryListParams, type MemoryListResult, type MemoryLogFilters, type MemorySearchParams, type MemorySearchResult, MemoryServerError, type MemoryStats, MemoryType, type MoveEntriesFilter, MoveFailureReason, type MoveResult, type MoveTarget, NamespaceIsolation, type PrincipalContext, RAGStrategy, type ReinforceParams, type ReinforceResult, type ReinforceSignal, SINGLE_TENANT_ID, type SecretElevationAggregate, type SecretElevationNotice, SensitivityLevel, type SourceEvidence, type StoreInput, StoreTarget, TAXONOMY_MAX_CATEGORIES, type TemporalQueryFilters, type TenantScopeOptions, type Timestamp, type Topology, type TopologyExtractionProvider, type TopologyServiceVariant, type UsageHygieneSnapshot, VectorProvider, type VectorStatus, type WikiLintReport, createPyxMemory, mergeExtractedEntities, normalizeGraphLabel, normalizeNameKey, projectSearchResponseForMcp, secretElevationAggregate, secretElevationNoticeFor, withSecretElevationNotice };
+export { type AgentId, type ApiResponse, type ConsolidationRunResult, type CorrectionInput, type CorrectionRecord, type CreatePyxMemoryOptions, DEFAULTS, DEPRECATED_RAG_STRATEGIES, DisabledMemory, type DroppedGraphRelationship, type DueScanInput, EmbeddingProviderName, type EnrichmentCallbacks, type EnrichmentPurpose, type EntityExtractionResult, type ExtendedMemoryInterface, type FetchCorrectionsInput, type GraphEnrichEvent, type GraphEnrichFileOptions, type GraphEnrichPreparedEvent, type GraphEnrichResult, type GraphEnrichResultEvent, type GraphEnrichment, type GraphEnrichmentStatus, type GraphExtractionPayload, type GraphFailureMode, type GraphNode, type GraphRelationship, type GraphRepairResult, type GraphTelemetrySnapshot, type GraphTraversalResult, type IngestEntity, type IngestErrorEvent, type IngestEvent, type IngestFileOptions, type IngestHeartbeatEvent, type IngestProgressEvent, type IngestRelationship, type IngestResultEvent, type IngestStage, type IngestionResult, type LineageParams, type LineageResult, type LineageVersion, MemoryClient, type MemoryClientOptions, type MemoryEntry, type MemoryIngestRequest, type MemoryInterface, type MemoryListParams, type MemoryListResult, type MemoryLogFilters, type MemorySearchParams, type MemorySearchResult, MemoryServerError, type MemoryStats, MemoryType, type MoveEntriesFilter, MoveFailureReason, type MoveResult, type MoveTarget, NamespaceIsolation, type PrincipalContext, RAGStrategy, type ReinforceParams, type ReinforceResult, type ReinforceSignal, SINGLE_TENANT_ID, type SecretElevationAggregate, type SecretElevationNotice, SensitivityLevel, type SourceEvidence, type StoreInput, StoreTarget, TAXONOMY_MAX_CATEGORIES, type TemporalQueryFilters, type TenantScopeOptions, type Timestamp, type Topology, type TopologyExtractionProvider, type TopologyServiceVariant, type UsageHygieneSnapshot, VectorProvider, type VectorStatus, type WikiLintReport, assertGraphExtractionPayload, createPyxMemory, mergeExtractedEntities, normalizeGraphLabel, normalizeNameKey, projectSearchResponseForMcp, secretElevationAggregate, secretElevationNoticeFor, withSecretElevationNotice };

package/dist/index.mjs

@@ -18,12 +18,13 @@ import {
   secretElevationAggregate,
   secretElevationNoticeFor,
   withSecretElevationNotice
-} from "./chunk-LGNSLDGB.mjs";
+} from "./chunk-MDFUZ3V2.mjs";
 import {
+  assertGraphExtractionPayload,
   mergeExtractedEntities,
   normalizeGraphLabel,
   normalizeNameKey
-} from "./chunk-A3L46P2G.mjs";
+} from "./chunk-34MTVIYK.mjs";
 
 // src/preset.ts
 var DEFAULT_MEMORY_URL = `http://localhost:${DEFAULTS.MEMORY_SERVER_PORT}`;
@@ -54,6 +55,7 @@ export {
   StoreTarget,
   TAXONOMY_MAX_CATEGORIES,
   VectorProvider,
+  assertGraphExtractionPayload,
   createPyxMemory,
   mergeExtractedEntities,
   normalizeGraphLabel,

package/dist/react.mjs

@@ -11,9 +11,9 @@ import {
   toGraphologyFormat,
   transformGraphData,
   unreachableHealth
-} from "./chunk-WDF5LAZS.mjs";
-import "./chunk-LGNSLDGB.mjs";
-import "./chunk-A3L46P2G.mjs";
+} from "./chunk-ZVI7DCB4.mjs";
+import "./chunk-MDFUZ3V2.mjs";
+import "./chunk-34MTVIYK.mjs";
 
 // ../dashboard/src/hooks/use-consolidation-log.ts
 import { useCallback as useCallback2, useMemo } from "react";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyxmate/memory",
-  "version": "1.17.15",
+  "version": "1.17.16",
   "type": "module",
   "description": "SDK for pyx-memory — Memory as a Service for AI agents",
   "license": "MIT",

package/dist/chunk-A3L46P2G.mjs

@@ -1,57 +0,0 @@
-// ../shared/src/graph/extraction.ts
-function normalizeGraphLabel(value, fallback) {
-  const normalized = value.trim().toUpperCase().replace(/[^A-Z0-9]+/g, "_").replace(/^_+|_+$/g, "");
-  return normalized.length > 0 ? normalized : fallback;
-}
-function normalizeNameKey(name) {
-  return name.trim().toLowerCase().replace(/\s+/g, " ");
-}
-function relationshipKey(relationship) {
-  return [
-    relationship.source.trim().toLowerCase(),
-    relationship.target.trim().toLowerCase(),
-    normalizeGraphLabel(relationship.type, "RELATED_TO")
-  ].join("\0");
-}
-function mergeExtractedEntities(callerEntities, callerRelationships, extracted) {
-  const entities = [...callerEntities ?? []];
-  const relationships = [...callerRelationships ?? []];
-  const nameByLowercase = /* @__PURE__ */ new Map();
-  for (const entity of entities) {
-    const key = entity.name.toLowerCase();
-    if (!nameByLowercase.has(key)) nameByLowercase.set(key, entity.name);
-  }
-  for (const entity of extracted.entities) {
-    const key = entity.name.toLowerCase();
-    if (nameByLowercase.has(key)) continue;
-    entities.push({ ...entity, type: normalizeGraphLabel(entity.type, "CONCEPT") });
-    nameByLowercase.set(key, entity.name);
-  }
-  for (const relationship of extracted.relations) {
-    const source = nameByLowercase.get(relationship.source.toLowerCase());
-    const target = nameByLowercase.get(relationship.target.toLowerCase());
-    if (source && target) {
-      relationships.push({
-        ...relationship,
-        source,
-        target,
-        type: normalizeGraphLabel(relationship.type, "RELATED_TO")
-      });
-    }
-  }
-  const seenRelationships = /* @__PURE__ */ new Set();
-  const dedupedRelationships = [];
-  for (const relationship of relationships) {
-    const key = relationshipKey(relationship);
-    if (seenRelationships.has(key)) continue;
-    seenRelationships.add(key);
-    dedupedRelationships.push(relationship);
-  }
-  return { entities, relationships: dedupedRelationships };
-}
-
-export {
-  normalizeGraphLabel,
-  normalizeNameKey,
-  mergeExtractedEntities
-};