@betterdb/semantic-cache 0.1.0 → 0.2.0

package/dist/adapters/openai-responses.js

@@ -0,0 +1,112 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.prepareSemanticParams = prepareSemanticParams;
+const normalizer_1 = require("../normalizer");
+async function normalizeResponsesPart(part, normalizer) {
+    const t = part.type;
+    if (t === 'input_text' || t === 'output_text') {
+        return { type: 'text', text: part.text ?? '' };
+    }
+    if (t === 'input_image') {
+        const fileId = part.file_id;
+        const imageUrl = part.image_url;
+        const detail = part.detail;
+        let source;
+        let mediaType = 'image/*';
+        if (fileId) {
+            source = { type: 'fileId', fileId, provider: 'openai' };
+        }
+        else if (imageUrl) {
+            if (imageUrl.startsWith('data:')) {
+                const semi = imageUrl.indexOf(';');
+                if (semi > 5)
+                    mediaType = imageUrl.slice(5, semi);
+                source = { type: 'base64', data: imageUrl };
+            }
+            else {
+                source = { type: 'url', url: imageUrl };
+            }
+        }
+        else {
+            return null;
+        }
+        const ref = await normalizer({ kind: 'image', source });
+        const block = { type: 'binary', kind: 'image', mediaType, ref };
+        if (detail)
+            block.detail = detail;
+        return block;
+    }
+    if (t === 'input_file') {
+        const fileId = part.file_id;
+        const fileData = part.file_data;
+        const fileUrl = part.file_url;
+        const filename = part.filename;
+        let source;
+        let mediaType = 'application/octet-stream';
+        if (fileId) {
+            source = { type: 'fileId', fileId, provider: 'openai' };
+        }
+        else if (fileData) {
+            if (fileData.startsWith('data:')) {
+                const semi = fileData.indexOf(';');
+                if (semi > 5)
+                    mediaType = fileData.slice(5, semi);
+            }
+            source = { type: 'base64', data: fileData };
+        }
+        else if (fileUrl) {
+            source = { type: 'url', url: fileUrl };
+        }
+        else {
+            return null;
+        }
+        const ref = await normalizer({ kind: 'document', source });
+        const block = { type: 'binary', kind: 'document', mediaType, ref };
+        if (filename)
+            block.filename = filename;
+        return block;
+    }
+    return null;
+}
+/**
+ * Extract semantic cache params from OpenAI Responses API request params.
+ *
+ * Extracts the last user input text (or the instructions if no user input exists)
+ * for semantic similarity matching.
+ */
+async function prepareSemanticParams(params, opts) {
+    const normalizer = opts?.normalizer ?? normalizer_1.defaultNormalizer;
+    const p = params;
+    if (typeof p.input === 'string') {
+        return { text: p.input, model: p.model };
+    }
+    if (Array.isArray(p.input)) {
+        // Find last user/message input item
+        const userItems = p.input.filter((item) => item.role === 'user');
+        const lastUser = userItems[userItems.length - 1];
+        if (lastUser) {
+            const content = lastUser.content;
+            if (typeof content === 'string') {
+                return { text: content, model: p.model };
+            }
+            if (Array.isArray(content)) {
+                const blocks = [];
+                for (const part of content) {
+                    const block = await normalizeResponsesPart(part, normalizer);
+                    if (block)
+                        blocks.push(block);
+                }
+                const text = blocks
+                    .filter((b) => b.type === 'text')
+                    .map((b) => b.text)
+                    .join(' ');
+                return { text, blocks, model: p.model };
+            }
+        }
+    }
+    // Fall back to instructions
+    if (p.instructions) {
+        return { text: p.instructions, model: p.model };
+    }
+    return { text: '', model: p.model };
+}

package/dist/adapters/openai.d.ts

