hyperspace-sdk-ts 3.1.1 → 3.1.3

package/README.md

@@ -1,6 +1,6 @@
 # HyperspaceDB TypeScript SDK
 
-Official TypeScript client for HyperspaceDB gRPC API v3.1.0.
+Official TypeScript client for HyperspaceDB gRPC API v3.1.1.
 
 Use this SDK for:
 - collection lifecycle management
@@ -8,8 +8,14 @@ Use this SDK for:
 - high-throughput batched search (`searchBatch`)
 - bulk insertion (`batchInsert`)
 - advanced filtering and hybrid search
+- recursive logical filters (`AND`, `OR`, `NOT`)
+- bulk point retrieval (`getPoints`)
+- metadata updates (`updatePayload`)
+- paginated scanning (`scroll`)
+- filtered point counting (`count`)
+- health monitoring (`healthCheck`)
 - typed metadata (`string | number | boolean`)
-- graph traversal APIs (`getNode`, `getNeighbors`, `getConceptParents`, `traverse`, `findSemanticClusters`)
+- graph traversal APIs (`getNode`, `getNeighbors`, `getSubsumptionTree`, `getConceptParents`, `traverse`, `exploreGraph`, `findSemanticClusters`)
 - rebuild with metadata pruning (`rebuildIndexWithFilter`)
 - multi-tenant authentication headers (`x-api-key`, `x-hyperspace-user-id`)
 
@@ -34,7 +40,12 @@ async function main() {
   const collection = "docs_ts";
 
   await client.deleteCollection(collection).catch(() => {});
-  await client.createCollection(collection, 3, "cosine");
+  await client.createCollection(collection, {
+    components: [
+      { name: "primary", metric: "cosine", full_dimension: 3, weight: 1.0 }
+    ],
+    cascade_pipeline: []
+  });
 
   await client.insert(1, [0.1, 0.2, 0.3], { source: "demo" }, collection);
   await client.insert(2, [0.2, 0.1, 0.4], { source: "demo" }, collection);
@@ -59,11 +70,22 @@ main().catch(console.error);
 - `apiKey`: optional API key
 - `userId`: optional tenant/user ID
 
-### `createCollection(name, dimension, metric)`
+### `createCollection(name, schema)`
 
-Create a new collection.
+Create a new collection using a `CollectionSchema`.
 
-- `metric`: `"l2" | "cosine" | "poincare" | "lorentz"`
+- `metric`: `"l2" | "cosine" | "poincare" | "lorentz" | "hybrid"`
+
+```ts
+await client.createCollection("my_coll", {
+  components: [
+    { name: "primary", metric: "lorentz", full_dimension: 129, weight: 1.0 }
+  ],
+  cascade_pipeline: [
+    { component_name: "primary", cutoff_dimension: 17, store_in_ram: true, rerank_top_k: 100 }
+  ]
+});
+```
 
 ### `deleteCollection(name)`
 
@@ -77,7 +99,7 @@ Returns `Promise<CollectionInfo[]>`.
 ```ts
 const collections = await client.listCollections();
 for (const col of collections) {
-  console.log(`${col.name}: dim=${col.dimension}, metric=${col.metric}, count=${col.count}`);
+  console.log(`${col.name}: count=${col.count}, schema=${JSON.stringify(col.schema)}`);
 }
 ```
 
@@ -122,9 +144,9 @@ const results = await client.searchText("How to use HyperspaceDB?", 10, "coll",
 });
 ```
 
-### Geometric Filters (New in v3.0)
+### Geometric Filters
 
-HyperspaceDB v3.0 introduces advanced spatial filters that run on the engine level:
+HyperspaceDB introduces advanced spatial filters that run on the engine level:
 
 ```ts
 // 1. Proximity Search (Ball)
