@langchain/langgraph-checkpoint 0.1.1 → 1.0.1

package/dist/store/base.d.cts

@@ -0,0 +1,391 @@
+import { Embeddings } from "@langchain/core/embeddings";
+
+//#region src/store/base.d.ts
+/**
+ * Error thrown when an invalid namespace is provided.
+ */
+declare class InvalidNamespaceError extends Error {
+  constructor(message: string);
+}
+/**
+ * Represents a stored item with metadata.
+ */
+interface Item {
+  /**
+   * The stored data as an object. Keys are filterable.
+   */
+  value: Record<string, any>;
+  /**
+   * Unique identifier within the namespace.
+   */
+  key: string;
+  /**
+   * Hierarchical path defining the collection in which this document resides.
+   * Represented as an array of strings, allowing for nested categorization.
+   * For example: ["documents", "user123"]
+   */
+  namespace: string[];
+  /**
+   * Timestamp of item creation.
+   */
+  createdAt: Date;
+  /**
+   * Timestamp of last update.
+   */
+  updatedAt: Date;
+}
+/**
+ * Represents a search result item with relevance score.
+ * Extends the base Item interface with an optional similarity score.
+ */
+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.
+ */
+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;
+}
+/**
+ * Operation to search for items within a namespace prefix.
+ */
+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 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>;
+  /**
+   * Maximum number of items to return.
+   * @default 10
+   */
+  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.
+ */
+interface PutOperation {
+  /**
+   * Hierarchical path for the item.
+   * 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 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 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[];
+}
+/**
+ * Operation to list and filter namespaces in the store.
+ */
+interface ListNamespacesOperation {
+  matchConditions?: MatchCondition[];
+  maxDepth?: number;
+  limit: number;
+  offset: number;
+}
+type NameSpacePath = (string | "*")[];
+type NamespaceMatchType = "prefix" | "suffix";
+interface MatchCondition {
+  matchType: NamespaceMatchType;
+  path: NameSpacePath;
+}
+type Operation = GetOperation | SearchOperation | PutOperation | ListNamespacesOperation;
+type OperationResults<Tuple extends readonly Operation[]> = { [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 };
+/**
+ * Configuration for indexing documents for semantic search in the store.
+ *
+ * This configures how documents are embedded and indexed for vector similarity search.
+ */
+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
+ */
+declare function getTextAtPath(obj: any, path: string): string[];
+/**
+ * Tokenizes a JSON path into parts
+ */
+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
+ */
+declare abstract class BaseStore {
+  /**
+   * 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>>;
+  /**
+   * 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.
+   * 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;
+    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 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>, index?: false | string[]): Promise<void>;
+  /**
+   * 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.
+   * 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;
+    limit?: number;
+    offset?: number;
+  }): Promise<string[][]>;
+  /**
+   * Start the store. Override if initialization is needed.
+   */
+  start(): void | Promise<void>;
+  /**
+   * Stop the store. Override if cleanup is needed.
+   */
+  stop(): void | Promise<void>;
+}
+//#endregion
+export { BaseStore, GetOperation, IndexConfig, InvalidNamespaceError, Item, ListNamespacesOperation, MatchCondition, NameSpacePath, NamespaceMatchType, Operation, OperationResults, PutOperation, SearchItem, SearchOperation, getTextAtPath, tokenizePath };
+//# sourceMappingURL=base.d.cts.map

package/dist/store/base.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.cts","names":[],"sources":["../../src/store/base.ts"],"mappings":";;;;;AAMA;cAAa,qBAAA,SAA8B,KAAA;EACzC,WAAA,CAAY,OAAA;AAAA;;;;UA2CG,IAAA;EA3CY;AA2C7B;;EAIE,KAAA,EAAO,MAAA;EAAA;;;EAIP,GAAA;EAce;;;;;EARf,SAAA;EAIW;;;EAAX,SAAA,EAAW,IAAA;EAII;AAOjB;;EAPE,SAAA,EAAW,IAAA;AAAA;;AAqBb;;;UAdiB,UAAA,SAAmB,IAAA;EAgC/B;AAML;;;;;;EA9BE,KAAA;AAAA;;;;UAMe,YAAA;EA+FA;;;;;;;EAvFf,SAAA;EAmJA;;;AAMF;;;;;EA/IE,GAAA;AAAA;;;;UAMe,eAAA;EAgJL;;;;;AAEZ;;;;;AAEA;EAxIE,eAAA;;;;;;;;;AA6IF;;;;;;;;;;;;;;;AAMA;EAzHE,MAAA,GAAS,MAAA;EAyHiB;;;;EAnH1B,KAAA;EAoHqC;;;;;EA7GrC,MAAA;EAiHU;;;;;;;;;;;;EAnGV,KAAA;AAAA;;;;UAMe,YAAA;EA4FX;;;;;;;;;;AAaN;;;;;EAzFE,SAAA;EA4GY;;;;AAqBd;;;EAxHE,GAAA;EAwHkD;AAmCpD;;;;;AAgBA;;;;;;EA7JE,KAAA,EAAO,MAAA;EAuKJ;;;;;;;;;;;;;;;;;;;EAlJH,KAAA;AAAA;;;;UAMe,uBAAA;EACf,eAAA,GAAkB,cAAA;EAClB,QAAA;EACA,KAAA;EACA,MAAA;AAAA;AAAA,KAGU,aAAA;AAAA,KAEA,kBAAA;AAAA,UAEK,cAAA;EACf,SAAA,EAAW,kBAAA;EACX,IAAA,EAAM,aAAA;AAAA;AAAA,KAGI,SAAA,GACR,YAAA,GACA,eAAA,GACA,YAAA,GACA,uBAAA;AAAA,KAEQ,gBAAA,wBAAwC,SAAA,oBACtC,KAAA,GAAQ,KAAA,CAAM,CAAA,UAAW,YAAA,UAEjC,KAAA,CAAM,CAAA,UAAW,eAAA,GACjB,UAAA,KACA,KAAA,CAAM,CAAA,UAAW,YAAA,GACjB,IAAA,UACA,KAAA,CAAM,CAAA,UAAW,uBAAA;;;;;;UAUN,WAAA;EAsMmB;;;;;;;;;;;;EAzLlC,IAAA;EAwPe;;;;EAlPf,UAAA,EAAY,UAAA;;;;;;;;;;;;;;EAeZ,MAAA;AAAA;;;;iBAMc,aAAA,CAAc,GAAA,OAAU,IAAA;;;;iBAmCxB,YAAA,CAAa,IAAA;;;;;;;;;;;;;uBAgBP,SAAA;;;;;;;;WAQX,KAAA,YAAiB,SAAA,GAAA,CACxB,UAAA,EAAY,EAAA,GACX,OAAA,CAAQ,gBAAA,CAAiB,EAAA;;;;;;;;EAStB,GAAA,CAAI,SAAA,YAAqB,GAAA,WAAc,OAAA,CAAQ,IAAA;;;;;;;;;;;;;;;;;;;;;;;EA0B/C,MAAA,CACJ,eAAA,YACA,OAAA;IACE,MAAA,GAAS,MAAA;IACT,KAAA;IACA,MAAA;IACA,KAAA;EAAA,IAED,OAAA,CAAQ,UAAA;;;;;;;;;;;;;;;;;;;;;;;;EAsCL,GAAA,CACJ,SAAA,YACA,GAAA,UACA,KAAA,EAAO,MAAA,eACP,KAAA,sBACC,OAAA;;;;;;;EAWG,MAAA,CAAO,SAAA,YAAqB,GAAA,WAAc,OAAA;;;;;;;;;;;;;;;;;;;;;EAwB1C,cAAA,CACJ,OAAA;IACE,MAAA;IACA,MAAA;IACA,QAAA;IACA,KAAA;IACA,MAAA;EAAA,IAED,OAAA;;;;EA0BH,KAAA,CAAA,UAAgB,OAAA;;;;EAKhB,IAAA,CAAA,UAAe,OAAA;AAAA"}