langgraph-checkpoint-grafomem 1.0.0__tar.gz

langgraph_checkpoint_grafomem-1.0.0/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.4
+Name: langgraph-checkpoint-grafomem
+Version: 1.0.0
+Summary: Grafomem (Fair Source) adapter for LangGraph Checkpointers
+Author-email: "Ulissy s.r.l." <hello@grafomem.com>
+License: Apache-2.0
+Project-URL: Homepage, https://grafomem.com
+Project-URL: Repository, https://github.com/cayerbe/grafomem
+Keywords: agent-memory,langgraph,checkpointer,governance,erasure,fair-source
+Requires-Dist: langgraph-checkpoint
+Requires-Dist: grafomem[runtime]>=0.4.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: langgraph; extra == "dev"

langgraph_checkpoint_grafomem-1.0.0/grafomem_checkpoint/__init__.py

@@ -0,0 +1,4 @@
+from .serializer import GrafomemSerializer
+from .saver import GrafomemCheckpointSaver
+
+__all__ = ["GrafomemSerializer", "GrafomemCheckpointSaver"]

langgraph_checkpoint_grafomem-1.0.0/grafomem_checkpoint/saver.py

@@ -0,0 +1,131 @@
+from typing import Any, AsyncIterator, Dict, Iterator, Mapping, Sequence, Collection
+from datetime import datetime, timezone
+import copy
+from langgraph.checkpoint.base import (
+    BaseCheckpointSaver,
+    Checkpoint,
+    CheckpointMetadata,
+    CheckpointTuple,
+    ChannelVersions,
+    RunnableConfig,
+)
+from grafomem.runtime import Receipt
+from .serializer import GrafomemSerializer
+
+class GrafomemCheckpointSaver(BaseCheckpointSaver):
+    """
+    Layer 2: LangGraph Checkpoint Saver Decorator for Lethe.
+    Delegates all storage operations to an inner saver.
+    Emits out-of-band erasure Receipts on delete_thread.
+    """
+    
+    def __init__(self, inner: BaseCheckpointSaver):
+        super().__init__(serde=inner.serde)
+        self.inner = inner
+        if not isinstance(self.inner.serde, GrafomemSerializer):
+            raise ValueError("Inner saver must use GrafomemSerializer as its serde")
+        self._receipts: Dict[str, Receipt] = {}
+        
+    def last_receipt(self, thread_id: str) -> Receipt | None:
+        return self._receipts.get(thread_id)
+        
+    def _create_receipt(self, thread_id: str) -> Receipt:
+        timestamp = datetime.now(timezone.utc).isoformat()
+        
+        payload = f"thread_data|erased|{thread_id}|{self.inner.serde.key_id}|{timestamp}".encode('utf-8')
+        signature = self.inner.serde.private_key.sign(payload)
+        
+        return Receipt(
+            before="thread_data",
+            after="erased",
+            scope=thread_id,
+            key_id=self.inner.serde.key_id,
+            timestamp=timestamp,
+            signature=signature
+        )
+        
+    # --- Delegated Methods ---
+
+    def get_tuple(self, config: RunnableConfig) -> CheckpointTuple | None:
+        return self.inner.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]:
+        return self.inner.list(config, filter=filter, before=before, limit=limit)
+
+    def put(
+        self,
+        config: RunnableConfig,
+        checkpoint: Checkpoint,
+        metadata: CheckpointMetadata,
+        new_versions: ChannelVersions,
+    ) -> RunnableConfig:
+        content_hash = self.inner.serde.compute_content_hash(checkpoint)
+        
+        # Inject content_hash into metadata to retain UUID7 keying for LangGraph
+        new_metadata = dict(metadata) if metadata else {}
+        new_metadata["grafomem_content_hash"] = content_hash
+        
+        return self.inner.put(config, checkpoint, new_metadata, new_versions)
+
+    def put_writes(
+        self,
+        config: RunnableConfig,
+        writes: Sequence[tuple[str, Any]],
+        task_id: str,
+        task_path: str = "",
+    ) -> None:
+        return self.inner.put_writes(config, writes, task_id, task_path)
+        
+    def delete_thread(self, thread_id: str) -> None:
+        self.inner.delete_thread(thread_id)
+        # Emit out-of-band erasure receipt
+        rcpt = self._create_receipt(thread_id)
+        self._receipts[thread_id] = rcpt
+
+    # --- Async Delegated Methods ---
+    async def aget_tuple(self, config: RunnableConfig) -> CheckpointTuple | None:
+        return await self.inner.aget_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 for t in self.inner.alist(config, filter=filter, before=before, limit=limit):
+            yield t
+
+    async def aput(
+        self,
+        config: RunnableConfig,
+        checkpoint: Checkpoint,
+        metadata: CheckpointMetadata,
+        new_versions: ChannelVersions,
+    ) -> RunnableConfig:
+        content_hash = self.inner.serde.compute_content_hash(checkpoint)
+        new_metadata = dict(metadata) if metadata else {}
+        new_metadata["grafomem_content_hash"] = content_hash
+        return await self.inner.aput(config, checkpoint, new_metadata, new_versions)
+
+    async def aput_writes(
+        self,
+        config: RunnableConfig,
+        writes: Sequence[tuple[str, Any]],
+        task_id: str,
+        task_path: str = "",
+    ) -> None:
+        return await self.inner.aput_writes(config, writes, task_id, task_path)
+
+    async def adelete_thread(self, thread_id: str) -> None:
+        await self.inner.adelete_thread(thread_id)
+        rcpt = self._create_receipt(thread_id)
+        self._receipts[thread_id] = rcpt

