Merge pull request #9 from nikhilvdev/feat/langgraph-adapter

Add LangGraph adapter, tests, and bump to 0.5.0

Author: nikhilvdev

CHANGELOG.md

@@ -4,6 +4,25 @@ All notable changes to this project are documented in this file.
 
 ## Unreleased
 
+## 0.5.0 - 2026-09-01
+
+- `LangGraphAdapter` (`pip install logquill[langgraph]`) — corrects an
+  overstatement in the 0.4.0 entry below: LangGraph nodes run as ordinary
+  LangChain `Runnable`s, so `LangChainAdapter` alone already captures node
+  execution, but LangGraph also has its own checkpoint lifecycle —
+  `on_interrupt`/`on_resume`, fired when a graph pauses on an `interrupt()`
+  call (e.g. for human review) and later resumes from a persisted
+  checkpoint — that LangGraph dispatches only to handlers that are
+  instances of its own `GraphCallbackHandler`; a plain `BaseCallbackHandler`
+  subclass (all `LangChainAdapter` is) never receives them. `LangGraphAdapter`
+  is `LangChainAdapter` plus those two, mapped to `.observation
+  ("graph_interrupted", ...)`/`.action("graph_resumed", ...)` carrying
+  `checkpoint_id`/`status`/`checkpoint_ns`/pending `Interrupt` payloads, with
+  the event's own `run_id` as `parent_span_id`. `pip install
+  logquill[langgraph]` pulls in a compatible `langchain-core` transitively;
+  `langgraph` is never imported unless `logquill.adapters.langgraph` is
+  imported explicitly.
+
 ## 0.4.0 - 2026-09-01
 
 - Closed three gaps found auditing Phases 1–3 against their own written

README.md

@@ -26,7 +26,7 @@ for what's landed so far.
 - **Pluggable formatters** — `JSONFormatter` out of the box; implement `format(record) -> str` for your own
 - **Config from file/env** — `load_config(dict)`, `logger_from_file(path)` (JSON/YAML), `logger_from_env()` build a `Logger` from one config shape — see [Config](#config)
 - **Plugin pipeline** — `ContextPlugin`, `RedactPlugin` (by key), `PIIRedactPlugin` (by pattern), `SamplingPlugin` (with tail-based elevation), `TamperEvidentPlugin` (hash-chained logs), `TraceContextPlugin` (cross-service trace correlation), and `AlertingPlugin` (`SlackAlertPlugin`/`PagerDutyAlertPlugin`/`EmailAlertPlugin`, deduplicated) out of the box; a broken plugin can't crash logging; `.use()` also accepts a plain function, no subclassing required (see [Plugins](#plugins))
-- **Agentic & harness tracing** — `.child()` loggers, `RunPlugin`, `.thought()/.action()/.observation()/.decision()`, `with agent_log.span(...)`, and framework adapters — `LangChainAdapter` (`pip install logquill[langchain]`, covers LangGraph for free), `CrewAIAdapter` (`pip install logquill[crewai]`), `LlamaIndexAdapter` (`pip install logquill[llamaindex]`), and `AutoGenAdapter` (`pip install logquill[autogen]`) — see [Agentic & harness tracing](#agentic--harness-tracing)
+- **Agentic & harness tracing** — `.child()` loggers, `RunPlugin`, `.thought()/.action()/.observation()/.decision()`, `with agent_log.span(...)`, and framework adapters — `LangChainAdapter` (`pip install logquill[langchain]`), `LangGraphAdapter` (`pip install logquill[langgraph]`, adds checkpoint interrupt/resume events on top), `CrewAIAdapter` (`pip install logquill[crewai]`), `LlamaIndexAdapter` (`pip install logquill[llamaindex]`), and `AutoGenAdapter` (`pip install logquill[autogen]`) — see [Agentic & harness tracing](#agentic--harness-tracing)
 - **Zero required runtime dependencies** — stdlib only; `aiohttp` is opt-in, for async HTTP
 - **Typed throughout** — `mypy --strict` clean on the public API
 - *(planned)* non-blocking async dispatch, `contextvars`-based context propagation — see `CHANGELOG.md`
@@ -554,8 +554,10 @@ assert record["meta"]["trace_id"] == "4bf92f3577b34da6a3ce929d0e0e4736"
 `LogQuillAdapter` is a thin base class for mapping a framework's own event
 callbacks onto `.thought()/.action()/.observation()/.decision()` and
 `.span()` — never a reimplementation of tracing logic per framework.
-`LangChainAdapter` (covers LangGraph for free, since it shares LangChain's
-callback system) ships behind the optional `langchain` extra:
+`LangChainAdapter` ships behind the optional `langchain` extra. LangGraph
+nodes run as ordinary LangChain `Runnable`s, so it already captures node
+execution with zero extra work — for LangGraph's own checkpoint
+interrupt/resume events too, see [LangGraph](#langgraph) below:
 
 ```bash
 pip install logquill[langchain]
