langgraph-checkpoint 1.0.0__tar.gz

langgraph_checkpoint-1.0.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,85 @@
+# 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/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")
+    )