langgraph_checkpoint_grafomem-1.0.0/grafomem_checkpoint/serializer.py

@@ -0,0 +1,70 @@
+from typing import Any, Tuple
+from cryptography.hazmat.primitives.asymmetric import ed25519
+from langgraph.checkpoint.serde.base import SerializerProtocol
+from langgraph.checkpoint.serde.jsonplus import JsonPlusSerializer
+
+from grafomem.cso import CSO
+
+class GrafomemSerializer(SerializerProtocol):
+    """
+    Layer 1: Serializer decorator for LangGraph checkpointers.
+    Wraps the underlying serde to output signed .gfm blobs.
+    """
+
+    def __init__(
+        self,
+        private_key: ed25519.Ed25519PrivateKey,
+        inner: SerializerProtocol | None = None,
+        key_id: str = "grafomem_checkpoint",
+        trusted_keys: dict | None = None,
+        model_id: str = "grafomem-langgraph-v1",
+        capabilities: frozenset[str] | None = None
+    ):
+        self.private_key = private_key
+        self.inner = inner or JsonPlusSerializer()
+        self.key_id = key_id
+        
+        if trusted_keys is None:
+            self.trusted_keys = {self.key_id: private_key.public_key()}
+        else:
+            self.trusted_keys = trusted_keys
+            
+        self.model_id = model_id
+        self.capabilities = capabilities or frozenset(["namespace.checkpoint"])
+        
+    def _create_cso(self, raw_bytes: bytes) -> CSO:
+        return CSO(
+            M=None,
+            blob=raw_bytes,
+            payload_type="blob",
+            model_id=self.model_id,
+            capabilities=self.capabilities,
+            key_id=self.key_id,
+            consent={"subject_id": "langgraph-checkpoint", "policy": "tenant"}
+        )
+
+    def compute_content_hash(self, obj: Any) -> str:
+        """Computes the content_hash without signing."""
+        _, raw_bytes = self.inner.dumps_typed(obj)
+        cso = self._create_cso(raw_bytes)
+        return cso.content_hash()
+        
+    def dumps_typed(self, obj: Any) -> Tuple[str, bytes]:
+        type_, raw_bytes = self.inner.dumps_typed(obj)
+        
+        # Wrap as a blob CSO
+        cso = self._create_cso(raw_bytes)
+        
+        gfm_bytes = cso.to_gfm(self.private_key)
+        return (type_, gfm_bytes)
+
+    def loads_typed(self, data: Tuple[str, bytes]) -> Any:
+        type_, gfm_bytes = data
+        
+        # Verify and unwrap
+        cso = CSO.from_gfm(gfm_bytes, self.trusted_keys)
+        
+        if cso.payload_type != "blob" or cso.blob is None:
+            raise ValueError("GrafomemSerializer expected a blob payload")
+            
+        return self.inner.loads_typed((type_, cso.blob))

langgraph_checkpoint_grafomem-1.0.0/langgraph_checkpoint_grafomem.egg-info/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.4
+Name: langgraph-checkpoint-grafomem
+Version: 1.0.0
+Summary: Grafomem (Fair Source) adapter for LangGraph Checkpointers
+Author-email: "Ulissy s.r.l." <hello@grafomem.com>
+License: Apache-2.0
+Project-URL: Homepage, https://grafomem.com
+Project-URL: Repository, https://github.com/cayerbe/grafomem
+Keywords: agent-memory,langgraph,checkpointer,governance,erasure,fair-source
+Requires-Dist: langgraph-checkpoint
+Requires-Dist: grafomem[runtime]>=0.4.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: langgraph; extra == "dev"

