@superlinked/sie-sdk 0.1.8

package/dist/index.d.cts

@@ -0,0 +1,907 @@
+export { maxsim, maxsimBatch, maxsimDocuments } from './scoring.cjs';
+
+/**
+ * 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.
+ */
+type DType = "float32" | "float16" | "bfloat16" | "int8" | "uint8" | "binary" | "ubinary";
+/**
+ * Output type options for encode operation.
+ */
+type OutputType = "dense" | "sparse" | "multivector";
+/**
+ * A single item to encode, score, or extract from.
+ *
+ * For simple text encoding, just use `{ text: "your text here" }`.
+ *
+ * @example
+ * // Simple text
+ * { text: "Hello world" }
+ *
+ * // With ID for tracking through results
+ * { id: "doc-1", text: "Document text" }
+ *
+ * // With images for multimodal models (ColPali, CLIP)
+ * { text: "Description", images: [imageBytes] }
+ *
+ * // Pre-encoded multivector (for use with maxsim utility)
+ * { multivector: [tokenEmbedding1, tokenEmbedding2, ...] }
+ */
+interface Item {
+    /** Optional ID to track this item through results */
+    id?: string;
+    /** Text content to encode */
+    text?: string;
+    /** Images as byte arrays (JPEG/PNG) for multimodal models */
+    images?: Uint8Array[];
+    /** Pre-encoded multivector (for use with maxsim utility) */
+    multivector?: Float32Array[];
+    /** Arbitrary metadata (passed through to results) */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Sparse vector result with non-zero indices and values.
+ * Used by SPLADE-type models.
+ */
+interface SparseResult {
+    /** Token indices with non-zero weights */
+    indices: Int32Array;
+    /** Weight values for each index */
+    values: Float32Array;
+}
+/**
+ * Server-side timing breakdown for a request.
+ */
+interface TimingInfo {
+    totalMs?: number;
+    queueMs?: number;
+    tokenizationMs?: number;
+    inferenceMs?: number;
+}
+/**
+ * Result of encoding a single item.
+ *
+ * Contains the item ID (if provided) and one or more output representations
+ * depending on what was requested via outputTypes.
+ */
+interface EncodeResult {
+    /** Item ID (echoed from request if provided) */
+    id?: string;
+    /** Dense embedding vector, shape [dims] */
+    dense?: Float32Array;
+    /** Sparse embedding with indices and values */
+    sparse?: SparseResult;
+    /** Multi-vector embedding for late interaction models, shape [numTokens][tokenDims] */
+    multivector?: Float32Array[];
+    /** Server-side timing breakdown */
+    timing?: TimingInfo;
+}
+/**
+ * Model dimension information.
+ */
+interface ModelDims {
+    dense?: number;
+    sparse?: number;
+    multivector?: number;
+}
+/**
+ * Information about a model returned by listModels().
+ */
+interface ModelInfo {
+    /** Model name/identifier */
+    name: string;
+    /** Whether the model is currently loaded in memory */
+    loaded: boolean;
+    /** Supported input types: ["text"], ["text", "image"], etc. */
+    inputs: string[];
+    /** Supported output types: ["dense"], ["dense", "sparse"], etc. */
+    outputs: string[];
+    /** Embedding dimensions for each output type */
+    dims?: ModelDims;
+    /** Maximum sequence length the model supports */
+    maxSequenceLength?: number;
+}
+/**
+ * A single score entry from reranking.
+ */
+interface ScoreEntry {
+    /** ID of the item (from request or auto-generated) */
+    itemId: string;
+    /** Relevance score (higher = more relevant) */
+    score: number;
+    /** Position in sorted order (0 = most relevant) */
+    rank: number;
+}
+/**
+ * Result of scoring items against a query.
+ */
+interface ScoreResult {
+    /** Model used for scoring */
+    model?: string;
+    /** Query ID (echoed from request if provided) */
+    queryId?: string;
+    /** Score entries, sorted by relevance (descending) */
+    scores: ScoreEntry[];
+}
+/**
+ * A single extracted entity (NER span).
+ */
+interface Entity {
+    /** The extracted text span */
+    text: string;
+    /** Entity type/label (e.g., "person", "organization") */
+    label: string;
+    /** Confidence score */
+    score: number;
+    /** Start character offset in the original text */
+    start?: number;
+    /** End character offset in the original text */
+    end?: number;
+    /** Bounding box [x, y, width, height] for image-based extraction */
+    bbox?: number[];
+}
+/**
+ * Result of extraction for a single item.
+ */
+interface ExtractResult {
+    /** Item ID (echoed from request if provided) */
+    id?: string;
+    /** List of extracted entities */
+    entities: Entity[];
+}
+/**
+ * Information about a worker in the cluster.
+ */
+interface WorkerInfo {
+    /** Worker base URL */
+    url: string;
+    /** GPU type (e.g., "l4", "a100-80gb") */
+    gpu: string;
+    /** Whether the worker is healthy */
+    healthy: boolean;
+    /** Number of items in the worker's queue */
+    queueDepth: number;
+    /** List of model names loaded on this worker */
+    loadedModels: string[];
+}
+/**
+ * Cluster capacity information returned by getCapacity().
+ */
+interface CapacityInfo {
+    /** Overall cluster status: "healthy", "degraded", "no_workers" */
+    status: string;
+    /** Number of healthy workers */
+    workerCount: number;
+    /** Number of GPUs available */
+    gpuCount: number;
+    /** Number of unique models loaded across all workers */
+    modelsLoaded: number;
+    /** GPU types configured in the cluster */
+    configuredGpuTypes: string[];
+    /** GPU types currently running */
+    liveGpuTypes: string[];
+    /** List of worker details */
+    workers: WorkerInfo[];
+}
+/**
+ * Pool specification for creating resource pools.
+ */
+interface PoolSpec {
+    /** Pool name (used in GPU param as "poolName/gpuType") */
+    name: string;
+    /** GPU requirements, e.g., { l4: 2, "a100-40gb": 1 } */
+    gpus?: Record<string, number>;
+}
+/**
+ * Pool status information.
+ */
+interface PoolStatus {
+    /** Pool state: "pending", "active", "expired" */
+    state: string;
+    /** Workers assigned to this pool */
+    assignedWorkers: Array<{
+        name: string;
+        url: string;
+        gpu: string;
+    }>;
+    /** Unix timestamp when pool was created */
+    createdAt?: number;
+    /** Unix timestamp of last lease renewal */
+    lastRenewed?: number;
+}
+/**
+ * Full pool information.
+ */
+interface PoolInfo {
+    /** Pool name */
+    name: string;
+    /** Pool specification */
+    spec: {
+        gpus?: Record<string, number>;
+    };
+    /** Pool status */
+    status: PoolStatus;
+}
+type ModelState = "available" | "loading" | "loaded" | "unloading";
+interface ClusterSummary {
+    worker_count: number;
+    gpu_count: number;
+    models_loaded: number;
+    total_qps: number;
+}
+interface ClusterWorkerInfo {
+    url: string;
+    gpu: string;
+    healthy: boolean;
+    queue_depth: number;
+    loaded_models: string[];
+}
+interface ModelSummary {
+    name: string;
+    state: ModelState;
+    worker_count: number;
+    gpu_types: string[];
+    total_queue_depth: number;
+}
+interface ServerInfo {
+    version: string;
+    uptime_seconds: number;
+    user: string;
+    working_dir: string;
+    pid: number;
+}
+interface GPUMetrics {
+    device: string;
+    name: string;
+    gpu_type: string;
+    utilization_pct: number;
+    memory_used_bytes: number;
+    memory_total_bytes: number;
+    memory_threshold_pct?: number;
+}
+interface ModelConfig {
+    hf_id: string;
+    adapter: string;
+    inputs: string[];
+    outputs: string[];
+    dims: Record<string, number | null>;
+    max_sequence_length?: number;
+    pooling?: string | null;
+    normalize?: boolean;
+    adapter_options_loadtime?: Record<string, unknown> | null;
+    adapter_options_runtime?: Record<string, unknown> | null;
+}
+interface ModelStatus {
+    name: string;
+    state: ModelState;
+    device: string | null;
+    memory_bytes: number;
+    config: ModelConfig;
+    queue_depth: number;
+    queue_pending_items: number;
+}
+interface WorkerStatusMessage {
+    timestamp: number;
+    name: string;
+    gpu: string;
+    gpu_count: number;
+    bundle: string;
+    machine_profile: string;
+    loaded_models: string[];
+    server: ServerInfo;
+    gpus: GPUMetrics[];
+    models: ModelStatus[];
+    counters: Record<string, Record<string, number>>;
+    histograms: Record<string, Record<string, Record<string, unknown>>>;
+}
+interface ClusterStatusMessage {
+    timestamp: number;
+    cluster: ClusterSummary;
+    workers: ClusterWorkerInfo[];
+    models: ModelSummary[];
+}
+type StatusMessage = WorkerStatusMessage | ClusterStatusMessage;
+/**
+ * Options for SIEClient constructor.
+ */
+interface SIEClientOptions {
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Default GPU type for all requests (e.g., "l4", "a100-80gb") */
+    gpu?: string;
+    /** API key for authentication (sent as Bearer token) */
+    apiKey?: string;
+    /** Whether to auto-retry on 202 (provisioning) responses */
+    waitForCapacity?: boolean;
+    /** Maximum time to wait for provisioning in milliseconds (default: 300000) */
+    provisionTimeout?: number;
+}
+/**
+ * Options for encode operation.
+ */
+interface EncodeOptions {
+    /** Output types to request: ["dense"], ["sparse"], ["dense", "sparse", "multivector"] */
+    outputTypes?: OutputType[];
+    /** Instruction prefix for instruction-tuned models */
+    instruction?: string;
+    /** Whether this is a query (for asymmetric models) */
+    isQuery?: boolean;
+    /** Output dtype for quantization */
+    outputDtype?: DType;
+    /** GPU type for this request (overrides client default) */
+    gpu?: string;
+    /** Whether to wait for capacity (overrides client default) */
+    waitForCapacity?: boolean;
+}
+/**
+ * Options for score operation.
+ */
+interface ScoreOptions {
+    /** Return only top K results */
+    topK?: number;
+    /** GPU type for this request */
+    gpu?: string;
+    /** Whether to wait for capacity */
+    waitForCapacity?: boolean;
+}
+/**
+ * Options for extract operation.
+ */
+interface ExtractOptions {
+    /** Entity labels to extract (e.g., ["person", "organization"]) */
+    labels: string[];
+    /** Minimum confidence threshold (0-1) */
+    threshold?: number;
+    /** GPU type for this request */
+    gpu?: string;
+    /** Whether to wait for capacity */
+    waitForCapacity?: boolean;
+}
+/**
+ * Helper to convert typed arrays to regular number array.
+ * Useful for JSON serialization or working with libraries that expect number[].
+ */
+declare function toNumberArray(arr: Float32Array | Int32Array): number[];
+/**
+ * Helper to convert number array to Float32Array.
+ */
+declare function toFloat32Array(arr: number[]): Float32Array;
+
+/**
+ * SIE Client implementation
+ *
+ * @example
+ * ```typescript
+ * import { SIEClient } from "@superlinked/sie-sdk";
+ *
+ * const client = new SIEClient("http://localhost:8080");
+ *
+ * // Encode single item
+ * const result = await client.encode("bge-m3", { text: "Hello world" });
+ * console.log(result.dense); // Float32Array
+ *
+ * // Batch encode
+ * const results = await client.encode("bge-m3", [
+ *   { text: "First document" },
+ *   { text: "Second document" },
+ * ]);
+ *
+ * // With GPU routing and auto-retry for capacity
+ * const resultWithGpu = await client.encode(
+ *   "bge-m3",
+ *   { text: "Hello" },
+ *   { gpu: "l4", waitForCapacity: true },
+ * );
+ *
+ * await client.close();
+ * ```
+ */
+
+/**
+ * SIE Client for embedding, scoring, and extraction.
+ *
+ * The client is async-only (no synchronous methods) and uses native fetch.
+ * It handles msgpack serialization, error parsing, and retry logic.
+ *
+ * @example Resource pool usage
+ * ```typescript
+ * const client = new SIEClient("http://router:8080");
+ *
+ * // Create a dedicated pool
+ * await client.createPool("eval-bench", { l4: 2 });
+ *
+ * // Use pool for requests
+ * await client.encode("bge-m3", { text: "Hello" }, { gpu: "eval-bench/l4" });
+ *
+ * // Check pool status
+ * const pool = await client.getPool("eval-bench");
+ * console.log(`Pool state: ${pool?.status.state}`);
+ *
+ * // Clean up
+ * await client.deletePool("eval-bench");
+ * await client.close();
+ * ```
+ */
+declare class SIEClient {
+    private readonly baseUrl;
+    private readonly timeout;
+    private readonly gpu?;
+    private readonly apiKey?;
+    private readonly defaultWaitForCapacity;
+    private readonly provisionTimeout;
+    private readonly pools;
+    private versionWarningLogged;
+    /**
+     * Create a new SIE client.
+     *
+     * @param baseUrl - Base URL of the SIE server (e.g., "http://localhost:8080")
+     * @param options - Client options
+     */
+    constructor(baseUrl: string, options?: SIEClientOptions);
+    /**
+     * Get the base URL of the SIE server.
+     *
+     * @returns The normalized base URL (without trailing slash)
+     */
+    getBaseUrl(): string;
+    /**
+     * Encode a single item.
+     *
+     * @param model - Model name (e.g., "bge-m3")
+     * @param item - Item to encode
+     * @param options - Encode options
+     * @returns Encode result with embeddings
+     */
+    encode(model: string, item: Item, options?: EncodeOptions): Promise<EncodeResult>;
+    /**
+     * Encode multiple items.
+     *
+     * @param model - Model name (e.g., "bge-m3")
+     * @param items - Items to encode
+     * @param options - Encode options
+     * @returns Array of encode results in same order as input
+     */
+    encode(model: string, items: Item[], options?: EncodeOptions): Promise<EncodeResult[]>;
+    /**
+     * List available models.
+     *
+     * @returns Array of model information
+     */
+    listModels(): Promise<ModelInfo[]>;
+    /**
+     * Stream real-time status updates from a worker or router.
+     *
+     * @param mode - "cluster" uses router /ws/cluster-status, "worker" uses /ws/status.
+     *               "auto" detects the endpoint via /health.
+     */
+    watch(mode?: "auto" | "cluster" | "worker"): AsyncGenerator<StatusMessage>;
+    /**
+     * Score items against a query using a reranker model.
+     *
+     * @param model - Model name (e.g., "bge-reranker-v2")
+     * @param query - Query item
+     * @param items - Items to score against the query
+     * @param options - Score options
+     * @returns Score result with sorted scores
+     *
+     * @example
+     * ```typescript
+     * const result = await client.score(
+     *   "bge-reranker-v2",
+     *   { text: "What is machine learning?" },
+     *   [
+     *     { id: "doc-1", text: "Machine learning is..." },
+     *     { id: "doc-2", text: "Python is..." },
+     *   ],
+     * );
+     *
+     * // Scores are sorted by relevance (descending)
+     * console.log(result.scores[0].itemId); // most relevant
+     * ```
+     */
+    score(model: string, query: Item, items: Item[], options?: ScoreOptions): Promise<ScoreResult>;
+    /**
+     * Extract entities from a single item.
+     *
+     * @param model - Model name (e.g., "gliner-multi-v2.1")
+     * @param item - Item to extract from
+     * @param options - Extract options with labels
+     * @returns Extract result with entities
+     */
+    extract(model: string, item: Item, options: ExtractOptions): Promise<ExtractResult>;
+    /**
+     * Extract entities from multiple items.
+     *
+     * @param model - Model name (e.g., "gliner-multi-v2.1")
+     * @param items - Items to extract from
+     * @param options - Extract options with labels
+     * @returns Array of extract results in same order as input
+     */
+    extract(model: string, items: Item[], options: ExtractOptions): Promise<ExtractResult[]>;
+    /**
+     * 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.
+     * This allows pool reuse if the client reconnects.
+     */
+    close(): Promise<void>;
+    /**
+     * Create a resource pool for isolated capacity.
+     *
+     * Pools provide dedicated worker capacity, isolated from other clients.
+     * Workers are assigned to pools and only serve requests from that pool.
+     *
+     * @param name - Pool name (used in GPU param as "poolName/machineProfile")
+     * @param gpus - Machine profile requirements, e.g., { "l4": 2, "l4-spot": 1 }
+     *
+     * @example
+     * ```typescript
+     * // Create a pool with 2 L4 GPUs
+     * await client.createPool("eval-bench", { l4: 2 });
+     *
+     * // Use the pool for requests
+     * await client.encode("bge-m3", { text: "Hello" }, { gpu: "eval-bench/l4" });
+     *
+     * // Clean up when done
+     * await client.deletePool("eval-bench");
+     * ```
+     */
+    createPool(name: string, gpus: Record<string, number>): Promise<void>;
+    /**
+     * Get information about a pool.
+     *
+     * @param name - Pool name to query
+     * @returns PoolInfo if pool exists, null otherwise
+     *
+     * @example
+     * ```typescript
+     * await client.createPool("eval-bench", { l4: 2 });
+     * const pool = await client.getPool("eval-bench");
+     * console.log(`Pool state: ${pool?.status.state}`);
+     * console.log(`Workers: ${pool?.status.assignedWorkers.length}`);
+     * ```
+     */
+    getPool(name: string): Promise<PoolInfo | null>;
+    /**
+     * Delete a pool.
+     *
+     * @param name - Pool name to delete
+     * @returns true if pool was deleted, false if pool didn't exist
+     *
+     * @example
+     * ```typescript
+     * // Clean up pool when done
+     * const deleted = await client.deletePool("eval-bench");
+     * if (deleted) {
+     *   console.log("Pool deleted successfully");
+     * }
+     * ```
+     */
+    deletePool(name: string): Promise<boolean>;
+    private checkServerVersion;
+    /**
+     * Parse GPU parameter into pool and GPU components.
+     *
+     * Supports "pool/gpu" format for pool routing.
+     */
+    private parseGpuParam;
+    /**
+     * Get current cluster capacity information.
+     *
+     * Queries the router'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
+     * @returns CapacityInfo with worker count, GPU types, and worker details
+     *
+     * @example
+     * ```typescript
+     * // Check cluster state
+     * const capacity = await client.getCapacity();
+     * console.log(`Workers: ${capacity.workerCount}, GPUs: ${capacity.liveGpuTypes}`);
+     *
+     * // Check if L4 GPUs are available
+     * const l4Capacity = await client.getCapacity("l4");
+     * if (l4Capacity.workerCount > 0) {
+     *   console.log("L4 workers available");
+     * }
+     * ```
+     */
+    getCapacity(gpu?: string): Promise<CapacityInfo>;
+    /**
+     * Wait for GPU capacity to become available.
+     *
+     * Polls the router 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")
+     * @param options - Wait options
+     * @returns CapacityInfo once capacity is available
+     *
+     * @example
+     * ```typescript
+     * // Wait for L4 capacity before running benchmarks
+     * const capacity = await client.waitForCapacity("l4", { timeout: 300000 });
+     * console.log(`Ready with ${capacity.workerCount} L4 workers`);
+     *
+     * // Wait and pre-load a model
+     * const capacityWithModel = await client.waitForCapacity("l4", { model: "bge-m3" });
+     * ```
+     */
+    waitForCapacity(gpu: string, options?: {
+        model?: string;
+        timeout?: number;
+        pollInterval?: number;
+    }): Promise<CapacityInfo>;
+    /**
+     * Make a msgpack HTTP request with retry logic for 202 and LoRA loading.
+     */
+    private requestWithRetry;
+    /**
+     * Make a single msgpack HTTP request to the SIE server (no retry logic).
+     */
+    private request;
+    /**
+     * Make a JSON HTTP request to the SIE server.
+     * Used for endpoints that return JSON (e.g., /v1/models, /health).
+     */
+    private requestJson;
+    private buildWsUrl;
+    private createWebSocket;
+    private detectEndpointType;
+}
+
+declare const SDK_VERSION = "0.1.8";
+
+/**
+ * Error classes for the SIE TypeScript SDK.
+ *
+ * These errors mirror the Python SDK (packages/sie_sdk/src/sie_sdk/client/errors.py)
+ * for consistent error handling across languages.
+ *
+ * @example
+ * // Catching specific error types
+ * try {
+ *   await client.encode("model", { text: "hello" });
+ * } catch (error) {
+ *   if (error instanceof RequestError) {
+ *     console.error(`Bad request (${error.code}): ${error.message}`);
+ *   } else if (error instanceof ProvisioningError) {
+ *     console.log(`GPU ${error.gpu} is provisioning, retry after ${error.retryAfter}ms`);
+ *   } else if (error instanceof SIEConnectionError) {
+ *     console.error("Cannot reach server:", error.message);
+ *   }
+ * }
+ */
+/**
+ * Base error for all SIE SDK errors.
+ *
+ * All SIE errors extend this class, so you can catch all SDK errors with:
+ * `catch (error) { if (error instanceof SIEError) { ... } }`
+ */
+declare class SIEError extends Error {
+    constructor(message: string);
+}
+/**
+ * Error connecting to the SIE server.
+ *
+ * Raised when:
+ * - Network is unreachable
+ * - DNS resolution fails
+ * - Connection times out
+ * - Server refuses connection
+ */
+declare class SIEConnectionError extends SIEError {
+    constructor(message: string);
+}
+/**
+ * Error in the request (4xx responses).
+ *
+ * Raised when the client sends an invalid request:
+ * - 400: Bad request (invalid parameters, malformed body)
+ * - 401: Unauthorized (missing or invalid API key)
+ * - 403: Forbidden (insufficient permissions)
+ * - 404: Not found (invalid endpoint or model)
+ * - 422: Validation error (invalid input format)
+ */
+declare class RequestError extends SIEError {
+    /** Error code from the server (e.g., "INVALID_MODEL", "VALIDATION_ERROR") */
+    readonly code: string | undefined;
+    /** HTTP status code (400-499) */
+    readonly statusCode: number | undefined;
+    constructor(message: string, code?: string, statusCode?: number);
+}
+/**
+ * Error from the server (5xx responses).
+ *
+ * Raised when the server encounters an internal error:
+ * - 500: Internal server error
+ * - 502: Bad gateway
+ * - 503: Service unavailable
+ * - 504: Gateway timeout
+ */
+declare class ServerError extends SIEError {
+    /** Error code from the server (e.g., "INTERNAL_ERROR", "LORA_LOADING") */
+    readonly code: string | undefined;
+    /** HTTP status code (500-599) */
+    readonly statusCode: number | undefined;
+    constructor(message: string, code?: string, statusCode?: number);
+}
+/**
+ * Error when capacity is not available and provisioning timed out.
+ *
+ * Raised when:
+ * - Server returns 202 (no capacity, provisioning)
+ * - waitForCapacity is false (caller doesn't want to wait)
+ * - Or provisioning timeout exceeded
+ *
+ * The caller can use `retryAfter` to know when to retry.
+ */
+declare class ProvisioningError extends SIEError {
+    /** The GPU type that was requested */
+    readonly gpu: string | undefined;
+    /** Suggested retry delay in milliseconds (from server Retry-After header) */
+    readonly retryAfter: number | undefined;
+    constructor(message: string, gpu?: string, retryAfter?: number);
+}
+/**
+ * Error related to resource pool operations.
+ *
+ * Raised when:
+ * - Pool creation fails (e.g., insufficient capacity)
+ * - Pool not found
+ * - Pool in invalid state (e.g., expired)
+ * - Pool lease renewal fails
+ */
+declare class PoolError extends SIEError {
+    /** Name of the pool */
+    readonly poolName: string | undefined;
+    /** Current pool state (if known): "pending", "active", "expired" */
+    readonly state: string | undefined;
+    constructor(message: string, poolName?: string, state?: string);
+}
+/**
+ * Error when LoRA adapter is loading and retry limit exceeded.
+ *
+ * Raised when:
+ * - Server returns 503 with LORA_LOADING code
+ * - Retry limit is exceeded
+ *
+ * This usually means the adapter is being loaded from disk/network
+ * and the caller should wait longer or reduce request rate.
+ */
+declare class LoraLoadingError extends SIEError {
+    /** The LoRA adapter that was requested */
+    readonly lora: string | undefined;
+    /** The model the LoRA was requested for */
+    readonly model: string | undefined;
+    constructor(message: string, lora?: string, model?: string);
+}
+/**
+ * Error when model is loading and retry limit exceeded.
+ *
+ * Raised when:
+ * - Server returns 503 with MODEL_LOADING code
+ * - Retry limit is exceeded
+ *
+ * This usually means the model is being loaded from disk/HuggingFace
+ * and the caller should wait longer.
+ */
+declare class ModelLoadingError extends SIEError {
+    /** The model that was requested */
+    readonly model: string | undefined;
+    constructor(message: string, model?: string);
+}
+
+/**
+ * MessagePack serialization with msgpack-numpy compatibility.
+ *
+ * The SIE server uses Python's msgpack-numpy library which serializes numpy arrays
+ * using extension type 78 ('N'). This module provides compatible encoding/decoding.
+ *
+ * Wire format for numpy arrays (extension type 78):
+ * - dtype string (e.g., '<f4' for float32, '<i4' for int32) terminated by '|'
+ * - shape as comma-separated dimensions terminated by '|'
+ * - raw array data in little-endian format
+ */
+/**
+ * Pack a message to MessagePack format (msgpack-numpy compatible)
+ */
+declare function packMessage(data: unknown): Uint8Array;
+/**
+ * Unpack a MessagePack message (msgpack-numpy compatible)
+ *
+ * Note: msgpack-numpy uses byte string keys (b'nd', b'type', b'shape', b'data') for numpy
+ * array metadata. In JavaScript these become Uint8Array which need to be decoded as text.
+ * After decoding, we recursively convert numpy array maps to typed arrays.
+ */
+declare function unpackMessage<T = unknown>(data: Uint8Array): T;
+
+/**
+ * Image handling utilities for the SIE TypeScript SDK.
+ *
+ * Per design.md Section 4.3, 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.
+ * Per design.md Section 4.3.
+ */
+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.
+ *
+ * Per design.md Section 4.3, 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 ClusterStatusMessage, type ClusterSummary, type ClusterWorkerInfo, type DType, 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, RequestError, SDK_VERSION, SIEClient, type SIEClientOptions, SIEConnectionError, SIEError, type ScoreEntry, type ScoreOptions, type ScoreResult, ServerError, type ServerInfo, type SparseResult, type StatusMessage, type TimingInfo, type WorkerInfo, type WorkerStatusMessage, detectImageFormat, packMessage, toFloat32Array, toImageBytes, toImageWireFormat, toNumberArray, unpackMessage };