@betterdb/semantic-cache 0.1.0

package/dist/SemanticCache.js

@@ -0,0 +1,416 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SemanticCache = void 0;
+const node_crypto_1 = require("node:crypto");
+const api_1 = require("@opentelemetry/api");
+const errors_1 = require("./errors");
+const telemetry_1 = require("./telemetry");
+const utils_1 = require("./utils");
+const INVALIDATE_BATCH_SIZE = 1000;
+function errMsg(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+class SemanticCache {
+    client;
+    embedFn;
+    name;
+    indexName;
+    entryPrefix;
+    statsKey;
+    defaultThreshold;
+    defaultTtl;
+    categoryThresholds;
+    uncertaintyBand;
+    telemetry;
+    _initialized = false;
+    _dimension = 0;
+    _initPromise = null;
+    _initGeneration = 0;
+    /**
+     * Creates a new SemanticCache instance.
+     *
+     * The caller owns the iovalkey client lifecycle. SemanticCache does not
+     * close or disconnect the client when it is done. Call client.quit() or
+     * client.disconnect() yourself when the application shuts down.
+     *
+     * Call initialize() before using check() or store().
+     */
+    constructor(options) {
+        this.client = options.client;
+        this.embedFn = options.embedFn;
+        this.name = options.name ?? 'betterdb_scache';
+        this.indexName = `${this.name}:idx`;
+        this.entryPrefix = `${this.name}:entry:`;
+        this.statsKey = `${this.name}:__stats`;
+        this.defaultThreshold = options.defaultThreshold ?? 0.1;
+        this.defaultTtl = options.defaultTtl;
+        this.categoryThresholds = options.categoryThresholds ?? {};
+        this.uncertaintyBand = options.uncertaintyBand ?? 0.05;
+        this.telemetry = (0, telemetry_1.createTelemetry)({
+            prefix: options.telemetry?.metricsPrefix ?? 'semantic_cache',
+            tracerName: options.telemetry?.tracerName ?? '@betterdb/semantic-cache',
+            registry: options.telemetry?.registry,
+        });
+    }
+    // ── Lifecycle ──────────────────────────────────────────────
+    async initialize() {
+        if (!this._initPromise) {
+            this._initPromise = this._doInitialize().catch((err) => {
+                this._initPromise = null;
+                throw err;
+            });
+        }
+        return this._initPromise;
+    }
+    async flush() {
+        // Mark uninitialized immediately so concurrent check()/store() calls get
+        // a clear SemanticCacheUsageError instead of cryptic Valkey errors.
+        // Bump generation so any in-flight _doInitialize() won't overwrite this state.
+        this._initialized = false;
+        this._initPromise = null;
+        this._initGeneration++;
+        // Valkey Search 1.2 does not support the DD (Delete Documents) flag on
+        // FT.DROPINDEX. Drop the index first, then clean up keys separately.
+        try {
+            await this.client.call('FT.DROPINDEX', this.indexName);
+        }
+        catch (err) {
+            if (!this.isIndexNotFoundError(err)) {
+                throw new errors_1.ValkeyCommandError('FT.DROPINDEX', err);
+            }
+        }
+        const entryPattern = `${this.name}:entry:*`;
+        let cursor = '0';
+        do {
+            const [nextCursor, keys] = await this.client.scan(cursor, 'MATCH', entryPattern, 'COUNT', '100');
+            cursor = nextCursor;
+            if (keys.length > 0)
+                await this.client.del(keys);
+        } while (cursor !== '0');
+        await this.client.del(this.statsKey);
+    }
+    // ── Public operations ──────────────────────────────────────
+    async check(prompt, options) {
+        this.assertInitialized('check');
+        return this.traced('check', async (span) => {
+            const category = options?.category ?? '';
+            const k = options?.k ?? 1;
+            const threshold = options?.threshold ??
+                (category && this.categoryThresholds[category] !== undefined
+                    ? this.categoryThresholds[category]
+                    : this.defaultThreshold);
+            const { vector: embedding, durationSec: embedSec } = await this.embed(prompt);
+            this.assertDimension(embedding);
+            // FT.SEARCH — Valkey Search 1.2 rejects KNN aliases in RETURN/SORTBY,
+            // so we omit both. Results include all fields and are pre-sorted by distance.
+            const searchStart = performance.now();
+            const filter = options?.filter;
+            const query = `${filter ? `(${filter})` : '*'}=>[KNN ${k} @embedding $vec AS __score]`;
+            let rawResult;
+            try {
+                rawResult = await this.client.call('FT.SEARCH', this.indexName, query, 'PARAMS', '2', 'vec', (0, utils_1.encodeFloat32)(embedding), 'LIMIT', '0', String(k), 'DIALECT', '2');
+            }
+            catch (err) {
+                throw new errors_1.ValkeyCommandError('FT.SEARCH', err);
+            }
+            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 };
+            // 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();
+                span.setAttributes({
+                    'cache.hit': false, 'cache.name': this.name,
+                    'cache.category': categoryLabel, ...timingAttrs,
+                });
+                return { hit: false, confidence: 'miss' };
+            }
+            const scoreStr = parsed[0].fields['__score'];
+            const score = scoreStr !== undefined ? parseFloat(scoreStr) : NaN;
+            if (!isNaN(score)) {
+                this.telemetry.metrics.similarityScore
+                    .labels({ cache_name: this.name, category: categoryLabel }).observe(score);
+            }
+            // Miss (no usable score, or score exceeds threshold)
+            if (isNaN(score) || score > threshold) {
+                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.category': categoryLabel, ...timingAttrs,
+                    ...(isNaN(score) ? {} : { 'cache.similarity': score, 'cache.threshold': threshold }),
+                });
+                const result = { hit: false, confidence: 'miss' };
+                if (!isNaN(score)) {
+                    result.similarity = score;
+                    result.nearestMiss = { similarity: score, deltaToThreshold: score - threshold };
+                }
+                return result;
+            }
+            // Hit
+            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();
+            const matchedKey = parsed[0].key;
+            if (this.defaultTtl !== undefined && matchedKey) {
+                await this.client.expire(matchedKey, this.defaultTtl);
+            }
+            span.setAttributes({
+                'cache.hit': true, 'cache.similarity': score, 'cache.threshold': threshold,
+                'cache.confidence': confidence, 'cache.matched_key': matchedKey,
+                'cache.category': categoryLabel, ...timingAttrs,
+            });
+            return {
+                hit: true, response: parsed[0].fields['response'],
+                similarity: score, confidence, matchedKey,
+            };
+        });
+    }
+    async store(prompt, response, options) {
+        this.assertInitialized('store');
+        return this.traced('store', async (span) => {
+            const { vector: embedding, durationSec: embedSec } = await this.embed(prompt);
+            this.assertDimension(embedding);
+            const entryKey = `${this.entryPrefix}${(0, node_crypto_1.randomUUID)()}`;
+            const category = options?.category ?? '';
+            const model = options?.model ?? '';
+            try {
+                await this.client.hset(entryKey, {
+                    prompt, response, model, category,
+                    inserted_at: Date.now().toString(),
+                    metadata: JSON.stringify(options?.metadata ?? {}),
+                    embedding: (0, utils_1.encodeFloat32)(embedding),
+                });
+            }
+            catch (err) {
+                throw new errors_1.ValkeyCommandError('HSET', err);
+            }
+            const ttl = options?.ttl ?? this.defaultTtl;
+            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,
+            });
+            return entryKey;
+        });
+    }
+    /**
+     * Deletes all entries matching a valkey-search filter expression.
+     *
+     * **Security note:** `filter` is passed directly to FT.SEARCH. Only pass
+     * trusted, programmatically-constructed expressions — never unsanitised
+     * user input.
+     */
+    async invalidate(filter) {
+        this.assertInitialized('invalidate');
+        return this.traced('invalidate', async (span) => {
+            let rawResult;
+            try {
+                rawResult = await this.client.call('FT.SEARCH', this.indexName, filter, 'RETURN', '0', 'LIMIT', '0', String(INVALIDATE_BATCH_SIZE), 'DIALECT', '2');
+            }
+            catch (err) {
+                throw new errors_1.ValkeyCommandError('FT.SEARCH', err);
+            }
+            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,
+                });
+                return { deleted: 0, truncated: false };
+            }
+            const keys = parsed.map((r) => r.key);
+            const truncated = keys.length === INVALIDATE_BATCH_SIZE;
+            try {
+                await this.client.del(keys);
+            }
+            catch (err) {
+                throw new errors_1.ValkeyCommandError('DEL', err);
+            }
+            span.setAttributes({
+                'cache.name': this.name, 'cache.filter': filter,
+                'cache.deleted_count': keys.length, 'cache.truncated': truncated,
+            });
+            return { deleted: keys.length, truncated };
+        });
+    }
+    async stats() {
+        this.assertInitialized('stats');
+        const raw = await this.client.hgetall(this.statsKey);
+        const hits = parseInt(raw.hits ?? '0', 10);
+        const misses = parseInt(raw.misses ?? '0', 10);
+        const total = parseInt(raw.total ?? '0', 10);
+        return { hits, misses, total, hitRate: total === 0 ? 0 : hits / total };
+    }
+    async indexInfo() {
+        this.assertInitialized('indexInfo');
+        let raw;
+        try {
+            raw = await this.client.call('FT.INFO', this.indexName);
+        }
+        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]);
+        }
+        return { name: this.indexName, numDocs, dimension: this._dimension, indexingState };
+    }
+    // ── Private helpers ────────────────────────────────────────
+    async _doInitialize() {
+        const gen = this._initGeneration;
+        return this.traced('initialize', async () => {
+            const dim = await this.ensureIndexAndGetDimension();
+            // If flush() ran while we were initializing, don't overwrite its state.
+            if (this._initGeneration !== gen)
+                return;
+            this._dimension = dim;
+            this._initialized = true;
+        });
+    }
+    async ensureIndexAndGetDimension() {
+        // Try reading an existing index
+        try {
+            const info = (await this.client.call('FT.INFO', this.indexName));
+            const dim = this.parseDimensionFromInfo(info);
+            if (dim > 0)
+                return dim;
+            // Couldn't parse dimension from FT.INFO — fall back to probe
+            return (await this.embed('probe')).vector.length;
+        }
+        catch (err) {
+            if (err instanceof errors_1.EmbeddingError)
+                throw err;
+            if (!this.isIndexNotFoundError(err)) {
+                throw new errors_1.ValkeyCommandError('FT.INFO', err);
+            }
+        }
+        // Index doesn't exist — probe dimension and create it
+        const dim = (await this.embed('probe')).vector.length;
+        try {
+            await this.client.call('FT.CREATE', this.indexName, 'ON', 'HASH', 'PREFIX', '1', this.entryPrefix, 'SCHEMA', 'prompt', 'TEXT', 'NOSTEM', 'response', 'TEXT', 'NOSTEM', 'model', 'TAG', 'category', 'TAG', 'inserted_at', 'NUMERIC', 'SORTABLE', 'embedding', 'VECTOR', 'HNSW', '6', 'TYPE', 'FLOAT32', 'DIM', String(dim), 'DISTANCE_METRIC', 'COSINE');
+        }
+        catch (err) {
+            throw new errors_1.ValkeyCommandError('FT.CREATE', err);
+        }
+        return dim;
+    }
+    /** Wraps embedFn with error handling and duration tracking. */
+    async embed(text) {
+        const start = performance.now();
+        let vector;
+        try {
+            vector = await this.embedFn(text);
+        }
+        catch (err) {
+            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);
+        return { vector, durationSec };
+    }
+    /**
+     * Wraps a method body in an OTel span with automatic status, end, and
+     * operation duration metric. The span is passed to fn so callers can
+     * set attributes — but callers must NOT call span.end() or span.setStatus(),
+     * as traced() handles both.
+     */
+    async traced(operation, fn) {
+        const start = performance.now();
+        return this.telemetry.tracer.startActiveSpan(`semantic_cache.${operation}`, async (span) => {
+            try {
+                const result = await fn(span);
+                span.setStatus({ code: api_1.SpanStatusCode.OK });
+                return result;
+            }
+            catch (err) {
+                span.setStatus({ code: api_1.SpanStatusCode.ERROR, message: String(err) });
+                throw err;
+            }
+            finally {
+                span.end();
+                this.telemetry.metrics.operationDuration
+                    .labels({ cache_name: this.name, operation })
+                    .observe((performance.now() - start) / 1000);
+            }
+        });
+    }
+    /** Increment stats counters via pipeline. */
+    async recordStat(field) {
+        const pipeline = this.client.pipeline();
+        pipeline.hincrby(this.statsKey, 'total', 1);
+        pipeline.hincrby(this.statsKey, field, 1);
+        await pipeline.exec();
+    }
+    assertInitialized(method) {
+        if (!this._initialized) {
+            throw new errors_1.SemanticCacheUsageError(`SemanticCache.initialize() must be called before ${method}().`);
+        }
+    }
+    assertDimension(embedding) {
+        if (embedding.length !== this._dimension) {
+            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;

package/dist/adapters/ai.d.ts

@@ -0,0 +1,43 @@
+import type { LanguageModelMiddleware } from 'ai';
+import { SemanticCache } from '../SemanticCache';
+export interface SemanticCacheMiddlewareOptions {
+    /** A pre-configured SemanticCache instance. */
+    cache: SemanticCache;
+    /**
+     * Extract the prompt text from AI SDK messages.
+     * Default: joins all user message content text parts.
+     */
+    extractPrompt?: (params: {
+        prompt: Array<{
+            role: string;
+            content: unknown;
+        }>;
+    }) => string;
+    /**
+     * Extract the response text from an AI SDK result.
+     * Default: finds the first text content part.
+     */
+    extractResponse?: (result: {
+        content: Array<{
+            type: string;
+            text?: string;
+        }>;
+    }) => string;
+}
+/**
+ * Creates a LanguageModelMiddleware that adds semantic caching to any
+ * AI SDK language model. Use with wrapLanguageModel() from the 'ai' package.
+ *
+ * @example
+ * ```typescript
+ * import { wrapLanguageModel } from 'ai';
+ * import { openai } from '@ai-sdk/openai';
+ * import { createSemanticCacheMiddleware } from '@betterdb/semantic-cache/ai';
+ *
+ * const model = wrapLanguageModel({
+ *   model: openai('gpt-4o'),
+ *   middleware: createSemanticCacheMiddleware({ cache }),
+ * });
+ * ```
+ */
+export declare function createSemanticCacheMiddleware(opts: SemanticCacheMiddlewareOptions): LanguageModelMiddleware;

package/dist/adapters/ai.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSemanticCacheMiddleware = createSemanticCacheMiddleware;
+function defaultExtractPrompt(params) {
+    const parts = [];
+    for (const msg of params.prompt) {
+        if (msg.role === 'user' && Array.isArray(msg.content)) {
+            for (const part of msg.content) {
+                if (typeof part === 'object' &&
+                    part !== null &&
+                    'type' in part &&
+                    part.type === 'text' &&
+                    'text' in part) {
+                    parts.push(part.text);
+                }
+            }
+        }
+    }
+    return parts.join('\n');
+}
+function defaultExtractResponse(result) {
+    for (const part of result.content ?? []) {
+        if (part.type === 'text' && part.text) {
+            return part.text;
+        }
+    }
+    return '';
+}
+/**
+ * Creates a LanguageModelMiddleware that adds semantic caching to any
+ * AI SDK language model. Use with wrapLanguageModel() from the 'ai' package.
+ *
+ * @example
+ * ```typescript
+ * import { wrapLanguageModel } from 'ai';
+ * import { openai } from '@ai-sdk/openai';
+ * import { createSemanticCacheMiddleware } from '@betterdb/semantic-cache/ai';
+ *
+ * const model = wrapLanguageModel({
+ *   model: openai('gpt-4o'),
+ *   middleware: createSemanticCacheMiddleware({ cache }),
+ * });
+ * ```
+ */
+function createSemanticCacheMiddleware(opts) {
+    const { cache } = opts;
+    const extractPrompt = opts.extractPrompt ?? defaultExtractPrompt;
+    const extractResponse = opts.extractResponse ?? defaultExtractResponse;
+    let initPromise = null;
+    async function ensureInitialized() {
+        if (!initPromise) {
+            initPromise = cache.initialize().catch((err) => {
+                initPromise = null; // allow retry on transient failure
+                throw err;
+            });
+        }
+        await initPromise;
+    }
+    return {
+        specificationVersion: 'v3',
+        wrapGenerate: async ({ doGenerate, params }) => {
+            await ensureInitialized();
+            const prompt = extractPrompt(params);
+            if (prompt) {
+                try {
+                    const cached = await cache.check(prompt);
+                    if (cached.hit && cached.response) {
+                        // Return a minimal generate result. Cast required because
+                        // LanguageModelV3GenerateResult is imported transitively via the
+                        // LanguageModelMiddleware type — we construct it inline to avoid
+                        // depending on @ai-sdk/provider directly.
+                        return {
+                            content: [{ type: 'text', text: cached.response }],
+                            finishReason: 'stop',
+                            usage: { promptTokens: 0, completionTokens: 0 },
+                            warnings: [],
+                        };
+                    }
+                }
+                catch {
+                    // Swallow check errors — caching should not break inference
+                }
+            }
+            const result = await doGenerate();
+            if (prompt) {
+                const response = extractResponse(result);
+                if (response) {
+                    await cache.store(prompt, response).catch(() => {
+                        // Swallow store errors — caching should not break inference
+                    });
+                }
+            }
+            return result;
+        },
+        // wrapStream is intentionally not implemented — semantic caching of
+        // streaming responses is not supported in v0.1
+    };
+}

package/dist/adapters/langchain.d.ts

@@ -0,0 +1,29 @@
+import { BaseCache } from '@langchain/core/caches';
+import type { Generation } from '@langchain/core/outputs';
+import { SemanticCache } from '../SemanticCache';
+export interface BetterDBSemanticCacheOptions {
+    /** A pre-configured SemanticCache instance. */
+    cache: SemanticCache;
+    /**
+     * When true, cache lookups and stores are scoped to the specific LLM
+     * configuration (model, temperature, etc.). This prevents cross-model
+     * cache pollution but reduces hit rates — a prompt cached against gpt-4o
+     * will not hit against gpt-4o-mini even if the responses would be identical.
+     *
+     * The llm_string is hashed (SHA-256, first 16 hex chars) for use as a
+     * Valkey TAG field. The hash is deterministic: same LLM config = same hash.
+     *
+     * Default: false.
+     */
+    filterByModel?: boolean;
+}
+export declare class BetterDBSemanticCache extends BaseCache {
+    private cache;
+    private filterByModel;
+    private initPromise;
+    constructor(opts: BetterDBSemanticCacheOptions);
+    private ensureInitialized;
+    private modelHash;
+    lookup(prompt: string, llm_string: string): Promise<Generation[] | null>;
+    update(prompt: string, llm_string: string, return_val: Generation[]): Promise<void>;
+}

package/dist/adapters/langchain.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BetterDBSemanticCache = void 0;
+const caches_1 = require("@langchain/core/caches");
+const utils_1 = require("../utils");
+class BetterDBSemanticCache extends caches_1.BaseCache {
+    cache;
+    filterByModel;
+    initPromise = null;
+    constructor(opts) {
+        super();
+        this.cache = opts.cache;
+        this.filterByModel = opts.filterByModel ?? false;
+    }
+    async ensureInitialized() {
+        if (!this.initPromise) {
+            this.initPromise = this.cache.initialize().catch((err) => {
+                this.initPromise = null; // allow retry on transient failure
+                throw err;
+            });
+        }
+        await this.initPromise;
+    }
+    modelHash(llm_string) {
+        // llm_string is a serialised LangChain LLM config — not human-readable.
+        // Hash it to a stable, TAG-safe identifier.
+        return (0, utils_1.sha256)(llm_string).slice(0, 16);
+    }
+    async lookup(prompt, llm_string) {
+        await this.ensureInitialized();
+        const opts = {};
+        if (this.filterByModel) {
+            opts.filter = `@model:{${this.modelHash(llm_string)}}`;
+        }
+        const result = await this.cache.check(prompt, opts);
+        if (!result.hit || !result.response)
+            return null;
+        return [{ text: result.response }];
+    }
+    async update(prompt, llm_string, return_val) {
+        await this.ensureInitialized();
+        const text = return_val.map((g) => g.text).join('');
+        if (!text)
+            return;
+        await this.cache.store(prompt, text, {
+            model: this.modelHash(llm_string),
+        });
+    }
+}
+exports.BetterDBSemanticCache = BetterDBSemanticCache;

package/dist/errors.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Thrown when the caller does something wrong — e.g. calling check()
+ * before initialize(), or providing an embedding with the wrong dimension.
+ * The message is always actionable: it tells the caller what to fix.
+ */
+export declare class SemanticCacheUsageError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thrown when the embedding function fails.
+ * Check the underlying cause for the original error from the embedding provider.
+ */
+export declare class EmbeddingError extends Error {
+    readonly cause: unknown;
+    constructor(message: string, cause: unknown);
+}
+/**
+ * Thrown when a Valkey command fails unexpectedly.
+ * Includes the command name and the underlying error.
+ */
+export declare class ValkeyCommandError extends Error {
+    readonly command: string;
+    readonly cause: unknown;
+    constructor(command: string, cause: unknown);
+}