@pyxmate/memory 0.10.0 → 0.11.0

package/dist/{chunk-KVRPHFDP.mjs → chunk-5IERAVVW.mjs}

@@ -112,21 +112,36 @@ var MemoryClient = class {
    * With enrichment callbacks: fetches extracted images, calls describeImage for each,
    * optionally extracts entities, then submits enrichment data back to the server.
    */
+  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: two-phase enrichment fans out across image-describe + entity-extract + v1/v2 negotiation; each branch maps to a documented case in memory-client-enrichment.test.ts
   async ingestFile(file, options) {
     const formData = new FormData();
     formData.append("file", file);
     if (options?.description) {
       formData.append("description", options.description);
     }
+    const wantsTextWindows = Boolean(
+      options?.enrichment?.extractEntities || options?.enrichment?.extractEntitiesV2
+    );
+    const headers = { ...this._authHeaders };
+    if (wantsTextWindows) {
+      headers["X-Pyx-Enrichment-Capabilities"] = "text_windows_v1";
+    }
     const res = await fetch(`${this.baseUrl}/api/memory/ingest/file`, {
       method: "POST",
       body: formData,
-      headers: this._authHeaders
+      headers
     });
     const result = await this.parseApiResponse(res);
-    if (result.enrichment && options?.enrichment?.describeImage) {
-      const { fileId, token, expiresAt, images } = result.enrichment;
-      const descriptions = [];
+    if (!result.enrichment || !options?.enrichment) {
+      return result;
+    }
+    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) {
       const CONCURRENCY = 5;
       for (let i = 0; i < images.length; i += CONCURRENCY) {
         const batch = images.slice(i, i + CONCURRENCY);
@@ -143,48 +158,66 @@ var MemoryClient = class {
               );
             }
             const imageBuffer = await imageRes.arrayBuffer();
-            const description = await options.enrichment.describeImage(imageBuffer, imageMeta);
+            const description = await describeImage(imageBuffer, imageMeta);
             return { imageId: imageMeta.imageId, description };
           })
         );
         descriptions.push(...batchResults);
       }
-      let entities;
-      let relationships;
-      if (options.enrichment.extractEntities && descriptions.length > 0) {
-        const extracted = await options.enrichment.extractEntities(
-          descriptions.map((d) => d.description)
-        );
+    }
+    let entities;
+    let relationships;
+    const v2Callback = options.enrichment.extractEntitiesV2;
+    const legacyCallback = options.enrichment.extractEntities;
+    const imageDescriptionTexts = descriptions.map((d) => d.description);
+    if (v2Callback && (textWindows.length > 0 || imageDescriptionTexts.length > 0)) {
+      const extracted = await v2Callback({
+        textWindows,
+        imageDescriptions: imageDescriptionTexts,
+        mimeType: file.type,
+        filename: file.name
+      });
+      entities = extracted.entities;
+      relationships = extracted.relationships;
+    } else if (legacyCallback) {
+      const allInputs = [...textWindows, ...imageDescriptionTexts];
+      if (allInputs.length > 0) {
+        const extracted = await legacyCallback(allInputs);
         entities = extracted.entities;
         relationships = extracted.relationships;
       }
-      const enrichTokenHeader = `${token}:${expiresAt}`;
-      const enrichRes = await fetch(`${this.baseUrl}/api/memory/files/${fileId}/enrich`, {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          "X-Enrichment-Token": enrichTokenHeader,
-          ...this._authHeaders
-        },
-        body: JSON.stringify({
-          imageDescriptions: descriptions,
-          entities,
-          relationships
-        })
-      });
-      if (!enrichRes.ok) {
-        const body = await enrichRes.json().catch(() => ({}));
-        throw new MemoryServerError(
-          body.error ?? `Enrichment failed: ${enrichRes.status}`,
-          enrichRes.status
-        );
-      }
-      const enrichData = await this.parseApiResponse(enrichRes);
-      const enrichCharacters = descriptions.reduce((sum, d) => sum + d.description.length, 0);
-      result.entryIds.push(...enrichData.entryIds);
-      result.chunks += descriptions.length;
-      result.totalCharacters += enrichCharacters;
     }
