@superlinked/sie-sdk 0.3.0 → 0.3.1

package/dist/index.d.cts

@@ -732,7 +732,7 @@ declare class SIEClient {
     private detectEndpointType;
 }
 
-declare const SDK_VERSION = "0.3.0";
+declare const SDK_VERSION = "0.3.1";
 
 /**
  * Helpers for converting SIE encode results to plain JavaScript types.
@@ -948,6 +948,39 @@ declare class ModelLoadingError extends SIEError {
     readonly model: string | undefined;
     constructor(message: string, model?: string);
 }
+/**
+ * Error when the server reports a *terminal* model-load failure.
+ *
+ * Distinct from {@link ModelLoadingError} — this is thrown on the first
+ * response (no retry budget consumed) when the server returns HTTP
+ * `502 MODEL_LOAD_FAILED`. The server uses this code for permanent-class
+ * failures (gated repos, missing dependencies, unrecognised model
+ * architectures) where retrying would waste time. See sie-test#85.
+ *
+ * Permanent failures will not auto-clear; an operator must fix the
+ * underlying cause (e.g. set `HF_TOKEN`, accept the model license on
+ * HuggingFace, upgrade `transformers`).
+ */
+declare class ModelLoadFailedError extends ServerError {
+    /** The model that was requested */
+    readonly model: string | undefined;
+    /**
+     * Server-side classification: one of `GATED`, `OOM`, `DEPENDENCY`,
+     * `NOT_FOUND`, `NETWORK`, `UNKNOWN`. Use this to route to specific
+     * remediation paths (e.g. surface a "set HF_TOKEN" hint for `GATED`).
+     */
+    readonly errorClass: string | undefined;
+    /** Whether the failure is non-retryable per server policy. */
+    readonly permanent: boolean;
+    /** How many load attempts the server has logged. */
+    readonly attempts: number;
+    constructor(message: string, options?: {
+        model?: string;
+        errorClass?: string;
+        permanent?: boolean;
+        attempts?: number;
+    });
+}
 
 /**
  * MessagePack serialization with msgpack-numpy compatibility.
@@ -1053,4 +1086,4 @@ declare function toImageWireFormat(input: ImageInput, format?: "jpeg" | "png" |
  */
 declare function detectImageFormat(bytes: Uint8Array): "jpeg" | "png" | "webp" | "unknown";
 
-export { type CapacityInfo, type Classification, type ClusterStatusMessage, type ClusterSummary, type ClusterWorkerInfo, type DType, type DetectedObject, type EncodeOptions, type EncodeResult, type Entity, type ExtractOptions, type ExtractResult, type GPUMetrics, type ImageInput, type ImageWireFormat, type Item, LoraLoadingError, type ModelConfig, type ModelDims, type ModelInfo, ModelLoadingError, type ModelState, type ModelStatus, type ModelSummary, type OutputType, PoolError, type PoolInfo, type PoolSpec, type PoolStatus, ProvisioningError, type Relation, RequestError, SDK_VERSION, SIEClient, type SIEClientOptions, SIEConnectionError, SIEError, type ScoreEntry, type ScoreOptions, type ScoreResult, ServerError, type ServerInfo, type SparseResult, type SparseVector, type StatusMessage, type TimingInfo, type WorkerInfo, type WorkerStatusMessage, denseEmbedding, detectImageFormat, multivectorEmbedding, normalizeSparseVector, packMessage, sparseEmbedding, sparseEmbeddingMap, toFloat32Array, toImageBytes, toImageWireFormat, toNumberArray, unpackMessage };
+export { type CapacityInfo, type Classification, type ClusterStatusMessage, type ClusterSummary, type ClusterWorkerInfo, type DType, type DetectedObject, type EncodeOptions, type EncodeResult, type Entity, type ExtractOptions, type ExtractResult, type GPUMetrics, type ImageInput, type ImageWireFormat, type Item, LoraLoadingError, type ModelConfig, type ModelDims, type ModelInfo, ModelLoadFailedError, ModelLoadingError, type ModelState, type ModelStatus, type ModelSummary, type OutputType, PoolError, type PoolInfo, type PoolSpec, type PoolStatus, ProvisioningError, type Relation, RequestError, SDK_VERSION, SIEClient, type SIEClientOptions, SIEConnectionError, SIEError, type ScoreEntry, type ScoreOptions, type ScoreResult, ServerError, type ServerInfo, type SparseResult, type SparseVector, type StatusMessage, type TimingInfo, type WorkerInfo, type WorkerStatusMessage, denseEmbedding, detectImageFormat, multivectorEmbedding, normalizeSparseVector, packMessage, sparseEmbedding, sparseEmbeddingMap, toFloat32Array, toImageBytes, toImageWireFormat, toNumberArray, unpackMessage };

package/dist/index.d.ts

