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.
Files changed (38) hide show
  1. {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/.gitignore +6 -0
  2. {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/PKG-INFO +13 -20
  3. {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/README.md +11 -18
  4. {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/langgraph/checkpoint/base/__init__.py +32 -3
  5. {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/langgraph/checkpoint/memory/__init__.py +18 -9
  6. {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/langgraph/checkpoint/serde/jsonplus.py +34 -8
  7. {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/langgraph/store/base/__init__.py +93 -11
  8. {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/langgraph/store/base/batch.py +9 -3
  9. {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/langgraph/store/base/embed.py +4 -1
  10. {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/langgraph/store/memory/__init__.py +1 -1
  11. {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/pyproject.toml +1 -1
  12. {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/tests/test_jsonplus.py +61 -0
  13. {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/tests/test_memory.py +13 -0
  14. {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/tests/test_store.py +140 -1
  15. {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/uv.lock +59 -58
  16. langgraph_checkpoint-4.2.0/tests/test_conformance_delta.py +0 -37
  17. {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/LICENSE +0 -0
  18. {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/Makefile +0 -0
  19. {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/langgraph/cache/base/__init__.py +0 -0
  20. {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/langgraph/cache/base/py.typed +0 -0
  21. {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/langgraph/cache/memory/__init__.py +0 -0
  22. {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/langgraph/cache/redis/__init__.py +0 -0
  23. {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/langgraph/checkpoint/base/id.py +0 -0
  24. {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/langgraph/checkpoint/base/py.typed +0 -0
  25. {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/langgraph/checkpoint/memory/py.typed +0 -0
  26. {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/langgraph/checkpoint/serde/__init__.py +0 -0
  27. {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/langgraph/checkpoint/serde/_msgpack.py +0 -0
  28. {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/langgraph/checkpoint/serde/base.py +0 -0
  29. {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/langgraph/checkpoint/serde/encrypted.py +0 -0
  30. {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/langgraph/checkpoint/serde/event_hooks.py +0 -0
  31. {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/langgraph/checkpoint/serde/py.typed +0 -0
  32. {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/langgraph/checkpoint/serde/types.py +0 -0
  33. {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/langgraph/store/base/py.typed +0 -0
  34. {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/langgraph/store/memory/py.typed +0 -0
  35. {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/tests/__init__.py +0 -0
  36. {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/tests/embed_test_utils.py +0 -0
  37. {langgraph_checkpoint-4.2.0 → langgraph_checkpoint-4.3.1}/tests/test_encrypted.py +0 -0
  38. {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.4
1
+ Metadata-Version: 2.5
2
2
  Name: langgraph-checkpoint
3
- Version: 4.2.0
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
- {"configurable": {"thread_id": "1", "checkpoint_id": "0c62ca34-ac19-445d-bbb0-5b4984975b2a"}} # also valid config
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
- "my_key": "meow",
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
- "__input__": {},
109
- "__start__": {
110
- "__start__": 1
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
- {"configurable": {"thread_id": "1", "checkpoint_id": "0c62ca34-ac19-445d-bbb0-5b4984975b2a"}} # also valid config
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
- "my_key": "meow",
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
- "__input__": {},
94
- "__start__": {
95
- "__start__": 1
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
 
@@ -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
 
@@ -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
- step_writes = self.writes.get((thread_id, checkpoint_ns, cp_id), {})
202
- for (_task_id, _idx), (tid, ch, serialized, _) in sorted(
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.writes[(thread_id, checkpoint_ns, checkpoint_id)].values()
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.writes[(thread_id, checkpoint_ns, checkpoint_id)].values()
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.writes[
383
- (thread_id, checkpoint_ns, checkpoint_id)
384
- ].values()
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
 
@@ -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 None
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 None
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 None
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 None
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: dict[str, Any] | None
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 dictionary with string keys and JSON-serializable values.
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: dict[str, Any],
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: Dictionary containing the item's data. Must contain string keys
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: dict[str, Any],
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: Dictionary containing the item's data. Must contain string keys
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
- if namespace[0] == "langgraph":
1281
- raise InvalidNamespaceError(
1282
- f'Root label for namespace cannot be "langgraph". Got: {namespace}'
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
  ]