hyperspace-sdk-ts 2.2.1 → 3.0.0

package/README.md

@@ -1,6 +1,6 @@
 # HyperspaceDB TypeScript SDK
 
-Official TypeScript client for HyperspaceDB gRPC API (v2.2.1).
+Official TypeScript client for HyperspaceDB gRPC API (v3.0.0-alpha.2).
 
 Use this SDK for:
 - collection lifecycle management
@@ -60,7 +60,7 @@ main().catch(console.error);
 
 Create a new collection.
 
-- `metric`: `"l2" | "cosine" | "poincare"`
+- `metric`: `"l2" | "cosine" | "poincare" | "lorentz"`
 
 ### `deleteCollection(name)`
 
@@ -71,6 +71,15 @@ Delete collection and all its data.
 Insert one vector. Accepts `number[]`, `Float32Array`, `Float64Array`.
 Optional `typedMetadata` supports typed values for range/boolean filters.
 
+### `insertText(id, text, meta?, collection?, durability?)`
+
+Insert text to be vectorized and stored on the server side (Server-Side Embedding).
+
+### `vectorize(text, metric?)`
+
+Convert text to a dense vector using the server's embedding engine.
+- `metric`: defaults to `"l2"`.
+
 ### `batchInsert(items, collection?, durability?)`
 
 Efficient bulk insertion.
