@superlinked/sie-sdk 0.1.9 → 0.2.0

package/dist/index.d.cts

@@ -146,6 +146,39 @@ interface Entity {
     /** Bounding box [x, y, width, height] for image-based extraction */
     bbox?: number[];
 }
+/**
+ * A relation triple between two entities.
+ */
+interface Relation {
+    /** Head entity text */
+    head: string;
+    /** Tail entity text */
+    tail: string;
+    /** Relation type label (e.g., "works_at", "founded_by") */
+    relation: string;
+    /** Confidence score */
+    score: number;
+}
+/**
+ * A text classification result.
+ */
+interface Classification {
+    /** Classification label (e.g., "positive", "negative") */
+    label: string;
+    /** Confidence score */
+    score: number;
+}
+/**
+ * A detected object with bounding box.
+ */
+interface DetectedObject {
+    /** Object class label (e.g., "person", "car") */
+    label: string;
+    /** Confidence score */
+    score: number;
+    /** Bounding box [x, y, width, height] */
+    bbox: number[];
+}
 /**
  * Result of extraction for a single item.
  */
@@ -154,6 +187,12 @@ interface ExtractResult {
     id?: string;
     /** List of extracted entities */
     entities: Entity[];
+    /** List of extracted relation triples */
+    relations: Relation[];
+    /** List of classification results */
+    classifications: Classification[];
+    /** List of detected objects */
+    objects: DetectedObject[];
 }
 /**
  * Information about a worker in the cluster.
@@ -343,8 +382,6 @@ interface EncodeOptions {
  * 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 */
@@ -474,6 +511,17 @@ declare class SIEClient {
      * @returns Array of model information
      */
     listModels(): Promise<ModelInfo[]>;
+    /**
+     * Get details for a specific model.
+     *
+     * Returns model metadata including dimensions, supported inputs/outputs,
+     * loaded status, and max sequence length. This is a lightweight call that
+     * reads from model config — it does not load the model or trigger inference.
+     *
+     * @param name - Model name (e.g., "BAAI/bge-m3")
+     * @returns Model information
+     */
+    getModel(name: string): Promise<ModelInfo>;
     /**
      * Stream real-time status updates from a worker or router.
      *
@@ -658,7 +706,76 @@ declare class SIEClient {
     private detectEndpointType;
 }
 
-declare const SDK_VERSION = "0.1.9";
+declare const SDK_VERSION = "0.2.0";
+
+/**
+ * Helpers for converting SIE encode results to plain JavaScript types.
+ *
+ * These functions bridge SDK result types (Float32Array, typed dicts) to the
+ * plain `number[]` / object formats that framework integrations and vector
+ * databases expect.
+ *
+ * @example
+ * ```typescript
+ * import { SIEClient, denseEmbedding, sparseEmbedding } from "@superlinked/sie-sdk";
+ *
+ * const client = new SIEClient("http://localhost:8080");
+ * const result = await client.encode("BAAI/bge-m3", { text: "hello" });
+ * const vec = denseEmbedding(result);   // number[]
+ * const sp  = sparseEmbedding(result);  // { indices: number[], values: number[] }
+ * ```
+ */
+
+/** Sparse vector in `{ indices, values }` format. */
+interface SparseVector {
+    indices: number[];
+    values: number[];
+}
+/**
+ * Extract the dense embedding from an encode result as `number[]`.
+ *
+ * @param result - An {@link EncodeResult} from `client.encode()`.
+ * @param strict - If `true` (default), throw when dense is missing. If `false`, return `[]`.
+ * @returns The dense vector as a plain JavaScript number array.
+ */
+declare function denseEmbedding(result: EncodeResult, strict?: boolean): number[];
+/**
+ * Extract the sparse embedding from an encode result.
+ *
+ * @param result - An {@link EncodeResult} from `client.encode()`.
+ * @returns Object with `indices: number[]` and `values: number[]`. Empty arrays if sparse is absent.
+ */
+declare function sparseEmbedding(result: EncodeResult): SparseVector;
+/**
+ * Extract the sparse embedding as a `Map<number, number>` (token index → weight).
+ *
+ * Useful for ChromaDB which expects sparse embeddings in this format.
+ *
+ * @param result - An {@link EncodeResult} from `client.encode()`.
+ * @returns Map from integer token indices to float weights. Empty map if sparse is absent.
+ */
+declare function sparseEmbeddingMap(result: EncodeResult): Map<number, number>;
+/**
+ * Convert a raw sparse sub-object to plain JavaScript arrays.
+ *
+ * Unlike {@link sparseEmbedding}, this takes the sparse value itself
+ * (already extracted from the result) — useful inside named-vector
+ * loops where you've already pulled `result.sparse`.
+ *
+ * @param sparse - A {@link SparseResult} with `indices` and `values` typed arrays.
+ * @returns Object with `indices: number[]` and `values: number[]`.
+ */
+declare function normalizeSparseVector(sparse: SparseResult): SparseVector;
+/**
+ * Convert a multivector (ColBERT) result to `number[][]`.
+ *
+ * SIE returns multivectors as `Float32Array[]`. Vector databases expect
+ * nested plain JavaScript arrays.
+ *
+ * @param raw - Array of Float32Array token vectors.
+ * @returns Nested array of number vectors.
+ */
+declare function multivectorEmbedding(raw: Float32Array[]): number[][];
 
 /**
  * Error classes for the SIE TypeScript SDK.
@@ -904,4 +1021,4 @@ declare function toImageWireFormat(input: ImageInput, format?: "jpeg" | "png" |
  */
 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 };
