@oracle/langchain-oracledb 0.2.0 → 1.1.0

package/dist/cache.d.cts

@@ -0,0 +1,168 @@
+import type { Generation } from "@langchain/core/outputs";
+import type { EmbeddingsInterface } from "@langchain/core/embeddings";
+import { BaseCache } from "@langchain/core/caches";
+import { OracleDBVSArgs, IndexParams } from "./vectorstores.js";
+import { OracleDBClient, OracleDBClientProvider } from "./utils.js";
+export type OracleSemanticCacheDBConfig = Omit<OracleDBVSArgs, "tableName"> & {
+    tableName?: string;
+};
+export interface OracleSemanticCacheOptions {
+    createIndexIfMissing?: boolean;
+    indexName?: string;
+    indexParams?: IndexParams;
+    scoreThreshold?: number;
+}
+export interface OracleCacheClearOptions {
+    prompt?: string;
+    llmKey?: string;
+}
+/**
+ * Caches model generations in Oracle Database using vector similarity between prompts.
+ * @example
+ * ```typescript
+ * // `embeddings` is an EmbeddingsInterface and `pool` is an Oracle connection pool.
+ * const cache = new OracleSemanticCache(embeddings, { client: pool }, {
+ *   scoreThreshold: 0.2,
+ *   createIndexIfMissing: true,
+ * });
+ * ```
+ */
+export declare class OracleSemanticCache extends BaseCache {
+    private readonly vectorStore;
+    readonly createIndexIfMissing?: boolean;
+    readonly indexName?: string;
+    readonly indexParams?: IndexParams;
+    readonly scoreThreshold?: number;
+    private readonly LLM_HASH;
+    private readonly PROMPT_HASH;
+    private readonly RETURN_VAL;
+    /**
+     * Creates a semantic cache instance without performing database setup.
+     *
+     * @param {EmbeddingsInterface} embeddings Embedding model used to vectorize prompts.
+     * @param {OracleSemanticCacheDBConfig} dbConfig Oracle vector-store configuration.
+     * @param {OracleDBClient | OracleDBClientProvider} dbConfig.client Connection, pool, or async provider to use.
+     * @param {string} dbConfig.tableName Cache table name. Defaults to `langchain_semantic_cache`.
+     *
+     * @param {OracleSemanticCacheOptions} options Optional index and distance threshold settings.
+     * @param {boolean} options.createIndexIfMissing Whether initialize() creates a vector index
+     *   if it does not exist. Defaults to `false`.
+     * @param {number} options.scoreThreshold Maximum vector distance accepted for a cache hit.
+     *   Lower distance values indicate closer matches.
+     *
+     * @throws If the client is missing, the table identifier is invalid,
+     * or the distance threshold is negative.
+     */
+    constructor(embeddings: EmbeddingsInterface, dbConfig: OracleSemanticCacheDBConfig, options?: OracleSemanticCacheOptions);
+    /**
+     * Initializes the underlying vector store and creates the optional vector index.
+     * @returns Promise that resolves when database setup completes.
+     */
+    initialize(): Promise<void>;
+    private cacheEntryId;
+    /**
+     * Retrieves the nearest cached response for the given model configuration key.
+     * @param {string} prompt Prompt to embed and search for.
+     * @param {string} llmKey Key identifying the model and its configuration.
+     * @returns Cached generations, or `null` when no match passes the threshold or the payload is malformed.
+     * @throws If search fails or deserialization encounters an unexpected error.
+     */
+    lookup(prompt: string, llmKey: string): Promise<Generation[] | null>;
+    /**
+     * Inserts or updates the entry for an exact prompt and model configuration key.
+     * Skips the entire update if any generation contains valid or invalid tool calls,
+     * avoiding reuse of procedural responses within an agent loop.
+     * @param {string} prompt Prompt to embed and store.
+     * @param {string} llmKey Key identifying the model and its configuration.
+     * @param {Generation[]} value Model generations to cache.
+     * @returns Promise that resolves when the write completes or the update is skipped.
+     */
+    update(prompt: string, llmKey: string, value: Generation[]): Promise<void>;
+    /**
+     * Deletes entries matching all supplied exact filters, without similarity search.
+     * With no filters, deletes every entry in the table.
+     * @param {OracleCacheClearOptions} options Optional prompt and model configuration filters.
+     * @param {string} options.prompt Optional prompt to match exactly.
+     * @param {string} options.llmKey Optional model configuration key to match exactly.
+     * @returns Promise that resolves when deletion has been committed.
+     * @throws If an unsupported filter is supplied or deletion fails.
+     */
+    clear(options?: OracleCacheClearOptions): Promise<void>;
+    /**
+     * Drops and purges the semantic cache table if it exists, removing all entries.
+     * @param {OracleDBClient | OracleDBClientProvider} client Connection, pool, or async provider to use.
+     * @param {string} tableName Table to drop. Defaults to `langchain_semantic_cache`.
+     * @returns Promise that resolves when the table has been dropped or does not exist.
+     */
+    static dropTable(client: OracleDBClient | OracleDBClientProvider, tableName?: string): Promise<void>;
+}
+/**
+ * Caches model generations by exact prompt and model configuration key in Oracle Database.
+ * Lookup uses a hashed primary key and does not require an embedding model.
+ *
+ * @example
+ * ```typescript
+ * // `pool` is an Oracle connection pool.
+ * const cache = new OracleCache(pool);
+ * await cache.initialize();
+ * await cache.update("Hello", "model-config", [{ text: "Hi!" }]);
+ * const generations = await cache.lookup("Hello", "model-config");
+ * ```
+ */
+export declare class OracleCache extends BaseCache {
+    readonly client: OracleDBClient | OracleDBClientProvider;
+    readonly tableName: string;
+    private readonly quotedTableName;
+    /**
+     * Creates an exact cache instance without performing database setup.
+     * @param {OracleDBClient | OracleDBClientProvider} client Connection, pool, or async provider to use.
+     * @param {string} tableName Cache table name. Defaults to `langchain_exact_cache`.
+     * @throws If the client is missing or the table identifier is invalid.
+     */
+    constructor(client: OracleDBClient | OracleDBClientProvider, tableName?: string);
+    /**
+     * Creates the cache table if it does not already exist.
+     * @returns Promise that resolves when database setup completes.
+     */
+    initialize(): Promise<void>;
+    /** Stores serialized generations in a CLOB, with separate hashes for filtered deletion. */
+    private ensureTable;
+    private encodeKey;
+    private cacheEntryId;
+    /**
+     * Retrieves the cached response for an exact prompt and model configuration key.
+     * Restored chat message IDs are cleared before returning the generations.
+     * @param {string} prompt Exact prompt used when writing the entry.
+     * @param {string} llmKey Key identifying the model and its configuration.
+     * @returns Cached generations, or `null` when the entry is absent or its payload is malformed.
+     * @throws If the query fails or deserialization encounters an unexpected error.
+     */
+    lookup(prompt: string, llmKey: string): Promise<Generation[] | null>;
+    /**
+     * Inserts or replaces generations for an exact prompt and model configuration key.
+     * Skips the entire update if any generation contains valid or invalid tool calls.
+     * Successful writes commit the connection's transaction.
+     * @param {string} prompt Prompt used to identify the entry.
+     * @param {string} llmKey Key identifying the model and its configuration.
+     * @param {Generation[]} value Model generations to cache.
+     * @returns Promise that resolves when the write is committed or the update is skipped.
+     */
+    update(prompt: string, llmKey: string, value: Generation[]): Promise<void>;
+    /**
+     * Deletes entries matching all supplied exact-match filters.
+     * With no filters, deletes every entry in the table. Commits the connection's transaction.
+     * @param {OracleCacheClearOptions} options Optional prompt and model configuration filters.
+     * @param {string} options.prompt Optional prompt to match exactly.
+     * @param {string} options.llmKey Optional model configuration key to match exactly.
+     * @returns Promise that resolves when deletion has been committed.
+     * @throws If an unsupported filter is supplied or deletion fails.
+     */
+    clear(options?: OracleCacheClearOptions): Promise<void>;
+    /**
+     * Drops and purges the exact cache table if it exists, removing all entries.
+     * @param {OracleDBClient | OracleDBClientProvider} client Connection, pool, or async provider to use.
+     * @param {string} tableName Table to drop. Defaults to `langchain_exact_cache`.
+     * @returns Promise that resolves when the table has been dropped or does not exist.
+     */
+    static dropTable(client: OracleDBClient | OracleDBClientProvider, tableName?: string): Promise<void>;
+}

