@wiscale/velesdb-sdk 1.15.0 → 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.15.0** | 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)
 ```
@@ -538,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)"
 );
 ```
 
@@ -828,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

@@ -648,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;
@@ -2046,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 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 };
+/**
+ * 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

@@ -648,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;
@@ -2046,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 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 };
+/**
+ * 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);
   }
@@ -2939,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");
@@ -2994,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) {
@@ -3131,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");
     }
   }
@@ -3145,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. */
@@ -3207,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) {
@@ -3723,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}`;
       }
@@ -3743,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) {
@@ -3884,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,
@@ -3914,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);
   }
@@ -2801,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");
@@ -2856,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) {
@@ -2993,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");
     }
   }
@@ -3007,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. */
@@ -3069,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) {
@@ -3585,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}`;
       }
@@ -3605,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) {
@@ -3746,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,
@@ -3775,6 +3830,7 @@ export {
   IoError,
   NodeNotFoundError,
   NotFoundError,
+  OpenAIEmbedder,
   OverflowError,
   PointNotFoundError,
   QueryError,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wiscale/velesdb-sdk",
-  "version": "1.15.0",
+  "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",
@@ -54,12 +54,12 @@
     "url": "https://github.com/cyberlife-coder/VelesDB/issues"
   },
   "devDependencies": {
-    "@eslint/js": "^9.0.0",
+    "@eslint/js": "^10.0.1",
     "@types/node": "^25.6.0",
     "@typescript-eslint/eslint-plugin": "^8.0.0",
     "@typescript-eslint/parser": "^8.0.0",
     "@vitest/coverage-v8": "^4.0.16",
-    "eslint": "^10.3.0",
+    "eslint": "^10.4.0",
     "eslint-config-prettier": "^10.1.8",
     "prettier": "^3.0.0",
     "tsup": "^8.0.0",