langgraph-checkpoint 1.0.0__py3-none-any.whl

langgraph/checkpoint/base/__init__.py

@@ -0,0 +1,432 @@
+from abc import ABC
+from datetime import datetime, timezone
+from typing import (
+    Any,
+    AsyncIterator,
+    Dict,
+    Iterator,
+    List,
+    Literal,
+    Mapping,
+    NamedTuple,
+    Optional,
+    Tuple,
+    TypedDict,
+    TypeVar,
+    Union,
+)
+
+from langchain_core.runnables import ConfigurableFieldSpec, RunnableConfig
+
+from langgraph.checkpoint.base.id import uuid6
+from langgraph.checkpoint.serde.base import SerializerProtocol, maybe_add_typed_methods
+from langgraph.checkpoint.serde.jsonplus import JsonPlusSerializer
+from langgraph.checkpoint.serde.types import (
+    ChannelProtocol,
+    SendProtocol,
+)
+
+V = TypeVar("V", int, float, str)
+PendingWrite = Tuple[str, str, Any]
+
+
+# Marked as total=False to allow for future expansion.
+class CheckpointMetadata(TypedDict, total=False):
+    """Metadata associated with a checkpoint."""
+
+    source: Literal["input", "loop", "update"]
+    """The source of the checkpoint.
+    - "input": The checkpoint was created from an input to invoke/stream/batch.
+    - "loop": The checkpoint was created from inside the pregel loop.
+    - "update": The checkpoint was created from a manual state update.
+    """
+    step: int
+    """The step number of the checkpoint.
+    -1 for the first "input" checkpoint.
+    0 for the first "loop" checkpoint.
+    ... for the nth checkpoint afterwards.
+    """
+    writes: dict[str, Any]
+    """The writes that were made between the previous checkpoint and this one.
+
+    Mapping from node name to writes emitted by that node.
+    """
+    score: Optional[int]
+    """The score of the checkpoint.
+
+    The score can be used to mark a checkpoint as "good".
+    """
+
+
+class TaskInfo(TypedDict):
+    status: Literal["scheduled", "success", "error"]
+
+
+class Checkpoint(TypedDict):
+    """State snapshot at a given point in time."""
+
+    v: int
+    """The version of the checkpoint format. Currently 1."""
+    id: str
+    """The ID of the checkpoint. This is both unique and monotonically
+    increasing, so can be used for sorting checkpoints from first to last."""
+    ts: str
+    """The timestamp of the checkpoint in ISO 8601 format."""
+    channel_values: dict[str, Any]
+    """The values of the channels at the time of the checkpoint.
+
+    Mapping from channel name to channel snapshot value.
+    """
+    channel_versions: dict[str, Union[str, int, float]]
+    """The versions of the channels at the time of the checkpoint.
+
+    The keys are channel names and the values are the logical time step
+    at which the channel was last updated.
+    """
+    versions_seen: dict[str, dict[str, Union[str, int, float]]]
+    """Map from node ID to map from channel name to version seen.
+
+    This keeps track of the versions of the channels that each node has seen.
+
+    Used to determine which nodes to execute next.
+    """
+    pending_sends: List[SendProtocol]
+    """List of packets sent to nodes but not yet processed.
+    Cleared by the next checkpoint."""
+    current_tasks: Dict[str, TaskInfo]
+    """Map from task ID to task info."""
+
+
+def empty_checkpoint() -> Checkpoint:
+    return Checkpoint(
+        v=1,
+        id=str(uuid6(clock_seq=-2)),
+        ts=datetime.now(timezone.utc).isoformat(),
+        channel_values={},
+        channel_versions={},
+        versions_seen={},
+        pending_sends=[],
+        current_tasks={},
+    )
+
+
+def copy_checkpoint(checkpoint: Checkpoint) -> Checkpoint:
+    return Checkpoint(
+        v=checkpoint["v"],
+        ts=checkpoint["ts"],
+        id=checkpoint["id"],
+        channel_values=checkpoint["channel_values"].copy(),
+        channel_versions=checkpoint["channel_versions"].copy(),
+        versions_seen={k: v.copy() for k, v in checkpoint["versions_seen"].items()},
+        pending_sends=checkpoint.get("pending_sends", []).copy(),
+        current_tasks=checkpoint.get("current_tasks", {}).copy(),
+    )
+
+
+def create_checkpoint(
+    checkpoint: Checkpoint,
+    channels: Optional[Mapping[str, ChannelProtocol]],
+    step: int,
+    *,
+    id: Optional[str] = None,
+) -> Checkpoint:
+    """Create a checkpoint for the given channels."""
+    ts = datetime.now(timezone.utc).isoformat()
+    if channels is None:
+        values = checkpoint["channel_values"]
+    else:
+        values: dict[str, Any] = {}
+        for k, v in channels.items():
+            try:
+                values[k] = v.checkpoint()
+            except EmptyChannelError:
+                pass
+    return Checkpoint(
+        v=1,
+        ts=ts,
+        id=id or str(uuid6(clock_seq=step)),
+        channel_values=values,
+        channel_versions=checkpoint["channel_versions"],
+        versions_seen=checkpoint["versions_seen"],
+        pending_sends=checkpoint.get("pending_sends", []),
+        current_tasks={},
+    )
+
+
+class CheckpointTuple(NamedTuple):
+    """A tuple containing a checkpoint and its associated data."""
+
+    config: RunnableConfig
+    checkpoint: Checkpoint
+    metadata: CheckpointMetadata
+    parent_config: Optional[RunnableConfig] = None
+    pending_writes: Optional[List[PendingWrite]] = None
+
+
+CheckpointThreadId = ConfigurableFieldSpec(
+    id="thread_id",
+    annotation=str,
+    name="Thread ID",
+    description=None,
+    default="",
+    is_shared=True,
+)
+
+CheckpointNS = ConfigurableFieldSpec(
+    id="checkpoint_ns",
+    annotation=str,
+    name="Checkpoint NS",
+    description='Checkpoint namespace. Denotes the path to the subgraph node the checkpoint originates from, separated by `|` character, e.g. `"child|grandchild"`. Defaults to "" (root graph).',
+    default=None,
+    is_shared=True,
+)
+
+CheckpointId = ConfigurableFieldSpec(
+    id="checkpoint_id",
+    annotation=Optional[str],
+    name="Checkpoint ID",
+    description="Pass to fetch a past checkpoint. If None, fetches the latest checkpoint.",
+    default=None,
+    is_shared=True,
+)
+
+
+class BaseCheckpointSaver(ABC):
+    """Base class for creating a graph checkpointer.
+
+    Checkpointers allow LangGraph agents to persist their state
+    within and across multiple interactions.
+
+    Attributes:
+        serde (SerializerProtocol): Serializer for encoding/decoding checkpoints.
+
+    Note:
+        When creating a custom checkpoint saver, consider implementing async
+        versions to avoid blocking the main thread.
+    """
+
+    serde: SerializerProtocol = JsonPlusSerializer()
+
+    def __init__(
+        self,
+        *,
+        serde: Optional[SerializerProtocol] = None,
+    ) -> None:
+        self.serde = maybe_add_typed_methods(serde or self.serde)
+
+    @property
+    def config_specs(self) -> list[ConfigurableFieldSpec]:
+        """Define the configuration options for the checkpoint saver.
+
+        Returns:
+            list[ConfigurableFieldSpec]: List of configuration field specs.
+        """
+        return [CheckpointThreadId, CheckpointNS, CheckpointId]
+
+    def get(self, config: RunnableConfig) -> Optional[Checkpoint]:
+        """Fetch a checkpoint using the given configuration.
+
+        Args:
+            config (RunnableConfig): Configuration specifying which checkpoint to retrieve.
+
+        Returns:
+            Optional[Checkpoint]: The requested checkpoint, or None if not found.
+        """
+        if value := self.get_tuple(config):
+            return value.checkpoint
+
+    def get_tuple(self, config: RunnableConfig) -> Optional[CheckpointTuple]:
+        """Fetch a checkpoint tuple using the given configuration.
+
+        Args:
+            config (RunnableConfig): Configuration specifying which checkpoint to retrieve.
+
+        Returns:
+            Optional[CheckpointTuple]: The requested checkpoint tuple, or None if not found.
+
+        Raises:
+            NotImplementedError: Implement this method in your custom checkpoint saver.
+        """
+        raise NotImplementedError
+
+    def list(
+        self,
+        config: Optional[RunnableConfig],
+        *,
+        filter: Optional[Dict[str, Any]] = None,
+        before: Optional[RunnableConfig] = None,
+        limit: Optional[int] = None,
+    ) -> Iterator[CheckpointTuple]:
+        """List checkpoints that match the given criteria.
+
+        Args:
+            config (Optional[RunnableConfig]): Base configuration for filtering checkpoints.
+            filter (Optional[Dict[str, Any]]): Additional filtering criteria.
+            before (Optional[RunnableConfig]): List checkpoints created before this configuration.
+            limit (Optional[int]): Maximum number of checkpoints to return.
+
+        Returns:
+            Iterator[CheckpointTuple]: Iterator of matching checkpoint tuples.
+
+        Raises:
+            NotImplementedError: Implement this method in your custom checkpoint saver.
+        """
+        raise NotImplementedError
+
+    def put(
+        self,
+        config: RunnableConfig,
+        checkpoint: Checkpoint,
+        metadata: CheckpointMetadata,
+    ) -> RunnableConfig:
+        """Store a checkpoint with its configuration and metadata.
+
+        Args:
+            config (RunnableConfig): Configuration for the checkpoint.
+            checkpoint (Checkpoint): The checkpoint to store.
+            metadata (CheckpointMetadata): Additional metadata for the checkpoint.
+
+        Returns:
+            RunnableConfig: Updated configuration after storing the checkpoint.
+
+        Raises:
+            NotImplementedError: Implement this method in your custom checkpoint saver.
+        """
+        raise NotImplementedError
+
+    def put_writes(
+        self,
+        config: RunnableConfig,
+        writes: List[Tuple[str, Any]],
+        task_id: str,
+    ) -> None:
+        """Store intermediate writes linked to a checkpoint.
+
+        Args:
+            config (RunnableConfig): Configuration of the related checkpoint.
+            writes (List[Tuple[str, Any]]): List of writes to store.
+            task_id (str): Identifier for the task creating the writes.
+
+        Raises:
+            NotImplementedError: Implement this method in your custom checkpoint saver.
+        """
+        raise NotImplementedError
+
+    async def aget(self, config: RunnableConfig) -> Optional[Checkpoint]:
+        """Asynchronously fetch a checkpoint using the given configuration.
+
+        Args:
+            config (RunnableConfig): Configuration specifying which checkpoint to retrieve.
+
+        Returns:
+            Optional[Checkpoint]: The requested checkpoint, or None if not found.
+        """
+        if value := await self.aget_tuple(config):
+            return value.checkpoint
+
+    async def aget_tuple(self, config: RunnableConfig) -> Optional[CheckpointTuple]:
+        """Asynchronously fetch a checkpoint tuple using the given configuration.
+
+        Args:
+            config (RunnableConfig): Configuration specifying which checkpoint to retrieve.
+
+        Returns:
+            Optional[CheckpointTuple]: The requested checkpoint tuple, or None if not found.
+
+        Raises:
+            NotImplementedError: Implement this method in your custom checkpoint saver.
+        """
+        raise NotImplementedError
+
+    async def alist(
+        self,
+        config: Optional[RunnableConfig],
+        *,
+        filter: Optional[Dict[str, Any]] = None,
+        before: Optional[RunnableConfig] = None,
+        limit: Optional[int] = None,
+    ) -> AsyncIterator[CheckpointTuple]:
+        """Asynchronously list checkpoints that match the given criteria.
+
+        Args:
+            config (Optional[RunnableConfig]): Base configuration for filtering checkpoints.
+            filter (Optional[Dict[str, Any]]): Additional filtering criteria for metadata.
+            before (Optional[RunnableConfig]): List checkpoints created before this configuration.
+            limit (Optional[int]): Maximum number of checkpoints to return.
+
+        Returns:
+            AsyncIterator[CheckpointTuple]: Async iterator of matching checkpoint tuples.
+
+        Raises:
+            NotImplementedError: Implement this method in your custom checkpoint saver.
+        """
+        raise NotImplementedError
+        yield
+
+    async def aput(
+        self,
+        config: RunnableConfig,
+        checkpoint: Checkpoint,
+        metadata: CheckpointMetadata,
+    ) -> RunnableConfig:
+        """Asynchronously store a checkpoint with its configuration and metadata.
+
+        Args:
+            config (RunnableConfig): Configuration for the checkpoint.
+            checkpoint (Checkpoint): The checkpoint to store.
+            metadata (CheckpointMetadata): Additional metadata for the checkpoint.
+
+        Returns:
+            RunnableConfig: Updated configuration after storing the checkpoint.
+
+        Raises:
+            NotImplementedError: Implement this method in your custom checkpoint saver.
+        """
+        raise NotImplementedError
+
+    async def aput_writes(
+        self,
+        config: RunnableConfig,
+        writes: List[Tuple[str, Any]],
+        task_id: str,
+    ) -> None:
+        """Asynchronously store intermediate writes linked to a checkpoint.
+
+        Args:
+            config (RunnableConfig): Configuration of the related checkpoint.
+            writes (List[Tuple[str, Any]]): List of writes to store.
+            task_id (str): Identifier for the task creating the writes.
+
+        Raises:
+            NotImplementedError: Implement this method in your custom checkpoint saver.
+        """
+        raise NotImplementedError
+
+    def get_next_version(self, current: Optional[V], channel: ChannelProtocol) -> V:
+        """Generate the next version ID for a channel.
+
+        Default is to use integer versions, incrementing by 1. If you override, you can use str/int/float versions,
+        as long as they are monotonically increasing.
+
+        Args:
+            current (Optional[V]): The current version identifier (int, float, or str).
+            channel (BaseChannel): The channel being versioned.
+
+        Returns:
+            V: The next version identifier, which must be increasing.
+        """
+        return current + 1 if current is not None else 1
+
+
+class EmptyChannelError(Exception):
+    """Raised when attempting to get the value of a channel that hasn't been updated
+    for the first time yet."""
+
+    pass
+
+
+def get_checkpoint_id(config: RunnableConfig) -> Optional[str]:
+    """Get checkpoint ID in a backwards-compatible manner (fallback on thread_ts)."""
+    return config["configurable"].get(
+        "checkpoint_id", config["configurable"].get("thread_ts")
+    )

