langgraph-checkpoint-objectstorage 0.1.7__py3-none-any.whl

langgraph_checkpoint_objectstorage/__init__.py

@@ -0,0 +1,5 @@
+"""LangGraph checkpoint saver backed by local filesystem, GCS, or S3."""
+
+from langgraph_checkpoint_objectstorage.saver import ObjectStorageSaver
+
+__all__ = ["ObjectStorageSaver"]

langgraph_checkpoint_objectstorage/envelope.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+from typing import Any
+
+import ormsgpack
+from langgraph.checkpoint.base import Checkpoint, CheckpointMetadata
+from langgraph.checkpoint.serde.jsonplus import JsonPlusSerializer
+
+_serde = JsonPlusSerializer()
+
+
+def pack_checkpoint(
+    checkpoint: Checkpoint,
+    metadata: CheckpointMetadata,
+    parent_checkpoint_id: str | None,
+) -> bytes:
+    ck_type, ck_bytes = _serde.dumps_typed(checkpoint)
+    md_type, md_bytes = _serde.dumps_typed(metadata)
+    return ormsgpack.packb(
+        {
+            "checkpoint": [ck_type, ck_bytes],
+            "metadata": [md_type, md_bytes],
+            "parent_checkpoint_id": parent_checkpoint_id,
+        }
+    )
+
+
+def unpack_checkpoint(
+    data: bytes,
+) -> tuple[Checkpoint, CheckpointMetadata, str | None]:
+    obj = ormsgpack.unpackb(data)
+    checkpoint = _serde.loads_typed(tuple(obj["checkpoint"]))
+    metadata = _serde.loads_typed(tuple(obj["metadata"]))
+    return checkpoint, metadata, obj["parent_checkpoint_id"]
+
+
+def pack_write(task_id: str, idx: int, channel: str, value: Any) -> bytes:
+    v_type, v_bytes = _serde.dumps_typed(value)
+    return ormsgpack.packb(
+        {
+            "task_id": task_id,
+            "idx": idx,
+            "channel": channel,
+            "type": v_type,
+            "value": v_bytes,
+        }
+    )
+
+
+def unpack_write(data: bytes) -> tuple[str, int, str, Any]:
+    obj = ormsgpack.unpackb(data)
+    value = _serde.loads_typed((obj["type"], obj["value"]))
+    return obj["task_id"], obj["idx"], obj["channel"], value

langgraph_checkpoint_objectstorage/keys.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+
+def _thread_ns_root(root: str, thread_id: str, checkpoint_ns: str) -> str:
+    parts = [root, thread_id]
+    if checkpoint_ns:
+        parts.append(checkpoint_ns)
+    return "/".join(parts)
+
+
+def checkpoints_prefix(root: str, thread_id: str, checkpoint_ns: str) -> str:
+    return f"{_thread_ns_root(root, thread_id, checkpoint_ns)}/checkpoints/"
+
+
+def checkpoint_key(
+    root: str, thread_id: str, checkpoint_ns: str, checkpoint_id: str
+) -> str:
+    return (
+        f"{checkpoints_prefix(root, thread_id, checkpoint_ns)}{checkpoint_id}.msgpack"
+    )
+
+
+def checkpoint_id_from_key(key: str) -> str:
+    filename = key.rsplit("/", 1)[-1]
+    if not filename.endswith(".msgpack"):
+        raise ValueError(f"not a checkpoint key: {key!r}")
+    return filename[: -len(".msgpack")]
+
+
+def writes_prefix(
+    root: str, thread_id: str, checkpoint_ns: str, checkpoint_id: str
+) -> str:
+    return f"{_thread_ns_root(root, thread_id, checkpoint_ns)}/writes/{checkpoint_id}/"
+
+
+def write_key(
+    root: str,
+    thread_id: str,
+    checkpoint_ns: str,
+    checkpoint_id: str,
+    task_id: str,
+    idx: int,
+) -> str:
+    prefix = writes_prefix(root, thread_id, checkpoint_ns, checkpoint_id)
+    return f"{prefix}{task_id}/{idx}.msgpack"
+
+
+def thread_prefix(root: str, thread_id: str) -> str:
+    return f"{root}/{thread_id}/"

langgraph_checkpoint_objectstorage/saver.py

