agentguard-governance-sdk 0.1.0__tar.gz

agentguard_governance_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 AgentGuard Team
+
+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.

agentguard_governance_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: agentguard-governance-sdk
+Version: 0.1.0
+Summary: Developer SDK for AgentGuard runtime governance and policy enforcement layer
+Author: AgentGuard Team
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/agentguard/agentguard
+Project-URL: Documentation, https://github.com/agentguard/agentguard/tree/main/sdk
+Project-URL: Bug Tracker, https://github.com/agentguard/agentguard/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Security
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: pydantic>=2.0.0
+Dynamic: license-file
+
+# agentguard-governance-sdk
+
+Official Python Developer SDK for the **AgentGuard** runtime governance and policy enforcement layer.
+
+AgentGuard intercepts proposed AI agent tool calls before dispatch, evaluates them against organizational RBAC, risk policies, token/rate limits, and cost budgets, and logs decisions to a cryptographic tamper-evident audit vault.
+
+---
+
+## Installation
+
+```bash
+pip install agentguard-governance-sdk
+```
+
+**Requirements:** Python 3.9+ with `httpx` and `pydantic`.
+
+
+---
+
+## Core Usage
+
+### Standard Exception-Driven Pattern
+
+By default, `client.guard(...)` returns a `GuardResult` on `ALLOW`, and raises structured exceptions when an action is blocked or queued for approval:
+
+```python
+from agentguard import (
+    AgentGuard,
+    AgentGuardDenied,
+    AgentGuardPending,
+    AgentGuardAuthenticationError,
+    AgentGuardTimeout,
+    AgentGuardServerError,
+)
+
+# Initialize client
+client = AgentGuard(
+    api_key="ag_agent_your_key_here",
+    base_url="http://localhost:8000/api/v1",  # Core Engine Gateway URL
+)
+
+try:
+    result = client.guard(
+        tool="read_customer",
+        parameters={"customer_id": "CUST-1001"},
+        estimated_tokens=50,
+        estimated_cost=0.001,
+    )
+    if result.allowed:
+        print(f"Action allowed! Request ID: {result.request_id}")
+        # Safely execute the real tool call here
+
+except AgentGuardDenied as e:
+    # Action was rejected by policy (e.g. CRITICAL risk, unpermitted tool, rate/budget exceeded)
+    print(f"Action DENIED: {e.reason} (request_id={e.request_id})")
+
+except AgentGuardPending as e:
+    # Action requires human-in-the-loop (HITL) approval
+    print(f"Action paused for human approval: {e.reason} (request_id={e.request_id})")
+
+except AgentGuardAuthenticationError as e:
+    print(f"Authentication failed (HTTP {e.status_code}): {e.detail}")
+
+except AgentGuardTimeout as e:
+    print(f"Connection to AgentGuard timed out or was refused: {e}")
+
+except AgentGuardServerError as e:
+    print(f"AgentGuard backend error (HTTP {e.status_code}): {e.detail}")
+
+finally:
+    client.close()
+```
+
+---
+
+### Context Manager Support
+
+`AgentGuard` instances can be managed automatically via a `with` block:
+
+```python
+from agentguard import AgentGuard
+
+with AgentGuard(api_key="ag_agent_...") as client:
+    result = client.guard(tool="send_email", parameters={"to": "user@example.com"})
+    print("Allowed:", result.allowed)
+```
+
+---
+
+### Non-Raising / Boolean Return Mode
+
+Pass `raise_for_status=False` to inspect decisions via the returned `GuardResult` without catching exceptions:
+
+```python
+with AgentGuard(api_key="ag_agent_...") as client:
+    result = client.guard(
+        tool="process_refund",
+        parameters={"amount": 5000},
+        raise_for_status=False,
+    )
+
+    if result.allowed:
+        print("Proceeding with refund...")
+    elif result.decision == "PENDING":
+        print(f"Queued for human review. Request ID: {result.request_id}")
+    elif result.decision == "DENY":
+        print(f"Refund denied: {result.reason}")
+```
+
+---
+
+## API Reference
+
+### `AgentGuard` Constructor
+
+```python
+AgentGuard(
+    api_key: str,
+    base_url: str = "http://localhost:8000/api/v1",
+    agent_id: Optional[Union[uuid.UUID, str]] = None,
+    timeout: float = 5.0,
+    max_retries: int = 1,
+    retry_backoff: float = 0.2,
+    http_client: Optional[httpx.Client] = None,
+)
+```
+
+### `client.guard(...)` Parameters
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `tool` | `str` | *required* | Name of the tool to be executed (e.g. `"read_customer"`). |
+| `parameters` | `dict` | `{}` | Key-value dictionary of arguments for the tool. |
+| `action` | `str` | `"execute"` | Action verb associated with the tool call. |
+| `agent_id` | `UUID \| str` | `None` | Optional override for the requesting agent UUID. |
+| `estimated_tokens` | `int` | `0` | Estimated token usage for sliding-window token rate limiting. |
+| `estimated_cost` | `float` | `0.0` | Estimated monetary spend for budget enforcement. |
+| `metadata` | `dict` | `None` | Custom context or telemetry dictionary attached to audit log. |
+| `timeout` | `float` | `None` | Per-request timeout override in seconds. |
+| `max_retries` | `int` | `None` | Per-request network retry attempts (safe network failures only). |
+| `raise_for_status` | `bool` | `True` | If `True`, raises `AgentGuardDenied` or `AgentGuardPending`. If `False`, returns `GuardResult` with `.allowed=False`. |
+
+### `GuardResult` Object Attributes
+
+- `allowed` (`bool`): `True` if permitted, `False` otherwise.
+- `decision` (`str`): `"ALLOW"`, `"DENY"`, or `"PENDING"`.
+- `request_id` (`str`): Server-generated UUID uniquely tracking this evaluation in the audit vault.
+- `reason` (`str`): Human-readable explanation of policy decision.
+- `raw_response` (`dict`): Raw JSON response dictionary from the gateway.
+
+### Exception Hierarchy
+
+```
+AgentGuardError (Base Exception)
+├── AgentGuardDenied (Action blocked by policy)
+│   ├── reason: str
+│   └── request_id: Optional[str]
+├── AgentGuardPending (Action paused for human approval)
+│   ├── reason: str
+│   └── request_id: Optional[str]
+├── AgentGuardAuthenticationError (HTTP 401/403)
+│   ├── status_code: int
+│   └── detail: Optional[str]
+├── AgentGuardTimeout (Unreachable / network dropped)
+│   └── message: str
+└── AgentGuardServerError (HTTP 5xx / unexpected response)
+    ├── status_code: int
+    ├── detail: Optional[str]
+    └── raw_response: Optional[str]
+```
+

