@superlinked/sie-sdk 0.2.0 → 0.3.0

package/dist/index.d.cts

@@ -15,6 +15,19 @@ type DType = "float32" | "float16" | "bfloat16" | "int8" | "uint8" | "binary" |
  * Output type options for encode operation.
  */
 type OutputType = "dense" | "sparse" | "multivector";
+/**
+ * Document input for composite-document extractors (PDF, DOCX, HTML, ...).
+ *
+ * The wire format is the document bytes plus an optional format hint. The
+ * hint is advisory — adapters may sniff the bytes when it is missing or
+ * unrecognized.
+ */
+interface DocumentInput {
+    /** Document bytes (raw file content) */
+    data: Uint8Array;
+    /** Document format hint: "pdf", "docx", "html", etc. */
+    format?: string;
+}
 /**
  * A single item to encode, score, or extract from.
  *
@@ -30,6 +43,9 @@ type OutputType = "dense" | "sparse" | "multivector";
  * // With images for multimodal models (ColPali, CLIP)
  * { text: "Description", images: [imageBytes] }
  *
+ * // With a document for composite-document extractors (Docling, ...)
+ * { document: { data: pdfBytes, format: "pdf" } }
+ *
  * // Pre-encoded multivector (for use with maxsim utility)
  * { multivector: [tokenEmbedding1, tokenEmbedding2, ...] }
  */