+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 };

package/dist/index.d.ts

@@ -146,6 +146,39 @@ interface Entity {
     /** Bounding box [x, y, width, height] for image-based extraction */
     bbox?: number[];
 }
+/**
+ * A relation triple between two entities.
+ */
+interface Relation {
+    /** Head entity text */
+    head: string;
+    /** Tail entity text */
+    tail: string;
+    /** Relation type label (e.g., "works_at", "founded_by") */
+    relation: string;
+    /** Confidence score */
+    score: number;
+}
+/**
+ * A text classification result.
+ */
+interface Classification {
+    /** Classification label (e.g., "positive", "negative") */
+    label: string;
+    /** Confidence score */
+    score: number;
+}
+/**
+ * A detected object with bounding box.
+ */
+interface DetectedObject {
+    /** Object class label (e.g., "person", "car") */
+    label: string;
+    /** Confidence score */
+    score: number;
+    /** Bounding box [x, y, width, height] */
+    bbox: number[];
+}
 /**
  * Result of extraction for a single item.
  */
@@ -154,6 +187,12 @@ interface ExtractResult {
     id?: string;
     /** List of extracted entities */
     entities: Entity[];
+    /** List of extracted relation triples */
+    relations: Relation[];
+    /** List of classification results */
+    classifications: Classification[];
+    /** List of detected objects */
+    objects: DetectedObject[];
 }
 /**
  * Information about a worker in the cluster.
@@ -343,8 +382,6 @@ interface EncodeOptions {
  * 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 */
