hyperspace-sdk-ts 2.2.0 → 3.0.0

package/README.md

@@ -1,6 +1,6 @@
 # HyperspaceDB TypeScript SDK
 
-Official TypeScript client for HyperspaceDB gRPC API.
+Official TypeScript client for HyperspaceDB gRPC API (v3.0.0-alpha.2).
 
 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
@@ -57,7 +60,7 @@ main().catch(console.error);
 
 Create a new collection.
 
-- `metric`: `"l2" | "cosine" | "poincare"`
+- `metric`: `"l2" | "cosine" | "poincare" | "lorentz"`
 
 ### `deleteCollection(name)`
 
@@ -66,6 +69,16 @@ 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.
+
+### `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?)`
 
@@ -79,17 +92,17 @@ await client.batchInsert([
 
 ### `search(vector, topK, collection?, options?)`
 
-Run nearest-neighbor search. 
-Options include `filters`, `hybridQuery`, and `hybridAlpha`.
+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" } }
+  ]
 });
 ```
 
@@ -97,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.
@@ -105,10 +126,142 @@ 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.
+
+### `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.
+
+```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?)`
+
+### `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,10 @@
-import { DurabilityLevel } from './proto/hyperspace_pb';
+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 {
     match?: {
         key: string;
@@ -17,6 +22,9 @@ export interface SearchResult {
     metadata: {
         [key: string]: string;
     };
+    typedMetadata: {
+        [key: string]: TypedMetadataValue;
+    };
 }
 export interface GraphNode {
     id: number;
@@ -25,35 +33,73 @@ 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, 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;
         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[];
         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;
         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 +110,8 @@ 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>;
+    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;
 }