@wiscale/velesdb-wasm 1.4.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,29 +93,33 @@ class VectorStore {
 
   // Methods
   insert(id: bigint, vector: Float32Array): void;
-  insert_with_payload(id: bigint, vector: Float32Array, payload: object): void;  // v0.8.5+
+  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}>;  // v0.8.5+
-  text_search(query: string, k: number, field?: string): Array<{id, score, payload}>;  // v0.8.5+
-  get(id: bigint): {id, vector, payload} | null;  // v0.8.5+
+  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
   
-  // ⭐ NEW v1.1.0
+  //
   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;
 }
 ```
 
-### Filter Format (v0.8.5+)
+### Filter Format
 
 ```javascript
 // Equality filter
@@ -256,42 +264,118 @@ The WASM build is optimized for client-side use cases but has some limitations c
 |---------|------|-------------|
 | Vector search (NEAR) | ✅ | ✅ |
 | Metadata filtering | ✅ | ✅ |
-| Full VelesQL queries | ❌ | ✅ |
-| Hybrid search (vector + BM25) | ❌ | ✅ |
-| Knowledge Graph operations | ❌ | ✅ |
-| MATCH clause (full-text) | ❌ | ✅ |
-| NEAR_FUSED (multi-query fusion) | ❌ | ✅ |
+| Hybrid search (vector + BM25) | ✅ | ✅ |
+| Full-text search (BM25) | ✅ | ✅ |
+| Multi-query fusion (MQG) | ✅ | ✅ |
+| Batch search | ✅ | ✅ |
+| 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
-- **Hybrid search** - Combine semantic + keyword search
-- **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
 
@@ -304,15 +388,15 @@ const store = new VectorStore(768, 'cosine');
 const results = store.search(query, 10);
 
 // REST (server-side) - using fetch
-const response = await fetch('http://localhost:8080/v1/collections/docs/search', {
+const response = await fetch('http://localhost:8080/collections/docs/search', {
   method: 'POST',
   headers: { 'Content-Type': 'application/json' },
-  body: JSON.stringify({ vector: query, limit: 10 })
+  body: JSON.stringify({ vector: query, top_k: 10 })
 });
 const results = await response.json();
 
 // REST with VelesQL
-const response = await fetch('http://localhost:8080/v1/query', {
+const response = await fetch('http://localhost:8080/query', {
   method: 'POST',
   headers: { 'Content-Type': 'application/json' },
   body: JSON.stringify({
@@ -346,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.4.1",
-  "license": "SEE LICENSE IN ../../LICENSE",
+  "version": "1.6.0",
+  "license": "MIT",
   "repository": {
     "type": "git",
     "url": "https://github.com/cyberlife-coder/velesdb"