+    const hasGraph = (entities?.length ?? 0) > 0;
+    const hasImages = descriptions.length > 0;
+    if (!hasGraph && !hasImages) {
+      return result;
+    }
+    const enrichTokenHeader = `${token}:${expiresAt}`;
+    const enrichRes = await fetch(`${this.baseUrl}/api/memory/files/${fileId}/enrich`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-Enrichment-Token": enrichTokenHeader,
+        ...this._authHeaders
+      },
+      body: JSON.stringify({
+        imageDescriptions: descriptions,
+        entities,
+        relationships
+      })
+    });
+    if (!enrichRes.ok) {
+      const body = await enrichRes.json().catch(() => ({}));
+      throw new MemoryServerError(
+        body.error ?? `Enrichment failed: ${enrichRes.status}`,
+        enrichRes.status
+      );
+    }
+    const enrichData = await this.parseApiResponse(enrichRes);
+    const enrichCharacters = descriptions.reduce((sum, d) => sum + d.description.length, 0);
+    result.entryIds.push(...enrichData.entryIds);
+    result.chunks += descriptions.length;
+    result.totalCharacters += enrichCharacters;
     return result;
   }
   /**

package/dist/{chunk-QFEFLBTN.mjs → chunk-DGVOXKYV.mjs}

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

package/dist/dashboard.mjs

@@ -11,8 +11,8 @@ import {
   toGraphologyFormat,
   transformGraphData,
   unreachableHealth
-} from "./chunk-QFEFLBTN.mjs";
-import "./chunk-KVRPHFDP.mjs";
+} from "./chunk-DGVOXKYV.mjs";
+import "./chunk-5IERAVVW.mjs";
 export {
   DashboardClient,
   Poller,

package/dist/index.d.ts

@@ -71,15 +71,50 @@ interface ExtendedMemoryInterface extends MemoryInterface {
     deleteBySource(source: string): Promise<number>;
 }
 
-/** Callbacks for two-phase file enrichment. */
+/**
+ * Callbacks for two-phase file enrichment. All callbacks are optional so the
+ * SDK can support every combination of the v2 flow:
+ *   - Image-rich PDF + describeImage only → describes images, no entity extraction
+ *   - Image-rich PDF + describeImage + extractEntities[V2] → describes + extracts
+ *   - Text-only file + extractEntities[V2] only → extracts from textWindows
+ *   - Mixed file + all three → describes + extracts from both sources
+ *
+ * Without ANY callback, ingestFile returns the parsed result without running
+ * Phase 2/3 — caller opted out of enrichment entirely.
+ */
 interface EnrichmentCallbacks {
-    /** Describe an image using LLM vision. Receives the raw image buffer and metadata. */
-    describeImage: (imageBuffer: ArrayBuffer, meta: ExtractedImageMeta) => Promise<string>;
-    /** Optionally extract entities/relationships from all image descriptions. */
+    /**
+     * Describe an image using LLM vision. Receives the raw image buffer and
+     * metadata. Required for image-bearing files; safe to omit for text-only
+     * uploads where the server emits zero images.
+     */
+    describeImage?: (imageBuffer: ArrayBuffer, meta: ExtractedImageMeta) => Promise<string>;
+    /**
+     * Legacy entity-extraction callback. Receives a flat string array which
+     * the SDK constructs as `[...textWindows, ...imageDescriptions]` — callers
+     * cannot distinguish the two sources. Kept for backwards compatibility;
+     * new code should prefer {@link extractEntitiesV2}.
+     */
     extractEntities?: (descriptions: string[]) => Promise<{
         entities: IngestEntity$1[];
         relationships: IngestRelationship$1[];
     }>;
+    /**
+     * v2 entity-extraction callback. Receives text windows and image
+     * descriptions separately so callers can apply different prompts per
+     * source. Takes precedence over {@link extractEntities} when both are
+     * defined. Triggers the `X-Pyx-Enrichment-Capabilities: text_windows_v1`
+     * negotiation header on ingest.
+     */
+    extractEntitiesV2?: (input: {
+        textWindows: string[];
+        imageDescriptions: string[];
+        mimeType: string;
+        filename: string;
+    }) => Promise<{
+        entities: IngestEntity$1[];
+        relationships: IngestRelationship$1[];
+    }>;
 }
 /** Error thrown by MemoryClient when the server returns a non-success response. */
 declare class MemoryServerError extends Error {

package/dist/index.mjs

@@ -1,7 +1,7 @@
 import {
   MemoryClient,
   MemoryServerError
-} from "./chunk-KVRPHFDP.mjs";
+} from "./chunk-5IERAVVW.mjs";
 
 // ../shared/src/constants/defaults.ts
 var DEFAULTS = {

package/dist/react.mjs

@@ -11,8 +11,8 @@ import {
   toGraphologyFormat,
   transformGraphData,
   unreachableHealth
-} from "./chunk-QFEFLBTN.mjs";
-import "./chunk-KVRPHFDP.mjs";
+} from "./chunk-DGVOXKYV.mjs";
+import "./chunk-5IERAVVW.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": "0.10.0",
+  "version": "0.11.0",
   "type": "module",
   "description": "SDK for pyx-memory — Memory as a Service for AI agents",
   "license": "MIT",