@superlinked/sie-sdk 0.6.3 → 0.6.5

package/dist/index.d.cts

@@ -1,11 +1,91 @@
 export { maxsim, maxsimBatch, maxsimDocuments } from './scoring.cjs';
 
+/**
+ * Image handling utilities for the SIE TypeScript SDK.
+ *
+ * Images are serialized as bytes for transport.
+ * This module handles conversion from various input formats to Uint8Array.
+ *
+ * Supported input formats:
+ * - Uint8Array (raw bytes)
+ * - ArrayBuffer / Buffer (Node.js)
+ * - Blob / File (browser)
+ * - string (base64 or data URL)
+ *
+ * @example
+ * ```typescript
+ * import { toImageBytes } from "@superlinked/sie-sdk";
+ *
+ * // From file input (browser)
+ * const file = document.querySelector('input[type="file"]').files[0];
+ * const bytes = await toImageBytes(file);
+ *
+ * // From base64 string
+ * const bytes = await toImageBytes(base64String);
+ *
+ * // From Uint8Array (passthrough)
+ * const bytes = await toImageBytes(existingBytes);
+ * ```
+ */
+/**
+ * Type for all supported image input formats.
+ */
+type ImageInput = Uint8Array | ArrayBuffer | Blob | string;
+/**
+ * Wire format for images sent to the server.
+ */
+interface ImageWireFormat {
+    data: Uint8Array;
+    format: "jpeg" | "png" | "webp";
+}
+/**
+ * Convert various image input types to Uint8Array.
+ *
+ * Accepts:
+ * - Uint8Array: passed through as-is
+ * - ArrayBuffer / Buffer: wrapped in Uint8Array
+ * - Blob / File: read as ArrayBuffer then wrapped
+ * - string: decoded from base64 or data URL
+ *
+ * @param input - Image data in any supported format
+ * @returns Image bytes as Uint8Array
+ *
+ * @example
+ * ```typescript
+ * // From base64 string
+ * const bytes = await toImageBytes(base64String);
+ *
+ * // From file (browser)
+ * const bytes = await toImageBytes(file);
+ * ```
+ */
+declare function toImageBytes(input: ImageInput): Promise<Uint8Array>;
+/**
+ * Convert image bytes to wire format for transport.
+ *
+ * Images are sent as:
+ * `{ data: <bytes>, format: "jpeg" | "png" | "webp" }`
+ *
+ * @param input - Image data in any supported format
+ * @param format - Image format (defaults to "jpeg")
+ * @returns Image in wire format
+ */
+declare function toImageWireFormat(input: ImageInput, format?: "jpeg" | "png" | "webp"): Promise<ImageWireFormat>;
+/**
+ * Detect image format from bytes (magic number check).
+ *
+ * @param bytes - Image bytes
+ * @returns Detected format or "unknown"
+ */
+declare function detectImageFormat(bytes: Uint8Array): "jpeg" | "png" | "webp" | "unknown";
+
 /**
  * Types for the SIE TypeScript SDK
  *
  * These types mirror the Python SDK (packages/sie_sdk/src/sie_sdk/types.py)
  * for full feature parity.
  */
+
 /**
  * Output dtype options for quantized embeddings.
  * Matches Python DType literal.
@@ -54,8 +134,8 @@ interface Item {
     id?: string;
     /** Text content to encode */
     text?: string;
-    /** Images as byte arrays (JPEG/PNG) for multimodal models */
-    images?: Uint8Array[];
+    /** Images for multimodal models; converted to wire format by the client */
+    images?: (ImageInput | ImageWireFormat)[];
     /** Document for composite-document extractors (PDF, DOCX, HTML, ...) */
     document?: DocumentInput;
     /** Pre-encoded multivector (for use with maxsim utility) */