@@ -0,0 +1,478 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+from collections.abc import AsyncIterator, Iterator, Mapping, Sequence
+from typing import Any
+
+import fsspec
+from fsspec import AbstractFileSystem
+from fsspec.asyn import AsyncFileSystem, sync as fsspec_sync
+from langchain_core.runnables import RunnableConfig
+from langgraph.checkpoint.base import (
+    BaseCheckpointSaver,
+    Checkpoint,
+    CheckpointMetadata,
+    CheckpointTuple,
+    ChannelVersions,
+    WRITES_IDX_MAP,
+    get_checkpoint_metadata,
+)
+from typeguard import typechecked
+
+from langgraph_checkpoint_objectstorage import envelope, keys
+
+logger = logging.getLogger("langgraph_checkpoint_objectstorage")
+
+_LOG_LEVEL_ENV = "LANGGRAPH_CHECKPOINT_OBJECTSTORAGE_LOG_LEVEL"
+
+
+def _thread_ns(config: RunnableConfig) -> tuple[str, str]:
+    configurable = config["configurable"]
+    return configurable["thread_id"], configurable.get("checkpoint_ns", "")
+
+
+def _cfg(
+    thread_id: str, checkpoint_ns: str, checkpoint_id: str | None
+) -> RunnableConfig:
+    return {
+        "configurable": {
+            "thread_id": thread_id,
+            "checkpoint_ns": checkpoint_ns,
+            "checkpoint_id": checkpoint_id,
+        }
+    }
+
+
+class ObjectStorageSaver(BaseCheckpointSaver):
+    """LangGraph checkpoint saver backed by local filesystem, GCS, or S3.
+
+    One class for all three backends -- which one is used is decided by
+    the fsspec filesystem passed in (or resolved from a URI via
+    `from_conn_string`), never by subclassing. Each checkpoint and each
+    pending write is stored as its own object under `root`, keyed by
+    thread_id/checkpoint_ns so unrelated threads never collide and writes
+    never require a read-modify-write on an existing key.
+
+    Example:
+        >>> saver = ObjectStorageSaver.from_conn_string("file:///tmp/checkpoints")
+        >>> graph = builder.compile(checkpointer=saver)
+    """
+
+    @typechecked
+    def __init__(self, fs: AbstractFileSystem, root: str) -> None:
+        """Wrap an existing fsspec filesystem as a checkpoint store.
+
+        Args:
+            fs: Any fsspec `AbstractFileSystem` instance (`LocalFileSystem`,
+                `S3FileSystem`, `GCSFileSystem`, ...). Async-native
+                filesystems (`s3fs`, `gcsfs`) get true async I/O; others
+                run through a thread pool.
+            root: Root prefix under which every checkpoint and write is
+                stored -- a directory path for local filesystems, or a
+                "bucket/prefix" path for object storage.
+        """
+        super().__init__()
+        self.fs = fs
+        self.root = root.rstrip("/")
+        self._is_async_native = isinstance(fs, AsyncFileSystem)
+        level_name = os.environ.get(_LOG_LEVEL_ENV)
+        if level_name:
+            logger.setLevel(level_name.upper())
+
+    @classmethod
+    @typechecked
+    def from_conn_string(
+        cls, conn_string: str, **storage_options: Any
+    ) -> "ObjectStorageSaver":
+        """Build a saver from an fsspec connection string.
+
+        Args:
+            conn_string: An fsspec URI, e.g. `"file:///path"`,
+                `"s3://bucket/prefix"`, or `"gcs://bucket/prefix"`.
+            **storage_options: Forwarded to the underlying fsspec
+                filesystem constructor -- useful for explicit credentials
+                or a custom S3-compatible endpoint (MinIO, etc.).
+
+        Returns:
+            A new `ObjectStorageSaver` backed by the resolved filesystem.
+        """
+        storage_options.setdefault("skip_instance_cache", True)
+        fs, path = fsspec.core.url_to_fs(conn_string, **storage_options)
+        return cls(fs, path)
+
+    def _run_sync(self, func, *args, **kwargs):
+        if self._is_async_native:
+            return fsspec_sync(self.fs.loop, func, *args, **kwargs)
+        return asyncio.run(func(*args, **kwargs))
+
+    async def _cat(self, key: str) -> bytes:
+        try:
+            if self._is_async_native:
+                data = await self.fs._cat_file(key)
+            else:
+                data = await asyncio.to_thread(self.fs.cat_file, key)
+        except FileNotFoundError:
+            logger.debug("cat key=%s -> not found", key)
+            raise
+        logger.debug("cat key=%s -> %d bytes", key, len(data))
+        return data
+
+    async def _pipe(self, key: str, data: bytes) -> None:
+        parent = key.rsplit("/", 1)[0]
+        if self._is_async_native:
+            await self.fs._makedirs(parent, exist_ok=True)
+            await self.fs._pipe_file(key, data)
+        else:
+            await asyncio.to_thread(self.fs.makedirs, parent, exist_ok=True)
+            await asyncio.to_thread(self.fs.pipe_file, key, data)
+        logger.debug("pipe key=%s <- %d bytes", key, len(data))
+
+    async def _find(self, prefix: str) -> list[str]:
+        try:
+            if self._is_async_native:
+                found = await self.fs._find(prefix)
+            else:
+                found = await asyncio.to_thread(self.fs.find, prefix)
+        except FileNotFoundError:
+            logger.debug("find prefix=%s -> not found", prefix)
+            raise
+        logger.debug("find prefix=%s -> %d keys", prefix, len(found))
+        return found
+
+    async def _exists(self, key: str) -> bool:
+        if self._is_async_native:
+            result = await self.fs._exists(key)
+        else:
+            result = await asyncio.to_thread(self.fs.exists, key)
+        logger.debug("exists key=%s -> %s", key, result)
+        return result
+
+    async def _rm(self, prefix: str) -> None:
+        try:
+            if self._is_async_native:
+                await self.fs._rm(prefix, recursive=True)
+            else:
+                await asyncio.to_thread(self.fs.rm, prefix, recursive=True)
+        except FileNotFoundError:
+            logger.debug("rm prefix=%s -> not found", prefix)
+            raise
+        logger.debug("rm prefix=%s -> removed", prefix)
+
+    async def _read_pending_writes(
+        self, thread_id: str, checkpoint_ns: str, checkpoint_id: str
+    ) -> list[tuple[str, str, Any]]:
+        prefix = keys.writes_prefix(self.root, thread_id, checkpoint_ns, checkpoint_id)
+        try:
+            write_keys = await self._find(prefix)
+        except FileNotFoundError:
+            return []
+        entries = []
+        for key in write_keys:
+            data = await self._cat(key)
+            entries.append(envelope.unpack_write(data))
+        entries.sort(key=lambda e: (e[0], e[1]))
+        return [(task_id, channel, value) for task_id, idx, channel, value in entries]
+
+    async def _put(
+        self,
+        config: RunnableConfig,
+        checkpoint: Checkpoint,
+        metadata: CheckpointMetadata,
+        new_versions: ChannelVersions,
+    ) -> RunnableConfig:
+        thread_id, checkpoint_ns = _thread_ns(config)
+        checkpoint_id = checkpoint["id"]
+        parent_checkpoint_id = config["configurable"].get("checkpoint_id")
+        full_metadata = get_checkpoint_metadata(config, metadata)
+        key = keys.checkpoint_key(self.root, thread_id, checkpoint_ns, checkpoint_id)
+        data = envelope.pack_checkpoint(checkpoint, full_metadata, parent_checkpoint_id)
+        await self._pipe(key, data)
+        return _cfg(thread_id, checkpoint_ns, checkpoint_id)
+
+    async def _get_tuple(self, config: RunnableConfig) -> CheckpointTuple | None:
+        thread_id, checkpoint_ns = _thread_ns(config)
+        checkpoint_id = config["configurable"].get("checkpoint_id")
+        if checkpoint_id is None:
+            logger.debug(
+                "get_tuple thread=%s ns=%s -> no checkpoint_id, resolving latest",
+                thread_id,
+                checkpoint_ns,
+            )
+            prefix = keys.checkpoints_prefix(self.root, thread_id, checkpoint_ns)
+            try:
+                candidates = await self._find(prefix)
+            except FileNotFoundError:
+                return None
+            if not candidates:
+                return None
+            key = max(candidates)
+            checkpoint_id = keys.checkpoint_id_from_key(key)
+        else:
+            key = keys.checkpoint_key(
+                self.root, thread_id, checkpoint_ns, checkpoint_id
+            )
+        try:
+            data = await self._cat(key)
+        except FileNotFoundError:
+            return None
+        checkpoint, metadata, parent_checkpoint_id = envelope.unpack_checkpoint(data)
+        parent_config = (
+            _cfg(thread_id, checkpoint_ns, parent_checkpoint_id)
+            if parent_checkpoint_id
+            else None
+        )
+        pending_writes = await self._read_pending_writes(
+            thread_id, checkpoint_ns, checkpoint_id
+        )
+        return CheckpointTuple(
+            config=_cfg(thread_id, checkpoint_ns, checkpoint_id),
+            checkpoint=checkpoint,
+            metadata=metadata,
+            parent_config=parent_config,
+            pending_writes=pending_writes,
+        )
+
+    async def _put_writes(
+        self,
+        config: RunnableConfig,
+        writes: Sequence[tuple[str, Any]],
+        task_id: str,
+        task_path: str = "",
+    ) -> None:
+        thread_id, checkpoint_ns = _thread_ns(config)
+        checkpoint_id = config["configurable"]["checkpoint_id"]
+        overwrite = all(channel in WRITES_IDX_MAP for channel, _ in writes)
+        for idx, (channel, value) in enumerate(writes):
+            actual_idx = WRITES_IDX_MAP.get(channel, idx)
+            key = keys.write_key(
+                self.root, thread_id, checkpoint_ns, checkpoint_id, task_id, actual_idx
+            )
+            if not overwrite and await self._exists(key):
+                logger.debug(
+                    "put_writes task=%s channel=%s idx=%s -> skipped, write already exists",
+                    task_id,
+                    channel,
+                    actual_idx,
+                )
+                continue
+            data = envelope.pack_write(task_id, actual_idx, channel, value)
+            await self._pipe(key, data)
+
+    async def _list(
+        self,
+        config: RunnableConfig | None,
+        *,
+        filter: dict[str, Any] | None = None,
+        before: RunnableConfig | None = None,
+        limit: int | None = None,
+    ):
+        thread_id, checkpoint_ns = _thread_ns(config)
+        prefix = keys.checkpoints_prefix(self.root, thread_id, checkpoint_ns)
+        try:
+            candidate_keys = sorted(await self._find(prefix), reverse=True)
+        except FileNotFoundError:
+            return
+        before_id = before["configurable"]["checkpoint_id"] if before else None
+        count = 0
+        for key in candidate_keys:
+            checkpoint_id = keys.checkpoint_id_from_key(key)
+            if before_id is not None and checkpoint_id >= before_id:
+                continue
+            data = await self._cat(key)
+            checkpoint, metadata, parent_checkpoint_id = envelope.unpack_checkpoint(
+                data
+            )
+            if filter and not all(metadata.get(k) == v for k, v in filter.items()):
+                continue
+            parent_config = (
+                _cfg(thread_id, checkpoint_ns, parent_checkpoint_id)
+                if parent_checkpoint_id
+                else None
+            )
+            pending_writes = await self._read_pending_writes(
+                thread_id, checkpoint_ns, checkpoint_id
+            )
+            yield CheckpointTuple(
+                config=_cfg(thread_id, checkpoint_ns, checkpoint_id),
+                checkpoint=checkpoint,
+                metadata=metadata,
+                parent_config=parent_config,
+                pending_writes=pending_writes,
+            )
+            count += 1
+            if limit is not None and count >= limit:
+                return
+
+    async def _delete_thread(self, thread_id: str) -> None:
+        prefix = keys.thread_prefix(self.root, thread_id)
+        try:
+            await self._rm(prefix)
+        except FileNotFoundError:
+            pass
+
+    async def aget_tuple(self, config: RunnableConfig) -> CheckpointTuple | None:
+        """Async variant of `get_tuple`. See `get_tuple` for details."""
+        return await 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]:
+        """Async variant of `list`. See `list` for details."""
+        async for tup in self._list(config, filter=filter, before=before, limit=limit):
+            yield tup
+
+    @typechecked
+    async def aput(
+        self,
+        config: Mapping[str, Any],
+        checkpoint: Mapping[str, Any],
+        metadata: Mapping[str, Any],
+        new_versions: ChannelVersions,
+    ) -> RunnableConfig:
+        """Async variant of `put`. See `put` for details."""
+        return await self._put(config, checkpoint, metadata, new_versions)
+
+    @typechecked
+    async def aput_writes(
+        self,
+        config: Mapping[str, Any],
+        writes: Sequence[tuple[str, Any]],
+        task_id: str,
+        task_path: str = "",
+    ) -> None:
+        """Async variant of `put_writes`. See `put_writes` for details."""
+        await self._put_writes(config, writes, task_id, task_path)
+
+    @typechecked
+    async def adelete_thread(self, thread_id: str) -> None:
+        """Async variant of `delete_thread`. See `delete_thread` for details."""
+        await self._delete_thread(thread_id)
+
+    def get_tuple(self, config: RunnableConfig) -> CheckpointTuple | None:
+        """Fetch a checkpoint tuple for the given configuration.
+
+        If `config["configurable"]` has no `"checkpoint_id"`, returns the
+        latest checkpoint in that thread/namespace.
+
+        Args:
+            config: Must contain `configurable.thread_id`. Optionally
+                `configurable.checkpoint_ns` (default `""`) and
+                `configurable.checkpoint_id` for an exact checkpoint
+                rather than the latest.
+
+        Returns:
+            The matching `CheckpointTuple`, or `None` if no checkpoint
+            exists for that thread/namespace/id -- never raises for
+            "not found".
+        """
+        return self._run_sync(self._get_tuple, config)
+
+    def list(
+        self,
+        config: RunnableConfig | None,
+        *,
+        filter: dict[str, Any] | None = None,
+        before: RunnableConfig | None = None,
+        limit: int | None = None,
+    ) -> Iterator[CheckpointTuple]:
+        """List checkpoints for a thread/namespace, newest first.
+
+        Args:
+            config: Must contain `configurable.thread_id` and, optionally,
+                `configurable.checkpoint_ns` (default `""`).
+            filter: Metadata key/value pairs a checkpoint must match
+                (applied client-side -- see the README's Known
+                limitations section).
+            before: Only return checkpoints older than
+                `before["configurable"]["checkpoint_id"]`.
+            limit: Maximum number of checkpoints to return.
+
+        Returns:
+            An iterator of matching `CheckpointTuple`s, newest first. This
+            sync version collects all results eagerly before yielding the
+            first one (it wraps the async implementation via
+            `asyncio.run`, which can't stream lazily) -- use `alist` from
+            async code for true streaming.
+        """
+
+        async def _collect() -> list[CheckpointTuple]:
+            return [
+                t
+                async for t in self._list(
+                    config, filter=filter, before=before, limit=limit
+                )
+            ]
+
+        yield from self._run_sync(_collect)
+
+    @typechecked
+    def put(
+        self,
+        config: Mapping[str, Any],
+        checkpoint: Mapping[str, Any],
+        metadata: Mapping[str, Any],
+        new_versions: ChannelVersions,
+    ) -> RunnableConfig:
+        """Store a checkpoint as its own object.
+
+        Args:
+            config: Must contain `configurable.thread_id`. If
+                `configurable.checkpoint_id` is set, the new checkpoint's
+                parent is set to that id; otherwise it has no parent.
+            checkpoint: The checkpoint to store, as produced by LangGraph.
+                Stored opaquely (see the README's Runtime type checking
+                section) -- never hand-extracted field by field.
+            metadata: Metadata to store alongside the checkpoint.
+            new_versions: Unused by this saver -- accepted for
+                `BaseCheckpointSaver` contract compatibility.
+
+        Returns:
+            The config to use to fetch this exact checkpoint later
+            (`configurable.thread_id`/`checkpoint_ns`/`checkpoint_id`).
+        """
+        return self._run_sync(self._put, config, checkpoint, metadata, new_versions)
+
+    @typechecked
+    def put_writes(
+        self,
+        config: Mapping[str, Any],
+        writes: Sequence[tuple[str, Any]],
+        task_id: str,
+        task_path: str = "",
+    ) -> None:
+        """Store pending writes linked to a checkpoint.
+
+        Regular channels use "first write wins" -- a duplicate
+        `(task_id, idx)` is silently ignored, so a retried task can't
+        clobber a write another task already committed. The control
+        channels (`ERROR`, `SCHEDULED`, `INTERRUPT`, `RESUME`) always
+        overwrite instead, since they must reflect the latest state.
+
+        Args:
+            config: Must contain `configurable.thread_id` and
+                `configurable.checkpoint_id` -- the checkpoint these
+                writes are pending against.
+            writes: `(channel, value)` pairs to store.
+            task_id: Identifier for the task that produced these writes.
+            task_path: Unused by this saver -- accepted for
+                `BaseCheckpointSaver` contract compatibility.
+        """
+        self._run_sync(self._put_writes, config, writes, task_id, task_path)
+
+    @typechecked
+    def delete_thread(self, thread_id: str) -> None:
+        """Delete every checkpoint and write for a thread, across all namespaces.
+
+        A no-op if the thread doesn't exist.
+
+        Args:
+            thread_id: The thread to delete.
+        """
+        self._run_sync(self._delete_thread, thread_id)

