langgraph-checkpoint 4.2.0__tar.gz → 4.3.1__tar.gz
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.
- {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/.gitignore +6 -0
- {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/PKG-INFO +13 -20
- {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/README.md +11 -18
- {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/langgraph/checkpoint/base/__init__.py +32 -3
- {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/langgraph/checkpoint/memory/__init__.py +18 -9
- {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/langgraph/checkpoint/serde/jsonplus.py +34 -8
- {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/langgraph/store/base/__init__.py +93 -11
- {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/langgraph/store/base/batch.py +9 -3
- {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/langgraph/store/base/embed.py +4 -1
- {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/langgraph/store/memory/__init__.py +1 -1
- {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/pyproject.toml +1 -1
- {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/tests/test_jsonplus.py +61 -0
- {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/tests/test_memory.py +13 -0
- {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/tests/test_store.py +140 -1
- {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/uv.lock +59 -58
- langgraph_checkpoint-4.2.0/tests/test_conformance_delta.py +0 -37
- {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/LICENSE +0 -0
- {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/Makefile +0 -0
- {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/langgraph/cache/base/__init__.py +0 -0
- {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/langgraph/cache/base/py.typed +0 -0
- {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/langgraph/cache/memory/__init__.py +0 -0
- {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/langgraph/cache/redis/__init__.py +0 -0
- {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/langgraph/checkpoint/base/id.py +0 -0
- {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/langgraph/checkpoint/base/py.typed +0 -0
- {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/langgraph/checkpoint/memory/py.typed +0 -0
- {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/langgraph/checkpoint/serde/__init__.py +0 -0
- {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/langgraph/checkpoint/serde/_msgpack.py +0 -0
- {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/langgraph/checkpoint/serde/base.py +0 -0
- {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/langgraph/checkpoint/serde/encrypted.py +0 -0
- {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/langgraph/checkpoint/serde/event_hooks.py +0 -0
- {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/langgraph/checkpoint/serde/py.typed +0 -0
- {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/langgraph/checkpoint/serde/types.py +0 -0
- {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/langgraph/store/base/py.typed +0 -0
- {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/langgraph/store/memory/py.typed +0 -0
- {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/tests/__init__.py +0 -0
- {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/tests/embed_test_utils.py +0 -0
- {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/tests/test_encrypted.py +0 -0
- {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/tests/test_redis_cache.py +0 -0
|
@@ -76,7 +76,12 @@ __pypackages__/
|
|
|
76
76
|
|
|
77
77
|
# Environments
|
|
78
78
|
.env
|
|
79
|
+
.env.*
|
|
79
80
|
.envrc
|
|
81
|
+
*.crt
|
|
82
|
+
*.key
|
|
83
|
+
*.pem
|
|
84
|
+
credentials.json
|
|
80
85
|
.venv
|
|
81
86
|
.venvs
|
|
82
87
|
env/
|
|
@@ -98,6 +103,7 @@ dmypy.json
|
|
|
98
103
|
|
|
99
104
|
.vercel
|
|
100
105
|
.turbo
|
|
106
|
+
node_modules/
|
|
101
107
|
.editorconfig
|
|
102
108
|
.scratch
|
|
103
109
|
.worktrees/
|
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
Metadata-Version: 2.
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
2
|
Name: langgraph-checkpoint
|
|
3
|
-
Version: 4.
|
|
3
|
+
Version: 4.3.1
|
|
4
4
|
Summary: Library with base interfaces for LangGraph checkpoint savers.
|
|
5
5
|
Project-URL: Source, https://github.com/langchain-ai/langgraph/tree/main/libs/checkpoint
|
|
6
6
|
Project-URL: Twitter, https://x.com/langchain_oss
|
|
@@ -54,7 +54,12 @@ You must pass these when invoking the graph as part of the configurable part of
|
|
|
54
54
|
|
|
55
55
|
```python
|
|
56
56
|
{"configurable": {"thread_id": "1"}} # valid config
|
|
57
|
-
{
|
|
57
|
+
{
|
|
58
|
+
"configurable": {
|
|
59
|
+
"thread_id": "1",
|
|
60
|
+
"checkpoint_id": "0c62ca34-ac19-445d-bbb0-5b4984975b2a",
|
|
61
|
+
}
|
|
62
|
+
} # also valid config
|
|
58
63
|
```
|
|
59
64
|
|
|
60
65
|
### Serde
|
|
@@ -94,24 +99,12 @@ checkpoint = {
|
|
|
94
99
|
"v": 4,
|
|
95
100
|
"ts": "2024-07-31T20:14:19.804150+00:00",
|
|
96
101
|
"id": "1ef4f797-8335-6428-8001-8a1503f9b875",
|
|
97
|
-
"channel_values": {
|
|
98
|
-
|
|
99
|
-
"node": "node"
|
|
100
|
-
},
|
|
101
|
-
"channel_versions": {
|
|
102
|
-
"__start__": 2,
|
|
103
|
-
"my_key": 3,
|
|
104
|
-
"start:node": 3,
|
|
105
|
-
"node": 3
|
|
106
|
-
},
|
|
102
|
+
"channel_values": {"my_key": "meow", "node": "node"},
|
|
103
|
+
"channel_versions": {"__start__": 2, "my_key": 3, "start:node": 3, "node": 3},
|
|
107
104
|
"versions_seen": {
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
"
|
|
111
|
-
},
|
|
112
|
-
"node": {
|
|
113
|
-
"start:node": 2
|
|
114
|
-
}
|
|
105
|
+
"__input__": {},
|
|
106
|
+
"__start__": {"__start__": 1},
|
|
107
|
+
"node": {"start:node": 2},
|
|
115
108
|
},
|
|
116
109
|
}
|
|
117
110
|
|
|
@@ -39,7 +39,12 @@ You must pass these when invoking the graph as part of the configurable part of
|
|
|
39
39
|
|
|
40
40
|
```python
|
|
41
41
|
{"configurable": {"thread_id": "1"}} # valid config
|
|
42
|
-
{
|
|
42
|
+
{
|
|
43
|
+
"configurable": {
|
|
44
|
+
"thread_id": "1",
|
|
45
|
+
"checkpoint_id": "0c62ca34-ac19-445d-bbb0-5b4984975b2a",
|
|
46
|
+
}
|
|
47
|
+
} # also valid config
|
|
43
48
|
```
|
|
44
49
|
|
|
45
50
|
### Serde
|
|
@@ -79,24 +84,12 @@ checkpoint = {
|
|
|
79
84
|
"v": 4,
|
|
80
85
|
"ts": "2024-07-31T20:14:19.804150+00:00",
|
|
81
86
|
"id": "1ef4f797-8335-6428-8001-8a1503f9b875",
|
|
82
|
-
"channel_values": {
|
|
83
|
-
|
|
84
|
-
"node": "node"
|
|
85
|
-
},
|
|
86
|
-
"channel_versions": {
|
|
87
|
-
"__start__": 2,
|
|
88
|
-
"my_key": 3,
|
|
89
|
-
"start:node": 3,
|
|
90
|
-
"node": 3
|
|
91
|
-
},
|
|
87
|
+
"channel_values": {"my_key": "meow", "node": "node"},
|
|
88
|
+
"channel_versions": {"__start__": 2, "my_key": 3, "start:node": 3, "node": 3},
|
|
92
89
|
"versions_seen": {
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
"
|
|
96
|
-
},
|
|
97
|
-
"node": {
|
|
98
|
-
"start:node": 2
|
|
99
|
-
}
|
|
90
|
+
"__input__": {},
|
|
91
|
+
"__start__": {"__start__": 1},
|
|
92
|
+
"node": {"start:node": 2},
|
|
100
93
|
},
|
|
101
94
|
}
|
|
102
95
|
|
{langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/langgraph/checkpoint/base/__init__.py
RENAMED
|
@@ -10,6 +10,7 @@ from typing import (
|
|
|
10
10
|
NamedTuple,
|
|
11
11
|
TypedDict,
|
|
12
12
|
TypeVar,
|
|
13
|
+
cast,
|
|
13
14
|
)
|
|
14
15
|
|
|
15
16
|
from langchain_core.runnables import RunnableConfig
|
|
@@ -161,6 +162,14 @@ class DeltaChannelHistory(TypedDict):
|
|
|
161
162
|
Always present; possibly empty. Already filtered to one channel.
|
|
162
163
|
Writes stored at the target checkpoint itself are pending for the
|
|
163
164
|
next super-step and are excluded.
|
|
165
|
+
|
|
166
|
+
Within a single checkpoint, writes are ordered by `writes_sort_key`,
|
|
167
|
+
`(task_path, task_id, idx)`, which is the order live execution applies
|
|
168
|
+
a super-step's task writes in. `task_id` is a hash of the path, so
|
|
169
|
+
ordering by it permutes parallel tasks writing one channel, and
|
|
170
|
+
reducers need not be order-invariant. Writes stored without a
|
|
171
|
+
`task_path` (graph input, `update_state` and `Command` updates, rows
|
|
172
|
+
predating the column) sort first, by `task_id`.
|
|
164
173
|
* `seed` — the stored value at the nearest ancestor whose
|
|
165
174
|
`channel_values[ch]` is populated. Omitted if the walk reached the
|
|
166
175
|
root without finding any stored value (consumer treats absence as
|
|
@@ -173,6 +182,20 @@ class DeltaChannelHistory(TypedDict):
|
|
|
173
182
|
seed: NotRequired[Any]
|
|
174
183
|
|
|
175
184
|
|
|
185
|
+
def writes_sort_key(
|
|
186
|
+
task_path: str, task_id: str = "", idx: int = 0
|
|
187
|
+
) -> tuple[str, str, int]:
|
|
188
|
+
"""Sort key for the writes of one super-step.
|
|
189
|
+
|
|
190
|
+
Live execution applies a super-step's tasks in this order, so a saver
|
|
191
|
+
that replays stored writes, as `get_delta_channel_history` does, must
|
|
192
|
+
sort them by it too, or an order-sensitive reducer rebuilds a different
|
|
193
|
+
value than the run produced. `task_path` is the string passed to
|
|
194
|
+
`put_writes`.
|
|
195
|
+
"""
|
|
196
|
+
return (task_path, task_id, idx)
|
|
197
|
+
|
|
198
|
+
|
|
176
199
|
class BaseCheckpointSaver(Generic[V]):
|
|
177
200
|
"""Base class for creating a graph checkpointer.
|
|
178
201
|
|
|
@@ -243,7 +266,8 @@ class BaseCheckpointSaver(Generic[V]):
|
|
|
243
266
|
config: Configuration specifying which checkpoint to retrieve.
|
|
244
267
|
|
|
245
268
|
Returns:
|
|
246
|
-
The requested checkpoint tuple, or `None` if not found.
|
|
269
|
+
The requested checkpoint tuple, or `None` if not found. Its
|
|
270
|
+
`pending_writes` must be in `writes_sort_key` order.
|
|
247
271
|
|
|
248
272
|
Raises:
|
|
249
273
|
NotImplementedError: Implement this method in your custom checkpoint saver.
|
|
@@ -433,7 +457,8 @@ class BaseCheckpointSaver(Generic[V]):
|
|
|
433
457
|
config: Configuration specifying which checkpoint to retrieve.
|
|
434
458
|
|
|
435
459
|
Returns:
|
|
436
|
-
The requested checkpoint tuple, or `None` if not found.
|
|
460
|
+
The requested checkpoint tuple, or `None` if not found. Its
|
|
461
|
+
`pending_writes` must be in `writes_sort_key` order.
|
|
437
462
|
|
|
438
463
|
Raises:
|
|
439
464
|
NotImplementedError: Implement this method in your custom checkpoint saver.
|
|
@@ -610,6 +635,10 @@ class BaseCheckpointSaver(Generic[V]):
|
|
|
610
635
|
`PostgresSaver`) override for performance; the return contract is
|
|
611
636
|
fixed here.
|
|
612
637
|
|
|
638
|
+
`PendingWrite` carries no `task_path`, so this default replays each
|
|
639
|
+
checkpoint's writes in `get_tuple`'s `pending_writes` order, which
|
|
640
|
+
`get_tuple` must return in `writes_sort_key` order.
|
|
641
|
+
|
|
613
642
|
Args:
|
|
614
643
|
config: Configuration identifying the target checkpoint.
|
|
615
644
|
channels: Channel names to walk for. Empty → empty mapping.
|
|
@@ -781,7 +810,7 @@ def get_serializable_checkpoint_metadata(
|
|
|
781
810
|
"""Get checkpoint metadata in a backwards-compatible manner."""
|
|
782
811
|
checkpoint_metadata = get_checkpoint_metadata(config, metadata)
|
|
783
812
|
if "writes" in checkpoint_metadata:
|
|
784
|
-
checkpoint_metadata.pop("writes")
|
|
813
|
+
cast(dict[str, Any], checkpoint_metadata).pop("writes")
|
|
785
814
|
return checkpoint_metadata
|
|
786
815
|
|
|
787
816
|
|
{langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/langgraph/checkpoint/memory/__init__.py
RENAMED
|
@@ -25,6 +25,7 @@ from langgraph.checkpoint.base import (
|
|
|
25
25
|
SerializerProtocol,
|
|
26
26
|
get_checkpoint_id,
|
|
27
27
|
get_checkpoint_metadata,
|
|
28
|
+
writes_sort_key,
|
|
28
29
|
)
|
|
29
30
|
|
|
30
31
|
logger = logging.getLogger(__name__)
|
|
@@ -139,6 +140,15 @@ class InMemorySaver(
|
|
|
139
140
|
result[k] = self.serde.loads_typed(vv)
|
|
140
141
|
return result
|
|
141
142
|
|
|
143
|
+
def _ordered_writes(
|
|
144
|
+
self, thread_id: str, checkpoint_ns: str, checkpoint_id: str
|
|
145
|
+
) -> list[tuple[str, str, tuple[str, bytes], str]]:
|
|
146
|
+
stored = self.writes.get((thread_id, checkpoint_ns, checkpoint_id), {})
|
|
147
|
+
return [
|
|
148
|
+
stored[k]
|
|
149
|
+
for k in sorted(stored, key=lambda k: writes_sort_key(stored[k][3], *k))
|
|
150
|
+
]
|
|
151
|
+
|
|
142
152
|
def get_delta_channel_history(
|
|
143
153
|
self, *, config: RunnableConfig, channels: Sequence[str]
|
|
144
154
|
) -> Mapping[str, DeltaChannelHistory]:
|
|
@@ -160,8 +170,8 @@ class InMemorySaver(
|
|
|
160
170
|
return {}
|
|
161
171
|
thread_id = config["configurable"]["thread_id"]
|
|
162
172
|
checkpoint_ns = config["configurable"].get("checkpoint_ns", "")
|
|
163
|
-
checkpoint_id = config["configurable"].get("checkpoint_id", "")
|
|
164
173
|
ns_storage = self.storage.get(thread_id, {}).get(checkpoint_ns, {})
|
|
174
|
+
checkpoint_id = get_checkpoint_id(config) or max(ns_storage, default="")
|
|
165
175
|
|
|
166
176
|
chain: list[str] = []
|
|
167
177
|
target_entry = ns_storage.get(checkpoint_id)
|
|
@@ -198,9 +208,8 @@ class InMemorySaver(
|
|
|
198
208
|
blob_value_by_ch[ch] = self.serde.loads_typed(blob_entry)
|
|
199
209
|
terminated_here.add(ch)
|
|
200
210
|
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
step_writes.items(), reverse=True
|
|
211
|
+
for tid, ch, serialized, _ in reversed(
|
|
212
|
+
self._ordered_writes(thread_id, checkpoint_ns, cp_id)
|
|
204
213
|
):
|
|
205
214
|
if ch not in remaining:
|
|
206
215
|
continue
|
|
@@ -246,7 +255,7 @@ class InMemorySaver(
|
|
|
246
255
|
if checkpoint_id := get_checkpoint_id(config):
|
|
247
256
|
if saved := self.storage[thread_id][checkpoint_ns].get(checkpoint_id):
|
|
248
257
|
checkpoint, metadata, parent_checkpoint_id = saved
|
|
249
|
-
writes = self.
|
|
258
|
+
writes = self._ordered_writes(thread_id, checkpoint_ns, checkpoint_id)
|
|
250
259
|
checkpoint_: Checkpoint = self.serde.loads_typed(checkpoint)
|
|
251
260
|
return CheckpointTuple(
|
|
252
261
|
config=config,
|
|
@@ -276,7 +285,7 @@ class InMemorySaver(
|
|
|
276
285
|
if checkpoints := self.storage[thread_id][checkpoint_ns]:
|
|
277
286
|
checkpoint_id = max(checkpoints.keys())
|
|
278
287
|
checkpoint, metadata, parent_checkpoint_id = checkpoints[checkpoint_id]
|
|
279
|
-
writes = self.
|
|
288
|
+
writes = self._ordered_writes(thread_id, checkpoint_ns, checkpoint_id)
|
|
280
289
|
checkpoint_ = self.serde.loads_typed(checkpoint)
|
|
281
290
|
return CheckpointTuple(
|
|
282
291
|
config={
|
|
@@ -379,9 +388,9 @@ class InMemorySaver(
|
|
|
379
388
|
elif limit is not None:
|
|
380
389
|
limit -= 1
|
|
381
390
|
|
|
382
|
-
writes = self.
|
|
383
|
-
|
|
384
|
-
|
|
391
|
+
writes = self._ordered_writes(
|
|
392
|
+
thread_id, checkpoint_ns, checkpoint_id
|
|
393
|
+
)
|
|
385
394
|
|
|
386
395
|
checkpoint_: Checkpoint = self.serde.loads_typed(checkpoint)
|
|
387
396
|
|
{langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/langgraph/checkpoint/serde/jsonplus.py
RENAMED
|
@@ -55,6 +55,7 @@ logger = logging.getLogger(__name__)
|
|
|
55
55
|
_MAX_WARNED_TYPES = 1000
|
|
56
56
|
_warned_unregistered_types: set[tuple[str, str]] = set()
|
|
57
57
|
_warned_blocked_types: set[tuple[str, str]] = set()
|
|
58
|
+
_warned_unreconstructable_types: set[tuple[str, str]] = set()
|
|
58
59
|
|
|
59
60
|
|
|
60
61
|
def _is_safe_json_type(id_list: list[str]) -> bool:
|
|
@@ -79,6 +80,27 @@ def _warn_once(
|
|
|
79
80
|
logger.warning(msg, *args)
|
|
80
81
|
|
|
81
82
|
|
|
83
|
+
def _reconstruction_fallback(tup: Any, exc: Exception) -> Any:
|
|
84
|
+
"""Return the serialized payload of an object that could not be rebuilt.
|
|
85
|
+
|
|
86
|
+
Returning `None` here would silently erase the value from restored state.
|
|
87
|
+
"""
|
|
88
|
+
try:
|
|
89
|
+
module, name, payload = tup[0], tup[1], tup[2]
|
|
90
|
+
except Exception:
|
|
91
|
+
return None
|
|
92
|
+
_warn_once(
|
|
93
|
+
_warned_unreconstructable_types,
|
|
94
|
+
(str(module), str(name)),
|
|
95
|
+
"Could not reconstruct %s.%s from checkpoint (%s); "
|
|
96
|
+
"returning its serialized data instead.",
|
|
97
|
+
module,
|
|
98
|
+
name,
|
|
99
|
+
type(exc).__name__,
|
|
100
|
+
)
|
|
101
|
+
return payload
|
|
102
|
+
|
|
103
|
+
|
|
82
104
|
class JsonPlusSerializer(SerializerProtocol):
|
|
83
105
|
"""Serializer that uses ormsgpack, with optional fallbacks.
|
|
84
106
|
|
|
@@ -638,6 +660,7 @@ def _create_msgpack_ext_hook(
|
|
|
638
660
|
)
|
|
639
661
|
)
|
|
640
662
|
elif code == EXT_CONSTRUCTOR_SINGLE_ARG:
|
|
663
|
+
tup = None
|
|
641
664
|
try:
|
|
642
665
|
tup = ormsgpack.unpackb(
|
|
643
666
|
data, ext_hook=ext_hook, option=ormsgpack.OPT_NON_STR_KEYS
|
|
@@ -649,9 +672,10 @@ def _create_msgpack_ext_hook(
|
|
|
649
672
|
return tup[2]
|
|
650
673
|
# module, name, arg
|
|
651
674
|
return getattr(importlib.import_module(tup[0]), tup[1])(tup[2])
|
|
652
|
-
except Exception:
|
|
653
|
-
return
|
|
675
|
+
except Exception as exc:
|
|
676
|
+
return _reconstruction_fallback(tup, exc)
|
|
654
677
|
elif code == EXT_CONSTRUCTOR_POS_ARGS:
|
|
678
|
+
tup = None
|
|
655
679
|
try:
|
|
656
680
|
tup = ormsgpack.unpackb(
|
|
657
681
|
data, ext_hook=ext_hook, option=ormsgpack.OPT_NON_STR_KEYS
|
|
@@ -662,9 +686,10 @@ def _create_msgpack_ext_hook(
|
|
|
662
686
|
return _send_from_args(tup[2])
|
|
663
687
|
# module, name, args
|
|
664
688
|
return getattr(importlib.import_module(tup[0]), tup[1])(*tup[2])
|
|
665
|
-
except Exception:
|
|
666
|
-
return
|
|
689
|
+
except Exception as exc:
|
|
690
|
+
return _reconstruction_fallback(tup, exc)
|
|
667
691
|
elif code == EXT_CONSTRUCTOR_KW_ARGS:
|
|
692
|
+
tup = None
|
|
668
693
|
try:
|
|
669
694
|
tup = ormsgpack.unpackb(
|
|
670
695
|
data, ext_hook=ext_hook, option=ormsgpack.OPT_NON_STR_KEYS
|
|
@@ -673,9 +698,10 @@ def _create_msgpack_ext_hook(
|
|
|
673
698
|
return tup[2]
|
|
674
699
|
# module, name, kwargs
|
|
675
700
|
return getattr(importlib.import_module(tup[0]), tup[1])(**tup[2])
|
|
676
|
-
except Exception:
|
|
677
|
-
return
|
|
701
|
+
except Exception as exc:
|
|
702
|
+
return _reconstruction_fallback(tup, exc)
|
|
678
703
|
elif code == EXT_METHOD_SINGLE_ARG:
|
|
704
|
+
tup = None
|
|
679
705
|
try:
|
|
680
706
|
tup = ormsgpack.unpackb(
|
|
681
707
|
data, ext_hook=ext_hook, option=ormsgpack.OPT_NON_STR_KEYS
|
|
@@ -686,8 +712,8 @@ def _create_msgpack_ext_hook(
|
|
|
686
712
|
return getattr(
|
|
687
713
|
getattr(importlib.import_module(tup[0]), tup[1]), tup[3]
|
|
688
714
|
)(tup[2])
|
|
689
|
-
except Exception:
|
|
690
|
-
return
|
|
715
|
+
except Exception as exc:
|
|
716
|
+
return _reconstruction_fallback(tup, exc)
|
|
691
717
|
elif code == EXT_PYDANTIC_V1:
|
|
692
718
|
try:
|
|
693
719
|
tup = ormsgpack.unpackb(
|
|
@@ -12,7 +12,7 @@ Core types:
|
|
|
12
12
|
from __future__ import annotations
|
|
13
13
|
|
|
14
14
|
from abc import ABC, abstractmethod
|
|
15
|
-
from collections.abc import Iterable
|
|
15
|
+
from collections.abc import Iterable, Mapping
|
|
16
16
|
from datetime import datetime
|
|
17
17
|
from typing import (
|
|
18
18
|
Any,
|
|
@@ -473,10 +473,10 @@ class PutOp(NamedTuple):
|
|
|
473
473
|
the full path would effectively be `"documents/user123/report1"`
|
|
474
474
|
"""
|
|
475
475
|
|
|
476
|
-
value:
|
|
476
|
+
value: Mapping[str, Any] | None
|
|
477
477
|
"""The data to store, or `None` to mark the item for deletion.
|
|
478
478
|
|
|
479
|
-
The value must be a
|
|
479
|
+
The value must be a mapping with string keys and JSON-serializable values.
|
|
480
480
|
Setting this to `None` signals that the item should be deleted.
|
|
481
481
|
|
|
482
482
|
Example:
|
|
@@ -771,7 +771,12 @@ class BaseStore(ABC):
|
|
|
771
771
|
|
|
772
772
|
Returns:
|
|
773
773
|
The retrieved item or `None` if not found.
|
|
774
|
+
|
|
775
|
+
Raises:
|
|
776
|
+
InvalidNamespaceError: If a namespace label is empty, is not a string,
|
|
777
|
+
or contains a period (`.`).
|
|
774
778
|
"""
|
|
779
|
+
_validate_namespace_labels(namespace)
|
|
775
780
|
return self.batch(
|
|
776
781
|
[GetOp(namespace, str(key), _ensure_refresh(self.ttl_config, refresh_ttl))]
|
|
777
782
|
)[0]
|
|
@@ -801,6 +806,10 @@ class BaseStore(ABC):
|
|
|
801
806
|
Returns:
|
|
802
807
|
List of items matching the search criteria.
|
|
803
808
|
|
|
809
|
+
Raises:
|
|
810
|
+
InvalidNamespaceError: If a `namespace_prefix` label is empty, is not a
|
|
811
|
+
string, or contains a period (`.`).
|
|
812
|
+
|
|
804
813
|
???+ example "Examples"
|
|
805
814
|
|
|
806
815
|
Basic filtering:
|
|
@@ -840,6 +849,7 @@ class BaseStore(ABC):
|
|
|
840
849
|
Natural language search support depends on your store implementation
|
|
841
850
|
and requires proper embedding configuration.
|
|
842
851
|
"""
|
|
852
|
+
_validate_namespace_labels(namespace_prefix)
|
|
843
853
|
return self.batch(
|
|
844
854
|
[
|
|
845
855
|
SearchOp(
|
|
@@ -857,7 +867,7 @@ class BaseStore(ABC):
|
|
|
857
867
|
self,
|
|
858
868
|
namespace: tuple[str, ...],
|
|
859
869
|
key: str,
|
|
860
|
-
value:
|
|
870
|
+
value: Mapping[str, Any],
|
|
861
871
|
index: Literal[False] | list[str] | None = None,
|
|
862
872
|
*,
|
|
863
873
|
ttl: float | None | NotProvided = NOT_PROVIDED,
|
|
@@ -869,7 +879,7 @@ class BaseStore(ABC):
|
|
|
869
879
|
Example: `("documents", "user123")`
|
|
870
880
|
key: Unique identifier within the namespace. Together with namespace forms
|
|
871
881
|
the complete path to the item.
|
|
872
|
-
value:
|
|
882
|
+
value: Mapping containing the item's data. Must contain string keys
|
|
873
883
|
and JSON-serializable values.
|
|
874
884
|
index: Controls how the item's fields are indexed for search:
|
|
875
885
|
|
|
@@ -887,6 +897,11 @@ class BaseStore(ABC):
|
|
|
887
897
|
By default, the expiration timer refreshes on both read operations (get/search)
|
|
888
898
|
and write operations (put/update), whenever the item is included in the operation.
|
|
889
899
|
|
|
900
|
+
Raises:
|
|
901
|
+
InvalidNamespaceError: If the namespace is empty, its root label is
|
|
902
|
+
`"langgraph"`, or a label is empty, is not a string, or contains a
|
|
903
|
+
period (`.`).
|
|
904
|
+
|
|
890
905
|
Note:
|
|
891
906
|
Indexing support depends on your store implementation.
|
|
892
907
|
If you do not initialize the store with indexing capabilities,
|
|
@@ -940,7 +955,12 @@ class BaseStore(ABC):
|
|
|
940
955
|
Args:
|
|
941
956
|
namespace: Hierarchical path for the item.
|
|
942
957
|
key: Unique identifier within the namespace.
|
|
958
|
+
|
|
959
|
+
Raises:
|
|
960
|
+
InvalidNamespaceError: If a namespace label is empty, is not a string,
|
|
961
|
+
or contains a period (`.`).
|
|
943
962
|
"""
|
|
963
|
+
_validate_namespace_labels(namespace)
|
|
944
964
|
self.batch([PutOp(namespace, str(key), None, ttl=None)])
|
|
945
965
|
|
|
946
966
|
def list_namespaces(
|
|
@@ -969,6 +989,10 @@ class BaseStore(ABC):
|
|
|
969
989
|
A list of namespace tuples that match the criteria. Each tuple represents a
|
|
970
990
|
full namespace path up to `max_depth`.
|
|
971
991
|
|
|
992
|
+
Raises:
|
|
993
|
+
InvalidNamespaceError: If a `prefix` or `suffix` label is empty, is not a
|
|
994
|
+
string, or contains a period (`.`).
|
|
995
|
+
|
|
972
996
|
???+ example "Examples":
|
|
973
997
|
|
|
974
998
|
Setting `max_depth=3`. Given the namespaces:
|
|
@@ -984,6 +1008,8 @@ class BaseStore(ABC):
|
|
|
984
1008
|
# [("a", "b", "c"), ("a", "b", "d"), ("a", "b", "f")]
|
|
985
1009
|
```
|
|
986
1010
|
"""
|
|
1011
|
+
_validate_namespace_labels(prefix or ())
|
|
1012
|
+
_validate_namespace_labels(suffix or ())
|
|
987
1013
|
match_conditions = []
|
|
988
1014
|
if prefix:
|
|
989
1015
|
match_conditions.append(MatchCondition(match_type="prefix", path=prefix))
|
|
@@ -1013,7 +1039,12 @@ class BaseStore(ABC):
|
|
|
1013
1039
|
|
|
1014
1040
|
Returns:
|
|
1015
1041
|
The retrieved item or `None` if not found.
|
|
1042
|
+
|
|
1043
|
+
Raises:
|
|
1044
|
+
InvalidNamespaceError: If a namespace label is empty, is not a string,
|
|
1045
|
+
or contains a period (`.`).
|
|
1016
1046
|
"""
|
|
1047
|
+
_validate_namespace_labels(namespace)
|
|
1017
1048
|
return (
|
|
1018
1049
|
await self.abatch(
|
|
1019
1050
|
[
|
|
@@ -1052,6 +1083,10 @@ class BaseStore(ABC):
|
|
|
1052
1083
|
Returns:
|
|
1053
1084
|
List of items matching the search criteria.
|
|
1054
1085
|
|
|
1086
|
+
Raises:
|
|
1087
|
+
InvalidNamespaceError: If a `namespace_prefix` label is empty, is not a
|
|
1088
|
+
string, or contains a period (`.`).
|
|
1089
|
+
|
|
1055
1090
|
???+ example "Examples"
|
|
1056
1091
|
|
|
1057
1092
|
Basic filtering:
|
|
@@ -1091,6 +1126,7 @@ class BaseStore(ABC):
|
|
|
1091
1126
|
Natural language search support depends on your store implementation
|
|
1092
1127
|
and requires proper embedding configuration.
|
|
1093
1128
|
"""
|
|
1129
|
+
_validate_namespace_labels(namespace_prefix)
|
|
1094
1130
|
return (
|
|
1095
1131
|
await self.abatch(
|
|
1096
1132
|
[
|
|
@@ -1110,7 +1146,7 @@ class BaseStore(ABC):
|
|
|
1110
1146
|
self,
|
|
1111
1147
|
namespace: tuple[str, ...],
|
|
1112
1148
|
key: str,
|
|
1113
|
-
value:
|
|
1149
|
+
value: Mapping[str, Any],
|
|
1114
1150
|
index: Literal[False] | list[str] | None = None,
|
|
1115
1151
|
*,
|
|
1116
1152
|
ttl: float | None | NotProvided = NOT_PROVIDED,
|
|
@@ -1122,7 +1158,7 @@ class BaseStore(ABC):
|
|
|
1122
1158
|
Example: `("documents", "user123")`
|
|
1123
1159
|
key: Unique identifier within the namespace. Together with namespace forms
|
|
1124
1160
|
the complete path to the item.
|
|
1125
|
-
value:
|
|
1161
|
+
value: Mapping containing the item's data. Must contain string keys
|
|
1126
1162
|
and JSON-serializable values.
|
|
1127
1163
|
index: Controls how the item's fields are indexed for search:
|
|
1128
1164
|
|
|
@@ -1140,6 +1176,11 @@ class BaseStore(ABC):
|
|
|
1140
1176
|
By default, the expiration timer refreshes on both read operations (get/search)
|
|
1141
1177
|
and write operations (put/update), whenever the item is included in the operation.
|
|
1142
1178
|
|
|
1179
|
+
Raises:
|
|
1180
|
+
InvalidNamespaceError: If the namespace is empty, its root label is
|
|
1181
|
+
`"langgraph"`, or a label is empty, is not a string, or contains a
|
|
1182
|
+
period (`.`).
|
|
1183
|
+
|
|
1143
1184
|
Note:
|
|
1144
1185
|
Indexing support depends on your store implementation.
|
|
1145
1186
|
If you do not initialize the store with indexing capabilities,
|
|
@@ -1201,7 +1242,12 @@ class BaseStore(ABC):
|
|
|
1201
1242
|
Args:
|
|
1202
1243
|
namespace: Hierarchical path for the item.
|
|
1203
1244
|
key: Unique identifier within the namespace.
|
|
1245
|
+
|
|
1246
|
+
Raises:
|
|
1247
|
+
InvalidNamespaceError: If a namespace label is empty, is not a string,
|
|
1248
|
+
or contains a period (`.`).
|
|
1204
1249
|
"""
|
|
1250
|
+
_validate_namespace_labels(namespace)
|
|
1205
1251
|
await self.abatch([PutOp(namespace, str(key), None)])
|
|
1206
1252
|
|
|
1207
1253
|
async def alist_namespaces(
|
|
@@ -1230,6 +1276,10 @@ class BaseStore(ABC):
|
|
|
1230
1276
|
A list of namespace tuples that match the criteria. Each tuple represents a
|
|
1231
1277
|
full namespace path up to `max_depth`.
|
|
1232
1278
|
|
|
1279
|
+
Raises:
|
|
1280
|
+
InvalidNamespaceError: If a `prefix` or `suffix` label is empty, is not a
|
|
1281
|
+
string, or contains a period (`.`).
|
|
1282
|
+
|
|
1233
1283
|
???+ example "Examples"
|
|
1234
1284
|
|
|
1235
1285
|
Setting `max_depth=3` with existing namespaces:
|
|
@@ -1245,6 +1295,8 @@ class BaseStore(ABC):
|
|
|
1245
1295
|
# Returns: [("a", "b", "c"), ("a", "b", "d"), ("a", "b", "f")]
|
|
1246
1296
|
```
|
|
1247
1297
|
"""
|
|
1298
|
+
_validate_namespace_labels(prefix or ())
|
|
1299
|
+
_validate_namespace_labels(suffix or ())
|
|
1248
1300
|
match_conditions = []
|
|
1249
1301
|
if prefix:
|
|
1250
1302
|
match_conditions.append(MatchCondition(match_type="prefix", path=prefix))
|
|
@@ -1263,6 +1315,14 @@ class BaseStore(ABC):
|
|
|
1263
1315
|
def _validate_namespace(namespace: tuple[str, ...]) -> None:
|
|
1264
1316
|
if not namespace:
|
|
1265
1317
|
raise InvalidNamespaceError("Namespace cannot be empty.")
|
|
1318
|
+
_validate_namespace_labels(namespace)
|
|
1319
|
+
if namespace[0] == "langgraph":
|
|
1320
|
+
raise InvalidNamespaceError(
|
|
1321
|
+
f'Root label for namespace cannot be "langgraph". Got: {namespace}'
|
|
1322
|
+
)
|
|
1323
|
+
|
|
1324
|
+
|
|
1325
|
+
def _validate_namespace_labels(namespace: tuple[str, ...]) -> None:
|
|
1266
1326
|
for label in namespace:
|
|
1267
1327
|
if not isinstance(label, str):
|
|
1268
1328
|
raise InvalidNamespaceError(
|
|
@@ -1273,14 +1333,35 @@ def _validate_namespace(namespace: tuple[str, ...]) -> None:
|
|
|
1273
1333
|
raise InvalidNamespaceError(
|
|
1274
1334
|
f"Invalid namespace label '{label}' found in {namespace}. Namespace labels cannot contain periods ('.')."
|
|
1275
1335
|
)
|
|
1336
|
+
elif "\x00" in label:
|
|
1337
|
+
raise InvalidNamespaceError(
|
|
1338
|
+
f"Invalid namespace label '{label}' found in {namespace}. Namespace labels cannot contain NUL bytes ('\\x00')."
|
|
1339
|
+
)
|
|
1276
1340
|
elif not label:
|
|
1277
1341
|
raise InvalidNamespaceError(
|
|
1278
1342
|
f"Namespace labels cannot be empty strings. Got {label} in {namespace}"
|
|
1279
1343
|
)
|
|
1280
|
-
|
|
1281
|
-
|
|
1282
|
-
|
|
1283
|
-
|
|
1344
|
+
|
|
1345
|
+
|
|
1346
|
+
def validate_op_namespace(op: Op) -> None:
|
|
1347
|
+
"""Validate the namespace labels an op carries before a store executes it.
|
|
1348
|
+
|
|
1349
|
+
`BaseStore` methods check labels before batching, but ops passed directly to
|
|
1350
|
+
`batch`/`abatch` skip those methods. Stores that serialize namespaces as
|
|
1351
|
+
delimited text should call this for every op they execute, so a label such
|
|
1352
|
+
as `"foo.bar"` cannot address the namespace `("foo", "bar")`.
|
|
1353
|
+
|
|
1354
|
+
Raises:
|
|
1355
|
+
InvalidNamespaceError: If a label is empty, is not a string, or contains
|
|
1356
|
+
a period (`.`).
|
|
1357
|
+
"""
|
|
1358
|
+
if isinstance(op, (GetOp, PutOp)):
|
|
1359
|
+
_validate_namespace_labels(op.namespace)
|
|
1360
|
+
elif isinstance(op, SearchOp):
|
|
1361
|
+
_validate_namespace_labels(op.namespace_prefix)
|
|
1362
|
+
elif isinstance(op, ListNamespacesOp):
|
|
1363
|
+
for condition in op.match_conditions or ():
|
|
1364
|
+
_validate_namespace_labels(condition.path)
|
|
1284
1365
|
|
|
1285
1366
|
|
|
1286
1367
|
def _ensure_refresh(
|
|
@@ -1319,4 +1400,5 @@ __all__ = [
|
|
|
1319
1400
|
"ensure_embeddings",
|
|
1320
1401
|
"tokenize_path",
|
|
1321
1402
|
"get_text_at_path",
|
|
1403
|
+
"validate_op_namespace",
|
|
1322
1404
|
]
|