@@ -732,7 +732,7 @@ declare class SIEClient {
     private detectEndpointType;
 }
 
-declare const SDK_VERSION = "0.3.0";
+declare const SDK_VERSION = "0.3.1";
 
 /**
  * Helpers for converting SIE encode results to plain JavaScript types.
@@ -948,6 +948,39 @@ declare class ModelLoadingError extends SIEError {
     readonly model: string | undefined;
     constructor(message: string, model?: string);
 }
+/**
+ * Error when the server reports a *terminal* model-load failure.
+ *
+ * Distinct from {@link ModelLoadingError} — this is thrown on the first
+ * response (no retry budget consumed) when the server returns HTTP
+ * `502 MODEL_LOAD_FAILED`. The server uses this code for permanent-class
+ * failures (gated repos, missing dependencies, unrecognised model
+ * architectures) where retrying would waste time. See sie-test#85.
+ *
+ * Permanent failures will not auto-clear; an operator must fix the
+ * underlying cause (e.g. set `HF_TOKEN`, accept the model license on
+ * HuggingFace, upgrade `transformers`).
+ */
+declare class ModelLoadFailedError extends ServerError {
+    /** The model that was requested */
+    readonly model: string | undefined;
+    /**
+     * Server-side classification: one of `GATED`, `OOM`, `DEPENDENCY`,
+     * `NOT_FOUND`, `NETWORK`, `UNKNOWN`. Use this to route to specific
+     * remediation paths (e.g. surface a "set HF_TOKEN" hint for `GATED`).
+     */
+    readonly errorClass: string | undefined;
+    /** Whether the failure is non-retryable per server policy. */
+    readonly permanent: boolean;
+    /** How many load attempts the server has logged. */
+    readonly attempts: number;
+    constructor(message: string, options?: {
+        model?: string;
+        errorClass?: string;
+        permanent?: boolean;
+        attempts?: number;
+    });
+}
 
 /**
  * MessagePack serialization with msgpack-numpy compatibility.
@@ -1053,4 +1086,4 @@ declare function toImageWireFormat(input: ImageInput, format?: "jpeg" | "png" |
  */
 declare function detectImageFormat(bytes: Uint8Array): "jpeg" | "png" | "webp" | "unknown";
 
-export { type CapacityInfo, type Classification, type ClusterStatusMessage, type ClusterSummary, type ClusterWorkerInfo, type DType, type DetectedObject, type EncodeOptions, type EncodeResult, type Entity, type ExtractOptions, type ExtractResult, type GPUMetrics, type ImageInput, type ImageWireFormat, type Item, LoraLoadingError, type ModelConfig, type ModelDims, type ModelInfo, ModelLoadingError, type ModelState, type ModelStatus, type ModelSummary, type OutputType, PoolError, type PoolInfo, type PoolSpec, type PoolStatus, ProvisioningError, type Relation, RequestError, SDK_VERSION, SIEClient, type SIEClientOptions, SIEConnectionError, SIEError, type ScoreEntry, type ScoreOptions, type ScoreResult, ServerError, type ServerInfo, type SparseResult, type SparseVector, type StatusMessage, type TimingInfo, type WorkerInfo, type WorkerStatusMessage, denseEmbedding, detectImageFormat, multivectorEmbedding, normalizeSparseVector, packMessage, sparseEmbedding, sparseEmbeddingMap, toFloat32Array, toImageBytes, toImageWireFormat, toNumberArray, unpackMessage };
+export { type CapacityInfo, type Classification, type ClusterStatusMessage, type ClusterSummary, type ClusterWorkerInfo, type DType, type DetectedObject, type EncodeOptions, type EncodeResult, type Entity, type ExtractOptions, type ExtractResult, type GPUMetrics, type ImageInput, type ImageWireFormat, type Item, LoraLoadingError, type ModelConfig, type ModelDims, type ModelInfo, ModelLoadFailedError, ModelLoadingError, type ModelState, type ModelStatus, type ModelSummary, type OutputType, PoolError, type PoolInfo, type PoolSpec, type PoolStatus, ProvisioningError, type Relation, RequestError, SDK_VERSION, SIEClient, type SIEClientOptions, SIEConnectionError, SIEError, type ScoreEntry, type ScoreOptions, type ScoreResult, ServerError, type ServerInfo, type SparseResult, type SparseVector, type StatusMessage, type TimingInfo, type WorkerInfo, type WorkerStatusMessage, denseEmbedding, detectImageFormat, multivectorEmbedding, normalizeSparseVector, packMessage, sparseEmbedding, sparseEmbeddingMap, toFloat32Array, toImageBytes, toImageWireFormat, toNumberArray, unpackMessage };

package/dist/index.js

@@ -85,6 +85,28 @@ var ModelLoadingError = class extends SIEError {
     this.model = model;
   }
 };
