@betterdb/semantic-cache 0.5.1 → 0.7.0

package/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2026-present BetterDB Inc.
+
+Portions of this software are licensed as follows:
+
+- All content residing under the "doc/" directory of this repository is licensed under the "Creative Commons: CC BY-SA 4.0 license".
+
+- All content that resides under the "proprietary/" directory of this repository, if that directory exists, is licensed under the license defined in "proprietary/LICENSE".
+
+- All third-party components incorporated into the BetterDB Software are licensed under the original license provided by the owner of the applicable component.
+
+- Content outside of the above-mentioned directories or restrictions above is available under the "MIT Expat" license as defined below.
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/dist/SemanticCache.d.ts

@@ -8,6 +8,7 @@ export declare class SemanticCache {
     private readonly entryPrefix;
     private readonly statsKey;
     private readonly similarityWindowKey;
+    private readonly missPendingKey;
     private readonly configKey;
     private defaultThreshold;
     private readonly defaultTtl;
@@ -159,10 +160,21 @@ export declare class SemanticCache {
     private recordStat;
     /** Append to the rolling similarity window sorted set and trim to 10,000 entries or 7 days. */
     private recordSimilarityWindow;
+    /**
+     * Track a miss so a subsequent store() can backfill its cost into the
+     * similarity-window record. Bounded by a 5-minute TTL on the bookkeeping
+     * zset — entries beyond that are pruned on every record and backfill.
+     */
+    private recordMissPending;
+    /**
+     * After a successful store(), find the oldest pending miss for the same
+     * query and update its similarity-window record with the now-known cost.
+     * Best-effort — silently no-op if no pending miss exists or the bookkeeping
+     * entry has already been pruned.
+     */
+    private applyCostToPendingMiss;
     private assertInitialized;
     private assertDimension;
-    private isIndexNotFoundError;
-    private parseDimensionFromInfo;
 }
 export interface ThresholdEffectivenessResult {
     category: string;

package/dist/SemanticCache.js

@@ -6,6 +6,7 @@ const node_crypto_2 = require("node:crypto");
 const api_1 = require("@opentelemetry/api");
 const errors_1 = require("./errors");
 const telemetry_1 = require("./telemetry");
+const valkey_search_kit_1 = require("@betterdb/valkey-search-kit");
 const utils_1 = require("./utils");
 const defaultCostTable_1 = require("./defaultCostTable");
 const cluster_1 = require("./cluster");
@@ -16,6 +17,19 @@ const PACKAGE_VERSION = require('../package.json').version;
 function errMsg(err) {
     return err instanceof Error ? err.message : String(err);
 }
+function parseHitCostMicros(raw) {
+    if (raw === undefined || raw === null) {
+        return null;
+    }
+    const n = parseInt(raw, 10);
+    if (!Number.isFinite(n) || n < 0) {
+        return null;
+    }
+    return n;
+}
+function correlationIdFor(prompt) {
+    return (0, node_crypto_2.createHash)('sha256').update(prompt).digest('hex').slice(0, 16);
+}
 class SemanticCache {
     client;
     embedFn;
@@ -24,6 +38,7 @@ class SemanticCache {
     entryPrefix;
     statsKey;
     similarityWindowKey;
+    missPendingKey;
     configKey;
     defaultThreshold;
     defaultTtl;
@@ -68,6 +83,7 @@ class SemanticCache {
         this.entryPrefix = `${this.name}:entry:`;
         this.statsKey = `${this.name}:__stats`;
         this.similarityWindowKey = `${this.name}:__similarity_window`;
+        this.missPendingKey = `${this.name}:__miss_pending`;
         this.configKey = `${this.name}:__config`;
         this.embedKeyPrefix = `${this.name}:embed:`;
         this.defaultThreshold = options.defaultThreshold ?? 0.1;
@@ -136,15 +152,12 @@ class SemanticCache {
             await this.client.call('FT.DROPINDEX', this.indexName);
         }
         catch (err) {
-            if (!this.isIndexNotFoundError(err)) {
+            if (!(0, valkey_search_kit_1.isIndexNotFoundError)(err)) {
                 throw new errors_1.ValkeyCommandError('FT.DROPINDEX', err);
             }
         }
         // Cluster-aware SCAN for entry keys and embed cache keys
-        const patterns = [
-            `${this.name}:entry:*`,
-            `${this.name}:embed:*`,
-        ];
+        const patterns = [`${this.name}:entry:*`, `${this.name}:embed:*`];
         for (const pattern of patterns) {
             await (0, cluster_1.clusterScan)(this.client, pattern, async (keys, nodeClient) => {
                 await nodeClient.del(keys);
@@ -152,6 +165,7 @@ class SemanticCache {
         }
         await this.client.del(this.statsKey);
         await this.client.del(this.similarityWindowKey);
+        await this.client.del(this.missPendingKey);
         this.analytics.capture('cache_flush');
     }
     /**
@@ -212,9 +226,9 @@ class SemanticCache {
             const userFilter = options?.filter;
             // AND semantics: each ref must be present — chain separate TAG clauses.
             const binaryFilter = binaryRefs.length > 0 && this._hasBinaryRefs
-                ? (binaryRefs.length === 1
+                ? binaryRefs.length === 1
                     ? `@binary_refs:{${(0, utils_1.escapeTag)(binaryRefs[0])}}`
-                    : binaryRefs.map((r) => `@binary_refs:{${(0, utils_1.escapeTag)(r)}}`).join(' '))
+                    : binaryRefs.map((r) => `@binary_refs:{${(0, utils_1.escapeTag)(r)}}`).join(' ')
                 : null;
             const combinedFilter = [userFilter, binaryFilter].filter(Boolean).join(' ');
             const filterExpr = combinedFilter ? `(${combinedFilter})` : '*';
@@ -230,15 +244,18 @@ class SemanticCache {
             const searchMs = performance.now() - searchStart;
             const parsed = (0, utils_1.parseFtSearchResponse)(rawResult);
             const categoryLabel = category || 'none';
-            const timingAttrs = { 'embedding_latency_ms': embedSec * 1000, 'search_latency_ms': searchMs };
+            const timingAttrs = { embedding_latency_ms: embedSec * 1000, search_latency_ms: searchMs };
             // No candidates at all
             if (parsed.length === 0) {
                 await this.recordStat('misses');
                 this.telemetry.metrics.requestsTotal
-                    .labels({ cache_name: this.name, result: 'miss', category: categoryLabel }).inc();
+                    .labels({ cache_name: this.name, result: 'miss', category: categoryLabel })
+                    .inc();
                 span.setAttributes({
-                    'cache.hit': false, 'cache.name': this.name,
-                    'cache.category': categoryLabel, ...timingAttrs,
+                    'cache.hit': false,
+                    'cache.name': this.name,
+                    'cache.category': categoryLabel,
+                    ...timingAttrs,
                 });
                 return { hit: false, confidence: 'miss' };
             }
@@ -246,19 +263,24 @@ class SemanticCache {
             const score = scoreStr !== undefined ? parseFloat(scoreStr) : NaN;
             if (!isNaN(score)) {
                 this.telemetry.metrics.similarityScore
-                    .labels({ cache_name: this.name, category: categoryLabel }).observe(score);
+                    .labels({ cache_name: this.name, category: categoryLabel })
+                    .observe(score);
             }
             // Miss (no usable score, or score exceeds threshold)
             if (isNaN(score) || score > threshold) {
                 if (!isNaN(score)) {
-                    await this.recordSimilarityWindow(score, 'miss', category);
+                    const missMember = await this.recordSimilarityWindow(score, 'miss', category, null);
+                    await this.recordMissPending(promptText, missMember);
                 }
                 await this.recordStat('misses');
                 this.telemetry.metrics.requestsTotal
-                    .labels({ cache_name: this.name, result: 'miss', category: categoryLabel }).inc();
+                    .labels({ cache_name: this.name, result: 'miss', category: categoryLabel })
+                    .inc();
                 span.setAttributes({
-                    'cache.hit': false, 'cache.name': this.name,
-                    'cache.category': categoryLabel, ...timingAttrs,
+                    'cache.hit': false,
+                    'cache.name': this.name,
+                    'cache.category': categoryLabel,
+                    ...timingAttrs,
                     ...(isNaN(score) ? {} : { 'cache.similarity': score, 'cache.threshold': threshold }),
                 });
                 const result = { hit: false, confidence: 'miss' };
@@ -278,17 +300,23 @@ class SemanticCache {
                     .filter(({ s }) => !isNaN(s))
                     .map(({ i, s }) => ({
                     origIdx: i,
-                    candidate: { response: parsed[i].fields['response'] ?? '', similarity: s },
+                    candidate: { response: parsed[i].fields['response'] ?? '', similarity: s, prompt: parsed[i].fields['prompt'] ?? '' },
                 }));
                 const picked = await rerankOpts.rerankFn(promptText, indexedCandidates.map((x) => x.candidate));
                 // Explicit bounds check: -1 means "reject all"; out-of-range is a caller bug
                 // treated as a miss rather than silently falling back to the top candidate.
                 if (picked === -1 || picked < 0 || picked >= indexedCandidates.length) {
-                    await this.recordSimilarityWindow(score, 'miss', category);
+                    const missMember = await this.recordSimilarityWindow(score, 'miss', category, null);
+                    await this.recordMissPending(promptText, missMember);
                     await this.recordStat('misses');
                     this.telemetry.metrics.requestsTotal
-                        .labels({ cache_name: this.name, result: 'miss', category: categoryLabel }).inc();
-                    span.setAttributes({ 'cache.hit': false, 'cache.name': this.name, 'cache.reranked': true });
+                        .labels({ cache_name: this.name, result: 'miss', category: categoryLabel })
+                        .inc();
+                    span.setAttributes({
+                        'cache.hit': false,
+                        'cache.name': this.name,
+                        'cache.reranked': true,
+                    });
                     return { hit: false, confidence: 'miss' };
                 }
                 // Map back to the original parsed[] index (not the candidates[] index)
@@ -304,12 +332,16 @@ class SemanticCache {
                     try {
                         await this.client.del(winner.key);
                     }
-                    catch { /* best effort */ }
-                    await this.recordSimilarityWindow(winnerScore, 'miss', category);
+                    catch {
+                        /* best effort */
+                    }
+                    const missMember = await this.recordSimilarityWindow(winnerScore, 'miss', category, null);
+                    await this.recordMissPending(promptText, missMember);
                     this.telemetry.metrics.staleModelEvictions.labels({ cache_name: this.name }).inc();
                     await this.recordStat('misses');
                     this.telemetry.metrics.requestsTotal
-                        .labels({ cache_name: this.name, result: 'miss', category: categoryLabel }).inc();
+                        .labels({ cache_name: this.name, result: 'miss', category: categoryLabel })
+                        .inc();
                     span.setAttributes({ 'cache.hit': false, 'cache.stale_evicted': true });
                     return { hit: false, confidence: 'miss' };
                 }
@@ -330,6 +362,8 @@ class SemanticCache {
                         similarity: winnerScore,
                         threshold,
                         category: category || undefined,
+                        // Reserved for consumer judge functions; not consumed by the built-in judge path.
+                        cachedPrompt: winner.fields['prompt'] ?? '',
                     }), timeoutMs);
                     decision = accepted ? 'accept' : 'reject';
                 }
@@ -363,7 +397,8 @@ class SemanticCache {
                 }
                 else {
                     // reject / error_reject / timeout_reject → treat as miss
-                    await this.recordSimilarityWindow(winnerScore, 'miss', category);
+                    const missMember = await this.recordSimilarityWindow(winnerScore, 'miss', category, null);
+                    await this.recordMissPending(promptText, missMember);
                     await this.recordStat('misses');
                     this.telemetry.metrics.requestsTotal
                         .labels({ cache_name: this.name, result: 'miss', category: categoryLabel })
@@ -387,27 +422,26 @@ class SemanticCache {
                 }
             }
             // --- End judge ---
+            const hitCostMicros = parseHitCostMicros(winner.fields['cost_micros']);
             // Record as genuine hit (moved here from before the judge block)
-            await this.recordSimilarityWindow(winnerScore, 'hit', category);
+            await this.recordSimilarityWindow(winnerScore, 'hit', category, hitCostMicros);
             await this.recordStat('hits');
             const metricResult = confidence === 'uncertain' ? 'uncertain_hit' : 'hit';
             this.telemetry.metrics.requestsTotal
-                .labels({ cache_name: this.name, result: metricResult, category: categoryLabel }).inc();
+                .labels({ cache_name: this.name, result: metricResult, category: categoryLabel })
+                .inc();
             if (this.defaultTtl !== undefined && matchedKey) {
                 await this.client.expire(matchedKey, this.defaultTtl);
             }
             // Cost saved
             let costSaved;
-            const costMicrosStr = winner.fields['cost_micros'];
-            if (costMicrosStr) {
-                const costMicros = parseInt(costMicrosStr, 10);
-                if (!isNaN(costMicros) && costMicros > 0) {
-                    costSaved = costMicros / 1_000_000;
-                    // Atomically increment cost_saved_micros in stats
-                    await this.client.hincrby(this.statsKey, 'cost_saved_micros', costMicros);
-                    this.telemetry.metrics.costSavedTotal
-                        .labels({ cache_name: this.name, category: categoryLabel }).inc(costSaved);
-                }
+            if (hitCostMicros !== null) {
+                costSaved = hitCostMicros / 1_000_000;
+                // Atomically increment cost_saved_micros in stats
+                await this.client.hincrby(this.statsKey, 'cost_saved_micros', hitCostMicros);
+                this.telemetry.metrics.costSavedTotal
+                    .labels({ cache_name: this.name, category: categoryLabel })
+                    .inc(costSaved);
             }
             // Content blocks
             let contentBlocks;
@@ -416,16 +450,25 @@ class SemanticCache {
                 try {
                     contentBlocks = JSON.parse(contentBlocksStr);
                 }
-                catch { /* ignore parse errors */ }
+                catch {
+                    /* ignore parse errors */
+                }
             }
             span.setAttributes({
-                'cache.hit': true, 'cache.similarity': winnerScore, 'cache.threshold': threshold,
-                'cache.confidence': confidence, 'cache.matched_key': matchedKey,
-                'cache.category': categoryLabel, ...timingAttrs,
+                'cache.hit': true,
+                'cache.similarity': winnerScore,
+                'cache.threshold': threshold,
+                'cache.confidence': confidence,
+                'cache.matched_key': matchedKey,
+                'cache.category': categoryLabel,
+                ...timingAttrs,
             });
             const result = {
-                hit: true, response: winner.fields['response'],
-                similarity: winnerScore, confidence, matchedKey,
+                hit: true,
+                response: winner.fields['response'],
+                similarity: winnerScore,
+                confidence,
+                matchedKey,
             };
             if (costSaved !== undefined)
                 result.costSaved = costSaved;
@@ -451,8 +494,9 @@ class SemanticCache {
                 this.costTable) {
                 const pricing = this.costTable[options.model];
                 if (pricing) {
-                    costMicros = Math.round((options.inputTokens * pricing.inputPer1k / 1000 +
-                        options.outputTokens * pricing.outputPer1k / 1000) * 1_000_000);
+                    costMicros = Math.round(((options.inputTokens * pricing.inputPer1k) / 1000 +
+                        (options.outputTokens * pricing.outputPer1k) / 1000) *
+                        1_000_000);
                 }
             }
             const hashFields = {
@@ -489,10 +533,16 @@ class SemanticCache {
             if (ttl !== undefined)
                 await this.client.expire(entryKey, ttl);
             span.setAttributes({
-                'cache.name': this.name, 'cache.key': entryKey, 'cache.ttl': ttl ?? -1,
-                'cache.category': category || 'none', 'cache.model': model || 'none',
-                'embedding_latency_ms': embedSec * 1000,
+                'cache.name': this.name,
+                'cache.key': entryKey,
+                'cache.ttl': ttl ?? -1,
+                'cache.category': category || 'none',
+                'cache.model': model || 'none',
+                embedding_latency_ms: embedSec * 1000,
             });
+            if (costMicros !== undefined && costMicros >= 0) {
+                await this.applyCostToPendingMiss(promptText, costMicros);
+            }
             return entryKey;
         });
     }
@@ -512,11 +562,15 @@ class SemanticCache {
             const category = options?.category ?? '';
             const model = options?.model ?? '';
             let costMicros;
-            if (options?.model && options?.inputTokens !== undefined && options?.outputTokens !== undefined && this.costTable) {
+            if (options?.model &&
+                options?.inputTokens !== undefined &&
+                options?.outputTokens !== undefined &&
+                this.costTable) {
                 const pricing = this.costTable[options.model];
                 if (pricing) {
-                    costMicros = Math.round((options.inputTokens * pricing.inputPer1k / 1000 +
-                        options.outputTokens * pricing.outputPer1k / 1000) * 1_000_000);
+                    costMicros = Math.round(((options.inputTokens * pricing.inputPer1k) / 1000 +
+                        (options.outputTokens * pricing.outputPer1k) / 1000) *
+                        1_000_000);
                 }
             }
             const hashFields = {
@@ -535,8 +589,9 @@ class SemanticCache {
             if (costMicros !== undefined && costMicros > 0) {
                 hashFields['cost_micros'] = String(costMicros);
             }
-            if (options?.temperature !== undefined)
+            if (options?.temperature !== undefined) {
                 hashFields['temperature'] = String(options.temperature);
+            }
             if (options?.topP !== undefined)
                 hashFields['top_p'] = String(options.topP);
             if (options?.seed !== undefined)
@@ -551,10 +606,16 @@ class SemanticCache {
             if (ttl !== undefined)
                 await this.client.expire(entryKey, ttl);
             span.setAttributes({
-                'cache.name': this.name, 'cache.key': entryKey, 'cache.ttl': ttl ?? -1,
-                'cache.category': category || 'none', 'cache.model': model || 'none',
-                'embedding_latency_ms': embedSec * 1000,
+                'cache.name': this.name,
+                'cache.key': entryKey,
+                'cache.ttl': ttl ?? -1,
+                'cache.category': category || 'none',
+                'cache.model': model || 'none',
+                embedding_latency_ms: embedSec * 1000,
             });
+            if (costMicros !== undefined && costMicros >= 0) {
+                await this.applyCostToPendingMiss(promptText, costMicros);
+            }
             return entryKey;
         });
     }
@@ -592,9 +653,9 @@ class SemanticCache {
                 const { binaryRefs } = resolved[i];
                 const { vector: embedding } = embeddings[i];
                 const binaryFilter = binaryRefs.length > 0 && this._hasBinaryRefs
-                    ? (binaryRefs.length === 1
+                    ? binaryRefs.length === 1
                         ? `@binary_refs:{${(0, utils_1.escapeTag)(binaryRefs[0])}}`
-                        : binaryRefs.map((r) => `@binary_refs:{${(0, utils_1.escapeTag)(r)}}`).join(' '))
+                        : binaryRefs.map((r) => `@binary_refs:{${(0, utils_1.escapeTag)(r)}}`).join(' ')
                     : null;
                 const combinedFilter = [userFilter, binaryFilter].filter(Boolean).join(' ');
                 const filterExpr = combinedFilter ? `(${combinedFilter})` : '*';
@@ -612,7 +673,8 @@ class SemanticCache {
                 if (err) {
                     await this.recordStat('misses');
                     this.telemetry.metrics.requestsTotal
-                        .labels({ cache_name: this.name, result: 'miss', category: categoryLabel }).inc();
+                        .labels({ cache_name: this.name, result: 'miss', category: categoryLabel })
+                        .inc();
                     results.push({ hit: false, confidence: 'miss' });
                     continue;
                 }
@@ -620,7 +682,8 @@ class SemanticCache {
                 if (parsed.length === 0) {
                     await this.recordStat('misses');
                     this.telemetry.metrics.requestsTotal
-                        .labels({ cache_name: this.name, result: 'miss', category: categoryLabel }).inc();
+                        .labels({ cache_name: this.name, result: 'miss', category: categoryLabel })
+                        .inc();
                     results.push({ hit: false, confidence: 'miss' });
                     continue;
                 }
@@ -628,11 +691,13 @@ class SemanticCache {
                 const score = scoreStr !== undefined ? parseFloat(scoreStr) : NaN;
                 if (isNaN(score) || score > threshold) {
                     if (!isNaN(score)) {
-                        await this.recordSimilarityWindow(score, 'miss', category);
+                        const missMember = await this.recordSimilarityWindow(score, 'miss', category, null);
+                        await this.recordMissPending(resolved[i].text, missMember);
                     }
                     await this.recordStat('misses');
                     this.telemetry.metrics.requestsTotal
-                        .labels({ cache_name: this.name, result: 'miss', category: categoryLabel }).inc();
+                        .labels({ cache_name: this.name, result: 'miss', category: categoryLabel })
+                        .inc();
                     const result = { hit: false, confidence: 'miss' };
                     if (!isNaN(score)) {
                         result.similarity = score;
@@ -641,26 +706,25 @@ class SemanticCache {
                     results.push(result);
                     continue;
                 }
-                await this.recordSimilarityWindow(score, 'hit', category);
+                const hitCostMicros = parseHitCostMicros(parsed[0].fields['cost_micros']);
+                await this.recordSimilarityWindow(score, 'hit', category, hitCostMicros);
                 const confidence = score >= threshold - this.uncertaintyBand ? 'uncertain' : 'high';
                 await this.recordStat('hits');
                 const metricResult = confidence === 'uncertain' ? 'uncertain_hit' : 'hit';
                 this.telemetry.metrics.requestsTotal
-                    .labels({ cache_name: this.name, result: metricResult, category: categoryLabel }).inc();
+                    .labels({ cache_name: this.name, result: metricResult, category: categoryLabel })
+                    .inc();
                 const matchedKey = parsed[0].key;
                 if (this.defaultTtl !== undefined && matchedKey) {
                     await this.client.expire(matchedKey, this.defaultTtl);
                 }
                 let costSaved;
-                const costMicrosStr = parsed[0].fields['cost_micros'];
-                if (costMicrosStr) {
-                    const costMicros = parseInt(costMicrosStr, 10);
-                    if (!isNaN(costMicros) && costMicros > 0) {
-                        costSaved = costMicros / 1_000_000;
-                        await this.client.hincrby(this.statsKey, 'cost_saved_micros', costMicros);
-                        this.telemetry.metrics.costSavedTotal
-                            .labels({ cache_name: this.name, category: categoryLabel }).inc(costSaved);
-                    }
+                if (hitCostMicros !== null) {
+                    costSaved = hitCostMicros / 1_000_000;
+                    await this.client.hincrby(this.statsKey, 'cost_saved_micros', hitCostMicros);
+                    this.telemetry.metrics.costSavedTotal
+                        .labels({ cache_name: this.name, category: categoryLabel })
+                        .inc(costSaved);
                 }
                 let contentBlocks;
                 const contentBlocksStr = parsed[0].fields['content_blocks'];
@@ -668,11 +732,16 @@ class SemanticCache {
                     try {
                         contentBlocks = JSON.parse(contentBlocksStr);
                     }
-                    catch { /* ignore */ }
+                    catch {
+                        /* ignore */
+                    }
                 }
                 const result = {
-                    hit: true, response: parsed[0].fields['response'],
-                    similarity: score, confidence, matchedKey,
+                    hit: true,
+                    response: parsed[0].fields['response'],
+                    similarity: score,
+                    confidence,
+                    matchedKey,
                 };
                 if (costSaved !== undefined)
                     result.costSaved = costSaved;
@@ -703,8 +772,10 @@ class SemanticCache {
             const parsed = (0, utils_1.parseFtSearchResponse)(rawResult);
             if (parsed.length === 0) {
                 span.setAttributes({
-                    'cache.name': this.name, 'cache.filter': filter,
-                    'cache.deleted_count': 0, 'cache.truncated': false,
+                    'cache.name': this.name,
+                    'cache.filter': filter,
+                    'cache.deleted_count': 0,
+                    'cache.truncated': false,
                 });
                 return { deleted: 0, truncated: false };
             }
@@ -717,8 +788,10 @@ class SemanticCache {
                 throw new errors_1.ValkeyCommandError('DEL', err);
             }
             span.setAttributes({
-                'cache.name': this.name, 'cache.filter': filter,
-                'cache.deleted_count': keys.length, 'cache.truncated': truncated,
+                'cache.name': this.name,
+                'cache.filter': filter,
+                'cache.deleted_count': keys.length,
+                'cache.truncated': truncated,
             });
             return { deleted: keys.length, truncated };
         });
@@ -761,16 +834,7 @@ class SemanticCache {
         catch (err) {
             throw new errors_1.ValkeyCommandError('FT.INFO', err);
         }
-        const info = raw;
-        let numDocs = 0;
-        let indexingState = 'unknown';
-        for (let i = 0; i < info.length - 1; i += 2) {
-            const key = String(info[i]);
-            if (key === 'num_docs')
-                numDocs = parseInt(String(info[i + 1]), 10) || 0;
-            else if (key === 'indexing')
-                indexingState = String(info[i + 1]);
-        }
+        const { numDocs, indexingState } = (0, valkey_search_kit_1.parseFtInfoStats)(raw);
         return { name: this.indexName, numDocs, dimension: this._dimension, indexingState };
     }
     /**
@@ -803,7 +867,9 @@ class SemanticCache {
                     }
                 }
             }
-            catch { /* skip corrupt entries */ }
+            catch {
+                /* skip corrupt entries */
+            }
         }
         const sampleCount = entries.length;
         const categoryLabel = category ?? 'all';
@@ -890,11 +956,15 @@ class SemanticCache {
                 if (entry.category)
                     categories.add(entry.category);
             }
-            catch { /* skip */ }
+            catch {
+                /* skip */
+            }
         }
         const results = await Promise.all([
             this.thresholdEffectiveness({ minSamples: options?.minSamples }),
-            ...[...categories].filter(Boolean).map((cat) => this.thresholdEffectiveness({ category: cat, minSamples: options?.minSamples })),
+            ...[...categories]
+                .filter(Boolean)
+                .map((cat) => this.thresholdEffectiveness({ category: cat, minSamples: options?.minSamples })),
         ]);
         return results;
     }
@@ -947,7 +1017,9 @@ class SemanticCache {
     }
     // -- Internal helpers exposed to package adapters --
     /** @internal Default similarity threshold. */
-    get _defaultThreshold() { return this.defaultThreshold; }
+    get _defaultThreshold() {
+        return this.defaultThreshold;
+    }
     /** @internal Test-only getter. */
     get _categoryThresholds() {
         return this.categoryThresholds;
@@ -980,15 +1052,11 @@ class SemanticCache {
             this.refreshConfig()
                 .then((ok) => {
                 if (!ok) {
-                    this.telemetry.metrics.configRefreshFailed
-                        .labels({ cache_name: this.name })
-                        .inc();
+                    this.telemetry.metrics.configRefreshFailed.labels({ cache_name: this.name }).inc();
                 }
             })
                 .catch(() => {
-                this.telemetry.metrics.configRefreshFailed
-                    .labels({ cache_name: this.name })
-                    .inc();
+                this.telemetry.metrics.configRefreshFailed.labels({ cache_name: this.name }).inc();
             });
         };
         // Synchronous first refresh: process started immediately after a proposal
@@ -1044,9 +1112,7 @@ class SemanticCache {
             metadata,
             heartbeatIntervalMs: this.discoveryOptions.heartbeatIntervalMs,
             onWriteFailed: () => {
-                this.telemetry.metrics.discoveryWriteFailed
-                    .labels({ cache_name: this.name })
-                    .inc();
+                this.telemetry.metrics.discoveryWriteFailed.labels({ cache_name: this.name }).inc();
             },
         });
         await manager.register();
@@ -1099,7 +1165,7 @@ class SemanticCache {
         // Try reading an existing index
         try {
             const info = (await this.client.call('FT.INFO', this.indexName));
-            const dim = this.parseDimensionFromInfo(info);
+            const dim = (0, valkey_search_kit_1.parseDimensionFromInfo)(info);
             const hasBinaryRefs = this.parseHasBinaryRefsFromInfo(info);
             if (dim > 0)
                 return { dim, hasBinaryRefs };
@@ -1110,7 +1176,7 @@ class SemanticCache {
         catch (err) {
             if (err instanceof errors_1.EmbeddingError)
                 throw err;
-            if (!this.isIndexNotFoundError(err)) {
+            if (!(0, valkey_search_kit_1.isIndexNotFoundError)(err)) {
                 throw new errors_1.ValkeyCommandError('FT.INFO', err);
             }
         }
@@ -1164,7 +1230,8 @@ class SemanticCache {
                 const cached = await this.client.getBuffer(embedKey);
                 if (cached) {
                     this.telemetry.metrics.embeddingCacheTotal
-                        .labels({ cache_name: this.name, result: 'hit' }).inc();
+                        .labels({ cache_name: this.name, result: 'hit' })
+                        .inc();
                     // Decode Float32 buffer
                     const vector = [];
                     for (let i = 0; i < cached.length; i += 4) {
@@ -1173,9 +1240,12 @@ class SemanticCache {
                     return { vector, durationSec: 0 };
                 }
             }
-            catch { /* ignore cache read errors */ }
+            catch {
+                /* ignore cache read errors */
+            }
             this.telemetry.metrics.embeddingCacheTotal
-                .labels({ cache_name: this.name, result: 'miss' }).inc();
+                .labels({ cache_name: this.name, result: 'miss' })
+                .inc();
         }
         const start = performance.now();
         let vector;
@@ -1186,9 +1256,7 @@ class SemanticCache {
             throw new errors_1.EmbeddingError(`embedFn failed: ${errMsg(err)}`, err);
         }
         const durationSec = (performance.now() - start) / 1000;
-        this.telemetry.metrics.embeddingDuration
-            .labels({ cache_name: this.name })
-            .observe(durationSec);
+        this.telemetry.metrics.embeddingDuration.labels({ cache_name: this.name }).observe(durationSec);
         // Store in embedding cache
         if (this.embeddingCacheEnabled && text) {
             const hash = (0, node_crypto_2.createHash)('sha256').update(text).digest('hex');
@@ -1197,7 +1265,9 @@ class SemanticCache {
                 const buf = (0, utils_1.encodeFloat32)(vector);
                 await this.client.set(embedKey, buf, 'EX', this.embeddingCacheTtl);
             }
-            catch { /* ignore cache write errors */ }
+            catch {
+                /* ignore cache write errors */
+            }
         }
         return { vector, durationSec };
     }
@@ -1235,22 +1305,99 @@ class SemanticCache {
         await pipeline.exec();
     }
     /** Append to the rolling similarity window sorted set and trim to 10,000 entries or 7 days. */
-    async recordSimilarityWindow(score, result, category) {
+    async recordSimilarityWindow(score, result, category, costSavedMicros) {
         const now = Date.now();
-        // Include a unique nonce so identical (score, result, category) tuples are
-        // each recorded as distinct ZADD members instead of overwriting each other.
-        const member = JSON.stringify({ score, result, category, _n: Math.random() });
+        const member = JSON.stringify({
+            score,
+            result,
+            category,
+            _n: Math.random(),
+            cost_saved_micros: costSavedMicros,
+        });
         const sevenDaysAgo = now - 7 * 24 * 60 * 60 * 1000;
         try {
             const pipeline = this.client.pipeline();
             pipeline.zadd(this.similarityWindowKey, now, member);
-            // Trim by time: remove entries older than 7 days
             pipeline.zremrangebyscore(this.similarityWindowKey, '-inf', sevenDaysAgo);
-            // Trim by count: keep at most 10,000 most recent
             pipeline.zremrangebyrank(this.similarityWindowKey, 0, -10001);
             await pipeline.exec();
         }
-        catch { /* best effort - never fail on window writes */ }
+        catch {
+            /* best effort - never fail on window writes */
+        }
+        return member;
+    }
+    /**
+     * Track a miss so a subsequent store() can backfill its cost into the
+     * similarity-window record. Bounded by a 5-minute TTL on the bookkeeping
+     * zset — entries beyond that are pruned on every record and backfill.
+     */
+    async recordMissPending(prompt, similarityMember) {
+        const correlationId = correlationIdFor(prompt);
+        const now = Date.now();
+        const fiveMinutesAgo = now - 5 * 60 * 1000;
+        const entry = JSON.stringify({ correlationId, similarityMember });
+        try {
+            await this.client.zadd(this.missPendingKey, now, entry);
+            await this.client.zremrangebyscore(this.missPendingKey, '-inf', `(${fiveMinutesAgo}`);
+        }
+        catch {
+            /* best effort */
+        }
+    }
+    /**
+     * After a successful store(), find the oldest pending miss for the same
+     * query and update its similarity-window record with the now-known cost.
+     * Best-effort — silently no-op if no pending miss exists or the bookkeeping
+     * entry has already been pruned.
+     */
+    async applyCostToPendingMiss(prompt, costMicros) {
+        const correlationId = correlationIdFor(prompt);
+        const fiveMinutesAgo = Date.now() - 5 * 60 * 1000;
+        try {
+            await this.client.zremrangebyscore(this.missPendingKey, '-inf', `(${fiveMinutesAgo}`);
+            const raw = (await this.client.zrange(this.missPendingKey, '0', '-1', 'WITHSCORES'));
+            let matchedEntry = null;
+            let matchedSimilarityMember = null;
+            for (let i = 0; i < raw.length; i += 2) {
+                const entryStr = raw[i];
+                try {
+                    const parsed = JSON.parse(entryStr);
+                    if (parsed.correlationId === correlationId) {
+                        matchedEntry = entryStr;
+                        matchedSimilarityMember = parsed.similarityMember;
+                        break;
+                    }
+                }
+                catch {
+                    /* skip malformed */
+                }
+            }
+            if (matchedEntry === null || matchedSimilarityMember === null) {
+                return;
+            }
+            const rawScore = await this.client.zscore(this.similarityWindowKey, matchedSimilarityMember);
+            if (rawScore === null) {
+                await this.client.zrem(this.missPendingKey, matchedEntry);
+                return;
+            }
+            const similarityScore = Number(rawScore);
+            if (!Number.isFinite(similarityScore)) {
+                await this.client.zrem(this.missPendingKey, matchedEntry);
+                return;
+            }
+            const parsedMember = JSON.parse(matchedSimilarityMember);
+            parsedMember.cost_saved_micros = costMicros;
+            const updatedMember = JSON.stringify(parsedMember);
+            const updatePipeline = this.client.pipeline();
+            updatePipeline.zrem(this.similarityWindowKey, matchedSimilarityMember);
+            updatePipeline.zadd(this.similarityWindowKey, similarityScore, updatedMember);
+            updatePipeline.zrem(this.missPendingKey, matchedEntry);
+            await updatePipeline.exec();
+        }
+        catch {
+            /* never fail store() because of bookkeeping */
+        }
     }
     assertInitialized(method) {
         if (!this._initialized) {
@@ -1262,49 +1409,6 @@ class SemanticCache {
             throw new errors_1.SemanticCacheUsageError(`Embedding dimension mismatch: index expects ${this._dimension}, embedFn returned ${embedding.length}. Call flush() then initialize() to rebuild.`);
         }
     }
-    isIndexNotFoundError(err) {
-        const msg = err instanceof Error ? err.message.toLowerCase() : '';
-        return (msg.includes('unknown index name') ||
-            msg.includes('no such index') ||
-            msg.includes('not found'));
-    }
-    parseDimensionFromInfo(info) {
-        for (let i = 0; i < info.length - 1; i += 2) {
-            const key = String(info[i]);
-            if (key !== 'attributes' && key !== 'fields')
-                continue;
-            const attributes = info[i + 1];
-            if (!Array.isArray(attributes))
-                continue;
-            for (const attr of attributes) {
-                if (!Array.isArray(attr))
-                    continue;
-                let isVector = false;
-                let dim = 0;
-                for (let j = 0; j < attr.length - 1; j++) {
-                    const attrKey = String(attr[j]);
-                    if (attrKey === 'type' && String(attr[j + 1]) === 'VECTOR')
-                        isVector = true;
-                    if (attrKey.toLowerCase() === 'dim')
-                        dim = parseInt(String(attr[j + 1]), 10) || 0;
-                    // Valkey Search 1.2 nests dimension inside an 'index' sub-array
-                    if (attrKey === 'index' && Array.isArray(attr[j + 1])) {
-                        const indexArr = attr[j + 1];
-                        for (let k = 0; k < indexArr.length - 1; k++) {
-                            if (String(indexArr[k]) === 'dimensions') {
-                                const d = parseInt(String(indexArr[k + 1]), 10) || 0;
-                                if (d > 0)
-                                    dim = d;
-                            }
-                        }
-                    }
-                }
-                if (isVector && dim > 0)
-                    return dim;
-            }
-        }
-        return 0;
-    }
 }
 exports.SemanticCache = SemanticCache;
 // --- Judge helpers ---

package/dist/index.d.ts

@@ -2,6 +2,7 @@ export { SemanticCache } from './SemanticCache';
 export type { ThresholdEffectivenessResult } from './SemanticCache';
 export { DEFAULT_COST_TABLE } from './defaultCostTable';
 export type { SemanticCacheOptions, CacheCheckOptions, CacheStoreOptions, CacheCheckResult, CacheStats, IndexInfo, InvalidateResult, CacheConfidence, EmbedFn, ModelCost, RerankOptions, JudgeOptions, ConfigRefreshOptions, } from './types';
+export { createKeywordOverlapRerank } from './rerank';
 export { SemanticCacheUsageError, EmbeddingError, ValkeyCommandError, } from './errors';
 export type { ContentBlock, TextBlock, BinaryBlock, ToolCallBlock, ToolResultBlock, ReasoningBlock, BlockHints, } from './utils';
 export { escapeTag } from './utils';

package/dist/index.js

@@ -1,10 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.defaultNormalizer = exports.composeNormalizer = exports.passthrough = exports.fetchAndHash = exports.hashUrl = exports.hashBytes = exports.hashBase64 = exports.escapeTag = exports.ValkeyCommandError = exports.EmbeddingError = exports.SemanticCacheUsageError = exports.DEFAULT_COST_TABLE = exports.SemanticCache = void 0;
+exports.defaultNormalizer = exports.composeNormalizer = exports.passthrough = exports.fetchAndHash = exports.hashUrl = exports.hashBytes = exports.hashBase64 = exports.escapeTag = exports.ValkeyCommandError = exports.EmbeddingError = exports.SemanticCacheUsageError = exports.createKeywordOverlapRerank = exports.DEFAULT_COST_TABLE = exports.SemanticCache = void 0;
 var SemanticCache_1 = require("./SemanticCache");
 Object.defineProperty(exports, "SemanticCache", { enumerable: true, get: function () { return SemanticCache_1.SemanticCache; } });
 var defaultCostTable_1 = require("./defaultCostTable");
 Object.defineProperty(exports, "DEFAULT_COST_TABLE", { enumerable: true, get: function () { return defaultCostTable_1.DEFAULT_COST_TABLE; } });
+var rerank_1 = require("./rerank");
+Object.defineProperty(exports, "createKeywordOverlapRerank", { enumerable: true, get: function () { return rerank_1.createKeywordOverlapRerank; } });
 var errors_1 = require("./errors");
 Object.defineProperty(exports, "SemanticCacheUsageError", { enumerable: true, get: function () { return errors_1.SemanticCacheUsageError; } });
 Object.defineProperty(exports, "EmbeddingError", { enumerable: true, get: function () { return errors_1.EmbeddingError; } });

package/dist/rerank.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Built-in rerank factories for @betterdb/semantic-cache.
+ */
+/**
+ * Built-in keyword-overlap reranker.
+ *
+ * Blends cosine similarity with word overlap and returns the index of the
+ * best candidate.
+ *
+ * @param compare
+ *   `"prompt"`  – overlap of the incoming query against each candidate's stored
+ *                 prompt. Equivalence signal. Catches entity mismatches
+ *                 (e.g. "weather in Paris" vs "weather in Berlin"). Default.
+ *   `"response"` – overlap of the incoming query against each candidate's cached
+ *                 response. Relevance signal.
+ *
+ * @param cosineWeight
+ *   Weight on cosine similarity in [0, 1]. Overlap weight is `1 - cosineWeight`.
+ *   Default: 0.7 (overlap 0.3).
+ *
+ * Candidate objects carry: `similarity` (cosine distance, lower = more similar),
+ * `response` (string), and `prompt` (string, stored prompt).
+ */
+export declare function createKeywordOverlapRerank(options?: {
+    compare?: 'prompt' | 'response';
+    cosineWeight?: number;
+}): (query: string, candidates: Array<{
+    response: string;
+    similarity: number;
+    prompt: string;
+}>) => Promise<number>;

package/dist/rerank.js

@@ -0,0 +1,73 @@
+"use strict";
+/**
+ * Built-in rerank factories for @betterdb/semantic-cache.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createKeywordOverlapRerank = createKeywordOverlapRerank;
+/**
+ * Tokenize: lowercase, split on whitespace, strip surrounding punctuation.
+ * Deterministic and dependency-free.
+ * IDF weighting would attach here at the token-weighting step.
+ */
+function tokenize(text) {
+    const out = new Set();
+    for (const raw of text.toLowerCase().split(/\s+/)) {
+        const tok = raw.replace(/^[.,!?;:"'()\[\]{}<>]+|[.,!?;:"'()\[\]{}<>]+$/g, '');
+        if (tok)
+            out.add(tok);
+    }
+    return out;
+}
+/**
+ * Built-in keyword-overlap reranker.
+ *
+ * Blends cosine similarity with word overlap and returns the index of the
+ * best candidate.
+ *
+ * @param compare
+ *   `"prompt"`  – overlap of the incoming query against each candidate's stored
+ *                 prompt. Equivalence signal. Catches entity mismatches
+ *                 (e.g. "weather in Paris" vs "weather in Berlin"). Default.
+ *   `"response"` – overlap of the incoming query against each candidate's cached
+ *                 response. Relevance signal.
+ *
+ * @param cosineWeight
+ *   Weight on cosine similarity in [0, 1]. Overlap weight is `1 - cosineWeight`.
+ *   Default: 0.7 (overlap 0.3).
+ *
+ * Candidate objects carry: `similarity` (cosine distance, lower = more similar),
+ * `response` (string), and `prompt` (string, stored prompt).
+ */
+function createKeywordOverlapRerank(options) {
+    const compare = options?.compare ?? 'prompt';
+    const cosineWeight = options?.cosineWeight ?? 0.7;
+    if (cosineWeight < 0 || cosineWeight > 1) {
+        throw new Error('cosineWeight must be in [0, 1]');
+    }
+    const overlapWeight = 1.0 - cosineWeight;
+    return async (query, candidates) => {
+        const queryTokens = tokenize(query);
+        let bestIdx = 0;
+        let bestScore = -Infinity;
+        for (let i = 0; i < candidates.length; i++) {
+            const text = candidates[i][compare] ?? '';
+            const candTokens = tokenize(text);
+            let overlap = 0;
+            if (queryTokens.size > 0) {
+                let intersection = 0;
+                for (const t of queryTokens) {
+                    if (candTokens.has(t))
+                        intersection++;
+                }
+                overlap = intersection / queryTokens.size;
+            }
+            const cosineSim = 1.0 - candidates[i].similarity;
+            const score = cosineWeight * cosineSim + overlapWeight * overlap;
+            if (score > bestScore) {
+                bestScore = score;
+                bestIdx = i;
+            }
+        }
+        return bestIdx;
+    };
+}

package/dist/types.d.ts

@@ -127,6 +127,7 @@ export interface RerankOptions {
     rerankFn: (query: string, candidates: Array<{
         response: string;
         similarity: number;
+        prompt: string;
     }>) => Promise<number>;
 }
 /**
@@ -162,6 +163,8 @@ export interface JudgeOptions {
         similarity: number;
         threshold: number;
         category: string | undefined;
+        /** The stored prompt text for the matched entry. */
+        cachedPrompt: string;
     }) => Promise<boolean>;
     /**
      * Behavior when judgeFn throws or exceeds timeoutMs.

package/dist/utils.d.ts

@@ -1,10 +1,6 @@
 /** SHA-256 hex digest of a string. */
 export declare function sha256(text: string): string;
-/** Escape a string for safe use as a Valkey Search TAG filter value.
- * Spaces are included because Valkey Search treats unescaped spaces as term
- * separators (OR semantics), which would broaden the filter unintentionally.
- */
-export declare function escapeTag(value: string): string;
+export { escapeTag, encodeFloat32, parseFtSearchResponse } from '@betterdb/valkey-search-kit';
 export type ContentBlock = TextBlock | BinaryBlock | ToolCallBlock | ToolResultBlock | ReasoningBlock;
 export interface TextBlock {
     type: 'text';
@@ -58,26 +54,3 @@ export declare function extractText(blocks: ContentBlock[]): string;
  * Used for the binary_refs TAG field on cache entries.
  */
 export declare function extractBinaryRefs(blocks: ContentBlock[]): string[];
-/**
- * Encode number[] as a little-endian Float32 Buffer.
- * Used to store embeddings as binary HSET field values.
- */
-export declare function encodeFloat32(vec: number[]): Buffer;
-/**
- * Parse a raw FT.SEARCH response from iovalkey's client.call().
- *
- * iovalkey returns FT.SEARCH results in the following shape:
- *   [totalCount, key1, [field1, val1, field2, val2, ...], key2, [...], ...]
- *
- * - totalCount is a string (e.g. "2")
- * - Each key is a string
- * - Each field list is a flat string array: [fieldName, value, fieldName, value, ...]
- *
- * Returns an array of { key: string, fields: Record<string, string> }.
- * Returns [] if totalCount is "0" or the response is empty/malformed.
- * Never throws — on any parse error, returns [].
- */
-export declare function parseFtSearchResponse(raw: unknown): Array<{
-    key: string;
-    fields: Record<string, string>;
-}>;

package/dist/utils.js

@@ -1,23 +1,18 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseFtSearchResponse = exports.encodeFloat32 = exports.escapeTag = void 0;
 exports.sha256 = sha256;
-exports.escapeTag = escapeTag;
 exports.extractText = extractText;
 exports.extractBinaryRefs = extractBinaryRefs;
-exports.encodeFloat32 = encodeFloat32;
-exports.parseFtSearchResponse = parseFtSearchResponse;
 const node_crypto_1 = require("node:crypto");
 /** SHA-256 hex digest of a string. */
 function sha256(text) {
     return (0, node_crypto_1.createHash)('sha256').update(text).digest('hex');
 }
-/** Escape a string for safe use as a Valkey Search TAG filter value.
- * Spaces are included because Valkey Search treats unescaped spaces as term
- * separators (OR semantics), which would broaden the filter unintentionally.
- */
-function escapeTag(value) {
-    return value.replace(/[,.<>{}[\]"':;!@#$%^&*()\-+=~|/\\ ]/g, '\\$&');
-}
+var valkey_search_kit_1 = require("@betterdb/valkey-search-kit");
+Object.defineProperty(exports, "escapeTag", { enumerable: true, get: function () { return valkey_search_kit_1.escapeTag; } });
+Object.defineProperty(exports, "encodeFloat32", { enumerable: true, get: function () { return valkey_search_kit_1.encodeFloat32; } });
+Object.defineProperty(exports, "parseFtSearchResponse", { enumerable: true, get: function () { return valkey_search_kit_1.parseFtSearchResponse; } });
 /**
  * Extract all text from a ContentBlock array, joining TextBlock.text values with a space.
  * Used to derive the embedding text from a multi-modal prompt.
@@ -38,70 +33,3 @@ function extractBinaryRefs(blocks) {
         .map((b) => b.ref)
         .sort();
 }
-/**
- * Encode number[] as a little-endian Float32 Buffer.
- * Used to store embeddings as binary HSET field values.
- */
-function encodeFloat32(vec) {
-    const buf = Buffer.alloc(vec.length * 4);
-    for (let i = 0; i < vec.length; i++) {
-        buf.writeFloatLE(vec[i], i * 4);
-    }
-    return buf;
-}
-/**
- * Parse a raw FT.SEARCH response from iovalkey's client.call().
- *
- * iovalkey returns FT.SEARCH results in the following shape:
- *   [totalCount, key1, [field1, val1, field2, val2, ...], key2, [...], ...]
- *
- * - totalCount is a string (e.g. "2")
- * - Each key is a string
- * - Each field list is a flat string array: [fieldName, value, fieldName, value, ...]
- *
- * Returns an array of { key: string, fields: Record<string, string> }.
- * Returns [] if totalCount is "0" or the response is empty/malformed.
- * Never throws — on any parse error, returns [].
- */
-function parseFtSearchResponse(raw) {
-    try {
-        if (!Array.isArray(raw) || raw.length < 1) {
-            return [];
-        }
-        const totalCount = typeof raw[0] === 'string' ? parseInt(raw[0], 10) : Number(raw[0]);
-        if (!totalCount || totalCount <= 0) {
-            return [];
-        }
-        const results = [];
-        let i = 1;
-        while (i < raw.length) {
-            const key = raw[i];
-            if (typeof key !== 'string') {
-                i++;
-                continue;
-            }
-            const fieldList = raw[i + 1];
-            const fields = {};
-            if (Array.isArray(fieldList)) {
-                const len = fieldList.length - (fieldList.length % 2);
-                for (let j = 0; j < len; j += 2) {
-                    const fieldName = String(fieldList[j]);
-                    const fieldValue = String(fieldList[j + 1]);
-                    fields[fieldName] = fieldValue;
-                }
-                i += 2;
-            }
-            else {
-                // No field list follows the key (e.g. RETURN 0 mode)
-                results.push({ key, fields });
-                i++;
-                continue;
-            }
-            results.push({ key, fields });
-        }
-        return results;
-    }
-    catch {
-        return [];
-    }
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@betterdb/semantic-cache",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "description": "Valkey-native semantic cache for LLM applications with built-in OpenTelemetry and Prometheus instrumentation",
   "keywords": [
     "valkey",
@@ -93,18 +93,11 @@
     "dist",
     "README.md"
   ],
-  "scripts": {
-    "build": "tsc && node scripts/inject-telemetry-defaults.mjs",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "clean": "rm -rf dist",
-    "update:pricing": "node scripts/update-model-prices.mjs"
-  },
   "dependencies": {
     "@opentelemetry/api": "^1.9.0",
     "posthog-node": ">=4.0.0",
-    "prom-client": "^15.1.3"
+    "prom-client": "^15.1.3",
+    "@betterdb/valkey-search-kit": "0.1.0"
   },
   "engines": {
     "node": ">=20.0.0"
@@ -137,5 +130,13 @@
     "openai": {
       "optional": true
     }
+  },
+  "scripts": {
+    "build": "tsc && node scripts/inject-telemetry-defaults.mjs",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist",
+    "update:pricing": "node scripts/update-model-prices.mjs"
   }
-}
+}