@@ -0,0 +1,42 @@
+/**
+ * OpenAI Chat Completions adapter for @betterdb/semantic-cache.
+ *
+ * Extracts the text to embed from OpenAI Chat Completions request params.
+ * Semantic caching keys on the last user message's text content because that
+ * is the actual query that changes between requests. Caching on the full
+ * conversation history would produce almost no hits in practice since each
+ * conversation turn is unique. Use the filter option on check() to scope
+ * results to a specific model or conversation context if needed.
+ *
+ * Usage:
+ *   import { prepareSemanticParams } from '@betterdb/semantic-cache/openai';
+ *   const { text, model } = await prepareSemanticParams(params);
+ *   const result = await cache.check(text, { filter: `@model:{${model}}` });
+ */
+import type { ChatCompletionCreateParams } from 'openai/resources/chat/completions';
+import type { BinaryBlock, TextBlock } from '../utils';
+import type { BinaryNormalizer } from '../normalizer';
+export interface OpenAISemanticPrepareOptions {
+    /** Binary content normalizer. Default: passthrough. */
+    normalizer?: BinaryNormalizer;
+}
+export interface SemanticParams {
+    /**
+     * The extracted text to embed. Pass to cache.check(text) or cache.store(text, response).
+     */
+    text: string;
+    /**
+     * Content blocks extracted from the last user message.
+     * Present when the message contains multi-part content (text + images/files).
+     * Pass to cache.check(blocks) for binary-aware cache lookups.
+     */
+    blocks?: (TextBlock | BinaryBlock)[];
+    /** Model name from the request params. Use as a TAG filter if desired. */
+    model?: string;
+}
+/**
+ * Extract semantic cache params from OpenAI Chat Completions request params.
+ *
+ * Extracts the last user message for semantic similarity matching.
+ */
+export declare function prepareSemanticParams(params: ChatCompletionCreateParams, opts?: OpenAISemanticPrepareOptions): Promise<SemanticParams>;

package/dist/adapters/openai.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.prepareSemanticParams = prepareSemanticParams;
+const normalizer_1 = require("../normalizer");
+async function normalizeContentPart(part, normalizer) {
+    if (part.type === 'text') {
+        return { type: 'text', text: part.text };
+    }
+    if (part.type === 'image_url') {
+        const url = part.image_url.url;
+        let source;
+        let mediaType = 'image/*';
+        if (url.startsWith('data:')) {
+            const semi = url.indexOf(';');
+            if (semi > 5)
+                mediaType = url.slice(5, semi);
+            source = { type: 'base64', data: url };
+        }
+        else {
+            source = { type: 'url', url };
+        }
+        const ref = await normalizer({ kind: 'image', source });
+        const block = { type: 'binary', kind: 'image', mediaType, ref };
+        if (part.image_url.detail)
+            block.detail = part.image_url.detail;
+        return block;
+    }
+    if (part.type === 'input_audio') {
+        const ref = await normalizer({
+            kind: 'audio',
+            source: { type: 'base64', data: part.input_audio.data },
+        });
+        return {
+            type: 'binary',
+            kind: 'audio',
+            mediaType: `audio/${part.input_audio.format}`,
+            ref,
+        };
+    }
+    if (part.type === 'file') {
+        const { file_id, file_data, filename } = part.file;
+        let source;
+        let mediaType = 'application/octet-stream';
+        if (file_id) {
+            source = { type: 'fileId', fileId: file_id, provider: 'openai' };
+        }
+        else if (file_data) {
+            if (file_data.startsWith('data:')) {
+                const semi = file_data.indexOf(';');
+                if (semi > 5)
+                    mediaType = file_data.slice(5, semi);
+            }
+            source = { type: 'base64', data: file_data };
+        }
+        else {
+            return null;
+        }
+        const ref = await normalizer({ kind: 'document', source });
+        const block = { type: 'binary', kind: 'document', mediaType, ref };
+        if (filename)
+            block.filename = filename;
+        return block;
+    }
+    return null;
+}
+/**
+ * Extract semantic cache params from OpenAI Chat Completions request params.
+ *
+ * Extracts the last user message for semantic similarity matching.
+ */
+async function prepareSemanticParams(params, opts) {
+    const normalizer = opts?.normalizer ?? normalizer_1.defaultNormalizer;
+    // Find last user message
+    const userMessages = params.messages.filter((m) => m.role === 'user');
+    if (userMessages.length === 0) {
+        return { text: '', model: params.model };
+    }
+    const lastUser = userMessages[userMessages.length - 1];
+    const content = lastUser.content;
+    if (typeof content === 'string') {
+        return { text: content, model: params.model };
+    }
+    if (Array.isArray(content)) {
+        const blocks = [];
+        for (const part of content) {
+            const block = await normalizeContentPart(part, normalizer);
+            if (block)
+                blocks.push(block);
+        }
+        const text = blocks
+            .filter((b) => b.type === 'text')
+            .map((b) => b.text)
+            .join(' ');
+        return { text, blocks, model: params.model };
+    }
+    return { text: '', model: params.model };
+}