@@ -575,6 +577,43 @@ LangChain's own `run_id`/`parent_run_id` are written directly onto
 field renaming, not translation. `langchain-core` is never imported unless
 you import `logquill.adapters.langchain` yourself.
 
+### LangGraph
+
+LangGraph nodes execute as ordinary LangChain `Runnable`s, so
+`LangChainAdapter` alone already covers everything that happens *inside* a
+node — `on_chain_start`/`on_llm_start`/`on_tool_start`/etc. all fire exactly
+as they would for a plain chain. What a plain `BaseCallbackHandler` can't
+see is LangGraph's own checkpoint lifecycle: `on_interrupt`/`on_resume`,
+fired when a graph pauses on an `interrupt()` call (e.g. for human review)
+and later resumes from a persisted checkpoint — LangGraph dispatches those
+two specifically to handlers that are instances of its own
+`GraphCallbackHandler`, which a plain `BaseCallbackHandler` subclass never
+receives. `LangGraphAdapter` is `LangChainAdapter` plus those two:
+
+```bash
+pip install logquill[langgraph]
+```
+
+```python
+from logquill import Logger, RunPlugin
+from logquill.adapters.langgraph import LangGraphAdapter
+
+log = Logger("app")
+handler = LangGraphAdapter(log.child("agent").use(RunPlugin()))
+graph = builder.compile(checkpointer=checkpointer)
+graph.invoke(input, config={"callbacks": [handler], "configurable": {"thread_id": "1"}})
+```
+
+`on_interrupt` becomes `.observation("graph_interrupted", ...)` carrying
+`checkpoint_id`, `status`, `checkpoint_ns` (the subgraph namespace path, if
+nested), and each pending `Interrupt`'s `id`/`value`; `on_resume` becomes
+`.action("graph_resumed", ...)` with the same checkpoint fields. Both use
+the event's own `run_id` as `parent_span_id`, matching the enclosing
+graph's still-open chain span — the graph hasn't ended, just paused.
+`pip install logquill[langgraph]` pulls in a compatible `langchain-core`
+transitively, so installing it alone is enough; `langgraph` is never
+imported unless you import `logquill.adapters.langgraph` yourself.
+
 `CrewAIAdapter` ships behind the optional `crewai` extra, listening on
 CrewAI's own event bus rather than a single callback handler:
 

logquill/__init__.py

@@ -41,7 +41,7 @@
 from logquill.transports.sql.sqlite_transport import SQLiteTransport
 from logquill.transports.transport import CollectingTransport, Transport
 
