jep-langgraph-adapter 0.1.1__tar.gz

jep_langgraph_adapter-0.1.1/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: jep-langgraph-adapter
+Version: 0.1.1
+Summary: JEP runtime adapter for LangGraph: replayable delegation and verifiable AI accountability semantics.
+Author: JEP
+License: MIT
+Keywords: jep,langgraph,accountability,replay,agent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Provides-Extra: langgraph
+Requires-Dist: langgraph>=0.2; extra == "langgraph"
+
+# jep-langgraph-adapter
+
+JEP runtime adapter for LangGraph: replayable delegation and verifiable AI accountability semantics.
+
+This package instruments LangGraph-style node callables without modifying LangGraph core. Wrapped node execution naturally emits a deterministic, hash-linked JEP accountability chain containing:
+
+- Judgment Event
+- Delegation Event
+- Termination Event
+- Verification Event
+
+Each event records `node_name`, `agent_id`, `tool_name`, `state_transition`, `authority_scope`, and `previous_event_hash`.
+
+## Install
+
+```bash
+pip install -e .
+```
+
+LangGraph is optional for tests and examples because the adapter works at the callable-node boundary:
+
+```bash
+pip install -e '.[langgraph]'
+```
+
+## Usage
+
+```python
+from jep_langgraph_adapter import LangGraphEventAdapter
+
+adapter = LangGraphEventAdapter(
+    session_id="demo-session",
+    agent_id="planner-agent",
+    authority_scope={"tools": ["search"], "max_steps": 3},
+)
+
+def plan(state):
+    return {**state, "plan": "call search"}
+
+wrapped_plan = adapter.wrap_node(plan, node_name="plan")
+next_state = wrapped_plan({"question": "What changed?"})
+adapter.exporter().export_jsonl("session.jsonl")
+```
+
+For a `StateGraph`, add wrapped nodes through `instrument_state_graph`:
+
+```python
+adapter.instrument_state_graph(graph, {"plan": plan, "answer": answer})
+```
+
+## Replay CLI
+
+```bash
+jep-langgraph replay session.jsonl
+```
+
+The replay command validates deterministic event hashes, sequence numbers, and `previous_event_hash` links.
+
+## Components
+
+- `JEPNodeMiddleware`: wraps sync or async LangGraph node callables.
+- `JEPExecutionTracer`: records judgment, delegation, termination, and verification events.
+- `JEPReplayExporter`: exports JSON/JSONL and validates replay chains.
+- `LangGraphEventAdapter`: high-level facade for node and graph instrumentation.
+
+## Examples
+
+- `examples/multi_step_graph.py`: multi-step graph execution.
+- `examples/sub_agent_delegation.py`: sub-agent delegation chain.
+- `examples/tool_invocation_replay.py`: tool invocation verification and replay.
+
+## Runtime and verification notes
+
+See [HARDENING.md](HARDENING.md) for supported behavior, regression checks, and compatibility boundaries.

jep_langgraph_adapter-0.1.1/README.md

@@ -0,0 +1,74 @@
+# jep-langgraph-adapter
+
+JEP runtime adapter for LangGraph: replayable delegation and verifiable AI accountability semantics.
+
+This package instruments LangGraph-style node callables without modifying LangGraph core. Wrapped node execution naturally emits a deterministic, hash-linked JEP accountability chain containing:
+
+- Judgment Event
+- Delegation Event
+- Termination Event
+- Verification Event
+
+Each event records `node_name`, `agent_id`, `tool_name`, `state_transition`, `authority_scope`, and `previous_event_hash`.
+
+## Install
+
+```bash
+pip install -e .
+```
+
+LangGraph is optional for tests and examples because the adapter works at the callable-node boundary:
+
+```bash
+pip install -e '.[langgraph]'
+```
+
+## Usage
+
+```python
+from jep_langgraph_adapter import LangGraphEventAdapter
+
+adapter = LangGraphEventAdapter(
+    session_id="demo-session",
+    agent_id="planner-agent",
+    authority_scope={"tools": ["search"], "max_steps": 3},
+)
+
+def plan(state):
+    return {**state, "plan": "call search"}
+
+wrapped_plan = adapter.wrap_node(plan, node_name="plan")
+next_state = wrapped_plan({"question": "What changed?"})
+adapter.exporter().export_jsonl("session.jsonl")
+```
+
+For a `StateGraph`, add wrapped nodes through `instrument_state_graph`:
+
+```python
+adapter.instrument_state_graph(graph, {"plan": plan, "answer": answer})
+```
+
+## Replay CLI
+
+```bash
+jep-langgraph replay session.jsonl
+```
+
+The replay command validates deterministic event hashes, sequence numbers, and `previous_event_hash` links.
+
+## Components
+
+- `JEPNodeMiddleware`: wraps sync or async LangGraph node callables.
+- `JEPExecutionTracer`: records judgment, delegation, termination, and verification events.
+- `JEPReplayExporter`: exports JSON/JSONL and validates replay chains.
+- `LangGraphEventAdapter`: high-level facade for node and graph instrumentation.
+
+## Examples
+
+- `examples/multi_step_graph.py`: multi-step graph execution.
+- `examples/sub_agent_delegation.py`: sub-agent delegation chain.
+- `examples/tool_invocation_replay.py`: tool invocation verification and replay.
+
+## Runtime and verification notes
+
+See [HARDENING.md](HARDENING.md) for supported behavior, regression checks, and compatibility boundaries.

