@almadar/std 16.245.0 → 16.246.1

package/dist/behaviors/knob-embeddings.d.ts

@@ -15,11 +15,15 @@
  *
  * @packageDocumentation
  */
+/** Each knob's vector as int8, all views over one shared buffer — the on-disk
+ *  bytes, never widened to a float per dimension (that was 8× the memory and
+ *  OOM-killed the builder server). The per-vector scale is dropped, so a
+ *  vector here is a direction: compare it with cosine similarity only. */
 interface KnobEmbeddingsManifest {
     version: string;
     model: string;
     dimensions: number;
-    vectors: Record<string, ReadonlyArray<number>>;
+    vectors: Readonly<Record<string, Int8Array>>;
 }
 /** Int8-quantized vector: `d` = base64 of one signed byte per dimension,
  *  `s` = per-vector max-abs scale; value = byte × s ÷ 127. Landed when the
@@ -43,6 +47,16 @@ interface StoredKnobEmbeddingsFile {
     table?: StoredKnobVector[];
     keys?: Record<string, number>;
 }
+/**
+ * Decode a parsed `knob-embeddings.json` into int8 vectors over one buffer
+ * sized (stored vectors × dimensions). Interned table entries are written
+ * once and shared by every key that points at them. Returns `null` for a
+ * file missing its model, dimensions or vectors, or holding a vector whose
+ * length is not `dimensions`.
+ */
+declare function decodeKnobEmbeddingsFile(parsed: Partial<StoredKnobEmbeddingsFile>): KnobEmbeddingsManifest | null;
+/** Read and decode a `knob-embeddings.json` at `path`; `null` when it is missing or invalid. */
+declare function readKnobEmbeddingsFile(path: string): Promise<KnobEmbeddingsManifest | null>;
 /**
  * Return the typed knob embeddings manifest. Returns `null` when the
  * JSON sidecar is missing (older std checkout, or a dev build with
@@ -51,4 +65,4 @@ interface StoredKnobEmbeddingsFile {
  */
 declare function getKnobEmbeddings(): Promise<KnobEmbeddingsManifest | null>;
 
-export { type KnobEmbeddingsManifest, type QuantizedKnobVector, type StoredKnobEmbeddingsFile, type StoredKnobVector, getKnobEmbeddings };
+export { type KnobEmbeddingsManifest, type QuantizedKnobVector, type StoredKnobEmbeddingsFile, type StoredKnobVector, decodeKnobEmbeddingsFile, getKnobEmbeddings, readKnobEmbeddingsFile };

package/dist/behaviors/knob-embeddings.js

@@ -23,29 +23,56 @@ async function resolveStdDataDirUncached() {
 
 // behaviors/knob-embeddings.ts
 var pending2 = null;
-function decodeVector(stored) {
-  if (!("d" in stored)) return stored;
-  const bytes = Buffer.from(stored.d, "base64");
-  const out = new Array(bytes.length);
-  for (let i = 0; i < bytes.length; i++) {
-    out[i] = bytes.readInt8(i) * stored.s / 127;
+function writeVector(stored, slot) {
+  if ("d" in stored) {
+    const bytes = Buffer.from(stored.d, "base64");
+    if (bytes.length !== slot.length) return false;
+    slot.set(new Int8Array(bytes.buffer, bytes.byteOffset, bytes.length));
+    return true;
   }
-  return out;
+  if (stored.length !== slot.length) return false;
+  let maxAbs = 0;
+  for (const v of stored) maxAbs = Math.max(maxAbs, Math.abs(v));
+  for (let i = 0; i < stored.length; i++) {
+    slot[i] = maxAbs === 0 ? 0 : Math.round(stored[i] * 127 / maxAbs);
+  }
+  return true;
 }
-function reconstructVectors(parsed) {
+function decodeKnobEmbeddingsFile(parsed) {
+  const interned = typeof parsed?.table === "object" && typeof parsed?.keys === "object";
+  const nonInterned = typeof parsed?.vectors === "object" && parsed.vectors !== null;
+  if (typeof parsed?.model !== "string" || typeof parsed?.dimensions !== "number" || !interned && !nonInterned) {
+    return null;
+  }
+  const dims = parsed.dimensions;
+  const stored = interned ? parsed.table ?? [] : Object.values(parsed.vectors ?? {});
+  const backing = new Int8Array(stored.length * dims);
+  const slots = [];
+  for (let i = 0; i < stored.length; i++) {
+    const slot = backing.subarray(i * dims, (i + 1) * dims);
+    if (!writeVector(stored[i], slot)) return null;
+    slots.push(slot);
+  }
   const vectors = {};
-  if (parsed.table && parsed.keys) {
-    const decoded = parsed.table.map(decodeVector);
-    for (const [key, idx] of Object.entries(parsed.keys)) {
-      const vec = decoded[idx];
-      if (vec) vectors[key] = vec;
+  if (interned) {
+    for (const [key, idx] of Object.entries(parsed.keys ?? {})) {
+      const slot = slots[idx];
+      if (slot) vectors[key] = slot;
     }
-    return vectors;
+  } else {
+    Object.keys(parsed.vectors ?? {}).forEach((key, i) => {
+      vectors[key] = slots[i];
+    });
   }
-  for (const [key, stored] of Object.entries(parsed.vectors ?? {})) {
-    vectors[key] = decodeVector(stored);
+  return { version: parsed.version ?? "", model: parsed.model, dimensions: dims, vectors };
+}
+async function readKnobEmbeddingsFile(path) {
+  try {
+    const { readFileSync } = await import('fs');
+    return decodeKnobEmbeddingsFile(JSON.parse(readFileSync(path, "utf-8")));
+  } catch {
+    return null;
   }
-  return vectors;
 }
 function loadManifest() {
   pending2 ?? (pending2 = loadManifestUncached().then((m) => {
@@ -55,29 +82,11 @@ function loadManifest() {
   return pending2;
 }
 async function loadManifestUncached() {
-  try {
-    const { readFileSync } = await import('fs');
-    const { resolve } = await import('path');
-    const dir = await resolveStdDataDir();
-    const raw = readFileSync(resolve(dir, "knob-embeddings.json"), "utf-8");
-    const parsed = JSON.parse(raw);
-    const interned = typeof parsed?.table === "object" && typeof parsed?.keys === "object";
-    const nonInterned = typeof parsed?.vectors === "object" && parsed.vectors !== null;
-    if (typeof parsed?.model !== "string" || typeof parsed?.dimensions !== "number" || !interned && !nonInterned) {
-      return null;
-    }
-    return {
-      version: parsed.version,
-      model: parsed.model,
-      dimensions: parsed.dimensions,
-      vectors: reconstructVectors(parsed)
-    };
-  } catch {
-    return null;
-  }
+  const { resolve } = await import('path');
+  return readKnobEmbeddingsFile(resolve(await resolveStdDataDir(), "knob-embeddings.json"));
 }
 async function getKnobEmbeddings() {
   return loadManifest();
 }
 
-export { getKnobEmbeddings };
+export { decodeKnobEmbeddingsFile, getKnobEmbeddings, readKnobEmbeddingsFile };