langgraph_checkpoint_grafomem-1.0.0/langgraph_checkpoint_grafomem.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+pyproject.toml
+grafomem_checkpoint/__init__.py
+grafomem_checkpoint/saver.py
+grafomem_checkpoint/serializer.py
+langgraph_checkpoint_grafomem.egg-info/PKG-INFO
+langgraph_checkpoint_grafomem.egg-info/SOURCES.txt
+langgraph_checkpoint_grafomem.egg-info/dependency_links.txt
+langgraph_checkpoint_grafomem.egg-info/requires.txt
+langgraph_checkpoint_grafomem.egg-info/top_level.txt
+tests/test_adapter.py

langgraph_checkpoint_grafomem-1.0.0/langgraph_checkpoint_grafomem.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

langgraph_checkpoint_grafomem-1.0.0/langgraph_checkpoint_grafomem.egg-info/requires.txt

@@ -0,0 +1,6 @@
+langgraph-checkpoint
+grafomem[runtime]>=0.4.0
+
+[dev]
+pytest
+langgraph

langgraph_checkpoint_grafomem-1.0.0/langgraph_checkpoint_grafomem.egg-info/top_level.txt

@@ -0,0 +1 @@
+grafomem_checkpoint

langgraph_checkpoint_grafomem-1.0.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "langgraph-checkpoint-grafomem"
+version = "1.0.0"
+description = "Grafomem (Fair Source) adapter for LangGraph Checkpointers"
+dependencies = [
+    "langgraph-checkpoint",
+    "grafomem[runtime]>=0.4.0"
+]
+license = { text = "Apache-2.0" }
+authors = [
+    { name = "Ulissy s.r.l.", email = "hello@grafomem.com" }
+]
+keywords = ["agent-memory", "langgraph", "checkpointer", "governance", "erasure", "fair-source"]
+
+[project.urls]
+Homepage = "https://grafomem.com"
+Repository = "https://github.com/cayerbe/grafomem"
+
+[project.optional-dependencies]
+dev = [
+    "pytest",
+    "langgraph"
+]

langgraph_checkpoint_grafomem-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

langgraph_checkpoint_grafomem-1.0.0/tests/test_adapter.py

