@langchain/langgraph-checkpoint 0.1.0 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (121) hide show
  1. package/CHANGELOG.md +12 -0
  2. package/dist/_virtual/rolldown_runtime.cjs +25 -0
  3. package/dist/base.cjs +74 -88
  4. package/dist/base.cjs.map +1 -0
  5. package/dist/base.d.cts +95 -0
  6. package/dist/base.d.cts.map +1 -0
  7. package/dist/base.d.ts +79 -73
  8. package/dist/base.d.ts.map +1 -0
  9. package/dist/base.js +69 -80
  10. package/dist/base.js.map +1 -1
  11. package/dist/cache/base.cjs +17 -21
  12. package/dist/cache/base.cjs.map +1 -0
  13. package/dist/cache/base.d.cts +43 -0
  14. package/dist/cache/base.d.cts.map +1 -0
  15. package/dist/cache/base.d.ts +41 -36
  16. package/dist/cache/base.d.ts.map +1 -0
  17. package/dist/cache/base.js +16 -16
  18. package/dist/cache/base.js.map +1 -1
  19. package/dist/cache/index.cjs +2 -19
  20. package/dist/cache/index.js +4 -3
  21. package/dist/cache/memory.cjs +53 -58
  22. package/dist/cache/memory.cjs.map +1 -0
  23. package/dist/cache/memory.d.cts +19 -0
  24. package/dist/cache/memory.d.cts.map +1 -0
  25. package/dist/cache/memory.d.ts +18 -13
  26. package/dist/cache/memory.d.ts.map +1 -0
  27. package/dist/cache/memory.js +52 -53
  28. package/dist/cache/memory.js.map +1 -1
  29. package/dist/id.cjs +12 -16
  30. package/dist/id.cjs.map +1 -0
  31. package/dist/id.d.cts +10 -0
  32. package/dist/id.d.cts.map +1 -0
  33. package/dist/id.d.ts +10 -2
  34. package/dist/id.d.ts.map +1 -0
  35. package/dist/id.js +10 -12
  36. package/dist/id.js.map +1 -1
  37. package/dist/index.cjs +36 -27
  38. package/dist/index.d.cts +12 -0
  39. package/dist/index.d.ts +12 -8
  40. package/dist/index.js +12 -9
  41. package/dist/memory.cjs +194 -268
  42. package/dist/memory.cjs.map +1 -0
  43. package/dist/memory.d.cts +22 -0
  44. package/dist/memory.d.cts.map +1 -0
  45. package/dist/memory.d.ts +19 -12
  46. package/dist/memory.d.ts.map +1 -0
  47. package/dist/memory.js +193 -263
  48. package/dist/memory.js.map +1 -1
  49. package/dist/serde/base.d.cts +10 -0
  50. package/dist/serde/base.d.cts.map +1 -0
  51. package/dist/serde/base.d.ts +9 -3
  52. package/dist/serde/base.d.ts.map +1 -0
  53. package/dist/serde/jsonplus.cjs +92 -141
  54. package/dist/serde/jsonplus.cjs.map +1 -0
  55. package/dist/serde/jsonplus.js +90 -136
  56. package/dist/serde/jsonplus.js.map +1 -1
  57. package/dist/serde/types.cjs +15 -9
  58. package/dist/serde/types.cjs.map +1 -0
  59. package/dist/serde/types.d.cts +55 -0
  60. package/dist/serde/types.d.cts.map +1 -0
  61. package/dist/serde/types.d.ts +53 -47
  62. package/dist/serde/types.d.ts.map +1 -0
  63. package/dist/serde/types.js +9 -5
  64. package/dist/serde/types.js.map +1 -1
  65. package/dist/serde/utils/fast-safe-stringify/index.cjs +88 -208
  66. package/dist/serde/utils/fast-safe-stringify/index.cjs.map +1 -0
  67. package/dist/serde/utils/fast-safe-stringify/index.js +87 -205
  68. package/dist/serde/utils/fast-safe-stringify/index.js.map +1 -1
  69. package/dist/store/base.cjs +200 -209
  70. package/dist/store/base.cjs.map +1 -0
  71. package/dist/store/base.d.cts +392 -0
  72. package/dist/store/base.d.cts.map +1 -0
  73. package/dist/store/base.d.ts +336 -332
  74. package/dist/store/base.d.ts.map +1 -0
  75. package/dist/store/base.js +198 -204
  76. package/dist/store/base.js.map +1 -1
  77. package/dist/store/batch.cjs +116 -147
  78. package/dist/store/batch.cjs.map +1 -0
  79. package/dist/store/batch.d.cts +49 -0
  80. package/dist/store/batch.d.cts.map +1 -0
  81. package/dist/store/batch.d.ts +48 -40
  82. package/dist/store/batch.d.ts.map +1 -0
  83. package/dist/store/batch.js +116 -143
  84. package/dist/store/batch.js.map +1 -1
  85. package/dist/store/memory.cjs +262 -363
  86. package/dist/store/memory.cjs.map +1 -0
  87. package/dist/store/memory.d.cts +64 -0
  88. package/dist/store/memory.d.cts.map +1 -0
  89. package/dist/store/memory.d.ts +30 -24
  90. package/dist/store/memory.d.ts.map +1 -0
  91. package/dist/store/memory.js +261 -358
  92. package/dist/store/memory.js.map +1 -1
  93. package/dist/store/utils.cjs +141 -249
  94. package/dist/store/utils.cjs.map +1 -0
  95. package/dist/store/utils.js +140 -245
  96. package/dist/store/utils.js.map +1 -1
  97. package/dist/types.d.cts +35 -0
  98. package/dist/types.d.cts.map +1 -0
  99. package/dist/types.d.ts +29 -28
  100. package/dist/types.d.ts.map +1 -0
  101. package/package.json +16 -18
  102. package/dist/cache/index.d.ts +0 -2
  103. package/dist/cache/index.js.map +0 -1
  104. package/dist/index.js.map +0 -1
  105. package/dist/serde/base.cjs +0 -3
  106. package/dist/serde/base.js +0 -2
  107. package/dist/serde/base.js.map +0 -1
  108. package/dist/serde/jsonplus.d.ts +0 -7
  109. package/dist/serde/utils/fast-safe-stringify/index.d.ts +0 -1
  110. package/dist/store/index.cjs +0 -20
  111. package/dist/store/index.d.ts +0 -3
  112. package/dist/store/index.js +0 -4
  113. package/dist/store/index.js.map +0 -1
  114. package/dist/store/utils.d.ts +0 -26
  115. package/dist/types.cjs +0 -3
  116. package/dist/types.js +0 -2
  117. package/dist/types.js.map +0 -1
  118. package/index.cjs +0 -1
  119. package/index.d.cts +0 -1
  120. package/index.d.ts +0 -1
  121. package/index.js +0 -1