@@ -474,6 +511,17 @@ declare class SIEClient {
      * @returns Array of model information
      */
     listModels(): Promise<ModelInfo[]>;
+    /**
+     * Get details for a specific model.
+     *
+     * Returns model metadata including dimensions, supported inputs/outputs,
+     * loaded status, and max sequence length. This is a lightweight call that
+     * reads from model config — it does not load the model or trigger inference.
+     *
+     * @param name - Model name (e.g., "BAAI/bge-m3")
+     * @returns Model information
+     */
+    getModel(name: string): Promise<ModelInfo>;
     /**
      * Stream real-time status updates from a worker or router.
      *
@@ -658,7 +706,76 @@ declare class SIEClient {
     private detectEndpointType;
 }
 
-declare const SDK_VERSION = "0.1.9";
+declare const SDK_VERSION = "0.2.0";
+
+/**
+ * Helpers for converting SIE encode results to plain JavaScript types.
+ *
+ * These functions bridge SDK result types (Float32Array, typed dicts) to the
+ * plain `number[]` / object formats that framework integrations and vector
+ * databases expect.
+ *
+ * @example
+ * ```typescript
+ * import { SIEClient, denseEmbedding, sparseEmbedding } from "@superlinked/sie-sdk";
+ *
+ * const client = new SIEClient("http://localhost:8080");
+ * const result = await client.encode("BAAI/bge-m3", { text: "hello" });
+ * const vec = denseEmbedding(result);   // number[]
+ * const sp  = sparseEmbedding(result);  // { indices: number[], values: number[] }
+ * ```
+ */
+
+/** Sparse vector in `{ indices, values }` format. */
+interface SparseVector {
+    indices: number[];
+    values: number[];
+}
+/**
+ * Extract the dense embedding from an encode result as `number[]`.
+ *
+ * @param result - An {@link EncodeResult} from `client.encode()`.
+ * @param strict - If `true` (default), throw when dense is missing. If `false`, return `[]`.
+ * @returns The dense vector as a plain JavaScript number array.
+ */
+declare function denseEmbedding(result: EncodeResult, strict?: boolean): number[];
+/**
+ * Extract the sparse embedding from an encode result.
+ *
+ * @param result - An {@link EncodeResult} from `client.encode()`.
+ * @returns Object with `indices: number[]` and `values: number[]`. Empty arrays if sparse is absent.
+ */
+declare function sparseEmbedding(result: EncodeResult): SparseVector;
+/**
+ * Extract the sparse embedding as a `Map<number, number>` (token index → weight).
+ *
+ * Useful for ChromaDB which expects sparse embeddings in this format.
+ *
+ * @param result - An {@link EncodeResult} from `client.encode()`.
+ * @returns Map from integer token indices to float weights. Empty map if sparse is absent.
+ */
+declare function sparseEmbeddingMap(result: EncodeResult): Map<number, number>;
+/**
+ * Convert a raw sparse sub-object to plain JavaScript arrays.
+ *
+ * Unlike {@link sparseEmbedding}, this takes the sparse value itself
+ * (already extracted from the result) — useful inside named-vector
+ * loops where you've already pulled `result.sparse`.
+ *
+ * @param sparse - A {@link SparseResult} with `indices` and `values` typed arrays.
+ * @returns Object with `indices: number[]` and `values: number[]`.
+ */
+declare function normalizeSparseVector(sparse: SparseResult): SparseVector;
+/**
+ * Convert a multivector (ColBERT) result to `number[][]`.
+ *
+ * SIE returns multivectors as `Float32Array[]`. Vector databases expect
+ * nested plain JavaScript arrays.
+ *
+ * @param raw - Array of Float32Array token vectors.
+ * @returns Nested array of number vectors.
+ */
+declare function multivectorEmbedding(raw: Float32Array[]): number[][];
 
 /**
  * Error classes for the SIE TypeScript SDK.
@@ -904,4 +1021,4 @@ declare function toImageWireFormat(input: ImageInput, format?: "jpeg" | "png" |
  */
 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 };
+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 };

package/dist/index.js

@@ -105,7 +105,7 @@ var SDK_VERSION_HEADER = "X-SIE-SDK-Version";
 var SERVER_VERSION_HEADER = "X-SIE-Server-Version";
 
 // src/version.ts
