agenttrafficcop 0.1.0__py3-none-any.whl

agenttrafficcop/__init__.py

@@ -0,0 +1,57 @@
+"""AgentTrafficCop Python SDK.
+
+A thin, typed client for the AgentTrafficCop governance middleware.
+Use it to route agent-to-agent messages through a running cop instance
+and receive typed exceptions when the circuit breaker trips.
+
+Quick start:
+
+    from agenttrafficcop import Guard
+
+    guard = Guard(url="http://localhost:8000", api_key="your-key")
+
+    try:
+        result = await guard.check(
+            session_id="run-42",
+            sender="coder",
+            recipient="reviewer",
+            payload={"diff": "fix typo"},
+        )
+        print("approved at step", result.step)
+    except LoopDetected as e:
+        print("loop caught:", e.error_code, e.diagnostics)
+
+Public API:
+    Guard              — the async client
+    RouteResult        — the 200 response shape
+    AgentTrafficCopError  — base exception
+    LoopDetected       — repeated or cyclic payload detected
+    StepLimitExceeded  — session hit the step cap
+    SchemaRejected     — server rejected the message schema
+    AuthError          — invalid or missing API key
+    ConnectionError    — could not reach the server
+"""
+
+from .client import Guard, RouteResult
+from .exceptions import (
+    AgentTrafficCopError,
+    AuthError,
+    ConnectionError,
+    LoopDetected,
+    SchemaRejected,
+    StepLimitExceeded,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    "Guard",
+    "RouteResult",
+    "AgentTrafficCopError",
+    "LoopDetected",
+    "StepLimitExceeded",
+    "SchemaRejected",
+    "AuthError",
+    "ConnectionError",
+]

agenttrafficcop/client.py