jep_langgraph_adapter-0.1.1/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "jep-langgraph-adapter"
+version = "0.1.1"
+description = "JEP runtime adapter for LangGraph: replayable delegation and verifiable AI accountability semantics."
+readme = "README.md"
+requires-python = ">=3.9"
+authors = [{ name = "JEP" }]
+license = { text = "MIT" }
+keywords = ["jep", "langgraph", "accountability", "replay", "agent"]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0"]
+langgraph = ["langgraph>=0.2"]
+
+[project.scripts]
+jep-langgraph = "jep_langgraph_adapter.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]

jep_langgraph_adapter-0.1.1/setup.cfg

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

jep_langgraph_adapter-0.1.1/src/jep_langgraph_adapter/__init__.py

@@ -0,0 +1,20 @@
+"""LangGraph adapter for JEP accountability event chains."""
+
+from .adapter import LangGraphEventAdapter
+from .canonicalization import canonicalize, canonical_hash
+from .events import JEPEvent, JEPEventType
+from .exporter import JEPReplayExporter, ReplayResult
+from .middleware import JEPNodeMiddleware
+from .tracer import JEPExecutionTracer
+
+__all__ = [
+    "JEPEvent",
+    "JEPEventType",
+    "JEPExecutionTracer",
+    "JEPNodeMiddleware",
+    "JEPReplayExporter",
+    "LangGraphEventAdapter",
+    "ReplayResult",
+    "canonical_hash",
+    "canonicalize",
+]

jep_langgraph_adapter-0.1.1/src/jep_langgraph_adapter/adapter.py

@@ -0,0 +1,64 @@
+"""Public LangGraph adapter facade."""
+
+from __future__ import annotations
+
+import uuid
+from typing import Any, Callable, Dict, Mapping, MutableMapping, Optional
+
+from .exporter import JEPReplayExporter
+from .middleware import JEPNodeMiddleware
+from .tracer import JEPExecutionTracer
+
+
+class LangGraphEventAdapter:
+    """Facade for instrumenting LangGraph nodes without patching LangGraph core."""
+
+    def __init__(
+        self,
+        *,
+        session_id: Optional[str] = None,
+        agent_id: str = "langgraph-agent",
+        authority_scope: Optional[Mapping[str, Any]] = None,
+        verifier: Optional[Callable[[Any], bool]] = None,
+    ) -> None:
+        self.tracer = JEPExecutionTracer(
+            session_id=session_id or str(uuid.uuid4()),
+            default_agent_id=agent_id,
+            default_authority_scope=dict(authority_scope or {}),
+        )
+        self.middleware = JEPNodeMiddleware(
+            self.tracer,
+            agent_id=agent_id,
+            authority_scope=authority_scope,
+            verifier=verifier,
+        )
+
+    @property
+    def events(self):
+        return self.tracer.events
+
+    def wrap_node(self, node: Callable[..., Any], **kwargs: Any) -> Callable[..., Any]:
+        return self.middleware.wrap_node(node, **kwargs)
+
+    def wrap_nodes(self, nodes: Mapping[str, Callable[..., Any]], **defaults: Any) -> Dict[str, Callable[..., Any]]:
+        return {
+            name: self.wrap_node(node, node_name=name, **defaults)
+            for name, node in nodes.items()
+        }
+
+    def instrument_state_graph(self, graph: Any, nodes: Mapping[str, Callable[..., Any]], **defaults: Any) -> Any:
+        """Add wrapped nodes to a LangGraph StateGraph-like object and return the graph."""
+
+        for name, node in nodes.items():
+            graph.add_node(name, self.wrap_node(node, node_name=name, **defaults))
+        return graph
+
+    def instrument_node_mapping(self, mapping: MutableMapping[str, Callable[..., Any]], **defaults: Any) -> MutableMapping[str, Callable[..., Any]]:
+        """Replace callables in a mutable node mapping with wrapped equivalents."""
+
+        for name, node in list(mapping.items()):
+            mapping[name] = self.wrap_node(node, node_name=name, **defaults)
+        return mapping
+
+    def exporter(self) -> JEPReplayExporter:
+        return JEPReplayExporter(self.events)

jep_langgraph_adapter-0.1.1/src/jep_langgraph_adapter/canonicalization.py

