Support langgraph checkpointer (#1005)

* Add checkpointer configuration to config.example.yaml

- Introduced a new section for checkpointer configuration to enable state persistence for the embedded DeerFlowClient.
- Documented supported types: memory, sqlite, and postgres, along with examples for each.
- Clarified that the LangGraph Server manages its own state persistence separately.

* refactor(checkpointer): streamline checkpointer initialization and logging

* fix(uv.lock): update revision and add new wheel URLs for brotlicffi package

* feat: add langchain-anthropic dependency and update related configurations

* Fix checkpointer lifecycle, docstring, and path resolution bugs from PR #1005 review (#4)

* Initial plan

* Address all review suggestions from PR #1005

Co-authored-by: foreleven <4785594+foreleven@users.noreply.github.com>

* Fix resolve_path to always return real Path; move SQLite special-string handling to callers

Co-authored-by: foreleven <4785594+foreleven@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: foreleven <4785594+foreleven@users.noreply.github.com>

---------

Co-authored-by: Copilot <198982749+Copilot@users.noreply.github.com>
Co-authored-by: foreleven <4785594+foreleven@users.noreply.github.com>

backend/src/agents/__init__.py

@@ -1,4 +1,5 @@
+from .checkpointer import get_checkpointer, make_checkpointer, reset_checkpointer
 from .lead_agent import make_lead_agent
 from .thread_state import SandboxState, ThreadState
 
-__all__ = ["make_lead_agent", "SandboxState", "ThreadState"]
+__all__ = ["make_lead_agent", "SandboxState", "ThreadState", "get_checkpointer", "reset_checkpointer", "make_checkpointer"]

backend/src/agents/checkpointer/__init__.py

@@ -0,0 +1,9 @@
+from .async_provider import make_checkpointer
+from .provider import checkpointer_context, get_checkpointer, reset_checkpointer
+
+__all__ = [
+    "get_checkpointer",
+    "reset_checkpointer",
+    "checkpointer_context",
+    "make_checkpointer",
+]

backend/src/agents/checkpointer/async_provider.py

@@ -0,0 +1,107 @@
+"""Async checkpointer factory.
+
+Provides an **async context manager** for long-running async servers that need
+proper resource cleanup.
+
+Supported backends: memory, sqlite, postgres.
+
+Usage (e.g. FastAPI lifespan)::
+
+    from src.agents.checkpointer.async_provider import make_checkpointer
+
+    async with make_checkpointer() as checkpointer:
+        app.state.checkpointer = checkpointer  # None if not configured
+
+For sync usage see :mod:`src.agents.checkpointer.provider`.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import logging
+from collections.abc import AsyncIterator
+
+from langgraph.types import Checkpointer
+
+from src.agents.checkpointer.provider import (
+    POSTGRES_CONN_REQUIRED,
+    POSTGRES_INSTALL,
+    SQLITE_INSTALL,
+    _resolve_sqlite_conn_str,
+)
+from src.config.app_config import get_app_config
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Async factory
+# ---------------------------------------------------------------------------
+
+
+@contextlib.asynccontextmanager
+async def _async_checkpointer(config) -> AsyncIterator[Checkpointer]:
+    """Async context manager that constructs and tears down a checkpointer."""
+    if config.type == "memory":
+        from langgraph.checkpoint.memory import InMemorySaver
+
+        yield InMemorySaver()
+        return
+
+    if config.type == "sqlite":
+        try:
+            from langgraph.checkpoint.sqlite.aio import AsyncSqliteSaver
+        except ImportError as exc:
+            raise ImportError(SQLITE_INSTALL) from exc
+
+        import pathlib
+
+        conn_str = _resolve_sqlite_conn_str(config.connection_string or "store.db")
+        # Only create parent directories for real filesystem paths
+        if conn_str != ":memory:" and not conn_str.startswith("file:"):
+            pathlib.Path(conn_str).parent.mkdir(parents=True, exist_ok=True)
+        async with AsyncSqliteSaver.from_conn_string(conn_str) as saver:
+            await saver.setup()
+            yield saver
+        return
+
+    if config.type == "postgres":
+        try:
+            from langgraph.checkpoint.postgres.aio import AsyncPostgresSaver
+        except ImportError as exc:
+            raise ImportError(POSTGRES_INSTALL) from exc
+
+        if not config.connection_string:
+            raise ValueError(POSTGRES_CONN_REQUIRED)
+
+        async with AsyncPostgresSaver.from_conn_string(config.connection_string) as saver:
+            await saver.setup()
+            yield saver
+        return
+
+    raise ValueError(f"Unknown checkpointer type: {config.type!r}")
+
+
+# ---------------------------------------------------------------------------
+# Public async context manager
+# ---------------------------------------------------------------------------
+
+
+@contextlib.asynccontextmanager
+async def make_checkpointer() -> AsyncIterator[Checkpointer | None]:
+    """Async context manager that yields a checkpointer for the caller's lifetime.
+    Resources are opened on enter and closed on exit — no global state::
+
+        async with make_checkpointer() as checkpointer:
+            app.state.checkpointer = checkpointer
+
+    Yields ``None`` when no checkpointer is configured in *config.yaml*.
+    """
+
+    config = get_app_config()
+
+    if config.checkpointer is None:
+        yield None
+        return
+
+    async with _async_checkpointer(config.checkpointer) as saver:
+        yield saver

backend/src/agents/checkpointer/provider.py

@@ -0,0 +1,179 @@
+"""Sync checkpointer factory.
+
+Provides a **sync singleton** and a **sync context manager** for LangGraph
+graph compilation and CLI tools.
+
+Supported backends: memory, sqlite, postgres.
+
+Usage::
+
+    from src.agents.checkpointer.provider import get_checkpointer, checkpointer_context
+
+    # Singleton — reused across calls, closed on process exit
+    cp = get_checkpointer()
+
+    # One-shot — fresh connection, closed on block exit
+    with checkpointer_context() as cp:
+        graph.invoke(input, config={"configurable": {"thread_id": "1"}})
+"""
+
+from __future__ import annotations
+
+import contextlib
+import logging
+from collections.abc import Iterator
+
+from langgraph.types import Checkpointer
+
+from src.config.app_config import get_app_config
+from src.config.checkpointer_config import CheckpointerConfig
+from src.config.paths import resolve_path
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Error message constants — imported by aio.provider too
+# ---------------------------------------------------------------------------
+
+SQLITE_INSTALL = "langgraph-checkpoint-sqlite is required for the SQLite checkpointer. Install it with: uv add langgraph-checkpoint-sqlite"
+POSTGRES_INSTALL = "langgraph-checkpoint-postgres is required for the PostgreSQL checkpointer. Install it with: uv add langgraph-checkpoint-postgres psycopg[binary] psycopg-pool"
+POSTGRES_CONN_REQUIRED = "checkpointer.connection_string is required for the postgres backend"
+
+# ---------------------------------------------------------------------------
+# Sync factory
+# ---------------------------------------------------------------------------
+
+
+def _resolve_sqlite_conn_str(raw: str) -> str:
+    """Return a SQLite connection string ready for use with ``SqliteSaver``.
+
+    SQLite special strings (``":memory:"`` and ``file:`` URIs) are returned
+    unchanged.  Plain filesystem paths — relative or absolute — are resolved
+    to an absolute string via :func:`resolve_path`.
+    """
+    if raw == ":memory:" or raw.startswith("file:"):
+        return raw
+    return str(resolve_path(raw))
+
+
+@contextlib.contextmanager
+def _sync_checkpointer_cm(config: CheckpointerConfig) -> Iterator[Checkpointer]:
+    """Context manager that creates and tears down a sync checkpointer.
+
+    Returns a configured ``Checkpointer`` instance. Resource cleanup for any
+    underlying connections or pools is handled by higher-level helpers in
+    this module (such as the singleton factory or context manager); this
+    function does not return a separate cleanup callback.
+    """
+    if config.type == "memory":
+        from langgraph.checkpoint.memory import InMemorySaver
+
+        logger.info("Checkpointer: using InMemorySaver (in-process, not persistent)")
+        yield InMemorySaver()
+        return
+
+    if config.type == "sqlite":
+        try:
+            from langgraph.checkpoint.sqlite import SqliteSaver
+        except ImportError as exc:
+            raise ImportError(SQLITE_INSTALL) from exc
+
+        conn_str = _resolve_sqlite_conn_str(config.connection_string or "store.db")
+        with SqliteSaver.from_conn_string(conn_str) as saver:
+            saver.setup()
+            logger.info("Checkpointer: using SqliteSaver (%s)", conn_str)
+            yield saver
+        return
+
+    if config.type == "postgres":
+        try:
+            from langgraph.checkpoint.postgres import PostgresSaver
+        except ImportError as exc:
+            raise ImportError(POSTGRES_INSTALL) from exc
+
+        if not config.connection_string:
+            raise ValueError(POSTGRES_CONN_REQUIRED)
+
+        with PostgresSaver.from_conn_string(config.connection_string) as saver:
+            saver.setup()
+            logger.info("Checkpointer: using PostgresSaver")
+            yield saver
+        return
+
+    raise ValueError(f"Unknown checkpointer type: {config.type!r}")
+
+
+# ---------------------------------------------------------------------------
+# Sync singleton
+# ---------------------------------------------------------------------------
+
+_checkpointer: Checkpointer = None
+_checkpointer_ctx = None  # open context manager keeping the connection alive
+
+
+def get_checkpointer() -> Checkpointer | None:
+    """Return the global sync checkpointer singleton, creating it on first call.
+
+    Returns ``None`` when no checkpointer is configured in *config.yaml*.
+
+    Raises:
+        ImportError: If the required package for the configured backend is not installed.
+        ValueError: If ``connection_string`` is missing for a backend that requires it.
+    """
+    global _checkpointer, _checkpointer_ctx
+
+    if _checkpointer is not None:
+        return _checkpointer
+
+    from src.config.checkpointer_config import get_checkpointer_config
+
+    config = get_checkpointer_config()
+    if config is None:
+        return None
+
+    _checkpointer_ctx = _sync_checkpointer_cm(config)
+    _checkpointer = _checkpointer_ctx.__enter__()
+
+    return _checkpointer
+
+
+def reset_checkpointer() -> None:
+    """Reset the sync singleton, forcing recreation on the next call.
+
+    Closes any open backend connections and clears the cached instance.
+    Useful in tests or after a configuration change.
+    """
+    global _checkpointer, _checkpointer_ctx
+    if _checkpointer_ctx is not None:
+        try:
+            _checkpointer_ctx.__exit__(None, None, None)
+        except Exception:
+            logger.warning("Error during checkpointer cleanup", exc_info=True)
+        _checkpointer_ctx = None
+    _checkpointer = None
+
+
+# ---------------------------------------------------------------------------
+# Sync context manager
+# ---------------------------------------------------------------------------
+
+
+@contextlib.contextmanager
+def checkpointer_context() -> Iterator[Checkpointer | None]:
+    """Sync context manager that yields a checkpointer and cleans up on exit.
+
+    Unlike :func:`get_checkpointer`, this does **not** cache the instance —
+    each ``with`` block creates and destroys its own connection.  Use it in
+    CLI scripts or tests where you want deterministic cleanup::
+
+        with checkpointer_context() as cp:
+            graph.invoke(input, config={"configurable": {"thread_id": "1"}})
+    """
+
+    config = get_app_config()
+    if config.checkpointer is None:
+        yield None
+        return
+
+    with _sync_checkpointer_cm(config.checkpointer) as saver:
+        yield saver