hyperspace-sdk-ts 3.1.6 → 3.1.7

package/README.md

@@ -42,10 +42,10 @@ async function main() {
   await client.deleteCollection(collection).catch(() => {});
   await client.createCollection(collection, {
     components: [
-      { name: "primary", metric: "cosine", full_dimension: 3, weight: 1.0 }
+      { name: "primary", metric: "cosine", fullDimension: 3, weight: 1.0 }
     ],
-    cascade_pipeline: []
-  });
+    cascadePipeline: []
+  }, '', 0.02, 'medium_plus');
 
   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);

package/dist/client.d.ts

@@ -163,7 +163,8 @@ export declare class HyperspaceClient {
     private _projectSingleBlock;
     private _projectCollectionVector;
     private _encryptFilters;
-    createCollection(name: string, schema: CollectionSchema, encryptionKey?: string, noiseSigma?: number): Promise<boolean>;
+    createCollection(name: string, schema: CollectionSchema, encryptionKey?: string, noiseSigma?: number, quantization?: string): Promise<boolean>;
+    private createCollectionGrpc;
     deleteCollection(name: string): Promise<boolean>;
     freezeCollection(name: string): Promise<string>;
     unfreezeCollection(name: string): Promise<string>;
@@ -254,5 +255,8 @@ export declare class HyperspaceClient {
     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>;
+    startRun(sessionId: string, taskDescription: string): Promise<boolean>;
+    stepRun(sessionId: string, x: number, y: number, metadata?: any): Promise<boolean>;
+    endRun(sessionId: string, status: string, finalScore?: number, lyapunovStability?: number): Promise<boolean>;
     close(): void;
 }

package/dist/client.js

@@ -298,7 +298,10 @@ class HyperspaceClient {
         this.collectionMetrics = {};
         this.collectionNoiseSigmas = {};
         this.collectionSchemas = {};
-        this.host = host;
+        const cleanHost = host.replace(/^https?:\/\//, '').replace(/\/$/, '');
+        const isSecure = cleanHost.endsWith(':443') || (!cleanHost.includes('localhost') && !cleanHost.includes('127.0.0.1') && !cleanHost.includes(':50051') && !cleanHost.includes(':50050') && cleanHost.includes('.'));
+        const formattedHost = isSecure && !cleanHost.includes(':') ? `${cleanHost}:443` : cleanHost;
+        this.host = formattedHost;
         this.apiKey = apiKey;
         this.userId = userId;
         const options = {
@@ -310,7 +313,8 @@ class HyperspaceClient {
             'grpc.http2.min_time_between_pings_ms': 10000,
             'grpc.http2.min_ping_interval_without_data_ms': 5000,
         };
-        this.client = new hyperspace_grpc_pb_1.DatabaseClient(host, grpc.credentials.createInsecure(), options);
+        const creds = isSecure ? grpc.credentials.createSsl() : grpc.credentials.createInsecure();
+        this.client = new hyperspace_grpc_pb_1.DatabaseClient(formattedHost, creds, options);
         this.metadata = new grpc.Metadata();
         if (apiKey) {
             this.metadata.add('x-api-key', apiKey);
@@ -531,11 +535,46 @@ class HyperspaceClient {
         });
     }
     // ... (create/delete unchanged) ...
-    createCollection(name, schema, encryptionKey = '', noiseSigma = 0.02) {
+    createCollection(name, schema, encryptionKey = '', noiseSigma = 0.02, quantization) {
         const metric = (schema.components && schema.components[0]) ? schema.components[0].metric : "l2";
         if (encryptionKey) {
             this.registerCollectionKey(name, encryptionKey, metric, noiseSigma, schema);
         }
+        if (quantization) {
+            const isYarSaaS = this.host.includes('yar.ink') || (!this.host.includes('localhost') && !this.host.includes('127.0.0.1'));
+            const hostOnly = this.host.split(':')[0];
+            const url = isYarSaaS ? 'https://the.yar.ink/api/collections' : `http://${hostOnly}:50050/api/collections`;
+            const comp = schema.components && schema.components[0];
+            const payload = {
+                name,
+                dimension: comp ? comp.fullDimension : 1024,
+                metric: comp ? comp.metric : "l2",
+                quantization,
+            };
+            if (schema.cascadePipeline && schema.cascadePipeline.length > 0) {
+                payload.mrl_cutoff_dimension = schema.cascadePipeline[0].cutoffDimension;
+                payload.mrl_rerank_top_k = schema.cascadePipeline[0].rerankTopK || 100;
+            }
+            return fetch(url, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    ...(this.apiKey ? { 'x-api-key': this.apiKey, 'Authorization': `Bearer ${this.apiKey}` } : {}),
+                    ...(this.userId ? { 'x-hyperspace-user-id': this.userId } : {}),
+                },
+                body: JSON.stringify(payload),
+            })
+                .then(async (r) => {
+                if (r.ok) {
+                    return true;
+                }
+                return this.createCollectionGrpc(name, schema);
+            })
+                .catch(() => this.createCollectionGrpc(name, schema));
+        }
+        return this.createCollectionGrpc(name, schema);
+    }
+    createCollectionGrpc(name, schema) {
         return new Promise((resolve, reject) => {
             const req = new hyperspace_pb_1.CreateCollectionRequest();
             req.setName(name);
@@ -549,7 +588,7 @@ class HyperspaceClient {
                 return comp;
             });
             protoSchema.setComponentsList(components);
-            const pipeline = schema.cascadePipeline.map(l => {
+            const pipeline = (schema.cascadePipeline || []).map(l => {
                 const layer = new hyperspace_pb.MrlLayer();
                 layer.setComponentName(l.componentName);
                 layer.setCutoffDimension(l.cutoffDimension);
@@ -759,19 +798,70 @@ class HyperspaceClient {
                     return reject(err);
                 resolve(resp.getSuccess());
             });
+        }).catch(async (err) => {
+            const errStr = (err ? String(err.message || '') + ' ' + String(err.details || '') : '');
+            const isUnavail = err && (err.code === 14 || err.code === 12 || err.code === 9 ||
+                errStr.includes('UNIMPLEMENTED') ||
+                errStr.includes('Embedding engine disabled') ||
+                errStr.includes('embedding model') ||
+                errStr.includes('FAILED_PRECONDITION') ||
+                errStr.includes('502') ||
+                errStr.includes('UNAVAILABLE'));
+            if (isUnavail) {
+                const vec = await this.vectorize(text, 'hybrid');
+                return this.insert(id, vec, meta, collection, durability, undefined, Buffer.from(text, 'utf-8'));
+            }
+            throw err;
         });
     }
-    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());
+    async vectorize(text, metric = 'l2') {
+        if (this.embedder) {
+            return Promise.resolve(this.embedder.encode(text));
+        }
+        try {
+            return await 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());
+                });
             });
