"""A LangGraph checkpointer on the shared execution volume. There is no Postgres here, and SQLite isn't safe on a network volume with several replicas, so each thread keeps its own write-once files, taken under a file lock: ///.ckpt one checkpoint, serialised ///.writes its pending writes, one per line The newest checkpoint is the highest id: LangGraph's ids sort by time. """ from __future__ import annotations import base64 import fcntl import json import re from collections.abc import AsyncIterator, Iterator, Sequence from pathlib import Path from typing import Any from langchain_core.runnables import RunnableConfig from langgraph.checkpoint.base import ( BaseCheckpointSaver, ChannelVersions, Checkpoint, CheckpointMetadata, CheckpointTuple, get_checkpoint_id, ) _SAFE = re.compile(r"[^A-Za-z0-9_.-]") def _name(value: str) -> str: return _SAFE.sub("_", value) or "root" def _dump(serde: Any, value: Any) -> dict[str, str]: kind, data = serde.dumps_typed(value) return {"type": kind, "data": base64.b64encode(data).decode()} def _load(serde: Any, stored: dict[str, str]) -> Any: return serde.loads_typed((stored["type"], base64.b64decode(stored["data"]))) class VolumeSaver(BaseCheckpointSaver): def __init__(self, root: Path) -> None: super().__init__() self._root = Path(root) def _dir(self, config: RunnableConfig) -> Path: options = config["configurable"] return self._root / _name(str(options["thread_id"])) / _name(str(options.get("checkpoint_ns", ""))) def _locked(self, folder: Path) -> Any: folder.mkdir(parents=True, exist_ok=True) lock = (folder / ".lock").open("a+") fcntl.flock(lock, fcntl.LOCK_EX) return lock def get_tuple(self, config: RunnableConfig) -> CheckpointTuple | None: folder = self._dir(config) wanted = get_checkpoint_id(config) if not folder.is_dir(): return None path = folder / f"{wanted}.ckpt" if wanted else max(folder.glob("*.ckpt"), default=None) if path is None or not path.exists(): return None return self._tuple(config, path) def _tuple(self, config: RunnableConfig, path: Path) -> CheckpointTuple: options = config["configurable"] stored = json.loads(path.read_text(encoding="utf-8")) identifier = path.stem writes: list[tuple[str, str, Any]] = [] pending = path.with_suffix(".writes") if pending.exists(): for line in pending.read_text(encoding="utf-8").splitlines(): entry = json.loads(line) writes.append((entry["task"], entry["channel"], _load(self.serde, entry["value"]))) base = {"thread_id": options["thread_id"], "checkpoint_ns": options.get("checkpoint_ns", "")} parent = stored.get("parent") return CheckpointTuple( config={"configurable": {**base, "checkpoint_id": identifier}}, checkpoint=_load(self.serde, stored["checkpoint"]), metadata=_load(self.serde, stored["metadata"]), parent_config={"configurable": {**base, "checkpoint_id": parent}} if parent else None, pending_writes=writes, ) def list( self, config: RunnableConfig | None, *, filter: dict[str, Any] | None = None, before: RunnableConfig | None = None, limit: int | None = None, ) -> Iterator[CheckpointTuple]: if config is None: return folder = self._dir(config) paths = sorted(folder.glob("*.ckpt"), reverse=True) if folder.is_dir() else [] ceiling = get_checkpoint_id(before) if before else None count = 0 for path in paths: if ceiling and path.stem >= ceiling: continue found = self._tuple(config, path) if filter and any(found.metadata.get(k) != v for k, v in filter.items()): continue yield found count += 1 if limit is not None and count >= limit: return def put( self, config: RunnableConfig, checkpoint: Checkpoint, metadata: CheckpointMetadata, new_versions: ChannelVersions, ) -> RunnableConfig: options = config["configurable"] folder = self._dir(config) body = { "checkpoint": _dump(self.serde, checkpoint), "metadata": _dump(self.serde, metadata), "parent": options.get("checkpoint_id"), } with self._locked(folder): temporary = folder / f"{checkpoint['id']}.tmp" temporary.write_text(json.dumps(body), encoding="utf-8") temporary.rename(folder / f"{checkpoint['id']}.ckpt") return { "configurable": { "thread_id": options["thread_id"], "checkpoint_ns": options.get("checkpoint_ns", ""), "checkpoint_id": checkpoint["id"], } } def put_writes( self, config: RunnableConfig, writes: Sequence[tuple[str, Any]], task_id: str, task_path: str = "", ) -> None: folder = self._dir(config) lines = [ json.dumps({"task": task_id, "channel": channel, "value": _dump(self.serde, value)}) for channel, value in writes ] with self._locked(folder), (folder / f"{get_checkpoint_id(config)}.writes").open("a", encoding="utf-8") as out: out.write("".join(f"{line}\n" for line in lines)) async def aget_tuple(self, config: RunnableConfig) -> CheckpointTuple | None: return self.get_tuple(config) async def alist( self, config: RunnableConfig | None, *, filter: dict[str, Any] | None = None, before: RunnableConfig | None = None, limit: int | None = None, ) -> AsyncIterator[CheckpointTuple]: for found in self.list(config, filter=filter, before=before, limit=limit): yield found async def aput( self, config: RunnableConfig, checkpoint: Checkpoint, metadata: CheckpointMetadata, new_versions: ChannelVersions, ) -> RunnableConfig: return self.put(config, checkpoint, metadata, new_versions) async def aput_writes( self, config: RunnableConfig, writes: Sequence[tuple[str, Any]], task_id: str, task_path: str = "", ) -> None: self.put_writes(config, writes, task_id, task_path)