@betterdb/semantic-cache 0.1.0 → 0.4.0

package/dist/adapters/ai.js

@@ -69,10 +69,15 @@ function createSemanticCacheMiddleware(opts) {
                         // LanguageModelV3GenerateResult is imported transitively via the
                         // LanguageModelMiddleware type — we construct it inline to avoid
                         // depending on @ai-sdk/provider directly.
+                        //
+                        // AI SDK v6 (specificationVersion v3) uses inputTokens/outputTokens
+                        // (not promptTokens/completionTokens). request is required to avoid
+                        // "Cannot read properties of undefined" in the SDK pipeline.
                         return {
                             content: [{ type: 'text', text: cached.response }],
                             finishReason: 'stop',
-                            usage: { promptTokens: 0, completionTokens: 0 },
+                            usage: { inputTokens: 0, outputTokens: 0 },
+                            request: { body: '' },
                             warnings: [],
                         };
                     }

package/dist/adapters/anthropic.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Anthropic Messages API adapter for @betterdb/semantic-cache.
+ *
+ * Extracts the text to embed from Anthropic Messages API request params.
+ * Semantic caching keys on the last user message's text content because that
+ * is the actual query. See openai.ts for the full rationale.
+ *
+ * Usage:
+ *   import { prepareSemanticParams } from '@betterdb/semantic-cache/anthropic';
+ *   const { text, model } = await prepareSemanticParams(params);
+ *   const result = await cache.check(text);
+ */
+import type { MessageCreateParamsNonStreaming } from '@anthropic-ai/sdk/resources';
+import type { BinaryBlock, TextBlock } from '../utils';
+import type { BinaryNormalizer } from '../normalizer';
+export interface AnthropicSemanticPrepareOptions {
+    /** Binary content normalizer. Default: passthrough. */
+    normalizer?: BinaryNormalizer;
+}
+export interface SemanticParams {
+    text: string;
+    blocks?: (TextBlock | BinaryBlock)[];
+    model?: string;
+}
+/**
+ * Extract semantic cache params from Anthropic Messages API request params.
+ *
+ * Extracts the last user message text for semantic similarity matching.
+ * The system prompt is not included in the cache key because it rarely changes
+ * within a deployment and would prevent hits across conversations.
+ */
+export declare function prepareSemanticParams(params: MessageCreateParamsNonStreaming, opts?: AnthropicSemanticPrepareOptions): Promise<SemanticParams>;