agentguard_governance_sdk-0.1.0/README.md

@@ -0,0 +1,171 @@
+# agentguard-governance-sdk
+
+Official Python Developer SDK for the **AgentGuard** runtime governance and policy enforcement layer.
+
+AgentGuard intercepts proposed AI agent tool calls before dispatch, evaluates them against organizational RBAC, risk policies, token/rate limits, and cost budgets, and logs decisions to a cryptographic tamper-evident audit vault.
+
+---
+
+## Installation
+
+```bash
+pip install agentguard-governance-sdk
+```
+
+**Requirements:** Python 3.9+ with `httpx` and `pydantic`.
+
+
+---
+
+## Core Usage
+
+### Standard Exception-Driven Pattern
+
+By default, `client.guard(...)` returns a `GuardResult` on `ALLOW`, and raises structured exceptions when an action is blocked or queued for approval:
+
+```python
+from agentguard import (
+    AgentGuard,
+    AgentGuardDenied,
+    AgentGuardPending,
+    AgentGuardAuthenticationError,
+    AgentGuardTimeout,
+    AgentGuardServerError,
+)
+
+# Initialize client
+client = AgentGuard(
+    api_key="ag_agent_your_key_here",
+    base_url="http://localhost:8000/api/v1",  # Core Engine Gateway URL
+)
+
+try:
+    result = client.guard(
+        tool="read_customer",
+        parameters={"customer_id": "CUST-1001"},
+        estimated_tokens=50,
+        estimated_cost=0.001,
+    )
+    if result.allowed:
+        print(f"Action allowed! Request ID: {result.request_id}")
+        # Safely execute the real tool call here
+
+except AgentGuardDenied as e:
+    # Action was rejected by policy (e.g. CRITICAL risk, unpermitted tool, rate/budget exceeded)
+    print(f"Action DENIED: {e.reason} (request_id={e.request_id})")
+
+except AgentGuardPending as e:
+    # Action requires human-in-the-loop (HITL) approval
+    print(f"Action paused for human approval: {e.reason} (request_id={e.request_id})")
+
+except AgentGuardAuthenticationError as e:
+    print(f"Authentication failed (HTTP {e.status_code}): {e.detail}")
+
+except AgentGuardTimeout as e:
+    print(f"Connection to AgentGuard timed out or was refused: {e}")
+
+except AgentGuardServerError as e:
+    print(f"AgentGuard backend error (HTTP {e.status_code}): {e.detail}")
+
+finally:
+    client.close()
+```
+
+---
+
+### Context Manager Support
+
+`AgentGuard` instances can be managed automatically via a `with` block:
+
+```python
+from agentguard import AgentGuard
+
+with AgentGuard(api_key="ag_agent_...") as client:
+    result = client.guard(tool="send_email", parameters={"to": "user@example.com"})
+    print("Allowed:", result.allowed)
+```
+
+---
+
+### Non-Raising / Boolean Return Mode
+
+Pass `raise_for_status=False` to inspect decisions via the returned `GuardResult` without catching exceptions:
+
+```python
+with AgentGuard(api_key="ag_agent_...") as client:
+    result = client.guard(
+        tool="process_refund",
+        parameters={"amount": 5000},
+        raise_for_status=False,
+    )
+
+    if result.allowed:
+        print("Proceeding with refund...")
+    elif result.decision == "PENDING":
+        print(f"Queued for human review. Request ID: {result.request_id}")
+    elif result.decision == "DENY":
+        print(f"Refund denied: {result.reason}")
+```
+
+---
+
+## API Reference
+
+### `AgentGuard` Constructor
+
+```python
+AgentGuard(
+    api_key: str,
+    base_url: str = "http://localhost:8000/api/v1",
+    agent_id: Optional[Union[uuid.UUID, str]] = None,
+    timeout: float = 5.0,
+    max_retries: int = 1,
+    retry_backoff: float = 0.2,
+    http_client: Optional[httpx.Client] = None,
+)
+```
+
+### `client.guard(...)` Parameters
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `tool` | `str` | *required* | Name of the tool to be executed (e.g. `"read_customer"`). |
+| `parameters` | `dict` | `{}` | Key-value dictionary of arguments for the tool. |
+| `action` | `str` | `"execute"` | Action verb associated with the tool call. |
+| `agent_id` | `UUID \| str` | `None` | Optional override for the requesting agent UUID. |
+| `estimated_tokens` | `int` | `0` | Estimated token usage for sliding-window token rate limiting. |
+| `estimated_cost` | `float` | `0.0` | Estimated monetary spend for budget enforcement. |
+| `metadata` | `dict` | `None` | Custom context or telemetry dictionary attached to audit log. |
+| `timeout` | `float` | `None` | Per-request timeout override in seconds. |
+| `max_retries` | `int` | `None` | Per-request network retry attempts (safe network failures only). |
+| `raise_for_status` | `bool` | `True` | If `True`, raises `AgentGuardDenied` or `AgentGuardPending`. If `False`, returns `GuardResult` with `.allowed=False`. |
+
+### `GuardResult` Object Attributes
+
+- `allowed` (`bool`): `True` if permitted, `False` otherwise.
+- `decision` (`str`): `"ALLOW"`, `"DENY"`, or `"PENDING"`.
+- `request_id` (`str`): Server-generated UUID uniquely tracking this evaluation in the audit vault.
+- `reason` (`str`): Human-readable explanation of policy decision.
+- `raw_response` (`dict`): Raw JSON response dictionary from the gateway.
+
+### Exception Hierarchy
+
+```
+AgentGuardError (Base Exception)
+├── AgentGuardDenied (Action blocked by policy)
+│   ├── reason: str
+│   └── request_id: Optional[str]
+├── AgentGuardPending (Action paused for human approval)
+│   ├── reason: str
+│   └── request_id: Optional[str]
+├── AgentGuardAuthenticationError (HTTP 401/403)
+│   ├── status_code: int
+│   └── detail: Optional[str]
+├── AgentGuardTimeout (Unreachable / network dropped)
+│   └── message: str
+└── AgentGuardServerError (HTTP 5xx / unexpected response)
+    ├── status_code: int
+    ├── detail: Optional[str]
+    └── raw_response: Optional[str]
+```
+