-        });
+        }
+        catch (grpcErr) {
+            const urls = [
+                'https://the.yar.ink/v1/embeddings',
+                `http://${this.host.split(':')[0]}:8080/v1/embeddings`
+            ];
+            const apiKey = process.env.CDE_API_KEY || ((this.apiKey && this.apiKey.startsWith('sk_')) ? this.apiKey : '') || process.env.HYPERSPACE_API_KEY || '';
+            for (const url of urls) {
+                try {
+                    const res = await fetch(url, {
+                        method: 'POST',
+                        headers: {
+                            'Content-Type': 'application/json',
+                            'Authorization': `Bearer ${apiKey}`
+                        },
+                        body: JSON.stringify({
+                            model: 'v5_Light',
+                            input: text
+                        })
+                    });
+                    if (res.ok) {
+                        const json = await res.json();
+                        if (json.data && json.data[0] && json.data[0].embedding) {
+                            return json.data[0].embedding;
+                        }
+                    }
+                }
+                catch (httpErr) {
+                    // try next
+                }
+            }
+            throw grpcErr;
+        }
     }
     batchInsert(items, collection = '', durability = hyperspace_pb_1.DurabilityLevel.DEFAULT_LEVEL) {
         return new Promise((resolve, reject) => {
@@ -985,6 +1075,20 @@ class HyperspaceClient {
                 });
                 resolve(results);
             });
+        }).catch(async (err) => {
+            const errStr = (err ? String(err.message || '') + ' ' + String(err.details || '') : '');
+            const isUnavail = err && (err.code === 14 || err.code === 12 || err.code === 9 ||
+                errStr.includes('UNIMPLEMENTED') ||
+                errStr.includes('Embedding engine disabled') ||
+                errStr.includes('embedding model') ||
+                errStr.includes('FAILED_PRECONDITION') ||
+                errStr.includes('502') ||
+                errStr.includes('UNAVAILABLE'));
+            if (isUnavail) {
+                const vec = await this.vectorize(text, 'hybrid');
+                return this.search(vec, topK, collection, options);
+            }
+            throw err;
         });
     }
     searchBatch(vectors, topK, collection = '') {
@@ -1496,6 +1600,73 @@ class HyperspaceClient {
             return 1.0;
         }
     }
