hyperspace-sdk-ts 2.2.0 → 3.0.0

package/dist/client.js

@@ -33,12 +33,127 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.HyperspaceClient = exports.DurabilityLevel = void 0;
+exports.HyperspaceClient = exports.HyperbolicMath = exports.DurabilityLevel = exports.TribunalContext = exports.CognitiveMath = 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.CognitiveMath = __importStar(require("./math"));
+var agents_1 = require("./agents");
+Object.defineProperty(exports, "TribunalContext", { enumerable: true, get: function () { return agents_1.TribunalContext; } });
+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 +161,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 +241,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 +251,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);
@@ -111,6 +267,37 @@ class HyperspaceClient {
             });
         });
     }
+    insertText(id, text, meta, collection = '', durability = hyperspace_pb_1.DurabilityLevel.DEFAULT_LEVEL) {
+        return new Promise((resolve, reject) => {
+            const req = new hyperspace_pb_1.InsertTextRequest();
+            req.setId(id);
+            req.setText(text);
+            if (meta) {
+                const map = req.getMetadataMap();
+                for (const k in meta)
+                    map.set(k, meta[k]);
+            }
+            req.setCollection(collection);
+            req.setDurability(durability);
+            this.client.insertText(req, this.metadata, (err, resp) => {
+                if (err)
+                    return reject(err);
+                resolve(resp.getSuccess());
+            });
+        });
+    }
+    vectorize(text, metric = 'l2') {
+        return new Promise((resolve, reject) => {
+            const req = new hyperspace_pb_1.VectorizeRequest();
+            req.setText(text);
+            req.setMetric(metric);
+            this.client.vectorize(req, this.metadata, (err, resp) => {
+                if (err)
+                    return reject(err);
+                resolve(resp.getVectorList());
+            });
+        });
+    }
     batchInsert(items, collection = '', durability = hyperspace_pb_1.DurabilityLevel.DEFAULT_LEVEL) {
         return new Promise((resolve, reject) => {
             const req = new hyperspace_pb_1.BatchInsertRequest();
@@ -125,6 +312,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 +345,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 +381,66 @@ class HyperspaceClient {
                     return {
                         id: r.getId(),
                         distance: r.getDistance(),
-                        metadata: meta
+                        metadata: meta,
+                        typedMetadata: HyperspaceClient.parseTypedMetadata(r.getTypedMetadataMap())
+                    };
+                });
+                resolve(results);
+            });
+        });
+    }
+    searchText(text, topK, collection = '', options) {
+        return new Promise((resolve, reject) => {
+            const req = new hyperspace_pb_1.SearchTextRequest();
+            req.setText(text);
+            req.setTopK(topK);
+            req.setCollection(collection);
+            if (options === null || options === void 0 ? void 0 : options.filters) {
+                const protoFilters = options.filters.map(f => {
+                    const pf = new hyperspace_pb.Filter();
+                    if (f.match) {
+                        const m = new hyperspace_pb.Match();
+                        m.setKey(f.match.key);
+                        m.setValue(f.match.value);
+                        pf.setMatch(m);
+                    }
+                    else if (f.range) {
+                        const r = new hyperspace_pb.Range();
+                        r.setKey(f.range.key);
+                        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;
+                });
+                req.setFiltersList(protoFilters);
+            }
+            this.client.searchText(req, this.metadata, (err, resp) => {
+                if (err)
+                    return reject(err);
+                const results = resp.getResultsList().map(r => {
+                    const metaMap = r.getMetadataMap();
+                    const meta = {};
+                    if (metaMap.getLength() > 0) {
+                        metaMap.forEach((entry, key) => {
+                            meta[key] = entry;
+                        });
+                    }
+                    return {
+                        id: r.getId(),
+                        distance: r.getDistance(),
+                        metadata: meta,
+                        typedMetadata: HyperspaceClient.parseTypedMetadata(r.getTypedMetadataMap())
                     };
                 });
                 resolve(results);
@@ -212,7 +471,8 @@ class HyperspaceClient {
                     return {
                         id: r.getId(),
                         distance: r.getDistance(),
-                        metadata: meta
+                        metadata: meta,
+                        typedMetadata: HyperspaceClient.parseTypedMetadata(r.getTypedMetadataMap())
                     };
                 }));
                 resolve(batch);
@@ -234,6 +494,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 +541,8 @@ class HyperspaceClient {
                     id: resp.getId(),
                     layer: resp.getLayer(),
                     neighbors: resp.getNeighborsList(),
-                    metadata
+                    metadata,
+                    typedMetadata: HyperspaceClient.parseTypedMetadata(resp.getTypedMetadataMap())
                 });
             });
         });
@@ -282,7 +570,8 @@ class HyperspaceClient {
                         id: n.getId(),
                         layer: n.getLayer(),
                         neighbors: n.getNeighborsList(),
-                        metadata
+                        metadata,
+                        typedMetadata: HyperspaceClient.parseTypedMetadata(n.getTypedMetadataMap())
                     };
                 });
                 resolve(nodes);