@@ -0,0 +1,263 @@
+"""The Guard client — the primary user-facing API of the SDK.
+
+Usage:
+
+    from agenttrafficcop import Guard, LoopDetected
+
+    async with Guard(url="http://localhost:8000", api_key="...") as guard:
+        try:
+            result = await guard.check(
+                session_id="run-42",
+                sender="coder",
+                recipient="reviewer",
+                payload={"diff": "fix typo"},
+            )
+            print("approved at step", result.step)
+        except LoopDetected as e:
+            print("loop caught:", e.error_code, e.diagnostics)
+
+The client is async-first. A sync wrapper is intentionally not provided
+in v0.1.0 — agent orchestrators are almost always async, and adding a
+sync path doubles the surface area for bugs.
+
+Multi-loop safety:
+    Some frameworks (notably LangGraph) create child event loops. If a
+    Guard instance is reused across loops, the cached httpx.AsyncClient
+    would be bound to the wrong loop. We detect this and transparently
+    rebuild the client for the currently running loop.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Dict, Optional
+
+import httpx
+
+from .exceptions import (
+    AgentTrafficCopError,
+    AuthError,
+    ConnectionError,
+    exception_from_response,
+)
+from .models import RouteResult
+
+
+class Guard:
+    """Async client for the AgentTrafficCop governance middleware.
+
+    Args:
+        url:      Base URL of the AgentTrafficCop server, e.g.
+                  "http://localhost:8000". No trailing slash required.
+        api_key:  The Bearer token. Must match one of the keys the
+                  server has configured in ATC_API_KEYS.
+        timeout:  Per-request timeout in seconds. Default 10.
+    """
+
+    def __init__(
+        self,
+        url: str,
+        api_key: str,
+        *,
+        timeout: float = 10.0,
+    ) -> None:
+        if not url:
+            raise ValueError("url must not be empty")
+        if not api_key:
+            raise ValueError("api_key must not be empty")
+        if timeout <= 0:
+            raise ValueError("timeout must be positive")
+
+        self._base_url = url.rstrip("/")
+        self._api_key = api_key
+        self._timeout = timeout
+        self._client: Optional[httpx.AsyncClient] = None
+        self._client_loop: Optional[asyncio.AbstractEventLoop] = None
+
+    # --- Lifecycle ----------------------------------------------------------
+
+    async def __aenter__(self) -> "Guard":
+        await self._ensure_client()
+        return self
+
+    async def __aexit__(self, *exc_info: Any) -> None:
+        await self.close()
+
+    async def _ensure_client(self) -> httpx.AsyncClient:
+        """Return an AsyncClient bound to the *current* event loop.
+
+        We detect a loop mismatch (LangGraph and some frameworks create
+        child event loops) and transparently create a fresh client. This
+        keeps the "one client per Guard" optimization for the common case
+        while remaining correct under nested/multiple event loops.
+        """
+        try:
+            current_loop = asyncio.get_running_loop()
+        except RuntimeError:
+            # No running loop — we're being called from sync code. Create
+            # a client anyway; the caller will hit an error on first use
+            # with a clearer message than ours would be.
+            current_loop = None
+
+        if (
+            self._client is not None
+            and not self._client.is_closed
+            and self._client_loop is current_loop
+        ):
+            return self._client
+
+        # Either no client yet, or it's bound to a different loop.
+        # Close the old one if it's still open and its loop is alive.
+        old = self._client
+        if old is not None and not old.is_closed:
+            try:
+                await old.aclose()
+            except RuntimeError:
+                # Old client was bound to a dead loop; drop it.
+                pass
+
+        self._client = httpx.AsyncClient(timeout=self._timeout)
+        self._client_loop = current_loop
+        return self._client
+
+    async def close(self) -> None:
+        """Close the underlying HTTP client. Safe to call multiple times
+        and from any event loop context."""
+        client = self._client
+        self._client = None
+        self._client_loop = None
+        if client is None or client.is_closed:
+            return
+        try:
+            await client.aclose()
+        except RuntimeError:
+            # Client was bound to a loop that has since closed.
+            pass
+
+    # --- Public API ---------------------------------------------------------
+
+    async def check(
+        self,
+        *,
+        session_id: str,
+        sender: str,
+        recipient: str,
+        payload: Dict[str, Any],
+        intent: str = "handoff",
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> RouteResult:
+        """Send one agent-to-agent message through the cop."""
+        body: Dict[str, Any] = {
+            "session_id": session_id,
+            "sender": sender,
+            "recipient": recipient,
+            "intent": intent,
+            "payload": payload,
+        }
+        if metadata is not None:
+            body["metadata"] = metadata
+
+        client = await self._ensure_client()
+
+        try:
+            response = await client.post(
+                f"{self._base_url}/v1/route",
+                headers={"authorization": f"Bearer {self._api_key}"},
+                json=body,
+            )
+        except httpx.RequestError as e:
+            raise ConnectionError(
+                f"Could not reach AgentTrafficCop at {self._base_url}: {e}",
+                error_code="CONNECTION_FAILED",
+                session_id=session_id,
+                diagnostics={"underlying": e.__class__.__name__},
+            ) from e
+
+        if response.status_code == 200:
+            try:
+                parsed = response.json()
+            except ValueError as e:
+                raise AgentTrafficCopError(
+                    "Server returned 200 with a non-JSON body.",
+                    error_code="MALFORMED_RESPONSE",
+                    session_id=session_id,
+                    diagnostics={"body_preview": response.text[:200]},
+                ) from e
+            try:
+                return RouteResult.from_response(parsed)
+            except ValueError as e:
+                raise AgentTrafficCopError(
+                    str(e),
+                    error_code="MALFORMED_RESPONSE",
+                    session_id=session_id,
+                    diagnostics={"body_preview": response.text[:200]},
+                ) from e
+
+        if response.status_code == 401:
+            raise AuthError(
+                "AgentTrafficCop rejected the API key.",
+                error_code="AUTH_INVALID",
+                session_id=session_id,
+                diagnostics={"body_preview": response.text[:200]},
+            )
+
+        if response.status_code == 422:
+            try:
+                parsed = response.json()
+            except ValueError:
+                parsed = {
+                    "error": "UNPARSEABLE_422",
+                    "message": "Server returned 422 with a non-JSON body.",
+                    "session_id": session_id,
+                    "diagnostics": {"body_preview": response.text[:200]},
+                }
+            raise exception_from_response(parsed)
+
+        raise AgentTrafficCopError(
+            f"AgentTrafficCop returned unexpected HTTP "
+            f"{response.status_code}.",
+            error_code="UNEXPECTED_STATUS",
+            session_id=session_id,
+            diagnostics={
+                "status_code": response.status_code,
+                "body_preview": response.text[:200],
+            },
+        )
+
+    # --- Admin utilities ----------------------------------------------------
+
+    async def health(self) -> Dict[str, Any]:
+        """Call GET /health and return the parsed body. No auth required."""
+        client = await self._ensure_client()
+        try:
+            response = await client.get(f"{self._base_url}/health")
+        except httpx.RequestError as e:
+            raise ConnectionError(
+                f"Could not reach AgentTrafficCop at {self._base_url}: {e}",
+                error_code="CONNECTION_FAILED",
+            ) from e
+        response.raise_for_status()
+        return response.json()
+
+    async def reset_session(self, session_id: str) -> bool:
+        """Call DELETE /v1/sessions/{id}. Returns True if the session existed."""
+        client = await self._ensure_client()
+        try:
+            response = await client.delete(
+                f"{self._base_url}/v1/sessions/{session_id}",
+                headers={"authorization": f"Bearer {self._api_key}"},
+            )
+        except httpx.RequestError as e:
+            raise ConnectionError(
+                f"Could not reach AgentTrafficCop at {self._base_url}: {e}",
+                error_code="CONNECTION_FAILED",
+                session_id=session_id,
+            ) from e
+        if response.status_code == 401:
+            raise AuthError(
+                "AgentTrafficCop rejected the API key.",
+                error_code="AUTH_INVALID",
+                session_id=session_id,
+            )
+        response.raise_for_status()
+        return bool(response.json().get("removed", False))

agenttrafficcop/exceptions.py

@@ -0,0 +1,143 @@
+"""Exception hierarchy for the AgentTrafficCop SDK.
+
+Every error the SDK raises inherits from `AgentTrafficCopError`, so a
+caller can write:
+
+    try:
+        await guard.check(...)
+    except AgentTrafficCopError as e:
+        log(e.error_code, e.session_id, e.diagnostics)
+
+The subclasses exist so callers can react to *specific* failures:
+
+    try:
+        await guard.check(...)
+    except LoopDetected:
+        halt_session()
+    except StepLimitExceeded:
+        alert_ops()
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+
+class AgentTrafficCopError(Exception):
+    """Base class for all SDK exceptions.
+
+    Attributes:
+        message:     Human-readable error message.
+        error_code:  Machine-readable code from the server (e.g.
+                     "REPEATED_PAYLOAD_LOOP"). None if the SDK raised
+                     this locally without a server response.
+        session_id:  Session the error relates to, if known.
+        diagnostics: Structured details from the server, if any.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        error_code: Optional[str] = None,
+        session_id: Optional[str] = None,
+        diagnostics: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.error_code = error_code
+        self.session_id = session_id
+        self.diagnostics = diagnostics or {}
+
+    def __repr__(self) -> str:
+        return (
+            f"{self.__class__.__name__}("
+            f"error_code={self.error_code!r}, "
+            f"session_id={self.session_id!r}, "
+            f"message={self.message!r})"
+        )
+
+
+# ---------------------------------------------------------------------------
+# Governance errors (server returned 422 with a known error code)
+# ---------------------------------------------------------------------------
+
+
+class LoopDetected(AgentTrafficCopError):
+    """The circuit breaker tripped on a repeated or cyclic payload.
+
+    The server sets `error_code` to one of:
+        REPEATED_PAYLOAD_LOOP  — same hash seen too many times consecutively
+        CYCLIC_PAYLOAD_LOOP    — short repeating cycle detected (A↔B)
+    """
+
+
+class StepLimitExceeded(AgentTrafficCopError):
+    """The session exceeded the configured maximum number of steps."""
+
+
+class SchemaRejected(AgentTrafficCopError):
+    """The server rejected the message as failing schema validation.
+
+    This means the message didn't match the AgentMessage contract.
+    Usually a client-side bug — the payload was malformed before it
+    was even sent.
+    """
+
+
+# ---------------------------------------------------------------------------
+# Transport / auth errors (server returned 401 or the request failed)
+# ---------------------------------------------------------------------------
+
+
+class AuthError(AgentTrafficCopError):
+    """The server rejected the API key (401).
+
+    Possible causes:
+        * No key configured on the server (fail-closed).
+        * Wrong key sent by the client.
+        * Malformed Authorization header.
+    """
+
+
+class ConnectionError(AgentTrafficCopError):
+    """Could not reach the AgentTrafficCop server.
+
+    Wraps the underlying transport error (httpx.ConnectError,
+    httpx.TimeoutException, etc.) as an SDK-level exception.
+    """
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers (used by the client to map server responses)
+# ---------------------------------------------------------------------------
+
+
+# Map server error codes -> SDK exception classes.
+_ERROR_CODE_MAP = {
+    "REPEATED_PAYLOAD_LOOP": LoopDetected,
+    "CYCLIC_PAYLOAD_LOOP": LoopDetected,
+    "STEP_LIMIT_EXCEEDED": StepLimitExceeded,
+    "SCHEMA_VALIDATION_FAILED": SchemaRejected,
+    "CIRCUIT_BREAKER_TRIPPED": LoopDetected,  # fallback for base breaker
+}
+
+
+def exception_from_response(body: Dict[str, Any]) -> AgentTrafficCopError:
+    """Build the right SDK exception from a 422 response body.
+
+    Falls back to the base class for unknown error codes so the SDK
+    never crashes on a server that adds new codes.
+    """
+    error_code = body.get("error")
+    message = body.get("message", "AgentTrafficCop rejected the message.")
+    session_id = body.get("session_id")
+    diagnostics = body.get("diagnostics") or {}
+
+    exc_class = _ERROR_CODE_MAP.get(error_code, AgentTrafficCopError)
+    return exc_class(
+        message,
+        error_code=error_code,
+        session_id=session_id,
+        diagnostics=diagnostics,
+    )

agenttrafficcop/langgraph.py

@@ -0,0 +1,139 @@
+"""LangGraph integration for AgentTrafficCop.
+
+Wraps a LangGraph node function so that every invocation first asks
+AgentTrafficCop whether the current handoff is allowed.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import logging
+from typing import Any, Awaitable, Callable, Dict, Optional, Union
+
+from .client import Guard
+from .exceptions import AgentTrafficCopError
+
+logger = logging.getLogger("agenttrafficcop.langgraph")
+
+StateT = Dict[str, Any]
+NodeFn = Callable[[StateT], Union[Optional[StateT], Awaitable[Optional[StateT]]]]
+ValueOrExtractor = Union[str, Callable[[StateT], Any]]
+
+_AUTO_PAYLOAD_EXCLUDE = frozenset(
+    {"messages", "history", "trace", "logs"}
+)
+
+
+def _resolve(value: ValueOrExtractor, state: StateT, *, name: str) -> Any:
+    if callable(value):
+        try:
+            return value(state)
+        except Exception as e:
+            raise RuntimeError(
+                f"AgentTrafficCop: {name} extractor raised on state: {e}"
+            ) from e
+    return value
+
+
+def _default_payload(state: StateT) -> Dict[str, Any]:
+    return {k: v for k, v in state.items() if k not in _AUTO_PAYLOAD_EXCLUDE}
+
+
+def guarded_node(
+    node_fn: NodeFn,
+    *,
+    guard: Guard,
+    sender: str,
+    recipient: str,
+    session_id: ValueOrExtractor = "session_id",
+    payload: Optional[ValueOrExtractor] = None,
+    intent: str = "handoff",
+    metadata: Optional[ValueOrExtractor] = None,
+    raise_on_trip: bool = True,
+) -> NodeFn:
+    if not callable(node_fn):
+        raise TypeError("node_fn must be callable")
+
+    is_async = inspect.iscoroutinefunction(node_fn)
+
+    async def _check(state: StateT) -> bool:
+        """Return True if the node should run, False if it should be skipped.
+
+        - With raise_on_trip=True, a trip raises out of this function.
+        - With raise_on_trip=False, a trip returns False and the caller
+          must skip the underlying node.
+        """
+        sid = _resolve(session_id, state, name="session_id")
+        if payload is None:
+            pld = _default_payload(state)
+        else:
+            pld = _resolve(payload, state, name="payload")
+        md = _resolve(metadata, state, name="metadata") if metadata is not None else None
+
+        if not isinstance(sid, str) or not sid:
+            raise ValueError(
+                "AgentTrafficCop: session_id resolved to an empty/invalid value"
+            )
+        if not isinstance(pld, dict):
+            raise ValueError(
+                "AgentTrafficCop: payload must resolve to a dict, got "
+                f"{type(pld).__name__}"
+            )
+
+        try:
+            await guard.check(
+                session_id=sid,
+                sender=sender,
+                recipient=recipient,
+                payload=pld,
+                intent=intent,
+                metadata=md,
+            )
+            return True
+        except AgentTrafficCopError as e:
+            if raise_on_trip:
+                logger.warning(
+                    "langgraph_node_tripped node=%s session=%s error_code=%s",
+                    getattr(node_fn, "__name__", repr(node_fn)),
+                    sid,
+                    e.error_code,
+                )
+                raise
+            logger.info(
+                "langgraph_node_skipped node=%s session=%s error_code=%s",
+                getattr(node_fn, "__name__", repr(node_fn)),
+                sid,
+                e.error_code,
+            )
+            return False
+
+    if is_async:
+        async def _wrapped_async(state: StateT) -> Any:
+            should_run = await _check(state)
+            if not should_run:
+                return None
+            return await node_fn(state)
+
+        _wrapped_async.__name__ = getattr(node_fn, "__name__", "guarded_node")
+        _wrapped_async.__doc__ = node_fn.__doc__
+        return _wrapped_async
+
+    def _wrapped_sync(state: StateT) -> Any:
+        try:
+            asyncio.get_running_loop()
+        except RuntimeError:
+            should_run = asyncio.run(_check(state))
+        else:
+            raise RuntimeError(
+                "guarded_node: sync node called inside a running event loop. "
+                "Either make your node async, or use raise_on_trip=False. "
+                "AgentTrafficCop's Guard is async-only by design."
+            )
+        if not should_run:
+            return None
+        return node_fn(state)
+
+    _wrapped_sync.__name__ = getattr(node_fn, "__name__", "guarded_node")
+    _wrapped_sync.__doc__ = node_fn.__doc__
+    return _wrapped_sync