@@ -0,0 +1,392 @@
1
+ import { Embeddings } from "@langchain/core/embeddings";
2
+
3
+ //#region src/store/base.d.ts
4
+
5
+ /**
6
+ * Error thrown when an invalid namespace is provided.
7
+ */
8
+ declare class InvalidNamespaceError extends Error {
9
+ constructor(message: string);
10
+ }
11
+ /**
12
+ * Represents a stored item with metadata.
13
+ */
14
+ interface Item {
15
+ /**
16
+ * The stored data as an object. Keys are filterable.
17
+ */
18
+ value: Record<string, any>;
19
+ /**
20
+ * Unique identifier within the namespace.
21
+ */
22
+ key: string;
23
+ /**
24
+ * Hierarchical path defining the collection in which this document resides.
25
+ * Represented as an array of strings, allowing for nested categorization.
26
+ * For example: ["documents", "user123"]
27
+ */
28
+ namespace: string[];
29
+ /**
30
+ * Timestamp of item creation.
31
+ */
32
+ createdAt: Date;
33
+ /**
34
+ * Timestamp of last update.
35
+ */
36
+ updatedAt: Date;
37
+ }
38
+ /**
39
+ * Represents a search result item with relevance score.
40
+ * Extends the base Item interface with an optional similarity score.
41
+ */
42
+ interface SearchItem extends Item {
43
+ /**
44
+ * Relevance/similarity score if from a ranked operation.
45
+ * Higher scores indicate better matches.
46
+ *
47
+ * This is typically a cosine similarity score between -1 and 1,
48
+ * where 1 indicates identical vectors and -1 indicates opposite vectors.
49
+ */
50
+ score?: number;
51
+ }
52
+ /**
53
+ * Operation to retrieve an item by namespace and ID.
54
+ */
55
+ interface GetOperation {
56
+ /**
57
+ * Hierarchical path for the item.
58
+ *
59
+ * @example
60
+ * // Get a user profile
61
+ * namespace: ["users", "profiles"]
62
+ */
63
+ namespace: string[];
64
+ /**
65
+ * Unique identifier within the namespace.
66
+ * Together with namespace forms the complete path to the item.
67
+ *
68
+ * @example
69
+ * key: "user123" // For a user profile
70
+ * key: "doc456" // For a document
71
+ */
72
+ key: string;
73
+ }
74
+ /**
75
+ * Operation to search for items within a namespace prefix.
76
+ */
77
+ interface SearchOperation {
78
+ /**
79
+ * Hierarchical path prefix to search within.
80
+ * Only items under this prefix will be searched.
81
+ *
82
+ * @example
83
+ * // Search all user documents
84
+ * namespacePrefix: ["users", "documents"]
85
+ *
86
+ * // Search everything
87
+ * namespacePrefix: []
88
+ */
89
+ namespacePrefix: string[];
90
+ /**
91
+ * Key-value pairs to filter results based on exact matches or comparison operators.
92
+ *
93
+ * Supports both exact matches and operator-based comparisons:
94
+ * - $eq: Equal to (same as direct value comparison)
95
+ * - $ne: Not equal to
96
+ * - $gt: Greater than
97
+ * - $gte: Greater than or equal to
98
+ * - $lt: Less than
99
+ * - $lte: Less than or equal to
100
+ *
101
+ * @example
102
+ * // Exact match
103
+ * filter: { status: "active" }
104
+ *
105
+ * // With operators
106
+ * filter: { score: { $gt: 4.99 } }
107
+ *
108
+ * // Multiple conditions
109
+ * filter: {
110
+ * score: { $gte: 3.0 },
111
+ * color: "red"
112
+ * }
113
+ */
114
+ filter?: Record<string, any>;
115
+ /**
116
+ * Maximum number of items to return.
117
+ * @default 10
118
+ */
119
+ limit?: number;
120
+ /**
121
+ * Number of items to skip before returning results.
122
+ * Useful for pagination.
123
+ * @default 0
124
+ */
125
+ offset?: number;
126
+ /**
127
+ * Natural language search query for semantic search.
128
+ * When provided, results will be ranked by relevance to this query
129
+ * using vector similarity search.
130
+ *
131
+ * @example
132
+ * // Find technical documentation about APIs
133
+ * query: "technical documentation about REST APIs"
134
+ *
135
+ * // Find recent ML papers
136
+ * query: "machine learning papers from 2023"
137
+ */
138
+ query?: string;
139
+ }
140
+ /**
141
+ * Operation to store, update, or delete an item.
142
+ */
143
+ interface PutOperation {
144
+ /**
145
+ * Hierarchical path for the item.
146
+ * Acts as a folder-like structure to organize items.
147
+ * Each element represents one level in the hierarchy.
148
+ *
149
+ * @example
150
+ * // Root level documents
151
+ * namespace: ["documents"]
152
+ *
153
+ * // User-specific documents
154
+ * namespace: ["documents", "user123"]
155
+ *
156
+ * // Nested cache structure
157
+ * namespace: ["cache", "docs", "v1"]
158
+ */
159
+ namespace: string[];
160
+ /**
161
+ * Unique identifier for the document within its namespace.
162
+ * Together with namespace forms the complete path to the item.
163
+ *
164
+ * Example: If namespace is ["documents", "user123"] and key is "report1",
165
+ * the full path would effectively be "documents/user123/report1"
166
+ */
167
+ key: string;
168
+ /**
169
+ * Data to be stored, or null to delete the item.
170
+ * Must be a JSON-serializable object with string keys.
171
+ * Setting to null signals that the item should be deleted.
172
+ *
173
+ * @example
174
+ * {
175
+ * field1: "string value",
176
+ * field2: 123,
177
+ * nested: { can: "contain", any: "serializable data" }
178
+ * }
179
+ */
180
+ value: Record<string, any> | null;
181
+ /**
182
+ * Controls how the item's fields are indexed for search operations.
183
+ *
184
+ * - undefined: Uses store's default indexing configuration
185
+ * - false: Disables indexing for this item
186
+ * - string[]: List of field paths to index
187
+ *
188
+ * Path syntax supports:
189
+ * - Nested fields: "metadata.title"
190
+ * - Array access: "chapters[*].content" (each indexed separately)
191
+ * - Specific indices: "authors[0].name"
192
+ *
193
+ * @example
194
+ * // Index specific fields
195
+ * index: ["metadata.title", "chapters[*].content"]
196
+ *
197
+ * // Disable indexing
198
+ * index: false
199
+ */
200
+ index?: false | string[];
201
+ }
202
+ /**
203
+ * Operation to list and filter namespaces in the store.
204
+ */
205
+ interface ListNamespacesOperation {
206
+ matchConditions?: MatchCondition[];
207
+ maxDepth?: number;
208
+ limit: number;
209
+ offset: number;
210
+ }
211
+ type NameSpacePath = (string | "*")[];
212
+ type NamespaceMatchType = "prefix" | "suffix";
213
+ interface MatchCondition {
214
+ matchType: NamespaceMatchType;
215
+ path: NameSpacePath;
216
+ }
217
+ type Operation = GetOperation | SearchOperation | PutOperation | ListNamespacesOperation;
218
+ 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 };
219
+ /**
220
+ * Configuration for indexing documents for semantic search in the store.
221
+ *
222
+ * This configures how documents are embedded and indexed for vector similarity search.
223
+ */
224
+ interface IndexConfig {
225
+ /**
226
+ * Number of dimensions in the embedding vectors.
227
+ *
228
+ * Common embedding model dimensions:
229
+ * - OpenAI text-embedding-3-large: 256, 1024, or 3072
230
+ * - OpenAI text-embedding-3-small: 512 or 1536
231
+ * - OpenAI text-embedding-ada-002: 1536
232
+ * - Cohere embed-english-v3.0: 1024
233
+ * - Cohere embed-english-light-v3.0: 384
234
+ * - Cohere embed-multilingual-v3.0: 1024
235
+ * - Cohere embed-multilingual-light-v3.0: 384
236
+ */
237
+ dims: number;
238
+ /**
239
+ * The embeddings model to use for generating vectors.
240
+ * This should be a LangChain Embeddings implementation.
241
+ */
242
+ embeddings: Embeddings;
243
+ /**
244
+ * Fields to extract text from for embedding generation.
245
+ *
246
+ * Path syntax supports:
247
+ * - Simple field access: "field"
248
+ * - Nested fields: "metadata.title"
249
+ * - Array indexing:
250
+ * - All elements: "chapters[*].content"
251
+ * - Specific index: "authors[0].name"
252
+ * - Last element: "array[-1]"
253
+ *
254
+ * @default ["$"] Embeds the entire document as one vector
255
+ */
256
+ fields?: string[];
257
+ }
258
+ /**
259
+ * Utility function to get text at a specific JSON path
260
+ */
261
+ declare function getTextAtPath(obj: any, path: string): string[];
262
+ /**
263
+ * Tokenizes a JSON path into parts
264
+ */
265
+ declare function tokenizePath(path: string): string[];
266
+ /**
267
+ * Abstract base class for persistent key-value stores.
268
+ *
269
+ * Stores enable persistence and memory that can be shared across threads,
270
+ * scoped to user IDs, assistant IDs, or other arbitrary namespaces.
271
+ *
272
+ * Features:
273
+ * - Hierarchical namespaces for organization
274
+ * - Key-value storage with metadata
275
+ * - Vector similarity search (if configured)
276
+ * - Filtering and pagination
277
+ */
278
+ declare abstract class BaseStore {
279
+ /**
280
+ * Execute multiple operations in a single batch.
281
+ * This is more efficient than executing operations individually.
282
+ *
283
+ * @param operations Array of operations to execute
284
+ * @returns Promise resolving to results matching the operations
285
+ */
286
+ abstract batch<Op extends Operation[]>(operations: Op): Promise<OperationResults<Op>>;
287
+ /**
288
+ * Retrieve a single item by its namespace and key.
289
+ *
290
+ * @param namespace Hierarchical path for the item
291
+ * @param key Unique identifier within the namespace
292
+ * @returns Promise resolving to the item or null if not found
293
+ */
294
+ get(namespace: string[], key: string): Promise<Item | null>;
295
+ /**
296
+ * Search for items within a namespace prefix.
297
+ * Supports both metadata filtering and vector similarity search.
298
+ *
299
+ * @param namespacePrefix Hierarchical path prefix to search within
300
+ * @param options Search options for filtering and pagination
301
+ * @returns Promise resolving to list of matching items with relevance scores
302
+ *
303
+ * @example
304
+ * // Search with filters
305
+ * await store.search(["documents"], {
306
+ * filter: { type: "report", status: "active" },
307
+ * limit: 5,
308
+ * offset: 10
309
+ * });
310
+ *
311
+ * // Vector similarity search
312
+ * await store.search(["users", "content"], {
313
+ * query: "technical documentation about APIs",
314
+ * limit: 20
315
+ * });
316
+ */
317
+ search(namespacePrefix: string[], options?: {
318
+ filter?: Record<string, any>;
319
+ limit?: number;
320
+ offset?: number;
321
+ query?: string;
322
+ }): Promise<SearchItem[]>;
323
+ /**
324
+ * Store or update an item.
325
+ *
326
+ * @param namespace Hierarchical path for the item
327
+ * @param key Unique identifier within the namespace
328
+ * @param value Object containing the item's data
329
+ * @param index Optional indexing configuration
330
+ *
331
+ * @example
332
+ * // Simple storage
333
+ * await store.put(["docs"], "report", { title: "Annual Report" });
334
+ *
335
+ * // With specific field indexing
336
+ * await store.put(
337
+ * ["docs"],
338
+ * "report",
339
+ * {
340
+ * title: "Q4 Report",
341
+ * chapters: [{ content: "..." }, { content: "..." }]
342
+ * },
343
+ * ["title", "chapters[*].content"]
344
+ * );
345
+ */
346
+ put(namespace: string[], key: string, value: Record<string, any>, index?: false | string[]): Promise<void>;
347
+ /**
348
+ * Delete an item from the store.
349
+ *
350
+ * @param namespace Hierarchical path for the item
351
+ * @param key Unique identifier within the namespace
352
+ */
353
+ delete(namespace: string[], key: string): Promise<void>;
354
+ /**
355
+ * List and filter namespaces in the store.
356
+ * Used to explore data organization and navigate the namespace hierarchy.
357
+ *
358
+ * @param options Options for listing namespaces
359
+ * @returns Promise resolving to list of namespace paths
360
+ *
361
+ * @example
362
+ * // List all namespaces under "documents"
363
+ * await store.listNamespaces({
364
+ * prefix: ["documents"],
365
+ * maxDepth: 2
366
+ * });
367
+ *
368
+ * // List namespaces ending with "v1"
369
+ * await store.listNamespaces({
370
+ * suffix: ["v1"],
371
+ * limit: 50
372
+ * });
373
+ */
374
+ listNamespaces(options?: {
375
+ prefix?: string[];
376
+ suffix?: string[];
377
+ maxDepth?: number;
378
+ limit?: number;
379
+ offset?: number;
380
+ }): Promise<string[][]>;
381
+ /**
382
+ * Start the store. Override if initialization is needed.
383
+ */
384
+ start(): void | Promise<void>;
385
+ /**
386
+ * Stop the store. Override if cleanup is needed.
387
+ */
388
+ stop(): void | Promise<void>;
389
+ }
390
+ //#endregion
391
+ export { BaseStore, GetOperation, IndexConfig, InvalidNamespaceError, Item, ListNamespacesOperation, MatchCondition, NameSpacePath, NamespaceMatchType, Operation, OperationResults, PutOperation, SearchItem, SearchOperation, getTextAtPath, tokenizePath };
392
+ //# sourceMappingURL=base.d.cts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"base.d.cts","names":["Embeddings","InvalidNamespaceError","Error","Item","Record","Date","SearchItem","GetOperation","SearchOperation","PutOperation","ListNamespacesOperation","MatchCondition","NameSpacePath","NamespaceMatchType","Operation","OperationResults","Tuple","K","IndexConfig","getTextAtPath","tokenizePath","BaseStore","Op","Promise"],"sources":["../../src/store/base.d.ts"],"sourcesContent":["/* eslint-disable @typescript-eslint/no-explicit-any */\nimport { Embeddings } from \"@langchain/core/embeddings\";\n/**\n * Error thrown when an invalid namespace is provided.\n */\nexport declare class InvalidNamespaceError extends Error {\n constructor(message: string);\n}\n/**\n * Represents a stored item with metadata.\n */\nexport interface Item {\n /**\n * The stored data as an object. Keys are filterable.\n */\n value: Record<string, any>;\n /**\n * Unique identifier within the namespace.\n */\n key: string;\n /**\n * Hierarchical path defining the collection in which this document resides.\n * Represented as an array of strings, allowing for nested categorization.\n * For example: [\"documents\", \"user123\"]\n */\n namespace: string[];\n /**\n * Timestamp of item creation.\n */\n createdAt: Date;\n /**\n * Timestamp of last update.\n */\n updatedAt: Date;\n}\n/**\n * Represents a search result item with relevance score.\n * Extends the base Item interface with an optional similarity score.\n */\nexport interface SearchItem extends Item {\n /**\n * Relevance/similarity score if from a ranked operation.\n * Higher scores indicate better matches.\n *\n * This is typically a cosine similarity score between -1 and 1,\n * where 1 indicates identical vectors and -1 indicates opposite vectors.\n */\n score?: number;\n}\n/**\n * Operation to retrieve an item by namespace and ID.\n */\nexport interface GetOperation {\n /**\n * Hierarchical path for the item.\n *\n * @example\n * // Get a user profile\n * namespace: [\"users\", \"profiles\"]\n */\n namespace: string[];\n /**\n * Unique identifier within the namespace.\n * Together with namespace forms the complete path to the item.\n *\n * @example\n * key: \"user123\" // For a user profile\n * key: \"doc456\" // For a document\n */\n key: string;\n}\n/**\n * Operation to search for items within a namespace prefix.\n */\nexport interface SearchOperation {\n /**\n * Hierarchical path prefix to search within.\n * Only items under this prefix will be searched.\n *\n * @example\n * // Search all user documents\n * namespacePrefix: [\"users\", \"documents\"]\n *\n * // Search everything\n * namespacePrefix: []\n */\n namespacePrefix: string[];\n /**\n * Key-value pairs to filter results based on exact matches or comparison operators.\n *\n * Supports both exact matches and operator-based comparisons:\n * - $eq: Equal to (same as direct value comparison)\n * - $ne: Not equal to\n * - $gt: Greater than\n * - $gte: Greater than or equal to\n * - $lt: Less than\n * - $lte: Less than or equal to\n *\n * @example\n * // Exact match\n * filter: { status: \"active\" }\n *\n * // With operators\n * filter: { score: { $gt: 4.99 } }\n *\n * // Multiple conditions\n * filter: {\n * score: { $gte: 3.0 },\n * color: \"red\"\n * }\n */\n filter?: Record<string, any>;\n /**\n * Maximum number of items to return.\n * @default 10\n */\n limit?: number;\n /**\n * Number of items to skip before returning results.\n * Useful for pagination.\n * @default 0\n */\n offset?: number;\n /**\n * Natural language search query for semantic search.\n * When provided, results will be ranked by relevance to this query\n * using vector similarity search.\n *\n * @example\n * // Find technical documentation about APIs\n * query: \"technical documentation about REST APIs\"\n *\n * // Find recent ML papers\n * query: \"machine learning papers from 2023\"\n */\n query?: string;\n}\n/**\n * Operation to store, update, or delete an item.\n */\nexport interface PutOperation {\n /**\n * Hierarchical path for the item.\n * Acts as a folder-like structure to organize items.\n * Each element represents one level in the hierarchy.\n *\n * @example\n * // Root level documents\n * namespace: [\"documents\"]\n *\n * // User-specific documents\n * namespace: [\"documents\", \"user123\"]\n *\n * // Nested cache structure\n * namespace: [\"cache\", \"docs\", \"v1\"]\n */\n namespace: string[];\n /**\n * Unique identifier for the document within its namespace.\n * Together with namespace forms the complete path to the item.\n *\n * Example: If namespace is [\"documents\", \"user123\"] and key is \"report1\",\n * the full path would effectively be \"documents/user123/report1\"\n */\n key: string;\n /**\n * Data to be stored, or null to delete the item.\n * Must be a JSON-serializable object with string keys.\n * Setting to null signals that the item should be deleted.\n *\n * @example\n * {\n * field1: \"string value\",\n * field2: 123,\n * nested: { can: \"contain\", any: \"serializable data\" }\n * }\n */\n value: Record<string, any> | null;\n /**\n * Controls how the item's fields are indexed for search operations.\n *\n * - undefined: Uses store's default indexing configuration\n * - false: Disables indexing for this item\n * - string[]: List of field paths to index\n *\n * Path syntax supports:\n * - Nested fields: \"metadata.title\"\n * - Array access: \"chapters[*].content\" (each indexed separately)\n * - Specific indices: \"authors[0].name\"\n *\n * @example\n * // Index specific fields\n * index: [\"metadata.title\", \"chapters[*].content\"]\n *\n * // Disable indexing\n * index: false\n */\n index?: false | string[];\n}\n/**\n * Operation to list and filter namespaces in the store.\n */\nexport interface ListNamespacesOperation {\n matchConditions?: MatchCondition[];\n maxDepth?: number;\n limit: number;\n offset: number;\n}\nexport type NameSpacePath = (string | \"*\")[];\nexport type NamespaceMatchType = \"prefix\" | \"suffix\";\nexport interface MatchCondition {\n matchType: NamespaceMatchType;\n path: NameSpacePath;\n}\nexport type Operation = GetOperation | SearchOperation | PutOperation | ListNamespacesOperation;\nexport type OperationResults<Tuple extends readonly Operation[]> = {\n [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;\n};\n/**\n * Configuration for indexing documents for semantic search in the store.\n *\n * This configures how documents are embedded and indexed for vector similarity search.\n */\nexport interface IndexConfig {\n /**\n * Number of dimensions in the embedding vectors.\n *\n * Common embedding model dimensions:\n * - OpenAI text-embedding-3-large: 256, 1024, or 3072\n * - OpenAI text-embedding-3-small: 512 or 1536\n * - OpenAI text-embedding-ada-002: 1536\n * - Cohere embed-english-v3.0: 1024\n * - Cohere embed-english-light-v3.0: 384\n * - Cohere embed-multilingual-v3.0: 1024\n * - Cohere embed-multilingual-light-v3.0: 384\n */\n dims: number;\n /**\n * The embeddings model to use for generating vectors.\n * This should be a LangChain Embeddings implementation.\n */\n embeddings: Embeddings;\n /**\n * Fields to extract text from for embedding generation.\n *\n * Path syntax supports:\n * - Simple field access: \"field\"\n * - Nested fields: \"metadata.title\"\n * - Array indexing:\n * - All elements: \"chapters[*].content\"\n * - Specific index: \"authors[0].name\"\n * - Last element: \"array[-1]\"\n *\n * @default [\"$\"] Embeds the entire document as one vector\n */\n fields?: string[];\n}\n/**\n * Utility function to get text at a specific JSON path\n */\nexport declare function getTextAtPath(obj: any, path: string): string[];\n/**\n * Tokenizes a JSON path into parts\n */\nexport declare function tokenizePath(path: string): string[];\n/**\n * Abstract base class for persistent key-value stores.\n *\n * Stores enable persistence and memory that can be shared across threads,\n * scoped to user IDs, assistant IDs, or other arbitrary namespaces.\n *\n * Features:\n * - Hierarchical namespaces for organization\n * - Key-value storage with metadata\n * - Vector similarity search (if configured)\n * - Filtering and pagination\n */\nexport declare abstract class BaseStore {\n /**\n * Execute multiple operations in a single batch.\n * This is more efficient than executing operations individually.\n *\n * @param operations Array of operations to execute\n * @returns Promise resolving to results matching the operations\n */\n abstract batch<Op extends Operation[]>(operations: Op): Promise<OperationResults<Op>>;\n /**\n * Retrieve a single item by its namespace and key.\n *\n * @param namespace Hierarchical path for the item\n * @param key Unique identifier within the namespace\n * @returns Promise resolving to the item or null if not found\n */\n get(namespace: string[], key: string): Promise<Item | null>;\n /**\n * Search for items within a namespace prefix.\n * Supports both metadata filtering and vector similarity search.\n *\n * @param namespacePrefix Hierarchical path prefix to search within\n * @param options Search options for filtering and pagination\n * @returns Promise resolving to list of matching items with relevance scores\n *\n * @example\n * // Search with filters\n * await store.search([\"documents\"], {\n * filter: { type: \"report\", status: \"active\" },\n * limit: 5,\n * offset: 10\n * });\n *\n * // Vector similarity search\n * await store.search([\"users\", \"content\"], {\n * query: \"technical documentation about APIs\",\n * limit: 20\n * });\n */\n search(namespacePrefix: string[], options?: {\n filter?: Record<string, any>;\n limit?: number;\n offset?: number;\n query?: string;\n }): Promise<SearchItem[]>;\n /**\n * Store or update an item.\n *\n * @param namespace Hierarchical path for the item\n * @param key Unique identifier within the namespace\n * @param value Object containing the item's data\n * @param index Optional indexing configuration\n *\n * @example\n * // Simple storage\n * await store.put([\"docs\"], \"report\", { title: \"Annual Report\" });\n *\n * // With specific field indexing\n * await store.put(\n * [\"docs\"],\n * \"report\",\n * {\n * title: \"Q4 Report\",\n * chapters: [{ content: \"...\" }, { content: \"...\" }]\n * },\n * [\"title\", \"chapters[*].content\"]\n * );\n */\n put(namespace: string[], key: string, value: Record<string, any>, index?: false | string[]): Promise<void>;\n /**\n * Delete an item from the store.\n *\n * @param namespace Hierarchical path for the item\n * @param key Unique identifier within the namespace\n */\n delete(namespace: string[], key: string): Promise<void>;\n /**\n * List and filter namespaces in the store.\n * Used to explore data organization and navigate the namespace hierarchy.\n *\n * @param options Options for listing namespaces\n * @returns Promise resolving to list of namespace paths\n *\n * @example\n * // List all namespaces under \"documents\"\n * await store.listNamespaces({\n * prefix: [\"documents\"],\n * maxDepth: 2\n * });\n *\n * // List namespaces ending with \"v1\"\n * await store.listNamespaces({\n * suffix: [\"v1\"],\n * limit: 50\n * });\n */\n listNamespaces(options?: {\n prefix?: string[];\n suffix?: string[];\n maxDepth?: number;\n limit?: number;\n offset?: number;\n }): Promise<string[][]>;\n /**\n * Start the store. Override if initialization is needed.\n */\n start(): void | Promise<void>;\n /**\n * Stop the store. Override if cleanup is needed.\n */\n stop(): void | Promise<void>;\n}\n"],"mappings":";;;;;AAKA;AAMA;AAAqB,cANAC,qBAAAA,SAA8BC,KAAAA,CAM9B;aAIVE,CAAAA,OAAAA,EAAAA,MAAAA;;;;AAwBX;AAaiBG,UAzCAJ,IAAAA,CAyCY;EAsBZK;AAkEjB;AA8DA;EAMYI,KAAAA,EAjMDR,MAiMCQ,CAAAA,MAAa,EAAA,GAAA,CAAA;EACbC;AACZ;;KACeA,EAAAA,MAAAA;;;AAGf;;;WAAuCL,EAAAA,MAAAA,EAAAA;;;;EAC3BO,SAAAA,EA1LGV,IA0LHU;EAAgB;;;WACJC,EAvLTX,IAuLSW;;;;;;AAA0EV,UAjLjFA,UAAAA,SAAmBH,IAiL8DG,CAAAA;;;;;;;;;AAOlG;AAqCA;AAIA;AAaA;AAAuC,UAjOtBC,YAAAA,CAiOsB;;;;;;;;WAwCtBH,EAAAA,MAAAA,EAAAA;;;;;;;;;;;;;;UAnPAI,eAAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;WAqCJJ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UA6BIK,YAAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;SAqCNL;;;;;;;;;;;;;;;;;;;;;;;;;UAyBMM,uBAAAA;oBACKC;;;;;KAKVC,aAAAA;KACAC,kBAAAA;UACKF,cAAAA;aACFE;QACLD;;KAEEE,SAAAA,GAAYP,eAAeC,kBAAkBC,eAAeC;KAC5DK,wCAAwCD,6BACpCE,QAAQA,MAAMC,WAAWR,sBAAsBO,MAAMC,WAAWT,kBAAkBF,eAAeU,MAAMC,WAAWV,eAAeJ,cAAca,MAAMC,WAAWP;;;;;;UAO/JQ,WAAAA;;;;;;;;;;;;;;;;;;cAkBDlB;;;;;;;;;;;;;;;;;;;iBAmBQmB,aAAAA;;;;iBAIAC,YAAAA;;;;;;;;;;;;;uBAaMC,SAAAA;;;;;;;;4BAQAP,yBAAyBQ,KAAKC,QAAQR,iBAAiBO;;;;;;;;yCAQ1CC,QAAQpB;;;;;;;;;;;;;;;;;;;;;;;;aAwBlCC;;;;MAITmB,QAAQjB;;;;;;;;;;;;;;;;;;;;;;;;+CAwBiCF,gDAAgDmB;;;;;;;4CAOnDA;;;;;;;;;;;;;;;;;;;;;;;;;;;MA2BtCA;;;;kBAIYA;;;;iBAIDA"}