@pyxmate/memory 0.10.0 → 0.12.1

package/dist/{chunk-KVRPHFDP.mjs → chunk-4YIKI2BA.mjs}

@@ -11,24 +11,31 @@ var MemoryServerError = class extends Error {
     return this.status === 404;
   }
 };
+var DEFAULT_REQUEST_TIMEOUT_MS = 3e4;
 var MemoryClient = class {
   baseUrl;
   _authHeaders;
+  _requestTimeoutMs;
   constructor(memoryUrl, apiKeyOrOptions) {
     this.baseUrl = memoryUrl.replace(/\/$/, "");
     let apiKey;
     let defaultHeaders = {};
+    let requestTimeoutMs = DEFAULT_REQUEST_TIMEOUT_MS;
     if (typeof apiKeyOrOptions === "string") {
       apiKey = apiKeyOrOptions;
     } else if (apiKeyOrOptions) {
       apiKey = apiKeyOrOptions.apiKey;
       defaultHeaders = apiKeyOrOptions.defaultHeaders ?? {};
+      if (apiKeyOrOptions.requestTimeoutMs !== void 0) {
+        requestTimeoutMs = apiKeyOrOptions.requestTimeoutMs;
+      }
     }
     const trimmed = apiKey?.trim();
     this._authHeaders = {
       ...trimmed ? { Authorization: `Bearer ${trimmed}` } : {},
       ...defaultHeaders
     };
+    this._requestTimeoutMs = requestTimeoutMs;
   }
   /** Encode a path segment to prevent URL injection */
   encodePathSegment(segment) {
@@ -112,21 +119,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 +165,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;
   }
   /**
@@ -302,16 +342,44 @@ var MemoryClient = class {
     return result.entries;
   }
   async fetchApi(path, options) {
-    const res = await fetch(`${this.baseUrl}${path}`, {
-      ...options,
-      headers: {
-        "Content-Type": "application/json",
-        ...options?.headers,
-        ...this._authHeaders
-      }
-    });
+    const signal = options?.signal ?? AbortSignal.timeout(this._requestTimeoutMs);
+    let res;
+    try {
+      res = await fetch(`${this.baseUrl}${path}`, {
+        ...options,
+        headers: {
+          "Content-Type": "application/json",
+          ...options?.headers,
+          ...this._authHeaders
+        },
+        signal
+      });
+    } catch (err) {
+      throw this.translateFetchError(err, path);
+    }
     return this.parseApiResponse(res);
   }
+  /**
+   * Map fetch-layer rejections into a typed `MemoryServerError` so callers
+   * can react uniformly. AbortSignal.timeout fires a `TimeoutError`; the
+   * caller's signal generally fires an `AbortError`. Anything else (DNS,
+   * TCP reset, TLS) becomes a wrapped error with status 0.
+   */
+  translateFetchError(err, path) {
+    if (err instanceof Error) {
+      if (err.name === "TimeoutError") {
+        return new MemoryServerError(
+          `Memory server request timed out after ${this._requestTimeoutMs}ms (${path})`,
+          504
+        );
+      }
+      if (err.name === "AbortError") {
+        return new MemoryServerError(`Memory server request aborted (${path})`, 499);
+      }
+      return new MemoryServerError(`Memory server request failed: ${err.message} (${path})`, 0);
+    }
+    return new MemoryServerError(`Memory server request failed: ${String(err)} (${path})`, 0);
+  }
   /** Parse and validate a JSON API response, throwing MemoryServerError on any failure. */
   async parseApiResponse(res) {
     let body;

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

@@ -1,6 +1,6 @@
 import {
   MemoryClient
-} from "./chunk-KVRPHFDP.mjs";
+} from "./chunk-4YIKI2BA.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-DZZHJ66P.mjs";
+import "./chunk-4YIKI2BA.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 {
@@ -93,10 +128,26 @@ interface MemoryClientOptions {
     apiKey?: string;
     /** Additional headers to send with every request (e.g., X-Caller-Access-Level). */
     defaultHeaders?: Record<string, string>;
+    /**
+     * Default per-request timeout in milliseconds. Without this, a wedged
+     * memory server (e.g. event-loop blocked by inference) makes every
+     * caller hang forever — that was the Korens demo wedge in 2026-04 where
+     * a 161-second pyx-memory stall propagated through the runtime to the
+     * browser. Defaults to 30 s, which is high enough that normal
+     * `/search` and `/stats` requests never hit it but low enough that a
+     * stuck server fails loudly.
+     *
+     * Only applied when the caller does NOT pass their own `signal` via
+     * RequestInit. Long-running operations (large `consolidate`, `reindex`,
+     * file ingest with enrichment) should pass their own AbortSignal —
+     * that signal fully replaces the default ceiling.
+     */
+    requestTimeoutMs?: number;
 }
 declare class MemoryClient implements ExtendedMemoryInterface {
     protected baseUrl: string;
     private readonly _authHeaders;
+    private readonly _requestTimeoutMs;
     constructor(memoryUrl: string, apiKeyOrOptions?: string | MemoryClientOptions);
     /** Encode a path segment to prevent URL injection */
     private encodePathSegment;
@@ -156,6 +207,13 @@ declare class MemoryClient implements ExtendedMemoryInterface {
     queryAsOf(asOfDate: string, filters?: TemporalQueryFilters): Promise<MemoryEntry$1[]>;
     queryByEventTime(startTime: string, endTime: string, filters?: TemporalQueryFilters): Promise<MemoryEntry$1[]>;
     protected fetchApi<T>(path: string, options?: RequestInit): Promise<T>;
+    /**
+     * Map fetch-layer rejections into a typed `MemoryServerError` so callers
+     * can react uniformly. AbortSignal.timeout fires a `TimeoutError`; the
+     * caller's signal generally fires an `AbortError`. Anything else (DNS,
+     * TCP reset, TLS) becomes a wrapped error with status 0.
+     */
+    private translateFetchError;
     /** Parse and validate a JSON API response, throwing MemoryServerError on any failure. */
     private parseApiResponse;
 }

package/dist/index.mjs

@@ -1,7 +1,7 @@
 import {
   MemoryClient,
   MemoryServerError
-} from "./chunk-KVRPHFDP.mjs";
+} from "./chunk-4YIKI2BA.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-DZZHJ66P.mjs";
+import "./chunk-4YIKI2BA.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.12.1",
   "type": "module",
   "description": "SDK for pyx-memory — Memory as a Service for AI agents",
   "license": "MIT",