@@ -412,7 +492,7 @@ interface SIEClientOptions {
     gpu?: string;
     /** API key for authentication (sent as Bearer token) */
     apiKey?: string;
-    /** Whether to auto-retry on 202 (provisioning) responses */
+    /** Whether to auto-retry on 503 PROVISIONING responses */
     waitForCapacity?: boolean;
     /** Maximum time to wait for provisioning in milliseconds (default: 300000) */
     provisionTimeout?: number;
@@ -736,7 +816,7 @@ interface ChatCompletionChunk {
 interface ChatCompletionOptions {
     /**
      * When `true`, retry the SAFE pre-execution capacity signals
-     * (`202 Accepted`, `503 MODEL_LOADING`, generic `503`) until
+     * (`503 PROVISIONING`, `503 MODEL_LOADING`) until
      * `provisionTimeoutMs` elapses. When `false`, the first such signal
      * throws (`ProvisioningError` / `ModelLoadingError` / `ServerError`).
      * Defaults to the client's `waitForCapacity` (false unless the
@@ -1103,11 +1183,11 @@ declare class SIEClient {
      * if the consumer-supplied `extractError` returns an `SIEStreamError`, the
      * generator throws it instead of yielding the chunk.
      *
-     * Retry policy mirrors {@link generate}: only the SAFE pre-execution
-     * capacity signals — `202` (provisioning) and `503 MODEL_LOADING` — are
-     * retried, and only while `waitForCapacity` is set and the provision
-     * budget remains. Once the body opens we never retry (the call is
-     * non-idempotent; a mid-stream failure must not re-issue generation).
+     * Retry policy mirrors {@link generate}: only explicit SAFE
+     * pre-execution capacity signals — `503 PROVISIONING` and
+     * `503 MODEL_LOADING` — are retried while the provision budget remains.
+     * Once the body opens we never retry (the call is non-idempotent; a
+     * mid-stream failure must not re-issue generation).
      *
      * @internal
      */
@@ -1257,9 +1337,9 @@ declare class SIEClient {
     /**
      * 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)
+     * Retried (capped by `provisionTimeout`):
+     *  - 503 `PROVISIONING` when `waitForCapacity: true`
+     *  - 503 `MODEL_LOADING` / `LORA_LOADING`
      *  - `SIEConnectionError` with `kind === "connect"` (issue #95)
      *
      * `kind === "timeout"` is NOT retried — would extend the user-visible
@@ -1280,7 +1360,7 @@ declare class SIEClient {
     private detectEndpointType;
 }
 
-declare const SDK_VERSION = "0.6.3";
+declare const SDK_VERSION = "0.6.5";
 
 /**
  * Helpers for converting SIE encode results to plain JavaScript types.
@@ -1435,7 +1515,7 @@ declare class ServerError extends SIEError {
  * Error when capacity is not available and provisioning timed out.
  *
  * Raised when:
- * - Server returns 202 (no capacity, provisioning)
+ * - Server returns 503 with PROVISIONING code
  * - waitForCapacity is false (caller doesn't want to wait)
  * - Or provisioning timeout exceeded
  *
@@ -1601,83 +1681,4 @@ declare function packMessage(data: unknown): Uint8Array;
  */
 declare function unpackMessage<T = unknown>(data: Uint8Array): T;
 
-/**
- * Image handling utilities for the SIE TypeScript SDK.
- *
- * Images are serialized as bytes for transport.
- * This module handles conversion from various input formats to Uint8Array.
- *
- * Supported input formats:
- * - Uint8Array (raw bytes)
- * - ArrayBuffer / Buffer (Node.js)
- * - Blob / File (browser)
- * - string (base64 or data URL)
- *
- * @example
- * ```typescript
- * import { toImageBytes } from "@superlinked/sie-sdk";
- *
- * // From file input (browser)
- * const file = document.querySelector('input[type="file"]').files[0];
- * const bytes = await toImageBytes(file);
- *
- * // From base64 string
- * const bytes = await toImageBytes(base64String);
- *
- * // From Uint8Array (passthrough)
- * const bytes = await toImageBytes(existingBytes);
- * ```
- */
-/**
- * Type for all supported image input formats.
- */
-type ImageInput = Uint8Array | ArrayBuffer | Blob | string;
-/**
- * Wire format for images sent to the server.
- */
-interface ImageWireFormat {
-    data: Uint8Array;
-    format: "jpeg" | "png" | "webp";
-}
-/**
- * Convert various image input types to Uint8Array.
- *
- * Accepts:
- * - Uint8Array: passed through as-is
- * - ArrayBuffer / Buffer: wrapped in Uint8Array
- * - Blob / File: read as ArrayBuffer then wrapped
- * - string: decoded from base64 or data URL
- *
- * @param input - Image data in any supported format
- * @returns Image bytes as Uint8Array
- *
- * @example
- * ```typescript
- * // From base64 string
- * const bytes = await toImageBytes(base64String);
- *
- * // From file (browser)
- * const bytes = await toImageBytes(file);
- * ```
- */
-declare function toImageBytes(input: ImageInput): Promise<Uint8Array>;
-/**
- * Convert image bytes to wire format for transport.
- *
- * Images are sent as:
- * `{ data: <bytes>, format: "jpeg" | "png" | "webp" }`
- *
- * @param input - Image data in any supported format
- * @param format - Image format (defaults to "jpeg")
- * @returns Image in wire format
- */
-declare function toImageWireFormat(input: ImageInput, format?: "jpeg" | "png" | "webp"): Promise<ImageWireFormat>;
-/**
- * Detect image format from bytes (magic number check).
- *
- * @param bytes - Image bytes
- * @returns Detected format or "unknown"
- */
-declare function detectImageFormat(bytes: Uint8Array): "jpeg" | "png" | "webp" | "unknown";
-
 export { type CapacityInfo, type ChatChoice, type ChatChunkChoice, type ChatCompletion, type ChatCompletionChunk, type ChatCompletionRequest, type ChatDelta, type ChatFinishReason, type ChatMessage, type ChatUsage, type Classification, type ClusterStatusMessage, type ClusterSummary, type ClusterWorkerInfo, type DType, type DetectedObject, type EncodeOptions, type EncodeResult, type Entity, type ExtractOptions, type ExtractResult, type FinishReason, type GPUMetrics, type GenerateChunk, type GenerateOptions, type GenerateResult, type GenerationUsage, type ImageInput, type ImageWireFormat, InputTooLongError, type Item, LoraLoadingError, type ModelCapabilities, 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, type ResponseFormat, SDK_VERSION, SIEClient, type SIEClientOptions, SIEConnectionError, SIEError, SIEStreamError, type ScoreEntry, type ScoreOptions, type ScoreResult, ServerError, type ServerInfo, type SparseResult, type SparseVector, type StatusMessage, type TimingInfo, type ToolCall, type ToolCallDelta, type ToolChoice, type ToolSpec, type WorkerInfo, type WorkerStatusMessage, denseEmbedding, detectImageFormat, multivectorEmbedding, normalizeSparseVector, packMessage, sparseEmbedding, sparseEmbeddingMap, toFloat32Array, toImageBytes, toImageWireFormat, toNumberArray, unpackMessage };

package/dist/index.d.ts

@@ -1,11 +1,91 @@
 export { maxsim, maxsimBatch, maxsimDocuments } from './scoring.js';
 
+/**
+ * Image handling utilities for the SIE TypeScript SDK.
+ *
+ * Images are serialized as bytes for transport.
+ * This module handles conversion from various input formats to Uint8Array.
+ *
+ * Supported input formats:
+ * - Uint8Array (raw bytes)
+ * - ArrayBuffer / Buffer (Node.js)
+ * - Blob / File (browser)
+ * - string (base64 or data URL)
+ *
+ * @example
+ * ```typescript
+ * import { toImageBytes } from "@superlinked/sie-sdk";
+ *
+ * // From file input (browser)
+ * const file = document.querySelector('input[type="file"]').files[0];
+ * const bytes = await toImageBytes(file);
+ *
+ * // From base64 string
+ * const bytes = await toImageBytes(base64String);
+ *
+ * // From Uint8Array (passthrough)
+ * const bytes = await toImageBytes(existingBytes);
+ * ```
+ */
+/**
+ * Type for all supported image input formats.
+ */
+type ImageInput = Uint8Array | ArrayBuffer | Blob | string;
+/**
+ * Wire format for images sent to the server.
+ */
+interface ImageWireFormat {
+    data: Uint8Array;
+    format: "jpeg" | "png" | "webp";
+}
+/**
+ * Convert various image input types to Uint8Array.
+ *
+ * Accepts:
+ * - Uint8Array: passed through as-is
+ * - ArrayBuffer / Buffer: wrapped in Uint8Array
+ * - Blob / File: read as ArrayBuffer then wrapped
+ * - string: decoded from base64 or data URL
+ *
+ * @param input - Image data in any supported format
+ * @returns Image bytes as Uint8Array
+ *
+ * @example
+ * ```typescript
+ * // From base64 string
+ * const bytes = await toImageBytes(base64String);
+ *
+ * // From file (browser)
+ * const bytes = await toImageBytes(file);
+ * ```
+ */
+declare function toImageBytes(input: ImageInput): Promise<Uint8Array>;
+/**
+ * Convert image bytes to wire format for transport.
+ *
+ * Images are sent as:
+ * `{ data: <bytes>, format: "jpeg" | "png" | "webp" }`
+ *
+ * @param input - Image data in any supported format
+ * @param format - Image format (defaults to "jpeg")
+ * @returns Image in wire format
+ */
+declare function toImageWireFormat(input: ImageInput, format?: "jpeg" | "png" | "webp"): Promise<ImageWireFormat>;
+/**
+ * Detect image format from bytes (magic number check).
+ *
+ * @param bytes - Image bytes
+ * @returns Detected format or "unknown"
+ */
+declare function detectImageFormat(bytes: Uint8Array): "jpeg" | "png" | "webp" | "unknown";
+
 /**
  * Types for the SIE TypeScript SDK
  *
  * These types mirror the Python SDK (packages/sie_sdk/src/sie_sdk/types.py)
  * for full feature parity.
  */
+
 /**
  * Output dtype options for quantized embeddings.
  * Matches Python DType literal.
@@ -54,8 +134,8 @@ interface Item {
     id?: string;
     /** Text content to encode */
     text?: string;
-    /** Images as byte arrays (JPEG/PNG) for multimodal models */
-    images?: Uint8Array[];
+    /** Images for multimodal models; converted to wire format by the client */
+    images?: (ImageInput | ImageWireFormat)[];
     /** Document for composite-document extractors (PDF, DOCX, HTML, ...) */
     document?: DocumentInput;
     /** Pre-encoded multivector (for use with maxsim utility) */
@@ -412,7 +492,7 @@ interface SIEClientOptions {
     gpu?: string;
     /** API key for authentication (sent as Bearer token) */
     apiKey?: string;
-    /** Whether to auto-retry on 202 (provisioning) responses */
+    /** Whether to auto-retry on 503 PROVISIONING responses */
     waitForCapacity?: boolean;
     /** Maximum time to wait for provisioning in milliseconds (default: 300000) */
     provisionTimeout?: number;
@@ -736,7 +816,7 @@ interface ChatCompletionChunk {
 interface ChatCompletionOptions {
     /**
      * When `true`, retry the SAFE pre-execution capacity signals
-     * (`202 Accepted`, `503 MODEL_LOADING`, generic `503`) until
+     * (`503 PROVISIONING`, `503 MODEL_LOADING`) until
      * `provisionTimeoutMs` elapses. When `false`, the first such signal
      * throws (`ProvisioningError` / `ModelLoadingError` / `ServerError`).
      * Defaults to the client's `waitForCapacity` (false unless the
@@ -1103,11 +1183,11 @@ declare class SIEClient {
      * if the consumer-supplied `extractError` returns an `SIEStreamError`, the
      * generator throws it instead of yielding the chunk.
      *
-     * Retry policy mirrors {@link generate}: only the SAFE pre-execution
-     * capacity signals — `202` (provisioning) and `503 MODEL_LOADING` — are
-     * retried, and only while `waitForCapacity` is set and the provision
-     * budget remains. Once the body opens we never retry (the call is
-     * non-idempotent; a mid-stream failure must not re-issue generation).
+     * Retry policy mirrors {@link generate}: only explicit SAFE
+     * pre-execution capacity signals — `503 PROVISIONING` and
+     * `503 MODEL_LOADING` — are retried while the provision budget remains.
+     * Once the body opens we never retry (the call is non-idempotent; a
+     * mid-stream failure must not re-issue generation).
      *
      * @internal
      */
@@ -1257,9 +1337,9 @@ declare class SIEClient {
     /**
      * 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)
+     * Retried (capped by `provisionTimeout`):
+     *  - 503 `PROVISIONING` when `waitForCapacity: true`
+     *  - 503 `MODEL_LOADING` / `LORA_LOADING`
      *  - `SIEConnectionError` with `kind === "connect"` (issue #95)
      *
      * `kind === "timeout"` is NOT retried — would extend the user-visible
@@ -1280,7 +1360,7 @@ declare class SIEClient {
     private detectEndpointType;
 }
 
-declare const SDK_VERSION = "0.6.3";
+declare const SDK_VERSION = "0.6.5";
 
 /**
  * Helpers for converting SIE encode results to plain JavaScript types.
@@ -1435,7 +1515,7 @@ declare class ServerError extends SIEError {
  * Error when capacity is not available and provisioning timed out.
  *
  * Raised when:
- * - Server returns 202 (no capacity, provisioning)
+ * - Server returns 503 with PROVISIONING code
  * - waitForCapacity is false (caller doesn't want to wait)
  * - Or provisioning timeout exceeded
  *
@@ -1601,83 +1681,4 @@ declare function packMessage(data: unknown): Uint8Array;
  */
 declare function unpackMessage<T = unknown>(data: Uint8Array): T;
 
-/**
- * Image handling utilities for the SIE TypeScript SDK.
- *
- * Images are serialized as bytes for transport.
- * This module handles conversion from various input formats to Uint8Array.
- *
- * Supported input formats:
- * - Uint8Array (raw bytes)
- * - ArrayBuffer / Buffer (Node.js)
- * - Blob / File (browser)
- * - string (base64 or data URL)
- *
- * @example
- * ```typescript
- * import { toImageBytes } from "@superlinked/sie-sdk";
- *
- * // From file input (browser)
- * const file = document.querySelector('input[type="file"]').files[0];
- * const bytes = await toImageBytes(file);
- *
- * // From base64 string
- * const bytes = await toImageBytes(base64String);
- *
- * // From Uint8Array (passthrough)
- * const bytes = await toImageBytes(existingBytes);
- * ```
- */
-/**
- * Type for all supported image input formats.
- */
-type ImageInput = Uint8Array | ArrayBuffer | Blob | string;
-/**
- * Wire format for images sent to the server.
- */
-interface ImageWireFormat {
-    data: Uint8Array;
-    format: "jpeg" | "png" | "webp";
-}
-/**
- * Convert various image input types to Uint8Array.
- *
- * Accepts:
- * - Uint8Array: passed through as-is
- * - ArrayBuffer / Buffer: wrapped in Uint8Array
- * - Blob / File: read as ArrayBuffer then wrapped
- * - string: decoded from base64 or data URL
- *
- * @param input - Image data in any supported format
- * @returns Image bytes as Uint8Array
- *
- * @example
- * ```typescript
- * // From base64 string
- * const bytes = await toImageBytes(base64String);
- *
- * // From file (browser)
- * const bytes = await toImageBytes(file);
- * ```
- */
-declare function toImageBytes(input: ImageInput): Promise<Uint8Array>;
-/**
- * Convert image bytes to wire format for transport.
- *
- * Images are sent as:
- * `{ data: <bytes>, format: "jpeg" | "png" | "webp" }`
- *
- * @param input - Image data in any supported format
- * @param format - Image format (defaults to "jpeg")
- * @returns Image in wire format
- */
-declare function toImageWireFormat(input: ImageInput, format?: "jpeg" | "png" | "webp"): Promise<ImageWireFormat>;
-/**
- * Detect image format from bytes (magic number check).
- *
- * @param bytes - Image bytes
- * @returns Detected format or "unknown"
- */
-declare function detectImageFormat(bytes: Uint8Array): "jpeg" | "png" | "webp" | "unknown";
-
 export { type CapacityInfo, type ChatChoice, type ChatChunkChoice, type ChatCompletion, type ChatCompletionChunk, type ChatCompletionRequest, type ChatDelta, type ChatFinishReason, type ChatMessage, type ChatUsage, type Classification, type ClusterStatusMessage, type ClusterSummary, type ClusterWorkerInfo, type DType, type DetectedObject, type EncodeOptions, type EncodeResult, type Entity, type ExtractOptions, type ExtractResult, type FinishReason, type GPUMetrics, type GenerateChunk, type GenerateOptions, type GenerateResult, type GenerationUsage, type ImageInput, type ImageWireFormat, InputTooLongError, type Item, LoraLoadingError, type ModelCapabilities, 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, type ResponseFormat, SDK_VERSION, SIEClient, type SIEClientOptions, SIEConnectionError, SIEError, SIEStreamError, type ScoreEntry, type ScoreOptions, type ScoreResult, ServerError, type ServerInfo, type SparseResult, type SparseVector, type StatusMessage, type TimingInfo, type ToolCall, type ToolCallDelta, type ToolChoice, type ToolSpec, type WorkerInfo, type WorkerStatusMessage, denseEmbedding, detectImageFormat, multivectorEmbedding, normalizeSparseVector, packMessage, sparseEmbedding, sparseEmbeddingMap, toFloat32Array, toImageBytes, toImageWireFormat, toNumberArray, unpackMessage };