hyperspace-sdk-ts 2.2.0 → 2.2.1

package/README.md

@@ -1,6 +1,6 @@
 # HyperspaceDB TypeScript SDK
 
-Official TypeScript client for HyperspaceDB gRPC API.
+Official TypeScript client for HyperspaceDB gRPC API (v2.2.1).
 
 Use this SDK for:
 - collection lifecycle management
@@ -8,6 +8,9 @@ Use this SDK for:
 - high-throughput batched search (`searchBatch`)
 - bulk insertion (`batchInsert`)
 - advanced filtering and hybrid search
+- typed metadata (`string | number | boolean`)
+- graph traversal APIs (`getNode`, `getNeighbors`, `getConceptParents`, `traverse`, `findSemanticClusters`)
+- rebuild with metadata pruning (`rebuildIndexWithFilter`)
 - multi-tenant authentication headers (`x-api-key`, `x-hyperspace-user-id`)
 
 ## Requirements
@@ -66,6 +69,7 @@ Delete collection and all its data.
 ### `insert(id, vector, meta?, collection?, durability?)`
 
 Insert one vector. Accepts `number[]`, `Float32Array`, `Float64Array`.
+Optional `typedMetadata` supports typed values for range/boolean filters.
 
 ### `batchInsert(items, collection?, durability?)`
 
