@anuma/sdk 7.1.0 → 7.2.0

package/dist/server/index.mjs

@@ -30252,10 +30252,18 @@ function admitVaultProjections(queryEmbedding, vectored, k) {
 }
 async function buildProjectedCorpus(query, vaultCtx, embeddingOptions, cache, queryOpts, opts) {
   let rowsDecrypted = 0;
+  const keysStart = nowMs();
   const keys = await getVaultCandidateKeysOp(
     vaultCtx,
     Object.keys(queryOpts).length > 0 ? queryOpts : void 0
   );
+  const corpusStats = {
+    keysMs: nowMs() - keysStart,
+    embeddingsFetchMs: 0,
+    rowsFetchMs: 0,
+    cacheHits: 0,
+    cacheMisses: 0
+  };
   const hydrateOpts = queryOpts.includeArchived ? { includeArchived: true } : void 0;
   const vaultSize = keys.length;
   if (keys.length === 0) {
@@ -30265,7 +30273,8 @@ async function buildProjectedCorpus(query, vaultCtx, embeddingOptions, cache, qu
       queryEmbedding: [],
       vaultSize: 0,
       laneEmbedFailed: false,
-      rowsDecrypted: 0
+      rowsDecrypted: 0,
+      corpusStats
     };
   }
   const queryEmbedStart = nowMs();
@@ -30287,16 +30296,20 @@ async function buildProjectedCorpus(query, vaultCtx, embeddingOptions, cache, qu
     for (const k2 of keys) {
       const cached = cachedRowVector(cache, k2.uniqueId, k2.updatedAt);
       if (cached && cached.length === queryEmbedding.length) {
+        corpusStats.cacheHits++;
         vectored.push({ uniqueId: k2.uniqueId, embedding: cached, updatedAt: k2.updatedAt });
         continue;
       }
+      corpusStats.cacheMisses++;
       const modelCompatible = (k2.embeddingModel ?? currentModel) === currentModel;
       if (modelCompatible) missIds.push(k2.uniqueId);
       else noVectorIds.push(k2.uniqueId);
     }
   }
   if (missIds.length > 0) {
+    const embeddingsStart = nowMs();
     const rows = await getVaultEmbeddingsByIdsOp(vaultCtx, missIds, hydrateOpts);
+    corpusStats.embeddingsFetchMs += nowMs() - embeddingsStart;
     const gotVector = /* @__PURE__ */ new Set();
     for (const r of rows) {
       if (!r.embedding) continue;
@@ -30324,7 +30337,9 @@ async function buildProjectedCorpus(query, vaultCtx, embeddingOptions, cache, qu
         `memoryVault: projected search un-embedded lane capped at ${laneIds.length}/${noVectorIds.length}`
       );
     }
+    const laneStart = nowMs();
     const laneFetched = await getVaultMemoriesByIdsOp(vaultCtx, laneIds, hydrateOpts);
+    corpusStats.rowsFetchMs += nowMs() - laneStart;
     rowsDecrypted += laneFetched.length;
     for (const row of laneFetched) laneById.set(row.uniqueId, row);
     const laneRows = laneFetched.filter((m) => !isEncrypted(m.content));
@@ -30376,7 +30391,9 @@ async function buildProjectedCorpus(query, vaultCtx, embeddingOptions, cache, qu
     }
   }
   const idsToFetch = [...admissionSet].filter((id) => !laneById.has(id));
+  const admittedStart = nowMs();
   const fetched = idsToFetch.length > 0 ? await getVaultMemoriesByIdsOp(vaultCtx, idsToFetch, hydrateOpts) : [];
+  corpusStats.rowsFetchMs += nowMs() - admittedStart;
   rowsDecrypted += fetched.length;
   const admittedRows = [
     ...fetched,
@@ -30405,7 +30422,10 @@ async function buildProjectedCorpus(query, vaultCtx, embeddingOptions, cache, qu
   }
   if (staleIds.length > 0) {
     const contentById = new Map(memories.map((m) => [m.uniqueId, m]));
-    for (const r of await getVaultEmbeddingsByIdsOp(vaultCtx, staleIds, hydrateOpts)) {
+    const staleStart = nowMs();
+    const staleRows = await getVaultEmbeddingsByIdsOp(vaultCtx, staleIds, hydrateOpts);
+    corpusStats.embeddingsFetchMs += nowMs() - staleStart;
+    for (const r of staleRows) {
       if (!r.embedding) continue;
       try {
         const parsed = JSON.parse(r.embedding);
@@ -30437,7 +30457,15 @@ async function buildProjectedCorpus(query, vaultCtx, embeddingOptions, cache, qu
     eventTimeKind: normalizeEventTimeKind(m.eventTimeKind),
     factType: m.factType
   }));
-  return { memories, embeddedItems, queryEmbedding, vaultSize, laneEmbedFailed, rowsDecrypted };
+  return {
+    memories,
+    embeddedItems,
+    queryEmbedding,
+    vaultSize,
+    laneEmbedFailed,
+    rowsDecrypted,
+    corpusStats
+  };
 }
 async function prepareVaultCandidates(query, vaultCtx, embeddingOptions, cache, searchOptions) {
   if (!query || typeof query !== "string") {
@@ -30478,6 +30506,7 @@ async function prepareVaultCandidates(query, vaultCtx, embeddingOptions, cache,
     embeddingFailure = true;
   };
   const embedStats = { queryMs: 0, rowsEmbedded: 0 };
+  let corpusStats;
   if (searchOptions?.decryptLast) {
     const forceIncludeIds = [
       ...searchOptions.entityRanking ?? [],
@@ -30498,6 +30527,7 @@ async function prepareVaultCandidates(query, vaultCtx, embeddingOptions, cache,
       onEmbeddingDegraded,
       embedStats
     });
+    corpusStats = corpus.corpusStats;
     if (corpus.vaultSize === 0) {
       return {
         memories: [],
@@ -30509,7 +30539,8 @@ async function prepareVaultCandidates(query, vaultCtx, embeddingOptions, cache,
         decryptLast: true,
         rowsDecrypted: corpus.rowsDecrypted,
         queryEmbedMs: embedStats.queryMs,
-        rowsEmbedded: embedStats.rowsEmbedded
+        rowsEmbedded: embedStats.rowsEmbedded,
+        corpusStats
       };
     }
     ({ memories, embeddedItems, queryEmbedding, vaultSize } = corpus);
@@ -30526,7 +30557,8 @@ async function prepareVaultCandidates(query, vaultCtx, embeddingOptions, cache,
         decryptLast: true,
         rowsDecrypted: corpus.rowsDecrypted,
         queryEmbedMs: embedStats.queryMs,
-        rowsEmbedded: embedStats.rowsEmbedded
+        rowsEmbedded: embedStats.rowsEmbedded,
+        corpusStats
       };
     }
   } else {
@@ -30659,7 +30691,8 @@ async function prepareVaultCandidates(query, vaultCtx, embeddingOptions, cache,
     embeddingsUnavailable,
     embeddingFailure,
     decryptLast: !!searchOptions?.decryptLast,
-    rowsDecrypted
+    rowsDecrypted,
+    ...corpusStats && { corpusStats }
   };
 }
 async function rankPreparedVaultCandidates(query, prepared, embeddingOptions, searchOptions) {
@@ -30876,7 +30909,8 @@ async function searchVaultMemoriesWithSize(query, vaultCtx, embeddingOptions, ca
       decryptLast: prepared.decryptLast,
       rowsDecrypted: prepared.rowsDecrypted,
       queryEmbedMs: prepared.queryEmbedMs,
-      rowsEmbedded: prepared.rowsEmbedded
+      rowsEmbedded: prepared.rowsEmbedded,
+      ...prepared.corpusStats && { corpusStats: prepared.corpusStats }
     };
   }
   if (prepared.memories.length === 0) {
@@ -30891,7 +30925,8 @@ async function searchVaultMemoriesWithSize(query, vaultCtx, embeddingOptions, ca
       decryptLast: prepared.decryptLast,
       rowsDecrypted: prepared.rowsDecrypted,
       queryEmbedMs: prepared.queryEmbedMs,
-      rowsEmbedded: prepared.rowsEmbedded
+      rowsEmbedded: prepared.rowsEmbedded,
+      ...prepared.corpusStats && { corpusStats: prepared.corpusStats }
     };
   }
   const ranked = await rankPreparedVaultCandidates(
@@ -30906,7 +30941,8 @@ async function searchVaultMemoriesWithSize(query, vaultCtx, embeddingOptions, ca
     decryptLast: prepared.decryptLast,
     rowsDecrypted: prepared.rowsDecrypted,
     queryEmbedMs: prepared.queryEmbedMs,
-    rowsEmbedded: prepared.rowsEmbedded
+    rowsEmbedded: prepared.rowsEmbedded,
+    ...prepared.corpusStats && { corpusStats: prepared.corpusStats }
   };
 }
 async function searchVaultMemories(query, vaultCtx, embeddingOptions, cache, searchOptions) {
@@ -32907,6 +32943,7 @@ async function recall(query, ctx, options = {}) {
   let factLaneRankedOnCosine = false;
   let decryptLastRan;
   let vaultRowsDecrypted;
+  let corpusStats;
   let graphLaneCount = 0;
   let temporalLaneCount = 0;
   let graphLaneFailed = false;
@@ -32947,6 +32984,10 @@ async function recall(query, ctx, options = {}) {
       ...decryptLastRan !== void 0 && { decryptLast: decryptLastRan },
       ...vaultRowsDecrypted !== void 0 && { vaultRowsDecrypted },
       ...vaultRowsEmbedded !== void 0 && { vaultRowsEmbedded },
+      ...corpusStats && {
+        vaultCacheHits: corpusStats.cacheHits,
+        vaultCacheMisses: corpusStats.cacheMisses
+      },
       ...chunkStats && {
         chunkRowsScanned: chunkStats.rowsScanned,
         chunkRowsFetched: chunkStats.rowsFetched,
@@ -32969,7 +33010,12 @@ async function recall(query, ctx, options = {}) {
         rerank: rerankMs,
         queryEmbed: queryEmbedMs,
         chunkLane: chunkLaneMs,
-        fuse: fuseMs
+        fuse: fuseMs,
+        ...corpusStats && {
+          corpusKeys: corpusStats.keysMs,
+          corpusEmbeddingsFetch: corpusStats.embeddingsFetchMs,
+          corpusRowsFetch: corpusStats.rowsFetchMs
+        }
       },
       degraded
     };
@@ -33043,7 +33089,8 @@ async function recall(query, ctx, options = {}) {
       embeddingsUnavailable: factEmbeddingsUnavailable,
       rankedOnCosine: factRankedOnCosine,
       decryptLast: factDecryptLast,
-      rowsDecrypted: factRowsDecrypted
+      rowsDecrypted: factRowsDecrypted,
+      corpusStats: factCorpusStats
     } = await (ctx.factSource?.search.bind(ctx.factSource) ?? ((searchQuery, searchOptions) => searchVaultMemoriesWithSize(
       searchQuery,
       ctx.vaultCtx,
@@ -33109,6 +33156,7 @@ async function recall(query, ctx, options = {}) {
     factLaneRankedOnCosine = factRankedOnCosine;
     decryptLastRan = factDecryptLast;
     vaultRowsDecrypted = factRowsDecrypted;
+    corpusStats = factCorpusStats;
     factLaneMs = nowMs() - factStart;
   }
   if (chunkEmbedFailed && !factLaneRankedOnCosine) embeddingsUnavailable = true;

package/dist/telemetry/index.d.mts

@@ -332,6 +332,8 @@ interface RecallDiagnostics {
      * LEGACY read path this batch is uncapped, so it can be the whole vault.
      */
     vaultRowsEmbedded?: number;
+    vaultCacheHits?: number;
+    vaultCacheMisses?: number;
     /** Embedded messages the chunk lane considered; absent when the lane did not run. */
     chunkRowsScanned?: number;
     /** Messages whose vectors the chunk lane read from storage on a cache miss. */
@@ -434,6 +436,9 @@ interface RecallDiagnostics {
         chunkLane: number;
         /** Cross-lane RRF fusion + provenance dedup after both lanes. */
         fuse: number;
+        corpusKeys?: number;
+        corpusEmbeddingsFetch?: number;
+        corpusRowsFetch?: number;
     };
     /** Soft-degradation signals that fired this call (empty when clean). */
     degraded: RecallDegradation[];

package/dist/telemetry/index.d.ts

@@ -332,6 +332,8 @@ interface RecallDiagnostics {
      * LEGACY read path this batch is uncapped, so it can be the whole vault.
      */
     vaultRowsEmbedded?: number;
+    vaultCacheHits?: number;
+    vaultCacheMisses?: number;
     /** Embedded messages the chunk lane considered; absent when the lane did not run. */
     chunkRowsScanned?: number;
     /** Messages whose vectors the chunk lane read from storage on a cache miss. */
@@ -434,6 +436,9 @@ interface RecallDiagnostics {
         chunkLane: number;
         /** Cross-lane RRF fusion + provenance dedup after both lanes. */
         fuse: number;
+        corpusKeys?: number;
+        corpusEmbeddingsFetch?: number;
+        corpusRowsFetch?: number;
     };
     /** Soft-degradation signals that fired this call (empty when clean). */
     degraded: RecallDegradation[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anuma/sdk",
-  "version": "7.1.0",
+  "version": "7.2.0",
   "description": "",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",