langgraph/checkpoint/base/id.py

@@ -0,0 +1,108 @@
+"""Adapted from
+https://github.com/oittaa/uuid6-python/blob/main/src/uuid6/__init__.py#L95
+Bundled in to avoid install issues with uuid6 package
+"""
+
+import secrets
+import time
+import uuid
+from typing import Optional, Tuple
+
+_last_v6_timestamp = None
+
+
+class UUID(uuid.UUID):
+    r"""UUID draft version objects"""
+
+    __slots__ = ()
+
+    def __init__(
+        self,
+        hex: Optional[str] = None,
+        bytes: Optional[bytes] = None,
+        bytes_le: Optional[bytes] = None,
+        fields: Optional[Tuple[int, int, int, int, int, int]] = None,
+        int: Optional[int] = None,
+        version: Optional[int] = None,
+        *,
+        is_safe: uuid.SafeUUID = uuid.SafeUUID.unknown,
+    ) -> None:
+        r"""Create a UUID."""
+
+        if int is None or [hex, bytes, bytes_le, fields].count(None) != 4:
+            return super().__init__(
+                hex=hex,
+                bytes=bytes,
+                bytes_le=bytes_le,
+                fields=fields,
+                int=int,
+                version=version,
+                is_safe=is_safe,
+            )
+        if not 0 <= int < 1 << 128:
+            raise ValueError("int is out of range (need a 128-bit value)")
+        if version is not None:
+            if not 6 <= version <= 8:
+                raise ValueError("illegal version number")
+            # Set the variant to RFC 4122.
+            int &= ~(0xC000 << 48)
+            int |= 0x8000 << 48
+            # Set the version number.
+            int &= ~(0xF000 << 64)
+            int |= version << 76
+        super().__init__(int=int, is_safe=is_safe)
+
+    @property
+    def subsec(self) -> int:
+        return ((self.int >> 64) & 0x0FFF) << 8 | ((self.int >> 54) & 0xFF)
+
+    @property
+    def time(self) -> int:
+        if self.version == 6:
+            return (
+                (self.time_low << 28)
+                | (self.time_mid << 12)
+                | (self.time_hi_version & 0x0FFF)
+            )
+        if self.version == 7:
+            return self.int >> 80
+        if self.version == 8:
+            return (self.int >> 80) * 10**6 + _subsec_decode(self.subsec)
+        return super().time
+
+
+def _subsec_decode(value: int) -> int:
+    return -(-value * 10**6 // 2**20)
+
+
+def uuid6(node: Optional[int] = None, clock_seq: Optional[int] = None) -> UUID:
+    r"""UUID version 6 is a field-compatible version of UUIDv1, reordered for
+    improved DB locality. It is expected that UUIDv6 will primarily be
+    used in contexts where there are existing v1 UUIDs. Systems that do
+    not involve legacy UUIDv1 SHOULD consider using UUIDv7 instead.
+
+    If 'node' is not given, a random 48-bit number is chosen.
+
+    If 'clock_seq' is given, it is used as the sequence number;
+    otherwise a random 14-bit sequence number is chosen."""
+
+    global _last_v6_timestamp
+
+    nanoseconds = time.time_ns()
+    # 0x01b21dd213814000 is the number of 100-ns intervals between the
+    # UUID epoch 1582-10-15 00:00:00 and the Unix epoch 1970-01-01 00:00:00.
+    timestamp = nanoseconds // 100 + 0x01B21DD213814000
+    if _last_v6_timestamp is not None and timestamp <= _last_v6_timestamp:
+        timestamp = _last_v6_timestamp + 1
+    _last_v6_timestamp = timestamp
+    if clock_seq is None:
+        clock_seq = secrets.randbits(14)  # instead of stable storage
+    if node is None:
+        node = secrets.randbits(48)
+    time_high_and_time_mid = (timestamp >> 12) & 0xFFFFFFFFFFFF
+    time_low_and_version = timestamp & 0x0FFF
+    uuid_int = time_high_and_time_mid << 80
+    uuid_int |= time_low_and_version << 64
+    uuid_int |= (clock_seq & 0x3FFF) << 48
+    uuid_int |= node & 0xFFFFFFFFFFFF
+    return UUID(int=uuid_int, version=6)

langgraph/checkpoint/memory.py

@@ -0,0 +1,351 @@
+import asyncio
+from collections import defaultdict
+from functools import partial
+from typing import Any, AsyncIterator, Dict, Iterator, List, Optional, Tuple
+
+from langchain_core.runnables import RunnableConfig
+
+from langgraph.checkpoint.base import (
+    BaseCheckpointSaver,
+    Checkpoint,
+    CheckpointMetadata,
+    CheckpointTuple,
+    SerializerProtocol,
+    get_checkpoint_id,
+)
+
+
+class MemorySaver(BaseCheckpointSaver):
+    """An in-memory checkpoint saver.
+
+    This checkpoint saver stores checkpoints in memory using a defaultdict.
+
+    Note:
+        Since checkpoints are saved in memory, they will be lost when the program exits.
+        Only use this saver for debugging or testing purposes.
+
+    Args:
+        serde (Optional[SerializerProtocol]): The serializer to use for serializing and deserializing checkpoints. Defaults to None.
+
+    Examples:
+
+            import asyncio
+
+            from langgraph.checkpoint.memory import MemorySaver
+            from langgraph.graph import StateGraph
+
+            builder = StateGraph(int)
+            builder.add_node("add_one", lambda x: x + 1)
+            builder.set_entry_point("add_one")
+            builder.set_finish_point("add_one")
+
+            memory = MemorySaver()
+            graph = builder.compile(checkpointer=memory)
+            coro = graph.ainvoke(1, {"configurable": {"thread_id": "thread-1"}})
+            asyncio.run(coro)  # Output: 2
+    """
+
+    # thread ID ->  checkpoint NS -> checkpoint ID -> checkpoint mapping
+    storage: defaultdict[str, dict[str, dict[str, tuple[bytes, bytes, Optional[str]]]]]
+
+    def __init__(
+        self,
+        *,
+        serde: Optional[SerializerProtocol] = None,
+    ) -> None:
+        super().__init__(serde=serde)
+        self.storage = defaultdict(lambda: defaultdict(dict))
+        self.writes = defaultdict(list)
+
+    def get_tuple(self, config: RunnableConfig) -> Optional[CheckpointTuple]:
+        """Get a checkpoint tuple from the in-memory storage.
+
+        This method retrieves a checkpoint tuple from the in-memory storage based on the
+        provided config. If the config contains a "checkpoint_id" key, the checkpoint with
+        the matching thread ID and timestamp is retrieved. Otherwise, the latest checkpoint
+        for the given thread ID is retrieved.
+
+        Args:
+            config (RunnableConfig): The config to use for retrieving the checkpoint.
+
+        Returns:
+            Optional[CheckpointTuple]: The retrieved checkpoint tuple, or None if no matching checkpoint was found.
+        """
+        thread_id = config["configurable"]["thread_id"]
+        checkpoint_ns = config["configurable"].get("checkpoint_ns", "")
+        if checkpoint_id := get_checkpoint_id(config):
+            if saved := self.storage[thread_id][checkpoint_ns].get(checkpoint_id):
+                checkpoint, metadata, parent_checkpoint_id = saved
+                writes = self.writes[(thread_id, checkpoint_ns, checkpoint_id)]
+                return CheckpointTuple(
+                    config=config,
+                    checkpoint=self.serde.loads_typed(checkpoint),
+                    metadata=self.serde.loads_typed(metadata),
+                    pending_writes=[
+                        (id, c, self.serde.loads_typed(v)) for id, c, v in writes
+                    ],
+                    parent_config={
+                        "configurable": {
+                            "thread_id": thread_id,
+                            "checkpoint_ns": checkpoint_ns,
+                            "checkpoint_id": parent_checkpoint_id,
+                        }
+                    }
+                    if parent_checkpoint_id
+                    else None,
+                )
+        else:
+            if checkpoints := self.storage[thread_id][checkpoint_ns]:
+                checkpoint_id = max(checkpoints.keys())
+                checkpoint, metadata, parent_checkpoint_id = checkpoints[checkpoint_id]
+                writes = self.writes[(thread_id, checkpoint_ns, checkpoint_id)]
+                return CheckpointTuple(
+                    config={
+                        "configurable": {
+                            "thread_id": thread_id,
+                            "checkpoint_ns": checkpoint_ns,
+                            "checkpoint_id": checkpoint_id,
+                        }
+                    },
+                    checkpoint=self.serde.loads_typed(checkpoint),
+                    metadata=self.serde.loads_typed(metadata),
+                    pending_writes=[
+                        (id, c, self.serde.loads_typed(v)) for id, c, v in writes
+                    ],
+                    parent_config={
+                        "configurable": {
+                            "thread_id": thread_id,
+                            "checkpoint_ns": checkpoint_ns,
+                            "checkpoint_id": parent_checkpoint_id,
+                        }
+                    }
+                    if parent_checkpoint_id
+                    else None,
+                )
+
+    def list(
+        self,
+        config: Optional[RunnableConfig],
+        *,
+        filter: Optional[Dict[str, Any]] = None,
+        before: Optional[RunnableConfig] = None,
+        limit: Optional[int] = None,
+    ) -> Iterator[CheckpointTuple]:
+        """List checkpoints from the in-memory storage.
+
+        This method retrieves a list of checkpoint tuples from the in-memory storage based
+        on the provided criteria.
+
+        Args:
+            config (Optional[RunnableConfig]): Base configuration for filtering checkpoints.
+            filter (Optional[Dict[str, Any]]): Additional filtering criteria for metadata.
+            before (Optional[RunnableConfig]): List checkpoints created before this configuration.
+            limit (Optional[int]): Maximum number of checkpoints to return.
+
+        Yields:
+            Iterator[CheckpointTuple]: An iterator of matching checkpoint tuples.
+        """
+        thread_ids = (config["configurable"]["thread_id"],) if config else self.storage
+        checkpoint_ns = (
+            config["configurable"].get("checkpoint_ns", "") if config else ""
+        )
+        for thread_id in thread_ids:
+            for checkpoint_id, (checkpoint, metadata_b, parent_checkpoint_id) in sorted(
+                self.storage[thread_id][checkpoint_ns].items(),
+                key=lambda x: x[0],
+                reverse=True,
+            ):
+                # filter by checkpoint ID
+                if (
+                    before
+                    and (before_checkpoint_id := get_checkpoint_id(before))
+                    and checkpoint_id >= before_checkpoint_id
+                ):
+                    continue
+
+                # filter by metadata
+                metadata = self.serde.loads_typed(metadata_b)
+                if filter and not all(
+                    query_value == metadata[query_key]
+                    for query_key, query_value in filter.items()
+                ):
+                    continue
+
+                # limit search results
+                if limit is not None and limit <= 0:
+                    break
+                elif limit is not None:
+                    limit -= 1
+
+                yield CheckpointTuple(
+                    config={
+                        "configurable": {
+                            "thread_id": thread_id,
+                            "checkpoint_ns": checkpoint_ns,
+                            "checkpoint_id": checkpoint_id,
+                        }
+                    },
+                    checkpoint=self.serde.loads_typed(checkpoint),
+                    metadata=metadata,
+                    parent_config={
+                        "configurable": {
+                            "thread_id": thread_id,
+                            "checkpoint_ns": checkpoint_ns,
+                            "checkpoint_id": parent_checkpoint_id,
+                        }
+                    }
+                    if parent_checkpoint_id
+                    else None,
+                )
+
+    def put(
+        self,
+        config: RunnableConfig,
+        checkpoint: Checkpoint,
+        metadata: CheckpointMetadata,
+    ) -> RunnableConfig:
+        """Save a checkpoint to the in-memory storage.
+
+        This method saves a checkpoint to the in-memory storage. The checkpoint is associated
+        with the provided config.
+
+        Args:
+            config (RunnableConfig): The config to associate with the checkpoint.
+            checkpoint (Checkpoint): The checkpoint to save.
+            metadata (CheckpointMetadata): Additional metadata to save with the checkpoint.
+
+        Returns:
+            RunnableConfig: The updated config containing the saved checkpoint's timestamp.
+        """
+        thread_id = config["configurable"]["thread_id"]
+        checkpoint_ns = config["configurable"]["checkpoint_ns"]
+        self.storage[thread_id][checkpoint_ns].update(
+            {
+                checkpoint["id"]: (
+                    self.serde.dumps_typed(checkpoint),
+                    self.serde.dumps_typed(metadata),
+                    config["configurable"].get("checkpoint_id"),  # parent
+                )
+            }
+        )
+        return {
+            "configurable": {
+                "thread_id": thread_id,
+                "checkpoint_ns": checkpoint_ns,
+                "checkpoint_id": checkpoint["id"],
+            }
+        }
+
+    def put_writes(
+        self,
+        config: RunnableConfig,
+        writes: List[Tuple[str, Any]],
+        task_id: str,
+    ) -> RunnableConfig:
+        """Save a list of writes to the in-memory storage.
+
+        This method saves a list of writes to the in-memory storage. The writes are associated
+        with the provided config.
+
+        Args:
+            config (RunnableConfig): The config to associate with the writes.
+            writes (list[tuple[str, Any]]): The writes to save.
+            task_id (str): Identifier for the task creating the writes.
+
+        Returns:
+            RunnableConfig: The updated config containing the saved writes' timestamp.
+        """
+        thread_id = config["configurable"]["thread_id"]
+        checkpoint_ns = config["configurable"]["checkpoint_ns"]
+        checkpoint_id = config["configurable"]["checkpoint_id"]
+        key = (thread_id, checkpoint_ns, checkpoint_id)
+        self.writes[key].extend(
+            [(task_id, c, self.serde.dumps_typed(v)) for c, v in writes]
+        )
+
+    async def aget_tuple(self, config: RunnableConfig) -> Optional[CheckpointTuple]:
+        """Asynchronous version of get_tuple.
+
+        This method is an asynchronous wrapper around get_tuple that runs the synchronous
+        method in a separate thread using asyncio.
+
+        Args:
+            config (RunnableConfig): The config to use for retrieving the checkpoint.
+
+        Returns:
+            Optional[CheckpointTuple]: The retrieved checkpoint tuple, or None if no matching checkpoint was found.
+        """
+        return await asyncio.get_running_loop().run_in_executor(
+            None, self.get_tuple, config
+        )
+
+    async def alist(
+        self,
+        config: Optional[RunnableConfig],
+        *,
+        filter: Optional[Dict[str, Any]] = None,
+        before: Optional[RunnableConfig] = None,
+        limit: Optional[int] = None,
+    ) -> AsyncIterator[CheckpointTuple]:
+        """Asynchronous version of list.
+
+        This method is an asynchronous wrapper around list that runs the synchronous
+        method in a separate thread using asyncio.
+
+        Args:
+            config (RunnableConfig): The config to use for listing the checkpoints.
+
+        Yields:
+            AsyncIterator[CheckpointTuple]: An asynchronous iterator of checkpoint tuples.
+        """
+        loop = asyncio.get_running_loop()
+        iter = await loop.run_in_executor(
+            None, partial(self.list, before=before, limit=limit, filter=filter), config
+        )
+        while True:
+            # handling StopIteration exception inside coroutine won't work
+            # as expected, so using next() with default value to break the loop
+            if item := await loop.run_in_executor(None, next, iter, None):
+                yield item
+            else:
+                break
+
+    async def aput(
+        self,
+        config: RunnableConfig,
+        checkpoint: Checkpoint,
+        metadata: CheckpointMetadata,
+    ) -> RunnableConfig:
+        """Asynchronous version of put.
+
+        Args:
+            config (RunnableConfig): The config to associate with the checkpoint.
+            checkpoint (Checkpoint): The checkpoint to save.
+            metadata (CheckpointMetadata): Additional metadata to save with the checkpoint.
+
+        Returns:
+            RunnableConfig: The updated config containing the saved checkpoint's timestamp.
+        """
+        return await asyncio.get_running_loop().run_in_executor(
+            None, self.put, config, checkpoint, metadata
+        )
+
+    async def aput_writes(
+        self,
+        config: RunnableConfig,
+        writes: List[Tuple[str, Any]],
+        task_id: str,
+    ) -> RunnableConfig:
+        """Asynchronous version of put_writes.
+
+        This method is an asynchronous wrapper around put_writes that runs the synchronous
+        method in a separate thread using asyncio.
+
+        Args:
+            config (RunnableConfig): The config to associate with the writes.
+            writes (List[Tuple[str, Any]]): The writes to save, each as a (channel, value) pair.
+            task_id (str): Identifier for the task creating the writes.
+        """
+        return await asyncio.get_running_loop().run_in_executor(
+            None, self.put_writes, config, writes, task_id
+        )

langgraph/checkpoint/serde/base.py

@@ -0,0 +1,45 @@
+from typing import Any, Protocol
+
+
+class SerializerProtocol(Protocol):
+    """Protocol for serialization and deserialization of objects.
+
+    - `dumps`: Serialize an object to bytes.
+    - `dumps_typed`: Serialize an object to a tuple (type, bytes).
+    - `loads`: Deserialize an object from bytes.
+    - `loads_typed`: Deserialize an object from a tuple (type, bytes).
+
+    Valid implementations include the `pickle`, `json` and `orjson` modules.
+    """
+
+    def dumps(self, obj: Any) -> bytes:
+        ...
+
+    def dumps_typed(self, obj: Any) -> tuple[str, bytes]:
+        ...
+
+    def loads(self, data: bytes) -> Any:
+        ...
+
+    def loads_typed(self, data: tuple[str, bytes]) -> Any:
+        ...
+
+
+class SerializerCompat(SerializerProtocol):
+    def __init__(self, serde: SerializerProtocol) -> None:
+        self.serde = serde
+
+    def dumps_typed(self, obj: Any) -> tuple[str, bytes]:
+        return type(obj).__name__, self.serde.dumps(obj)
+
+    def loads_typed(self, data: tuple[str, bytes]) -> Any:
+        return self.serde.loads(data[1])
+
+
+def maybe_add_typed_methods(serde: SerializerProtocol) -> SerializerProtocol:
+    """Wrap serde old serde implementations in a class with loads_typed and dumps_typed for backwards compatibility."""
+
+    if not hasattr(serde, "loads_typed") or not hasattr(serde, "dumps_typed"):
+        return SerializerCompat(serde)
+
+    return serde

langgraph/checkpoint/serde/jsonplus.py

@@ -0,0 +1,112 @@
+import dataclasses
+import importlib
+import json
+from datetime import datetime, timedelta, timezone
+from enum import Enum
+from typing import Any, Optional
+from uuid import UUID
+
+from langchain_core.load.load import Reviver
+from langchain_core.load.serializable import Serializable
+
+from langgraph.checkpoint.serde.base import SerializerProtocol
+from langgraph.checkpoint.serde.types import SendProtocol
+
+LC_REVIVER = Reviver()
+
+
+class JsonPlusSerializer(SerializerProtocol):
+    def _encode_constructor_args(
+        self,
+        constructor: type[Any],
+        *,
+        method: Optional[str] = None,
+        args: Optional[list[Any]] = None,
+        kwargs: Optional[dict[str, Any]] = None,
+    ):
+        return {
+            "lc": 2,
+            "type": "constructor",
+            "id": [*constructor.__module__.split("."), constructor.__name__],
+            "method": method,
+            "args": args if args is not None else [],
+            "kwargs": kwargs if kwargs is not None else {},
+        }
+
+    def _default(self, obj):
+        if isinstance(obj, Serializable):
+            return obj.to_json()
+        elif hasattr(obj, "model_dump") and callable(obj.model_dump):
+            return self._encode_constructor_args(obj.__class__, kwargs=obj.model_dump())
+        elif hasattr(obj, "dict") and callable(obj.dict):
+            return self._encode_constructor_args(obj.__class__, kwargs=obj.dict())
+        elif isinstance(obj, UUID):
+            return self._encode_constructor_args(UUID, args=[obj.hex])
+        elif isinstance(obj, (set, frozenset)):
+            return self._encode_constructor_args(type(obj), args=[list(obj)])
+        elif isinstance(obj, datetime):
+            return self._encode_constructor_args(
+                datetime, method="fromisoformat", args=[obj.isoformat()]
+            )
+        elif isinstance(obj, timezone):
+            return self._encode_constructor_args(timezone, args=obj.__getinitargs__())
+        elif isinstance(obj, timedelta):
+            return self._encode_constructor_args(
+                timedelta, args=[obj.days, obj.seconds, obj.microseconds]
+            )
+        elif dataclasses.is_dataclass(obj):
+            return self._encode_constructor_args(
+                obj.__class__,
+                kwargs={
+                    field.name: getattr(obj, field.name)
+                    for field in dataclasses.fields(obj)
+                },
+            )
+        elif isinstance(obj, Enum):
+            return self._encode_constructor_args(obj.__class__, args=[obj.value])
+        elif isinstance(obj, SendProtocol):
+            return self._encode_constructor_args(
+                obj.__class__, kwargs={"node": obj.node, "arg": obj.arg}
+            )
+        else:
+            raise TypeError(
+                f"Object of type {obj.__class__.__name__} is not JSON serializable"
+            )
+
+    def _reviver(self, value: dict[str, Any]) -> Any:
+        if (
+            value.get("lc", None) == 2
+            and value.get("type", None) == "constructor"
+            and value.get("id", None) is not None
+        ):
+            # Get module and class name
+            [*module, name] = value["id"]
+            # Import module
+            mod = importlib.import_module(".".join(module))
+            # Import class
+            cls = getattr(mod, name)
+            # Instantiate class
+            if value["method"] is not None:
+                method = getattr(cls, value["method"])
+                return method(*value["args"], **value["kwargs"])
+            else:
+                return cls(*value["args"], **value["kwargs"])
+
+        return LC_REVIVER(value)
+
+    def dumps(self, obj: Any) -> bytes:
+        return json.dumps(obj, default=self._default, ensure_ascii=False).encode(
+            "utf-8", "ignore"
+        )
+
+    def dumps_typed(self, obj: Any) -> tuple[str, bytes]:
+        return "json", self.dumps(obj)
+
+    def loads(self, data: bytes) -> Any:
+        return json.loads(data, object_hook=self._reviver)
+
+    def loads_typed(self, data: tuple[str, bytes]) -> Any:
+        type_, data_ = data
+        if type_ != "json":
+            raise ValueError("JsonPlusSerializer can only deserialize `json` data")
+        return self.loads(data_)

langgraph/checkpoint/serde/types.py

@@ -0,0 +1,66 @@
+from typing import (
+    Any,
+    AsyncGenerator,
+    Generator,
+    Optional,
+    Protocol,
+    Sequence,
+    TypeVar,
+    runtime_checkable,
+)
+
+from langchain_core.runnables import RunnableConfig
+from typing_extensions import Self
+
+Value = TypeVar("Value")
+Update = TypeVar("Update")
+C = TypeVar("C")
+
+
+class ChannelProtocol(Protocol[Value, Update, C]):
+    # Mirrors langgraph.channels.base.BaseChannel
+    @property
+    def ValueType(self) -> Any:
+        ...
+
+    @property
+    def UpdateType(self) -> Any:
+        ...
+
+    def checkpoint(self) -> Optional[C]:
+        ...
+
+    def from_checkpoint(
+        self, checkpoint: Optional[C], config: RunnableConfig
+    ) -> Generator[Self, None, None]:
+        ...
+
+    async def afrom_checkpoint(
+        self, checkpoint: Optional[C], config: RunnableConfig
+    ) -> AsyncGenerator[Self, None]:
+        ...
+
+    def update(self, values: Sequence[Update]) -> bool:
+        ...
+
+    def get(self) -> Value:
+        ...
+
+    def consume(self) -> bool:
+        ...
+
+
+@runtime_checkable
+class SendProtocol(Protocol):
+    # Mirrors langgraph.constants.Send
+    node: str
+    arg: Any
+
+    def __hash__(self) -> int:
+        ...
+
+    def __repr__(self) -> str:
+        ...
+
+    def __eq__(self, value: object) -> bool:
+        ...

langgraph_checkpoint-1.0.0.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 LangChain, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

langgraph_checkpoint-1.0.0.dist-info/METADATA

@@ -0,0 +1,103 @@
+Metadata-Version: 2.1
+Name: langgraph-checkpoint
+Version: 1.0.0
+Summary: Library with base interfaces for LangGraph checkpoint savers.
+Home-page: https://www.github.com/langchain-ai/langgraph
+License: MIT
+Requires-Python: >=3.9.0,<4.0.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: langchain-core (>=0.2.22,<0.3)
+Project-URL: Repository, https://www.github.com/langchain-ai/langgraph
+Description-Content-Type: text/markdown
+
+# LangGraph Checkpoint
+
+This library defines the base interface for LangGraph checkpointers. Checkpointers provide persistence layer for LangGraph. They allow you to interact with and manage the graph's state. When you use a graph with a checkpointer, the checkpointer saves a _checkpoint_ of the graph state at every superstep, enabling several powerful capabilities like human-in-the-loop, "memory" between interactions and more.
+
+## Key concepts
+
+### Checkpoint
+
+Checkpoint is a snapshot of the graph state at a given point in time. Checkpoint tuple refers to an object containing checkpoint and the associated config, metadata and pending writes.
+
+### Thread
+
+Threads enable the checkpointing of multiple different runs, making them essential for multi-tenant chat applications and other scenarios where maintaining separate states is necessary. A thread is a unique ID assigned to a series of checkpoints saved by a checkpointer. When using a checkpointer, you must specify a `thread_id` and optionally `checkpoint_id` when running the graph.
+
+- `thread_id` is simply the ID of a thread. This is always required
+- `checkpoint_id` can optionally be passed. This identifier refers to a specific checkpoint within a thread. This can be used to kick of a run of a graph from some point halfway through a thread.
+
+You must pass these when invoking the graph as part of the configurable part of the config, e.g.
+
+```python
+{"configurable": {"thread_id": "1"}}  # valid config
+{"configurable": {"thread_id": "1", "checkpoint_id": "0c62ca34-ac19-445d-bbb0-5b4984975b2a"}}  # also valid config
+```
+
+### Serde
+
+`langgraph_checkpoint` also defines protocol for serialization/deserialization (serde) and provides an default implementation (`langgraph.checkpoint.serde.jsonplus.JsonPlusSerializer`) that handles a wide variety of types, including LangChain and LangGraph primitives, datetimes, enums and more.
+
+### Pending writes
+
+When a graph node fails mid-execution at a given superstep, LangGraph stores pending checkpoint writes from any other nodes that completed successfully at that superstep, so that whenever we resume graph execution from that superstep we don't re-run the successful nodes.
+
+## Interface
+
+Each checkpointer should conform to `langgraph.checkpoint.base.BaseCheckpointSaver` interface and must implement the following methods:
+
+- `.put` - Store a checkpoint with its configuration and metadata.
+- `.put_writes` - Store intermediate writes linked to a checkpoint (i.e. pending writes).
+- `.get_tuple` - Fetch a checkpoint tuple using for a given configuration (`thread_id` and `thread_ts`).
+- `.list` - List checkpoints that match a given configuration and filter criteria.
+
+If the checkpointer will be used with asynchronous graph execution (i.e. executing the graph via `.ainvoke`, `.astream`, `.abatch`), checkpointer must implement asynchronous versions of the above methods (`.aput`, `.aput_writes`, `.aget_tuple`, `.alist`).
+
+## Usage
+
+```python
+from langgraph.checkpoint.memory import MemorySaver
+
+checkpointer = MemorySaver()
+checkpoint = {
+  "v": 1,
+  "ts": "2024-07-31T20:14:19.804150+00:00",
+  "id": "1ef4f797-8335-6428-8001-8a1503f9b875",
+  "channel_values": {
+    "my_key": "meow",
+    "node": "node"
+  },
+  "channel_versions": {
+    "__start__": 2,
+    "my_key": 3,
+    "start:node": 3,
+    "node": 3
+  },
+  "versions_seen": {
+    "__input__": {},
+    "__start__": {
+      "__start__": 1
+    },
+    "node": {
+      "start:node": 2
+    }
+  },
+  "pending_sends": [],
+  "current_tasks": {}
+}
+
+# store checkpoint
+checkpointer.put(thread_config, checkpoint, {})
+
+# load checkpoint
+checkpointer.get(thread_config)
+
+# list checkpoints
+list(checkpointer.list(thread_config))
+```
+

langgraph_checkpoint-1.0.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+langgraph/checkpoint/base/__init__.py,sha256=BUx44KPtMETXa80VToEyF4p72IEUGUDB-QO-fIK91ko,14301
+langgraph/checkpoint/base/id.py,sha256=LpzsCxAwjOAVK3tTQqnuV2f7NXV2V7z3HuIe1SDHqBU,3667
+langgraph/checkpoint/memory.py,sha256=5onxgUIKJtaKJodSPoOcoeYc85BW2tKmM2pZTEQ0BS4,13696
+langgraph/checkpoint/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+langgraph/checkpoint/serde/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+langgraph/checkpoint/serde/base.py,sha256=Iow-xSaQppHUlE2Wffn3KGWhkYBthcnVIo1WtO6Rwfk,1392
+langgraph/checkpoint/serde/jsonplus.py,sha256=0bvmxTbQKIghi49eccTVca4MNcLa3Q52vxgYkw8YgFA,4228
+langgraph/checkpoint/serde/types.py,sha256=zji7QcYQCzmj1NnU4aC_zdFQJ-skYkENPK-i9KjMEbg,1277
+langgraph_checkpoint-1.0.0.dist-info/LICENSE,sha256=2btS8uNUDWD_UNjw9ba6ZJt_00aUjEw9CGyK-xIHY8c,1072
+langgraph_checkpoint-1.0.0.dist-info/METADATA,sha256=OM6wQ-AQceYHsqRlkXWzCh9ctgeUk_cLgJe6X5D1gLM,4401
+langgraph_checkpoint-1.0.0.dist-info/WHEEL,sha256=FMvqSimYX_P7y0a7UY-_Mc83r5zkBZsCYPm7Lr0Bsq4,88
+langgraph_checkpoint-1.0.0.dist-info/RECORD,,

langgraph_checkpoint-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 1.8.1
+Root-Is-Purelib: true
+Tag: py3-none-any