agenttrafficcop 0.1.0__tar.gz

agenttrafficcop-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,161 @@
+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/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-0.1.0/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))