zizkadb-langgraph 0.1.0__tar.gz

zizkadb_langgraph-0.1.0/.gitignore

@@ -0,0 +1,67 @@
+# Environment
+.env
+*.env
+.env.local
+*.env.local
+.env.staging
+infra/.env.staging
+
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+.venv/
+venv/
+env/
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+
+# Node
+node_modules/
+.next/
+.turbo/
+*.tsbuildinfo
+*.log
+
+# macOS
+.DS_Store
+# iCloud duplicate filenames (e.g. "file 2.py")
+* 2.*
+* 2/
+
+# Docker volumes
+postgres_data/
+qdrant_data/
+redis_data/
+
+# IDE
+.idea/
+.vscode/
+.cursor/mcp.json
+.mcp.json
+*.swp
+
+# Postgres backups (created by infra/backup-postgres.sh)
+infra/backups/
+
+# Local native stack (Qdrant binary, storage)
+.local/
+
+# Qdrant data when started from repo root by mistake
+storage/
+.qdrant-initialized
+
+# Extra local venvs / caches
+.venv-phase0/
+.venv-ci/
+.ruff_cache/
+core/.venv/
+
+# Profiling artifacts
+*.profraw
+default.profraw
+
+# Agents
+.agents/

zizkadb_langgraph-0.1.0/PKG-INFO

