hyperspace-sdk-ts 3.1.0 → 3.1.2

package/README.md

@@ -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)}`);
 }
 ```
 
@@ -145,6 +167,69 @@ 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.
+
+```ts
+// Hybrid Search (Semantic Vector + BM25 Lexical)
+const results = await client.search([0.1, -0.2, 0.5], 10, "coll", {
+  hybridQuery: "hybrid search implementation",
+  hybridAlpha: 0.7, // 70% vector weight
+  bm25: {
+    method: "bm25plus",
+    language: "english"
+  }
+});
+
+// Or Pure Lexical Search via searchText
+const lexicalResults = await client.searchText("full-text query", 10, "coll", {
+  bm25: { method: "lucene" }
+});
 ```
 
 ### `searchBatch(vectors, topK, collection?)`
@@ -223,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.2)
+
+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`)
 

package/dist/client.d.ts

@@ -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;
@@ -48,6 +107,15 @@ export interface VacuumFilter {
     op: 'lt' | 'lte' | 'gt' | 'gte' | 'eq' | 'ne';
     value: number;
 }
+export interface Bm25Options {
+    method?: "bm25plus" | "bm25l" | "robertson" | "lucene" | "atire";
+    k1?: number;
+    b?: number;
+    delta?: number;
+    language?: string;
+    ngrams?: number;
+    fusionMethod?: "rrf" | "weighted";
+}
 export type EventTypeName = 'insert' | 'delete';
 export interface SubscribeOptions {
     types?: EventTypeName[];
@@ -69,20 +137,33 @@ export declare const HyperbolicMath: {
 export declare class HyperspaceClient {
     private client;
     private metadata;
+    private host;
+    private apiKey?;
+    private userId?;
     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>;
+    createCollection(name: string, schema: CollectionSchema): 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(vector: number[] | Float32Array | Float64Array, id: number, meta?: {
+    insert(id: number, vector: number[] | Float32Array | Float64Array, meta?: {
         [key: string]: string;
     }, collection?: string, durability?: DurabilityLevel, typedMetadata?: {
         [key: string]: TypedMetadataValue;
-    }): Promise<boolean>;
-    insertText(text: string, id: number, meta?: {
+    }, payload?: Uint8Array): Promise<boolean>;
+    insertText(id: number, text: string, meta?: {
         [key: string]: string;
     }, collection?: string, durability?: DurabilityLevel): Promise<boolean>;
     vectorize(text: string, metric?: string): Promise<number[]>;
@@ -97,12 +178,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<{
@@ -125,5 +221,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;
 }