package/dist/cache.d.ts

@@ -0,0 +1,168 @@
+import type { Generation } from "@langchain/core/outputs";
+import type { EmbeddingsInterface } from "@langchain/core/embeddings";
+import { BaseCache } from "@langchain/core/caches";
+import { OracleDBVSArgs, IndexParams } from "./vectorstores.js";
+import { OracleDBClient, OracleDBClientProvider } from "./utils.js";
+export type OracleSemanticCacheDBConfig = Omit<OracleDBVSArgs, "tableName"> & {
+    tableName?: string;
+};
+export interface OracleSemanticCacheOptions {
+    createIndexIfMissing?: boolean;
+    indexName?: string;
+    indexParams?: IndexParams;
+    scoreThreshold?: number;
+}
+export interface OracleCacheClearOptions {
+    prompt?: string;
+    llmKey?: string;
+}
+/**
+ * Caches model generations in Oracle Database using vector similarity between prompts.
+ * @example
+ * ```typescript
+ * // `embeddings` is an EmbeddingsInterface and `pool` is an Oracle connection pool.
+ * const cache = new OracleSemanticCache(embeddings, { client: pool }, {
+ *   scoreThreshold: 0.2,
+ *   createIndexIfMissing: true,
+ * });
+ * ```
+ */
+export declare class OracleSemanticCache extends BaseCache {
+    private readonly vectorStore;
+    readonly createIndexIfMissing?: boolean;
+    readonly indexName?: string;
+    readonly indexParams?: IndexParams;
+    readonly scoreThreshold?: number;
+    private readonly LLM_HASH;
+    private readonly PROMPT_HASH;
+    private readonly RETURN_VAL;
+    /**
+     * Creates a semantic cache instance without performing database setup.
+     *
+     * @param {EmbeddingsInterface} embeddings Embedding model used to vectorize prompts.
+     * @param {OracleSemanticCacheDBConfig} dbConfig Oracle vector-store configuration.
+     * @param {OracleDBClient | OracleDBClientProvider} dbConfig.client Connection, pool, or async provider to use.
+     * @param {string} dbConfig.tableName Cache table name. Defaults to `langchain_semantic_cache`.
+     *
+     * @param {OracleSemanticCacheOptions} options Optional index and distance threshold settings.
+     * @param {boolean} options.createIndexIfMissing Whether initialize() creates a vector index
+     *   if it does not exist. Defaults to `false`.
+     * @param {number} options.scoreThreshold Maximum vector distance accepted for a cache hit.
+     *   Lower distance values indicate closer matches.
+     *
+     * @throws If the client is missing, the table identifier is invalid,
+     * or the distance threshold is negative.
+     */
+    constructor(embeddings: EmbeddingsInterface, dbConfig: OracleSemanticCacheDBConfig, options?: OracleSemanticCacheOptions);
+    /**
+     * Initializes the underlying vector store and creates the optional vector index.
+     * @returns Promise that resolves when database setup completes.
+     */
+    initialize(): Promise<void>;
+    private cacheEntryId;
+    /**
+     * Retrieves the nearest cached response for the given model configuration key.
+     * @param {string} prompt Prompt to embed and search for.
+     * @param {string} llmKey Key identifying the model and its configuration.
+     * @returns Cached generations, or `null` when no match passes the threshold or the payload is malformed.
+     * @throws If search fails or deserialization encounters an unexpected error.
+     */
+    lookup(prompt: string, llmKey: string): Promise<Generation[] | null>;
+    /**
+     * Inserts or updates the entry for an exact prompt and model configuration key.
+     * Skips the entire update if any generation contains valid or invalid tool calls,
+     * avoiding reuse of procedural responses within an agent loop.
+     * @param {string} prompt Prompt to embed and store.
+     * @param {string} llmKey Key identifying the model and its configuration.
+     * @param {Generation[]} value Model generations to cache.
+     * @returns Promise that resolves when the write completes or the update is skipped.
+     */
+    update(prompt: string, llmKey: string, value: Generation[]): Promise<void>;
+    /**
+     * Deletes entries matching all supplied exact filters, without similarity search.
+     * With no filters, deletes every entry in the table.
+     * @param {OracleCacheClearOptions} options Optional prompt and model configuration filters.
+     * @param {string} options.prompt Optional prompt to match exactly.
+     * @param {string} options.llmKey Optional model configuration key to match exactly.
+     * @returns Promise that resolves when deletion has been committed.
+     * @throws If an unsupported filter is supplied or deletion fails.
+     */
+    clear(options?: OracleCacheClearOptions): Promise<void>;
+    /**
+     * Drops and purges the semantic cache table if it exists, removing all entries.
+     * @param {OracleDBClient | OracleDBClientProvider} client Connection, pool, or async provider to use.
+     * @param {string} tableName Table to drop. Defaults to `langchain_semantic_cache`.
+     * @returns Promise that resolves when the table has been dropped or does not exist.
+     */
+    static dropTable(client: OracleDBClient | OracleDBClientProvider, tableName?: string): Promise<void>;
+}
+/**
+ * Caches model generations by exact prompt and model configuration key in Oracle Database.
+ * Lookup uses a hashed primary key and does not require an embedding model.
+ *
+ * @example
+ * ```typescript
+ * // `pool` is an Oracle connection pool.
+ * const cache = new OracleCache(pool);
+ * await cache.initialize();
+ * await cache.update("Hello", "model-config", [{ text: "Hi!" }]);
+ * const generations = await cache.lookup("Hello", "model-config");
+ * ```
+ */
+export declare class OracleCache extends BaseCache {
+    readonly client: OracleDBClient | OracleDBClientProvider;
+    readonly tableName: string;
+    private readonly quotedTableName;
+    /**
+     * Creates an exact cache instance without performing database setup.
+     * @param {OracleDBClient | OracleDBClientProvider} client Connection, pool, or async provider to use.
+     * @param {string} tableName Cache table name. Defaults to `langchain_exact_cache`.
+     * @throws If the client is missing or the table identifier is invalid.
+     */
+    constructor(client: OracleDBClient | OracleDBClientProvider, tableName?: string);
+    /**
+     * Creates the cache table if it does not already exist.
+     * @returns Promise that resolves when database setup completes.
+     */
+    initialize(): Promise<void>;
+    /** Stores serialized generations in a CLOB, with separate hashes for filtered deletion. */
+    private ensureTable;
+    private encodeKey;
+    private cacheEntryId;
+    /**
+     * Retrieves the cached response for an exact prompt and model configuration key.
+     * Restored chat message IDs are cleared before returning the generations.
+     * @param {string} prompt Exact prompt used when writing the entry.
+     * @param {string} llmKey Key identifying the model and its configuration.
+     * @returns Cached generations, or `null` when the entry is absent or its payload is malformed.
+     * @throws If the query fails or deserialization encounters an unexpected error.
+     */
+    lookup(prompt: string, llmKey: string): Promise<Generation[] | null>;
+    /**
+     * Inserts or replaces generations for an exact prompt and model configuration key.
+     * Skips the entire update if any generation contains valid or invalid tool calls.
+     * Successful writes commit the connection's transaction.
+     * @param {string} prompt Prompt used to identify the entry.
+     * @param {string} llmKey Key identifying the model and its configuration.
+     * @param {Generation[]} value Model generations to cache.
+     * @returns Promise that resolves when the write is committed or the update is skipped.
+     */
+    update(prompt: string, llmKey: string, value: Generation[]): Promise<void>;
+    /**
+     * Deletes entries matching all supplied exact-match filters.
+     * With no filters, deletes every entry in the table. Commits the connection's transaction.
+     * @param {OracleCacheClearOptions} options Optional prompt and model configuration filters.
+     * @param {string} options.prompt Optional prompt to match exactly.
+     * @param {string} options.llmKey Optional model configuration key to match exactly.
+     * @returns Promise that resolves when deletion has been committed.
+     * @throws If an unsupported filter is supplied or deletion fails.
+     */
+    clear(options?: OracleCacheClearOptions): Promise<void>;
+    /**
+     * Drops and purges the exact cache table if it exists, removing all entries.
+     * @param {OracleDBClient | OracleDBClientProvider} client Connection, pool, or async provider to use.
+     * @param {string} tableName Table to drop. Defaults to `langchain_exact_cache`.
+     * @returns Promise that resolves when the table has been dropped or does not exist.
+     */
+    static dropTable(client: OracleDBClient | OracleDBClientProvider, tableName?: string): Promise<void>;
+}