@wiscale/velesdb-wasm 1.5.1 → 1.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 Wiscale France
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,7 +1,7 @@
 # VelesDB WASM
 
 [![npm](https://img.shields.io/npm/v/@wiscale/velesdb-wasm)](https://www.npmjs.com/package/@wiscale/velesdb-wasm)
-[![License](https://img.shields.io/badge/license-ELv2-blue)](https://github.com/cyberlife-coder/VelesDB/blob/main/LICENSE)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 
 WebAssembly build of [VelesDB](https://github.com/cyberlife-coder/VelesDB) - vector search in the browser.
 
@@ -11,6 +11,10 @@ WebAssembly build of [VelesDB](https://github.com/cyberlife-coder/VelesDB) - vec
 - **SIMD optimized** - Uses WASM SIMD128 for fast distance calculations
 - **Multiple metrics** - Cosine, Euclidean, Dot Product, Hamming, Jaccard
 - **Memory optimization** - SQ8 (4x) and Binary (32x) quantization
+- **Knowledge Graph** - In-memory graph store with BFS/DFS traversal
+- **Agent Memory** - Semantic memory for AI agents (store/query knowledge facts)
+- **VelesQL parser** - Parse and validate VelesQL queries client-side
+- **Sparse search** - Inverted index with RRF hybrid fusion
 - **Lightweight** - Minimal bundle size
 
 ## Installation
@@ -89,18 +93,26 @@ class VectorStore {
 
   // Methods
   insert(id: bigint, vector: Float32Array): void;
-  insert_with_payload(id: bigint, vector: Float32Array, payload: object): void;  insert_batch(batch: Array<[bigint, number[]]>): void;  // Bulk insert
+  insert_with_payload(id: bigint, vector: Float32Array, payload: object): void;
+  insert_batch(batch: Array<[bigint, number[]]>): void;  // Bulk insert
   search(query: Float32Array, k: number): Array<[bigint, number]>;
-  search_with_filter(query: Float32Array, k: number, filter: object): Array<{id, score, payload}>;  text_search(query: string, k: number, field?: string): Array<{id, score, payload}>;  get(id: bigint): {id, vector, payload} | null;  remove(id: bigint): boolean;
+  search_with_filter(query: Float32Array, k: number, filter: object): Array<{id, score, payload}>;
+  text_search(query: string, k: number, field?: string): Array<{id, score, payload}>;
+  get(id: bigint): {id, vector, payload} | null;
+  remove(id: bigint): boolean;
   clear(): void;
   reserve(additional: number): void;  // Pre-allocate memory
   memory_usage(): number;  // Accurate for each storage mode
   
   //
   multi_query_search(vectors: Float32Array, num_vectors: number, k: number, strategy?: string, rrf_k?: number): Array<[bigint, number]>;
-  hybrid_search(vector: Float32Array, text_query: string, k: number, vector_weight?: number, field?: string): Array<{id, score, payload}>;
+  hybrid_search(vector: Float32Array, text_query: string, k: number, vector_weight?: number): Array<{id, score, payload}>;
   batch_search(vectors: Float32Array, num_vectors: number, k: number): Array<Array<[bigint, number]>>;
   
+  // Sparse search (inverted index)
+  sparse_insert(doc_id: bigint, indices: Uint32Array, values: Float32Array): void;
+  sparse_search(indices: Uint32Array, values: Float32Array, k: number): Array<{doc_id, score}>;
+
   // Metadata-only store
   static new_metadata_only(): VectorStore;
   readonly is_metadata_only: boolean;
@@ -256,38 +268,114 @@ The WASM build is optimized for client-side use cases but has some limitations c
 | Full-text search (BM25) | ✅ | ✅ |
 | Multi-query fusion (MQG) | ✅ | ✅ |
 | Batch search | ✅ | ✅ |
-| Full VelesQL queries | ❌ | ✅ |
-| Knowledge Graph operations | ❌ | ✅ |
+| Sparse search | ✅ | ✅ |
+| Knowledge Graph (nodes, edges, traversal) | ✅ | ✅ |
+| Agent Memory (SemanticMemory) | ✅ | ✅ |
+| VelesQL parsing & validation | ✅ | ✅ |
+| VelesQL query execution | ❌ | ✅ |
 | JOIN operations | ❌ | ✅ |
 | Aggregations (GROUP BY) | ❌ | ✅ |
 | Persistence | IndexedDB | Disk (mmap) |
 | Max vectors | ~100K (browser RAM) | Millions |
 
-### Unsupported Operations
+### VelesQL (Parser Only)
 
-When you try to use unsupported features, you'll get clear error messages:
+VelesQL parsing and validation are available in WASM. You can parse queries, inspect their AST, and validate syntax client-side. However, query **execution** (running queries against data) requires the REST server.
 
 ```javascript
-// ❌ VelesQL string queries not supported in WASM
-// Use the native API instead:
+import { VelesQL } from '@wiscale/velesdb-wasm';
+
+// Parse and inspect a query
+const parsed = VelesQL.parse("SELECT * FROM docs WHERE vector NEAR $v LIMIT 10");
+console.log(parsed.tableName);       // "docs"
+console.log(parsed.hasVectorSearch); // true
+console.log(parsed.limit);          // 10
+
+// Validate syntax
+VelesQL.isValid("SELECT * FROM docs");        // true
+VelesQL.isValid("SELEC * FROM docs");         // false
+
+// Parse MATCH (graph) queries
+const match = VelesQL.parse("MATCH (p:Person)-[:KNOWS]->(f:Person) RETURN f.name");
+console.log(match.isMatch);              // true
+console.log(match.matchNodeCount);       // 2
+console.log(match.matchRelationshipCount); // 1
+```
 
-// Instead of: store.query("SELECT * FROM docs WHERE vector NEAR $v")
-// Use:
-const results = store.search(queryVector, 10);
+### Knowledge Graph (GraphStore)
 
-// Instead of: store.query("SELECT * FROM docs WHERE category = 'tech'")
-// Use:
-const results = store.search_with_filter(queryVector, 10, {
-  condition: { type: "eq", field: "category", value: "tech" }
-});
+Build and traverse in-memory knowledge graphs entirely in the browser:
+
+```javascript
+import { GraphStore, GraphNode, GraphEdge } from '@wiscale/velesdb-wasm';
+
+const graph = new GraphStore();
+
+// Create nodes
+const alice = new GraphNode(1n, "Person");
+alice.set_string_property("name", "Alice");
+const bob = new GraphNode(2n, "Person");
+bob.set_string_property("name", "Bob");
+
+graph.add_node(alice);
+graph.add_node(bob);
+
+// Create edges
+const edge = new GraphEdge(1n, 1n, 2n, "KNOWS");
+graph.add_edge(edge);
+
+// Traverse
+const neighbors = graph.get_neighbors(1n);   // [2n]
+const outgoing = graph.get_outgoing(1n);      // [GraphEdge]
+const bfsResults = graph.bfs_traverse(1n, 3, 100); // BFS up to depth 3
+```
+
+### Agent Memory (SemanticMemory)
+
+Store and retrieve knowledge facts by semantic similarity for AI agent workloads:
+
+```javascript
+import { SemanticMemory } from '@wiscale/velesdb-wasm';
+
+const memory = new SemanticMemory(384);
+
+// Store knowledge with embedding vectors
+memory.store(1n, "Paris is the capital of France", embedding1);
+memory.store(2n, "Berlin is the capital of Germany", embedding2);
+
+// Query by similarity
+const results = memory.query(queryEmbedding, 5);
+// [{id, score, content}, ...]
+
+console.log(memory.len);       // 2
+console.log(memory.dimension); // 384
+```
+
+### Sparse Search (SparseIndex)
+
+Inverted-index search with sparse vectors and RRF hybrid fusion:
+
+```javascript
+import { SparseIndex, hybrid_search_fuse } from '@wiscale/velesdb-wasm';
+
+const index = new SparseIndex();
+
+// Insert sparse vectors (term indices + weights)
+index.insert(1n, new Uint32Array([10, 20, 30]), new Float32Array([1.0, 0.5, 0.3]));
+index.insert(2n, new Uint32Array([10, 40]),     new Float32Array([0.8, 1.2]));
+
+// Search
+const results = index.search(new Uint32Array([10, 20]), new Float32Array([1.0, 1.0]), 5);
+
+// Fuse dense + sparse results with RRF
+const fused = hybrid_search_fuse(denseResults, sparseResults, 60, 10);
 ```
 
 ### When to Use REST Backend
 
 Consider using the [REST server](https://github.com/cyberlife-coder/VelesDB) if you need:
 
-- **Full VelesQL support** - Complex SQL-like queries with JOINs and aggregations
-- **Knowledge Graph** - Entity relationships and graph traversal
+- **VelesQL query execution** - Running queries against data (JOINs, aggregations, server-side filtering)
 - **Large datasets** - More than 100K vectors
 - **Server-side processing** - Centralized vector database
 
@@ -342,6 +430,6 @@ Typical latencies on modern browsers:
 
 ## License
 
-Elastic License 2.0 (ELv2)
+MIT License (bindings). The core engine (`velesdb-core` and `velesdb-server`) is under VelesDB Core License 1.0.
 
-See [LICENSE](https://github.com/cyberlife-coder/VelesDB/blob/main/LICENSE) for details.
+See [LICENSE](./LICENSE) for WASM bindings license, [root LICENSE](https://github.com/cyberlife-coder/VelesDB/blob/main/LICENSE) for core engine.

package/package.json

@@ -5,8 +5,8 @@
     "Julien Lange <contact@wiscale.fr>"
   ],
   "description": "VelesDB for WebAssembly - Vector search in the browser",
-  "version": "1.5.1",
-  "license": "SEE LICENSE IN ../../LICENSE",
+  "version": "1.6.0",
+  "license": "MIT",
   "repository": {
     "type": "git",
     "url": "https://github.com/cyberlife-coder/velesdb"

package/velesdb_wasm.d.ts

@@ -531,7 +531,9 @@ export enum StorageMode {
      */
     Binary = 2,
     /**
-     * Product Quantization (currently mapped to SQ8 path in WASM runtime)
+     * Product Quantization — **WASM limitation**: PQ requires `rayon`/`persistence`
+     * which are unavailable in WASM. This variant uses the SQ8 codepath as a
+     * fallback. For true PQ, use the native `velesdb-core` crate.
      */
     ProductQuantization = 3,
 }
@@ -616,6 +618,17 @@ export class VectorStore {
     get(id: bigint): any;
     /**
      * Hybrid search (vector + text). `vector_weight` 0-1 (default 0.5).
+     *
+     * For `Full` storage mode, this computes per-vector distance and text
+     * matching in a single pass. For quantized modes (`SQ8`, `Binary`,
+     * `ProductQuantization`), a decomposed approach is used: vector scores
+     * are obtained via the quantization-aware `compute_scores` path, text
+     * matches are evaluated independently on payloads, and the two result
+     * sets are fused with the requested weight. Quantized vector scores are
+     * approximate, so recall may differ slightly from `Full` mode.
+     *
+     * Returns `[{id, score, payload}, ...]` sorted by combined score
+     * descending, truncated to `k` results.
      */
     hybrid_search(query_vector: Float32Array, text_query: string, k: number, vector_weight?: number | null): any;
     /**
@@ -953,21 +966,21 @@ export interface InitOutput {
     readonly vectorstore_with_capacity: (a: number, b: number, c: number, d: number, e: number) => void;
     readonly velesql_isValid: (a: number, b: number) => number;
     readonly velesql_parse: (a: number, b: number, c: number) => void;
-    readonly __wbg_set_traversalprogress_is_complete: (a: number, b: number) => void;
     readonly __wbg_set_traversalprogress_current_depth: (a: number, b: number) => void;
     readonly __wbg_set_traversalprogress_estimated_total: (a: number, b: number) => void;
     readonly __wbg_set_traversalprogress_visited_count: (a: number, b: number) => void;
+    readonly __wbg_set_traversalprogress_is_complete: (a: number, b: number) => void;
     readonly __wbg_get_traversalprogress_is_complete: (a: number) => number;
     readonly __wbg_get_traversalprogress_current_depth: (a: number) => number;
     readonly __wbg_get_traversalprogress_estimated_total: (a: number) => number;
     readonly __wbg_get_traversalprogress_visited_count: (a: number) => number;
     readonly graphnode_id: (a: number) => bigint;
     readonly __wbg_traversalprogress_free: (a: number, b: number) => void;
-    readonly __wasm_bindgen_func_elem_1295: (a: number, b: number) => void;
-    readonly __wasm_bindgen_func_elem_284: (a: number, b: number) => void;
-    readonly __wasm_bindgen_func_elem_1296: (a: number, b: number, c: number, d: number) => void;
-    readonly __wasm_bindgen_func_elem_1327: (a: number, b: number, c: number, d: number) => void;
-    readonly __wasm_bindgen_func_elem_285: (a: number, b: number, c: number) => void;
+    readonly __wasm_bindgen_func_elem_1318: (a: number, b: number) => void;
+    readonly __wasm_bindgen_func_elem_289: (a: number, b: number) => void;
+    readonly __wasm_bindgen_func_elem_1319: (a: number, b: number, c: number, d: number) => void;
+    readonly __wasm_bindgen_func_elem_1364: (a: number, b: number, c: number, d: number) => void;
+    readonly __wasm_bindgen_func_elem_290: (a: number, b: number, c: number) => void;
     readonly __wbindgen_export: (a: number, b: number) => number;
     readonly __wbindgen_export2: (a: number, b: number, c: number, d: number) => number;
     readonly __wbindgen_export3: (a: number) => void;

package/velesdb_wasm.js

@@ -1366,7 +1366,9 @@ export const StorageMode = Object.freeze({
      */
     Binary: 2, "2": "Binary",
     /**
-     * Product Quantization (currently mapped to SQ8 path in WASM runtime)
+     * Product Quantization — **WASM limitation**: PQ requires `rayon`/`persistence`
+     * which are unavailable in WASM. This variant uses the SQ8 codepath as a
+     * fallback. For true PQ, use the native `velesdb-core` crate.
      */
     ProductQuantization: 3, "3": "ProductQuantization",
 });
@@ -1628,6 +1630,17 @@ export class VectorStore {
     }
     /**
      * Hybrid search (vector + text). `vector_weight` 0-1 (default 0.5).
+     *
+     * For `Full` storage mode, this computes per-vector distance and text
+     * matching in a single pass. For quantized modes (`SQ8`, `Binary`,
+     * `ProductQuantization`), a decomposed approach is used: vector scores
+     * are obtained via the quantization-aware `compute_scores` path, text
+     * matches are evaluated independently on payloads, and the two result
+     * sets are fused with the requested weight. Quantized vector scores are
+     * approximate, so recall may differ slightly from `Full` mode.
+     *
+     * Returns `[{id, score, payload}, ...]` sorted by combined score
+     * descending, truncated to `k` results.
      * @param {Float32Array} query_vector
      * @param {string} text_query
      * @param {number} k
@@ -2512,7 +2525,7 @@ function __wbg_get_imports() {
                     const a = state0.a;
                     state0.a = 0;
                     try {
-                        return __wasm_bindgen_func_elem_1327(a, state0.b, arg0, arg1);
+                        return __wasm_bindgen_func_elem_1364(a, state0.b, arg0, arg1);
                     } finally {
                         state0.a = a;
                     }
@@ -2546,7 +2559,7 @@ function __wbg_get_imports() {
                     const a = state0.a;
                     state0.a = 0;
                     try {
-                        return __wasm_bindgen_func_elem_1327(a, state0.b, arg0, arg1);
+                        return __wasm_bindgen_func_elem_1364(a, state0.b, arg0, arg1);
                     } finally {
                         state0.a = a;
                     }
@@ -2679,13 +2692,13 @@ function __wbg_get_imports() {
             return addHeapObject(ret);
         },
         __wbindgen_cast_0000000000000001: function(arg0, arg1) {
-            // Cast intrinsic for `Closure(Closure { dtor_idx: 136, function: Function { arguments: [Externref], shim_idx: 137, ret: Result(Unit), inner_ret: Some(Result(Unit)) }, mutable: true }) -> Externref`.
-            const ret = makeMutClosure(arg0, arg1, wasm.__wasm_bindgen_func_elem_1295, __wasm_bindgen_func_elem_1296);
+            // Cast intrinsic for `Closure(Closure { dtor_idx: 138, function: Function { arguments: [Externref], shim_idx: 139, ret: Result(Unit), inner_ret: Some(Result(Unit)) }, mutable: true }) -> Externref`.
+            const ret = makeMutClosure(arg0, arg1, wasm.__wasm_bindgen_func_elem_1318, __wasm_bindgen_func_elem_1319);
             return addHeapObject(ret);
         },
         __wbindgen_cast_0000000000000002: function(arg0, arg1) {
             // Cast intrinsic for `Closure(Closure { dtor_idx: 9, function: Function { arguments: [NamedExternref("Event")], shim_idx: 10, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
-            const ret = makeMutClosure(arg0, arg1, wasm.__wasm_bindgen_func_elem_284, __wasm_bindgen_func_elem_285);
+            const ret = makeMutClosure(arg0, arg1, wasm.__wasm_bindgen_func_elem_289, __wasm_bindgen_func_elem_290);
             return addHeapObject(ret);
         },
         __wbindgen_cast_0000000000000003: function(arg0) {
@@ -2722,14 +2735,14 @@ function __wbg_get_imports() {
     };
 }
 
-function __wasm_bindgen_func_elem_285(arg0, arg1, arg2) {
-    wasm.__wasm_bindgen_func_elem_285(arg0, arg1, addHeapObject(arg2));
+function __wasm_bindgen_func_elem_290(arg0, arg1, arg2) {
+    wasm.__wasm_bindgen_func_elem_290(arg0, arg1, addHeapObject(arg2));
 }
 
-function __wasm_bindgen_func_elem_1296(arg0, arg1, arg2) {
+function __wasm_bindgen_func_elem_1319(arg0, arg1, arg2) {
     try {
         const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
-        wasm.__wasm_bindgen_func_elem_1296(retptr, arg0, arg1, addHeapObject(arg2));
+        wasm.__wasm_bindgen_func_elem_1319(retptr, arg0, arg1, addHeapObject(arg2));
         var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
         var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
         if (r1) {
@@ -2740,8 +2753,8 @@ function __wasm_bindgen_func_elem_1296(arg0, arg1, arg2) {
     }
 }
 
-function __wasm_bindgen_func_elem_1327(arg0, arg1, arg2, arg3) {
-    wasm.__wasm_bindgen_func_elem_1327(arg0, arg1, addHeapObject(arg2), addHeapObject(arg3));
+function __wasm_bindgen_func_elem_1364(arg0, arg1, arg2, arg3) {
+    wasm.__wasm_bindgen_func_elem_1364(arg0, arg1, addHeapObject(arg2), addHeapObject(arg3));
 }