@@ -0,0 +1,45 @@
+"""Deterministic canonicalization utilities for replayable JEP events."""
+
+from __future__ import annotations
+
+import dataclasses
+import hashlib
+import json
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+
+def _normalize(value: Any) -> Any:
+    """Convert Python values into deterministic JSON-compatible structures."""
+
+    if dataclasses.is_dataclass(value):
+        value = dataclasses.asdict(value)
+
+    if isinstance(value, Mapping):
+        return {str(key): _normalize(value[key]) for key in sorted(value, key=lambda item: str(item))}
+
+    if isinstance(value, (str, int, float, bool)) or value is None:
+        return value
+
+    if isinstance(value, Sequence) and not isinstance(value, (str, bytes, bytearray)):
+        return [_normalize(item) for item in value]
+
+    if isinstance(value, (set, frozenset)):
+        return sorted((_normalize(item) for item in value), key=lambda item: canonicalize(item))
+
+    if isinstance(value, (bytes, bytearray)):
+        return value.hex()
+
+    return repr(value)
+
+
+def canonicalize(value: Any) -> str:
+    """Return a deterministic JSON representation for hashing and export."""
+
+    return json.dumps(_normalize(value), sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+
+
+def canonical_hash(value: Any) -> str:
+    """Return the SHA-256 hash of a canonicalized value."""
+
+    return hashlib.sha256(canonicalize(value).encode("utf-8")).hexdigest()

jep_langgraph_adapter-0.1.1/src/jep_langgraph_adapter/cli.py

@@ -0,0 +1,34 @@
+"""Command line interface for the JEP LangGraph adapter."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from .exporter import JEPReplayExporter
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="jep-langgraph")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+    replay = subparsers.add_parser("replay", help="verify and replay a JSONL JEP event chain")
+    replay.add_argument("session", help="path to session.jsonl")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    if args.command == "replay":
+        result = JEPReplayExporter.replay_file(args.session)
+        if result.valid:
+            print(f"Replay valid: {len(result.events)} events")
+            return 0
+        print("Replay invalid:", file=sys.stderr)
+        for error in result.errors:
+            print(f"- {error}", file=sys.stderr)
+        return 1
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

jep_langgraph_adapter-0.1.1/src/jep_langgraph_adapter/events.py

@@ -0,0 +1,85 @@
+"""JEP event model used by the LangGraph adapter."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Dict, Mapping, Optional
+
+from .canonicalization import canonical_hash, canonicalize
+
+
+class JEPEventType(str, Enum):
+    """JEP accountability event types emitted around LangGraph execution."""
+
+    JUDGMENT = "Judgment Event"
+    DELEGATION = "Delegation Event"
+    TERMINATION = "Termination Event"
+    VERIFICATION = "Verification Event"
+
+
+@dataclass(frozen=True)
+class JEPEvent:
+    """A replayable, hash-linked JEP event."""
+
+    event_type: JEPEventType
+    event_id: str
+    session_id: str
+    sequence: int
+    node_name: str
+    agent_id: str
+    tool_name: Optional[str]
+    state_transition: Mapping[str, Any]
+    authority_scope: Mapping[str, Any]
+    previous_event_hash: Optional[str]
+    delegation_parent_hash: Optional[str] = None
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+    event_hash: Optional[str] = None
+
+    def payload(self, include_hash: bool = False) -> Dict[str, Any]:
+        data: Dict[str, Any] = {
+            "event_type": self.event_type.value,
+            "event_id": self.event_id,
+            "session_id": self.session_id,
+            "sequence": self.sequence,
+            "node_name": self.node_name,
+            "agent_id": self.agent_id,
+            "tool_name": self.tool_name,
+            "state_transition": dict(self.state_transition),
+            "authority_scope": dict(self.authority_scope),
+            "previous_event_hash": self.previous_event_hash,
+            "delegation_parent_hash": self.delegation_parent_hash,
+            "metadata": dict(self.metadata),
+        }
+        if include_hash:
+            data["event_hash"] = self.hash()
+        return data
+
+    def hash(self) -> str:
+        return self.event_hash or canonical_hash(self.payload(include_hash=False))
+
+    def to_json(self) -> str:
+        return canonicalize(self.payload(include_hash=True))
+
+    @classmethod
+    def from_mapping(cls, data: Mapping[str, Any]) -> "JEPEvent":
+        event_hash = data.get("event_hash")
+        event = cls(
+            event_type=JEPEventType(data["event_type"]),
+            event_id=str(data["event_id"]),
+            session_id=str(data["session_id"]),
+            sequence=int(data["sequence"]),
+            node_name=str(data["node_name"]),
+            agent_id=str(data["agent_id"]),
+            tool_name=data.get("tool_name"),
+            state_transition=data.get("state_transition", {}),
+            authority_scope=data.get("authority_scope", {}),
+            previous_event_hash=data.get("previous_event_hash"),
+            delegation_parent_hash=data.get("delegation_parent_hash"),
+            metadata=data.get("metadata", {}),
+            event_hash=event_hash,
+        )
+        expected = event.hash() if event_hash is None else canonical_hash(event.payload(include_hash=False))
+        if event_hash is not None and event_hash != expected:
+            raise ValueError(f"event_hash mismatch for {event.event_id}: expected {expected}, got {event_hash}")
+        return event

jep_langgraph_adapter-0.1.1/src/jep_langgraph_adapter/exporter.py

@@ -0,0 +1,77 @@
+"""Replay and export support for JEP event chains."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterable, List, Optional, Sequence
+
+from .events import JEPEvent
+
+
+@dataclass(frozen=True)
+class ReplayResult:
+    valid: bool
+    events: Sequence[JEPEvent]
+    errors: Sequence[str]
+
+
+class JEPReplayExporter:
+    """Export and verify replayable JEP event chains."""
+
+    def __init__(self, events: Optional[Iterable[JEPEvent]] = None) -> None:
+        self.events = list(events or [])
+
+    def export_jsonl(self, path: str | Path, events: Optional[Iterable[JEPEvent]] = None) -> Path:
+        destination = Path(path)
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        selected_events = list(events or self.events)
+        with destination.open("w", encoding="utf-8") as handle:
+            for event in selected_events:
+                handle.write(event.to_json())
+                handle.write("\n")
+        return destination
+
+    def export_json(self, path: str | Path, events: Optional[Iterable[JEPEvent]] = None) -> Path:
+        destination = Path(path)
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        selected_events = [event.payload(include_hash=True) for event in list(events or self.events)]
+        with destination.open("w", encoding="utf-8") as handle:
+            json.dump(selected_events, handle, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+        return destination
+
+    @staticmethod
+    def load_jsonl(path: str | Path) -> List[JEPEvent]:
+        events: List[JEPEvent] = []
+        with Path(path).open("r", encoding="utf-8") as handle:
+            for line_number, line in enumerate(handle, start=1):
+                if not line.strip():
+                    continue
+                try:
+                    events.append(JEPEvent.from_mapping(json.loads(line)))
+                except Exception as exc:  # noqa: BLE001 - replay should report malformed event lines.
+                    raise ValueError(f"invalid event on line {line_number}: {exc}") from exc
+        return events
+
+    @staticmethod
+    def replay(events: Iterable[JEPEvent]) -> ReplayResult:
+        parsed = list(events)
+        errors: List[str] = []
+        previous_hash = None
+        for expected_sequence, event in enumerate(parsed):
+            if event.sequence != expected_sequence:
+                errors.append(f"sequence mismatch at {event.event_id}: expected {expected_sequence}, got {event.sequence}")
+            if event.previous_event_hash != previous_hash:
+                errors.append(
+                    f"previous_event_hash mismatch at {event.event_id}: "
+                    f"expected {previous_hash}, got {event.previous_event_hash}"
+                )
+            if event.hash() != event.payload(include_hash=True)["event_hash"]:
+                errors.append(f"event_hash mismatch at {event.event_id}")
+            previous_hash = event.hash()
+        return ReplayResult(valid=not errors, events=parsed, errors=errors)
+
+    @classmethod
+    def replay_file(cls, path: str | Path) -> ReplayResult:
+        return cls.replay(cls.load_jsonl(path))

jep_langgraph_adapter-0.1.1/src/jep_langgraph_adapter/middleware.py

@@ -0,0 +1,290 @@
+"""LangGraph node middleware that wraps node callables without modifying LangGraph core."""
+
+from __future__ import annotations
+
+import inspect
+import asyncio
+from copy import deepcopy
+from functools import wraps
+from typing import Any, Callable, Mapping, Optional
+
+from .tracer import JEPExecutionTracer
+
+
+class JEPNodeMiddleware:
+    """Wrap LangGraph node execution and emit JEP events automatically."""
+
+    def __init__(
+        self,
+        tracer: Optional[JEPExecutionTracer] = None,
+        *,
+        agent_id: Optional[str] = None,
+        authority_scope: Optional[Mapping[str, Any]] = None,
+        verifier: Optional[Callable[[Any], bool]] = None,
+    ) -> None:
+        self.tracer = tracer or JEPExecutionTracer()
+        self.agent_id = agent_id
+        self.authority_scope = dict(authority_scope or {})
+        self.verifier = verifier
+
+    def wrap_node(
+        self,
+        node: Callable[..., Any],
+        *,
+        node_name: Optional[str] = None,
+        agent_id: Optional[str] = None,
+        tool_name: Optional[str] = None,
+        authority_scope: Optional[Mapping[str, Any]] = None,
+        is_delegation: bool = False,
+        delegated_to: Optional[str] = None,
+    ) -> Callable[..., Any]:
+        """Return a wrapped node callable that records judgment/termination/verification events."""
+
+        resolved_node_name = node_name or getattr(
+            node, "__name__", node.__class__.__name__
+        )
+        resolved_agent_id = agent_id or self.agent_id
+        resolved_scope = dict(
+            authority_scope if authority_scope is not None else self.authority_scope
+        )
+
+        if inspect.iscoroutinefunction(node):
+
+            @wraps(node)
+            async def async_wrapper(state: Any, *args: Any, **kwargs: Any) -> Any:
+                input_snapshot = deepcopy(state)
+                delegation_event = self._maybe_record_delegation(
+                    is_delegation=is_delegation,
+                    delegated_to=delegated_to,
+                    node_name=resolved_node_name,
+                    agent_id=resolved_agent_id,
+                    tool_name=tool_name,
+                    state=state,
+                    authority_scope=resolved_scope,
+                )
+                context = (
+                    self.tracer.delegation_context(delegation_event)
+                    if delegation_event
+                    else _NullContext()
+                )
+                with context:
+                    self.tracer.record_judgment(
+                        node_name=resolved_node_name,
+                        agent_id=resolved_agent_id,
+                        input_state=input_snapshot,
+                        authority_scope=resolved_scope,
+                        metadata={"callable": repr(node)},
+                    )
+                    try:
+                        result = await node(state, *args, **kwargs)
+                    except BaseException as exc:
+                        self._record_failure(
+                            resolved_node_name,
+                            resolved_agent_id,
+                            input_snapshot,
+                            resolved_scope,
+                            exc,
+                        )
+                        raise
+                    self._record_completion(
+                        node_name=resolved_node_name,
+                        agent_id=resolved_agent_id,
+                        tool_name=tool_name,
+                        input_state=input_snapshot,
+                        output_state=result,
+                        authority_scope=resolved_scope,
+                    )
+                    if self.verifier is not None:
+                        try:
+                            verified = self.verifier(result)
+                            if inspect.isawaitable(verified):
+                                verified = await verified
+                            self._record_verdict(
+                                resolved_node_name,
+                                resolved_agent_id,
+                                tool_name,
+                                result,
+                                resolved_scope,
+                                verified,
+                            )
+                        except BaseException as exc:
+                            self._record_verdict(
+                                resolved_node_name,
+                                resolved_agent_id,
+                                tool_name,
+                                result,
+                                resolved_scope,
+                                False,
+                                exc,
+                            )
+                            raise
+                    return result
+
+            return async_wrapper
+
+        @wraps(node)
+        def wrapper(state: Any, *args: Any, **kwargs: Any) -> Any:
+            input_snapshot = deepcopy(state)
+            delegation_event = self._maybe_record_delegation(
+                is_delegation=is_delegation,
+                delegated_to=delegated_to,
+                node_name=resolved_node_name,
+                agent_id=resolved_agent_id,
+                tool_name=tool_name,
+                state=state,
+                authority_scope=resolved_scope,
+            )
+            context = (
+                self.tracer.delegation_context(delegation_event)
+                if delegation_event
+                else _NullContext()
+            )
+            with context:
+                self.tracer.record_judgment(
+                    node_name=resolved_node_name,
+                    agent_id=resolved_agent_id,
+                    input_state=input_snapshot,
+                    authority_scope=resolved_scope,
+                    metadata={"callable": repr(node)},
+                )
+                try:
+                    result = node(state, *args, **kwargs)
+                except BaseException as exc:
+                    self._record_failure(
+                        resolved_node_name,
+                        resolved_agent_id,
+                        input_snapshot,
+                        resolved_scope,
+                        exc,
+                    )
+                    raise
+                self._record_completion(
+                    node_name=resolved_node_name,
+                    agent_id=resolved_agent_id,
+                    tool_name=tool_name,
+                    input_state=input_snapshot,
+                    output_state=result,
+                    authority_scope=resolved_scope,
+                )
+                if self.verifier is not None:
+                    try:
+                        verified = self.verifier(result)
+                        if inspect.isawaitable(verified):
+                            if inspect.iscoroutine(verified):
+                                verified.close()
+                            raise TypeError("async verifiers require an async node")
+                        self._record_verdict(
+                            resolved_node_name,
+                            resolved_agent_id,
+                            tool_name,
+                            result,
+                            resolved_scope,
+                            verified,
+                        )
+                    except BaseException as exc:
+                        self._record_verdict(
+                            resolved_node_name,
+                            resolved_agent_id,
+                            tool_name,
+                            result,
+                            resolved_scope,
+                            False,
+                            exc,
+                        )
+                        raise
+                return result
+
+        return wrapper
+
+    def record_delegation(self, **kwargs: Any):
+        """Record an explicit sub-agent delegation event from user graph code."""
+
+        return self.tracer.record_delegation(**kwargs)
+
+    def _maybe_record_delegation(
+        self,
+        *,
+        is_delegation: bool,
+        delegated_to: Optional[str],
+        node_name: str,
+        agent_id: Optional[str],
+        tool_name: Optional[str],
+        state: Any,
+        authority_scope: Mapping[str, Any],
+    ):
+        if not is_delegation:
+            return None
+        return self.tracer.record_delegation(
+            node_name=node_name,
+            agent_id=agent_id,
+            delegated_to=delegated_to or node_name,
+            tool_name=tool_name,
+            state=state,
+            authority_scope=authority_scope,
+        )
+
+    def _record_completion(
+        self,
+        *,
+        node_name: str,
+        agent_id: Optional[str],
+        tool_name: Optional[str],
+        input_state: Any,
+        output_state: Any,
+        authority_scope: Mapping[str, Any],
+    ) -> None:
+        self.tracer.record_termination(
+            node_name=node_name,
+            agent_id=agent_id,
+            input_state=input_state,
+            output_state=output_state,
+            authority_scope=authority_scope,
+            metadata={
+                "status": "succeeded",
+                "verification_status": (
+                    "pending" if self.verifier is not None else "unchecked"
+                ),
+            },
+        )
+
+    def _record_failure(self, node_name, agent_id, input_state, scope, exc):
+        self.tracer.record_termination(
+            node_name=node_name,
+            agent_id=agent_id,
+            input_state=input_state,
+            output_state=None,
+            authority_scope=scope,
+            metadata={
+                "status": (
+                    "cancelled" if isinstance(exc, asyncio.CancelledError) else "failed"
+                ),
+                "error_type": type(exc).__name__,
+            },
+        )
+
+    def _record_verdict(
+        self, node_name, agent_id, tool_name, state, scope, verified, error=None
+    ):
+        if type(verified) is not bool:
+            raise TypeError("verifier must return a boolean")
+        self.tracer.record_verification(
+            node_name=node_name,
+            agent_id=agent_id,
+            tool_name=tool_name,
+            state=state,
+            verified=verified,
+            authority_scope=scope,
+            metadata=(
+                {"status": "error", "error_type": type(error).__name__}
+                if error
+                else {"status": "checked"}
+            ),
+        )
+
+
+class _NullContext:
+    def __enter__(self):
+        return None
+
+    def __exit__(self, exc_type, exc, tb):
+        return False

jep_langgraph_adapter-0.1.1/src/jep_langgraph_adapter/tracer.py

@@ -0,0 +1,184 @@
+"""Execution tracer that emits JEP accountability events."""
+
+from __future__ import annotations
+
+import contextvars
+import uuid
+from copy import deepcopy
+from threading import RLock
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Mapping, Optional
+
+from .canonicalization import canonical_hash
+from .events import JEPEvent, JEPEventType
+
+
+@dataclass
+class JEPExecutionTracer:
+    """Collects a deterministic chain of JEP events for a LangGraph run."""
+
+    session_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    default_agent_id: str = "langgraph-agent"
+    default_authority_scope: Mapping[str, Any] = field(default_factory=dict)
+    events: List[JEPEvent] = field(default_factory=list)
+    _lock: Any = field(default_factory=RLock, repr=False)
+    _delegation_hash: Any = field(
+        default_factory=lambda: contextvars.ContextVar(
+            "jep_delegation_hash", default=None
+        ),
+        repr=False,
+    )
+
+    @property
+    def previous_event_hash(self) -> Optional[str]:
+        return self.events[-1].hash() if self.events else None
+
+    def record_judgment(
+        self,
+        *,
+        node_name: str,
+        agent_id: Optional[str],
+        input_state: Any,
+        authority_scope: Optional[Mapping[str, Any]] = None,
+        metadata: Optional[Mapping[str, Any]] = None,
+    ) -> JEPEvent:
+        return self._append(
+            JEPEventType.JUDGMENT,
+            node_name=node_name,
+            agent_id=agent_id,
+            tool_name=None,
+            state_transition={
+                "phase": "before_node",
+                "input_state_hash": canonical_hash(input_state),
+                "output_state_hash": None,
+            },
+            authority_scope=authority_scope,
+            metadata=metadata,
+        )
+
+    def record_delegation(
+        self,
+        *,
+        node_name: str,
+        agent_id: Optional[str],
+        delegated_to: str,
+        tool_name: Optional[str] = None,
+        state: Any = None,
+        authority_scope: Optional[Mapping[str, Any]] = None,
+        metadata: Optional[Mapping[str, Any]] = None,
+    ) -> JEPEvent:
+        parent_hash = self._delegation_hash.get() or self.previous_event_hash
+        return self._append(
+            JEPEventType.DELEGATION,
+            node_name=node_name,
+            agent_id=agent_id,
+            tool_name=tool_name,
+            state_transition={
+                "phase": "delegation",
+                "state_hash": canonical_hash(state),
+                "delegated_to": delegated_to,
+            },
+            authority_scope=authority_scope,
+            delegation_parent_hash=parent_hash,
+            metadata=metadata,
+        )
+
+    def record_termination(
+        self,
+        *,
+        node_name: str,
+        agent_id: Optional[str],
+        input_state: Any,
+        output_state: Any,
+        authority_scope: Optional[Mapping[str, Any]] = None,
+        metadata: Optional[Mapping[str, Any]] = None,
+    ) -> JEPEvent:
+        return self._append(
+            JEPEventType.TERMINATION,
+            node_name=node_name,
+            agent_id=agent_id,
+            tool_name=None,
+            state_transition={
+                "phase": "after_node",
+                "input_state_hash": canonical_hash(input_state),
+                "output_state_hash": canonical_hash(output_state),
+            },
+            authority_scope=authority_scope,
+            metadata=metadata,
+        )
+
+    def record_verification(
+        self,
+        *,
+        node_name: str,
+        agent_id: Optional[str],
+        tool_name: Optional[str],
+        state: Any,
+        verified: bool,
+        authority_scope: Optional[Mapping[str, Any]] = None,
+        metadata: Optional[Mapping[str, Any]] = None,
+    ) -> JEPEvent:
+        return self._append(
+            JEPEventType.VERIFICATION,
+            node_name=node_name,
+            agent_id=agent_id,
+            tool_name=tool_name,
+            state_transition={
+                "phase": "verification",
+                "state_hash": canonical_hash(state),
+                "verified": verified,
+            },
+            authority_scope=authority_scope,
+            metadata=metadata,
+        )
+
+    def delegation_context(self, delegation_event: JEPEvent):
+        """Return a context manager that records nested events under a delegation hash."""
+
+        class _DelegationContext:
+            def __enter__(self_inner):
+                self_inner.token = self._delegation_hash.set(delegation_event.hash())
+                return delegation_event
+
+            def __exit__(self_inner, exc_type, exc, tb):
+                self._delegation_hash.reset(self_inner.token)
+                return False
+
+        return _DelegationContext()
+
+    def _append(
+        self,
+        event_type: JEPEventType,
+        *,
+        node_name: str,
+        agent_id: Optional[str],
+        tool_name: Optional[str],
+        state_transition: Mapping[str, Any],
+        authority_scope: Optional[Mapping[str, Any]],
+        delegation_parent_hash: Optional[str] = None,
+        metadata: Optional[Mapping[str, Any]] = None,
+    ) -> JEPEvent:
+        with self._lock:
+            event = JEPEvent(
+                event_type=event_type,
+                event_id=f"{self.session_id}:{len(self.events)}",
+                session_id=self.session_id,
+                sequence=len(self.events),
+                node_name=node_name,
+                agent_id=agent_id or self.default_agent_id,
+                tool_name=tool_name,
+                state_transition=deepcopy(dict(state_transition)),
+                authority_scope=deepcopy(
+                    dict(
+                        authority_scope
+                        if authority_scope is not None
+                        else self.default_authority_scope
+                    )
+                ),
+                previous_event_hash=self.previous_event_hash,
+                delegation_parent_hash=delegation_parent_hash,
+                metadata=deepcopy(dict(metadata or {})),
+            )
+            event = JEPEvent.from_mapping(event.payload(include_hash=True))
+            self.events.append(event)
+            return event

jep_langgraph_adapter-0.1.1/src/jep_langgraph_adapter.egg-info/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: jep-langgraph-adapter
+Version: 0.1.1
+Summary: JEP runtime adapter for LangGraph: replayable delegation and verifiable AI accountability semantics.
+Author: JEP
+License: MIT
+Keywords: jep,langgraph,accountability,replay,agent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Provides-Extra: langgraph
+Requires-Dist: langgraph>=0.2; extra == "langgraph"
+
+# jep-langgraph-adapter
+
+JEP runtime adapter for LangGraph: replayable delegation and verifiable AI accountability semantics.
+
+This package instruments LangGraph-style node callables without modifying LangGraph core. Wrapped node execution naturally emits a deterministic, hash-linked JEP accountability chain containing:
+
+- Judgment Event
+- Delegation Event
+- Termination Event
+- Verification Event
+
+Each event records `node_name`, `agent_id`, `tool_name`, `state_transition`, `authority_scope`, and `previous_event_hash`.
+
+## Install
+
+```bash
+pip install -e .
+```
+
+LangGraph is optional for tests and examples because the adapter works at the callable-node boundary:
+
+```bash
+pip install -e '.[langgraph]'
+```
+
+## Usage
+
+```python
+from jep_langgraph_adapter import LangGraphEventAdapter
+
+adapter = LangGraphEventAdapter(
+    session_id="demo-session",
+    agent_id="planner-agent",
+    authority_scope={"tools": ["search"], "max_steps": 3},
+)
+
+def plan(state):
+    return {**state, "plan": "call search"}
+
+wrapped_plan = adapter.wrap_node(plan, node_name="plan")
+next_state = wrapped_plan({"question": "What changed?"})
+adapter.exporter().export_jsonl("session.jsonl")
+```
+
+For a `StateGraph`, add wrapped nodes through `instrument_state_graph`:
+
+```python
+adapter.instrument_state_graph(graph, {"plan": plan, "answer": answer})
+```
+
+## Replay CLI
+
+```bash
+jep-langgraph replay session.jsonl
+```
+
+The replay command validates deterministic event hashes, sequence numbers, and `previous_event_hash` links.
+
+## Components
+
+- `JEPNodeMiddleware`: wraps sync or async LangGraph node callables.
+- `JEPExecutionTracer`: records judgment, delegation, termination, and verification events.
+- `JEPReplayExporter`: exports JSON/JSONL and validates replay chains.
+- `LangGraphEventAdapter`: high-level facade for node and graph instrumentation.
+
+## Examples
+
+- `examples/multi_step_graph.py`: multi-step graph execution.
+- `examples/sub_agent_delegation.py`: sub-agent delegation chain.
+- `examples/tool_invocation_replay.py`: tool invocation verification and replay.
+
+## Runtime and verification notes
+
+See [HARDENING.md](HARDENING.md) for supported behavior, regression checks, and compatibility boundaries.

jep_langgraph_adapter-0.1.1/src/jep_langgraph_adapter.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+README.md
+pyproject.toml
+src/jep_langgraph_adapter/__init__.py
+src/jep_langgraph_adapter/adapter.py
+src/jep_langgraph_adapter/canonicalization.py
+src/jep_langgraph_adapter/cli.py
+src/jep_langgraph_adapter/events.py
+src/jep_langgraph_adapter/exporter.py
+src/jep_langgraph_adapter/middleware.py
+src/jep_langgraph_adapter/tracer.py
+src/jep_langgraph_adapter.egg-info/PKG-INFO
+src/jep_langgraph_adapter.egg-info/SOURCES.txt
+src/jep_langgraph_adapter.egg-info/dependency_links.txt
+src/jep_langgraph_adapter.egg-info/entry_points.txt
+src/jep_langgraph_adapter.egg-info/requires.txt
+src/jep_langgraph_adapter.egg-info/top_level.txt
+tests/test_adapter.py
+tests/test_execution_failures.py

jep_langgraph_adapter-0.1.1/src/jep_langgraph_adapter.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

jep_langgraph_adapter-0.1.1/src/jep_langgraph_adapter.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+jep-langgraph = jep_langgraph_adapter.cli:main

jep_langgraph_adapter-0.1.1/src/jep_langgraph_adapter.egg-info/requires.txt

@@ -0,0 +1,6 @@
+
+[dev]
+pytest>=7.0
+
+[langgraph]
+langgraph>=0.2

jep_langgraph_adapter-0.1.1/src/jep_langgraph_adapter.egg-info/top_level.txt

@@ -0,0 +1 @@
+jep_langgraph_adapter

jep_langgraph_adapter-0.1.1/tests/test_adapter.py

@@ -0,0 +1,58 @@
+from pathlib import Path
+
+from jep_langgraph_adapter import JEPEventType, JEPReplayExporter, LangGraphEventAdapter, canonicalize
+
+
+def test_wrap_node_emits_hash_chain(tmp_path: Path):
+    adapter = LangGraphEventAdapter(session_id="test", agent_id="agent", authority_scope={"scope": "local"})
+
+    def node(state):
+        return {**state, "done": True}
+
+    wrapped = adapter.wrap_node(node, node_name="node_a")
+    assert wrapped({"done": False}) == {"done": True}
+
+    assert [event.event_type for event in adapter.events] == [JEPEventType.JUDGMENT, JEPEventType.TERMINATION]
+    assert adapter.events[0].previous_event_hash is None
+    assert adapter.events[1].previous_event_hash == adapter.events[0].hash()
+    assert adapter.events[0].node_name == "node_a"
+    assert adapter.events[0].agent_id == "agent"
+    assert adapter.events[0].authority_scope == {"scope": "local"}
+
+    path = adapter.exporter().export_jsonl(tmp_path / "session.jsonl")
+    result = JEPReplayExporter.replay_file(path)
+    assert result.valid, result.errors
+
+
+def test_delegation_and_tool_verification_events():
+    adapter = LangGraphEventAdapter(session_id="test", verifier=lambda state: state["value"] == 42)
+
+    def tool(state):
+        return {"value": state["value"] * 2}
+
+    wrapped = adapter.wrap_node(
+        tool,
+        node_name="tool_node",
+        tool_name="double",
+        is_delegation=True,
+        delegated_to="tool-agent",
+    )
+    wrapped({"value": 21})
+
+    assert [event.event_type for event in adapter.events] == [
+        JEPEventType.DELEGATION,
+        JEPEventType.JUDGMENT,
+        JEPEventType.TERMINATION,
+        JEPEventType.VERIFICATION,
+    ]
+    assert adapter.events[0].state_transition["delegated_to"] == "tool-agent"
+    assert adapter.events[1].delegation_parent_hash is None
+    assert adapter.events[3].tool_name == "double"
+    assert adapter.events[3].state_transition["verified"] is True
+    assert JEPReplayExporter.replay(adapter.events).valid
+
+
+def test_canonicalization_is_deterministic():
+    left = {"b": [2, 1], "a": {"z": True}}
+    right = {"a": {"z": True}, "b": [2, 1]}
+    assert canonicalize(left) == canonicalize(right)

jep_langgraph_adapter-0.1.1/tests/test_execution_failures.py

@@ -0,0 +1,58 @@
+import asyncio
+from concurrent.futures import ThreadPoolExecutor
+import pytest
+from jep_langgraph_adapter import LangGraphEventAdapter, JEPEventType
+
+
+def test_tool_without_verifier_is_unchecked():
+    adapter = LangGraphEventAdapter()
+    adapter.wrap_node(lambda s: s, tool_name="echo")({})
+    assert [e.event_type for e in adapter.events] == [JEPEventType.JUDGMENT, JEPEventType.TERMINATION]
+    assert adapter.events[-1].metadata["verification_status"] == "unchecked"
+
+
+def test_failure_closes_event_and_preserves_input_snapshot():
+    adapter = LangGraphEventAdapter()
+    def fail(state):
+        state["value"] = 2
+        raise RuntimeError("failed")
+    with pytest.raises(RuntimeError):
+        adapter.wrap_node(fail)({"value": 1})
+    assert adapter.events[-1].metadata["status"] == "failed"
+    assert adapter.events[0].state_transition["input_state_hash"] == adapter.events[-1].state_transition["input_state_hash"]
+
+
+def test_async_cancellation_and_async_verifier():
+    async def run():
+        cancelled = LangGraphEventAdapter()
+        async def cancel(state):
+            raise asyncio.CancelledError()
+        with pytest.raises(asyncio.CancelledError):
+            await cancelled.wrap_node(cancel)({})
+        assert cancelled.events[-1].metadata["status"] == "cancelled"
+        async def verify(state):
+            await asyncio.sleep(0)
+            return False
+        adapter = LangGraphEventAdapter(verifier=verify)
+        async def node(state):
+            return state
+        await adapter.wrap_node(node)({})
+        assert adapter.events[-1].state_transition["verified"] is False
+    asyncio.run(run())
+
+
+def test_verifier_must_return_boolean_and_errors_are_recorded():
+    adapter = LangGraphEventAdapter(verifier=lambda s: "yes")
+    with pytest.raises(TypeError):
+        adapter.wrap_node(lambda s: s)({})
+    assert adapter.events[-1].state_transition["verified"] is False
+    assert adapter.events[-1].metadata["status"] == "error"
+
+
+def test_parallel_nodes_keep_unique_sequence_and_hash_chain():
+    adapter = LangGraphEventAdapter()
+    node = adapter.wrap_node(lambda s: s)
+    with ThreadPoolExecutor(max_workers=8) as pool:
+        list(pool.map(node, range(40)))
+    assert [e.sequence for e in adapter.events] == list(range(80))
+    assert all(e.previous_event_hash == p.hash() for p, e in zip(adapter.events, adapter.events[1:]))