package/dist/analytics.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Product analytics module for semantic-cache.
+ *
+ * Uses posthog-node as an optional peer dependency with a noop fallback.
+ * Instance identity is a UUID persisted in Valkey.
+ */
+export interface ValkeyLike {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<unknown>;
+}
+export interface Analytics {
+    init(client: ValkeyLike, name: string, configProps?: Record<string, unknown>): Promise<void>;
+    capture(event: string, properties?: Record<string, unknown>): void;
+    shutdown(): Promise<void>;
+}
+export interface AnalyticsOptions {
+    apiKey?: string;
+    host?: string;
+    disabled?: boolean;
+    /** Interval in ms for periodic stats snapshots. Default: 300_000 (5 min). 0 to disable. */
+    statsIntervalMs?: number;
+}
+export declare const NOOP_ANALYTICS: Analytics;
+export declare function createAnalytics(opts?: AnalyticsOptions): Promise<Analytics>;

package/dist/analytics.js

@@ -0,0 +1,116 @@
+"use strict";
+/**
+ * Product analytics module for semantic-cache.
+ *
+ * Uses posthog-node as an optional peer dependency with a noop fallback.
+ * Instance identity is a UUID persisted in Valkey.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NOOP_ANALYTICS = void 0;
+exports.createAnalytics = createAnalytics;
+const EVENT_PREFIX = 'semantic_cache:';
+// Build-time placeholders — replaced by scripts/inject-telemetry-defaults.mjs
+// When the placeholder is NOT replaced, the startsWith('__') guard treats it as unset.
+const BAKED_POSTHOG_API_KEY = '__BETTERDB_POSTHOG_API_KEY__';
+const BAKED_POSTHOG_HOST = '__BETTERDB_POSTHOG_HOST__';
+exports.NOOP_ANALYTICS = {
+    async init() { },
+    capture() { },
+    async shutdown() { },
+};
+function isTelemetryOptedOut() {
+    const val = process.env.BETTERDB_TELEMETRY;
+    return val !== undefined && ['false', '0', 'no', 'off'].includes(val.toLowerCase());
+}
+class PostHogAnalytics {
+    posthog;
+    distinctId = '';
+    constructor(posthog) {
+        this.posthog = posthog;
+    }
+    async init(client, name, configProps) {
+        const idKey = `${name}:__instance_id`;
+        let id = await client.get(idKey);
+        if (!id) {
+            id = crypto.randomUUID();
+            await client.set(idKey, id);
+        }
+        this.distinctId = id;
+        this.capture('cache_init', configProps);
+    }
+    capture(event, properties) {
+        try {
+            this.posthog.capture({
+                distinctId: this.distinctId,
+                event: `${EVENT_PREFIX}${event}`,
+                properties,
+            });
+        }
+        catch {
+            // never throw from analytics
+        }
+    }
+    async shutdown() {
+        try {
+            await this.posthog.shutdown();
+        }
+        catch {
+            // swallow
+        }
+    }
+}
+async function createAnalytics(opts) {
+    if (opts?.disabled || isTelemetryOptedOut()) {
+        return exports.NOOP_ANALYTICS;
+    }
+    // Key resolution: opts.apiKey → BETTERDB_POSTHOG_API_KEY env var → baked wheel value
+    const bakedKey = BAKED_POSTHOG_API_KEY.startsWith('__') ? undefined : BAKED_POSTHOG_API_KEY;
+    const apiKey = opts?.apiKey ?? process.env.BETTERDB_POSTHOG_API_KEY ?? bakedKey;
+    if (!apiKey) {
+        return exports.NOOP_ANALYTICS;
+    }
+    const bakedHost = BAKED_POSTHOG_HOST.startsWith('__') ? undefined : BAKED_POSTHOG_HOST;
+    const host = opts?.host ?? process.env.BETTERDB_POSTHOG_HOST ?? bakedHost;
+    try {
+        // @ts-ignore — posthog-node is an optional peer dep
+        const { PostHog } = await Promise.resolve().then(() => __importStar(require('posthog-node')));
+        const posthog = new PostHog(apiKey, { host, flushAt: 20, flushInterval: 10_000 });
+        return new PostHogAnalytics(posthog);
+    }
+    catch {
+        return exports.NOOP_ANALYTICS;
+    }
+}

package/dist/cluster.d.ts

@@ -0,0 +1,10 @@
+import type Valkey from 'iovalkey';
+/**
+ * Perform a SCAN across all master nodes if the client is a Cluster instance,
+ * or on the single client if standalone. Calls `onKeys` with each batch of
+ * matched keys. The caller handles what to do with them (GET, DEL, etc.).
+ *
+ * This is the single place in the codebase that handles the cluster vs
+ * standalone SCAN divergence.
+ */
+export declare function clusterScan(client: Valkey, pattern: string, onKeys: (keys: string[], nodeClient: Valkey) => Promise<void>, count?: number): Promise<void>;