@@ -0,0 +1,34 @@
+Metadata-Version: 2.5
+Name: zizkadb-langgraph
+Version: 0.1.0
+Summary: LangGraph middleware for ZizkaDB — automatic causal logging per graph node
+License: AGPL-3.0-or-later
+Requires-Python: >=3.10
+Requires-Dist: zizkadb-sdk>=0.3.0
+Provides-Extra: langgraph
+Requires-Dist: langgraph>=0.2.0; extra == 'langgraph'
+Description-Content-Type: text/markdown
+
+# zizkadb-langgraph
+
+LangGraph middleware for [ZizkaDB](https://db.zizka.ai) — logs `graph_node` / `graph_node_done` with automatic `parent_id` via graph state.
+
+```bash
+pip install zizkadb-langgraph
+```
+
+```python
+from zizkadb import ZizkaDB
+from zizkadb_langgraph import ZizkaDBLangGraphMiddleware, wrap_node
+
+async with ZizkaDB(host="http://localhost:8000") as db:
+    async with db.track(agent="research-bot") as ctx:
+        mw = ZizkaDBLangGraphMiddleware(db, agent="research-bot", session_id=ctx.session_id)
+
+        async def retrieve(state):
+            return {"docs": ["a", "b"]}
+
+        graph.add_node("retrieve", wrap_node(mw, "retrieve", retrieve))
+```
+
+See `examples/golden-path/langgraph-rag-bot/` for the full RAG support-bot reference.

zizkadb_langgraph-0.1.0/README.md

@@ -0,0 +1,23 @@
+# zizkadb-langgraph
+
+LangGraph middleware for [ZizkaDB](https://db.zizka.ai) — logs `graph_node` / `graph_node_done` with automatic `parent_id` via graph state.
+
+```bash
+pip install zizkadb-langgraph
+```
+
+```python
+from zizkadb import ZizkaDB
+from zizkadb_langgraph import ZizkaDBLangGraphMiddleware, wrap_node
+
+async with ZizkaDB(host="http://localhost:8000") as db:
+    async with db.track(agent="research-bot") as ctx:
+        mw = ZizkaDBLangGraphMiddleware(db, agent="research-bot", session_id=ctx.session_id)
+
+        async def retrieve(state):
+            return {"docs": ["a", "b"]}
+
+        graph.add_node("retrieve", wrap_node(mw, "retrieve", retrieve))
+```
+
+See `examples/golden-path/langgraph-rag-bot/` for the full RAG support-bot reference.

zizkadb_langgraph-0.1.0/pyproject.toml

@@ -0,0 +1,23 @@
+[project]
+name = "zizkadb-langgraph"
+version = "0.1.0"
+description = "LangGraph middleware for ZizkaDB — automatic causal logging per graph node"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "AGPL-3.0-or-later" }
+dependencies = [
+    "zizkadb-sdk>=0.3.0",
+]
+
+[project.optional-dependencies]
+langgraph = ["langgraph>=0.2.0"]
+
+[project.entry-points."zizkadb.integrations"]
+langgraph = "zizkadb_langgraph.middleware"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["zizkadb_langgraph"]

zizkadb_langgraph-0.1.0/tests/test_middleware.py

@@ -0,0 +1,41 @@
+"""LangGraph middleware keeps graph state lineage in sync."""
+
+from __future__ import annotations
+
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+from zizkadb_langgraph.middleware import STATE_LAST_EVENT_KEY, ZizkaDBLangGraphMiddleware, wrap_node
+
+
+def _make_db() -> MagicMock:
+    counter = iter(range(1, 100))
+    db = MagicMock()
+
+    async def _log(**kwargs):
+        result = MagicMock()
+        result.event_id = f"evt-{next(counter)}"
+        return result
+
+    db.log = AsyncMock(side_effect=_log)
+    return db
+
+
+@pytest.mark.asyncio
+async def test_wrap_node_updates_caller_state_after_done():
+    db = _make_db()
+    mw = ZizkaDBLangGraphMiddleware(db, agent="bot", session_id="sess-1")
+    state = {STATE_LAST_EVENT_KEY: "evt-root"}
+
+    async def node(state: dict) -> dict:
+        return {"docs": [1]}
+
+    wrapped = wrap_node(mw, "retrieve", node)
+    await wrapped(state)
+
+    assert state[STATE_LAST_EVENT_KEY] == "evt-2"
+    calls = db.log.call_args_list
+    assert len(calls) == 2
+    assert calls[0].kwargs["parent_id"] == "evt-root"
+    assert calls[1].kwargs["parent_id"] == "evt-1"

zizkadb_langgraph-0.1.0/zizkadb_langgraph/__init__.py

@@ -0,0 +1,5 @@
+"""LangGraph integration for ZizkaDB."""
+
+from zizkadb_langgraph.middleware import ZizkaDBLangGraphMiddleware, wrap_node
+
+__all__ = ["ZizkaDBLangGraphMiddleware", "wrap_node"]

zizkadb_langgraph-0.1.0/zizkadb_langgraph/middleware.py

@@ -0,0 +1,78 @@
+"""LangGraph node wrapper — logs graph_node events with automatic parent_id."""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Awaitable
+
+from zizkadb import ZizkaDB
+
+STATE_LAST_EVENT_KEY = "zizkadb_last_event_id"
+
+
+class ZizkaDBLangGraphMiddleware:
+    """Attach to a LangGraph state dict key for cross-node lineage."""
+
+    def __init__(self, db: ZizkaDB, agent: str, session_id: str | None = None) -> None:
+        self.db = db
+        self.agent = agent
+        self.session_id = session_id
+
+    async def log_node(
+        self,
+        state: dict[str, Any],
+        node_name: str,
+        *,
+        input_summary: dict[str, Any] | None = None,
+        output_summary: dict[str, Any] | None = None,
+        phase: str = "enter",
+    ) -> None:
+        parent_id = state.get(STATE_LAST_EVENT_KEY)
+        event = "graph_node" if phase == "enter" else "graph_node_done"
+        data: dict[str, Any] = {"node": node_name, "phase": phase}
+        if input_summary:
+            data["input"] = input_summary
+        if output_summary:
+            data["output"] = output_summary
+        result = await self.db.log(
+            agent=self.agent,
+            event=event,
+            data=data,
+            parent_id=parent_id,
+            session_id=self.session_id or state.get("session_id"),
+        )
+        state[STATE_LAST_EVENT_KEY] = result.event_id
+
+
+def wrap_node(
+    middleware: ZizkaDBLangGraphMiddleware,
+    node_name: str,
+    fn: Callable[..., Awaitable[dict[str, Any]]],
+) -> Callable[..., Awaitable[dict[str, Any]]]:
+    """Wrap an async LangGraph node to log enter/exit with causal links."""
+
+    async def wrapped(state: dict[str, Any], *args: Any, **kwargs: Any) -> dict[str, Any]:
+        await middleware.log_node(
+            state,
+            node_name,
+            input_summary={"keys": list(state.keys())[:20]},
+            phase="enter",
+        )
+        out = await fn(state, *args, **kwargs)
+        if isinstance(out, dict):
+            merged = {**state, **out}
+        else:
+            merged = dict(state)
+        await middleware.log_node(
+            merged,
+            node_name,
+            output_summary={"keys": list(merged.keys())[:20]},
+            phase="done",
+        )
+        # Propagate the done-phase event id back to the caller's state dict.
+        # log_node updates `merged` (a copy), so without this the next node reads
+        # a stale zizkadb_last_event_id and forks the causal chain.
+        state[STATE_LAST_EVENT_KEY] = merged[STATE_LAST_EVENT_KEY]
+        return out if isinstance(out, dict) else state
+
+    wrapped.__name__ = getattr(fn, "__name__", node_name)
+    return wrapped