@wiscale/velesdb-sdk 1.14.4 → 1.17.0

package/README.md

@@ -2,11 +2,15 @@
 
 Official TypeScript SDK for [VelesDB](https://github.com/cyberlife-coder/VelesDB) -- the local-first vector database for AI and RAG. Sub-millisecond semantic search in Browser and Node.js.
 
-**v1.14.4** | Node.js >= 18 | Browser (WASM) | MIT License
+**v1.17.0** | Node.js >= 18 | Browser (WASM) | MIT License
 
-## What's New in v1.14.2
+## What's New in v1.16.0
 
-- **No SDK source change.** v1.14.2 is a workspace patch focused on the Python Haystack `DocumentStore` (`DuplicatePolicy.SKIP` contract fix) and seven version-drift gaps in the release tooling. The TS SDK ships in lock-step with the workspace and is functionally identical to v1.14.1; the version bump only ensures `npm install @wiscale/velesdb-sdk` resolves to the same release line as `pip install velesdb` and `cargo add velesdb-core@1.14.2`.
+- **First-party embedding helper.** New `OpenAIEmbedder` (plus the `Embedder` interface and `OpenAIEmbedderOptions` type), exported from the package root. It calls any OpenAI-compatible `/embeddings` endpoint via the global `fetch` API — no extra runtime dependency — so you can go from text to vectors without hand-writing the request. See [Embedding helper](#embedding-helper) below. Works in Node.js ≥ 18, browsers, and Deno.
+
+### Previous (v1.14.2)
+
+- **No SDK source change.** v1.14.2 was a workspace patch focused on the Python Haystack `DocumentStore` (`DuplicatePolicy.SKIP` contract fix) and seven version-drift gaps in the release tooling. The TS SDK ships in lock-step with the workspace and was functionally identical to v1.14.1.
 
 ### Previous (v1.14.1)
 
@@ -125,6 +129,7 @@ await db.upsertBatch('documents', [
 ]);
 
 // 5. Search for similar vectors
+const queryVector = new Float32Array(768).fill(0.1);
 const results = await db.search('documents', queryVector, { k: 5 });
 console.log(results);
 // [{ id: 'doc-1', score: 0.95, payload: { title: 'Hello World', ... } }, ...]
@@ -151,6 +156,7 @@ await db.init();
 // Same API as WASM backend
 await db.createCollection('products', { dimension: 1536 });
 await db.upsert('products', { id: 1, vector: embedding });
+const queryVector = new Float32Array(1536).fill(0.1);
 const results = await db.search('products', queryVector, { k: 10 });
 ```
 
@@ -161,6 +167,39 @@ const results = await db.search('products', queryVector, { k: 10 });
 > are accepted for backward compatibility but are deprecated and will be removed
 > in a future major version. Always target `/v1/` in custom HTTP clients.
 
+## Embedding helper
+
+The SDK ships an optional `OpenAIEmbedder` so you can turn text into vectors without
+writing the HTTP call yourself. It targets any OpenAI-compatible `/embeddings`
+endpoint (OpenAI, Azure OpenAI, vLLM, …) using the global `fetch` API, so it adds
+**no extra runtime dependency** and runs in Node.js ≥ 18, browsers, and Deno.
+
+```typescript
+import { VelesDB, OpenAIEmbedder } from '@wiscale/velesdb-sdk';
+
+const embedder = new OpenAIEmbedder({
+  apiKey: process.env.OPENAI_API_KEY!,
+  model: 'text-embedding-3-small', // default; pass `dimensions` to truncate
+});
+
+const db = new VelesDB({ backend: 'wasm' });
+await db.init();
+
+// Embed first so the collection dimension matches the model output.
+const vectors = await embedder.embed(['hello world', 'vector search']);
+await db.createCollection('docs', { dimension: embedder.dimension, metric: 'cosine' });
+await db.upsertBatch('docs', vectors.map((vector, i) => ({ id: `doc-${i}`, vector })));
+
+const [query] = await embedder.embed(['greeting']);
+const results = await db.search('docs', query, { k: 5 });
+```
+
+`embedder.dimension` is `0` until the first `embed()` call (or until you pass
+`dimensions` to the constructor), at which point it is inferred from the model's
+output. To use a different provider, set `baseUrl`. Implement the `Embedder`
+interface (`{ dimension: number; embed(texts: string[]): Promise<number[][]> }`)
+to plug in any other embedding source.
+
 ## API Reference
 
 ### Client
@@ -312,7 +351,7 @@ Vector similarity search.
 ```typescript
 const results = await db.search('docs', queryVector, {
   k: 10,
-  filter: { category: 'tech' },
+  filter: { condition: { type: 'eq', field: 'category', value: 'tech' } },
   includeVectors: true
 });
 // Returns: SearchResult[] = [{ id, score, payload?, vector? }, ...]
@@ -325,7 +364,7 @@ Execute multiple search queries in parallel.
 ```typescript
 const batchResults = await db.searchBatch('docs', [
   { vector: queryA, k: 5 },
-  { vector: queryB, k: 10, filter: { type: 'article' } },
+  { vector: queryB, k: 10, filter: { condition: { type: 'eq', field: 'type', value: 'article' } } },
 ]);
 // Returns: SearchResult[][] (one result array per query)
 ```
@@ -430,6 +469,37 @@ const results = await db.multiQuerySearch('docs', [emb1, emb2], {
 
 > **Note:** WASM supports `rrf`, `average`, `maximum`. The `weighted` and `relative_score` strategies are REST-only.
 
+#### Named sparse indexes — `sparseIndexName` vs `sparseSearchNamed()`
+
+A collection can carry multiple sparse indexes (e.g. `splade_v2`, `bm25_titles`). The TypeScript SDK exposes two distinct APIs depending on whether you want a dense + sparse hybrid query or a pure sparse query against a named index.
+
+| API | Shape | Use when |
+|---|---|---|
+| `db.search(coll, denseVec, { sparseVector, sparseIndexName })` | dense + sparse hybrid against the named sparse index | You already have a dense embedding and want to combine it with a specific named sparse index in a single search call. The dense vector drives the primary candidate set; the named sparse index re-ranks. |
+| `db.sparseSearchNamed(coll, sparseVec, indexName, options?)` | pure sparse against a named index | You have only a sparse vector (e.g. SPLADE expansion, lexical query) and want to query a specific named sparse index directly. No dense component. |
+
+```typescript
+// Hybrid: dense + sparse via the splade_v2 named index
+const hybrid = await db.search('docs', denseEmbedding, {
+  k: 10,
+  sparseVector: { 42: 0.8, 99: 0.3 },
+  sparseIndexName: 'splade_v2',
+});
+
+// Pure sparse against the same named index
+const sparseOnly = await db.sparseSearchNamed(
+  'docs',
+  { 42: 0.8, 99: 0.3 },
+  'splade_v2',
+  { k: 10 },
+);
+```
+
+When the collection has only one (default) sparse index, omit `sparseIndexName` on `db.search()`; the server picks the default. For named indexes, both APIs require the explicit name.
+
+> **Note:** Both APIs are REST-only when a named index is required.
+> The WASM backend has no concept of named sparse indexes — `sparseIndexName` is silently ignored on `db.search()` (the collection's single sparse index is used), and `db.sparseSearchNamed()` throws `wasmNotSupported`. Tracked as a follow-up to either surface a `wasmNotSupported` throw on `sparseIndexName` or implement named-sparse support in WASM.
+
 ---
 
 ### Collection Utilities
@@ -507,7 +577,7 @@ const combined = await db.query('users',
 
 // Fusion strategy
 const fused = await db.query('docs',
-  "SELECT * FROM docs USING FUSION(strategy = 'rrf', k = 60) LIMIT 20"
+  "SELECT * FROM docs LIMIT 20 USING FUSION(strategy = 'rrf', k = 60)"
 );
 ```
 
@@ -797,6 +867,11 @@ import {
   VelesDB,
   AgentMemoryClient,
 
+  // Embedding helper
+  OpenAIEmbedder,
+  type Embedder,
+  type OpenAIEmbedderOptions,
+
   // Backends (advanced: use VelesDB client instead)
   WasmBackend,
   RestBackend,

package/dist/index.d.mts

@@ -376,6 +376,30 @@ declare const f: {
  * @packageDocumentation
  */
 
+/**
+ * Options for `db.sparseSearchNamed()` — **pure sparse** query against a
+ * named sparse index (issue #380).
+ *
+ * Use this when you have only a sparse vector and want to query a specific
+ * named sparse index directly. The query carries no dense component.
+ *
+ * For **dense + sparse hybrid** against a named index, use
+ * `db.search(..., { sparseVector, sparseIndexName })` instead
+ * (see {@link SearchOptions.sparseIndexName}).
+ *
+ * **Backend support:** REST only. The WASM backend has no concept of named
+ * sparse indexes; this method throws `wasmNotSupported` on WASM.
+ */
+interface SparseSearchNamedOptions {
+    /** Number of results to return (default: 10) */
+    k?: number;
+    /** Filter expression */
+    filter?: FilterInput;
+    /** Optional dense vector to combine with sparse for hybrid named search */
+    vector?: number[] | Float32Array;
+    /** Search quality preset */
+    quality?: SearchQuality;
+}
 /** Search options */
 interface SearchOptions {
     /** Number of results to return (default: 10) */
@@ -386,6 +410,18 @@ interface SearchOptions {
     includeVectors?: boolean;
     /** Optional sparse vector for hybrid sparse+dense search */
     sparseVector?: SparseVector;
+    /**
+     * Named sparse index to combine with the dense query for **hybrid** search
+     * (when the collection has multiple sparse indexes). When omitted, the
+     * default sparse index is used.
+     *
+     * For a **pure sparse** query against a named index (no dense vector),
+     * call `db.sparseSearchNamed()` instead — see {@link SparseSearchNamedOptions}.
+     *
+     * **Backend support:** REST only. The WASM backend silently ignores this
+     * field and uses the collection's single sparse index regardless.
+     */
+    sparseIndexName?: string;
     /** Search quality preset (default: 'balanced'). */
     quality?: SearchQuality;
 }
@@ -612,8 +648,8 @@ interface ColumnStatsDetail {
     name: string;
     nullCount: number;
     distinctCount: number;
-    minValue: unknown | null;
-    maxValue: unknown | null;
+    minValue: unknown;
+    maxValue: unknown;
     avgSizeBytes: number;
     histogramBuckets: number | null;
     histogramStale: boolean | null;
@@ -1152,6 +1188,17 @@ interface IVelesDBBackend {
     traverseParallel(collection: string, request: TraverseParallelRequest): Promise<TraverseResponse>;
     /** Get the in-degree and out-degree of a node */
     getNodeDegree(collection: string, nodeId: number): Promise<DegreeResponse>;
+    /**
+     * Search a named sparse index (issue #380).
+     *
+     * Sends `sparse_vectors: { [indexName]: query }` and `sparse_index: indexName`
+     * to the `/search` endpoint. When `options.vector` is provided, the request
+     * also includes a dense vector for hybrid sparse+dense search against the
+     * named index.
+     *
+     * WASM backend: not supported (throws `VelesDB-WASM-NOT-SUPPORTED`).
+     */
+    sparseSearchNamed(collection: string, query: SparseVector, indexName: string, options?: SparseSearchNamedOptions): Promise<SearchResult[]>;
     /** Train Product Quantization on a collection */
     trainPq(collection: string, options?: PqTrainOptions): Promise<string>;
     /** Stream-insert documents with backpressure support */
@@ -1322,6 +1369,13 @@ declare class VelesDB {
         filter?: FilterInput;
     }): Promise<SearchResult[]>;
     multiQuerySearch(collection: string, vectors: Array<number[] | Float32Array>, options?: MultiQuerySearchOptions): Promise<SearchResult[]>;
+    /**
+     * Pure sparse search against a named sparse index.
+     *
+     * @see {@link SparseSearchNamedOptions} for the full pure-sparse vs hybrid comparison.
+     * @see {@link VelesDB.search} for dense + sparse hybrid against a named index.
+     */
+    sparseSearchNamed(collection: string, query: SparseVector, indexName: string, options?: SparseSearchNamedOptions): Promise<SearchResult[]>;
     query(collection: string, queryString: string, params?: Record<string, unknown>, options?: QueryOptions): Promise<QueryApiResponse>;
     queryExplain(queryString: string, params?: Record<string, unknown>, options?: {
         analyze?: boolean;
@@ -1454,16 +1508,9 @@ declare class WasmBackend implements IVelesDBBackend {
     getNodePayload(c: string, id: number): Promise<NodePayloadResponse>;
     upsertNodePayload(c: string, id: number, p: Record<string, unknown>): Promise<void>;
     graphSearch(c: string, r: GraphSearchRequest): Promise<GraphSearchResponse>;
+    sparseSearchNamed(c: string, q: SparseVector, idx: string, o?: SparseSearchNamedOptions): Promise<SearchResult[]>;
 }
 
-/**
- * REST Backend for VelesDB
- *
- * Connects to VelesDB server via REST API.
- * This is the composition root that delegates to focused backend modules.
- * HTTP infrastructure lives in rest-http.ts.
- */
-
 /**
  * REST Backend
  *
@@ -1521,6 +1568,7 @@ declare class RestBackend implements IVelesDBBackend {
         id: number;
         score: number;
     }>>;
+    sparseSearchNamed(c: string, q: SparseVector, idx: string, o?: SparseSearchNamedOptions): Promise<SearchResult[]>;
     query(c: string, q: string, p?: Record<string, unknown>, o?: QueryOptions): Promise<QueryApiResponse>;
     queryExplain(q: string, p?: Record<string, unknown>, o?: {
         analyze?: boolean;
@@ -1998,4 +2046,45 @@ type VelesErrorCode = (typeof VELES_ERROR_CODES)[number];
  */
 declare function parseVelesError(code: string | null | undefined, message: string): VelesError;
 
-export { type ActualStats, type AddEdgeRequest, AgentMemoryClient, type AgentMemoryConfig, type AggregateQueryOptions, type AggregateResponse, type AggregationQueryResponse, AllocationFailedError, type AsyncIndexBuilderOptions, type BackendType, BackpressureError, type CapabilityMap, type Collection, type CollectionConfig, type CollectionConfigResponse, CollectionExistsError, CollectionNotFoundError, type CollectionSanityChecks, type CollectionSanityDiagnostics, type CollectionSanityResponse, type CollectionStatsResponse, type CollectionType, type ColumnStatsDetail, ColumnStoreError, type CompareOp, type Condition, ConfigError, ConnectionError, type CreateIndexOptions, DatabaseLockedError, type DeferredIndexerOptions, type DegreeResponse, DimensionMismatchError, type DistanceMetric, EdgeExistsError, EdgeNotFoundError, type EdgesResponse, type EpisodicEvent, EpochMismatchError, type ExplainCost, type ExplainFeatures, type ExplainPlanStep, type ExplainResponse, type Filter, type FilterInput, type FusionOptions, type FusionStrategy, type GetEdgesOptions, type GetNodeEdgesOptions, GpuError, type GraphCollectionConfig, type GraphEdge, GraphNotSupportedError, type GraphSchemaMode, type GraphSearchRequest, type GraphSearchResponse, type GraphSearchResultItem, GuardRailError, type GuardRailsConfigResponse, type GuardRailsUpdateRequest, type HnswParams, type IVelesDBBackend, IncompatibleSchemaVersionError, IndexCorruptedError, IndexError, type IndexInfo, type IndexType, InternalError, InvalidCollectionNameError, InvalidDimensionError, InvalidEdgeLabelError, InvalidQuantizerConfigError, InvalidVectorError, IoError, type JsonValue, type ListNodesResponse, type MatchQueryOptions, type MatchQueryResponse, type MatchQueryResultItem, type MultiQuerySearchOptions, type NearVectorOptions, NodeNotFoundError, type NodePayloadResponse, type NodeStats, NotFoundError, OverflowError, PointNotFoundError, type PqTrainOptions, type ProceduralPattern, type QueryApiResponse, QueryError, type QueryOptions, type QueryResponse, type QueryResult, type QueryStats, REST_CAPABILITIES, type RebuildIndexResponse, type RelDirection, type RelOptions, RestBackend, type RestPointId, SchemaValidationError, type ScrollRequest, type ScrollResponse, SearchNotSupportedError, type SearchOptions, type SearchQuality, type SearchQualityWire, type SearchResult, type SemanticEntry, SerializationError, SnapshotBuildFailedError, SparseIndexError, type SparseVector, StorageError, type StorageMode, type StreamUpsertResponse, TrainingFailedError, type TraversalResultItem, type TraversalStats, type TraverseParallelRequest, type TraverseRequest, type TraverseResponse, VELES_ERROR_CODES, ValidationError, type VectorDocument, VectorNotAllowedError, VectorRequiredError, VelesDB, type VelesDBConfig, VelesDBError, VelesError, type VelesErrorCode, VelesQLBuilder, WASM_CAPABILITIES, WasmBackend, f, isTypedFilter, normalizeFilter, parseVelesError, searchQualityToMode, velesql };
+/**
+ * Optional embedding helpers for the VelesDB TypeScript SDK.
+ *
+ * A thin {@link Embedder} interface plus an adapter for OpenAI-compatible
+ * endpoints. The adapter uses the global `fetch` API (Node ≥ 18, browsers,
+ * Deno) and has no additional runtime dependencies.
+ *
+ * @example
+ * ```typescript
+ * import { VelesDB, OpenAIEmbedder } from '@wiscale/velesdb-sdk';
+ *
+ * const embedder = new OpenAIEmbedder({ apiKey: process.env.OPENAI_API_KEY! });
+ * const db = new VelesDB({ backend: 'wasm' });
+ * await db.init();
+ * await db.createCollection('docs', { dimension: embedder.dimension ?? 1536 });
+ * const vectors = await embedder.embed(['hello world', 'vector search']);
+ * ```
+ */
+interface Embedder {
+    /** Embedding dimension, or `0` if not yet known (determined after first call). */
+    readonly dimension: number;
+    embed(texts: string[]): Promise<number[][]>;
+}
+interface OpenAIEmbedderOptions {
+    model?: string;
+    apiKey: string;
+    /** Override the base URL for Azure OpenAI, vLLM, or any compatible endpoint. */
+    baseUrl?: string;
+    /** Request a specific output dimension (requires a model that supports it). */
+    dimensions?: number;
+}
+declare class OpenAIEmbedder implements Embedder {
+    private readonly model;
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly requestedDimensions;
+    dimension: number;
+    constructor(options: OpenAIEmbedderOptions);
+    embed(texts: string[]): Promise<number[][]>;
+}
+
+export { type ActualStats, type AddEdgeRequest, AgentMemoryClient, type AgentMemoryConfig, type AggregateQueryOptions, type AggregateResponse, type AggregationQueryResponse, AllocationFailedError, type AsyncIndexBuilderOptions, type BackendType, BackpressureError, type CapabilityMap, type Collection, type CollectionConfig, type CollectionConfigResponse, CollectionExistsError, CollectionNotFoundError, type CollectionSanityChecks, type CollectionSanityDiagnostics, type CollectionSanityResponse, type CollectionStatsResponse, type CollectionType, type ColumnStatsDetail, ColumnStoreError, type CompareOp, type Condition, ConfigError, ConnectionError, type CreateIndexOptions, DatabaseLockedError, type DeferredIndexerOptions, type DegreeResponse, DimensionMismatchError, type DistanceMetric, EdgeExistsError, EdgeNotFoundError, type EdgesResponse, type Embedder, type EpisodicEvent, EpochMismatchError, type ExplainCost, type ExplainFeatures, type ExplainPlanStep, type ExplainResponse, type Filter, type FilterInput, type FusionOptions, type FusionStrategy, type GetEdgesOptions, type GetNodeEdgesOptions, GpuError, type GraphCollectionConfig, type GraphEdge, GraphNotSupportedError, type GraphSchemaMode, type GraphSearchRequest, type GraphSearchResponse, type GraphSearchResultItem, GuardRailError, type GuardRailsConfigResponse, type GuardRailsUpdateRequest, type HnswParams, type IVelesDBBackend, IncompatibleSchemaVersionError, IndexCorruptedError, IndexError, type IndexInfo, type IndexType, InternalError, InvalidCollectionNameError, InvalidDimensionError, InvalidEdgeLabelError, InvalidQuantizerConfigError, InvalidVectorError, IoError, type JsonValue, type ListNodesResponse, type MatchQueryOptions, type MatchQueryResponse, type MatchQueryResultItem, type MultiQuerySearchOptions, type NearVectorOptions, NodeNotFoundError, type NodePayloadResponse, type NodeStats, NotFoundError, OpenAIEmbedder, type OpenAIEmbedderOptions, OverflowError, PointNotFoundError, type PqTrainOptions, type ProceduralPattern, type QueryApiResponse, QueryError, type QueryOptions, type QueryResponse, type QueryResult, type QueryStats, REST_CAPABILITIES, type RebuildIndexResponse, type RelDirection, type RelOptions, RestBackend, type RestPointId, SchemaValidationError, type ScrollRequest, type ScrollResponse, SearchNotSupportedError, type SearchOptions, type SearchQuality, type SearchQualityWire, type SearchResult, type SemanticEntry, SerializationError, SnapshotBuildFailedError, SparseIndexError, type SparseSearchNamedOptions, type SparseVector, StorageError, type StorageMode, type StreamUpsertResponse, TrainingFailedError, type TraversalResultItem, type TraversalStats, type TraverseParallelRequest, type TraverseRequest, type TraverseResponse, VELES_ERROR_CODES, ValidationError, type VectorDocument, VectorNotAllowedError, VectorRequiredError, VelesDB, type VelesDBConfig, VelesDBError, VelesError, type VelesErrorCode, VelesQLBuilder, WASM_CAPABILITIES, WasmBackend, f, isTypedFilter, normalizeFilter, parseVelesError, searchQualityToMode, velesql };

package/dist/index.d.ts

@@ -376,6 +376,30 @@ declare const f: {
  * @packageDocumentation
  */
 
+/**
+ * Options for `db.sparseSearchNamed()` — **pure sparse** query against a
+ * named sparse index (issue #380).
+ *
+ * Use this when you have only a sparse vector and want to query a specific
+ * named sparse index directly. The query carries no dense component.
+ *
+ * For **dense + sparse hybrid** against a named index, use
+ * `db.search(..., { sparseVector, sparseIndexName })` instead
+ * (see {@link SearchOptions.sparseIndexName}).
+ *
+ * **Backend support:** REST only. The WASM backend has no concept of named
+ * sparse indexes; this method throws `wasmNotSupported` on WASM.
+ */
+interface SparseSearchNamedOptions {
+    /** Number of results to return (default: 10) */
+    k?: number;
+    /** Filter expression */
+    filter?: FilterInput;
+    /** Optional dense vector to combine with sparse for hybrid named search */
+    vector?: number[] | Float32Array;
+    /** Search quality preset */
+    quality?: SearchQuality;
+}
 /** Search options */
 interface SearchOptions {
     /** Number of results to return (default: 10) */
@@ -386,6 +410,18 @@ interface SearchOptions {
     includeVectors?: boolean;
     /** Optional sparse vector for hybrid sparse+dense search */
     sparseVector?: SparseVector;
+    /**
+     * Named sparse index to combine with the dense query for **hybrid** search
+     * (when the collection has multiple sparse indexes). When omitted, the
+     * default sparse index is used.
+     *
+     * For a **pure sparse** query against a named index (no dense vector),
+     * call `db.sparseSearchNamed()` instead — see {@link SparseSearchNamedOptions}.
+     *
+     * **Backend support:** REST only. The WASM backend silently ignores this
+     * field and uses the collection's single sparse index regardless.
+     */
+    sparseIndexName?: string;
     /** Search quality preset (default: 'balanced'). */
     quality?: SearchQuality;
 }
@@ -612,8 +648,8 @@ interface ColumnStatsDetail {
     name: string;
     nullCount: number;
     distinctCount: number;
-    minValue: unknown | null;
-    maxValue: unknown | null;
+    minValue: unknown;
+    maxValue: unknown;
     avgSizeBytes: number;
     histogramBuckets: number | null;
     histogramStale: boolean | null;
@@ -1152,6 +1188,17 @@ interface IVelesDBBackend {
     traverseParallel(collection: string, request: TraverseParallelRequest): Promise<TraverseResponse>;
     /** Get the in-degree and out-degree of a node */
     getNodeDegree(collection: string, nodeId: number): Promise<DegreeResponse>;
+    /**
+     * Search a named sparse index (issue #380).
+     *
+     * Sends `sparse_vectors: { [indexName]: query }` and `sparse_index: indexName`
+     * to the `/search` endpoint. When `options.vector` is provided, the request
+     * also includes a dense vector for hybrid sparse+dense search against the
+     * named index.
+     *
+     * WASM backend: not supported (throws `VelesDB-WASM-NOT-SUPPORTED`).
+     */
+    sparseSearchNamed(collection: string, query: SparseVector, indexName: string, options?: SparseSearchNamedOptions): Promise<SearchResult[]>;
     /** Train Product Quantization on a collection */
     trainPq(collection: string, options?: PqTrainOptions): Promise<string>;
     /** Stream-insert documents with backpressure support */
@@ -1322,6 +1369,13 @@ declare class VelesDB {
         filter?: FilterInput;
     }): Promise<SearchResult[]>;
     multiQuerySearch(collection: string, vectors: Array<number[] | Float32Array>, options?: MultiQuerySearchOptions): Promise<SearchResult[]>;
+    /**
+     * Pure sparse search against a named sparse index.
+     *
+     * @see {@link SparseSearchNamedOptions} for the full pure-sparse vs hybrid comparison.
+     * @see {@link VelesDB.search} for dense + sparse hybrid against a named index.
+     */
+    sparseSearchNamed(collection: string, query: SparseVector, indexName: string, options?: SparseSearchNamedOptions): Promise<SearchResult[]>;
     query(collection: string, queryString: string, params?: Record<string, unknown>, options?: QueryOptions): Promise<QueryApiResponse>;
     queryExplain(queryString: string, params?: Record<string, unknown>, options?: {
         analyze?: boolean;
@@ -1454,16 +1508,9 @@ declare class WasmBackend implements IVelesDBBackend {
     getNodePayload(c: string, id: number): Promise<NodePayloadResponse>;
     upsertNodePayload(c: string, id: number, p: Record<string, unknown>): Promise<void>;
     graphSearch(c: string, r: GraphSearchRequest): Promise<GraphSearchResponse>;
+    sparseSearchNamed(c: string, q: SparseVector, idx: string, o?: SparseSearchNamedOptions): Promise<SearchResult[]>;
 }
 
-/**
- * REST Backend for VelesDB
- *
- * Connects to VelesDB server via REST API.
- * This is the composition root that delegates to focused backend modules.
- * HTTP infrastructure lives in rest-http.ts.
- */
-
 /**
  * REST Backend
  *
@@ -1521,6 +1568,7 @@ declare class RestBackend implements IVelesDBBackend {
         id: number;
         score: number;
     }>>;
+    sparseSearchNamed(c: string, q: SparseVector, idx: string, o?: SparseSearchNamedOptions): Promise<SearchResult[]>;
     query(c: string, q: string, p?: Record<string, unknown>, o?: QueryOptions): Promise<QueryApiResponse>;
     queryExplain(q: string, p?: Record<string, unknown>, o?: {
         analyze?: boolean;
@@ -1998,4 +2046,45 @@ type VelesErrorCode = (typeof VELES_ERROR_CODES)[number];
  */
 declare function parseVelesError(code: string | null | undefined, message: string): VelesError;
 
-export { type ActualStats, type AddEdgeRequest, AgentMemoryClient, type AgentMemoryConfig, type AggregateQueryOptions, type AggregateResponse, type AggregationQueryResponse, AllocationFailedError, type AsyncIndexBuilderOptions, type BackendType, BackpressureError, type CapabilityMap, type Collection, type CollectionConfig, type CollectionConfigResponse, CollectionExistsError, CollectionNotFoundError, type CollectionSanityChecks, type CollectionSanityDiagnostics, type CollectionSanityResponse, type CollectionStatsResponse, type CollectionType, type ColumnStatsDetail, ColumnStoreError, type CompareOp, type Condition, ConfigError, ConnectionError, type CreateIndexOptions, DatabaseLockedError, type DeferredIndexerOptions, type DegreeResponse, DimensionMismatchError, type DistanceMetric, EdgeExistsError, EdgeNotFoundError, type EdgesResponse, type EpisodicEvent, EpochMismatchError, type ExplainCost, type ExplainFeatures, type ExplainPlanStep, type ExplainResponse, type Filter, type FilterInput, type FusionOptions, type FusionStrategy, type GetEdgesOptions, type GetNodeEdgesOptions, GpuError, type GraphCollectionConfig, type GraphEdge, GraphNotSupportedError, type GraphSchemaMode, type GraphSearchRequest, type GraphSearchResponse, type GraphSearchResultItem, GuardRailError, type GuardRailsConfigResponse, type GuardRailsUpdateRequest, type HnswParams, type IVelesDBBackend, IncompatibleSchemaVersionError, IndexCorruptedError, IndexError, type IndexInfo, type IndexType, InternalError, InvalidCollectionNameError, InvalidDimensionError, InvalidEdgeLabelError, InvalidQuantizerConfigError, InvalidVectorError, IoError, type JsonValue, type ListNodesResponse, type MatchQueryOptions, type MatchQueryResponse, type MatchQueryResultItem, type MultiQuerySearchOptions, type NearVectorOptions, NodeNotFoundError, type NodePayloadResponse, type NodeStats, NotFoundError, OverflowError, PointNotFoundError, type PqTrainOptions, type ProceduralPattern, type QueryApiResponse, QueryError, type QueryOptions, type QueryResponse, type QueryResult, type QueryStats, REST_CAPABILITIES, type RebuildIndexResponse, type RelDirection, type RelOptions, RestBackend, type RestPointId, SchemaValidationError, type ScrollRequest, type ScrollResponse, SearchNotSupportedError, type SearchOptions, type SearchQuality, type SearchQualityWire, type SearchResult, type SemanticEntry, SerializationError, SnapshotBuildFailedError, SparseIndexError, type SparseVector, StorageError, type StorageMode, type StreamUpsertResponse, TrainingFailedError, type TraversalResultItem, type TraversalStats, type TraverseParallelRequest, type TraverseRequest, type TraverseResponse, VELES_ERROR_CODES, ValidationError, type VectorDocument, VectorNotAllowedError, VectorRequiredError, VelesDB, type VelesDBConfig, VelesDBError, VelesError, type VelesErrorCode, VelesQLBuilder, WASM_CAPABILITIES, WasmBackend, f, isTypedFilter, normalizeFilter, parseVelesError, searchQualityToMode, velesql };
+/**
+ * Optional embedding helpers for the VelesDB TypeScript SDK.
+ *
+ * A thin {@link Embedder} interface plus an adapter for OpenAI-compatible
+ * endpoints. The adapter uses the global `fetch` API (Node ≥ 18, browsers,
+ * Deno) and has no additional runtime dependencies.
+ *
+ * @example
+ * ```typescript
+ * import { VelesDB, OpenAIEmbedder } from '@wiscale/velesdb-sdk';
+ *
+ * const embedder = new OpenAIEmbedder({ apiKey: process.env.OPENAI_API_KEY! });
+ * const db = new VelesDB({ backend: 'wasm' });
+ * await db.init();
+ * await db.createCollection('docs', { dimension: embedder.dimension ?? 1536 });
+ * const vectors = await embedder.embed(['hello world', 'vector search']);
+ * ```
+ */
+interface Embedder {
+    /** Embedding dimension, or `0` if not yet known (determined after first call). */
+    readonly dimension: number;
+    embed(texts: string[]): Promise<number[][]>;
+}
+interface OpenAIEmbedderOptions {
+    model?: string;
+    apiKey: string;
+    /** Override the base URL for Azure OpenAI, vLLM, or any compatible endpoint. */
+    baseUrl?: string;
+    /** Request a specific output dimension (requires a model that supports it). */
+    dimensions?: number;
+}
+declare class OpenAIEmbedder implements Embedder {
+    private readonly model;
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly requestedDimensions;
+    dimension: number;
+    constructor(options: OpenAIEmbedderOptions);
+    embed(texts: string[]): Promise<number[][]>;
+}
+
+export { type ActualStats, type AddEdgeRequest, AgentMemoryClient, type AgentMemoryConfig, type AggregateQueryOptions, type AggregateResponse, type AggregationQueryResponse, AllocationFailedError, type AsyncIndexBuilderOptions, type BackendType, BackpressureError, type CapabilityMap, type Collection, type CollectionConfig, type CollectionConfigResponse, CollectionExistsError, CollectionNotFoundError, type CollectionSanityChecks, type CollectionSanityDiagnostics, type CollectionSanityResponse, type CollectionStatsResponse, type CollectionType, type ColumnStatsDetail, ColumnStoreError, type CompareOp, type Condition, ConfigError, ConnectionError, type CreateIndexOptions, DatabaseLockedError, type DeferredIndexerOptions, type DegreeResponse, DimensionMismatchError, type DistanceMetric, EdgeExistsError, EdgeNotFoundError, type EdgesResponse, type Embedder, type EpisodicEvent, EpochMismatchError, type ExplainCost, type ExplainFeatures, type ExplainPlanStep, type ExplainResponse, type Filter, type FilterInput, type FusionOptions, type FusionStrategy, type GetEdgesOptions, type GetNodeEdgesOptions, GpuError, type GraphCollectionConfig, type GraphEdge, GraphNotSupportedError, type GraphSchemaMode, type GraphSearchRequest, type GraphSearchResponse, type GraphSearchResultItem, GuardRailError, type GuardRailsConfigResponse, type GuardRailsUpdateRequest, type HnswParams, type IVelesDBBackend, IncompatibleSchemaVersionError, IndexCorruptedError, IndexError, type IndexInfo, type IndexType, InternalError, InvalidCollectionNameError, InvalidDimensionError, InvalidEdgeLabelError, InvalidQuantizerConfigError, InvalidVectorError, IoError, type JsonValue, type ListNodesResponse, type MatchQueryOptions, type MatchQueryResponse, type MatchQueryResultItem, type MultiQuerySearchOptions, type NearVectorOptions, NodeNotFoundError, type NodePayloadResponse, type NodeStats, NotFoundError, OpenAIEmbedder, type OpenAIEmbedderOptions, OverflowError, PointNotFoundError, type PqTrainOptions, type ProceduralPattern, type QueryApiResponse, QueryError, type QueryOptions, type QueryResponse, type QueryResult, type QueryStats, REST_CAPABILITIES, type RebuildIndexResponse, type RelDirection, type RelOptions, RestBackend, type RestPointId, SchemaValidationError, type ScrollRequest, type ScrollResponse, SearchNotSupportedError, type SearchOptions, type SearchQuality, type SearchQualityWire, type SearchResult, type SemanticEntry, SerializationError, SnapshotBuildFailedError, SparseIndexError, type SparseSearchNamedOptions, type SparseVector, StorageError, type StorageMode, type StreamUpsertResponse, TrainingFailedError, type TraversalResultItem, type TraversalStats, type TraverseParallelRequest, type TraverseRequest, type TraverseResponse, VELES_ERROR_CODES, ValidationError, type VectorDocument, VectorNotAllowedError, VectorRequiredError, VelesDB, type VelesDBConfig, VelesDBError, VelesError, type VelesErrorCode, VelesQLBuilder, WASM_CAPABILITIES, WasmBackend, f, isTypedFilter, normalizeFilter, parseVelesError, searchQualityToMode, velesql };

package/dist/index.js

@@ -105,6 +105,7 @@ __export(index_exports, {
   IoError: () => IoError,
   NodeNotFoundError: () => NodeNotFoundError,
   NotFoundError: () => NotFoundError,
+  OpenAIEmbedder: () => OpenAIEmbedder,
   OverflowError: () => OverflowError,
   PointNotFoundError: () => PointNotFoundError,
   QueryError: () => QueryError,
@@ -725,49 +726,49 @@ var VELES_ERROR_CODES = [
   "VELES-035",
   "VELES-036"
 ];
-var CODE_TO_CLASS = {
-  "VELES-001": CollectionExistsError,
-  "VELES-002": CollectionNotFoundError,
-  "VELES-003": PointNotFoundError,
-  "VELES-004": DimensionMismatchError,
-  "VELES-005": InvalidVectorError,
-  "VELES-006": StorageError,
-  "VELES-007": IndexError,
-  "VELES-008": IndexCorruptedError,
-  "VELES-009": ConfigError,
-  "VELES-010": QueryError,
-  "VELES-011": IoError,
-  "VELES-012": SerializationError,
-  "VELES-013": InternalError,
-  "VELES-014": VectorNotAllowedError,
-  "VELES-015": SearchNotSupportedError,
-  "VELES-016": VectorRequiredError,
-  "VELES-017": SchemaValidationError,
-  "VELES-018": GraphNotSupportedError,
-  "VELES-019": EdgeExistsError,
-  "VELES-020": EdgeNotFoundError,
-  "VELES-021": InvalidEdgeLabelError,
-  "VELES-022": NodeNotFoundError,
-  "VELES-023": OverflowError,
-  "VELES-024": ColumnStoreError,
-  "VELES-025": GpuError,
-  "VELES-026": EpochMismatchError,
-  "VELES-027": GuardRailError,
-  "VELES-028": InvalidQuantizerConfigError,
-  "VELES-029": TrainingFailedError,
-  "VELES-030": SparseIndexError,
-  "VELES-031": DatabaseLockedError,
-  "VELES-032": InvalidDimensionError,
-  "VELES-033": AllocationFailedError,
-  "VELES-034": InvalidCollectionNameError,
-  "VELES-035": SnapshotBuildFailedError,
-  "VELES-036": IncompatibleSchemaVersionError
-};
+var CODE_TO_CLASS = /* @__PURE__ */ new Map([
+  ["VELES-001", CollectionExistsError],
+  ["VELES-002", CollectionNotFoundError],
+  ["VELES-003", PointNotFoundError],
+  ["VELES-004", DimensionMismatchError],
+  ["VELES-005", InvalidVectorError],
+  ["VELES-006", StorageError],
+  ["VELES-007", IndexError],
+  ["VELES-008", IndexCorruptedError],
+  ["VELES-009", ConfigError],
+  ["VELES-010", QueryError],
+  ["VELES-011", IoError],
+  ["VELES-012", SerializationError],
+  ["VELES-013", InternalError],
+  ["VELES-014", VectorNotAllowedError],
+  ["VELES-015", SearchNotSupportedError],
+  ["VELES-016", VectorRequiredError],
+  ["VELES-017", SchemaValidationError],
+  ["VELES-018", GraphNotSupportedError],
+  ["VELES-019", EdgeExistsError],
+  ["VELES-020", EdgeNotFoundError],
+  ["VELES-021", InvalidEdgeLabelError],
+  ["VELES-022", NodeNotFoundError],
+  ["VELES-023", OverflowError],
+  ["VELES-024", ColumnStoreError],
+  ["VELES-025", GpuError],
+  ["VELES-026", EpochMismatchError],
+  ["VELES-027", GuardRailError],
+  ["VELES-028", InvalidQuantizerConfigError],
+  ["VELES-029", TrainingFailedError],
+  ["VELES-030", SparseIndexError],
+  ["VELES-031", DatabaseLockedError],
+  ["VELES-032", InvalidDimensionError],
+  ["VELES-033", AllocationFailedError],
+  ["VELES-034", InvalidCollectionNameError],
+  ["VELES-035", SnapshotBuildFailedError],
+  ["VELES-036", IncompatibleSchemaVersionError]
+]);
 function parseVelesError(code, message) {
   if (code === null || code === void 0) {
     return new VelesError(message, "VELES-UNKNOWN");
   }
-  const Cls = CODE_TO_CLASS[code];
+  const Cls = CODE_TO_CLASS.get(code);
   if (Cls !== void 0) {
     return new Cls(message);
   }
@@ -957,6 +958,9 @@ async function wasmMatchProceduralPatterns(_collection, _embedding, _k) {
 }
 
 // src/backends/wasm-wave4-stubs.ts
+function wasmSparseSearchNamed(_c, _q, _idx, _o) {
+  return Promise.resolve(wasmNotSupported("Named sparse index search"));
+}
 function wasmRebuildIndex(_c) {
   return Promise.resolve(wasmNotSupported("Index rebuild"));
 }
@@ -1404,6 +1408,10 @@ var WasmBackend = class {
     this.ensureInitialized();
     return wasmGraphSearch(c, r);
   }
+  async sparseSearchNamed(c, q, idx, o) {
+    this.ensureInitialized();
+    return wasmSparseSearchNamed(c, q, idx, o);
+  }
 };
 
 // src/backends/crud-backend.ts
@@ -1977,6 +1985,9 @@ async function search(transport, collection, query3, options) {
   if (options?.sparseVector) {
     body.sparse_vector = transport.sparseToRest(options.sparseVector);
   }
+  if (options?.sparseIndexName) {
+    body.sparse_index = options.sparseIndexName;
+  }
   const response = await transport.requestJson(
     "POST",
     `${collectionPath(collection)}/search`,
@@ -2042,12 +2053,33 @@ async function multiQuerySearch(transport, collection, vectors, options) {
       avg_weight: options?.fusionParams?.avgWeight,
       max_weight: options?.fusionParams?.maxWeight,
       hit_weight: options?.fusionParams?.hitWeight,
+      dense_weight: options?.fusionParams?.denseWeight,
+      sparse_weight: options?.fusionParams?.sparseWeight,
       filter: options?.filter
     }
   );
   throwOnError(response, `Collection '${collection}'`);
   return response.data?.results ?? [];
 }
+async function sparseSearchNamed(transport, collection, query3, indexName, options) {
+  const body = {
+    sparse_vectors: { [indexName]: transport.sparseToRest(query3) },
+    sparse_index: indexName,
+    top_k: options?.k ?? 10,
+    filter: options?.filter,
+    ...searchQualityToMode(options?.quality)
+  };
+  if (options?.vector) {
+    body.vector = Array.from(options.vector);
+  }
+  const response = await transport.requestJson(
+    "POST",
+    `${collectionPath(collection)}/search`,
+    body
+  );
+  throwOnError(response, `Collection '${collection}'`);
+  return response.data?.results ?? [];
+}
 async function searchIds(transport, collection, query3, options) {
   const queryVector = toNumberArray(query3);
   const response = await transport.requestJson(
@@ -2735,6 +2767,10 @@ var RestBackend = class {
     this.ensureInitialized();
     return searchIds(buildSearchTransport(this.httpConfig), c, q, o);
   }
+  async sparseSearchNamed(c, q, idx, o) {
+    this.ensureInitialized();
+    return sparseSearchNamed(buildSearchTransport(this.httpConfig), c, q, idx, o);
+  }
   // Query
   async query(c, q, p, o) {
     this.ensureInitialized();
@@ -2904,7 +2940,8 @@ function validateDocsBatch(docs, validateDoc) {
   }
 }
 function validateDocument(doc, config) {
-  if (doc.id === void 0 || doc.id === null) {
+  const id = doc.id;
+  if (id === void 0 || id === null) {
     throw new ValidationError("Document ID is required");
   }
   requireVector(doc.vector, "Vector");
@@ -2941,6 +2978,11 @@ function hybridSearch2(backend, collection, vector, textQuery, options) {
   requireNonEmptyString(textQuery, "Text query");
   return backend.hybridSearch(collection, vector, textQuery, options);
 }
+function sparseSearchNamed2(backend, collection, query3, indexName, options) {
+  requireNonEmptyString(collection, "Collection name");
+  requireNonEmptyString(indexName, "Index name");
+  return backend.sparseSearchNamed(collection, query3, indexName, options);
+}
 function multiQuerySearch2(backend, collection, vectors, options) {
   if (!Array.isArray(vectors) || vectors.length === 0) {
     throw new ValidationError("Vectors must be a non-empty array");
@@ -2954,11 +2996,15 @@ function trainPq2(backend, collection, options) {
   return backend.trainPq(collection, options);
 }
 function streamInsert2(backend, config, collection, docs) {
-  validateDocsBatch(docs, (doc) => validateDocument(doc, config));
+  validateDocsBatch(docs, (doc) => {
+    validateDocument(doc, config);
+  });
   return backend.streamInsert(collection, docs);
 }
 function streamUpsertPoints2(backend, config, collection, docs) {
-  validateDocsBatch(docs, (doc) => validateDocument(doc, config));
+  validateDocsBatch(docs, (doc) => {
+    validateDocument(doc, config);
+  });
   return backend.streamUpsertPoints(collection, docs);
 }
 function scroll2(backend, collection, request2) {
@@ -3091,13 +3137,14 @@ var VelesDB = class {
     this.backend = this.createBackend(config);
   }
   validateConfig(config) {
-    if (!config.backend) {
+    const backend = config.backend;
+    if (!backend) {
       throw new ValidationError("Backend type is required");
     }
-    if (config.backend !== "wasm" && config.backend !== "rest") {
-      throw new ValidationError(`Invalid backend type: ${config.backend}. Use 'wasm' or 'rest'`);
+    if (backend !== "wasm" && backend !== "rest") {
+      throw new ValidationError(`Invalid backend type: ${backend}. Use 'wasm' or 'rest'`);
     }
-    if (config.backend === "rest" && !config.url) {
+    if (backend === "rest" && !config.url) {
       throw new ValidationError("URL is required for REST backend");
     }
   }
@@ -3105,10 +3152,14 @@ var VelesDB = class {
     switch (config.backend) {
       case "wasm":
         return new WasmBackend();
-      case "rest":
+      case "rest": {
+        if (!config.url) {
+          throw new ValidationError("URL is required for REST backend");
+        }
         return new RestBackend(config.url, config.apiKey, config.timeout);
+      }
       default:
-        throw new ValidationError(`Unknown backend: ${config.backend}`);
+        throw new ValidationError(`Unknown backend: ${String(config.backend)}`);
     }
   }
   /** Initialize the client. Must be called before any other operations. */
@@ -3167,7 +3218,9 @@ var VelesDB = class {
   }
   async upsertBatch(collection, docs) {
     this.ensureInitialized();
-    validateDocsBatch(docs, (doc) => validateDocument(doc, this.config));
+    validateDocsBatch(docs, (doc) => {
+      validateDocument(doc, this.config);
+    });
     await this.backend.upsertBatch(collection, docs);
   }
   async delete(collection, id) {
@@ -3217,6 +3270,16 @@ var VelesDB = class {
     this.ensureInitialized();
     return multiQuerySearch2(this.backend, collection, vectors, options);
   }
+  /**
+   * Pure sparse search against a named sparse index.
+   *
+   * @see {@link SparseSearchNamedOptions} for the full pure-sparse vs hybrid comparison.
+   * @see {@link VelesDB.search} for dense + sparse hybrid against a named index.
+   */
+  async sparseSearchNamed(collection, query3, indexName, options) {
+    this.ensureInitialized();
+    return sparseSearchNamed2(this.backend, collection, query3, indexName, options);
+  }
   async query(collection, queryString, params, options) {
     this.ensureInitialized();
     return query2(this.backend, collection, queryString, params, options);
@@ -3673,13 +3736,14 @@ var VelesQLBuilder = class _VelesQLBuilder {
     return `*${min}..${max}`;
   }
   buildWhereClause() {
-    if (this.state.whereClauses.length === 0) return "";
-    const first = this.state.whereClauses[0];
-    if (!first) return "";
-    let result = first;
-    for (let i = 1; i < this.state.whereClauses.length; i++) {
-      const operator = this.state.whereOperators[i - 1] ?? "AND";
-      const clause = this.state.whereClauses[i];
+    let result = "";
+    for (const [idx, clause] of this.state.whereClauses.entries()) {
+      if (idx === 0) {
+        if (!clause) return "";
+        result = clause;
+        continue;
+      }
+      const operator = this.state.whereOperators[idx - 1] ?? "AND";
       if (clause) {
         result += ` ${operator} ${clause}`;
       }
@@ -3693,13 +3757,14 @@ function velesql() {
 
 // src/filter.ts
 function isTypedFilter(input) {
-  if (typeof input !== "object" || input === null) {
+  const value = input;
+  if (typeof value !== "object" || value === null) {
     return false;
   }
-  if (!("condition" in input)) {
+  if (!("condition" in value)) {
     return false;
   }
-  const cond = input.condition;
+  const cond = value.condition;
   return typeof cond === "object" && cond !== null;
 }
 function normalizeFilter(input) {
@@ -3834,6 +3899,47 @@ var f = {
     return { condition: { type: "not", condition: filter.condition } };
   }
 };
+
+// src/embed.ts
+var OpenAIEmbedder = class {
+  constructor(options) {
+    this.model = options.model ?? "text-embedding-3-small";
+    this.apiKey = options.apiKey;
+    this.baseUrl = options.baseUrl?.replace(/\/$/, "") ?? "https://api.openai.com/v1";
+    this.requestedDimensions = options.dimensions;
+    this.dimension = options.dimensions ?? 0;
+  }
+  async embed(texts) {
+    if (texts.length === 0) return [];
+    const body = { model: this.model, input: texts };
+    if (this.requestedDimensions !== void 0) {
+      body["dimensions"] = this.requestedDimensions;
+    }
+    const response = await fetch(`${this.baseUrl}/embeddings`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.apiKey}`
+      },
+      body: JSON.stringify(body)
+    });
+    if (!response.ok) {
+      const text = await response.text().catch(() => "");
+      throw new Error(
+        `OpenAI embeddings request failed: ${response.status} ${response.statusText} \u2014 ${text.slice(0, 500)}`
+      );
+    }
+    const json = await response.json();
+    const vectors = json.data.map((item) => item.embedding);
+    if (this.dimension === 0) {
+      for (const vec of vectors) {
+        this.dimension = vec.length;
+        break;
+      }
+    }
+    return vectors;
+  }
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AgentMemoryClient,
@@ -3864,6 +3970,7 @@ var f = {
   IoError,
   NodeNotFoundError,
   NotFoundError,
+  OpenAIEmbedder,
   OverflowError,
   PointNotFoundError,
   QueryError,

package/dist/index.mjs

@@ -587,49 +587,49 @@ var VELES_ERROR_CODES = [
   "VELES-035",
   "VELES-036"
 ];
-var CODE_TO_CLASS = {
-  "VELES-001": CollectionExistsError,
-  "VELES-002": CollectionNotFoundError,
-  "VELES-003": PointNotFoundError,
-  "VELES-004": DimensionMismatchError,
-  "VELES-005": InvalidVectorError,
-  "VELES-006": StorageError,
-  "VELES-007": IndexError,
-  "VELES-008": IndexCorruptedError,
-  "VELES-009": ConfigError,
-  "VELES-010": QueryError,
-  "VELES-011": IoError,
-  "VELES-012": SerializationError,
-  "VELES-013": InternalError,
-  "VELES-014": VectorNotAllowedError,
-  "VELES-015": SearchNotSupportedError,
-  "VELES-016": VectorRequiredError,
-  "VELES-017": SchemaValidationError,
-  "VELES-018": GraphNotSupportedError,
-  "VELES-019": EdgeExistsError,
-  "VELES-020": EdgeNotFoundError,
-  "VELES-021": InvalidEdgeLabelError,
-  "VELES-022": NodeNotFoundError,
-  "VELES-023": OverflowError,
-  "VELES-024": ColumnStoreError,
-  "VELES-025": GpuError,
-  "VELES-026": EpochMismatchError,
-  "VELES-027": GuardRailError,
-  "VELES-028": InvalidQuantizerConfigError,
-  "VELES-029": TrainingFailedError,
-  "VELES-030": SparseIndexError,
-  "VELES-031": DatabaseLockedError,
-  "VELES-032": InvalidDimensionError,
-  "VELES-033": AllocationFailedError,
-  "VELES-034": InvalidCollectionNameError,
-  "VELES-035": SnapshotBuildFailedError,
-  "VELES-036": IncompatibleSchemaVersionError
-};
+var CODE_TO_CLASS = /* @__PURE__ */ new Map([
+  ["VELES-001", CollectionExistsError],
+  ["VELES-002", CollectionNotFoundError],
+  ["VELES-003", PointNotFoundError],
+  ["VELES-004", DimensionMismatchError],
+  ["VELES-005", InvalidVectorError],
+  ["VELES-006", StorageError],
+  ["VELES-007", IndexError],
+  ["VELES-008", IndexCorruptedError],
+  ["VELES-009", ConfigError],
+  ["VELES-010", QueryError],
+  ["VELES-011", IoError],
+  ["VELES-012", SerializationError],
+  ["VELES-013", InternalError],
+  ["VELES-014", VectorNotAllowedError],
+  ["VELES-015", SearchNotSupportedError],
+  ["VELES-016", VectorRequiredError],
+  ["VELES-017", SchemaValidationError],
+  ["VELES-018", GraphNotSupportedError],
+  ["VELES-019", EdgeExistsError],
+  ["VELES-020", EdgeNotFoundError],
+  ["VELES-021", InvalidEdgeLabelError],
+  ["VELES-022", NodeNotFoundError],
+  ["VELES-023", OverflowError],
+  ["VELES-024", ColumnStoreError],
+  ["VELES-025", GpuError],
+  ["VELES-026", EpochMismatchError],
+  ["VELES-027", GuardRailError],
+  ["VELES-028", InvalidQuantizerConfigError],
+  ["VELES-029", TrainingFailedError],
+  ["VELES-030", SparseIndexError],
+  ["VELES-031", DatabaseLockedError],
+  ["VELES-032", InvalidDimensionError],
+  ["VELES-033", AllocationFailedError],
+  ["VELES-034", InvalidCollectionNameError],
+  ["VELES-035", SnapshotBuildFailedError],
+  ["VELES-036", IncompatibleSchemaVersionError]
+]);
 function parseVelesError(code, message) {
   if (code === null || code === void 0) {
     return new VelesError(message, "VELES-UNKNOWN");
   }
-  const Cls = CODE_TO_CLASS[code];
+  const Cls = CODE_TO_CLASS.get(code);
   if (Cls !== void 0) {
     return new Cls(message);
   }
@@ -819,6 +819,9 @@ async function wasmMatchProceduralPatterns(_collection, _embedding, _k) {
 }
 
 // src/backends/wasm-wave4-stubs.ts
+function wasmSparseSearchNamed(_c, _q, _idx, _o) {
+  return Promise.resolve(wasmNotSupported("Named sparse index search"));
+}
 function wasmRebuildIndex(_c) {
   return Promise.resolve(wasmNotSupported("Index rebuild"));
 }
@@ -1266,6 +1269,10 @@ var WasmBackend = class {
     this.ensureInitialized();
     return wasmGraphSearch(c, r);
   }
+  async sparseSearchNamed(c, q, idx, o) {
+    this.ensureInitialized();
+    return wasmSparseSearchNamed(c, q, idx, o);
+  }
 };
 
 // src/backends/crud-backend.ts
@@ -1839,6 +1846,9 @@ async function search(transport, collection, query3, options) {
   if (options?.sparseVector) {
     body.sparse_vector = transport.sparseToRest(options.sparseVector);
   }
+  if (options?.sparseIndexName) {
+    body.sparse_index = options.sparseIndexName;
+  }
   const response = await transport.requestJson(
     "POST",
     `${collectionPath(collection)}/search`,
@@ -1904,12 +1914,33 @@ async function multiQuerySearch(transport, collection, vectors, options) {
       avg_weight: options?.fusionParams?.avgWeight,
       max_weight: options?.fusionParams?.maxWeight,
       hit_weight: options?.fusionParams?.hitWeight,
+      dense_weight: options?.fusionParams?.denseWeight,
+      sparse_weight: options?.fusionParams?.sparseWeight,
       filter: options?.filter
     }
   );
   throwOnError(response, `Collection '${collection}'`);
   return response.data?.results ?? [];
 }
+async function sparseSearchNamed(transport, collection, query3, indexName, options) {
+  const body = {
+    sparse_vectors: { [indexName]: transport.sparseToRest(query3) },
+    sparse_index: indexName,
+    top_k: options?.k ?? 10,
+    filter: options?.filter,
+    ...searchQualityToMode(options?.quality)
+  };
+  if (options?.vector) {
+    body.vector = Array.from(options.vector);
+  }
+  const response = await transport.requestJson(
+    "POST",
+    `${collectionPath(collection)}/search`,
+    body
+  );
+  throwOnError(response, `Collection '${collection}'`);
+  return response.data?.results ?? [];
+}
 async function searchIds(transport, collection, query3, options) {
   const queryVector = toNumberArray(query3);
   const response = await transport.requestJson(
@@ -2597,6 +2628,10 @@ var RestBackend = class {
     this.ensureInitialized();
     return searchIds(buildSearchTransport(this.httpConfig), c, q, o);
   }
+  async sparseSearchNamed(c, q, idx, o) {
+    this.ensureInitialized();
+    return sparseSearchNamed(buildSearchTransport(this.httpConfig), c, q, idx, o);
+  }
   // Query
   async query(c, q, p, o) {
     this.ensureInitialized();
@@ -2766,7 +2801,8 @@ function validateDocsBatch(docs, validateDoc) {
   }
 }
 function validateDocument(doc, config) {
-  if (doc.id === void 0 || doc.id === null) {
+  const id = doc.id;
+  if (id === void 0 || id === null) {
     throw new ValidationError("Document ID is required");
   }
   requireVector(doc.vector, "Vector");
@@ -2803,6 +2839,11 @@ function hybridSearch2(backend, collection, vector, textQuery, options) {
   requireNonEmptyString(textQuery, "Text query");
   return backend.hybridSearch(collection, vector, textQuery, options);
 }
+function sparseSearchNamed2(backend, collection, query3, indexName, options) {
+  requireNonEmptyString(collection, "Collection name");
+  requireNonEmptyString(indexName, "Index name");
+  return backend.sparseSearchNamed(collection, query3, indexName, options);
+}
 function multiQuerySearch2(backend, collection, vectors, options) {
   if (!Array.isArray(vectors) || vectors.length === 0) {
     throw new ValidationError("Vectors must be a non-empty array");
@@ -2816,11 +2857,15 @@ function trainPq2(backend, collection, options) {
   return backend.trainPq(collection, options);
 }
 function streamInsert2(backend, config, collection, docs) {
-  validateDocsBatch(docs, (doc) => validateDocument(doc, config));
+  validateDocsBatch(docs, (doc) => {
+    validateDocument(doc, config);
+  });
   return backend.streamInsert(collection, docs);
 }
 function streamUpsertPoints2(backend, config, collection, docs) {
-  validateDocsBatch(docs, (doc) => validateDocument(doc, config));
+  validateDocsBatch(docs, (doc) => {
+    validateDocument(doc, config);
+  });
   return backend.streamUpsertPoints(collection, docs);
 }
 function scroll2(backend, collection, request2) {
@@ -2953,13 +2998,14 @@ var VelesDB = class {
     this.backend = this.createBackend(config);
   }
   validateConfig(config) {
-    if (!config.backend) {
+    const backend = config.backend;
+    if (!backend) {
       throw new ValidationError("Backend type is required");
     }
-    if (config.backend !== "wasm" && config.backend !== "rest") {
-      throw new ValidationError(`Invalid backend type: ${config.backend}. Use 'wasm' or 'rest'`);
+    if (backend !== "wasm" && backend !== "rest") {
+      throw new ValidationError(`Invalid backend type: ${backend}. Use 'wasm' or 'rest'`);
     }
-    if (config.backend === "rest" && !config.url) {
+    if (backend === "rest" && !config.url) {
       throw new ValidationError("URL is required for REST backend");
     }
   }
@@ -2967,10 +3013,14 @@ var VelesDB = class {
     switch (config.backend) {
       case "wasm":
         return new WasmBackend();
-      case "rest":
+      case "rest": {
+        if (!config.url) {
+          throw new ValidationError("URL is required for REST backend");
+        }
         return new RestBackend(config.url, config.apiKey, config.timeout);
+      }
       default:
-        throw new ValidationError(`Unknown backend: ${config.backend}`);
+        throw new ValidationError(`Unknown backend: ${String(config.backend)}`);
     }
   }
   /** Initialize the client. Must be called before any other operations. */
@@ -3029,7 +3079,9 @@ var VelesDB = class {
   }
   async upsertBatch(collection, docs) {
     this.ensureInitialized();
-    validateDocsBatch(docs, (doc) => validateDocument(doc, this.config));
+    validateDocsBatch(docs, (doc) => {
+      validateDocument(doc, this.config);
+    });
     await this.backend.upsertBatch(collection, docs);
   }
   async delete(collection, id) {
@@ -3079,6 +3131,16 @@ var VelesDB = class {
     this.ensureInitialized();
     return multiQuerySearch2(this.backend, collection, vectors, options);
   }
+  /**
+   * Pure sparse search against a named sparse index.
+   *
+   * @see {@link SparseSearchNamedOptions} for the full pure-sparse vs hybrid comparison.
+   * @see {@link VelesDB.search} for dense + sparse hybrid against a named index.
+   */
+  async sparseSearchNamed(collection, query3, indexName, options) {
+    this.ensureInitialized();
+    return sparseSearchNamed2(this.backend, collection, query3, indexName, options);
+  }
   async query(collection, queryString, params, options) {
     this.ensureInitialized();
     return query2(this.backend, collection, queryString, params, options);
@@ -3535,13 +3597,14 @@ var VelesQLBuilder = class _VelesQLBuilder {
     return `*${min}..${max}`;
   }
   buildWhereClause() {
-    if (this.state.whereClauses.length === 0) return "";
-    const first = this.state.whereClauses[0];
-    if (!first) return "";
-    let result = first;
-    for (let i = 1; i < this.state.whereClauses.length; i++) {
-      const operator = this.state.whereOperators[i - 1] ?? "AND";
-      const clause = this.state.whereClauses[i];
+    let result = "";
+    for (const [idx, clause] of this.state.whereClauses.entries()) {
+      if (idx === 0) {
+        if (!clause) return "";
+        result = clause;
+        continue;
+      }
+      const operator = this.state.whereOperators[idx - 1] ?? "AND";
       if (clause) {
         result += ` ${operator} ${clause}`;
       }
@@ -3555,13 +3618,14 @@ function velesql() {
 
 // src/filter.ts
 function isTypedFilter(input) {
-  if (typeof input !== "object" || input === null) {
+  const value = input;
+  if (typeof value !== "object" || value === null) {
     return false;
   }
-  if (!("condition" in input)) {
+  if (!("condition" in value)) {
     return false;
   }
-  const cond = input.condition;
+  const cond = value.condition;
   return typeof cond === "object" && cond !== null;
 }
 function normalizeFilter(input) {
@@ -3696,6 +3760,47 @@ var f = {
     return { condition: { type: "not", condition: filter.condition } };
   }
 };
+
+// src/embed.ts
+var OpenAIEmbedder = class {
+  constructor(options) {
+    this.model = options.model ?? "text-embedding-3-small";
+    this.apiKey = options.apiKey;
+    this.baseUrl = options.baseUrl?.replace(/\/$/, "") ?? "https://api.openai.com/v1";
+    this.requestedDimensions = options.dimensions;
+    this.dimension = options.dimensions ?? 0;
+  }
+  async embed(texts) {
+    if (texts.length === 0) return [];
+    const body = { model: this.model, input: texts };
+    if (this.requestedDimensions !== void 0) {
+      body["dimensions"] = this.requestedDimensions;
+    }
+    const response = await fetch(`${this.baseUrl}/embeddings`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.apiKey}`
+      },
+      body: JSON.stringify(body)
+    });
+    if (!response.ok) {
+      const text = await response.text().catch(() => "");
+      throw new Error(
+        `OpenAI embeddings request failed: ${response.status} ${response.statusText} \u2014 ${text.slice(0, 500)}`
+      );
+    }
+    const json = await response.json();
+    const vectors = json.data.map((item) => item.embedding);
+    if (this.dimension === 0) {
+      for (const vec of vectors) {
+        this.dimension = vec.length;
+        break;
+      }
+    }
+    return vectors;
+  }
+};
 export {
   AgentMemoryClient,
   AllocationFailedError,
@@ -3725,6 +3830,7 @@ export {
   IoError,
   NodeNotFoundError,
   NotFoundError,
+  OpenAIEmbedder,
   OverflowError,
   PointNotFoundError,
   QueryError,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wiscale/velesdb-sdk",
-  "version": "1.14.4",
+  "version": "1.17.0",
   "description": "VelesDB TypeScript SDK: The Local Vector Database for AI & RAG. Microsecond semantic search in Browser & Node.js.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -22,8 +22,8 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
-    "lint": "eslint src --ext .ts",
-    "lint:fix": "eslint src --ext .ts --fix",
+    "lint": "eslint src",
+    "lint:fix": "eslint src --fix",
     "format": "prettier --write src",
     "typecheck": "tsc --noEmit",
     "prepublishOnly": "npm run build"
@@ -54,15 +54,17 @@
     "url": "https://github.com/cyberlife-coder/VelesDB/issues"
   },
   "devDependencies": {
+    "@eslint/js": "^10.0.1",
     "@types/node": "^25.6.0",
-    "@typescript-eslint/eslint-plugin": "^6.0.0",
-    "@typescript-eslint/parser": "^6.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.0.0",
+    "@typescript-eslint/parser": "^8.0.0",
     "@vitest/coverage-v8": "^4.0.16",
-    "eslint": "^8.0.0",
-    "eslint-config-prettier": "^9.0.0",
+    "eslint": "^10.4.0",
+    "eslint-config-prettier": "^10.1.8",
     "prettier": "^3.0.0",
     "tsup": "^8.0.0",
-    "typescript": "^5.3.0",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.0.0",
     "vitest": "^4.0.16"
   },
   "dependencies": {