primust-langgraph 1.0.0__tar.gz

primust_langgraph-1.0.0/.gitignore

@@ -0,0 +1,22 @@
+node_modules/
+dist/
+.next/
+__pycache__/
+*.egg-info/
+.venv/
+.env
+.env.local
+.env.*.local
+*.pyc
+.turbo/
+*.pem
+*.key
+.DS_Store
+.claude/
+.claude.json
+.claude.json.backup
+.pytest_cache/
+*.db
+*.db-shm
+*.db-wal
+.vercel

primust_langgraph-1.0.0/PKG-INFO

@@ -0,0 +1,19 @@
+Metadata-Version: 2.4
+Name: primust-langgraph
+Version: 1.0.0
+Summary: Primust governance adapter for LangGraph
+Project-URL: Homepage, https://primust.com
+Project-URL: Documentation, https://docs.primust.com/adapters/langgraph
+Author-email: "Primust, Inc." <eng@primust.com>
+License-Expression: LicenseRef-Proprietary
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Requires-Dist: langgraph>=0.2.0
+Requires-Dist: primust>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'

primust_langgraph-1.0.0/README.md

@@ -0,0 +1,33 @@
+# primust-langgraph
+
+Primust governance adapter for [LangGraph](https://github.com/langchain-ai/langgraph).
+
+```bash
+pip install primust-langgraph
+```
+
+## Quickstart
+
+```python
+import primust
+from primust_langgraph import PrimustLangGraph
+
+p = primust.Pipeline(api_key="pk_live_...", workflow_id="my-agent")
+adapter = PrimustLangGraph(pipeline=p)
+
+# Wrap your LangGraph compiled graph
+instrumented = adapter.instrument(compiled_graph)
+result = instrumented.invoke({"input": "..."})
+```
+
+## What it does
+
+Automatically records governance checks at LangGraph node boundaries. Each node execution produces a commitment hash — raw content never leaves your environment.
+
+## Docs
+
+[docs.primust.com/adapters/langgraph](https://docs.primust.com/adapters/langgraph)
+
+## License
+
+Proprietary — see LICENSE file.

primust_langgraph-1.0.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "primust-langgraph"
+version = "1.0.0"
+description = "Primust governance adapter for LangGraph"
+requires-python = ">=3.11"
+license = "LicenseRef-Proprietary"
+authors = [{ name = "Primust, Inc.", email = "eng@primust.com" }]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+  "primust>=1.0.0",
+  "langgraph>=0.2.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0",
+]
+
+[project.urls]
+Homepage = "https://primust.com"
+Documentation = "https://docs.primust.com/adapters/langgraph"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/primust_langgraph"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

primust_langgraph-1.0.0/src/primust_langgraph/__init__.py

@@ -0,0 +1,5 @@
+"""Primust governance adapter for LangGraph."""
+
+from primust_langgraph.adapter import PrimustLangGraph
+
+__all__ = ["PrimustLangGraph"]

primust_langgraph-1.0.0/src/primust_langgraph/adapter.py

@@ -0,0 +1,162 @@
+"""
+Primust LangGraph adapter — instruments tool calls and node transitions.
+
+Privacy invariant: raw tool input/output NEVER leaves the customer environment.
+Only commitment hashes (poseidon2) transit to the Primust API.
+
+Surface declaration:
+  surface_type: in_process_adapter
+  observation_mode: post_action_realtime
+  scope_type: full_workflow
+  proof_ceiling: execution (mathematical for deterministic tools)
+"""
+
+from __future__ import annotations
+
+import functools
+import logging
+from typing import Any, Callable
+
+from primust import Pipeline, CheckSession
+
+logger = logging.getLogger("primust.langgraph")
+
+PROOF_LEVEL_MAP = {
+    "deterministic_rule": "mathematical",
+    "zkml_model": "verifiable_inference",
+    "ml_model": "execution",
+    "witnessed": "witnessed",
+    "default": "attestation",
+}
+
+SURFACE_DECLARATION = {
+    "surface_type": "in_process_adapter",
+    "surface_name": "langgraph_tool_hooks",
+    "observation_mode": "post_action_realtime",
+    "scope_type": "full_workflow",
+    "proof_ceiling": "execution",
+    "surface_coverage_statement": (
+        "All LangGraph tool calls observed via tool execution lifecycle hooks. "
+        "Actions outside the LangGraph graph scope are not observed."
+    ),
+}
+
+
+class PrimustLangGraph:
+    """Wraps a LangGraph graph. Instruments all tool calls and node transitions."""
+
+    def __init__(
+        self,
+        pipeline: Pipeline,
+        manifest_map: dict[str, str] | None = None,
+    ) -> None:
+        self.pipeline = pipeline
+        self.manifest_map = manifest_map or {}
+
+    def wrap(self, graph: Any) -> Any:
+        """
+        Instrument a LangGraph StateGraph by wrapping its tool nodes.
+
+        Returns the same graph object with instrumented tool calls.
+        """
+        if hasattr(graph, "nodes"):
+            for node_name, node_fn in list(graph.nodes.items()):
+                if callable(node_fn):
+                    graph.nodes[node_name] = self._wrap_node(node_name, node_fn)
+        return graph
+
+    def wrap_tool(self, check_label: str, tool_fn: Callable[..., Any]) -> Callable[..., Any]:
+        """Wrap a single tool function with Primust instrumentation."""
+        return self._wrap_node(check_label, tool_fn)
+
+    def _wrap_node(self, node_name: str, node_fn: Callable[..., Any]) -> Callable[..., Any]:
+        adapter = self
+
+        @functools.wraps(node_fn)
+        def instrumented(*args: Any, **kwargs: Any) -> Any:
+            manifest_id = adapter.manifest_map.get(node_name, f"auto:{node_name}")
+            session: CheckSession | None = None
+            try:
+                session = adapter.pipeline.open_check(node_name, manifest_id)
+            except Exception:
+                logger.exception("Failed to open check for %s", node_name)
+
+            try:
+                result = node_fn(*args, **kwargs)
+            except Exception as exc:
+                if session:
+                    try:
+                        adapter.pipeline.record(
+                            session,
+                            input=_extract_input(args, kwargs),
+                            check_result="error",
+                        )
+                    except Exception:
+                        logger.exception("Failed to record error for %s", node_name)
+                raise exc
+
+            if session:
+                try:
+                    adapter.pipeline.record(
+                        session,
+                        input=_extract_input(args, kwargs),
+                        check_result="pass",
+                        output=result,
+                    )
+                except Exception:
+                    logger.exception("Failed to record result for %s", node_name)
+
+            return result
+
+        @functools.wraps(node_fn)
+        async def instrumented_async(*args: Any, **kwargs: Any) -> Any:
+            manifest_id = adapter.manifest_map.get(node_name, f"auto:{node_name}")
+            session: CheckSession | None = None
+            try:
+                session = adapter.pipeline.open_check(node_name, manifest_id)
+            except Exception:
+                logger.exception("Failed to open check for %s", node_name)
+
+            try:
+                result = await node_fn(*args, **kwargs)
+            except Exception as exc:
+                if session:
+                    try:
+                        adapter.pipeline.record(
+                            session,
+                            input=_extract_input(args, kwargs),
+                            check_result="error",
+                        )
+                    except Exception:
+                        logger.exception("Failed to record error for %s", node_name)
+                raise exc
+
+            if session:
+                try:
+                    adapter.pipeline.record(
+                        session,
+                        input=_extract_input(args, kwargs),
+                        check_result="pass",
+                        output=result,
+                    )
+                except Exception:
+                    logger.exception("Failed to record result for %s", node_name)
+
+            return result
+
+        import asyncio
+        if asyncio.iscoroutinefunction(node_fn):
+            return instrumented_async
+        return instrumented
+
+    def get_surface_declaration(self) -> dict[str, str]:
+        return dict(SURFACE_DECLARATION)
+
+
+def _extract_input(args: tuple[Any, ...], kwargs: dict[str, Any]) -> Any:
+    """Extract tool input from args/kwargs for commitment hashing."""
+    if kwargs:
+        return kwargs
+    if len(args) == 1:
+        return args[0]
+    return list(args)

primust_langgraph-1.0.0/tests/test_adapter.py

@@ -0,0 +1,277 @@
+"""
+P11-A: LangGraph adapter tests — 9 MUST PASS.
+
+Uses mock Pipeline and mock LangGraph graph objects.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+from unittest.mock import MagicMock, patch
+
+import httpx
+import pytest
+
+from primust_artifact_core import commit, commit_output
+from primust.pipeline import Pipeline, CheckSession
+
+from primust_langgraph import PrimustLangGraph
+
+
+# ── Mock HTTP transport ──
+
+
+class MockTransport(httpx.BaseTransport):
+    def __init__(self) -> None:
+        self.requests: list[dict[str, Any]] = []
+        self._run_counter = 0
+
+    def handle_request(self, request: httpx.Request) -> httpx.Response:
+        body = request.content.decode("utf-8") if request.content else ""
+        parsed = json.loads(body) if body else {}
+        self.requests.append({
+            "method": request.method,
+            "url": str(request.url),
+            "body": parsed,
+            "raw_body": body,
+        })
+        path = request.url.path
+        if path == "/api/v1/runs" and request.method == "POST":
+            self._run_counter += 1
+            return httpx.Response(200, json={
+                "run_id": f"run_{self._run_counter:04d}",
+                "policy_snapshot_hash": "sha256:" + "aa" * 32,
+                "process_context_hash": parsed.get("process_context_hash"),
+            })
+        if "/records" in path and request.method == "POST":
+            return httpx.Response(200, json={
+                "record_id": "rec_test001",
+                "chain_hash": "sha256:" + "bb" * 32,
+            })
+        if "/close" in path and request.method == "POST":
+            return httpx.Response(200, json={
+                "vpec_id": "vpec_test001",
+                "schema_version": "4.0.0",
+                "state": "signed",
+            })
+        return httpx.Response(404, json={"detail": "not found"})
+
+
+# ── Mock LangGraph graph ──
+
+
+class MockStateGraph:
+    """Simulates a LangGraph StateGraph with nodes."""
+
+    def __init__(self) -> None:
+        self.nodes: dict[str, Any] = {}
+
+    def add_node(self, name: str, fn: Any) -> None:
+        self.nodes[name] = fn
+
+
+@pytest.fixture
+def transport() -> MockTransport:
+    return MockTransport()
+
+
+@pytest.fixture
+def pipeline(transport: MockTransport) -> Pipeline:
+    client = httpx.Client(
+        base_url="https://api.primust.com",
+        headers={"X-API-Key": "pk_live_org001_us_secret"},
+        transport=transport,
+    )
+    return Pipeline(
+        api_key="pk_live_org001_us_secret",
+        workflow_id="wf_langgraph",
+        process_context_hash="sha256:" + "cc" * 32,
+        http_client=client,
+    )
+
+
+# ── Tests ──
+
+
+class TestLangGraphAdapter:
+    """P11-A: LangGraph adapter."""
+
+    def test_tool_call_creates_record_with_commitment_hash(
+        self, pipeline: Pipeline, transport: MockTransport
+    ) -> None:
+        """MUST PASS: tool call → CheckExecutionRecord created with commitment_hash."""
+        adapter = PrimustLangGraph(
+            pipeline=pipeline,
+            manifest_map={"search": "manifest_search_v1"},
+        )
+
+        def search_tool(query: str) -> str:
+            return f"Results for {query}"
+
+        wrapped = adapter.wrap_tool("search", search_tool)
+        result = wrapped(query="test query")
+
+        assert result == "Results for test query"
+
+        record_req = [r for r in transport.requests if "/records" in r["url"]]
+        assert len(record_req) == 1
+        body = record_req[0]["body"]
+        assert body["commitment_hash"].startswith("poseidon2:")
+        assert body["manifest_id"] == "manifest_search_v1"
+
+    def test_raw_tool_input_not_in_http_body(
+        self, pipeline: Pipeline, transport: MockTransport
+    ) -> None:
+        """MUST PASS: raw tool input not in HTTP body (interceptor test)."""
+        adapter = PrimustLangGraph(pipeline=pipeline)
+
+        sensitive_input = "this is sensitive PII data that must never transit"
+
+        def pii_tool(data: str) -> str:
+            return "processed"
+
+        wrapped = adapter.wrap_tool("pii_tool", pii_tool)
+        wrapped(data=sensitive_input)
+
+        record_req = [r for r in transport.requests if "/records" in r["url"]]
+        raw_body = record_req[0]["raw_body"]
+        assert sensitive_input not in raw_body
+
+    def test_check_open_tst_fetched_before_tool_executes(
+        self, pipeline: Pipeline, transport: MockTransport
+    ) -> None:
+        """MUST PASS: check_open_tst fetched before tool executes."""
+        adapter = PrimustLangGraph(pipeline=pipeline)
+
+        def slow_tool(x: int) -> int:
+            return x * 2
+
+        wrapped = adapter.wrap_tool("slow_tool", slow_tool)
+        wrapped(x=42)
+
+        record_req = [r for r in transport.requests if "/records" in r["url"]]
+        body = record_req[0]["body"]
+        assert body["check_open_tst"] is not None
+        from datetime import datetime
+        datetime.fromisoformat(body["check_open_tst"])  # valid ISO string
+
+    def test_check_close_tst_at_record_time(
+        self, pipeline: Pipeline, transport: MockTransport
+    ) -> None:
+        """MUST PASS: check_close_tst fetched at p.record() time."""
+        adapter = PrimustLangGraph(pipeline=pipeline)
+
+        def tool(x: int) -> int:
+            return x + 1
+
+        wrapped = adapter.wrap_tool("tool", tool)
+        wrapped(x=1)
+
+        record_req = [r for r in transport.requests if "/records" in r["url"]]
+        body = record_req[0]["body"]
+        assert body["check_close_tst"] is not None
+        from datetime import datetime
+        datetime.fromisoformat(body["check_close_tst"])
+
+    def test_output_commitment_present_when_tool_returns(
+        self, pipeline: Pipeline, transport: MockTransport
+    ) -> None:
+        """MUST PASS: output_commitment present when tool returns output."""
+        adapter = PrimustLangGraph(pipeline=pipeline)
+
+        def calc_tool(a: int, b: int) -> dict[str, int]:
+            return {"sum": a + b}
+
+        wrapped = adapter.wrap_tool("calc_tool", calc_tool)
+        result = wrapped(a=3, b=4)
+        assert result == {"sum": 7}
+
+        record_req = [r for r in transport.requests if "/records" in r["url"]]
+        body = record_req[0]["body"]
+        assert body["output_commitment"].startswith("poseidon2:")
+
+    def test_manifest_hash_captured_per_record(
+        self, pipeline: Pipeline, transport: MockTransport
+    ) -> None:
+        """MUST PASS: manifest_hash captured per record."""
+        adapter = PrimustLangGraph(
+            pipeline=pipeline,
+            manifest_map={"tool_a": "manifest_a_v1"},
+        )
+
+        wrapped = adapter.wrap_tool("tool_a", lambda: "ok")
+        wrapped()
+
+        record_req = [r for r in transport.requests if "/records" in r["url"]]
+        body = record_req[0]["body"]
+        assert body["manifest_id"] == "manifest_a_v1"
+
+    def test_process_context_hash_propagated(
+        self, pipeline: Pipeline, transport: MockTransport
+    ) -> None:
+        """MUST PASS: process_context_hash propagated from Pipeline."""
+        adapter = PrimustLangGraph(pipeline=pipeline)
+        wrapped = adapter.wrap_tool("tool", lambda: "ok")
+        wrapped()
+
+        run_req = [r for r in transport.requests if r["url"].endswith("/api/v1/runs")]
+        assert run_req[0]["body"]["process_context_hash"] == "sha256:" + "cc" * 32
+
+    def test_surface_type_in_process_adapter(
+        self, pipeline: Pipeline, transport: MockTransport
+    ) -> None:
+        """MUST PASS: surface_type = in_process_adapter in ObservationSurface."""
+        adapter = PrimustLangGraph(pipeline=pipeline)
+        surface = adapter.get_surface_declaration()
+        assert surface["surface_type"] == "in_process_adapter"
+        assert surface["observation_mode"] == "post_action_realtime"
+        assert surface["scope_type"] == "full_workflow"
+
+    def test_all_five_proof_levels_reachable(self) -> None:
+        """MUST PASS: all 5 proof levels reachable depending on manifest stage type."""
+        from primust_langgraph.adapter import PROOF_LEVEL_MAP
+        expected = {"mathematical", "verifiable_inference", "execution", "witnessed", "attestation"}
+        assert set(PROOF_LEVEL_MAP.values()) == expected
+
+    def test_wrap_graph_instruments_nodes(
+        self, pipeline: Pipeline, transport: MockTransport
+    ) -> None:
+        """wrap() instruments all nodes in a StateGraph."""
+        adapter = PrimustLangGraph(
+            pipeline=pipeline,
+            manifest_map={"node_a": "manifest_a"},
+        )
+
+        graph = MockStateGraph()
+        graph.add_node("node_a", lambda state: {"output": "done"})
+
+        adapter.wrap(graph)
+
+        # Call the wrapped node
+        result = graph.nodes["node_a"](state={"input": "test"})
+        assert result == {"output": "done"}
+
+        record_req = [r for r in transport.requests if "/records" in r["url"]]
+        assert len(record_req) == 1
+
+    def test_adapter_failure_does_not_block_tool(
+        self, pipeline: Pipeline, transport: MockTransport
+    ) -> None:
+        """Adapter failure does not block tool execution (fail open)."""
+        adapter = PrimustLangGraph(pipeline=pipeline)
+
+        # Force pipeline.record to raise
+        original_record = pipeline.record
+        def broken_record(*a: Any, **kw: Any) -> Any:
+            raise RuntimeError("record exploded")
+        pipeline.record = broken_record  # type: ignore
+
+        def tool(x: int) -> int:
+            return x * 10
+
+        wrapped = adapter.wrap_tool("tool", tool)
+        result = wrapped(x=5)
+        assert result == 50  # tool still returns correctly
+
+        pipeline.record = original_record  # type: ignore