langgraph_checkpoint_objectstorage-0.1.7.dist-info/METADATA

@@ -0,0 +1,360 @@
+Metadata-Version: 2.5
+Name: langgraph-checkpoint-objectstorage
+Version: 0.1.7
+Summary: LangGraph checkpoint saver backed by local filesystem, GCS, or S3 via fsspec
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: fsspec>=2024.10.0
+Requires-Dist: langchain-core>=0.2.38
+Requires-Dist: langgraph-checkpoint<5,>=4.0
+Requires-Dist: ormsgpack>=1.12.0
+Requires-Dist: typeguard>=4.0
+Provides-Extra: gcs
+Requires-Dist: gcsfs>=2024.10.0; extra == 'gcs'
+Provides-Extra: s3
+Requires-Dist: s3fs>=2024.10.0; extra == 's3'
+Description-Content-Type: text/markdown
+
+# langgraph-checkpoint-objectstorage
+
+[![CI](https://github.com/sergiommarcial/langgraph-objectstorage-checkpoint/actions/workflows/ci.yml/badge.svg)](https://github.com/sergiommarcial/langgraph-objectstorage-checkpoint/actions/workflows/ci.yml)
+
+A [LangGraph](https://github.com/langchain-ai/langgraph) `BaseCheckpointSaver`
+that persists checkpoints to local filesystem, Google Cloud Storage, or AWS
+S3. One class, backend picked by connection string, nothing to run beyond a
+bucket (or a directory).
+
+## Table of contents
+
+- [Features](#features)
+- [Requirements](#requirements)
+- [Install](#install)
+- [Quickstart](#quickstart)
+- [Examples](#examples)
+- [Choosing a backend](#choosing-a-backend)
+- [Architecture](#architecture)
+- [Runtime type checking](#runtime-type-checking)
+- [Logging](#logging)
+- [Known limitations](#known-limitations)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Features
+
+- `ObjectStorageSaver.from_conn_string(...)` picks local disk, GCS, or S3
+  from the URI scheme. No per-backend subclasses.
+- Full sync and async support: every `BaseCheckpointSaver` method, both
+  flavors (`get_tuple`/`aget_tuple`, `put`/`aput`, `list`/`alist`,
+  `put_writes`/`aput_writes`, `delete_thread`/`adelete_thread`).
+- Tested against the official contract with
+  [`langgraph-checkpoint-conformance`](https://pypi.org/project/langgraph-checkpoint-conformance/)
+  on all three backends, not just hand-written assertions.
+- Runtime type checking on the public API via
+  [typeguard](https://typeguard.readthedocs.io/) catches wrong-argument-type
+  mistakes at the call site.
+- Ships `py.typed` for full static type coverage under mypy/pyright.
+- No database or extra service required in production, just object storage.
+
+## Requirements
+
+Python 3.11+.
+
+## Install
+
+```bash
+pip install langgraph-checkpoint-objectstorage        # local filesystem only
+pip install "langgraph-checkpoint-objectstorage[s3]"   # + AWS S3
+pip install "langgraph-checkpoint-objectstorage[gcs]"  # + Google Cloud Storage
+```
+
+## Quickstart
+
+```python
+from langgraph.graph import END, START, StateGraph
+from langgraph_checkpoint_objectstorage import ObjectStorageSaver
+
+
+def increment(state: dict) -> dict:
+    return {"count": state["count"] + 1}
+
+
+builder = StateGraph(dict)
+builder.add_node("increment", increment)
+builder.add_edge(START, "increment")
+builder.add_edge("increment", END)
+
+saver = ObjectStorageSaver.from_conn_string("file:///tmp/checkpoints")
+graph = builder.compile(checkpointer=saver)
+
+config = {"configurable": {"thread_id": "1"}}
+result = graph.invoke({"count": 0}, config)
+print(result)  # {"count": 1}
+
+# Checkpoints persisted under the thread survive process restarts --
+# inspect or resume from the same thread_id at any later point:
+history = list(graph.get_state_history(config))
+```
+
+## Examples
+
+This same quickstart, runnable under three build tools:
+
+- [`examples/pip`](examples/pip): venv + `pip install -r requirements.txt`
+- [`examples/uv/filesystem`](examples/uv/filesystem): `uv run main.py`
+- [`examples/poetry/filesystem`](examples/poetry/filesystem): `poetry install && poetry run python main.py`
+
+Each installs the package from this repo via a local path dependency
+(swap for a normal PyPI dependency once the package is published).
+
+Further along, against object storage instead of local disk (real bucket
+or a local emulator, no cloud account needed): multiple independent
+sessions run sequentially and one is resumed later, plus the same pattern
+run concurrently via the async API, for both S3 and GCS:
+
+- [`examples/uv/s3`](examples/uv/s3) / [`examples/uv/s3-async`](examples/uv/s3-async)
+- [`examples/poetry/gcs`](examples/poetry/gcs) / [`examples/poetry/gcs-async`](examples/poetry/gcs-async)
+
+Sequential and concurrent are separate examples rather than one combined
+script, see [Known limitations](#known-limitations) for why.
+
+## Choosing a backend
+
+Swap the connection string; everything else stays the same.
+
+```python
+from langgraph_checkpoint_objectstorage import ObjectStorageSaver
+
+# Local filesystem -- handy for development, or single-node deployments
+saver = ObjectStorageSaver.from_conn_string("file:///var/lib/my-app/checkpoints")
+
+# Google Cloud Storage
+saver = ObjectStorageSaver.from_conn_string("gcs://my-bucket/checkpoints")
+
+# AWS S3
+saver = ObjectStorageSaver.from_conn_string("s3://my-bucket/checkpoints")
+```
+
+`from_conn_string` forwards extra keyword arguments to the underlying
+[fsspec](https://filesystem-spec.readthedocs.io/) filesystem constructor.
+Useful for explicit credentials, non-default regions, or S3-compatible
+endpoints (MinIO, Cloudflare R2, etc.):
+
+```python
+saver = ObjectStorageSaver.from_conn_string(
+    "s3://my-bucket/checkpoints",
+    key="...",
+    secret="...",
+    client_kwargs={"endpoint_url": "https://minio.internal:9000"},
+)
+```
+
+Credentials otherwise follow each backend's normal resolution: AWS's usual
+chain (env vars, `~/.aws/credentials`, instance/task role) for S3,
+Application Default Credentials for GCS. Nothing library-specific to
+configure beyond the connection string.
+
+## Architecture
+
+Business logic (key layout, filtering, ordering, idempotency) is written
+once, as async methods. The public sync API is a thin `asyncio.run(...)`
+wrapper around that same async core, not a second implementation, so
+there's a single source of truth per operation instead of sync and async
+code drifting apart. An I/O bridge picks native async calls when the
+backend supports them (`s3fs`, `gcsfs`) and falls back to
+`asyncio.to_thread` when it doesn't (local disk):
+
+```mermaid
+flowchart TD
+    App["Your application<br/>(graph.invoke / ainvoke)"]
+
+    subgraph PublicAPI["Public API — BaseCheckpointSaver contract"]
+        Sync["put / get_tuple / list /<br/>put_writes / delete_thread"]
+        Async["aput / aget_tuple / alist /<br/>aput_writes / adelete_thread"]
+    end
+
+    Core["Async core<br/>(business logic, written once)"]
+    Bridge["I/O bridge<br/>_cat / _pipe / _find / _exists / _rm"]
+    Native["fsspec async-native<br/>(s3fs, gcsfs)"]
+    Threaded["asyncio.to_thread<br/>(LocalFileSystem)"]
+    Backend[("Local disk / S3 / GCS")]
+
+    App --> Sync
+    App --> Async
+    Sync -->|"asyncio.run(...)<br/>thin wrapper, not a<br/>second implementation"| Core
+    Async --> Core
+    Core --> Bridge
+    Bridge -->|backend supports async| Native --> Backend
+    Bridge -->|no native async| Threaded --> Backend
+```
+
+Each checkpoint and each write becomes its own object: no read-modify-write
+on existing keys, so concurrent writers on different threads never race,
+and a `put` or `put_writes` call is always a single write:
+
+```mermaid
+flowchart TD
+    Root["{root}"] --> Thread["{thread_id}/"]
+    Thread --> NS["{checkpoint_ns}/"]
+    NS --> CkptDir["checkpoints/"]
+    NS --> WriteDir["writes/"]
+    CkptDir --> Ckpt["{checkpoint_id}.msgpack<br/>checkpoint + metadata + parent_checkpoint_id"]
+    WriteDir --> WCkpt["{checkpoint_id}/"]
+    WCkpt --> WTask["{task_id}/"]
+    WTask --> WIdx["{idx}.msgpack<br/>task_id + idx + channel + value"]
+```
+
+Key technical decisions this reflects:
+
+- `checkpoint_id` is LangGraph's own [uuid6](https://github.com/langchain-ai/langgraph/blob/main/libs/checkpoint/langgraph/checkpoint/base/id.py),
+  already time-sortable, so `list()`'s newest-first ordering falls out of a
+  plain key sort, with no secondary index to keep in sync.
+- Checkpoints and metadata are serialized through LangGraph's own
+  `JsonPlusSerializer` and treated as opaque: never hand-extracted field by
+  field, since real LangGraph objects carry fields their own TypedDicts
+  don't declare (see [Runtime type checking](#runtime-type-checking)).
+- `put_writes`' overwrite-vs-ignore split ("first write wins" for regular
+  channels, always-replace for the control channels `ERROR`/`SCHEDULED`/
+  `INTERRUPT`/`RESUME`) mirrors the official sqlite/postgres savers exactly.
+- `list(filter=...)` is deliberately client-side, not an oversight: object
+  storage has no query engine to push a filter into. See
+  [Known limitations](#known-limitations).
+
+## Runtime type checking
+
+Public methods are decorated with [typeguard](https://typeguard.readthedocs.io/)
+and raise `typeguard.TypeCheckError` on a call with the wrong argument
+types (e.g. a non-string `thread_id`, a `writes` argument that isn't a
+sequence of `(channel, value)` pairs). This catches integration mistakes
+at the call site instead of letting them corrupt stored data silently.
+
+`config`, `checkpoint`, and `metadata` arguments are intentionally *not*
+strictly checked against LangGraph's `RunnableConfig`/`Checkpoint`/
+`CheckpointMetadata` TypedDicts: real LangGraph objects don't match those
+TypedDicts exactly (a real `RunnableConfig`'s `metadata` field is a
+`collections.ChainMap`, not a plain `dict`; real checkpoints carry fields
+like the legacy `pending_sends` key that isn't declared at all), and strict
+checking would reject every real invocation. Same reasoning applies to
+`get_tuple`/`list`'s return value, which isn't runtime-checked for the same
+reason. Other arguments (`thread_id`, `task_id`, `writes`, `limit`, ...)
+are checked normally.
+
+## Logging
+
+Uses standard `logging` under the logger name
+`langgraph_checkpoint_objectstorage`. No handlers are configured, so it
+stays silent until your application's logging config says otherwise.
+
+For quick debugging, set `LANGGRAPH_CHECKPOINT_OBJECTSTORAGE_LOG_LEVEL=DEBUG`
+before constructing an `ObjectStorageSaver`. It emits one DEBUG line per
+storage read/write/list with the key or prefix touched.
+
+## Known limitations
+
+- `list(filter=...)` is client-side: every checkpoint in the thread/namespace
+  is fetched and filtered in Python, since object storage has no query
+  engine to push the filter into. Fine for typical thread histories (dozens
+  to low hundreds of checkpoints); a very long-running thread's `list` calls
+  will get proportionally slower.
+- No garbage collection or retention policy. Old checkpoints accumulate
+  until you call `delete_thread`, or you set up bucket lifecycle rules
+  yourself.
+- Two writers on the *same* `thread_id` writing concurrently can race, at
+  the same guarantee level as the official sqlite saver (last write "wins"
+  by whichever checkpoint_id sorts last, not by wall-clock order under
+  clock skew). Concurrent writers on different threads never race.
+- The sync `list()` eagerly collects all matching checkpoints before
+  yielding the first one (it wraps the async implementation via
+  `asyncio.run`, which can't stream lazily). Use `alist()` from async code
+  if you need true streaming.
+- Don't mix sync and async calls on the *same* `ObjectStorageSaver`
+  instance against S3 or GCS. Sync calls run on a persistent background
+  loop the underlying filesystem maintains; async calls run on whichever
+  loop the caller provides. The aiohttp session those backends use can
+  only belong to one loop at a time, so alternating between the two on
+  one instance breaks with `RuntimeError: ... attached to a different
+  loop`. Build a separate saver instance per usage style instead (see
+  `examples/uv/s3` vs `examples/uv/s3-async`, or `examples/poetry/gcs` vs
+  `examples/poetry/gcs-async`). Local filesystem isn't affected: it has no
+  persistent session to misalign.
+
+## Development
+
+```bash
+make install        # sync deps into an isolated .venv (installs uv if missing)
+make lint             # black --check, pyflakes, bandit, vulture -- runs before test/build
+make format          # apply black formatting in place
+make test            # full suite -- docker-compose integration tests auto-skip if not up
+make test-unit        # tests/unit only -- no external services, fast
+make test-integration  # tests/integration -- starts docker-compose emulators first
+```
+
+`test`/`test-unit`/`test-integration`/`build` all run `lint` first, so a
+formatting or static-analysis failure blocks the run rather than
+surfacing only after tests pass. `bandit`/`vulture` are scoped to `src/`
+only: `bandit` flags every pytest `assert` and the tests' intentionally
+fake credentials, and `vulture` can't see that `ObjectStorageSaver`'s
+public methods are called by library consumers rather than this codebase
+(see `vulture_whitelist.py`).
+
+Or without `make`, directly via `uv`:
+
+```bash
+uv sync --all-extras --group dev
+uv run pytest
+```
+
+Test layout: `tests/unit/` exercises internal modules (key layout,
+serialization, the saver's core logic, logging, type checking) with no
+external service. `tests/integration/` validates the full
+`BaseCheckpointSaver` contract via
+[`langgraph-checkpoint-conformance`](https://pypi.org/project/langgraph-checkpoint-conformance/)
+against real backends: local disk, an in-process moto server for S3, and
+(via `docker-compose.yaml`) `fake-gcs-server`/`moto-server` containers for a
+full local GCS/S3 round-trip with no cloud account needed. A gated test
+against a real GCS bucket runs only when `GCS_TEST_BUCKET` is set.
+
+```bash
+make compose-up      # start local S3/GCS emulators
+make test-integration
+make compose-down     # stop them when done
+```
+
+## Contributing
+
+Issues and PRs welcome. Before opening one, `make test` should pass
+(`make test-integration` too, if your change touches backend I/O). CI runs
+lint, unit tests (Python 3.11/3.12/3.13), and integration tests against
+docker-compose emulators on every push and PR.
+
+Add an entry under `## [Unreleased]` in [`CHANGELOG.md`](CHANGELOG.md) for
+any user-facing change. On merge to `main`, CI moves that section into a
+new dated version automatically (see the `release` job in
+`.github/workflows/ci.yml`). An empty `[Unreleased]` just gets a generic
+placeholder line instead, so it's worth taking the extra minute.
+
+### Releasing
+
+The `release` job only bumps `pyproject.toml` and `CHANGELOG.md` and
+pushes that commit to `main` -- it doesn't tag or publish anything.
+Publishing to PyPI is a manual step, since it's the one part of this
+pipeline that isn't reversible:
+
+```bash
+git pull origin main
+git tag -a vX.Y.Z -m vX.Y.Z
+git push origin vX.Y.Z
+```
+
+Pushing that tag triggers `.github/workflows/publish.yml`, which builds
+the package and publishes it to PyPI via trusted publishing (no token
+needed). Create the GitHub release from the same tag, e.g.:
+
+```bash
+gh release create vX.Y.Z --title vX.Y.Z --generate-notes
+```
+
+## License
+
+[MIT](LICENSE).

langgraph_checkpoint_objectstorage-0.1.7.dist-info/RECORD

@@ -0,0 +1,9 @@
+langgraph_checkpoint_objectstorage/__init__.py,sha256=nd0AxTrW0Dv5MQlrlF2aJwZ_SqDbZu-e8RX27gm7LIs,180
+langgraph_checkpoint_objectstorage/envelope.py,sha256=dMnB-KKJSd5CkT_5innloqH6mW8o95wBdt7yFT3dw1Y,1546
+langgraph_checkpoint_objectstorage/keys.py,sha256=cgsDjztuY1PkcVPK59f2aiZ01x94egAogM9QZEZLBrE,1358
+langgraph_checkpoint_objectstorage/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+langgraph_checkpoint_objectstorage/saver.py,sha256=r9cvLpj1FDFjL7UfuYkpEMSnGw1ZkVYMlbbMiPPnH8g,18282
+langgraph_checkpoint_objectstorage-0.1.7.dist-info/METADATA,sha256=ZJLoQLfMaXNpBXPUi4yQfxe3lLXIUaax8OhwbVopJjQ,14945
+langgraph_checkpoint_objectstorage-0.1.7.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+langgraph_checkpoint_objectstorage-0.1.7.dist-info/licenses/LICENSE,sha256=gGtZrZUyidOHBs8CU2BO9VBa_qgnurOGJMu-MZTsqXM,1063
+langgraph_checkpoint_objectstorage-0.1.7.dist-info/RECORD,,

langgraph_checkpoint_objectstorage-0.1.7.dist-info/WHEEL

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

langgraph_checkpoint_objectstorage-0.1.7.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sergio
+
+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.