@omendb/omendb 0.0.30 → 0.0.32

package/README.md

@@ -374,13 +374,16 @@ const merged = db.mergeFrom(otherDb);
 
 ## Performance
 
-**10K vectors, 128D, M=16, ef=100. Measured 2026-01-20 (Apple M3 Max):**
+Node bindings call the same Rust core as the Rust and Python APIs, so authoritative ANN numbers are tracked at the repo root with the shared SIFT benchmark on Fedora/Linux medians.
 
-| Metric     | Value        |
-| ---------- | ------------ |
-| Search QPS | 11,542       |
-| Build      | 30,826 vec/s |
-| Recall@10  | 89.7%        |
+Use the shared benchmark for comparable performance claims:
+
+```bash
+cd python && uv run python benchmark.py
+cd python && uv run python benchmark.py --publish
+```
+
+Older Apple M3 Max wrapper numbers were local reference points only and are no longer treated as the authoritative baseline.
 
 ## License
 

package/index.d.ts

@@ -209,6 +209,71 @@ export declare class VectorDatabase {
    * @returns Array of results in same order as input, null for missing IDs
    */
   getBatch(ids: Array<string>): Array<GetResult | undefined | null>
+  /**
+   * Add a typed directed edge between two document IDs.
+   *
+   * @param fromId - Source document ID
+   * @param toId - Target document ID
+   * @param edgeType - Edge type label (e.g. "related", "parent")
+   * @param weight - Edge weight (default: 1.0)
+   * @param metadata - Arbitrary JSON-compatible metadata
+   */
+  addEdge(fromId: string, toId: string, edgeType: string, weight?: number | undefined | null, metadata?: JsonValue | undefined | null): void
+  /**
+   * Remove the edge of the given type between two nodes.
+   *
+   * @returns true if an edge was found and removed
+   */
+  removeEdge(fromId: string, toId: string, edgeType: string): boolean
+  /**
+   * Get all edges for a node in the given direction.
+   *
+   * @param id - Node ID
+   * @param direction - "outgoing", "incoming", or "both" (default: "both")
+   * @returns Array of edges with fromId, toId, edgeType, weight, metadata
+   */
+  getEdges(id: string, direction?: string | undefined | null, edgeType?: string | undefined | null): Array<EdgeResult>
+  /**
+   * BFS traversal from a starting node.
+   *
+   * @param startId - Starting node ID
+   * @param direction - "outgoing", "incoming", or "both" (default: "outgoing")
+   * @param maxDepth - Maximum traversal depth (default: 1)
+   * @param edgeType - Filter by edge type
+   * @returns Reachable node IDs (not including startId)
+   */
+  traverse(startId: string, direction?: string | undefined | null, maxDepth?: number | undefined | null, edgeType?: string | undefined | null): Array<string>
+  /**
+   * Expand a list of IDs by following their edges (depth=1).
+   *
+   * @param ids - Starting node IDs
+   * @param direction - "outgoing", "incoming", or "both" (default: "outgoing")
+   * @param edgeType - Filter by edge type
+   * @returns Expanded ID set (includes original IDs + neighbors)
+   */
+  expand(ids: Array<string>, direction?: string | undefined | null, edgeType?: string | undefined | null): Array<string>
+  /** Number of edges in the graph. */
+  get edgeCount(): number
+  /** Look up a single edge by endpoints and type. */
+  getEdge(fromId: string, toId: string, edgeType: string): EdgeResult | null
+  /** Get neighbor IDs for a node. */
+  neighbors(id: string, direction?: string | undefined | null, edgeType?: string | undefined | null): Array<string>
+  /** Count edges for a node. */
+  nodeDegree(id: string, direction?: string | undefined | null, edgeType?: string | undefined | null): number
+  /** Check if a path exists between two nodes. */
+  hasPath(fromId: string, toId: string, direction?: string | undefined | null, maxDepth?: number | undefined | null, edgeType?: string | undefined | null): boolean
+  /** Find shortest path between two nodes. */
+  shortestPath(fromId: string, toId: string, direction?: string | undefined | null, maxDepth?: number | undefined | null, edgeType?: string | undefined | null): Array<string> | null
+  /** BFS traversal returning discovery edges. */
+  traverseEdges(startId: string, direction?: string | undefined | null, maxDepth?: number | undefined | null, edgeType?: string | undefined | null): Array<TraversalHitResult>
+  /** Extract ego-graph around a node. */
+  subgraph(id: string, maxDepth?: number | undefined | null, direction?: string | undefined | null, edgeType?: string | undefined | null): SubgraphResult
+  /** Batch add edges with a single WAL sync. */
+  addEdges(edges: Array<EdgeInput>): number
+  /** Get all unique edge types. */
+  edgeTypes(): Array<string>
+  /** Get all node IDs with edges. */
+  nodeIds(): Array<string>
   /**
    * Check if text search is enabled.
    *
@@ -258,11 +323,9 @@ export declare class VectorDatabase {
   /**
    * Search for k nearest neighbors.
    *
-   * @param query - Query vector(s): number[] or Float32Array for single-vector stores;
-   *                number[][] or Float32Array[] for multi-vector stores
+   * @param query - Query vector (number[] or Float32Array)
    * @param k - Number of results to return
-   * @param options - Optional search options. Single-vector: {filter?, ef?, maxDistance?}.
-   *                  Multi-vector: {rerank?, rerankFactor?}
+   * @param options - Optional search options: {filter?, ef?, maxDistance?}
    * @returns Array of {id, distance, score, metadata}
    *
    * @example
@@ -273,12 +336,9 @@ export declare class VectorDatabase {
    * // With options
    * db.search([1, 0, 0, 0], 10, { filter: { category: "A" }, ef: 200 });
    * db.search([1, 0, 0, 0], 10, { maxDistance: 0.5 });
-   *
-   * // Multi-vector search
-   * db.search([[0.1, 0.2], [0.3, 0.4]], 5, { rerank: true, rerankFactor: 8 });
    * ```
    */
-  search(query: Array<number> | Float32Array | string | Array<Array<number>> | Array<Float32Array>, k: number, options?: { filter?: Record<string, unknown>; ef?: number; maxDistance?: number; rerank?: boolean; rerankFactor?: number } | undefined): Promise<Array<SearchResult>>
+  search(query: Array<number> | Float32Array | string, k: number, options?: { filter?: Record<string, unknown>; ef?: number; maxDistance?: number } | undefined): Promise<Array<SearchResult>>
   /**
    * Search multi-vector store with query tokens.
    *
@@ -287,7 +347,7 @@ export declare class VectorDatabase {
    * @param query - Query tokens (number[][] or Float32Array[])
    * @param k - Number of results to return
    * @param rerank - Enable MaxSim reranking for better quality (default: true)
-   * @param rerankFactor - Fetch k*rerankFactor candidates before reranking (default: 32)
+   * @param rerankFactor - Fetch k*rerankFactor candidates before reranking (default: 20)
    * @returns Array of {id, distance, metadata}
    */
   searchMulti(query: Array<Array<number>> | Array<Float32Array>, k: number, rerank?: boolean | undefined | null, rerankFactor?: number | undefined | null): Array<SearchResult>
@@ -367,6 +427,22 @@ export declare class VectorDatabase {
   hybridSparseSearch(queryVector: Array<number> | Float32Array, sparseQuery: { indices: number[]; values: number[] } | Record<string, number>, k: number, options?: { alpha?: number; filter?: Record<string, unknown> } | undefined): Array<SparseSearchResult>
 }
 
+export interface EdgeInput {
+  fromId: string
+  toId: string
+  edgeType: string
+  weight?: number
+  metadata?: Record<string, unknown> | null
+}
+
+export interface EdgeResult {
+  fromId: string
+  toId: string
+  edgeType: string
+  weight: number
+  metadata?: Record<string, unknown> | null
+}
+
 export interface GetResult {
   id: string
   vector: Float32Array
@@ -462,12 +538,13 @@ export interface OpenOptions {
   metric?: string
   /**
    * Enable multi-vector mode for ColBERT-style retrieval
-   * - true: Enable with default config (repetitions=8, partition_bits=4, dProj=16)
-   * - { repetitions?, partitionBits?, seed?, dProj? }: Custom config
+   * - true: Enable with default config (repetitions=8, partitionBits=4, dProj=16)
+   * - { repetitions?, partitionBits?, seed?, dProj?, poolFactor? }: Custom config
    * - dProj: Dimension projection (16 = 8x smaller FDE, null = full token dim)
+   * - poolFactor: Optional token pooling ratio (2 halves stored tokens)
    * - false/null: Disabled (default, single-vector mode)
    */
-  multiVector?: boolean | { repetitions?: number; partitionBits?: number; seed?: number; dProj?: number | null } | null | undefined
+  multiVector?: boolean | { repetitions?: number; partitionBits?: number; seed?: number; dProj?: number | null; poolFactor?: number | null } | null | undefined
   /** SQ8 refiner: rescore with full precision (default: true when quantized) */
   rescore?: boolean
   /** Candidate multiplier for rescoring (default: 3.0) */
@@ -511,8 +588,19 @@ export interface StatsResult {
   path: string
 }
 
+export interface SubgraphResult {
+  nodeIds: Array<string>
+  edges: Array<EdgeResult>
+}
+
 export interface TextSearchResult {
   id: string
   score: number
   metadata: Record<string, unknown>
 }
+
+export interface TraversalHitResult {
+  id: string
+  depth: number
+  edge: EdgeResult
+}

package/index.js

@@ -365,6 +365,72 @@ class VectorDatabase {
 	hybridSparseSearch(queryVector, sparseQuery, k, options) {
 		return this._native.hybridSparseSearch(queryVector, sparseQuery, k, options);
 	}
+
+	// --- Edge graph API ---
+
+	addEdge(fromId, toId, edgeType, weight, metadata) {
+		return this._native.addEdge(fromId, toId, edgeType, weight, metadata);
+	}
+
+	removeEdge(fromId, toId, edgeType) {
+		return this._native.removeEdge(fromId, toId, edgeType);
+	}
+
+	getEdges(id, direction, edgeType) {
+		return this._native.getEdges(id, direction, edgeType);
+	}
+
+	traverse(startId, direction, maxDepth, edgeType) {
+		return this._native.traverse(startId, direction, maxDepth, edgeType);
+	}
+
+	expand(ids, direction, edgeType) {
+		return this._native.expand(ids, direction, edgeType);
+	}
+
+	get edgeCount() {
+		return this._native.edgeCount;
+	}
+
+	getEdge(fromId, toId, edgeType) {
+		return this._native.getEdge(fromId, toId, edgeType);
+	}
+
+	neighbors(id, direction, edgeType) {
+		return this._native.neighbors(id, direction, edgeType);
+	}
+
+	nodeDegree(id, direction, edgeType) {
+		return this._native.nodeDegree(id, direction, edgeType);
+	}
+
+	hasPath(fromId, toId, direction, maxDepth, edgeType) {
+		return this._native.hasPath(fromId, toId, direction, maxDepth, edgeType);
+	}
+
+	shortestPath(fromId, toId, direction, maxDepth, edgeType) {
+		return this._native.shortestPath(fromId, toId, direction, maxDepth, edgeType);
+	}
+
+	traverseEdges(startId, direction, maxDepth, edgeType) {
+		return this._native.traverseEdges(startId, direction, maxDepth, edgeType);
+	}
+
+	subgraph(id, maxDepth, direction, edgeType) {
+		return this._native.subgraph(id, maxDepth, direction, edgeType);
+	}
+
+	addEdges(edges) {
+		return this._native.addEdges(edges);
+	}
+
+	edgeTypes() {
+		return this._native.edgeTypes();
+	}
+
+	nodeIds() {
+		return this._native.nodeIds();
+	}
 }
 
 function open(path, options, embeddingFn) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omendb/omendb",
-  "version": "0.0.30",
+  "version": "0.0.32",
   "description": "Fast embedded vector database with HNSW + ACORN-1 filtered search",
   "main": "index.js",
   "types": "index.d.ts",
@@ -50,10 +50,10 @@
     "omendb.node"
   ],
   "optionalDependencies": {
-    "@omendb/omendb-darwin-x64": "0.0.30",
-    "@omendb/omendb-darwin-arm64": "0.0.30",
-    "@omendb/omendb-linux-x64-gnu": "0.0.30",
-    "@omendb/omendb-linux-arm64-gnu": "0.0.30",
-    "@omendb/omendb-win32-x64-msvc": "0.0.30"
+    "@omendb/omendb-darwin-x64": "0.0.32",
+    "@omendb/omendb-darwin-arm64": "0.0.32",
+    "@omendb/omendb-linux-x64-gnu": "0.0.32",
+    "@omendb/omendb-linux-arm64-gnu": "0.0.32",
+    "@omendb/omendb-win32-x64-msvc": "0.0.32"
   }
 }