package/dist/adapters/anthropic.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.prepareSemanticParams = prepareSemanticParams;
+const normalizer_1 = require("../normalizer");
+async function normalizeBlock(block, normalizer) {
+    const type = block.type;
+    if (type === 'text') {
+        const b = block;
+        return { type: 'text', text: b.text };
+    }
+    if (type === 'image') {
+        const b = block;
+        const src = b.source;
+        let source;
+        let mediaType = 'image/*';
+        if (src.type === 'base64') {
+            source = { type: 'base64', data: src.data };
+            mediaType = src.media_type ?? 'image/*';
+        }
+        else if (src.type === 'url') {
+            source = { type: 'url', url: src.url };
+        }
+        else if (src.type === 'file') {
+            source = { type: 'fileId', fileId: src.file_id, provider: 'anthropic' };
+        }
+        else {
+            return null;
+        }
+        const ref = await normalizer({ kind: 'image', source });
+        return { type: 'binary', kind: 'image', mediaType, ref };
+    }
+    if (type === 'document') {
+        const b = block;
+        const src = b.source;
+        let source;
+        let mediaType = 'application/octet-stream';
+        if (src.type === 'base64') {
+            source = { type: 'base64', data: src.data };
+            mediaType = src.media_type ?? 'application/pdf';
+        }
+        else if (src.type === 'text') {
+            const encoded = Buffer.from(src.text).toString('base64');
+            source = { type: 'base64', data: encoded };
+            mediaType = 'text/plain';
+        }
+        else if (src.type === 'url') {
+            source = { type: 'url', url: src.url };
+            mediaType = 'application/pdf';
+        }
+        else if (src.type === 'file') {
+            source = { type: 'fileId', fileId: src.file_id, provider: 'anthropic' };
+        }
+        else {
+            return null;
+        }
+        const ref = await normalizer({ kind: 'document', source });
+        return { type: 'binary', kind: 'document', mediaType, ref };
+    }
+    return null;
+}
+/**
+ * Extract semantic cache params from Anthropic Messages API request params.
+ *
+ * Extracts the last user message text for semantic similarity matching.
+ * The system prompt is not included in the cache key because it rarely changes
+ * within a deployment and would prevent hits across conversations.
+ */
+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 normalizeBlock(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/adapters/langchain.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BetterDBSemanticCache = void 0;
 const caches_1 = require("@langchain/core/caches");
+const messages_1 = require("@langchain/core/messages");
 const utils_1 = require("../utils");
 class BetterDBSemanticCache extends caches_1.BaseCache {
     cache;
@@ -35,7 +36,11 @@ class BetterDBSemanticCache extends caches_1.BaseCache {
         const result = await this.cache.check(prompt, opts);
         if (!result.hit || !result.response)
             return null;
-        return [{ text: result.response }];
+        // Return a ChatGeneration-shaped object with a proper AIMessage so that
+        // ChatOpenAI and other chat models can unwrap it correctly on cache hit.
+        // Plain { text } without a message causes "Cannot read properties of undefined"
+        // when the model tries to access response.content.
+        return [{ text: result.response, message: new messages_1.AIMessage(result.response) }];
     }
     async update(prompt, llm_string, return_val) {
         await this.ensureInitialized();

package/dist/adapters/langgraph.d.ts

@@ -0,0 +1,104 @@
+/**
+ * LangGraph BaseStore adapter for @betterdb/semantic-cache.
+ *
+ * BetterDBSemanticStore implements the LangGraph BaseStore interface,
+ * enabling similarity-based memory retrieval from a SemanticCache instance.
+ *
+ * When to use this vs @betterdb/agent-cache/langgraph:
+ * - Use @betterdb/agent-cache/langgraph (BetterDBSaver) for exact-match checkpoint
+ *   persistence - storing and retrieving agent state snapshots by checkpoint ID.
+ * - Use BetterDBSemanticStore (this class) for similarity-based memory retrieval -
+ *   finding the most semantically relevant past observations, documents, or facts
+ *   for a given query.
+ * They can coexist on the same Valkey instance with different key prefixes.
+ *
+ * Storage layout:
+ *   {name}:entry:{uuid}  - HSET entry per item (via SemanticCache.store)
+ *   namespace is stored as the 'category' tag on entries for filtered recall
+ *
+ * Limitations:
+ * - get() uses a Valkey SCAN for the deterministic key and may be slow on large stores.
+ *   For high-frequency get() patterns, prefer a dedicated hash store (agent-cache session tier).
+ * - delete() uses invalidate() which is limited to 1000 entries per call and requires
+ *   FT.SEARCH to find matching keys.
+ */
+import type { SemanticCache } from '../SemanticCache';
+/** A stored item in the semantic memory store. */
+export interface Item {
+    /** Dot-separated namespace path (e.g. ['user', 'alice', 'memories']). */
+    namespace: string[];
+    /** Unique key within the namespace. */
+    key: string;
+    /** The stored value. */
+    value: Record<string, unknown>;
+    /** Creation timestamp as ISO string. */
+    createdAt: string;
+    /** Last update timestamp as ISO string. */
+    updatedAt: string;
+}
+/** Options for the search() method. */
+export interface SearchOptions {
+    /** Natural-language query for similarity search. */
+    query?: string;
+    /** Maximum number of results. Default: 10. */
+    limit?: number;
+    /** Similarity threshold override (cosine distance, 0-2). */
+    threshold?: number;
+}
+export interface BetterDBSemanticStoreOptions {
+    /**
+     * A pre-configured SemanticCache instance.
+     * The cache must be initialized before calling store methods.
+     */
+    cache: SemanticCache;
+    /**
+     * Field to embed from stored values when no explicit query is provided.
+     * Default: 'content'. The value of this field (if a string) is used as
+     * the embedding text when put() is called without an explicit embed field.
+     */
+    embedField?: string;
+}
+/**
+ * LangGraph-compatible semantic memory store backed by SemanticCache.
+ *
+ * Implements a subset of the LangGraph BaseStore interface sufficient for
+ * use as an in-memory store with similarity recall.
+ */
+export declare class BetterDBSemanticStore {
+    private readonly cache;
+    private readonly embedField;
+    constructor(opts: BetterDBSemanticStoreOptions);
+    /**
+     * Store a value at namespace/key.
+     * The embedField value (if present and a string) is used as the embedding text.
+     * Falls back to JSON stringified value if embedField is absent.
+     */
+    put(namespace: string[], key: string, value: Record<string, unknown>): Promise<void>;
+    /**
+     * Retrieve a value by exact namespace and key.
+     * Paginates through all entries in the namespace using stable SORTBY ordering.
+     */
+    get(namespace: string[], key: string): Promise<Item | null>;
+    /**
+     * Search the namespace using similarity.
+     * When query is provided, embeds it and returns the k most similar entries.
+     * When query is absent, returns all entries in the namespace (up to limit).
+     */
+    search(namespace: string[], options?: SearchOptions): Promise<Item[]>;
+    /**
+     * Delete the specific entry at namespace/key.
+     * Pages through the namespace using stable SORTBY ordering; adjusts the offset
+     * for each deleted entry so no entries are skipped in large namespaces.
+     */
+    delete(namespace: string[], key: string): Promise<void>;
+    /**
+     * Batch put/delete multiple items.
+     * Executes sequentially to avoid races when the same (namespace, key) appears
+     * more than once: concurrent delete+put pairs can interleave and leave duplicates.
+     */
+    batch(writes: Array<{
+        namespace: string[];
+        key: string;
+        value: Record<string, unknown> | null;
+    }>): Promise<void>;
+}

package/dist/adapters/langgraph.js

@@ -0,0 +1,271 @@
+"use strict";
+/**
+ * LangGraph BaseStore adapter for @betterdb/semantic-cache.
+ *
+ * BetterDBSemanticStore implements the LangGraph BaseStore interface,
+ * enabling similarity-based memory retrieval from a SemanticCache instance.
+ *
+ * When to use this vs @betterdb/agent-cache/langgraph:
+ * - Use @betterdb/agent-cache/langgraph (BetterDBSaver) for exact-match checkpoint
+ *   persistence - storing and retrieving agent state snapshots by checkpoint ID.
+ * - Use BetterDBSemanticStore (this class) for similarity-based memory retrieval -
+ *   finding the most semantically relevant past observations, documents, or facts
+ *   for a given query.
+ * They can coexist on the same Valkey instance with different key prefixes.
+ *
+ * Storage layout:
+ *   {name}:entry:{uuid}  - HSET entry per item (via SemanticCache.store)
+ *   namespace is stored as the 'category' tag on entries for filtered recall
+ *
+ * Limitations:
+ * - get() uses a Valkey SCAN for the deterministic key and may be slow on large stores.
+ *   For high-frequency get() patterns, prefer a dedicated hash store (agent-cache session tier).
+ * - delete() uses invalidate() which is limited to 1000 entries per call and requires
+ *   FT.SEARCH to find matching keys.
+ */
+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.BetterDBSemanticStore = void 0;
+const utils_1 = require("../utils");
+function namespaceKey(namespace) {
+    return namespace.join(':');
+}
+function namespaceToCategory(namespace) {
+    // Replace path separators (. and /) only, leaving : intact as the namespace-segment
+    // separator. Matches the Python implementation for cross-language compatibility.
+    return namespaceKey(namespace).replace(/[./]/g, '_');
+}
+/**
+ * LangGraph-compatible semantic memory store backed by SemanticCache.
+ *
+ * Implements a subset of the LangGraph BaseStore interface sufficient for
+ * use as an in-memory store with similarity recall.
+ */
+class BetterDBSemanticStore {
+    cache;
+    embedField;
+    constructor(opts) {
+        this.cache = opts.cache;
+        this.embedField = opts.embedField ?? 'content';
+    }
+    /**
+     * Store a value at namespace/key.
+     * The embedField value (if present and a string) is used as the embedding text.
+     * Falls back to JSON stringified value if embedField is absent.
+     */
+    async put(namespace, key, value) {
+        // Upsert: remove any existing entry for this key before writing so repeated
+        // put() calls don't accumulate stale duplicates.
+        await this.delete(namespace, key);
+        const embedText = typeof value[this.embedField] === 'string'
+            ? value[this.embedField]
+            : JSON.stringify(value);
+        const category = namespaceToCategory(namespace);
+        const now = new Date().toISOString();
+        const item = {
+            namespace,
+            key,
+            value,
+            createdAt: now,
+            updatedAt: now,
+        };
+        await this.cache.store(embedText, JSON.stringify(item), {
+            category,
+            metadata: { key, namespace: namespaceKey(namespace) },
+        });
+    }
+    /**
+     * Retrieve a value by exact namespace and key.
+     * Paginates through all entries in the namespace using stable SORTBY ordering.
+     */
+    async get(namespace, key) {
+        const category = namespaceToCategory(namespace);
+        const catFilter = `@category:{${(0, utils_1.escapeTag)(category)}}`;
+        const { parseFtSearchResponse } = await Promise.resolve().then(() => __importStar(require('../utils')));
+        const BATCH = 100;
+        let offset = 0;
+        while (true) {
+            let raw;
+            try {
+                raw = await this.cache._searchEntries(catFilter, BATCH, offset);
+            }
+            catch {
+                return null;
+            }
+            const entries = parseFtSearchResponse(raw);
+            if (entries.length === 0)
+                break;
+            for (const entry of entries) {
+                const responseStr = entry.fields['response'];
+                if (!responseStr)
+                    continue;
+                try {
+                    const item = JSON.parse(responseStr);
+                    if (item.key === key)
+                        return item;
+                }
+                catch { /* skip corrupt */ }
+            }
+            if (entries.length < BATCH)
+                break;
+            offset += BATCH;
+        }
+        return null;
+    }
+    /**
+     * Search the namespace using similarity.
+     * When query is provided, embeds it and returns the k most similar entries.
+     * When query is absent, returns all entries in the namespace (up to limit).
+     */
+    async search(namespace, options) {
+        const limit = options?.limit ?? 10;
+        const query = options?.query;
+        const category = namespaceToCategory(namespace);
+        if (query) {
+            const { encodeFloat32, parseFtSearchResponse } = await Promise.resolve().then(() => __importStar(require('../utils')));
+            const threshold = options?.threshold ?? this.cache._defaultThreshold;
+            const { vector } = await this.cache._embedText(query);
+            const filterExpr = `(@category:{${(0, utils_1.escapeTag)(category)}})`;
+            const knnQuery = `${filterExpr}=>[KNN ${limit} @embedding $vec AS __score]`;
+            let raw;
+            try {
+                raw = await this.cache.client.call('FT.SEARCH', this.cache.indexName, knnQuery, 'PARAMS', '2', 'vec', encodeFloat32(vector), 'LIMIT', '0', String(limit), 'DIALECT', '2');
+            }
+            catch {
+                return [];
+            }
+            const items = [];
+            for (const entry of parseFtSearchResponse(raw)) {
+                const scoreVal = parseFloat(entry.fields['__score'] ?? 'NaN');
+                if (isNaN(scoreVal) || scoreVal > threshold)
+                    continue;
+                const responseStr = entry.fields['response'];
+                if (responseStr) {
+                    try {
+                        items.push(JSON.parse(responseStr));
+                    }
+                    catch { /* skip */ }
+                }
+            }
+            return items;
+        }
+        // No query — return all entries in namespace (up to limit) using _searchEntries
+        const { parseFtSearchResponse } = await Promise.resolve().then(() => __importStar(require('../utils')));
+        try {
+            const result = await this.cache._searchEntries(`@category:{${(0, utils_1.escapeTag)(category)}}`, limit, 0);
+            const items = [];
+            for (const entry of parseFtSearchResponse(result)) {
+                const responseStr = entry.fields['response'];
+                if (responseStr) {
+                    try {
+                        items.push(JSON.parse(responseStr));
+                    }
+                    catch { /* skip */ }
+                }
+            }
+            return items;
+        }
+        catch {
+            return [];
+        }
+    }
+    /**
+     * Delete the specific entry at namespace/key.
+     * Pages through the namespace using stable SORTBY ordering; adjusts the offset
+     * for each deleted entry so no entries are skipped in large namespaces.
+     */
+    async delete(namespace, key) {
+        const category = namespaceToCategory(namespace);
+        const catFilter = `@category:{${(0, utils_1.escapeTag)(category)}}`;
+        const client = this.cache.client;
+        const { parseFtSearchResponse } = await Promise.resolve().then(() => __importStar(require('../utils')));
+        const BATCH = 100;
+        let offset = 0;
+        while (true) {
+            let raw;
+            try {
+                raw = await this.cache._searchEntries(catFilter, BATCH, offset);
+            }
+            catch {
+                return;
+            }
+            const entries = parseFtSearchResponse(raw);
+            if (entries.length === 0)
+                break;
+            let deletedCount = 0;
+            for (const entry of entries) {
+                const responseStr = entry.fields['response'];
+                if (!responseStr)
+                    continue;
+                try {
+                    const item = JSON.parse(responseStr);
+                    if (item.key === key) {
+                        await client.del(entry.key).catch(() => { });
+                        deletedCount++;
+                    }
+                }
+                catch { /* skip corrupt */ }
+            }
+            if (deletedCount > 0) {
+                // After deletions, Valkey Search async indexing may keep deleted entries
+                // visible briefly — offset arithmetic is unreliable. Re-scan from 0 to
+                // catch any remaining copies (mirrors the Python implementation).
+                offset = 0;
+            }
+            else if (entries.length < BATCH) {
+                break; // Last page with no matches — done
+            }
+            else {
+                offset += BATCH; // No deletions this page, advance safely
+            }
+        }
+    }
+    /**
+     * Batch put/delete multiple items.
+     * Executes sequentially to avoid races when the same (namespace, key) appears
+     * more than once: concurrent delete+put pairs can interleave and leave duplicates.
+     */
+    async batch(writes) {
+        for (const w of writes) {
+            if (w.value === null) {
+                await this.delete(w.namespace, w.key);
+            }
+            else {
+                await this.put(w.namespace, w.key, w.value);
+            }
+        }
+    }
+}
+exports.BetterDBSemanticStore = BetterDBSemanticStore;

package/dist/adapters/llamaindex.d.ts

@@ -0,0 +1,32 @@
+/**
+ * LlamaIndex adapter for @betterdb/semantic-cache.
+ *
+ * Extracts the text to embed from LlamaIndex ChatMessage arrays.
+ * Semantic caching keys on the last user message's text content.
+ * See openai.ts for the full rationale.
+ *
+ * Usage:
+ *   import { prepareSemanticParams } from '@betterdb/semantic-cache/llamaindex';
+ *   const { text, model } = prepareSemanticParams(messages, { model: 'gpt-4o' });
+ *   const result = await cache.check(text);
+ */
+import type { ChatMessage } from '@llamaindex/core/llms';
+import type { BinaryBlock, TextBlock } from '../utils';
+import type { BinaryNormalizer } from '../normalizer';
+export interface LlamaIndexSemanticPrepareOptions {
+    /** Model name to include in the returned SemanticParams. */
+    model?: string;
+    /** Binary content normalizer. Default: passthrough. */
+    normalizer?: BinaryNormalizer;
+}
+export interface SemanticParams {
+    text: string;
+    blocks?: (TextBlock | BinaryBlock)[];
+    model?: string;
+}
+/**
+ * Extract semantic cache params from a LlamaIndex ChatMessage array.
+ *
+ * Extracts the last user message for semantic similarity matching.
+ */
+export declare function prepareSemanticParams(messages: ChatMessage[], opts?: LlamaIndexSemanticPrepareOptions): Promise<SemanticParams>;

package/dist/adapters/llamaindex.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.prepareSemanticParams = prepareSemanticParams;
+const normalizer_1 = require("../normalizer");
+async function normalizeDetail(part, normalizer) {
+    if (part.type === 'text') {
+        return { type: 'text', text: part.text ?? '' };
+    }
+    if (part.type === 'image_url' && part.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 });
+        return { type: 'binary', kind: 'image', mediaType, ref };
+    }
+    if (part.type === 'file' && part.data) {
+        const ref = await normalizer({ kind: 'document', source: { type: 'base64', data: part.data } });
+        return {
+            type: 'binary',
+            kind: 'document',
+            mediaType: part.mimeType ?? 'application/octet-stream',
+            ref,
+        };
+    }
+    if ((part.type === 'audio' || part.type === 'image') && part.data) {
+        const kind = part.type === 'audio' ? 'audio' : 'image';
+        const ref = await normalizer({ kind, source: { type: 'base64', data: part.data } });
+        return {
+            type: 'binary',
+            kind,
+            mediaType: part.mimeType ?? (kind === 'audio' ? 'audio/*' : 'image/*'),
+            ref,
+        };
+    }
+    return null;
+}
+/**
+ * Extract semantic cache params from a LlamaIndex ChatMessage array.
+ *
+ * Extracts the last user message for semantic similarity matching.
+ */
+async function prepareSemanticParams(messages, opts) {
+    const normalizer = opts?.normalizer ?? normalizer_1.defaultNormalizer;
+    // Find last user message
+    const userMessages = messages.filter((m) => m.role === 'user');
+    if (userMessages.length === 0) {
+        return { text: '', model: opts?.model };
+    }
+    const lastUser = userMessages[userMessages.length - 1];
+    if (typeof lastUser.content === 'string') {
+        return { text: lastUser.content, model: opts?.model };
+    }
+    if (Array.isArray(lastUser.content)) {
+        const blocks = [];
+        for (const part of lastUser.content) {
+            const block = await normalizeDetail(part, normalizer);
+            if (block)
+                blocks.push(block);
+        }
+        const text = blocks
+            .filter((b) => b.type === 'text')
+            .map((b) => b.text)
+            .join(' ');
+        return { text, blocks, model: opts?.model };
+    }
+    return { text: '', model: opts?.model };
+}

package/dist/adapters/openai-responses.d.ts

@@ -0,0 +1,31 @@
+/**
+ * OpenAI Responses API adapter for @betterdb/semantic-cache.
+ *
+ * Extracts the text to embed from OpenAI Responses API request params.
+ * Semantic caching keys on the last user input text. See openai.ts for
+ * the rationale for keying on the last user message rather than full history.
+ *
+ * Usage:
+ *   import { prepareSemanticParams } from '@betterdb/semantic-cache/openai-responses';
+ *   const { text, model } = await prepareSemanticParams(params);
+ *   const result = await cache.check(text);
+ */
+import type { ResponseCreateParams } from 'openai/resources/responses/responses';
+import type { BinaryBlock, TextBlock } from '../utils';
+import type { BinaryNormalizer } from '../normalizer';
+export interface OpenAIResponsesSemanticPrepareOptions {
+    /** Binary content normalizer. Default: passthrough. */
+    normalizer?: BinaryNormalizer;
+}
+export interface SemanticParams {
+    text: string;
+    blocks?: (TextBlock | BinaryBlock)[];
+    model?: string;
+}
+/**
+ * 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.
+ */
+export declare function prepareSemanticParams(params: ResponseCreateParams, opts?: OpenAIResponsesSemanticPrepareOptions): Promise<SemanticParams>;