agentguard_governance_sdk-0.1.0/agentguard/__init__.py

@@ -0,0 +1,27 @@
+"""AgentGuard Python SDK.
+
+Framework-Agnostic Runtime Governance Layer for Autonomous AI Agents.
+"""
+from agentguard.client import AgentGuard
+from agentguard.exceptions import (
+    AgentGuardAuthenticationError,
+    AgentGuardDenied,
+    AgentGuardError,
+    AgentGuardPending,
+    AgentGuardServerError,
+    AgentGuardTimeout,
+)
+from agentguard.models import GuardRequest, GuardResult
+
+__all__ = [
+    "AgentGuard",
+    "GuardRequest",
+    "GuardResult",
+    "AgentGuardError",
+    "AgentGuardDenied",
+    "AgentGuardPending",
+    "AgentGuardAuthenticationError",
+    "AgentGuardTimeout",
+    "AgentGuardServerError",
+]
+__version__ = "0.1.0"

agentguard_governance_sdk-0.1.0/agentguard/client.py

@@ -0,0 +1,120 @@
+"""AgentGuard client for governing autonomous agent tool calls over HTTP."""
+import uuid
+from typing import Any, Optional, Union
+import httpx
+
+from agentguard.guard import evaluate_guard
+from agentguard.models import GuardResult
+
+
+class AgentGuard:
+    """Synchronous client for the AgentGuard Core Engine.
+
+    Usage:
+        client = AgentGuard(api_key="ag_live_...")
+        result = client.guard(tool="read_customer", parameters={"customer_id": "123"})
+        if result.allowed:
+            # execute tool
+            pass
+
+    By default, blocked decisions raise structured exceptions (AgentGuardDenied,
+    AgentGuardPending). Pass `raise_for_status=False` to handle decisions via
+    the boolean `.allowed` attribute instead.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = "http://localhost:8000/api/v1",
+        agent_id: Optional[Union[uuid.UUID, str]] = None,
+        timeout: float = 5.0,
+        max_retries: int = 1,
+        retry_backoff: float = 0.2,
+        http_client: Optional[httpx.Client] = None,
+    ) -> None:
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.agent_id = agent_id
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.retry_backoff = retry_backoff
+
+        self._headers = {
+            "X-API-Key": self.api_key,
+            "Content-Type": "application/json",
+            "User-Agent": "agentguard-python-sdk/0.1.0",
+        }
+
+        self._client = http_client or httpx.Client(timeout=timeout)
+        self._owns_client = http_client is None
+
+    def guard(
+        self,
+        tool: str,
+        parameters: Optional[dict[str, Any]] = None,
+        *,
+        action: str = "execute",
+        agent_id: Optional[Union[uuid.UUID, str]] = None,
+        estimated_tokens: int = 0,
+        estimated_cost: float = 0.0,
+        metadata: Optional[dict[str, Any]] = None,
+        timeout: Optional[float] = None,
+        max_retries: Optional[int] = None,
+        raise_for_status: bool = True,
+    ) -> GuardResult:
+        """Evaluate a proposed tool call through AgentGuard.
+
+        Args:
+            tool: Name of the tool to be executed (e.g. "read_customer").
+            parameters: Key-value parameters intended for the tool.
+            action: Action verb (default: "execute").
+            agent_id: Optional override for the calling agent UUID.
+            estimated_tokens: Estimated token usage for cost enforcement.
+            estimated_cost: Estimated monetary cost for budget caps.
+            metadata: Custom context metadata attached to the request.
+            timeout: Per-request timeout in seconds (overrides client default).
+            max_retries: Per-request network retry attempts.
+            raise_for_status: If True (default), raises AgentGuardDenied or
+                AgentGuardPending. If False, returns GuardResult with .allowed=False.
+
+        Returns:
+            GuardResult with .allowed=True, .decision, .request_id, and .reason.
+
+        Raises:
+            AgentGuardDenied: If policy blocks the action.
+            AgentGuardPending: If action requires human review (HITL).
+            AgentGuardAuthenticationError: If API key is invalid or revoked.
+            AgentGuardTimeout: If the backend is unreachable or times out.
+            AgentGuardServerError: If the backend encounters an internal error.
+        """
+        effective_agent_id = agent_id or self.agent_id
+        effective_timeout = timeout if timeout is not None else self.timeout
+        effective_retries = max_retries if max_retries is not None else self.max_retries
+
+        return evaluate_guard(
+            client=self._client,
+            base_url=self.base_url,
+            headers=self._headers,
+            tool=tool,
+            parameters=parameters or {},
+            action=action,
+            agent_id=effective_agent_id,
+            estimated_tokens=estimated_tokens,
+            estimated_cost=estimated_cost,
+            metadata=metadata,
+            timeout=effective_timeout,
+            max_retries=effective_retries,
+            retry_backoff=self.retry_backoff,
+            raise_for_status=raise_for_status,
+        )
+
+    def close(self) -> None:
+        """Close the underlying HTTP client if owned by this instance."""
+        if self._owns_client and not self._client.is_closed:
+            self._client.close()
+
+    def __enter__(self) -> "AgentGuard":
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        self.close()

agentguard_governance_sdk-0.1.0/agentguard/exceptions.py

@@ -0,0 +1,95 @@
+"""Structured exceptions for the AgentGuard SDK.
+
+All SDK exceptions inherit from AgentGuardError so callers can catch broadly or specifically.
+"""
+from typing import Optional
+
+
+class AgentGuardError(Exception):
+    """Base exception for all AgentGuard SDK errors."""
+    pass
+
+
+class AgentGuardDenied(AgentGuardError):
+    """Raised when a proposed tool call is blocked (DENIED) by AgentGuard governance.
+
+    Attributes:
+        reason: Human-readable explanation of why the action was denied.
+        request_id: Server-assigned UUID tracking the decision in the audit vault.
+    """
+    def __init__(self, reason: str, request_id: Optional[str] = None) -> None:
+        self.reason = reason
+        self.request_id = request_id
+        msg = f"AgentGuard denied tool call: {reason}"
+        if request_id:
+            msg += f" (request_id={request_id})"
+        super().__init__(msg)
+
+
+class AgentGuardPending(AgentGuardError):
+    """Raised when a proposed tool call requires Human-in-the-Loop (HITL) approval (PENDING).
+
+    This is not an unexpected failure; it indicates the agent must pause until a human
+    reviews the request. The request_id can be used to track or poll approval status.
+
+    Attributes:
+        reason: Policy explanation detailing why human review was flagged.
+        request_id: Server-assigned UUID representing the pending HITL request.
+    """
+    def __init__(self, reason: str, request_id: Optional[str] = None) -> None:
+        self.reason = reason
+        self.request_id = request_id
+        msg = f"AgentGuard queued action for human approval: {reason}"
+        if request_id:
+            msg += f" (request_id={request_id})"
+        super().__init__(msg)
+
+
+class AgentGuardAuthenticationError(AgentGuardError):
+    """Raised when the backend rejects client credentials (HTTP 401 Unauthorized or 403 Forbidden).
+
+    Attributes:
+        status_code: HTTP status code received (typically 401 or 403).
+        detail: Error details returned by the backend.
+    """
+    def __init__(self, status_code: int = 401, detail: Optional[str] = None) -> None:
+        self.status_code = status_code
+        self.detail = detail
+        msg = f"AgentGuard authentication failed (HTTP {status_code})"
+        if detail:
+            msg += f": {detail}"
+        super().__init__(msg)
+
+
+class AgentGuardTimeout(AgentGuardError):
+    """Raised when AgentGuard cannot be reached within the configured timeout.
+
+    NOTE: Raised for both connection timeouts and connection refusals — treat as
+    'could not reach the backend', not literally 'timed out'.
+    """
+    def __init__(self, message: str = "Request to AgentGuard timed out or connection refused") -> None:
+        self.message = message
+        super().__init__(message)
+
+
+class AgentGuardServerError(AgentGuardError):
+    """Raised when the AgentGuard backend returns an unexpected 5xx response or unparseable payload.
+
+    Attributes:
+        status_code: HTTP response status code.
+        detail: Backend error detail message if available.
+        raw_response: Raw response body string for debugging.
+    """
+    def __init__(
+        self,
+        status_code: int,
+        detail: Optional[str] = None,
+        raw_response: Optional[str] = None,
+    ) -> None:
+        self.status_code = status_code
+        self.detail = detail
+        self.raw_response = raw_response
+        msg = f"AgentGuard backend error (HTTP {status_code})"
+        if detail:
+            msg += f": {detail}"
+        super().__init__(msg)