@@ -40,6 +56,8 @@ interface Item {
     text?: string;
     /** Images as byte arrays (JPEG/PNG) for multimodal models */
     images?: Uint8Array[];
+    /** Document for composite-document extractors (PDF, DOCX, HTML, ...) */
+    document?: DocumentInput;
     /** Pre-encoded multivector (for use with maxsim utility) */
     multivector?: Float32Array[];
     /** Arbitrary metadata (passed through to results) */
@@ -98,7 +116,7 @@ interface ModelInfo {
     name: string;
     /** Whether the model is currently loaded in memory */
     loaded: boolean;
-    /** Supported input types: ["text"], ["text", "image"], etc. */
+    /** Supported input types: ["text"], ["text", "image"], ["text", "document"], etc. */
     inputs: string[];
     /** Supported output types: ["dense"], ["dense", "sparse"], etc. */
     outputs: string[];
@@ -448,7 +466,7 @@ declare function toFloat32Array(arr: number[]): Float32Array;
  *
  * @example Resource pool usage
  * ```typescript
- * const client = new SIEClient("http://router:8080");
+ * const client = new SIEClient("http://gateway:8080");
  *
  * // Create a dedicated pool
  * await client.createPool("eval-bench", { l4: 2 });
@@ -523,9 +541,9 @@ declare class SIEClient {
      */
     getModel(name: string): Promise<ModelInfo>;
     /**
-     * Stream real-time status updates from a worker or router.
+     * Stream real-time status updates from a worker or gateway.
      *
-     * @param mode - "cluster" uses router /ws/cluster-status, "worker" uses /ws/status.
+     * @param mode - "cluster" uses gateway /ws/cluster-status, "worker" uses /ws/status.
      *               "auto" detects the endpoint via /health.
      */
     watch(mode?: "auto" | "cluster" | "worker"): AsyncGenerator<StatusMessage>;
@@ -576,7 +594,7 @@ declare class SIEClient {
      * Close the client and cleanup resources.
      *
      * Stops pool lease renewal timers. Note that pools are not deleted
-     * automatically - they are garbage collected by the router after inactivity.
+     * automatically - they are garbage collected by the gateway after inactivity.
      * This allows pool reuse if the client reconnects.
      */
     close(): Promise<void>;
@@ -643,7 +661,7 @@ declare class SIEClient {
     /**
      * Get current cluster capacity information.
      *
-     * Queries the router's /health endpoint for cluster state. Useful for
+     * Queries the gateway's /health endpoint for cluster state. Useful for
      * checking if specific GPU types are available before sending requests.
      *
      * @param gpu - Optional filter to check specific GPU type availability
@@ -666,7 +684,7 @@ declare class SIEClient {
     /**
      * Wait for GPU capacity to become available.
      *
-     * Polls the router until workers with the specified GPU type are online.
+     * Polls the gateway until workers with the specified GPU type are online.
      * This is useful for pre-warming the cluster before running benchmarks.
      *
      * @param gpu - GPU type to wait for (e.g., "l4", "a100-80gb")
@@ -689,7 +707,15 @@ declare class SIEClient {
         pollInterval?: number;
     }): Promise<CapacityInfo>;
     /**
-     * Make a msgpack HTTP request with retry logic for 202 and LoRA loading.
+     * Make a msgpack HTTP request with retry logic.
+     *
+     * Retried (only when `waitForCapacity: true`, capped by `provisionTimeout`):
+     *  - 202 Accepted (provisioning)
+     *  - 503 `MODEL_LOADING` / `LORA_LOADING` / no error code (scale-from-zero)
+     *  - `SIEConnectionError` with `kind === "connect"` (issue #95)
+     *
+     * `kind === "timeout"` is NOT retried — would extend the user-visible
+     * timeout from `timeout` to `provisionTimeout`.
      */
     private requestWithRetry;
     /**
@@ -706,7 +732,7 @@ declare class SIEClient {
     private detectEndpointType;
 }
 
-declare const SDK_VERSION = "0.2.0";
+declare const SDK_VERSION = "0.3.0";
 
 /**
  * Helpers for converting SIE encode results to plain JavaScript types.
@@ -806,6 +832,11 @@ declare function multivectorEmbedding(raw: Float32Array[]): number[][];
 declare class SIEError extends Error {
     constructor(message: string);
 }
+/**
+ * `SIEConnectionError` failure category. Only `"connect"` is auto-retried
+ * under `waitForCapacity: true`; `"timeout"` and `"other"` fail fast.
+ */
+type SIEConnectionErrorKind = "connect" | "timeout" | "other";
 /**
  * Error connecting to the SIE server.
  *
@@ -816,7 +847,8 @@ declare class SIEError extends Error {
  * - Server refuses connection
  */
 declare class SIEConnectionError extends SIEError {
-    constructor(message: string);
+    readonly kind: SIEConnectionErrorKind;
+    constructor(message: string, kind?: SIEConnectionErrorKind);
 }
 /**
  * Error in the request (4xx responses).

package/dist/index.d.ts

@@ -15,6 +15,19 @@ type DType = "float32" | "float16" | "bfloat16" | "int8" | "uint8" | "binary" |
  * Output type options for encode operation.
  */
 type OutputType = "dense" | "sparse" | "multivector";
+/**
+ * Document input for composite-document extractors (PDF, DOCX, HTML, ...).
+ *
+ * The wire format is the document bytes plus an optional format hint. The
+ * hint is advisory — adapters may sniff the bytes when it is missing or
+ * unrecognized.
+ */
+interface DocumentInput {
+    /** Document bytes (raw file content) */
+    data: Uint8Array;
+    /** Document format hint: "pdf", "docx", "html", etc. */
+    format?: string;
+}
 /**
  * A single item to encode, score, or extract from.
  *
@@ -30,6 +43,9 @@ type OutputType = "dense" | "sparse" | "multivector";
  * // With images for multimodal models (ColPali, CLIP)
  * { text: "Description", images: [imageBytes] }
  *
+ * // With a document for composite-document extractors (Docling, ...)
+ * { document: { data: pdfBytes, format: "pdf" } }
+ *
  * // Pre-encoded multivector (for use with maxsim utility)
  * { multivector: [tokenEmbedding1, tokenEmbedding2, ...] }
  */
@@ -40,6 +56,8 @@ interface Item {
     text?: string;
     /** Images as byte arrays (JPEG/PNG) for multimodal models */
     images?: Uint8Array[];
+    /** Document for composite-document extractors (PDF, DOCX, HTML, ...) */
+    document?: DocumentInput;
     /** Pre-encoded multivector (for use with maxsim utility) */
     multivector?: Float32Array[];
     /** Arbitrary metadata (passed through to results) */
@@ -98,7 +116,7 @@ interface ModelInfo {
     name: string;
     /** Whether the model is currently loaded in memory */
     loaded: boolean;
-    /** Supported input types: ["text"], ["text", "image"], etc. */
+    /** Supported input types: ["text"], ["text", "image"], ["text", "document"], etc. */
     inputs: string[];
     /** Supported output types: ["dense"], ["dense", "sparse"], etc. */
     outputs: string[];
@@ -448,7 +466,7 @@ declare function toFloat32Array(arr: number[]): Float32Array;
  *
  * @example Resource pool usage
  * ```typescript
- * const client = new SIEClient("http://router:8080");
+ * const client = new SIEClient("http://gateway:8080");
  *
  * // Create a dedicated pool
  * await client.createPool("eval-bench", { l4: 2 });
@@ -523,9 +541,9 @@ declare class SIEClient {
      */
     getModel(name: string): Promise<ModelInfo>;
     /**
-     * Stream real-time status updates from a worker or router.
+     * Stream real-time status updates from a worker or gateway.
      *
-     * @param mode - "cluster" uses router /ws/cluster-status, "worker" uses /ws/status.
+     * @param mode - "cluster" uses gateway /ws/cluster-status, "worker" uses /ws/status.
      *               "auto" detects the endpoint via /health.
      */
     watch(mode?: "auto" | "cluster" | "worker"): AsyncGenerator<StatusMessage>;
@@ -576,7 +594,7 @@ declare class SIEClient {
      * Close the client and cleanup resources.
      *
      * Stops pool lease renewal timers. Note that pools are not deleted
-     * automatically - they are garbage collected by the router after inactivity.
+     * automatically - they are garbage collected by the gateway after inactivity.
      * This allows pool reuse if the client reconnects.
      */
     close(): Promise<void>;
@@ -643,7 +661,7 @@ declare class SIEClient {
     /**
      * Get current cluster capacity information.
      *
-     * Queries the router's /health endpoint for cluster state. Useful for
+     * Queries the gateway's /health endpoint for cluster state. Useful for
      * checking if specific GPU types are available before sending requests.
      *
      * @param gpu - Optional filter to check specific GPU type availability
@@ -666,7 +684,7 @@ declare class SIEClient {
     /**
      * Wait for GPU capacity to become available.
      *
-     * Polls the router until workers with the specified GPU type are online.
+     * Polls the gateway until workers with the specified GPU type are online.
      * This is useful for pre-warming the cluster before running benchmarks.
      *
      * @param gpu - GPU type to wait for (e.g., "l4", "a100-80gb")
@@ -689,7 +707,15 @@ declare class SIEClient {
         pollInterval?: number;
     }): Promise<CapacityInfo>;
     /**
-     * Make a msgpack HTTP request with retry logic for 202 and LoRA loading.
+     * Make a msgpack HTTP request with retry logic.
+     *
+     * Retried (only when `waitForCapacity: true`, capped by `provisionTimeout`):
+     *  - 202 Accepted (provisioning)
+     *  - 503 `MODEL_LOADING` / `LORA_LOADING` / no error code (scale-from-zero)
+     *  - `SIEConnectionError` with `kind === "connect"` (issue #95)
+     *
+     * `kind === "timeout"` is NOT retried — would extend the user-visible
+     * timeout from `timeout` to `provisionTimeout`.
      */
     private requestWithRetry;
     /**
@@ -706,7 +732,7 @@ declare class SIEClient {
     private detectEndpointType;
 }
 
-declare const SDK_VERSION = "0.2.0";
+declare const SDK_VERSION = "0.3.0";
 
 /**
  * Helpers for converting SIE encode results to plain JavaScript types.
@@ -806,6 +832,11 @@ declare function multivectorEmbedding(raw: Float32Array[]): number[][];
 declare class SIEError extends Error {
     constructor(message: string);
 }
+/**
+ * `SIEConnectionError` failure category. Only `"connect"` is auto-retried
+ * under `waitForCapacity: true`; `"timeout"` and `"other"` fail fast.
+ */
+type SIEConnectionErrorKind = "connect" | "timeout" | "other";
 /**
  * Error connecting to the SIE server.
  *
@@ -816,7 +847,8 @@ declare class SIEError extends Error {
  * - Server refuses connection
  */
 declare class SIEConnectionError extends SIEError {
-    constructor(message: string);
+    readonly kind: SIEConnectionErrorKind;
+    constructor(message: string, kind?: SIEConnectionErrorKind);
 }
 /**
  * Error in the request (4xx responses).

package/dist/index.js

@@ -9,9 +9,11 @@ var SIEError = class extends Error {
   }
 };
 var SIEConnectionError = class extends SIEError {
-  constructor(message) {
+  kind;
+  constructor(message, kind = "other") {
     super(message);
     this.name = "SIEConnectionError";
+    this.kind = kind;
   }
 };
 var RequestError = class extends SIEError {
@@ -103,9 +105,6 @@ var MODEL_LOADING_DEFAULT_DELAY = 5e3;
 var MODEL_LOADING_ERROR_CODE = "MODEL_LOADING";
 var SDK_VERSION_HEADER = "X-SIE-SDK-Version";
 var SERVER_VERSION_HEADER = "X-SIE-Server-Version";
-
-// src/version.ts
-var SDK_VERSION = "0.2.0";
 var EXT_TYPE_NUMPY = 78;
 function parseDtype(dtype) {
   const typeChar = dtype.slice(-2, -1);
@@ -474,6 +473,9 @@ function parseCapacityInfo(data, gpuFilter) {
   };
 }
 
+// src/version.ts
+var SDK_VERSION = "0.3.0";
+
 // src/client.ts
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
@@ -614,9 +616,9 @@ var SIEClient = class {
     };
   }
   /**
-   * Stream real-time status updates from a worker or router.
+   * Stream real-time status updates from a worker or gateway.
    *
-   * @param mode - "cluster" uses router /ws/cluster-status, "worker" uses /ws/status.
+   * @param mode - "cluster" uses gateway /ws/cluster-status, "worker" uses /ws/status.
    *               "auto" detects the endpoint via /health.
    */
   async *watch(mode = "auto") {
@@ -787,7 +789,7 @@ var SIEClient = class {
    * Close the client and cleanup resources.
    *
    * Stops pool lease renewal timers. Note that pools are not deleted
-   * automatically - they are garbage collected by the router after inactivity.
+   * automatically - they are garbage collected by the gateway after inactivity.
    * This allows pool reuse if the client reconnects.
    */
   async close() {
@@ -1044,7 +1046,7 @@ var SIEClient = class {
   /**
    * Get current cluster capacity information.
    *
-   * Queries the router's /health endpoint for cluster state. Useful for
+   * Queries the gateway's /health endpoint for cluster state. Useful for
    * checking if specific GPU types are available before sending requests.
    *
    * @param gpu - Optional filter to check specific GPU type availability
@@ -1066,10 +1068,10 @@ var SIEClient = class {
   async getCapacity(gpu) {
     const response = await this.requestJson("/health");
     const data = await response.json();
-    if (data.type !== "router") {
+    if (data.type !== "gateway") {
       throw new RequestError(
-        "getCapacity() requires a router endpoint. This appears to be a worker.",
-        "not_router",
+        "getCapacity() requires a gateway endpoint. This appears to be a worker.",
+        "not_gateway",
         400
       );
     }
@@ -1078,7 +1080,7 @@ var SIEClient = class {
   /**
    * Wait for GPU capacity to become available.
    *
-   * Polls the router until workers with the specified GPU type are online.
+   * Polls the gateway until workers with the specified GPU type are online.
    * This is useful for pre-warming the cluster before running benchmarks.
    *
    * @param gpu - GPU type to wait for (e.g., "l4", "a100-80gb")
@@ -1124,13 +1126,35 @@ var SIEClient = class {
     }
   }
   /**
-   * Make a msgpack HTTP request with retry logic for 202 and LoRA loading.
+   * Make a msgpack HTTP request with retry logic.
+   *
+   * Retried (only when `waitForCapacity: true`, capped by `provisionTimeout`):
+   *  - 202 Accepted (provisioning)
+   *  - 503 `MODEL_LOADING` / `LORA_LOADING` / no error code (scale-from-zero)
+   *  - `SIEConnectionError` with `kind === "connect"` (issue #95)
+   *
+   * `kind === "timeout"` is NOT retried — would extend the user-visible
+   * timeout from `timeout` to `provisionTimeout`.
    */
   async requestWithRetry(path, body, pool, gpu, waitForCapacity, model) {
     const startTime = Date.now();
     let loraRetries = 0;
     while (true) {
-      const response = await this.request(path, body, pool, gpu);
+      let response;
+      try {
+        response = await this.request(path, body, pool, gpu);
+      } catch (err) {
+        if (waitForCapacity && err instanceof SIEConnectionError && err.kind === "connect") {
+          const elapsed = Date.now() - startTime;
+          if (elapsed < this.provisionTimeout) {
+            const remaining = this.provisionTimeout - elapsed;
+            const delay = Math.min(DEFAULT_RETRY_DELAY, remaining);
+            await sleep(delay);
+            continue;
+          }
+        }
+        throw err;
+      }
       if (response.status === HTTP_ACCEPTED) {
         const retryAfter = getRetryAfter2(response);
         if (!waitForCapacity) {
@@ -1187,6 +1211,17 @@ var SIEClient = class {
           await sleep(actualDelay);
           continue;
         }
+        if (waitForCapacity) {
+          const elapsed = Date.now() - startTime;
+          if (elapsed < this.provisionTimeout) {
+            const retryAfter = getRetryAfter2(response);
+            const delay = retryAfter ?? DEFAULT_RETRY_DELAY;
+            const remaining = this.provisionTimeout - elapsed;
+            const actualDelay = Math.min(delay, remaining);
+            await sleep(actualDelay);
+            continue;
+          }
+        }
       }
       if (!response.ok) {
         await handleError(response, gpu);
@@ -1228,10 +1263,10 @@ var SIEClient = class {
       return response;
     } catch (error) {
       if (error instanceof Error && error.name === "AbortError") {
-        throw new SIEConnectionError(`Request timeout after ${this.timeout}ms`);
+        throw new SIEConnectionError(`Request timeout after ${this.timeout}ms`, "timeout");
       }
       if (error instanceof TypeError) {
-        throw new SIEConnectionError(`Connection failed: ${error.message}`);
+        throw new SIEConnectionError(`Connection failed: ${error.message}`, "connect");
       }
       throw error;
     } finally {
@@ -1265,10 +1300,10 @@ var SIEClient = class {
       return response;
     } catch (error) {
       if (error instanceof Error && error.name === "AbortError") {
-        throw new SIEConnectionError(`Request timeout after ${this.timeout}ms`);
+        throw new SIEConnectionError(`Request timeout after ${this.timeout}ms`, "timeout");
       }
       if (error instanceof TypeError) {
-        throw new SIEConnectionError(`Connection failed: ${error.message}`);
+        throw new SIEConnectionError(`Connection failed: ${error.message}`, "connect");
       }
       throw error;
     } finally {
@@ -1316,7 +1351,7 @@ var SIEClient = class {
         return "worker";
       }
       const data = await response.json();
-      return data.type === "router" ? "cluster" : "worker";
+      return data.type === "gateway" ? "cluster" : "worker";
     } catch {
       return "worker";
     } finally {