agenttrafficcop/models.py

@@ -0,0 +1,58 @@
+"""Typed models returned by the AgentTrafficCop SDK.
+
+These mirror the response schemas of the server's /v1/route endpoint,
+but live in the SDK so callers get typed attributes and IDE
+autocomplete instead of raw dicts.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict
+
+
+@dataclass(frozen=True)
+class RouteResult:
+    """A successful approval returned by POST /v1/route.
+
+    Attributes:
+        approved:      Always True on success. Present for symmetry with
+                       the server response.
+        session_id:    The session this message belongs to.
+        step:          1-indexed step number this message was assigned.
+        payload_hash:  SHA-256 hex digest of the payload (64 chars).
+        message:       Human-readable confirmation from the server.
+        raw:           The original response dict, in case a caller needs
+                       a field the SDK doesn't model yet.
+    """
+
+    approved: bool
+    session_id: str
+    step: int
+    payload_hash: str
+    message: str
+    raw: Dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_response(cls, body: Dict[str, Any]) -> "RouteResult":
+        """Build a RouteResult from a parsed JSON response body.
+
+        Raises ValueError if required fields are missing or malformed.
+        """
+        try:
+            return cls(
+                approved=bool(body["approved"]),
+                session_id=str(body["session_id"]),
+                step=int(body["step"]),
+                payload_hash=str(body["payload_hash"]),
+                message=str(body.get("message", "")),
+                raw=dict(body),
+            )
+        except KeyError as e:
+            raise ValueError(
+                f"Server response missing required field: {e}"
+            ) from e
+        except (TypeError, ValueError) as e:
+            raise ValueError(
+                f"Server response had an unexpected shape: {e}"
+            ) from e

agenttrafficcop-0.1.0.dist-info/METADATA

@@ -0,0 +1,194 @@
+Metadata-Version: 2.4
+Name: agenttrafficcop
+Version: 0.1.0
+Summary: Python SDK for AgentTrafficCop — a runtime circuit breaker and schema shield for multi-agent systems.
+Author: AgentTrafficCop
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/belalshafeq/Agent_Cop
+Project-URL: Repository, https://github.com/belalshafeq/Agent_Cop
+Project-URL: Issues, https://github.com/belalshafeq/Agent_Cop/issues
+Project-URL: Changelog, https://github.com/belalshafeq/Agent_Cop/blob/main/sdk/CHANGELOG.md
+Keywords: ai,agents,multi-agent,llm,governance,orchestration,circuit-breaker,langgraph,observability
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Distributed Computing
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx<0.28.0,>=0.27.0
+Provides-Extra: langgraph
+Requires-Dist: langgraph<2.0.0,>=1.2.0; extra == "langgraph"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Dynamic: license-file
+
+pip install "agenttrafficcop[langgraph]"
+
+## Quick Start
+
+```python
+import asyncio
+from agenttrafficcop import Guard, LoopDetected
+
+async def main():
+    async with Guard(
+        url="http://localhost:8000",
+        api_key="your-api-key",
+    ) as guard:
+        try:
+            result = await guard.check(
+                session_id="run-42",
+                sender="coder",
+                recipient="reviewer",
+                payload={"diff": "fix typo", "file": "app.py"},
+            )
+            print("approved at step", result.step)
+        except LoopDetected as e:
+            print("loop caught:", e.error_code)
+            print("  session:", e.session_id)
+            print("  step:", e.diagnostics.get("step"))
+
+asyncio.run(main())
+```
+
+## API Reference
+
+### `Guard(url, api_key, *, timeout=10.0)`
+
+Async client. Use as a context manager so the underlying HTTP client
+is closed cleanly.
+
+| Method | Purpose |
+|---|---|
+| `await guard.check(session_id, sender, recipient, payload, intent="handoff", metadata=None)` | Route one message. Returns `RouteResult` on success. |
+| `await guard.health()` | Call `GET /health`. No auth. |
+| `await guard.reset_session(session_id)` | Delete a session. Returns `bool`. |
+| `await guard.close()` | Close the HTTP client. Called by `__aexit__`. |
+
+### `RouteResult`
+
+| Attribute | Type | Meaning |
+|---|---|---|
+| `approved` | `bool` | Always `True` on success. |
+| `session_id` | `str` | Session this message belongs to. |
+| `step` | `int` | 1-indexed step number. |
+| `payload_hash` | `str` | SHA-256 hex digest (64 chars). |
+| `message` | `str` | Human-readable confirmation. |
+| `raw` | `dict` | Original response body. |
+
+### Exceptions
+
+All inherit from `AgentTrafficCopError`:
+
+| Exception | When |
+|---|---|
+| `LoopDetected` | Repeated or cyclic payload. |
+| `StepLimitExceeded` | Session hit the step cap. |
+| `SchemaRejected` | Server rejected the message schema. |
+| `AuthError` | Missing or invalid API key (401). |
+| `ConnectionError` | Could not reach the server. |
+| `AgentTrafficCopError` | Base class — catch this for everything. |
+
+Every exception exposes `.error_code`, `.session_id`, and `.diagnostics`.
+
+## Catching Everything
+
+```python
+try:
+    await guard.check(...)
+except AgentTrafficCopError as e:
+    log.error("governance: %s session=%s", e.error_code, e.session_id)
+    # ... decide what to do
+```
+
+## LangGraph Integration
+
+If you're using [LangGraph](https://langchain-ai.github.io/langgraph/),
+the SDK ships an optional adapter that wraps any node so its handoff
+passes through AgentTrafficCop before the node runs.
+
+### Install the extra
+
+```bash
+pip install -e "./sdk[langgraph]"
+```
+
+### Wrap any node in one line
+
+```python
+from agenttrafficcop import Guard
+from agenttrafficcop.langgraph import guarded_node
+
+guard = Guard(url="http://localhost:8000", api_key="your-key")
+
+graph.add_node(
+    "reviewer",
+    guarded_node(
+        reviewer_fn,
+        guard=guard,
+        sender="coder",
+        recipient="reviewer",
+        # Both of these can be static values OR callables that take
+        # the LangGraph state and return the value.
+        session_id=lambda state: state["run_id"],
+        payload=lambda state: {"draft": state["draft"]},
+    ),
+)
+```
+
+That's it. Every time LangGraph invokes the `reviewer` node,
+AgentTrafficCop sees a handoff. If the breaker trips, the node raises
+before doing any work.
+
+### What if I don't supply `payload=`?
+
+The wrapper falls back to hashing the entire state dict (minus a small
+denylist of known-noise keys like `messages`, `history`, `trace`). This
+works for small graphs, but for real graphs you should supply an
+explicit `payload=` extractor — otherwise a growing message history
+could cause false-positive trips.
+
+### Sync nodes
+
+`guarded_node` supports sync and async node functions. Sync nodes are
+called directly; async nodes are awaited. The guard call itself is
+always async, so if you use a sync node you must call it from a sync
+context (no running event loop). For anything async-first, make the
+node `async def` and everything works.
+
+### Handling trips without raising
+
+By default, a breaker trip raises the SDK exception (e.g.
+`LoopDetected`) and propagates out of the node. If you'd rather handle
+trips via state — for example, to route to a human-review node — pass:
+
+```python
+guarded_node(..., raise_on_trip=False)
+```
+
+The node becomes a no-op on a trip, and the graph continues.
+
+### Full example
+
+See [`examples/langgraph_demo.py`](../examples/langgraph_demo.py)
+for a runnable two-node graph that visibly trips the breaker.
+
+## Compatibility
+
+- Python 3.11+
+- `httpx` 0.27.x
+- LangGraph 1.2.x (optional)
+- Works against any AgentTrafficCop server 1.0.0+
+
+## License
+
+MIT

agenttrafficcop-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+agenttrafficcop/__init__.py,sha256=O4yl3qsrU5FSMgKxuynIRp0LHCMbtRcx6O4aXlULCE8,1537
+agenttrafficcop/client.py,sha256=6q7VuxfAL3L_4tDPva50l-28nEn-NReakTOGbysn5aE,9316
+agenttrafficcop/exceptions.py,sha256=g-hMi-zuBf7Co9miDG938PAhmofXGNoMfdHRl5B-bhg,4564
+agenttrafficcop/langgraph.py,sha256=fzenKuN0H2Etq1RbF2AlEtjOOdqARBSBsr-qiAeugrU,4527
+agenttrafficcop/models.py,sha256=IRD-ayh5acmZR5armeu1TYog23muJpOptrE1_8uKQCc,1993
+agenttrafficcop/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agenttrafficcop-0.1.0.dist-info/licenses/LICENSE,sha256=6xZONMHoPrlWkaq8qqcyvVX1ynl0MShd9irMuBCrrGo,1071
+agenttrafficcop-0.1.0.dist-info/METADATA,sha256=bKtSDCEMyCkeQlNQAXAUwFoI5Oy-6IUVd0Lsho4CUfM,6244
+agenttrafficcop-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+agenttrafficcop-0.1.0.dist-info/top_level.txt,sha256=b-yrJ9FhjQ4FHM21XFyMPUm7cW8aAZKlqvC19H2ArDI,16
+agenttrafficcop-0.1.0.dist-info/RECORD,,

agenttrafficcop-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

agenttrafficcop-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AgentTrafficCop
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agenttrafficcop-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+agenttrafficcop