@@ -311,7 +600,8 @@ class HyperspaceClient {
                         id: n.getId(),
                         layer: n.getLayer(),
                         neighbors: n.getNeighborsList(),
-                        metadata
+                        metadata,
+                        typedMetadata: HyperspaceClient.parseTypedMetadata(n.getTypedMetadataMap())
                     };
                 });
                 resolve(nodes);
@@ -344,10 +634,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 +667,8 @@ class HyperspaceClient {
                         id: n.getId(),
                         layer: n.getLayer(),
                         neighbors: n.getNeighborsList(),
-                        metadata
+                        metadata,
+                        typedMetadata: HyperspaceClient.parseTypedMetadata(n.getTypedMetadataMap())
                     };
                 });
                 resolve(nodes);
@@ -391,6 +690,53 @@ 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;
+    }
+    syncHandshake(collection, clientBuckets, clientLogicalClock = 0, clientCount = 0) {
+        return new Promise((resolve, reject) => {
+            if (clientBuckets.length !== 256) {
+                return reject(new Error("clientBuckets must contain exactly 256 elements"));
+            }
+            const req = new hyperspace_pb.SyncHandshakeRequest();
+            req.setCollection(collection);
+            req.setClientBucketsList(clientBuckets);
+            req.setClientLogicalClock(clientLogicalClock);
+            req.setClientCount(clientCount);
+            this.client.syncHandshake(req, this.metadata, (err, res) => {
+                if (err)
+                    return reject(err);
+                resolve(res.toObject());
+            });
+        });
+    }
+    syncPull(collection, bucketIndices, onData, onError) {
+        const req = new hyperspace_pb.SyncPullRequest();
+        req.setCollection(collection);
+        req.setBucketIndicesList(bucketIndices);
+        const stream = this.client.syncPull(req, this.metadata);
+        stream.on('data', (data) => {
+            onData(data.toObject());
+        });
+        if (onError) {
+            stream.on('error', onError);
+        }
+        return stream;
+    }
     close() {
         this.client.close();
     }

package/dist/math.d.ts

@@ -0,0 +1,44 @@
+/**
+ * HyperspaceDB Spatial and Cognitive Math SDK
+ * Provides hyperbolic math functions and Cognitive AI metrics for solving LLM hallucinations.
+ */
+export declare function dot(a: number[], b: number[]): number;
+export declare function normSq(v: number[]): number;
+export declare function norm(v: number[]): number;
+export declare function mobiusAdd(x: number[], y: number[], c?: number): number[];
+export declare function expMap(x: number[], v: number[], c?: number): number[];
+export declare function logMap(x: number[], y: number[], c?: number): number[];
+export declare function parallelTransport(x: number[], y: number[], v: number[], c?: number): number[];
+export declare function frechetMean(points: number[][], c?: number, maxIter?: number, tol?: number): number[];
+/** Computes the Minkowski inner product (Lorentz product) between two vectors. */
+export declare function lorentzProduct(u: number[], v: number[]): number;
+/** Computes the Lorentz distance between two points on the hyperboloid. */
+export declare function lorentzDist(u: number[], v: number[]): number;
+/** Converts a point from the Lorentz model (Hyperboloid) to the Poincaré Ball model (129 -> 128). */
+export declare function lorentzToPoincare(x: number[]): number[];
+/** Converts a point from the Poincaré Ball model to the Lorentz model (128 -> 129). */
+export declare function poincareToLorentz(p: number[]): number[];
+/** Ensures a vector satisfies the Lorentz constraint -x0^2 + |x|^2 = -1 (stabilization). */
+export declare function projectToHyperboloid(v: number[]): number[];
+/**
+ * Calculates the spatial entropy (dispersion) of a `candidate` vector relative to its `neighbors`.
+ * Used to track LLM hallucinations (Task 2.3.1).
+ * Returns a value in [0, 1) where values approaching 1 imply high chaos (hallucination).
+ */
+export declare function localEntropy(candidate: number[], neighbors: number[][], c?: number): number;
+/**
+ * Evaluates if a trajectory of vectors (e.g. Chain of Thought) converges to an attractor.
+ * Calculates the average energy derivative (Lyapunov function derivative).
+ * Negative values indicate convergence (stable), positive indicate divergence (chaos/hallucination).
+ */
+export declare function lyapunovConvergence(trajectory: number[][], c?: number): number;
+/**
+ * Extrapolates the trajectory in linear space (Koopman linearization) by tracking the
+ * shift vector from `past` to `current` and projecting it forward.
+ */
+export declare function koopmanExtrapolate(past: number[], current: number[], steps: number, c?: number): number[];
+/**
+ * Resonates a thought vector towards a global context vector (Phase-Locked Loop context synchronization).
+ * Pulls the thought towards the context along the geodesic by `resonanceFactor` [0, 1].
+ */
+export declare function contextResonance(thought: number[], globalContext: number[], resonanceFactor: number, c?: number): number[];