@@ -0,0 +1,173 @@
+import pytest
+import time
+import copy
+from typing import TypedDict, Annotated
+import operator
+
+from cryptography.hazmat.primitives.asymmetric import ed25519
+from langgraph.graph import StateGraph, START, END
+from langgraph.checkpoint.memory import MemorySaver
+from grafomem.errors import SignatureMismatch
+
+from grafomem_checkpoint.serializer import GrafomemSerializer
+from grafomem_checkpoint.saver import GrafomemCheckpointSaver
+
+
+class State(TypedDict):
+    messages: Annotated[list, operator.add]
+    count: int
+    large_data: list[dict]
+
+def my_node(state: State):
+    return {"messages": ["hello"], "count": state.get("count", 0) + 1, "large_data": state.get("large_data", [])}
+
+async def my_async_node(state: State):
+    return {"messages": ["hello"], "count": state.get("count", 0) + 1, "large_data": state.get("large_data", [])}
+
+def build_graph(saver):
+    builder = StateGraph(State)
+    builder.add_node("A", my_node)
+    builder.add_node("B", my_node)
+    builder.add_edge(START, "A")
+    builder.add_edge("A", "B")
+    builder.add_edge("B", END)
+    return builder.compile(checkpointer=saver)
+
+def test_real_graph_interrupt_and_resume():
+    priv = ed25519.Ed25519PrivateKey.generate()
+    serde = GrafomemSerializer(private_key=priv)
+    inner = MemorySaver(serde=serde)
+    saver = GrafomemCheckpointSaver(inner)
+    
+    # Graph that suspends / interrupts
+    builder = StateGraph(State)
+    builder.add_node("A", my_node)
+    builder.add_edge(START, "A")
+    builder.add_edge("A", END)
+    graph = builder.compile(checkpointer=saver, interrupt_after=["A"])
+    
+    config = {"configurable": {"thread_id": "thread-1"}}
+    
+    # Invoke and interrupt
+    result1 = graph.invoke({"messages": ["start"], "count": 0, "large_data": [{"key": "value"}] * 10}, config)
+    
+    # State should be at A
+    checkpoint_tuple = saver.get_tuple(config)
+    assert checkpoint_tuple is not None
+    assert checkpoint_tuple.checkpoint["id"] is not None
+    assert checkpoint_tuple.metadata.get("grafomem_content_hash") is not None
+    
+    # Resume bit-identical
+    result2 = graph.invoke(None, config)
+    assert result2["count"] == 1
+    assert result2["messages"] == ["start", "hello"]
+    
+@pytest.mark.asyncio
+async def test_async_real_graph_interrupt_resume_adelete():
+    priv = ed25519.Ed25519PrivateKey.generate()
+    serde = GrafomemSerializer(private_key=priv)
+    inner = MemorySaver(serde=serde)
+    saver = GrafomemCheckpointSaver(inner)
+    
+    # Graph that suspends / interrupts
+    builder = StateGraph(State)
+    builder.add_node("A", my_async_node)
+    builder.add_edge(START, "A")
+    builder.add_edge("A", END)
+    graph = builder.compile(checkpointer=saver, interrupt_after=["A"])
+    
+    config = {"configurable": {"thread_id": "thread-async-1"}}
+    
+    # ainvoke and interrupt
+    await graph.ainvoke({"messages": ["start_async"], "count": 0, "large_data": []}, config)
+    
+    # State should be at A
+    checkpoint_tuple = await saver.aget_tuple(config)
+    assert checkpoint_tuple is not None
+    assert checkpoint_tuple.checkpoint["id"] is not None
+    assert checkpoint_tuple.metadata.get("grafomem_content_hash") is not None
+    
+    # Resume bit-identical
+    result2 = await graph.ainvoke(None, config)
+    assert result2["count"] == 1
+    assert result2["messages"] == ["start_async", "hello"]
+    
+    # Async Delete Thread
+    await saver.adelete_thread("thread-async-1")
+    
+    # Get receipt and verify
+    rcpt = saver.last_receipt("thread-async-1")
+    assert rcpt is not None
+    assert rcpt.scope == "thread-async-1"
+    assert rcpt.before == "thread_data"
+    assert rcpt.after == "erased"
+    assert rcpt.verify(priv.public_key())
+    
+def test_tamper_signature_mismatch():
+    priv = ed25519.Ed25519PrivateKey.generate()
+    serde = GrafomemSerializer(private_key=priv)
+    inner = MemorySaver(serde=serde)
+    saver = GrafomemCheckpointSaver(inner)
+    
+    graph = build_graph(saver)
+    config = {"configurable": {"thread_id": "thread-2"}}
+    graph.invoke({"messages": ["hi"], "count": 0}, config)
+    
+    type_, gfm_bytes = serde.dumps_typed({"id": "some_id", "v": 1})
+    
+    # Flip a byte
+    b_arr = bytearray(gfm_bytes)
+    b_arr[-1] ^= 0x01
+    
+    with pytest.raises(ValueError, match="signature mismatch"):
+        serde.loads_typed((type_, bytes(b_arr)))
+
+def test_delete_thread_receipt():
+    priv = ed25519.Ed25519PrivateKey.generate()
+    serde = GrafomemSerializer(private_key=priv)
+    inner = MemorySaver(serde=serde)
+    saver = GrafomemCheckpointSaver(inner)
+    
+    graph = build_graph(saver)
+    config = {"configurable": {"thread_id": "thread-3"}}
+    graph.invoke({"messages": ["hi"], "count": 0}, config)
+    
+    # Erase
+    saver.delete_thread("thread-3")
+    
+    # Get receipt
+    rcpt = saver.last_receipt("thread-3")
+    assert rcpt is not None
+    assert rcpt.scope == "thread-3"
+    assert rcpt.before == "thread_data"
+    assert rcpt.after == "erased"
+    
+    # Verify receipt signature
+    assert rcpt.verify(priv.public_key())
+
+def test_serialization_overhead():
+    priv = ed25519.Ed25519PrivateKey.generate()
+    serde = GrafomemSerializer(private_key=priv)
+    inner = MemorySaver(serde=serde)
+    saver = GrafomemCheckpointSaver(inner)
+    
+    # Generate large state
+    large_data = [{"k": f"value_{i}", "data": "x" * 1000} for i in range(1000)] # ~1MB
+    state = {"v": 1, "id": "test", "ts": "2026", "channel_values": {"large_data": large_data}}
+    
+    # Measure without Grafomem
+    from langgraph.checkpoint.serde.jsonplus import JsonPlusSerializer
+    base_serde = JsonPlusSerializer()
+    
+    t0 = time.time()
+    for _ in range(10):
+        base_serde.dumps_typed(state)
+    base_time = (time.time() - t0) / 10
+    
+    t0 = time.time()
+    for _ in range(10):
+        serde.dumps_typed(state)
+    grafomem_time = (time.time() - t0) / 10
+    
+    overhead = grafomem_time - base_time
+    print(f"\n[Overhead Report] Base serialization: {base_time*1000:.2f}ms, Grafomem serialization: {grafomem_time*1000:.2f}ms. Overhead: {overhead*1000:.2f}ms per step.")