@@ -81,6 +85,7 @@ await client.batchInsert([
 
 Run nearest-neighbor search. 
 Options include `filters`, `hybridQuery`, and `hybridAlpha`.
+Decimal range values are supported and sent as `gte_f64/lte_f64` in gRPC payload.
 
 ```ts
 const results = await client.search(vector, 10, "coll", {
@@ -105,6 +110,50 @@ Retrieve collection stats and logical clock.
 
 Close underlying gRPC channel.
 
+### `subscribeToEvents(options, onEvent, onError?)`
+
+Subscribe to CDC stream events from server:
+
+```ts
+const stream = client.subscribeToEvents(
+  { types: ["insert", "delete"], collection: "docs_ts" },
+  (event) => console.log("event:", event.toObject()),
+  (err) => console.error(err),
+);
+```
+
+### `rebuildIndex(collection)`
+
+Trigger index rebuild/vacuum for a collection.
+
+### `rebuildIndexWithFilter(collection, filter)`
+
+Rebuild with metadata pruning for sleep/reconsolidation workflows.
+
+```ts
+await client.rebuildIndexWithFilter("docs_ts", {
+  key: "energy",
+  op: "lt",
+  value: 0.1,
+});
+```
+
+### `HyperbolicMath`
+
+```ts
+import { HyperbolicMath } from "hyperspace-sdk-ts";
+
+const z = HyperbolicMath.mobiusAdd([0.1, 0.0], [0.2, 0.0]);
+```
+
+Provided utilities:
+- `mobiusAdd(x, y, c?)`
+- `expMap(x, v, c?)`
+- `logMap(x, y, c?)`
+- `riemannianGradient(x, euclideanGrad, c?)`
+- `parallelTransport(x, y, v, c?)`
+- `frechetMean(points, c?, maxIter?, tol?)`
+
 ## Performance Notes
 
 - Prefer `searchBatch` and `batchInsert` for throughput-heavy services.

package/dist/client.d.ts

@@ -1,5 +1,7 @@
-import { DurabilityLevel } from './proto/hyperspace_pb';
+import * as grpc from '@grpc/grpc-js';
+import { DurabilityLevel, EventMessage } from './proto/hyperspace_pb';
 export { DurabilityLevel };
+export type TypedMetadataValue = string | number | boolean;
 export interface Filter {
     match?: {
         key: string;
@@ -17,6 +19,9 @@ export interface SearchResult {
     metadata: {
         [key: string]: string;
     };
+    typedMetadata: {
+        [key: string]: TypedMetadataValue;
+    };
 }
 export interface GraphNode {
     id: number;
@@ -25,23 +30,52 @@ export interface GraphNode {
     metadata: {
         [key: string]: string;
     };
+    typedMetadata: {
+        [key: string]: TypedMetadataValue;
+    };
+}
+export interface VacuumFilter {
+    key: string;
+    op: 'lt' | 'lte' | 'gt' | 'gte' | 'eq' | 'ne';
+    value: number;
 }
+export type EventTypeName = 'insert' | 'delete';
+export interface SubscribeOptions {
+    types?: EventTypeName[];
+    collection?: string;
+}
+export declare const HyperbolicMath: {
+    projectToBall(x: number[], c?: number): number[];
+    mobiusAdd(x: number[], y: number[], c?: number): number[];
+    expMap(x: number[], v: number[], c?: number): number[];
+    logMap(x: number[], y: number[], c?: number): number[];
+    riemannianGradient(x: number[], euclideanGrad: number[], c?: number): number[];
+    parallelTransport(x: number[], y: number[], v: number[], c?: number): number[];
+    frechetMean(points: number[][], c?: number, maxIter?: number, tol?: number): number[];
+};
 export declare class HyperspaceClient {
     private client;
     private metadata;
     private static toVectorList;
+    private static toProtoMetadataValue;
+    private static parseTypedMetadata;
     constructor(host?: string, apiKey?: string, userId?: string);
     createCollection(name: string, dimension: number, metric: string): Promise<boolean>;
     deleteCollection(name: string): Promise<boolean>;
     insert(id: number, vector: number[] | Float32Array | Float64Array, meta?: {
         [key: string]: string;
-    }, collection?: string, durability?: DurabilityLevel): Promise<boolean>;
+    }, collection?: string, durability?: DurabilityLevel, typedMetadata?: {
+        [key: string]: TypedMetadataValue;
+    }): Promise<boolean>;
     batchInsert(items: {
         id: number;
         vector: number[] | Float32Array | Float64Array;
         metadata?: {
             [key: string]: string;
         };
+        typedMetadata?: {
+            [key: string]: TypedMetadataValue;
+        };
     }[], collection?: string, durability?: DurabilityLevel): Promise<boolean>;
     search(vector: number[] | Float32Array | Float64Array, topK: number, collection?: string, options?: {
         filters?: Filter[];
@@ -54,6 +88,8 @@ export declare class HyperspaceClient {
         stateHash: number;
         count: number;
     }>;
+    rebuildIndex(collection: string): Promise<boolean>;
+    rebuildIndexWithFilter(collection: string, filter: VacuumFilter): Promise<boolean>;
     getNode(id: number, layer?: number, collection?: string): Promise<GraphNode>;
     getNeighbors(id: number, layer?: number, limit?: number, offset?: number, collection?: string): Promise<GraphNode[]>;
     getConceptParents(id: number, layer?: number, limit?: number, collection?: string): Promise<GraphNode[]>;
@@ -64,5 +100,6 @@ export declare class HyperspaceClient {
         filters?: Filter[];
     }): Promise<GraphNode[]>;
     findSemanticClusters(layer?: number, minClusterSize?: number, maxClusters?: number, maxNodes?: number, collection?: string): Promise<number[][]>;
+    subscribeToEvents(options: SubscribeOptions, onEvent: (event: EventMessage) => void, onError?: (err: Error) => void): grpc.ClientReadableStream<EventMessage>;
     close(): void;
 }

package/dist/client.js

@@ -33,12 +33,124 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.HyperspaceClient = exports.DurabilityLevel = void 0;
+exports.HyperspaceClient = exports.HyperbolicMath = exports.DurabilityLevel = void 0;
 const grpc = __importStar(require("@grpc/grpc-js"));
 const hyperspace_grpc_pb_1 = require("./proto/hyperspace_grpc_pb");
 const hyperspace_pb_1 = require("./proto/hyperspace_pb");
 Object.defineProperty(exports, "DurabilityLevel", { enumerable: true, get: function () { return hyperspace_pb_1.DurabilityLevel; } });
 const hyperspace_pb = __importStar(require("./proto/hyperspace_pb")); // New, for direct access to types
+exports.HyperbolicMath = {
+    projectToBall(x, c = 1.0) {
+        if (c <= 0)
+            throw new Error('Curvature c must be > 0');
+        const normSq = (u) => u.reduce((s, z) => s + z * z, 0);
+        const n = Math.sqrt(Math.max(normSq(x), 0));
+        const maxN = (1 / Math.sqrt(c)) - 1e-9;
+        if (n <= maxN || n <= 1e-15)
+            return [...x];
+        const scale = maxN / n;
+        return x.map((v) => v * scale);
+    },
+    mobiusAdd(x, y, c = 1.0) {
+        if (x.length !== y.length)
+            throw new Error('Dimension mismatch');
+        if (c <= 0)
+            throw new Error('Curvature c must be > 0');
+        const dot = (a, b) => a.reduce((s, v, i) => s + v * b[i], 0);
+        const x2 = dot(x, x);
+        const y2 = dot(y, y);
+        const xy = dot(x, y);
+        const left = 1 + 2 * c * xy + c * y2;
+        const right = 1 - c * x2;
+        const den = 1 + 2 * c * xy + c * c * x2 * y2;
+        if (Math.abs(den) < 1e-15)
+            throw new Error('Mobius denominator too small');
+        return x.map((xi, i) => (left * xi + right * y[i]) / den);
+    },
+    expMap(x, v, c = 1.0) {
+        if (x.length !== v.length)
+            throw new Error('Dimension mismatch');
+        if (c <= 0)
+            throw new Error('Curvature c must be > 0');
+        const normSq = (u) => u.reduce((s, z) => s + z * z, 0);
+        const vNorm = Math.sqrt(Math.max(normSq(v), 0));
+        if (vNorm < 1e-15)
+            return [...x];
+        const lambdaX = 2 / Math.max(1 - c * normSq(x), 1e-15);
+        const scale = Math.tanh(Math.sqrt(c) * lambdaX * vNorm / 2) / (Math.sqrt(c) * vNorm);
+        return exports.HyperbolicMath.mobiusAdd(x, v.map((vi) => scale * vi), c);
+    },
+    logMap(x, y, c = 1.0) {
+        if (x.length !== y.length)
+            throw new Error('Dimension mismatch');
+        if (c <= 0)
+            throw new Error('Curvature c must be > 0');
+        const normSq = (u) => u.reduce((s, z) => s + z * z, 0);
+        const delta = exports.HyperbolicMath.mobiusAdd(x.map((xi) => -xi), y, c);
+        const deltaNorm = Math.sqrt(Math.max(normSq(delta), 0));
+        if (deltaNorm < 1e-15)
+            return new Array(x.length).fill(0);
+        const lambdaX = 2 / Math.max(1 - c * normSq(x), 1e-15);
+        const arg = Math.min(Math.sqrt(c) * deltaNorm, 1 - 1e-15);
+        const factor = (2 / (lambdaX * Math.sqrt(c))) * Math.atanh(arg);
+        return delta.map((di) => factor * di / deltaNorm);
+    },
+    riemannianGradient(x, euclideanGrad, c = 1.0) {
+        if (x.length !== euclideanGrad.length)
+            throw new Error('Dimension mismatch');
+        if (c <= 0)
+            throw new Error('Curvature c must be > 0');
+        const normSq = (u) => u.reduce((s, z) => s + z * z, 0);
+        const lambdaX = 2 / Math.max(1 - c * normSq(x), 1e-15);
+        const scale = 1 / (lambdaX * lambdaX);
+        return euclideanGrad.map((g) => scale * g);
+    },
+    parallelTransport(x, y, v, c = 1.0) {
+        if (x.length !== y.length || x.length !== v.length)
+            throw new Error('Dimension mismatch');
+        if (c <= 0)
+            throw new Error('Curvature c must be > 0');
+        const normSq = (u) => u.reduce((s, z) => s + z * z, 0);
+        const gyro = (u, w, z) => {
+            const uw = exports.HyperbolicMath.mobiusAdd(u, w, c);
+            const wz = exports.HyperbolicMath.mobiusAdd(w, z, c);
+            const left = exports.HyperbolicMath.mobiusAdd(u, wz, c);
+            return exports.HyperbolicMath.mobiusAdd(uw.map((k) => -k), left, c);
+        };
+        const g = gyro(y, x.map((xi) => -xi), v);
+        const lambdaX = 2 / Math.max(1 - c * normSq(x), 1e-15);
+        const lambdaY = 2 / Math.max(1 - c * normSq(y), 1e-15);
+        const scale = lambdaX / lambdaY;
+        return g.map((gi) => scale * gi);
+    },
+    frechetMean(points, c = 1.0, maxIter = 64, tol = 1e-8) {
+        if (!points.length)
+            throw new Error('Points set cannot be empty');
+        if (c <= 0)
+            throw new Error('Curvature c must be > 0');
+        const dim = points[0].length;
+        if (points.some((p) => p.length !== dim))
+            throw new Error('Dimension mismatch');
+        const normSq = (u) => u.reduce((s, z) => s + z * z, 0);
+        let mu = exports.HyperbolicMath.projectToBall(points[0], c);
+        for (let iter = 0; iter < Math.max(1, maxIter); iter++) {
+            const grad = new Array(dim).fill(0);
+            for (const p of points) {
+                const lg = exports.HyperbolicMath.logMap(mu, p, c);
+                for (let i = 0; i < dim; i++)
+                    grad[i] += lg[i];
+            }
+            for (let i = 0; i < dim; i++)
+                grad[i] /= points.length;
+            const gNorm = Math.sqrt(Math.max(normSq(grad), 0));
+            if (gNorm <= Math.max(tol, 1e-15))
+                break;
+            mu = exports.HyperbolicMath.expMap(mu, grad, c);
+            mu = exports.HyperbolicMath.projectToBall(mu, c);
+        }
+        return mu;
+    }
+};
 class HyperspaceClient {
     static toVectorList(vector) {
         if (Array.isArray(vector)) {
@@ -46,6 +158,42 @@ class HyperspaceClient {
         }
         return Array.from(vector);
     }
+    static toProtoMetadataValue(value) {
+        const out = new hyperspace_pb.MetadataValue();
+        if (typeof value === 'string')
+            out.setStringValue(value);
+        else if (typeof value === 'boolean')
+            out.setBoolValue(value);
+        else if (Number.isInteger(value))
+            out.setIntValue(Number(value));
+        else
+            out.setDoubleValue(Number(value));
+        return out;
+    }
+    static parseTypedMetadata(metaMap) {
+        const out = {};
+        if (metaMap.getLength() === 0)
+            return out;
+        metaMap.forEach((value, key) => {
+            switch (value.getKindCase()) {
+                case hyperspace_pb.MetadataValue.KindCase.STRING_VALUE:
+                    out[key] = value.getStringValue();
+                    break;
+                case hyperspace_pb.MetadataValue.KindCase.INT_VALUE:
+                    out[key] = value.getIntValue();
+                    break;
+                case hyperspace_pb.MetadataValue.KindCase.DOUBLE_VALUE:
+                    out[key] = value.getDoubleValue();
+                    break;
+                case hyperspace_pb.MetadataValue.KindCase.BOOL_VALUE:
+                    out[key] = value.getBoolValue();
+                    break;
+                default:
+                    break;
+            }
+        });
+        return out;
+    }
     constructor(host = 'localhost:50051', apiKey, userId) {
         const options = {
             'grpc.max_send_message_length': 64 * 1024 * 1024,
@@ -90,7 +238,7 @@ class HyperspaceClient {
             });
         });
     }
-    insert(id, vector, meta, collection = '', durability = hyperspace_pb_1.DurabilityLevel.DEFAULT_LEVEL) {
+    insert(id, vector, meta, collection = '', durability = hyperspace_pb_1.DurabilityLevel.DEFAULT_LEVEL, typedMetadata) {
         return new Promise((resolve, reject) => {
             const req = new hyperspace_pb_1.InsertRequest();
             req.setId(id);
@@ -100,6 +248,11 @@ class HyperspaceClient {
                 for (const k in meta)
                     map.set(k, meta[k]);
             }
+            if (typedMetadata) {
+                const map = req.getTypedMetadataMap();
+                for (const k in typedMetadata)
+                    map.set(k, HyperspaceClient.toProtoMetadataValue(typedMetadata[k]));
+            }
             req.setCollection(collection);
             req.setOriginNodeId('');
             req.setLogicalClock(0);
@@ -125,6 +278,11 @@ class HyperspaceClient {
                     for (const k in item.metadata)
                         map.set(k, item.metadata[k]);
                 }
+                if (item.typedMetadata) {
+                    const map = v.getTypedMetadataMap();
+                    for (const k in item.typedMetadata)
+                        map.set(k, HyperspaceClient.toProtoMetadataValue(item.typedMetadata[k]));
+                }
                 return v;
             });
             req.setVectorsList(vectors);
@@ -153,10 +311,18 @@ class HyperspaceClient {
                     else if (f.range) {
                         const r = new hyperspace_pb.Range();
                         r.setKey(f.range.key);
-                        if (f.range.gte !== undefined)
-                            r.setGte(f.range.gte);
-                        if (f.range.lte !== undefined)
-                            r.setLte(f.range.lte);
+                        if (f.range.gte !== undefined) {
+                            if (Number.isInteger(f.range.gte))
+                                r.setGte(f.range.gte);
+                            else
+                                r.setGteF64(f.range.gte);
+                        }
+                        if (f.range.lte !== undefined) {
+                            if (Number.isInteger(f.range.lte))
+                                r.setLte(f.range.lte);
+                            else
+                                r.setLteF64(f.range.lte);
+                        }
                         pf.setRange(r);
                     }
                     return pf;
@@ -181,7 +347,8 @@ class HyperspaceClient {
                     return {
                         id: r.getId(),
                         distance: r.getDistance(),
-                        metadata: meta
+                        metadata: meta,
+                        typedMetadata: HyperspaceClient.parseTypedMetadata(r.getTypedMetadataMap())
                     };
                 });
                 resolve(results);
@@ -212,7 +379,8 @@ class HyperspaceClient {
                     return {
                         id: r.getId(),
                         distance: r.getDistance(),
-                        metadata: meta
+                        metadata: meta,
+                        typedMetadata: HyperspaceClient.parseTypedMetadata(r.getTypedMetadataMap())
                     };
                 }));
                 resolve(batch);
@@ -234,6 +402,33 @@ class HyperspaceClient {
             });
         });
     }
+    rebuildIndex(collection) {
+        return new Promise((resolve, reject) => {
+            const req = new hyperspace_pb_1.RebuildIndexRequest();
+            req.setName(collection);
+            this.client.rebuildIndex(req, this.metadata, (err) => {
+                if (err)
+                    return reject(err);
+                resolve(true);
+            });
+        });
+    }
+    rebuildIndexWithFilter(collection, filter) {
+        return new Promise((resolve, reject) => {
+            const req = new hyperspace_pb_1.RebuildIndexRequest();
+            req.setName(collection);
+            const fq = new hyperspace_pb_1.VacuumFilterQuery();
+            fq.setKey(filter.key);
+            fq.setOp(filter.op);
+            fq.setValue(filter.value);
+            req.setFilterQuery(fq);
+            this.client.rebuildIndex(req, this.metadata, (err) => {
+                if (err)
+                    return reject(err);
+                resolve(true);
+            });
+        });
+    }
     getNode(id, layer = 0, collection = '') {
         return new Promise((resolve, reject) => {
             const req = new hyperspace_pb_1.GetNodeRequest();
@@ -254,7 +449,8 @@ class HyperspaceClient {
                     id: resp.getId(),
                     layer: resp.getLayer(),
                     neighbors: resp.getNeighborsList(),
-                    metadata
+                    metadata,
+                    typedMetadata: HyperspaceClient.parseTypedMetadata(resp.getTypedMetadataMap())
                 });
             });
         });
@@ -282,7 +478,8 @@ class HyperspaceClient {
                         id: n.getId(),
                         layer: n.getLayer(),
                         neighbors: n.getNeighborsList(),
-                        metadata
+                        metadata,
+                        typedMetadata: HyperspaceClient.parseTypedMetadata(n.getTypedMetadataMap())
                     };
                 });
                 resolve(nodes);
@@ -311,7 +508,8 @@ class HyperspaceClient {
                         id: n.getId(),
                         layer: n.getLayer(),
                         neighbors: n.getNeighborsList(),
-                        metadata
+                        metadata,
+                        typedMetadata: HyperspaceClient.parseTypedMetadata(n.getTypedMetadataMap())
                     };
                 });
                 resolve(nodes);
@@ -344,10 +542,18 @@ class HyperspaceClient {
                     else if (f.range) {
                         const r = new hyperspace_pb.Range();
                         r.setKey(f.range.key);
-                        if (f.range.gte !== undefined)
-                            r.setGte(f.range.gte);
-                        if (f.range.lte !== undefined)
-                            r.setLte(f.range.lte);
+                        if (f.range.gte !== undefined) {
+                            if (Number.isInteger(f.range.gte))
+                                r.setGte(f.range.gte);
+                            else
+                                r.setGteF64(f.range.gte);
+                        }
+                        if (f.range.lte !== undefined) {
+                            if (Number.isInteger(f.range.lte))
+                                r.setLte(f.range.lte);
+                            else
+                                r.setLteF64(f.range.lte);
+                        }
                         pf.setRange(r);
                     }
                     return pf;
@@ -369,7 +575,8 @@ class HyperspaceClient {
                         id: n.getId(),
                         layer: n.getLayer(),
                         neighbors: n.getNeighborsList(),
-                        metadata
+                        metadata,
+                        typedMetadata: HyperspaceClient.parseTypedMetadata(n.getTypedMetadataMap())
                     };
                 });
                 resolve(nodes);
@@ -391,6 +598,23 @@ class HyperspaceClient {
             });
         });
     }
+    subscribeToEvents(options, onEvent, onError) {
+        const req = new hyperspace_pb_1.EventSubscriptionRequest();
+        if (options.collection) {
+            req.setCollection(options.collection);
+        }
+        const requested = options.types || [];
+        if (requested.length > 0) {
+            const mapped = requested.map((t) => t === 'insert' ? hyperspace_pb_1.EventType.VECTOR_INSERTED : hyperspace_pb_1.EventType.VECTOR_DELETED);
+            req.setTypesList(mapped);
+        }
+        const stream = this.client.subscribeToEvents(req, this.metadata);
+        stream.on('data', onEvent);
+        if (onError) {
+            stream.on('error', onError);
+        }
+        return stream;
+    }
     close() {
         this.client.close();
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hyperspace-sdk-ts",
-  "version": "2.2.0",
+  "version": "2.2.1",
   "description": "Official TypeScript SDK for HyperspaceDB gRPC API",
   "main": "dist/client.js",
   "types": "dist/client.d.ts",