@@ -83,18 +92,17 @@ await client.batchInsert([
 
 ### `search(vector, topK, collection?, options?)`
 
-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.
+Run nearest-neighbor search with a raw vector. 
+
+### `searchText(text, topK, collection?, options?)`
+
+Run nearest-neighbor search using text input. The text is vectorized on the server before searching.
 
 ```ts
-const results = await client.search(vector, 10, "coll", {
+const results = await client.searchText("How to use HyperspaceDB?", 10, "coll", {
   filters: [
-    { match: { key: "category", value: "electronics" } },
-    { range: { key: "price", gte: 100, lte: 500 } }
-  ],
-  hybridQuery: "latest smartphone",
-  hybridAlpha: 0.5
+    { match: { key: "category", value: "docs" } }
+  ]
 });
 ```
 
@@ -102,6 +110,14 @@ const results = await client.search(vector, 10, "coll", {
 
 Run multiple searches in one gRPC request to reduce RPC overhead.
 
+### `searchWasserstein(vector, topK, collection?)`
+
+Execute O(N) Cross-Feature Match (1D L1 CDF distance) instead of generic Poincare/L2. Ideal for comparing distributions.
+
+### `searchMultiCollection(vector, collections, topK)`
+
+Submit one vector and run parallel searches across multiple collections in one batch request (e.g. for Multi-Geometry benchmarks comparing L2, Cosine, Poincare, Lorentz).
+
 ### `getDigest(collection?)`
 
 Retrieve collection stats and logical clock.
@@ -126,6 +142,10 @@ const stream = client.subscribeToEvents(
 
 Trigger index rebuild/vacuum for a collection.
 
+### `triggerReconsolidation(collection, targetVector, learningRate)`
+
+Trigger AI Sleep Mode natively: updates parameters using Flow Matching (Riemannian SGD) instantly via the database engine.
+
 ### `rebuildIndexWithFilter(collection, filter)`
 
 Rebuild with metadata pruning for sleep/reconsolidation workflows.
@@ -154,10 +174,94 @@ Provided utilities:
 - `parallelTransport(x, y, v, c?)`
 - `frechetMean(points, c?, maxIter?, tol?)`
 
+### `CognitiveMath` (Spatial AI Engine)
+
+Provides advanced tools for Agentic AI, running entirely on the client side:
+
+```ts
+import { CognitiveMath } from "hyperspace-sdk-ts";
+
+// 1. Detect Hallucinations (Entropy approaches 1.0)
+const entropy = CognitiveMath.localEntropy(candidateThought, neighbors, 1.0);
+
+// 2. Proof of Convergence (Negative derivative = convergence)
+const stability = CognitiveMath.lyapunovConvergence(chainOfThought, 1.0);
+
+// 3. Extrapolate next thought (Koopman linearization)
+const nextThought = CognitiveMath.koopmanExtrapolate(past, current, 1.0, 1.0);
+
+// 4. Phase-Locked Loop for topic tracking
+const syncedThought = CognitiveMath.contextResonance(thought, globalContext, 0.5, 1.0);
+```
+
+## Embedding Pipeline (Optional)
+
+HyperspaceDB supports **per-geometry embeddings** — each geometry (`l2`, `cosine`, `poincare`, `lorentz`) can have its own backend independently.
+
+### Server-Side Config (`.env`)
+
+```env
+HYPERSPACE_EMBED=true
+
+# Cosine via OpenAI
+HS_EMBED_COSINE_PROVIDER=openai
+HS_EMBED_COSINE_EMBED_MODEL=text-embedding-3-small
+HS_EMBED_COSINE_API_KEY=sk-...
+
+# Poincaré via HuggingFace Hub (downloads model.onnx + tokenizer.json)
+HS_EMBED_POINCARE_PROVIDER=huggingface
+HS_EMBED_POINCARE_HF_MODEL_ID=your-org/cde-spatial-poincare-128d
+HS_EMBED_POINCARE_DIM=128
+HF_TOKEN=hf_...          # Optional — for gated/private models
+
+# Lorentz via local ONNX file
+HS_EMBED_LORENTZ_PROVIDER=local
+HS_EMBED_LORENTZ_MODEL_PATH=./models/lorentz_128d.onnx
+HS_EMBED_LORENTZ_TOKENIZER_PATH=./models/lorentz_128d_tokenizer.json
+HS_EMBED_LORENTZ_DIM=129  # spatial_dim + 1 for time component
+```
+
+### Client-Side Embedder
+
+```ts
+import { OpenAIEmbedder, HuggingFaceEmbedder, LocalOnnxEmbedder } from "hyperspace-sdk-ts";
+
+// OpenAI API
+const embedder = new OpenAIEmbedder({ apiKey: "sk-...", model: "text-embedding-3-small" });
+const vector = await embedder.encode("my text");
+
+// HuggingFace Hub — downloads model.onnx + tokenizer.json on first use
+const embedder = new HuggingFaceEmbedder({
+  modelId: "BAAI/bge-small-en-v1.5",
+  geometry: "cosine",
+  hfToken: process.env.HF_TOKEN,  // Optional
+});
+const vector = await embedder.encode("my text");
+
+// Local ONNX file
+const embedder = new LocalOnnxEmbedder({
+  modelPath: "./models/bge-small.onnx",
+  tokenizerPath: "./models/bge-small-tokenizer.json",
+  geometry: "cosine",
+});
+const vector = await embedder.encode("my text");
+```
+
+### Supported Geometries
+
+| Geometry | Post-Processing | Best For |
+|---|---|---|
+| `cosine` | Unit normalize | Semantic similarity |
+| `l2` | Unit normalize | Euclidean distance tasks |
+| `poincare` | Clamp to unit ball | Hierarchical data (trees, ontologies) |
+| `lorentz` | None (model handles it) | Mixed hierarchical + semantic |
+
 ## Performance Notes
 
 - Prefer `searchBatch` and `batchInsert` for throughput-heavy services.
 - Reuse one client instance per process or worker.
+- For `lorentz` geometry, dimension = spatial_dim + 1 (the time component x₀).
+- For `huggingface` provider, models are cached locally after first download.
 
 ## Error Handling
 

package/dist/agents.d.ts

@@ -0,0 +1,16 @@
+import { HyperspaceClient } from './client';
+export declare class TribunalContext {
+    private client;
+    private collectionName;
+    /**
+     * Heterogeneous Tribunal Framework (Tribunal Router).
+     * Evaluates LLM claims by verifying geometric/logical paths between concepts
+     * using the HyperspaceDB Graph Traversal API.
+     */
+    constructor(client: HyperspaceClient, collectionName: string);
+    /**
+     * Calculates Graph-Geometric Trust Score by traversing from Concept A to Concept B.
+     * Returns a score in [0.0, 1.0]. A score of 0.0 means disconnected (Hallucination).
+     */
+    evaluateClaim(conceptAId: number, conceptBId: number, maxDepth?: number, maxNodes?: number): Promise<number>;
+}

package/dist/agents.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TribunalContext = void 0;
+class TribunalContext {
+    /**
+     * Heterogeneous Tribunal Framework (Tribunal Router).
+     * Evaluates LLM claims by verifying geometric/logical paths between concepts
+     * using the HyperspaceDB Graph Traversal API.
+     */
+    constructor(client, collectionName) {
+        this.client = client;
+        this.collectionName = collectionName;
+    }
+    /**
+     * Calculates Graph-Geometric Trust Score by traversing from Concept A to Concept B.
+     * Returns a score in [0.0, 1.0]. A score of 0.0 means disconnected (Hallucination).
+     */
+    async evaluateClaim(conceptAId, conceptBId, maxDepth = 5, maxNodes = 256) {
+        if (conceptAId === conceptBId)
+            return 1.0;
+        try {
+            // Extract local geometric subgraph via the Graph Traversal API
+            const nodes = await this.client.traverse(conceptAId, 0, maxDepth, maxNodes, this.collectionName);
+            if (!nodes || nodes.length === 0)
+                return 0.0;
+            const adjList = {};
+            for (const node of nodes) {
+                adjList[node.id] = node.neighbors;
+            }
+            if (!adjList[conceptAId])
+                return 0.0;
+            // Perform BFS to find the shortest geometric path distance
+            const queue = [[conceptAId, 0]];
+            const visited = new Set([conceptAId]);
+            let pathLength = -1;
+            while (queue.length > 0) {
+                const [current, depth] = queue.shift();
+                if (current === conceptBId) {
+                    pathLength = depth;
+                    break;
+                }
+                if (depth >= maxDepth)
+                    continue;
+                const neighbors = adjList[current] || [];
+                for (const neighbor of neighbors) {
+                    if (!visited.has(neighbor)) {
+                        visited.add(neighbor);
+                        queue.push([neighbor, depth + 1]);
+                    }
+                }
+            }
+            if (pathLength === -1)
+                return 0.0; // No logical pathway
+            // Geometric Trust Score decays smoothly based on shortest path
+            const trustScore = Math.exp(-0.4 * pathLength);
+            return trustScore;
+        }
+        catch (e) {
+            console.error("TribunalContext evaluateClaim Error:", e);
+            return 0.0;
+        }
+    }
+}
+exports.TribunalContext = TribunalContext;

package/dist/client.d.ts

@@ -1,5 +1,8 @@
 import * as grpc from '@grpc/grpc-js';
 import { DurabilityLevel, EventMessage } from './proto/hyperspace_pb';
+import * as hyperspace_pb from './proto/hyperspace_pb';
+export * as CognitiveMath from './math';
+export { TribunalContext } from './agents';
 export { DurabilityLevel };
 export type TypedMetadataValue = string | number | boolean;
 export interface Filter {
@@ -67,6 +70,10 @@ export declare class HyperspaceClient {
     }, collection?: string, durability?: DurabilityLevel, typedMetadata?: {
         [key: string]: TypedMetadataValue;
     }): Promise<boolean>;
+    insertText(id: number, text: string, meta?: {
+        [key: string]: string;
+    }, collection?: string, durability?: DurabilityLevel): Promise<boolean>;
+    vectorize(text: string, metric?: string): Promise<number[]>;
     batchInsert(items: {
         id: number;
         vector: number[] | Float32Array | Float64Array;
@@ -82,6 +89,9 @@ export declare class HyperspaceClient {
         hybridQuery?: string;
         hybridAlpha?: number;
     }): Promise<SearchResult[]>;
+    searchText(text: string, topK: number, collection?: string, options?: {
+        filters?: Filter[];
+    }): Promise<SearchResult[]>;
     searchBatch(vectors: Array<number[] | Float32Array | Float64Array>, topK: number, collection?: string): Promise<SearchResult[][]>;
     getDigest(collection?: string): Promise<{
         logicalClock: number;
@@ -101,5 +111,7 @@ export declare class HyperspaceClient {
     }): 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>;
+    syncHandshake(collection: string, clientBuckets: number[], clientLogicalClock?: number, clientCount?: number): Promise<hyperspace_pb.SyncHandshakeResponse.AsObject>;
+    syncPull(collection: string, bucketIndices: number[], onData: (data: hyperspace_pb.SyncVectorData.AsObject) => void, onError?: (err: Error) => void): grpc.ClientReadableStream<hyperspace_pb.SyncVectorData>;
     close(): void;
 }

package/dist/client.js

@@ -33,12 +33,15 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.HyperspaceClient = exports.HyperbolicMath = 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)
@@ -264,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();
@@ -355,6 +389,64 @@ class HyperspaceClient {
             });
         });
     }
+    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);
+            });
+        });
+    }
     searchBatch(vectors, topK, collection = '') {
         return new Promise((resolve, reject) => {
             const req = new hyperspace_pb_1.BatchSearchRequest();
@@ -615,6 +707,36 @@ class HyperspaceClient {
         }
         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[];