@langchain/langgraph-checkpoint 0.0.12 → 0.0.13

package/dist/store/base.d.ts

@@ -1,3 +1,4 @@
+import { Embeddings } from "@langchain/core/embeddings";
 /**
  * Error thrown when an invalid namespace is provided.
  */
@@ -31,16 +32,39 @@ export interface Item {
      */
     updatedAt: Date;
 }
+/**
+ * Represents a search result item with relevance score.
+ * Extends the base Item interface with an optional similarity score.
+ */
+export interface SearchItem extends Item {
+    /**
+     * Relevance/similarity score if from a ranked operation.
+     * Higher scores indicate better matches.
+     *
+     * This is typically a cosine similarity score between -1 and 1,
+     * where 1 indicates identical vectors and -1 indicates opposite vectors.
+     */
+    score?: number;
+}
 /**
  * Operation to retrieve an item by namespace and ID.
  */
 export interface GetOperation {
     /**
      * Hierarchical path for the item.
+     *
+     * @example
+     * // Get a user profile
+     * namespace: ["users", "profiles"]
      */
     namespace: string[];
     /**
      * Unique identifier within the namespace.
+     * Together with namespace forms the complete path to the item.
+     *
+     * @example
+     * key: "user123"  // For a user profile
+     * key: "doc456"   // For a document
      */
     key: string;
 }
@@ -50,10 +74,39 @@ export interface GetOperation {
 export interface SearchOperation {
     /**
      * Hierarchical path prefix to search within.
+     * Only items under this prefix will be searched.
+     *
+     * @example
+     * // Search all user documents
+     * namespacePrefix: ["users", "documents"]
+     *
+     * // Search everything
+     * namespacePrefix: []
      */
     namespacePrefix: string[];
     /**
-     * Key-value pairs to filter results.
+     * Key-value pairs to filter results based on exact matches or comparison operators.
+     *
+     * Supports both exact matches and operator-based comparisons:
+     * - $eq: Equal to (same as direct value comparison)
+     * - $ne: Not equal to
+     * - $gt: Greater than
+     * - $gte: Greater than or equal to
+     * - $lt: Less than
+     * - $lte: Less than or equal to
+     *
+     * @example
+     * // Exact match
+     * filter: { status: "active" }
+     *
+     * // With operators
+     * filter: { score: { $gt: 4.99 } }
+     *
+     * // Multiple conditions
+     * filter: {
+     *   score: { $gte: 3.0 },
+     *   color: "red"
+     * }
      */
     filter?: Record<string, any>;
     /**
@@ -63,9 +116,23 @@ export interface SearchOperation {
     limit?: number;
     /**
      * Number of items to skip before returning results.
+     * Useful for pagination.
      * @default 0
      */
     offset?: number;
+    /**
+     * Natural language search query for semantic search.
+     * When provided, results will be ranked by relevance to this query
+     * using vector similarity search.
+     *
+     * @example
+     * // Find technical documentation about APIs
+     * query: "technical documentation about REST APIs"
+     *
+     * // Find recent ML papers
+     * query: "machine learning papers from 2023"
+     */
+    query?: string;
 }
 /**
  * Operation to store, update, or delete an item.
@@ -73,96 +140,237 @@ export interface SearchOperation {
 export interface PutOperation {
     /**
      * Hierarchical path for the item.
-     * Represented as a tuple of strings, allowing for nested categorization.
-     * @example ["documents", "user123"]
+     * Acts as a folder-like structure to organize items.
+     * Each element represents one level in the hierarchy.
+     *
+     * @example
+     * // Root level documents
+     * namespace: ["documents"]
+     *
+     * // User-specific documents
+     * namespace: ["documents", "user123"]
+     *
+     * // Nested cache structure
+     * namespace: ["cache", "docs", "v1"]
      */
     namespace: string[];
     /**
-     * Unique identifier for the document.
-     * Should be distinct within its namespace.
+     * Unique identifier for the document within its namespace.
+     * Together with namespace forms the complete path to the item.
+     *
+     * Example: If namespace is ["documents", "user123"] and key is "report1",
+     * the full path would effectively be "documents/user123/report1"
      */
     key: string;
     /**
-     * Data to be stored, or None to delete the item.
-     * Schema:
-     *  - Should be an object where:
-     *    - Keys are strings representing field names
-     *    - Values can be of any serializable type
-     *  - If null, it indicates that the item should be deleted
+     * Data to be stored, or null to delete the item.
+     * Must be a JSON-serializable object with string keys.
+     * Setting to null signals that the item should be deleted.
+     *
+     * @example
+     * {
+     *   field1: "string value",
+     *   field2: 123,
+     *   nested: { can: "contain", any: "serializable data" }
+     * }
      */
     value: Record<string, any> | null;
+    /**
+     * Controls how the item's fields are indexed for search operations.
+     *
+     * - undefined: Uses store's default indexing configuration
+     * - false: Disables indexing for this item
+     * - string[]: List of field paths to index
+     *
+     * Path syntax supports:
+     * - Nested fields: "metadata.title"
+     * - Array access: "chapters[*].content" (each indexed separately)
+     * - Specific indices: "authors[0].name"
+     *
+     * @example
+     * // Index specific fields
+     * index: ["metadata.title", "chapters[*].content"]
+     *
+     * // Disable indexing
+     * index: false
+     */
+    index?: false | string[];
 }
