maximem-synap-langgraph 0.1.0__tar.gz

maximem_synap_langgraph-0.1.0/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: maximem-synap-langgraph
+Version: 0.1.0
+Summary: Synap memory integration for LangGraph — BaseStore + BaseCheckpointSaver
+Author: Synap Team
+License-Expression: Apache-2.0
+Keywords: synap,memory,langgraph,ai,agents,checkpointer,store
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: maximem-synap>=0.2.0
+Requires-Dist: maximem-synap-integrations-common>=0.1.0
+Requires-Dist: langgraph>=1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+
+# maximem-synap-langgraph
+
+Synap memory integration for [LangGraph](https://langchain-ai.github.io/langgraph/).
+
+## Install
+
+```bash
+pip install maximem-synap-langgraph
+```
+
+Requires `langgraph>=1.0`, `maximem-synap>=0.2.0`.
+
+## What's in the box
+
+- **`SynapStore`** — implements LangGraph's `BaseStore` for cross-thread long-term memory. Semantic search via `store.search(namespace, query=...)` routes to `sdk.fetch(...)`, so your graph nodes get Synap-powered recall out of the box.
+
+- **`SynapCheckpointSaver`** — implements `BaseCheckpointSaver` with **best-effort fuzzy retrieval**. Checkpoint writes succeed durably; reads use `sdk.fetch` which is semantic-search shaped rather than exact KV. Use for observability/audit and demo flows. For production checkpoint durability, pair with `SqliteSaver` / `PostgresSaver`.
+
+## Quickstart
+
+```python
+from langgraph.graph import StateGraph, START, END
+from maximem_synap import MaximemSynapSDK
+from synap_langgraph import SynapStore, SynapCheckpointSaver
+
+sdk = MaximemSynapSDK(api_key="sk-...")
+
+store = SynapStore(sdk, user_id="alice", customer_id="acme")
+saver = SynapCheckpointSaver(sdk, user_id="alice", customer_id="acme")
+
+graph = StateGraph(MyState)
+# ... add nodes / edges ...
+app = graph.compile(checkpointer=saver, store=store)
+
+# Store usage inside a node:
+async def remember(state, runtime):
+    await runtime.store.aput(
+        ("alice", "preferences"),
+        "language",
+        {"value": "English"},
+    )
+```
+
+## Error policy
+
+- **Writes** (`SynapStore.put`, `SynapCheckpointSaver.put`, `put_writes`) surface SDK failures as `SynapIntegrationError`. Silent drops would hide ingestion outages.
+- **Reads** (`get`, `search`, `get_tuple`, `list`) degrade gracefully — they log at `ERROR` and return `None`/`[]` rather than crashing the graph.
+- **Deletes** (`SynapStore.delete`, `SynapCheckpointSaver.delete_thread`) warn once and no-op — Synap has no public delete API.
+
+## When to use which checkpointer
+
+| Goal | Saver |
+| ---- | ----- |
+| Durable thread checkpoints, exact restore | LangGraph's `SqliteSaver` or `PostgresSaver` |
+| Thread state surfaced in Synap for observability/audit/cross-thread analysis | `SynapCheckpointSaver` |
+| Both | Use Sqlite/Postgres as primary; layer `SynapCheckpointSaver` for the Synap view |
+
+Cross-thread long-term memory (`BaseStore`) maps cleanly to Synap — use `SynapStore` as your default.

maximem_synap_langgraph-0.1.0/README.md

@@ -0,0 +1,58 @@
+# maximem-synap-langgraph
+
+Synap memory integration for [LangGraph](https://langchain-ai.github.io/langgraph/).
+
+## Install
+
+```bash
+pip install maximem-synap-langgraph
+```
+
+Requires `langgraph>=1.0`, `maximem-synap>=0.2.0`.
+
+## What's in the box
+
+- **`SynapStore`** — implements LangGraph's `BaseStore` for cross-thread long-term memory. Semantic search via `store.search(namespace, query=...)` routes to `sdk.fetch(...)`, so your graph nodes get Synap-powered recall out of the box.
+
+- **`SynapCheckpointSaver`** — implements `BaseCheckpointSaver` with **best-effort fuzzy retrieval**. Checkpoint writes succeed durably; reads use `sdk.fetch` which is semantic-search shaped rather than exact KV. Use for observability/audit and demo flows. For production checkpoint durability, pair with `SqliteSaver` / `PostgresSaver`.
+
+## Quickstart
+
+```python
+from langgraph.graph import StateGraph, START, END
+from maximem_synap import MaximemSynapSDK
+from synap_langgraph import SynapStore, SynapCheckpointSaver
+
+sdk = MaximemSynapSDK(api_key="sk-...")
+
+store = SynapStore(sdk, user_id="alice", customer_id="acme")
+saver = SynapCheckpointSaver(sdk, user_id="alice", customer_id="acme")
+
+graph = StateGraph(MyState)
+# ... add nodes / edges ...
+app = graph.compile(checkpointer=saver, store=store)
+
+# Store usage inside a node:
+async def remember(state, runtime):
+    await runtime.store.aput(
+        ("alice", "preferences"),
+        "language",
+        {"value": "English"},
+    )
+```
+
+## Error policy
+
+- **Writes** (`SynapStore.put`, `SynapCheckpointSaver.put`, `put_writes`) surface SDK failures as `SynapIntegrationError`. Silent drops would hide ingestion outages.
+- **Reads** (`get`, `search`, `get_tuple`, `list`) degrade gracefully — they log at `ERROR` and return `None`/`[]` rather than crashing the graph.
+- **Deletes** (`SynapStore.delete`, `SynapCheckpointSaver.delete_thread`) warn once and no-op — Synap has no public delete API.
+
+## When to use which checkpointer
+
+| Goal | Saver |
+| ---- | ----- |
+| Durable thread checkpoints, exact restore | LangGraph's `SqliteSaver` or `PostgresSaver` |
+| Thread state surfaced in Synap for observability/audit/cross-thread analysis | `SynapCheckpointSaver` |
+| Both | Use Sqlite/Postgres as primary; layer `SynapCheckpointSaver` for the Synap view |
+
+Cross-thread long-term memory (`BaseStore`) maps cleanly to Synap — use `SynapStore` as your default.

maximem_synap_langgraph-0.1.0/maximem_synap_langgraph.egg-info/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: maximem-synap-langgraph
+Version: 0.1.0
+Summary: Synap memory integration for LangGraph — BaseStore + BaseCheckpointSaver
+Author: Synap Team
+License-Expression: Apache-2.0
+Keywords: synap,memory,langgraph,ai,agents,checkpointer,store
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: maximem-synap>=0.2.0
+Requires-Dist: maximem-synap-integrations-common>=0.1.0
+Requires-Dist: langgraph>=1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+
+# maximem-synap-langgraph
+
+Synap memory integration for [LangGraph](https://langchain-ai.github.io/langgraph/).
+
+## Install
+
+```bash
+pip install maximem-synap-langgraph
+```
+
+Requires `langgraph>=1.0`, `maximem-synap>=0.2.0`.
+
+## What's in the box
+
+- **`SynapStore`** — implements LangGraph's `BaseStore` for cross-thread long-term memory. Semantic search via `store.search(namespace, query=...)` routes to `sdk.fetch(...)`, so your graph nodes get Synap-powered recall out of the box.
+
+- **`SynapCheckpointSaver`** — implements `BaseCheckpointSaver` with **best-effort fuzzy retrieval**. Checkpoint writes succeed durably; reads use `sdk.fetch` which is semantic-search shaped rather than exact KV. Use for observability/audit and demo flows. For production checkpoint durability, pair with `SqliteSaver` / `PostgresSaver`.
+
+## Quickstart
+
+```python
+from langgraph.graph import StateGraph, START, END
+from maximem_synap import MaximemSynapSDK
+from synap_langgraph import SynapStore, SynapCheckpointSaver
+
+sdk = MaximemSynapSDK(api_key="sk-...")
+
+store = SynapStore(sdk, user_id="alice", customer_id="acme")
+saver = SynapCheckpointSaver(sdk, user_id="alice", customer_id="acme")
+
+graph = StateGraph(MyState)
+# ... add nodes / edges ...
+app = graph.compile(checkpointer=saver, store=store)
+
+# Store usage inside a node:
+async def remember(state, runtime):
+    await runtime.store.aput(
+        ("alice", "preferences"),
+        "language",
+        {"value": "English"},
+    )
+```
+
+## Error policy
+
+- **Writes** (`SynapStore.put`, `SynapCheckpointSaver.put`, `put_writes`) surface SDK failures as `SynapIntegrationError`. Silent drops would hide ingestion outages.
+- **Reads** (`get`, `search`, `get_tuple`, `list`) degrade gracefully — they log at `ERROR` and return `None`/`[]` rather than crashing the graph.
+- **Deletes** (`SynapStore.delete`, `SynapCheckpointSaver.delete_thread`) warn once and no-op — Synap has no public delete API.
+
+## When to use which checkpointer
+
+| Goal | Saver |
+| ---- | ----- |
+| Durable thread checkpoints, exact restore | LangGraph's `SqliteSaver` or `PostgresSaver` |
+| Thread state surfaced in Synap for observability/audit/cross-thread analysis | `SynapCheckpointSaver` |
+| Both | Use Sqlite/Postgres as primary; layer `SynapCheckpointSaver` for the Synap view |
+
+Cross-thread long-term memory (`BaseStore`) maps cleanly to Synap — use `SynapStore` as your default.

maximem_synap_langgraph-0.1.0/maximem_synap_langgraph.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+README.md
+pyproject.toml
+maximem_synap_langgraph.egg-info/PKG-INFO
+maximem_synap_langgraph.egg-info/SOURCES.txt
+maximem_synap_langgraph.egg-info/dependency_links.txt
+maximem_synap_langgraph.egg-info/requires.txt
+maximem_synap_langgraph.egg-info/top_level.txt
+synap_langgraph/__init__.py
+synap_langgraph/checkpointer.py
+synap_langgraph/store.py

maximem_synap_langgraph-0.1.0/maximem_synap_langgraph.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

maximem_synap_langgraph-0.1.0/maximem_synap_langgraph.egg-info/requires.txt

@@ -0,0 +1,7 @@
+maximem-synap>=0.2.0
+maximem-synap-integrations-common>=0.1.0
+langgraph>=1.0
+
+[dev]
+pytest>=7.0
+pytest-asyncio>=0.21

maximem_synap_langgraph-0.1.0/maximem_synap_langgraph.egg-info/top_level.txt

@@ -0,0 +1 @@
+synap_langgraph

maximem_synap_langgraph-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "maximem-synap-langgraph"
+version = "0.1.0"
+description = "Synap memory integration for LangGraph — BaseStore + BaseCheckpointSaver"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+authors = [
+    {name = "Synap Team"}
+]
+keywords = ["synap", "memory", "langgraph", "ai", "agents", "checkpointer", "store"]
+
+dependencies = [
+    "maximem-synap>=0.2.0",
+    "maximem-synap-integrations-common>=0.1.0",
+    "langgraph>=1.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-asyncio>=0.21",
+]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["synap_langgraph*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

maximem_synap_langgraph-0.1.0/setup.cfg

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

maximem_synap_langgraph-0.1.0/synap_langgraph/__init__.py

@@ -0,0 +1,22 @@
+"""Synap integration for LangGraph.
+
+Exposes:
+
+- :class:`SynapStore` — a ``BaseStore`` implementation backed by Synap's
+  semantic memory (``sdk.memories.create`` + ``sdk.fetch``). Drop it into
+  ``StateGraph.compile(store=SynapStore(...))`` for cross-thread long-term
+  memory. Semantic search via ``store.asearch`` is the natural fit for our
+  retrieval model.
+
+- :class:`SynapCheckpointSaver` — a ``BaseCheckpointSaver`` that persists
+  thread execution state to Synap. **Best-effort fuzzy retrieval**: reads
+  use ``sdk.fetch`` with metadata filters, which is semantic-search-shaped
+  rather than exact KV. Pair with a real KV saver (SqliteSaver, PostgresSaver)
+  for production-grade checkpoint fidelity; use ``SynapCheckpointSaver`` for
+  observability/audit and demo flows.
+"""
+
+from synap_langgraph.store import SynapStore
+from synap_langgraph.checkpointer import SynapCheckpointSaver
+
+__all__ = ["SynapStore", "SynapCheckpointSaver"]

maximem_synap_langgraph-0.1.0/synap_langgraph/checkpointer.py

@@ -0,0 +1,421 @@
+"""SynapCheckpointSaver — best-effort fuzzy ``BaseCheckpointSaver``.
+
+Synap's retrieval is semantic-search shaped, not exact key-value. This saver
+trades off checkpoint fidelity for the benefits of storing thread state in
+Synap: observability, audit, and cross-thread memory sitting next to the
+execution history.
+
+For production durability, pair with a proper KV-backed saver
+(``SqliteSaver`` / ``PostgresSaver`` in a subgraph or a composite saver).
+
+Storage strategy:
+
+- ``aput(config, checkpoint, metadata, new_versions)`` serialises the
+  checkpoint blob via ``self.serde.dumps_typed`` → ``(type, bytes)``, then
+  ingests as a Synap memory via ``sdk.memories.create`` with the raw bytes
+  base64-encoded in ``document`` and metadata tagging the thread/checkpoint
+  coordinates.
+- ``aget_tuple(config)`` fetches by thread id and returns the latest
+  matching checkpoint.
+- ``alist(...)`` yields the filtered matches from a single fetch.
+- ``aput_writes`` ingests pending writes with a distinguishing metadata type.
+- ``adelete_thread`` warns + no-ops (Synap has no public delete API).
+
+Error policy: writes surface ``SynapIntegrationError`` on SDK failure. Reads
+degrade gracefully (return ``None`` / empty iterator).
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import logging
+from typing import Any, AsyncIterator, Iterator, Optional, Sequence
+
+from langchain_core.runnables import RunnableConfig
+from langgraph.checkpoint.base import (
+    BaseCheckpointSaver,
+    ChannelVersions,
+    Checkpoint,
+    CheckpointMetadata,
+    CheckpointTuple,
+)
+from maximem_synap import MaximemSynapSDK
+from synap_integrations_common import (
+    run_async,
+    wrap_sdk_errors_async,
+)
+
+logger = logging.getLogger(__name__)
+
+
+_MARKER = "lg_cp"
+_WRITE_MARKER = "lg_cp_writes"
+
+
+class SynapCheckpointSaver(BaseCheckpointSaver):
+    """Synap-backed LangGraph checkpoint saver (best-effort fuzzy)."""
+
+    def __init__(
+        self,
+        sdk: MaximemSynapSDK,
+        user_id: str,
+        customer_id: str = "",
+        *,
+        mode: str = "accurate",
+    ) -> None:
+        if sdk is None:
+            raise ValueError("SynapCheckpointSaver requires a non-None sdk")
+        if not user_id:
+            raise ValueError("SynapCheckpointSaver requires a non-empty user_id")
+        super().__init__()
+        self.sdk = sdk
+        self.user_id = user_id
+        self.customer_id = customer_id
+        self.mode = mode
+        self._delete_warned = False
+
+    # ── put ─────────────────────────────────────────────────────────────────
+
+    async def aput(
+        self,
+        config: RunnableConfig,
+        checkpoint: Checkpoint,
+        metadata: CheckpointMetadata,
+        new_versions: ChannelVersions,
+    ) -> RunnableConfig:
+        configurable = dict(config.get("configurable", {}))
+        thread_id = str(configurable.get("thread_id") or "")
+        checkpoint_ns = str(configurable.get("checkpoint_ns") or "")
+        checkpoint_id = str(checkpoint.get("id") or configurable.get("checkpoint_id") or "")
+        parent_checkpoint_id = str(configurable.get("checkpoint_id") or "")
+
+        serde_type, raw_bytes = self.serde.dumps_typed(checkpoint)
+        document = _encode(serde_type, raw_bytes, metadata, new_versions)
+
+        meta = {
+            _MARKER: True,
+            "thread_id": thread_id,
+            "checkpoint_ns": checkpoint_ns,
+            "checkpoint_id": checkpoint_id,
+            "parent_checkpoint_id": parent_checkpoint_id,
+        }
+
+        async with wrap_sdk_errors_async(
+            "langgraph.checkpointer.put",
+            logger,
+            thread_id=thread_id,
+            checkpoint_id=checkpoint_id,
+        ):
+            await self.sdk.memories.create(
+                document=document,
+                user_id=self.user_id,
+                customer_id=self.customer_id or None,
+                metadata=meta,
+            )
+
+        return {
+            "configurable": {
+                "thread_id": thread_id,
+                "checkpoint_ns": checkpoint_ns,
+                "checkpoint_id": checkpoint_id,
+            }
+        }
+
+    def put(
+        self,
+        config: RunnableConfig,
+        checkpoint: Checkpoint,
+        metadata: CheckpointMetadata,
+        new_versions: ChannelVersions,
+    ) -> RunnableConfig:
+        return run_async(self.aput(config, checkpoint, metadata, new_versions))
+
+    # ── put_writes ──────────────────────────────────────────────────────────
+
+    async def aput_writes(
+        self,
+        config: RunnableConfig,
+        writes: Sequence[tuple[str, Any]],
+        task_id: str,
+        task_path: str = "",
+    ) -> None:
+        configurable = dict(config.get("configurable", {}))
+        thread_id = str(configurable.get("thread_id") or "")
+        checkpoint_ns = str(configurable.get("checkpoint_ns") or "")
+        checkpoint_id = str(configurable.get("checkpoint_id") or "")
+
+        # Serialise each write individually so deserialisation fidelity survives
+        # per-channel. Each write is (channel, value).
+        encoded_writes: list[dict[str, Any]] = []
+        for channel, value in writes:
+            t, b = self.serde.dumps_typed(value)
+            encoded_writes.append({
+                "channel": channel,
+                "type": t,
+                "value_b64": base64.b64encode(b).decode("ascii"),
+            })
+
+        document = json.dumps({
+            "task_id": task_id,
+            "task_path": task_path,
+            "writes": encoded_writes,
+        })
+
+        meta = {
+            _WRITE_MARKER: True,
+            "thread_id": thread_id,
+            "checkpoint_ns": checkpoint_ns,
+            "checkpoint_id": checkpoint_id,
+            "task_id": task_id,
+        }
+
+        async with wrap_sdk_errors_async(
+            "langgraph.checkpointer.put_writes",
+            logger,
+            thread_id=thread_id,
+            checkpoint_id=checkpoint_id,
+            task_id=task_id,
+        ):
+            await self.sdk.memories.create(
+                document=document,
+                user_id=self.user_id,
+                customer_id=self.customer_id or None,
+                metadata=meta,
+            )
+
+    def put_writes(
+        self,
+        config: RunnableConfig,
+        writes: Sequence[tuple[str, Any]],
+        task_id: str,
+        task_path: str = "",
+    ) -> None:
+        run_async(self.aput_writes(config, writes, task_id, task_path))
+
+    # ── get_tuple ───────────────────────────────────────────────────────────
+
+    async def aget_tuple(self, config: RunnableConfig) -> Optional[CheckpointTuple]:
+        configurable = dict(config.get("configurable", {}))
+        thread_id = str(configurable.get("thread_id") or "")
+        if not thread_id:
+            return None
+        checkpoint_ns = str(configurable.get("checkpoint_ns") or "")
+        target_cp_id = configurable.get("checkpoint_id")
+
+        tuples = await self._fetch_checkpoint_tuples(
+            thread_id=thread_id,
+            checkpoint_ns=checkpoint_ns,
+            target_cp_id=str(target_cp_id) if target_cp_id else None,
+            limit=10,
+        )
+        if not tuples:
+            return None
+        return tuples[0]
+
+    def get_tuple(self, config: RunnableConfig) -> Optional[CheckpointTuple]:
+        return run_async(self.aget_tuple(config))
+
+    # ── list ────────────────────────────────────────────────────────────────
+
+    async def alist(
+        self,
+        config: Optional[RunnableConfig],
+        *,
+        filter: Optional[dict[str, Any]] = None,
+        before: Optional[RunnableConfig] = None,
+        limit: Optional[int] = None,
+    ) -> AsyncIterator[CheckpointTuple]:
+        configurable = dict((config or {}).get("configurable", {}))
+        thread_id = str(configurable.get("thread_id") or "")
+        if not thread_id:
+            return
+        checkpoint_ns = str(configurable.get("checkpoint_ns") or "")
+        before_id: Optional[str] = None
+        if before:
+            before_id = str(
+                (before.get("configurable") or {}).get("checkpoint_id") or ""
+            ) or None
+
+        tuples = await self._fetch_checkpoint_tuples(
+            thread_id=thread_id,
+            checkpoint_ns=checkpoint_ns,
+            target_cp_id=None,
+            limit=max(limit or 25, 25),
+        )
+
+        count = 0
+        for tup in tuples:
+            if before_id and tup.config["configurable"].get("checkpoint_id") == before_id:
+                break
+            if filter and not _metadata_matches_filter(tup.metadata, filter):
+                continue
+            yield tup
+            count += 1
+            if limit and count >= limit:
+                return
+
+    def list(
+        self,
+        config: Optional[RunnableConfig],
+        *,
+        filter: Optional[dict[str, Any]] = None,
+        before: Optional[RunnableConfig] = None,
+        limit: Optional[int] = None,
+    ) -> Iterator[CheckpointTuple]:
+        async def _collect() -> list[CheckpointTuple]:
+            out: list[CheckpointTuple] = []
+            async for t in self.alist(config, filter=filter, before=before, limit=limit):
+                out.append(t)
+            return out
+
+        return iter(run_async(_collect()))
+
+    # ── delete_thread ───────────────────────────────────────────────────────
+
+    async def adelete_thread(self, thread_id: str) -> None:
+        if not self._delete_warned:
+            logger.warning(
+                "SynapCheckpointSaver.delete_thread: Synap has no public delete "
+                "API; this is a no-op. This warning fires once."
+            )
+            self._delete_warned = True
+
+    def delete_thread(self, thread_id: str) -> None:
+        run_async(self.adelete_thread(thread_id))
+
+    # ── fetch helpers ───────────────────────────────────────────────────────
+
+    async def _fetch_checkpoint_tuples(
+        self,
+        *,
+        thread_id: str,
+        checkpoint_ns: str,
+        target_cp_id: Optional[str],
+        limit: int,
+    ) -> list[CheckpointTuple]:
+        try:
+            response = await self.sdk.fetch(
+                user_id=self.user_id,
+                customer_id=self.customer_id or None,
+                search_query=[f"{thread_id}"],
+                max_results=limit,
+                mode=self.mode,
+                include_conversation_context=False,
+            )
+        except Exception as exc:  # noqa: BLE001
+            logger.error(
+                "SynapCheckpointSaver: sdk.fetch failed thread_id=%s error=%s",
+                thread_id, exc, exc_info=True,
+            )
+            return []
+
+        # Collect candidate facts: must be our checkpoint marker + same thread.
+        candidates: list[tuple[Any, dict[str, Any]]] = []
+        for fact in getattr(response, "facts", None) or []:
+            md = getattr(fact, "metadata", None) or {}
+            if not md.get(_MARKER):
+                continue
+            if md.get("thread_id") != thread_id:
+                continue
+            if checkpoint_ns and md.get("checkpoint_ns") != checkpoint_ns:
+                continue
+            if target_cp_id and md.get("checkpoint_id") != target_cp_id:
+                continue
+            candidates.append((fact, md))
+
+        # Most recent first by extracted_at.
+        candidates.sort(
+            key=lambda pair: getattr(pair[0], "extracted_at", 0) or 0,
+            reverse=True,
+        )
+
+        tuples: list[CheckpointTuple] = []
+        for fact, md in candidates:
+            try:
+                checkpoint, cp_metadata = _decode(
+                    getattr(fact, "content", "") or "",
+                    self.serde,
+                )
+            except Exception as exc:  # noqa: BLE001
+                logger.error(
+                    "SynapCheckpointSaver: failed to decode checkpoint "
+                    "thread_id=%s id=%s error=%s",
+                    thread_id, md.get("checkpoint_id"), exc, exc_info=True,
+                )
+                continue
+
+            cfg: RunnableConfig = {
+                "configurable": {
+                    "thread_id": thread_id,
+                    "checkpoint_ns": md.get("checkpoint_ns") or "",
+                    "checkpoint_id": md.get("checkpoint_id") or "",
+                }
+            }
+            parent_cfg: Optional[RunnableConfig] = None
+            parent_id = md.get("parent_checkpoint_id")
+            if parent_id:
+                parent_cfg = {
+                    "configurable": {
+                        "thread_id": thread_id,
+                        "checkpoint_ns": md.get("checkpoint_ns") or "",
+                        "checkpoint_id": parent_id,
+                    }
+                }
+            tuples.append(
+                CheckpointTuple(
+                    config=cfg,
+                    checkpoint=checkpoint,
+                    metadata=cp_metadata,
+                    parent_config=parent_cfg,
+                    pending_writes=None,
+                )
+            )
+        return tuples
+
+
+# ── encode / decode helpers ─────────────────────────────────────────────────
+
+
+def _encode(
+    serde_type: str,
+    raw_bytes: bytes,
+    metadata: CheckpointMetadata,
+    new_versions: ChannelVersions,
+) -> str:
+    """Pack the checkpoint + metadata into a single JSON string document."""
+    return json.dumps({
+        "serde_type": serde_type,
+        "checkpoint_b64": base64.b64encode(raw_bytes).decode("ascii"),
+        "metadata": _safe_json(dict(metadata or {})),
+        "new_versions": _safe_json(dict(new_versions or {})),
+    })
+
+
+def _decode(document: str, serde: Any) -> tuple[Checkpoint, CheckpointMetadata]:
+    payload = json.loads(document)
+    t = payload["serde_type"]
+    b = base64.b64decode(payload["checkpoint_b64"])
+    checkpoint = serde.loads_typed((t, b))
+    metadata: CheckpointMetadata = payload.get("metadata") or {}  # type: ignore[assignment]
+    return checkpoint, metadata
+
+
+def _safe_json(obj: Any) -> Any:
+    """Coerce an arbitrary dict into json-serialisable form (best effort)."""
+    try:
+        json.dumps(obj)
+        return obj
+    except TypeError:
+        return {k: str(v) for k, v in obj.items()} if isinstance(obj, dict) else str(obj)
+
+
+def _metadata_matches_filter(
+    metadata: CheckpointMetadata,
+    filter_: dict[str, Any],
+) -> bool:
+    md = dict(metadata or {})
+    for k, v in filter_.items():
+        if md.get(k) != v:
+            return False
+    return True

maximem_synap_langgraph-0.1.0/synap_langgraph/store.py

@@ -0,0 +1,316 @@
+"""SynapStore — LangGraph ``BaseStore`` backed by Synap semantic memory.
+
+Implements ``batch`` / ``abatch`` (the only abstract methods) and dispatches
+individual ops (:class:`PutOp`, :class:`GetOp`, :class:`SearchOp`,
+:class:`ListNamespacesOp`) to async helpers. The convenience API
+(``put``/``get``/``search``/``delete``/``list_namespaces`` + async variants)
+is inherited unchanged from ``BaseStore`` and rides through ``(a)batch``.
+
+Storage strategy:
+
+- Each ``put`` is ingested as a Synap memory via ``sdk.memories.create`` with
+  the value JSON-encoded in ``document`` and ``metadata`` tagging the
+  namespace tuple (joined by ``/``) plus the key.
+- ``get`` retrieves via ``sdk.fetch`` with ``search_query=[namespace+key]``
+  and filters the returned facts by the namespace/key metadata markers.
+- ``search`` uses ``sdk.fetch(search_query=[query])`` and filters by
+  namespace-prefix in metadata. Scores flow through from ``confidence``.
+- ``delete`` and ``list_namespaces`` warn + no-op (Synap has no public
+  delete API, same pattern as synap-crewai).
+
+Error policy:
+
+- Writes surface ``SynapIntegrationError`` on SDK failure — silent drops
+  would hide ingestion outages.
+- Reads degrade gracefully — return ``None``/``[]`` with an ERROR log so an
+  SDK blip doesn't poison an agent turn.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from datetime import datetime, timezone
+from typing import Any, Iterable, Optional
+
+from langgraph.store.base import (
+    BaseStore,
+    GetOp,
+    Item,
+    ListNamespacesOp,
+    Op,
+    PutOp,
+    Result,
+    SearchItem,
+    SearchOp,
+)
+from maximem_synap import MaximemSynapSDK
+from synap_integrations_common import (
+    SynapIntegrationError,
+    run_async,
+    wrap_sdk_errors_async,
+)
+
+logger = logging.getLogger(__name__)
+
+# Metadata keys we stamp on every Synap memory we create through SynapStore
+# so we can identify / filter them on retrieval.
+_MARKER = "lg_store"
+_NS = "lg_store_ns"
+_KEY = "lg_store_key"
+
+
+def _ns_str(namespace: tuple[str, ...]) -> str:
+    """Stringify a namespace tuple for metadata / search tokens."""
+    return "/".join(namespace)
+
+
+def _matches_namespace_prefix(
+    item_ns: str,
+    prefix: tuple[str, ...],
+) -> bool:
+    """Return True iff ``item_ns`` sits at or below ``prefix``."""
+    if not prefix:
+        return True
+    pref_str = _ns_str(prefix)
+    return item_ns == pref_str or item_ns.startswith(pref_str + "/")
+
+
+class SynapStore(BaseStore):
+    """LangGraph cross-thread long-term memory store backed by Synap.
+
+    Example::
+
+        from langgraph.graph import StateGraph, START, END
+        from maximem_synap import MaximemSynapSDK
+        from synap_langgraph import SynapStore
+
+        sdk = MaximemSynapSDK(api_key="sk-...")
+        store = SynapStore(sdk, user_id="alice", customer_id="acme")
+
+        graph = StateGraph(MyState)
+        # ... add nodes / edges ...
+        app = graph.compile(store=store)
+    """
+
+    def __init__(
+        self,
+        sdk: MaximemSynapSDK,
+        user_id: str,
+        customer_id: str = "",
+        *,
+        mode: str = "accurate",
+    ) -> None:
+        if sdk is None:
+            raise ValueError("SynapStore requires a non-None sdk")
+        if not user_id:
+            raise ValueError("SynapStore requires a non-empty user_id")
+
+        super().__init__()
+        self.sdk = sdk
+        self.user_id = user_id
+        self.customer_id = customer_id
+        self.mode = mode
+        self._delete_warned = False
+        self._listns_warned = False
+
+    # ── abstract methods ────────────────────────────────────────────────────
+
+    async def abatch(self, ops: Iterable[Op]) -> list[Result]:
+        return [await self._dispatch(op) for op in ops]
+
+    def batch(self, ops: Iterable[Op]) -> list[Result]:
+        return run_async(self.abatch(list(ops)))
+
+    # ── dispatcher ──────────────────────────────────────────────────────────
+
+    async def _dispatch(self, op: Op) -> Result:
+        if isinstance(op, PutOp):
+            # value=None on PutOp signals delete (matches the base-class pattern)
+            if op.value is None:
+                return await self._adelete(op.namespace, op.key)
+            return await self._aput(op.namespace, op.key, op.value, op.index)
+        if isinstance(op, GetOp):
+            return await self._aget(op.namespace, op.key)
+        if isinstance(op, SearchOp):
+            return await self._asearch(
+                op.namespace_prefix, op.query, op.filter, op.limit, op.offset,
+            )
+        if isinstance(op, ListNamespacesOp):
+            return await self._alist_namespaces(op)
+        raise ValueError(f"SynapStore: unsupported op type {type(op).__name__}")
+
+    # ── op implementations ─────────────────────────────────────────────────
+
+    async def _aput(
+        self,
+        namespace: tuple[str, ...],
+        key: str,
+        value: dict[str, Any],
+        index: Any = None,
+    ) -> None:
+        ns = _ns_str(namespace)
+        document = json.dumps(value, default=str)
+        metadata = {
+            _MARKER: True,
+            _NS: ns,
+            _KEY: key,
+        }
+        async with wrap_sdk_errors_async(
+            "langgraph.store.put",
+            logger,
+            namespace=ns,
+            key=key,
+        ):
+            await self.sdk.memories.create(
+                document=document,
+                user_id=self.user_id,
+                customer_id=self.customer_id or None,
+                metadata=metadata,
+            )
+
+    async def _aget(
+        self,
+        namespace: tuple[str, ...],
+        key: str,
+    ) -> Optional[Item]:
+        ns = _ns_str(namespace)
+        try:
+            response = await self.sdk.fetch(
+                user_id=self.user_id,
+                customer_id=self.customer_id or None,
+                search_query=[f"{ns} {key}"],
+                max_results=50,
+                mode=self.mode,
+                include_conversation_context=False,
+            )
+        except Exception as exc:  # noqa: BLE001 — read-side degrades gracefully
+            logger.error(
+                "SynapStore.get: sdk.fetch failed namespace=%s key=%s error=%s",
+                ns, key, exc, exc_info=True,
+            )
+            return None
+
+        for fact in getattr(response, "facts", None) or []:
+            md = getattr(fact, "metadata", None) or {}
+            if md.get(_MARKER) and md.get(_NS) == ns and md.get(_KEY) == key:
+                return _fact_to_item(fact, namespace, key)
+        return None
+
+    async def _asearch(
+        self,
+        namespace_prefix: tuple[str, ...],
+        query: Optional[str],
+        filter_: Optional[dict[str, Any]],
+        limit: int,
+        offset: int,
+    ) -> list[SearchItem]:
+        q = query or _ns_str(namespace_prefix) or ""
+        try:
+            response = await self.sdk.fetch(
+                user_id=self.user_id,
+                customer_id=self.customer_id or None,
+                search_query=[q] if q else None,
+                max_results=max(limit + offset, 10),
+                mode=self.mode,
+                include_conversation_context=False,
+            )
+        except Exception as exc:  # noqa: BLE001 — read-side degrades gracefully
+            logger.error(
+                "SynapStore.search: sdk.fetch failed namespace_prefix=%s query=%s error=%s",
+                _ns_str(namespace_prefix), query, exc, exc_info=True,
+            )
+            return []
+
+        matches: list[SearchItem] = []
+        for fact in getattr(response, "facts", None) or []:
+            md = getattr(fact, "metadata", None) or {}
+            if not md.get(_MARKER):
+                continue
+            item_ns_str = md.get(_NS) or ""
+            if not _matches_namespace_prefix(item_ns_str, namespace_prefix):
+                continue
+            if filter_ and not _filter_matches(md, filter_):
+                continue
+            item_ns = tuple(item_ns_str.split("/")) if item_ns_str else ()
+            key = md.get(_KEY) or str(fact.id)
+            matches.append(_fact_to_search_item(fact, item_ns, key))
+
+        return matches[offset : offset + limit]
+
+    async def _adelete(
+        self,
+        namespace: tuple[str, ...],
+        key: str,
+    ) -> None:
+        if not self._delete_warned:
+            logger.warning(
+                "SynapStore.delete: Synap has no public delete API. Delete/update "
+                "operations are no-ops; data is write-only. This warning fires once."
+            )
+            self._delete_warned = True
+
+    async def _alist_namespaces(self, op: ListNamespacesOp) -> list[tuple[str, ...]]:
+        if not self._listns_warned:
+            logger.warning(
+                "SynapStore.list_namespaces: Synap does not expose a namespace "
+                "enumeration API; returning []. This warning fires once."
+            )
+            self._listns_warned = True
+        return []
+
+
+# ── helpers ────────────────────────────────────────────────────────────────
+
+
+def _fact_to_item(fact: Any, namespace: tuple[str, ...], key: str) -> Item:
+    value = _parse_value(getattr(fact, "content", "") or "")
+    now = _as_datetime(getattr(fact, "extracted_at", None))
+    return Item(
+        value=value,
+        key=key,
+        namespace=namespace,
+        created_at=now,
+        updated_at=now,
+    )
+
+
+def _fact_to_search_item(
+    fact: Any,
+    namespace: tuple[str, ...],
+    key: str,
+) -> SearchItem:
+    value = _parse_value(getattr(fact, "content", "") or "")
+    now = _as_datetime(getattr(fact, "extracted_at", None))
+    score = getattr(fact, "confidence", None)
+    return SearchItem(
+        namespace=namespace,
+        key=key,
+        value=value,
+        created_at=now,
+        updated_at=now,
+        score=float(score) if isinstance(score, (int, float)) else None,
+    )
+
+
+def _parse_value(document: str) -> dict[str, Any]:
+    if not document:
+        return {}
+    try:
+        parsed = json.loads(document)
+    except (ValueError, TypeError):
+        return {"_raw": document}
+    if isinstance(parsed, dict):
+        return parsed
+    return {"_value": parsed}
+
+
+def _as_datetime(value: Any) -> datetime:
+    if isinstance(value, datetime):
+        return value
+    return datetime.now(timezone.utc)
+
+
+# Silence the unused-import complaint — SynapIntegrationError is re-exported
+# via wrap_sdk_errors_async raising it. Keep the symbol visible for typing.
+_ = SynapIntegrationError