@@ -145,8 +167,50 @@ const coneFilter = {
 const results = await client.search([0.1, 0.2, 0.3], 10, "coll", {
   filters: [ballFilter, boxFilter]
 });
+
+// 4. Recursive Logical Filters
+const logicFilter = {
+  and: [
+    { match: { key: "status", value: "active" } },
+    { or: [
+        { range: { key: "score", gte: 0.8 } },
+        { match: { key: "priority", value: "high" } }
+      ]
+    }
+  ]
+};
+```
+
+### `getPoints(ids, collection?)`
+
+Retrieve multiple points by their IDs.
+Returns `Promise<Point[]>`.
+
+### `updatePayload(id, metadata, collection?)`
+
+Patch metadata for an existing point.
+```ts
+await client.updatePayload(1, { status: "processed", tags: "updated" });
 ```
 
+### `scroll(limit?, offset?, filters?, collection?)`
+
+Paginated retrieval of points with optional filtering.
+```ts
+const points = await client.scroll(50, 0, [{ match: { key: "category", value: "news" } }]);
+```
+
+### `count(filters?, collection?)`
+
+Count points matching filters.
+```ts
+const total = await client.count([{ range: { key: "price", lte: 100 } }]);
+```
+
+### `healthCheck()`
+
+Check server connectivity. Returns `"ONLINE"` or throws.
+
 ### Hybrid & Lexical Search (BM25)
 
 HyperspaceDB supports combined lexical and vector ranking.
@@ -244,21 +308,47 @@ Provides advanced tools for Agentic AI, running entirely on the client side:
 import { CognitiveMath } from "hyperspace-sdk-ts";
 
 // 1. Detect Hallucinations (Entropy approaches 1.0)
-const entropy = CognitiveMath.localEntropy(candidateThought, neighbors, 1.0);
+const entropy = client.localEntropy(candidateThought, neighbors, 1.0);
 
 // 2. Proof of Convergence (Negative derivative = convergence)
-const stability = CognitiveMath.lyapunovConvergence(chainOfThought, 1.0);
+const stability = await client.getTrustScore([1, 2, 3]);
 
 // 3. Extrapolate next thought (Koopman linearization)
-const nextThought = CognitiveMath.koopmanExtrapolate(past, current, 1.0, 1.0);
+const nextThought = await client.predictMomentum([10, 11], 1.0);
 
 // 4. Phase-Locked Loop for topic tracking
 const syncedThought = CognitiveMath.contextResonance(thought, globalContext, 0.5, 1.0);
+
+// 5. Predict Semantic Relation (A + R ≈ B)
+const relation = await client.predictRelation(1, 2);
+```
+
+## Implicit Graph Engine (v3.1.1)
+
+HyperspaceDB treats your vectors as nodes in a dynamic graph. Relationships are inferred from the geometry:
+- **Lorentz / Poincare**: Hierarchy and subsumption (light cones).
+- **L2 / Cosine**: Semantic similarity and adjacency.
+
+### Subsumption Trees
+Extract directed hierarchies from Lorentz-encoded data:
+```ts
+const tree = await client.getSubsumptionTree(1, 5);
+```
+
+### Advanced Traversal
+Navigate the graph using physical kernels:
+```ts
+const results = await client.traverse({
+    startId: 1,
+    traversalMode: 2, // 0: GREEDY, 1: DIFFUSIVE, 2: MOMENTUM
+    breadthLimit: 5
+});
+```
 ```
 
 ## Embedding Pipeline (Optional)
 
-HyperspaceDB supports **per-geometry embeddings** — each geometry (`l2`, `cosine`, `poincare`, `lorentz`) can have its own backend independently.
+HyperspaceDB supports **per-geometry embeddings** — each geometry (`l2`, `cosine`, `poincare`, `lorentz`, `hybrid`) can have its own backend independently.
 
 ### Server-Side Config (`.env`)
 
@@ -330,3 +420,58 @@ const vector = await embedder.encode("my text");
 All methods reject on transport/protocol errors. Targets gRPC data plane operations.
 For control plane endpoints (`/api/*`), use regular HTTP requests to the server's HTTP port.
 
+## Zero-Knowledge Client-Side Encryption (ZK-Privacy)
+
+HyperspaceDB v3.1.1 introduces Zero-Knowledge client-side encryption (ZK-Privacy). All private data (vectors, metadata, payloads) are encrypted/obfuscated *before* they leave the client. The database server never sees the raw vectors or plaintext data, ensuring maximum security even in public or untrusted DePIN environments.
+
+### Key Features
+1. **Vector Projection**: High-dimensional vectors are projected using a deterministic orthogonal matrix (or Lorentz boost matrix for hyperbolic spaces) generated from the collection key. This preserves distances (L2, Cosine, Lorentz) while hiding the vector coordinates.
+2. **Anisotropic Noise Injection**: Injecting subtle deterministic noise into the vectors to prevent reconstruction attacks.
+3. **Payload Encryption**: Sidecar payloads are encrypted client-side using AES-256-GCM before being sent to the database.
+4. **Metadata Hashing**: Metadata keys and values are obfuscated using HMAC-SHA256.
+
+### Usage Example
+
+```ts
+import { HyperspaceClient } from "hyperspace-sdk-ts";
+
+async function main() {
+  const client = new HyperspaceClient("localhost:50051", "I_LOVE_HYPERSPACEDB");
+  
+  const collection = "encrypted_docs";
+  const secretKey = "my-super-secret-key";
+
+  // Register collection key to enable automatic client-side encryption/decryption
+  // noiseSigma defaults to 0.02 (2% anisotropic noise)
+  client.registerCollectionKey(collection, secretKey, "cosine", 0.02);
+
+  // 1. Insert vector (will be projected, noise injected, payload encrypted, metadata hashed)
+  await client.insert(
+    1, 
+    [0.1, 0.2, 0.3], 
+    { category: "confidential" }, 
+    collection,
+    undefined,
+    undefined,
+    Buffer.from("This is a highly secret document payload", "utf-8")
+  );
+
+  // 2. Search (search vector is projected and noise-injected; results are decrypted locally)
+  const results = await client.search([0.1, 0.2, 0.3], 5, collection, {
+    // Filters are automatically hashed client-side
+    filter: { category: "confidential" }
+  });
+
+  for (const res of results) {
+    console.log(`ID: ${res.id}, Distance: ${res.distance}`);
+    if (res.payload) {
+      console.log(`Decrypted Payload: ${Buffer.from(res.payload).toString("utf-8")}`);
+    }
+  }
+
+  client.close();
+}
+
+main().catch(console.error);
+```
+

package/dist/client.d.ts

@@ -1,7 +1,7 @@
 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 * as CognitiveMathExport from './math';
 export { TribunalContext } from './agents';
 export { DurabilityLevel };
 export type TypedMetadataValue = string | number | boolean;
@@ -10,11 +10,31 @@ export interface Filter {
         key: string;
         value: string;
     };
+    prefix?: {
+        key: string;
+        prefix: string;
+    };
     range?: {
         key: string;
         gte?: number;
         lte?: number;
     };
+    inCone?: {
+        axes: number[];
+        apertures: number[];
+        cen: number[];
+    };
+    inBall?: {
+        center: number[];
+        radius: number;
+    };
+    inBox?: {
+        minBounds: number[];
+        maxBounds: number[];
+    };
+    and?: Filter[];
+    or?: Filter[];
+    not?: Filter;
 }
 export interface SearchResult {
     id: number;
@@ -25,12 +45,51 @@ export interface SearchResult {
     typedMetadata: {
         [key: string]: TypedMetadataValue;
     };
+    payload?: Uint8Array;
+}
+export interface VectorComponent {
+    name: string;
+    metric: string;
+    fullDimension: number;
+    weight: number;
+}
+export interface MrlLayer {
+    componentName: string;
+    cutoffDimension: number;
+    storeInRam: boolean;
+    rerankTopK: number;
+}
+export interface CollectionSchema {
+    components: VectorComponent[];
+    cascadePipeline: MrlLayer[];
 }
 export interface CollectionInfo {
     name: string;
     count: number;
-    dimension: number;
-    metric: string;
+    schema?: CollectionSchema;
+}
+export interface CollectionStats {
+    count: number;
+    schema?: CollectionSchema;
+    indexingQueue: number;
+    diskUsageBytes: number;
+    ramUsageBytes: number;
+    activeTasks: number;
+}
+export interface SystemMetrics {
+    cpuUsage: number;
+    ramUsageMb: number;
+    totalVectors: number;
+    activeCollections: number;
+    uptimeSeconds: number;
+    networkRxBytes: number;
+    networkTxBytes: number;
+}
+export interface CollectionConfig {
+    quantizationMode?: 'NONE' | 'SCALAR_I8';
+    efSearch?: number;
+    efConstruction?: number;
+    m?: number;
 }
 export interface GraphNode {
     id: number;
@@ -78,19 +137,50 @@ export declare const HyperbolicMath: {
 export declare class HyperspaceClient {
     private client;
     private metadata;
+    private host;
+    private apiKey?;
+    private userId?;
+    embedder?: {
+        encode: (text: string) => Promise<number[]> | number[];
+    };
+    private collectionKeys;
+    private encryptionContexts;
+    private collectionMetrics;
+    private collectionNoiseSigmas;
+    private collectionSchemas;
     private static toVectorList;
     private static toProtoMetadataValue;
     private static parseTypedMetadata;
+    private toProtoFilter;
     constructor(host?: string, apiKey?: string, userId?: string);
-    createCollection(name: string, dimension: number, metric: string): Promise<boolean>;
+    registerCollectionKey(collectionName: string, key: string, metric?: string, noiseSigma?: number, schema?: CollectionSchema): void;
+    private deriveKeys;
+    private encryptPayload;
+    private decryptPayload;
+    private hashMetadataKey;
+    private hashMetadataValue;
+    private _getEncryptionContext;
+    private _projectSingleBlock;
+    private _projectCollectionVector;
+    private _encryptFilters;
+    createCollection(name: string, schema: CollectionSchema, encryptionKey?: string, noiseSigma?: number): Promise<boolean>;
     deleteCollection(name: string): Promise<boolean>;
+    freezeCollection(name: string): Promise<string>;
+    unfreezeCollection(name: string): Promise<string>;
     listCollections(): Promise<CollectionInfo[]>;
+    getPoints(ids: number[], collection?: string): Promise<{
+        id: number;
+        vector: number[];
+        metadata: {
+            [key: string]: string;
+        };
+    }[]>;
     delete(id: number, collection?: string): Promise<boolean>;
     insert(id: number, vector: number[] | Float32Array | Float64Array, meta?: {
         [key: string]: string;
     }, collection?: string, durability?: DurabilityLevel, typedMetadata?: {
         [key: string]: TypedMetadataValue;
-    }): Promise<boolean>;
+    }, payload?: Uint8Array): Promise<boolean>;
     insertText(id: number, text: string, meta?: {
         [key: string]: string;
     }, collection?: string, durability?: DurabilityLevel): Promise<boolean>;
@@ -106,15 +196,27 @@ export declare class HyperspaceClient {
         };
     }[], collection?: string, durability?: DurabilityLevel): Promise<boolean>;
     search(vector: number[] | Float32Array | Float64Array, topK: number, collection?: string, options?: {
+        filter?: {
+            [key: string]: string;
+        };
         filters?: Filter[];
         hybridQuery?: string;
         hybridAlpha?: number;
         bm25?: Bm25Options;
+        mrlDimension?: number;
+        useWasserstein?: boolean;
+        includePayload?: boolean;
+        componentWeights?: {
+            [key: string]: number;
+        };
+        useWave?: boolean;
+        restartFactor?: number;
     }): Promise<SearchResult[]>;
     searchText(text: string, topK: number, collection?: string, options?: {
         filters?: Filter[];
         bm25?: Bm25Options;
         hybridAlpha?: number;
+        includePayload?: boolean;
     }): Promise<SearchResult[]>;
     searchBatch(vectors: Array<number[] | Float32Array | Float64Array>, topK: number, collection?: string): Promise<SearchResult[][]>;
     getDigest(collection?: string): Promise<{
@@ -137,5 +239,20 @@ export declare class HyperspaceClient {
     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>;
+    getCollectionStats(name: string): Promise<CollectionStats>;
+    exists(name: string): Promise<boolean>;
+    getCacheStats(name: string): Promise<any>;
+    clearCache(name: string): Promise<boolean>;
+    updateCacheConfig(name: string, policy: string, annThreshold?: number): Promise<boolean>;
+    updateCollection(name: string, config: CollectionConfig): Promise<boolean>;
+    createSnapshot(): Promise<boolean>;
+    vacuum(): Promise<boolean>;
+    getMetrics(onData: (data: any) => void, onError?: (err: Error) => void): grpc.ClientReadableStream<any>;
+    searchMultiCollection(collections: string[], query: number[]): Promise<any>;
+    triggerReconsolidation(collection: string, targetVector: number[], learningRate?: number): Promise<boolean>;
+    getSubsumptionTree(rootId: number, maxDepth?: number, collection?: string): Promise<GraphNode[]>;
+    exploreGraph(startId: number, maxDepth?: number, maxNodes?: number, collection?: string): Promise<any>;
+    predictMomentum(trajectoryIds: number[], steps?: number, collection?: string, curvature?: number): Promise<number[]>;
+    getTrustScore(trajectoryIds: number[], collection?: string, curvature?: number): Promise<number>;
     close(): void;
 }