-__version__ = "0.4.0"
+__version__ = "0.5.0"
 
 __all__ = [
     "AlertingPlugin",

logquill/adapters/langgraph.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+from typing import Any
+
+try:
+    from langgraph.callbacks import GraphCallbackHandler  # type: ignore[import-not-found]
+except ImportError as exc:
+    raise ImportError(
+        "logquill.adapters.langgraph requires the optional `langgraph` "
+        "dependency — install with `pip install logquill[langgraph]`."
+    ) from exc
+
+from logquill.adapters.langchain import LangChainAdapter
+
+
+def _checkpoint_meta(event: Any) -> dict[str, Any]:
+    meta: dict[str, Any] = {"checkpoint_id": event.checkpoint_id, "status": event.status}
+    if event.checkpoint_ns:
+        meta["checkpoint_ns"] = list(event.checkpoint_ns)
+    if event.run_id is not None:
+        meta["parent_span_id"] = str(event.run_id)
+    return meta
+
+
+# `type: ignore[misc]` — same reason as every other adapter here:
+# `GraphCallbackHandler` types as `Any` whenever `langgraph` isn't installed
+# (optional, never in `dev` — see pyproject.toml), and mypy refuses to let a
+# class subclass something typed `Any`.
+class LangGraphAdapter(LangChainAdapter, GraphCallbackHandler):  # type: ignore[misc]
+    """`LangChainAdapter` plus LangGraph's own checkpoint pause/resume events.
+
+    `LangChainAdapter` alone already covers everything that happens *inside*
+    a LangGraph node — nodes execute as ordinary LangChain `Runnable`s, so
+    `on_chain_start`/`on_llm_start`/`on_tool_start`/etc. all fire exactly as
+    they would for a plain chain. What a plain `BaseCallbackHandler` cannot
+    see is LangGraph's own checkpoint lifecycle: `on_interrupt`/`on_resume`,
+    fired when a graph pauses on an `interrupt()` call (e.g. for human
+    review) and later resumes from a persisted checkpoint. LangGraph
+    dispatches those two specifically to handlers that are instances of its
+    own `GraphCallbackHandler` — a plain `BaseCallbackHandler` subclass
+    (which is all `LangChainAdapter` is) never receives them, silently. This
+    class exists for that reason alone; everything else is inherited
+    unchanged from `LangChainAdapter`.
+
+        from logquill import Logger, RunPlugin
+        from logquill.adapters.langgraph import LangGraphAdapter
+
+        log = Logger("app")
+        handler = LangGraphAdapter(log.child("agent").use(RunPlugin()))
+        graph = builder.compile(checkpointer=checkpointer)
+        graph.invoke(input, config={"callbacks": [handler], "configurable": {"thread_id": "1"}})
+
+    `on_interrupt` becomes `.observation("graph_interrupted", ...)` carrying
+    `checkpoint_id`, `status`, `checkpoint_ns` (the subgraph namespace path,
+    if nested), and each pending `Interrupt`'s `id`/`value`; `on_resume`
+    becomes `.action("graph_resumed", ...)` with the same checkpoint fields.
+    Both use `event.run_id` as `parent_span_id`, matching the enclosing
+    graph's own chain span from `LangChainAdapter.on_chain_start` — the
+    graph hasn't ended, just paused, so its span is still open.
+
+    `pip install logquill[langgraph]` — pulls in a compatible `langchain-core`
+    transitively, so installing this extra alone is enough; `langgraph` is
+    never imported unless you import `logquill.adapters.langgraph` yourself.
+    """
+
+    def on_interrupt(self, event: Any) -> None:
+        meta = _checkpoint_meta(event)
+        meta["interrupts"] = [{"id": i.id, "value": i.value} for i in event.interrupts]
+        self.log.observation("graph_interrupted", **meta)
+
+    def on_resume(self, event: Any) -> None:
+        self.log.action("graph_resumed", **_checkpoint_meta(event))

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "logquill"
-version = "0.4.0"
+version = "0.5.0"
 description = "A structured, leveled logging framework with pluggable transports and a plugin pipeline."
 readme = "README.md"
 license = "MIT"
@@ -51,6 +51,7 @@ aws = ["boto3>=1.34"]
 presidio = ["presidio-analyzer>=2.2", "presidio-anonymizer>=2.2"]
 crypto = ["cryptography>=41"]
 langchain = ["langchain-core>=0.3"]
+langgraph = ["langgraph>=1.0"]
 crewai = ["crewai>=1.0"]
 llamaindex = ["llama-index-core>=0.12"]
 autogen = ["autogen-core>=0.6"]