+    async startRun(sessionId, taskDescription) {
+        const ip = this.host.split(':')[0];
+        const url = `http://${ip}:50050/api/admin/runs/start`;
+        const headers = { 'Content-Type': 'application/json' };
+        if (this.apiKey)
+            headers['x-api-key'] = this.apiKey;
+        if (this.userId)
+            headers['x-hyperspace-user-id'] = this.userId;
+        const res = await fetch(url, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify({
+                session_id: sessionId,
+                task_description: taskDescription
+            })
+        });
+        if (!res.ok) {
+            throw new Error(`Failed to start run: ${res.statusText} (${await res.text()})`);
+        }
+        return res.status === 200;
+    }
+    async stepRun(sessionId, x, y, metadata) {
+        const ip = this.host.split(':')[0];
+        const url = `http://${ip}:50050/api/admin/runs/step`;
+        const headers = { 'Content-Type': 'application/json' };
+        if (this.apiKey)
+            headers['x-api-key'] = this.apiKey;
+        if (this.userId)
+            headers['x-hyperspace-user-id'] = this.userId;
+        const res = await fetch(url, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify({
+                session_id: sessionId,
+                x,
+                y,
+                metadata
+            })
+        });
+        if (!res.ok) {
+            throw new Error(`Failed to record run step: ${res.statusText} (${await res.text()})`);
+        }
+        return res.status === 200;
+    }
+    async endRun(sessionId, status, finalScore, lyapunovStability) {
+        const ip = this.host.split(':')[0];
+        const url = `http://${ip}:50050/api/admin/runs/end`;
+        const headers = { 'Content-Type': 'application/json' };
+        if (this.apiKey)
+            headers['x-api-key'] = this.apiKey;
+        if (this.userId)
+            headers['x-hyperspace-user-id'] = this.userId;
+        const res = await fetch(url, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify({
+                session_id: sessionId,
+                status,
+                final_score: finalScore,
+                lyapunov_stability: lyapunovStability
+            })
+        });
+        if (!res.ok) {
+            throw new Error(`Failed to end run: ${res.statusText} (${await res.text()})`);
+        }
+        return res.status === 200;
+    }
     close() {
         this.client.close();
     }

package/dist/math.d.ts

@@ -26,10 +26,11 @@ export declare function projectToHyperboloid(v: number[]): number[];
  * 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;
+/** Computes hybrid distance (Lorentz H³² over 0..33 + Euclidean over 33..801). */
+export declare function hybridDistance(u: number[], v: 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).
+ * Evaluates if a trajectory of vectors (e.g. Chain of Thought) converges toward a solution goal attractor.
+ * Negative values indicate distance contraction (stable convergence), positive indicate goal divergence (hallucination).
  */
 export declare function lyapunovConvergence(trajectory: number[][], c?: number): number;
 /**

package/dist/math.js

@@ -18,6 +18,7 @@ exports.lorentzToPoincare = lorentzToPoincare;
 exports.poincareToLorentz = poincareToLorentz;
 exports.projectToHyperboloid = projectToHyperboloid;
 exports.localEntropy = localEntropy;
+exports.hybridDistance = hybridDistance;
 exports.lyapunovConvergence = lyapunovConvergence;
 exports.koopmanExtrapolate = koopmanExtrapolate;
 exports.contextResonance = contextResonance;
@@ -199,22 +200,48 @@ function localEntropy(candidate, neighbors, c = 1.0) {
     const meanDeviation = totalDeviation / neighbors.length;
     return 1.0 - Math.exp(-meanDeviation);
 }
+/** Computes hybrid distance (Lorentz H³² over 0..33 + Euclidean over 33..801). */
+function hybridDistance(u, v) {
+    if (u.length >= 801 && v.length >= 801) {
+        let mink = -u[0] * v[0];
+        for (let i = 1; i < 33; i++)
+            mink += u[i] * v[i];
+        const lorDist = Math.acosh(Math.max(1.0, -mink));
+        let eucSq = 0.0;
+        for (let i = 33; i < u.length; i++) {
+            const diff = u[i] - v[i];
+            eucSq += diff * diff;
+        }
+        return lorDist + Math.sqrt(eucSq);
+    }
+    else {
+        let sumSq = 0.0;
+        for (let i = 0; i < u.length; i++) {
+            const diff = u[i] - v[i];
+            sumSq += diff * diff;
+        }
+        return Math.sqrt(sumSq);
+    }
+}
 /**
- * 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).
+ * Evaluates if a trajectory of vectors (e.g. Chain of Thought) converges toward a solution goal attractor.
+ * Negative values indicate distance contraction (stable convergence), positive indicate goal divergence (hallucination).
  */
 function lyapunovConvergence(trajectory, c = 1.0) {
     if (trajectory.length < 3)
         throw new Error("Need at least 3 points");
-    const attractor = frechetMean(trajectory, c, 32, 1e-6);
-    let vDiffSum = 0.0;
-    for (let i = 0; i < trajectory.length - 1; i++) {
-        const vt0 = norm(logMap(attractor, trajectory[i], c));
-        const vt1 = norm(logMap(attractor, trajectory[i + 1], c));
-        vDiffSum += (vt1 - vt0);
+    const goal = trajectory[trajectory.length - 1];
+    let lyapSum = 0.0;
+    let count = 0;
+    for (let i = 0; i < trajectory.length - 2; i++) {
+        const d0 = hybridDistance(trajectory[i], goal);
+        const d1 = hybridDistance(trajectory[i + 1], goal);
+        if (d0 > 1e-12) {
+            lyapSum += (d1 - d0) / d0;
+            count++;
+        }
     }
-    return vDiffSum / (trajectory.length - 1);
+    return count > 0 ? lyapSum / count : 0.0;
 }
 /**
  * Extrapolates the trajectory in linear space (Koopman linearization) by tracking the