-var SDK_VERSION = "0.1.9";
+var SDK_VERSION = "0.2.0";
 var EXT_TYPE_NUMPY = 78;
 function parseDtype(dtype) {
   const typeChar = dtype.slice(-2, -1);
@@ -422,7 +422,28 @@ function parseEntity(data) {
 function parseExtractResult(data) {
   return {
     id: data.id,
-    entities: data.entities.map(parseEntity)
+    entities: data.entities.map(parseEntity),
+    relations: (data.relations ?? []).map(
+      (r) => ({
+        head: r.head,
+        tail: r.tail,
+        relation: r.relation,
+        score: r.score
+      })
+    ),
+    classifications: (data.classifications ?? []).map(
+      (c) => ({
+        label: c.label,
+        score: c.score
+      })
+    ),
+    objects: (data.objects ?? []).map(
+      (o) => ({
+        label: o.label,
+        score: o.score,
+        bbox: o.bbox
+      })
+    )
   };
 }
 function parseExtractResults(data) {
@@ -570,6 +591,28 @@ var SIEClient = class {
       maxSequenceLength: m.max_sequence_length
     }));
   }
+  /**
+   * Get details for a specific model.
+   *
+   * Returns model metadata including dimensions, supported inputs/outputs,
+   * loaded status, and max sequence length. This is a lightweight call that
+   * reads from model config — it does not load the model or trigger inference.
+   *
+   * @param name - Model name (e.g., "BAAI/bge-m3")
+   * @returns Model information
+   */
+  async getModel(name) {
+    const response = await this.requestJson(`/v1/models/${encodeURIComponent(name)}`, "GET");
+    const data = await response.json();
+    return {
+      name: data.name,
+      loaded: data.loaded,
+      inputs: data.inputs,
+      outputs: data.outputs,
+      dims: data.dims,
+      maxSequenceLength: data.max_sequence_length
+    };
+  }
   /**
    * Stream real-time status updates from a worker or router.
    *
@@ -674,9 +717,6 @@ var SIEClient = class {
       query,
       items
     };
-    if (options.topK !== void 0) {
-      body.top_k = options.topK;
-    }
     const waitForCapacity = options.waitForCapacity ?? this.defaultWaitForCapacity;
     const { pool, gpu } = this.parseGpuParam(options.gpu);
     const response = await this.requestWithRetry(
@@ -1293,6 +1333,50 @@ function toFloat32Array(arr) {
   return new Float32Array(arr);
 }
 
+// src/encoding.ts
+function denseEmbedding(result, strict = true) {
+  const dense = result.dense;
+  if (!dense) {
+    if (strict) {
+      throw new Error("Encode result missing dense embedding");
+    }
+    return [];
+  }
+  return toNumberArray(dense);
+}
+function sparseEmbedding(result) {
+  const sparse = result.sparse;
+  if (!sparse) {
+    return { indices: [], values: [] };
+  }
+  return {
+    indices: toNumberArray(sparse.indices),
+    values: toNumberArray(sparse.values)
+  };
+}
+function sparseEmbeddingMap(result) {
+  const sparse = result.sparse;
+  if (!sparse) {
+    return /* @__PURE__ */ new Map();
+  }
+  const indices = toNumberArray(sparse.indices);
+  const values = toNumberArray(sparse.values);
+  const map = /* @__PURE__ */ new Map();
+  for (let i = 0; i < indices.length; i++) {
+    map.set(indices[i], values[i]);
+  }
+  return map;
+}
+function normalizeSparseVector(sparse) {
+  return {
+    indices: toNumberArray(sparse.indices),
+    values: toNumberArray(sparse.values)
+  };
+}
+function multivectorEmbedding(raw) {
+  return raw.map((v) => toNumberArray(v));
+}
+
 // src/scoring.ts
 function maxsim(query, document) {
   if (query.length === 0 || document.length === 0) {
@@ -1380,6 +1464,6 @@ function detectImageFormat(bytes) {
   return "unknown";
 }
 
-export { LoraLoadingError, ModelLoadingError, PoolError, ProvisioningError, RequestError, SDK_VERSION, SIEClient, SIEConnectionError, SIEError, ServerError, detectImageFormat, maxsim, maxsimBatch, maxsimDocuments, packMessage, toFloat32Array, toImageBytes, toImageWireFormat, toNumberArray, unpackMessage };
+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 };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map