-export type NameSpacePath = (string | "*")[];
-export type NamespaceMatchType = "prefix" | "suffix";
-export interface MatchCondition {
-    matchType: NamespaceMatchType;
-    path: NameSpacePath;
-}
+/**
+ * Operation to list and filter namespaces in the store.
+ */
 export interface ListNamespacesOperation {
     matchConditions?: MatchCondition[];
     maxDepth?: number;
     limit: number;
     offset: number;
 }
+export type NameSpacePath = (string | "*")[];
+export type NamespaceMatchType = "prefix" | "suffix";
+export interface MatchCondition {
+    matchType: NamespaceMatchType;
+    path: NameSpacePath;
+}
 export type Operation = GetOperation | SearchOperation | PutOperation | ListNamespacesOperation;
 export type OperationResults<Tuple extends readonly Operation[]> = {
-    [K in keyof Tuple]: Tuple[K] extends PutOperation ? void : Tuple[K] extends SearchOperation ? Item[] : Tuple[K] extends GetOperation ? Item | null : Tuple[K] extends ListNamespacesOperation ? string[][] : never;
+    [K in keyof Tuple]: Tuple[K] extends PutOperation ? void : Tuple[K] extends SearchOperation ? SearchItem[] : Tuple[K] extends GetOperation ? Item | null : Tuple[K] extends ListNamespacesOperation ? string[][] : never;
 };
 /**
- * Abstract base class for key-value stores.
+ * Configuration for indexing documents for semantic search in the store.
+ *
+ * This configures how documents are embedded and indexed for vector similarity search.
+ */
+export interface IndexConfig {
+    /**
+     * Number of dimensions in the embedding vectors.
+     *
+     * Common embedding model dimensions:
+     * - OpenAI text-embedding-3-large: 256, 1024, or 3072
+     * - OpenAI text-embedding-3-small: 512 or 1536
+     * - OpenAI text-embedding-ada-002: 1536
+     * - Cohere embed-english-v3.0: 1024
+     * - Cohere embed-english-light-v3.0: 384
+     * - Cohere embed-multilingual-v3.0: 1024
+     * - Cohere embed-multilingual-light-v3.0: 384
+     */
+    dims: number;
+    /**
+     * The embeddings model to use for generating vectors.
+     * This should be a LangChain Embeddings implementation.
+     */
+    embeddings: Embeddings;
+    /**
+     * Fields to extract text from for embedding generation.
+     *
+     * Path syntax supports:
+     * - Simple field access: "field"
+     * - Nested fields: "metadata.title"
+     * - Array indexing:
+     *   - All elements: "chapters[*].content"
+     *   - Specific index: "authors[0].name"
+     *   - Last element: "array[-1]"
+     *
+     * @default ["$"] Embeds the entire document as one vector
+     */
+    fields?: string[];
+}
+/**
+ * Utility function to get text at a specific JSON path
+ */
+export declare function getTextAtPath(obj: any, path: string): string[];
+/**
+ * Tokenizes a JSON path into parts
+ */
+export declare function tokenizePath(path: string): string[];
+/**
+ * Abstract base class for persistent key-value stores.
+ *
+ * Stores enable persistence and memory that can be shared across threads,
+ * scoped to user IDs, assistant IDs, or other arbitrary namespaces.
+ *
+ * Features:
+ * - Hierarchical namespaces for organization
+ * - Key-value storage with metadata
+ * - Vector similarity search (if configured)
+ * - Filtering and pagination
  */
 export declare abstract class BaseStore {
     /**
-     * Execute a batch of operations.
-     * @param _operations An array of operations to execute.
-     * @returns A promise that resolves to the results of the operations.
+     * Execute multiple operations in a single batch.
+     * This is more efficient than executing operations individually.
+     *
+     * @param operations Array of operations to execute
+     * @returns Promise resolving to results matching the operations
      */
-    abstract batch<Op extends Operation[]>(_operations: Op): Promise<OperationResults<Op>>;
+    abstract batch<Op extends Operation[]>(operations: Op): Promise<OperationResults<Op>>;
     /**
-     * Retrieve a single item.
-     * @param namespace Hierarchical path for the item.
-     * @param key Unique identifier within the namespace.
-     * @returns A promise that resolves to the retrieved item or null if not found.
+     * Retrieve a single item by its namespace and key.
+     *
+     * @param namespace Hierarchical path for the item
+     * @param key Unique identifier within the namespace
+     * @returns Promise resolving to the item or null if not found
      */
     get(namespace: string[], key: string): Promise<Item | null>;
     /**
      * Search for items within a namespace prefix.
-     * @param namespacePrefix Hierarchical path prefix to search within.
-     * @param options Search options.
-     * @param options.filter Key-value pairs to filter results.
-     * @param options.limit Maximum number of items to return (default: 10).
-     * @param options.offset Number of items to skip before returning results (default: 0).
-     * @returns A promise that resolves to a list of items matching the search criteria.
+     * Supports both metadata filtering and vector similarity search.
+     *
+     * @param namespacePrefix Hierarchical path prefix to search within
+     * @param options Search options for filtering and pagination
+     * @returns Promise resolving to list of matching items with relevance scores
+     *
+     * @example
+     * // Search with filters
+     * await store.search(["documents"], {
+     *   filter: { type: "report", status: "active" },
+     *   limit: 5,
+     *   offset: 10
+     * });
+     *
+     * // Vector similarity search
+     * await store.search(["users", "content"], {
+     *   query: "technical documentation about APIs",
+     *   limit: 20
+     * });
      */
     search(namespacePrefix: string[], options?: {
         filter?: Record<string, any>;
         limit?: number;
         offset?: number;
-    }): Promise<Item[]>;
+        query?: string;
+    }): Promise<SearchItem[]>;
     /**
      * Store or update an item.
-     * @param namespace Hierarchical path for the item.
-     * @param key Unique identifier within the namespace.
-     * @param value Object containing the item's data.
+     *
+     * @param namespace Hierarchical path for the item
+     * @param key Unique identifier within the namespace
+     * @param value Object containing the item's data
+     * @param index Optional indexing configuration
+     *
+     * @example
+     * // Simple storage
+     * await store.put(["docs"], "report", { title: "Annual Report" });
+     *
+     * // With specific field indexing
+     * await store.put(
+     *   ["docs"],
+     *   "report",
+     *   {
+     *     title: "Q4 Report",
+     *     chapters: [{ content: "..." }, { content: "..." }]
+     *   },
+     *   ["title", "chapters[*].content"]
+     * );
      */