+var ModelLoadFailedError = class extends ServerError {
+  /** The model that was requested */
+  model;
+  /**
+   * Server-side classification: one of `GATED`, `OOM`, `DEPENDENCY`,
+   * `NOT_FOUND`, `NETWORK`, `UNKNOWN`. Use this to route to specific
+   * remediation paths (e.g. surface a "set HF_TOKEN" hint for `GATED`).
+   */
+  errorClass;
+  /** Whether the failure is non-retryable per server policy. */
+  permanent;
+  /** How many load attempts the server has logged. */
+  attempts;
+  constructor(message, options) {
+    super(message, "MODEL_LOAD_FAILED", 502);
+    this.name = "ModelLoadFailedError";
+    this.model = options?.model;
+    this.errorClass = options?.errorClass;
+    this.permanent = options?.permanent ?? true;
+    this.attempts = options?.attempts ?? 1;
+  }
+};
 
 // src/internal/constants.ts
 var MSGPACK_CONTENT_TYPE = "application/msgpack";
@@ -309,7 +331,7 @@ function getRetryAfter2(response) {
   const header = response.headers.get("Retry-After");
   return getRetryAfter(header);
 }
-async function getErrorCode(response) {
+async function getErrorDetail(response) {
   try {
     const contentType = response.headers.get("content-type") ?? "";
     let data;
@@ -320,24 +342,42 @@ async function getErrorCode(response) {
       data = await response.json();
     }
     if (data.error && typeof data.error === "object") {
-      const error = data.error;
-      if (typeof error.code === "string") {
-        return error.code;
-      }
+      return data.error;
     }
     if (data.detail && typeof data.detail === "object") {
-      const detail = data.detail;
-      if (typeof detail.code === "string") {
-        return detail.code;
-      }
+      return data.detail;
     }
     if (typeof data.code === "string") {
-      return data.code;
+      return data;
     }
   } catch {
   }
   return void 0;
 }
+async function getErrorCode(response) {
+  const detail = await getErrorDetail(response);
+  if (!detail) return void 0;
+  const code = detail.code;
+  return typeof code === "string" ? code : void 0;
+}
+async function throwIfModelLoadFailed(response, model) {
+  if (response.status !== 502) return;
+  const detail = await getErrorDetail(response.clone());
+  if (!detail) return;
+  if (detail.code !== "MODEL_LOAD_FAILED") return;
+  const errorClass = typeof detail.error_class === "string" ? detail.error_class : void 0;
+  const permanent = typeof detail.permanent === "boolean" ? detail.permanent : true;
+  const attemptsRaw = detail.attempts;
+  const parsedAttempts = typeof attemptsRaw === "number" ? attemptsRaw : typeof attemptsRaw === "string" ? Number.parseInt(attemptsRaw, 10) : Number.NaN;
+  const attempts = Number.isFinite(parsedAttempts) ? parsedAttempts : 1;
+  const message = typeof detail.message === "string" ? detail.message : `Model '${model ?? "?"}' failed to load`;
+  throw new ModelLoadFailedError(message, {
+    model,
+    errorClass,
+    permanent,
+    attempts
+  });
+}
 async function handleError(response, gpu) {
   const { status } = response;
   let errorBody = {};
@@ -474,7 +514,7 @@ function parseCapacityInfo(data, gpuFilter) {
 }
 
 // src/version.ts
-var SDK_VERSION = "0.3.0";
+var SDK_VERSION = "0.3.1";
 
 // src/client.ts
 function sleep(ms) {
@@ -1178,6 +1218,7 @@ var SIEClient = class {
         await sleep(actualDelay);
         continue;
       }
+      await throwIfModelLoadFailed(response, model);
       if (response.status === 503) {
         const clonedResponse = response.clone();
         const errorCode = await getErrorCode(clonedResponse);
@@ -1499,6 +1540,6 @@ function detectImageFormat(bytes) {
   return "unknown";
 }
 
-export { LoraLoadingError, ModelLoadingError, PoolError, ProvisioningError, RequestError, SDK_VERSION, SIEClient, SIEConnectionError, SIEError, ServerError, denseEmbedding, detectImageFormat, maxsim, maxsimBatch, maxsimDocuments, multivectorEmbedding, normalizeSparseVector, packMessage, sparseEmbedding, sparseEmbeddingMap, toFloat32Array, toImageBytes, toImageWireFormat, toNumberArray, unpackMessage };
+export { LoraLoadingError, ModelLoadFailedError, ModelLoadingError, PoolError, ProvisioningError, RequestError, SDK_VERSION, SIEClient, SIEConnectionError, SIEError, ServerError, denseEmbedding, detectImageFormat, maxsim, maxsimBatch, maxsimDocuments, multivectorEmbedding, normalizeSparseVector, packMessage, sparseEmbedding, sparseEmbeddingMap, toFloat32Array, toImageBytes, toImageWireFormat, toNumberArray, unpackMessage };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map