package/dist/cluster.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clusterScan = clusterScan;
+const iovalkey_1 = require("iovalkey");
+const errors_1 = require("./errors");
+function getMasterNodes(client) {
+    if (!(client instanceof iovalkey_1.Cluster))
+        return [client];
+    // Cast needed: TypeScript can't narrow Valkey & Cluster because both classes
+    // share a private `reconnectTimeout` field, collapsing the intersection to never.
+    return client.nodes('master');
+}
+/**
+ * Perform a SCAN across all master nodes if the client is a Cluster instance,
+ * or on the single client if standalone. Calls `onKeys` with each batch of
+ * matched keys. The caller handles what to do with them (GET, DEL, etc.).
+ *
+ * This is the single place in the codebase that handles the cluster vs
+ * standalone SCAN divergence.
+ */
+async function clusterScan(client, pattern, onKeys, count = 100) {
+    const nodes = getMasterNodes(client);
+    if (nodes.length === 0) {
+        throw new errors_1.ValkeyCommandError('SCAN', new Error('cluster has no master nodes visible'));
+    }
+    for (const nodeClient of nodes) {
+        let cursor = '0';
+        do {
+            let scanResult;
+            try {
+                scanResult = await nodeClient.scan(cursor, 'MATCH', pattern, 'COUNT', count);
+            }
+            catch (err) {
+                throw new errors_1.ValkeyCommandError('SCAN', err);
+            }
+            cursor = scanResult[0];
+            const keys = scanResult[1];
+            if (keys.length > 0) {
+                await onKeys(keys, nodeClient);
+            }
+        } while (cursor !== '0');
+    }
+}

package/dist/defaultCostTable.d.ts

@@ -0,0 +1,11 @@
+/**
+ * AUTO-GENERATED. Do not edit by hand.
+ * Source: https://github.com/BerriAI/litellm/blob/main/model_prices_and_context_window.json
+ * Commit: 26fcbc9
+ * Fetched: 2026-04-21T17:10:19.295Z
+ * Entries: 1971
+ *
+ * Regenerate: pnpm --filter @betterdb/semantic-cache update:pricing
+ */
+import type { ModelCost } from './types';
+export declare const DEFAULT_COST_TABLE: Record<string, ModelCost>;