-    put(namespace: string[], key: string, value: Record<string, any>): Promise<void>;
+    put(namespace: string[], key: string, value: Record<string, any>, index?: false | string[]): Promise<void>;
     /**
-     * Delete an item.
-     * @param namespace Hierarchical path for the item.
-     * @param key Unique identifier within the namespace.
+     * Delete an item from the store.
+     *
+     * @param namespace Hierarchical path for the item
+     * @param key Unique identifier within the namespace
      */
     delete(namespace: string[], key: string): Promise<void>;
     /**
      * List and filter namespaces in the store.
-     * @param options Options for listing namespaces.
-     * @param options.prefix Filter namespaces that start with this path.
-     * @param options.suffix Filter namespaces that end with this path.
-     * @param options.maxDepth Return namespaces up to this depth in the hierarchy.
-     * @param options.limit Maximum number of namespaces to return (default 100).
-     * @param options.offset Number of namespaces to skip for pagination (default 0).
-     * @returns A promise that resolves to a list of namespace arrays that match the criteria.
-     */
-    listNamespaces(options: {
+     * Used to explore data organization and navigate the namespace hierarchy.
+     *
+     * @param options Options for listing namespaces
+     * @returns Promise resolving to list of namespace paths
+     *
+     * @example
+     * // List all namespaces under "documents"
+     * await store.listNamespaces({
+     *   prefix: ["documents"],
+     *   maxDepth: 2
+     * });
+     *
+     * // List namespaces ending with "v1"
+     * await store.listNamespaces({
+     *   suffix: ["v1"],
+     *   limit: 50
+     * });
+     */
+    listNamespaces(options?: {
         prefix?: string[];
         suffix?: string[];
         maxDepth?: number;
@@ -170,11 +378,11 @@ export declare abstract class BaseStore {
         offset?: number;
     }): Promise<string[][]>;
     /**
-     * Stop the store. No-op if not implemented.
+     * Start the store. Override if initialization is needed.
      */
-    stop(): void;
+    start(): void;
     /**
-     * Start the store. No-op if not implemented.
+     * Stop the store. Override if cleanup is needed.
      */
-    start(): void;
+    stop(): void;
 }

package/dist/store/base.js

@@ -1,4 +1,3 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
 /**
  * Error thrown when an invalid namespace is provided.
  */
@@ -34,69 +33,158 @@ function validateNamespace(namespace) {
     }
 }
 /**
- * Abstract base class for key-value stores.
+ * Utility function to get text at a specific JSON path
+ */
+export function getTextAtPath(obj, path) {
+    const parts = path.split(".");
+    let current = obj;
+    for (const part of parts) {
+        if (part.includes("[")) {
+            const [arrayName, indexStr] = part.split("[");
+            const index = indexStr.replace("]", "");
+            if (!current[arrayName])
+                return [];
+            if (index === "*") {
+                const results = [];
+                for (const item of current[arrayName]) {
+                    if (typeof item === "string")
+                        results.push(item);
+                }
+                return results;
+            }
+            const idx = parseInt(index, 10);
+            if (Number.isNaN(idx))
+                return [];
+            current = current[arrayName][idx];
+        }
+        else {
+            current = current[part];
+        }
+        if (current === undefined)
+            return [];
+    }
+    return typeof current === "string" ? [current] : [];
+}
+/**
+ * Tokenizes a JSON path into parts
+ */
+export function tokenizePath(path) {
+    return path.split(".");
+}
+/**
+ * Abstract base class for persistent key-value stores.
+ *
+ * Stores enable persistence and memory that can be shared across threads,
+ * scoped to user IDs, assistant IDs, or other arbitrary namespaces.
+ *
+ * Features:
+ * - Hierarchical namespaces for organization
+ * - Key-value storage with metadata
+ * - Vector similarity search (if configured)
+ * - Filtering and pagination
  */
 export class BaseStore {
-    // convenience methods
     /**
-     * Retrieve a single item.
-     * @param namespace Hierarchical path for the item.
-     * @param key Unique identifier within the namespace.
-     * @returns A promise that resolves to the retrieved item or null if not found.
+     * Retrieve a single item by its namespace and key.
+     *
+     * @param namespace Hierarchical path for the item
+     * @param key Unique identifier within the namespace
+     * @returns Promise resolving to the item or null if not found
      */
     async get(namespace, key) {
-        const batchResult = await this.batch([{ namespace, key }]);
-        return batchResult[0];
+        return (await this.batch([{ namespace, key }]))[0];
     }
     /**
      * Search for items within a namespace prefix.
-     * @param namespacePrefix Hierarchical path prefix to search within.
-     * @param options Search options.
-     * @param options.filter Key-value pairs to filter results.
-     * @param options.limit Maximum number of items to return (default: 10).
-     * @param options.offset Number of items to skip before returning results (default: 0).
-     * @returns A promise that resolves to a list of items matching the search criteria.
+     * Supports both metadata filtering and vector similarity search.
+     *
+     * @param namespacePrefix Hierarchical path prefix to search within
+     * @param options Search options for filtering and pagination
+     * @returns Promise resolving to list of matching items with relevance scores
+     *
+     * @example
+     * // Search with filters
+     * await store.search(["documents"], {
+     *   filter: { type: "report", status: "active" },
+     *   limit: 5,
+     *   offset: 10
+     * });
+     *
+     * // Vector similarity search
+     * await store.search(["users", "content"], {
+     *   query: "technical documentation about APIs",
+     *   limit: 20
+     * });
      */
-    async search(namespacePrefix, options) {
-        const optionsWithDefaults = {
-            limit: 10,
-            offset: 0,
-            ...(options || {}),
-        };
-        const batchResults = await this.batch([
-            { namespacePrefix, ...optionsWithDefaults },
-        ]);
-        return batchResults[0];
+    async search(namespacePrefix, options = {}) {
+        const { filter, limit = 10, offset = 0, query } = options;
+        return (await this.batch([
+            {
+                namespacePrefix,
+                filter,
+                limit,
+                offset,
+                query,
+            },
+        ]))[0];
     }
     /**
      * Store or update an item.
-     * @param namespace Hierarchical path for the item.
-     * @param key Unique identifier within the namespace.
-     * @param value Object containing the item's data.
+     *
+     * @param namespace Hierarchical path for the item
+     * @param key Unique identifier within the namespace
+     * @param value Object containing the item's data
+     * @param index Optional indexing configuration
+     *
+     * @example
+     * // Simple storage
+     * await store.put(["docs"], "report", { title: "Annual Report" });
+     *
+     * // With specific field indexing
+     * await store.put(
+     *   ["docs"],
+     *   "report",
+     *   {
+     *     title: "Q4 Report",
+     *     chapters: [{ content: "..." }, { content: "..." }]
+     *   },
+     *   ["title", "chapters[*].content"]
+     * );
      */
-    async put(namespace, key, value) {
+    async put(namespace, key, value, index) {
         validateNamespace(namespace);
-        await this.batch([{ namespace, key, value }]);
+        await this.batch([{ namespace, key, value, index }]);
     }
     /**
-     * Delete an item.
-     * @param namespace Hierarchical path for the item.
-     * @param key Unique identifier within the namespace.
+     * Delete an item from the store.
+     *
+     * @param namespace Hierarchical path for the item
+     * @param key Unique identifier within the namespace
      */
     async delete(namespace, key) {
         await this.batch([{ namespace, key, value: null }]);
     }
     /**
      * List and filter namespaces in the store.
-     * @param options Options for listing namespaces.
-     * @param options.prefix Filter namespaces that start with this path.
-     * @param options.suffix Filter namespaces that end with this path.
-     * @param options.maxDepth Return namespaces up to this depth in the hierarchy.
-     * @param options.limit Maximum number of namespaces to return (default 100).
-     * @param options.offset Number of namespaces to skip for pagination (default 0).
-     * @returns A promise that resolves to a list of namespace arrays that match the criteria.
+     * Used to explore data organization and navigate the namespace hierarchy.
+     *
+     * @param options Options for listing namespaces
+     * @returns Promise resolving to list of namespace paths
+     *
+     * @example
+     * // List all namespaces under "documents"
+     * await store.listNamespaces({
+     *   prefix: ["documents"],
+     *   maxDepth: 2
+     * });
+     *
+     * // List namespaces ending with "v1"
+     * await store.listNamespaces({
+     *   suffix: ["v1"],
+     *   limit: 50
+     * });
      */
-    async listNamespaces(options) {
+    async listNamespaces(options = {}) {
         const { prefix, suffix, maxDepth, limit = 100, offset = 0 } = options;
         const matchConditions = [];
         if (prefix) {
@@ -105,25 +193,21 @@ export class BaseStore {
         if (suffix) {
             matchConditions.push({ matchType: "suffix", path: suffix });
         }
-        const op = {
-            matchConditions: matchConditions.length > 0 ? matchConditions : undefined,
-            maxDepth,
-            limit,
-            offset,
-        };
-        const batchResults = await this.batch([op]);
-        return batchResults[0];
+        return (await this.batch([
+            {
+                matchConditions: matchConditions.length ? matchConditions : undefined,
+                maxDepth,
+                limit,
+                offset,
+            },
+        ]))[0];
     }
     /**
-     * Stop the store. No-op if not implemented.
+     * Start the store. Override if initialization is needed.
      */
-    stop() {
-        // no-op if not implemented.
-    }
+    start() { }
     /**
-     * Start the store. No-op if not implemented.
+     * Stop the store. Override if cleanup is needed.
      */
-    start() {
-        // no-op if not implemented.
-    }
+    stop() { }
 }