agf-sdk 0.1.0__py3-none-any.whl

agf/__init__.py

@@ -0,0 +1,37 @@
+"""Agent Governance Foundation Python SDK."""
+from .client import AGFClient, Agent, DecisionResult
+from .exceptions import (
+    AGFAuthError,
+    AGFConnectionError,
+    AGFDeniedError,
+    AGFError,
+    AGFReviewRequiredError,
+)
+from .govern import AgentGovernance, AuthResult
+from .sync import SyncAGFClient
+from .webhook import AGFWebhookVerificationError, WebhookEvent, parse_event, verify_signature
+
+__all__ = [
+    # High-level facade (most users start here)
+    "AgentGovernance",
+    "AuthResult",
+    # Async client
+    "AGFClient",
+    "Agent",
+    "DecisionResult",
+    # Sync client
+    "SyncAGFClient",
+    # Exceptions
+    "AGFError",
+    "AGFAuthError",
+    "AGFConnectionError",
+    "AGFDeniedError",
+    "AGFReviewRequiredError",
+    # Webhook
+    "AGFWebhookVerificationError",
+    "WebhookEvent",
+    "verify_signature",
+    "parse_event",
+]
+
+__version__ = "0.1.0"

agf/client.py

@@ -0,0 +1,207 @@
+"""AGF Python SDK — async client."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+import httpx
+
+from .exceptions import AGFAuthError, AGFConnectionError, AGFDeniedError, AGFReviewRequiredError
+
+_DEFAULT_BASE_URL = "https://api.agentgovernancefoundation.com"
+_DEFAULT_TIMEOUT = 15.0
+
+
+@dataclass(frozen=True)
+class DecisionResult:
+    """Returned by :meth:`AGFClient.decide` on an ALLOW decision."""
+    decision: str
+    artifact_id: str
+    trust_score: int
+    risk_score: float
+    policy_version: str
+    chain_depth: int
+    effective_scope: list[str]
+    reasoning: list[str]
+    approval_request_id: str | None = None
+
+
+@dataclass(frozen=True)
+class Agent:
+    id: str
+    org_id: str
+    name: str
+    did: str
+    status: str
+    trust_score: int | None = None
+    created_at: str = ""
+
+
+@dataclass
+class AGFClient:
+    """Async AGF runtime client.
+
+    Args:
+        api_key:  Org-level API key from Settings → API Keys.
+        base_url: Override the default AGF runtime URL.
+        timeout:  HTTP timeout in seconds.
+
+    Example::
+
+        client = AGFClient(api_key="ak_live_...")
+        result = await client.decide(
+            action_type="write:database",
+            resource="prod-customers",
+            chain=[root_jwt, agent_jwt],
+        )
+    """
+
+    api_key: str
+    base_url: str = _DEFAULT_BASE_URL
+    timeout: float = _DEFAULT_TIMEOUT
+    _http: httpx.AsyncClient = field(init=False, repr=False)
+
+    def __post_init__(self) -> None:
+        self._http = httpx.AsyncClient(
+            base_url=self.base_url.rstrip("/"),
+            headers={
+                "X-AGF-Key": self.api_key,
+                "Content-Type": "application/json",
+                "User-Agent": "agf-sdk/0.1.0 python",
+            },
+            timeout=self._timeout_obj,
+        )
+
+    @property
+    def _timeout_obj(self) -> httpx.Timeout:
+        return httpx.Timeout(self.timeout)
+
+    async def __aenter__(self) -> "AGFClient":
+        return self
+
+    async def __aexit__(self, *_: Any) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def _request(self, method: str, path: str, **kwargs: Any) -> dict[str, Any]:
+        try:
+            resp = await self._http.request(method, path, **kwargs)
+        except httpx.ConnectError as exc:
+            raise AGFConnectionError(f"Cannot connect to AGF runtime at {self.base_url}: {exc}") from exc
+        except httpx.TimeoutException as exc:
+            raise AGFConnectionError(f"AGF runtime request timed out: {exc}") from exc
+
+        if resp.status_code == 401:
+            raise AGFAuthError("Invalid API key or suspended organisation.")
+        if resp.status_code == 403:
+            raise AGFAuthError("Insufficient permissions.")
+
+        resp.raise_for_status()
+        return resp.json()  # type: ignore[no-any-return]
+
+    async def decide(
+        self,
+        action_type: str,
+        resource: str,
+        *,
+        chain: list[str] | None = None,
+        audience: str = "agf",
+        context: dict[str, Any] | None = None,
+        policy_version: str | None = None,
+    ) -> DecisionResult:
+        """Evaluate an action against the AGF policy engine.
+
+        Raises:
+            AGFDeniedError:         The PDP issued a DENY decision.
+            AGFReviewRequiredError: The action needs human review (HITL).
+            AGFConnectionError:     Cannot reach the AGF runtime.
+            AGFAuthError:           API key is invalid.
+        """
+        body: dict[str, Any] = {
+            "chain": chain or [],
+            "action": {"type": action_type, "resource": resource},
+            "audience": audience,
+        }
+        if context:
+            body["context"] = context
+        if policy_version:
+            body["policy_version"] = policy_version
+
+        data = await self._request("POST", "/v1/decide", json=body)
+        decision_data = data.get("data", data)
+        decision = decision_data.get("decision", "DENY")
+        artifact_id = decision_data.get("artifact_id", "")
+
+        if decision == "DENY":
+            raise AGFDeniedError(
+                f"Action '{action_type}' on '{resource}' was denied by policy.",
+                artifact_id=artifact_id,
+                risk_score=decision_data.get("risk_score", 0.0),
+                reasoning=decision_data.get("reasoning", []),
+            )
+        if decision == "REVIEW_REQUIRED":
+            raise AGFReviewRequiredError(
+                f"Action '{action_type}' on '{resource}' requires human approval.",
+                approval_request_id=decision_data.get("approval_request_id") or "",
+                artifact_id=artifact_id,
+            )
+
+        return DecisionResult(
+            decision=decision,
+            artifact_id=artifact_id,
+            trust_score=decision_data.get("trust_score", 0),
+            risk_score=decision_data.get("risk_score", 0.0),
+            policy_version=decision_data.get("policy_version", ""),
+            chain_depth=decision_data.get("chain_depth", 0),
+            effective_scope=decision_data.get("effective_scope", []),
+            reasoning=decision_data.get("reasoning", []),
+            approval_request_id=decision_data.get("approval_request_id"),
+        )
+
+    async def list_agents(
+        self,
+        *,
+        status: str | None = None,
+        page: int = 1,
+        per_page: int = 50,
+    ) -> list[Agent]:
+        params: dict[str, Any] = {"page": page, "per_page": per_page}
+        if status:
+            params["status"] = status
+        data = await self._request("GET", "/v1/agents", params=params)
+        items = data.get("items", data) if isinstance(data, dict) else data
+        return [
+            Agent(
+                id=a["id"],
+                org_id=a.get("org_id", ""),
+                name=a.get("name", ""),
+                did=a.get("did", ""),
+                status=a.get("status", "active"),
+                trust_score=a.get("trust_score"),
+                created_at=a.get("created_at", ""),
+            )
+            for a in items
+        ]
+
+    async def register_agent(
+        self,
+        name: str,
+        did: str,
+        public_key_pem: str,
+        metadata: dict[str, Any] | None = None,
+    ) -> Agent:
+        body: dict[str, Any] = {"name": name, "did": did, "public_key_pem": public_key_pem}
+        if metadata:
+            body["metadata"] = metadata
+        a = await self._request("POST", "/v1/agents", json=body)
+        return Agent(
+            id=a["id"],
+            org_id=a.get("org_id", ""),
+            name=a.get("name", name),
+            did=a.get("did", did),
+            status=a.get("status", "active"),
+            trust_score=a.get("trust_score"),
+            created_at=a.get("created_at", ""),
+        )

agf/crewai.py

@@ -0,0 +1,128 @@
+"""CrewAI integration — AGFCrewAITool.
+
+Install extra: pip install agf-sdk[crewai]
+
+In CrewAI, policy enforcement happens at the **Tool** level — the ``Task``
+object has no direct intercept point since execution is driven by the ``Agent``
+runner. Wrap individual tools before assigning them to a CrewAI Agent.
+
+Usage::
+
+    from crewai.tools import BaseTool as CrewBaseTool
+    from agf.crewai import AGFCrewAITool
+    from agf import AGFClient
+
+    client = AGFClient(api_key="ak_live_...")
+
+    class MyDBTool(CrewBaseTool):
+        name: str = "database_query"
+        description: str = "Query the production database"
+
+        def _run(self, query: str) -> str:
+            return db.execute(query)
+
+    guarded = AGFCrewAITool(
+        tool=MyDBTool(),
+        client=client,
+        agent_id="did:agf:crew-researcher",
+        action_type="query:database",
+        resource="prod-db",
+    )
+
+    crew_agent = Agent(tools=[guarded], ...)
+"""
+from __future__ import annotations
+
+import asyncio
+from typing import Any, TYPE_CHECKING
+
+from .exceptions import AGFDeniedError, AGFReviewRequiredError
+
+if TYPE_CHECKING:
+    from .client import AGFClient
+
+try:
+    from crewai.tools import BaseTool as CrewBaseTool  # type: ignore[import]
+except ImportError:
+    try:
+        # Older CrewAI versions re-exported LangChain's BaseTool
+        from langchain_core.tools import BaseTool as CrewBaseTool  # type: ignore[import]
+    except ImportError as exc:
+        raise ImportError(
+            "crewai is required for AGFCrewAITool. "
+            "Install with: pip install agf-sdk[crewai]"
+        ) from exc
+
+
+class AGFCrewAITool(CrewBaseTool):
+    """A CrewAI tool wrapper that enforces AGF policy before execution.
+
+    CrewAI agents call ``_run()`` on tools during task execution. This wrapper
+    intercepts that call, runs an AGF policy check, and only invokes the real
+    tool if the decision is ALLOW.
+
+    Args:
+        tool:        The underlying CrewAI (or LangChain) ``BaseTool`` to guard.
+        client:      An initialised :class:`~agf.client.AGFClient`.
+        agent_id:    DID or identifier for the acting agent.
+        action_type: AGF action type, e.g. ``"query:database"``.
+                     Defaults to ``"tool:<tool_name>"``.
+        resource:    AGF resource string. Defaults to the tool name.
+        chain:       JWT delegation chain passed to ``/v1/decide``.
+        audience:    AGF audience field (default ``"agf"``).
+
+    Raises:
+        AGFDeniedError:         Decision was DENY.
+        AGFReviewRequiredError: Decision was REVIEW_REQUIRED.
+    """
+
+    tool: Any
+    client: Any
+    agent_id: str = ""
+    action_type: str = ""
+    resource: str = ""
+    chain: list[str] = []
+    audience: str = "agf"
+
+    class Config:
+        arbitrary_types_allowed = True
+
+    def model_post_init(self, __context: Any) -> None:
+        if not self.name:
+            object.__setattr__(self, "name", f"agf_guarded_{self.tool.name}")
+        if not self.description:
+            object.__setattr__(self, "description", self.tool.description)
+        if not self.action_type:
+            object.__setattr__(self, "action_type", f"tool:{self.tool.name}")
+        if not self.resource:
+            object.__setattr__(self, "resource", self.tool.name)
+
+    def _run(self, *args: Any, **kwargs: Any) -> Any:
+        """Synchronous execution with AGF policy gate."""
+        self._enforce_sync()
+        return self.tool._run(*args, **kwargs)
+
+    def _enforce_sync(self) -> None:
+        """Run the async policy check synchronously, handling nested loops."""
+        async def _check() -> None:
+            await self.client.decide(
+                self.action_type,
+                self.resource,
+                chain=self.chain or None,
+                audience=self.audience,
+            )
+
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            loop = None
+
+        if loop and loop.is_running():
+            try:
+                import nest_asyncio  # type: ignore[import]
+                nest_asyncio.apply()
+            except ImportError:
+                pass
+            loop.run_until_complete(loop.create_task(_check()))
+        else:
+            asyncio.run(_check())

agf/exceptions.py

@@ -0,0 +1,57 @@
+"""AGF SDK exceptions."""
+from __future__ import annotations
+
+
+class AGFError(Exception):
+    """Base exception for all AGF SDK errors."""
+
+
+class AGFConnectionError(AGFError):
+    """Failed to reach the AGF runtime API."""
+
+
+class AGFAuthError(AGFError):
+    """API key is invalid or the org is suspended."""
+
+
+class AGFDeniedError(AGFError):
+    """The PDP denied the requested action.
+
+    Attributes:
+        artifact_id: Signed audit artifact ID for this decision.
+        risk_score:  Risk score at time of decision (0.0–1.0).
+        reasoning:   List of reasons from the policy engine.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        artifact_id: str = "",
+        risk_score: float = 0.0,
+        reasoning: list[str] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.artifact_id = artifact_id
+        self.risk_score = risk_score
+        self.reasoning = reasoning or []
+
+
+class AGFReviewRequiredError(AGFError):
+    """The action was flagged for human-in-the-loop review.
+
+    Attributes:
+        approval_request_id: The HITL approval request ID.
+        artifact_id:         Signed audit artifact ID.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        approval_request_id: str = "",
+        artifact_id: str = "",
+    ) -> None:
+        super().__init__(message)
+        self.approval_request_id = approval_request_id
+        self.artifact_id = artifact_id

agf/govern.py

@@ -0,0 +1,247 @@
+"""High-level synchronous facade — AgentGovernance.
+
+The primary entry point for most users. Wraps :class:`~agf.sync.SyncAGFClient`
+with a result-based API (no exceptions for deny/review) and convenience methods
+for LangChain and CrewAI integration.
+
+Usage::
+
+    import os
+    from agf import AgentGovernance
+
+    agf = AgentGovernance(
+        api_key=os.environ["AGF_API_KEY"],
+        org_id="org_acme",
+    )
+
+    result = agf.authorize(
+        agent_id="did:agf:agt_01abc",
+        action="file:write",
+        resource="s3://corp-data/q2.csv",
+    )
+
+    if result.allowed:
+        # proceed
+        pass
+    else:
+        raise PermissionError(f"Denied: {result.reason}")
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from .client import AGFClient, Agent, DecisionResult
+from .exceptions import AGFDeniedError, AGFReviewRequiredError
+from .sync import SyncAGFClient
+
+_DEFAULT_BASE_URL = "https://api.agentgovernancefoundation.com"
+
+
+@dataclass(frozen=True)
+class AuthResult:
+    """Returned by :meth:`AgentGovernance.authorize`.
+
+    Attributes:
+        allowed:             True when the PDP issued an ALLOW decision.
+        denied:              True when the PDP issued a DENY decision.
+        review_required:     True when the action needs human review (HITL).
+        reason:              Human-readable denial or review reason.
+        artifact_id:         Signed audit artifact ID.
+        risk_score:          Risk score at time of decision (0.0–1.0).
+        trust_score:         Trust score of the request chain (0–100).
+        approval_request_id: HITL approval request ID (review_required only).
+        policy_version:      Policy version that evaluated the request.
+    """
+
+    allowed: bool
+    denied: bool = False
+    review_required: bool = False
+    reason: str = ""
+    artifact_id: str = ""
+    risk_score: float = 0.0
+    trust_score: int = 0
+    approval_request_id: str = ""
+    policy_version: str = ""
+
+
+class AgentGovernance:
+    """Synchronous AGF client with a result-based authorization API.
+
+    Args:
+        api_key:  Org-level API key from Settings → API Keys.
+        org_id:   Your organisation slug (stored for context; not sent to the API).
+        base_url: Override the default AGF runtime URL.
+        timeout:  HTTP timeout in seconds (default 15).
+
+    Example::
+
+        agf = AgentGovernance(api_key="agfk_...", org_id="org_acme")
+        result = agf.authorize("did:agf:agt_01abc", "file:write", "s3://bucket/file.csv")
+        if result.allowed:
+            write_file()
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        org_id: str = "",
+        base_url: str = _DEFAULT_BASE_URL,
+        timeout: float = 15.0,
+    ) -> None:
+        self.org_id = org_id
+        self._sync = SyncAGFClient(api_key=api_key, base_url=base_url, timeout=timeout)
+
+    def authorize(
+        self,
+        agent_id: str,
+        action: str,
+        resource: str,
+        *,
+        chain: list[str] | None = None,
+        audience: str = "agf",
+        context: dict[str, Any] | None = None,
+    ) -> AuthResult:
+        """Check whether *agent_id* may perform *action* on *resource*.
+
+        Never raises :exc:`~agf.AGFDeniedError` or
+        :exc:`~agf.AGFReviewRequiredError` — check ``result.allowed`` instead.
+
+        Args:
+            agent_id: DID of the acting agent (``did:agf:agt_...``).
+            action:   Action string, e.g. ``"file:write"``.
+            resource: Target resource URI, e.g. ``"s3://bucket/file.csv"``.
+            chain:    Optional JWT delegation chain.
+            audience: AGF audience field (default ``"agf"``).
+            context:  Optional context dict (time_of_day, ip, session_id, …).
+
+        Returns:
+            :class:`AuthResult` — inspect ``.allowed`` before proceeding.
+        """
+        try:
+            result: DecisionResult = self._sync.decide(
+                action_type=action,
+                resource=resource,
+                chain=chain,
+                audience=audience,
+                context=context,
+            )
+            return AuthResult(
+                allowed=True,
+                artifact_id=result.artifact_id,
+                risk_score=result.risk_score,
+                trust_score=result.trust_score,
+                policy_version=result.policy_version,
+            )
+        except AGFDeniedError as exc:
+            return AuthResult(
+                allowed=False,
+                denied=True,
+                reason=str(exc),
+                artifact_id=exc.artifact_id,
+                risk_score=exc.risk_score,
+            )
+        except AGFReviewRequiredError as exc:
+            return AuthResult(
+                allowed=False,
+                review_required=True,
+                reason=str(exc),
+                artifact_id=exc.artifact_id,
+                approval_request_id=exc.approval_request_id,
+            )
+
+    def list_agents(self, *, status: str | None = None, page: int = 1, per_page: int = 50) -> list[Agent]:
+        """List agents in the org. Thin pass-through to the REST API."""
+        return self._sync.list_agents(status=status, page=page, per_page=per_page)
+
+    def register_agent(
+        self,
+        name: str,
+        did: str,
+        public_key_pem: str,
+        metadata: dict[str, Any] | None = None,
+    ) -> Agent:
+        """Register a new agent identity. Thin pass-through to the REST API."""
+        return self._sync.register_agent(name, did, public_key_pem, metadata)
+
+    def langchain_tool(
+        self,
+        agent_id: str,
+        *,
+        audience: str = "agf",
+        chain: list[str] | None = None,
+    ) -> Any:
+        """Return a LangChain ``BaseTool`` that calls AGF before each tool use.
+
+        The returned tool is an *authorization gate* — add it to your agent's
+        tool list and the agent will call it to check access before acting.
+        For per-tool wrapping use :class:`~agf.langchain.AGFGuardedTool` directly.
+
+        Requires ``pip install agf-sdk[langchain]``.
+
+        Args:
+            agent_id: DID of the acting agent.
+            audience: AGF audience field (default ``"agf"``).
+            chain:    Optional JWT delegation chain.
+        """
+        try:
+            from langchain_core.tools import BaseTool  # type: ignore[import]
+        except ImportError as exc:
+            raise ImportError(
+                "langchain-core is required. Install with: pip install agf-sdk[langchain]"
+            ) from exc
+
+        govern = self
+        _agent_id = agent_id
+        _audience = audience
+        _chain = chain
+
+        class _AGFAuthTool(BaseTool):
+            name: str = "agf_authorize"
+            description: str = (
+                "Check whether an action is authorized before executing it. "
+                "Input must be JSON with 'action' and 'resource' keys. "
+                "Always call this before performing sensitive operations."
+            )
+
+            class Config:
+                arbitrary_types_allowed = True
+
+            def _run(self, tool_input: str, **kwargs: Any) -> str:
+                import json
+
+                try:
+                    body = json.loads(tool_input)
+                except Exception:
+                    body = {"action": str(tool_input), "resource": ""}
+
+                result = govern.authorize(
+                    _agent_id,
+                    body.get("action", ""),
+                    body.get("resource", ""),
+                    audience=_audience,
+                    chain=_chain,
+                )
+                if result.allowed:
+                    return f"AUTHORIZED — artifact_id={result.artifact_id}"
+                if result.review_required:
+                    return f"REVIEW_REQUIRED — approval_request_id={result.approval_request_id}"
+                return f"DENIED — {result.reason}"
+
+            async def _arun(self, tool_input: str, **kwargs: Any) -> str:
+                return self._run(tool_input, **kwargs)
+
+        return _AGFAuthTool()
+
+    def async_client(self) -> AGFClient:
+        """Return the underlying async :class:`~agf.client.AGFClient` for advanced use."""
+        return self._sync._async
+
+    def close(self) -> None:
+        self._sync.close()
+
+    def __enter__(self) -> "AgentGovernance":
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.close()

agf/langchain.py

@@ -0,0 +1,124 @@
+"""LangChain integration — AGFGuardedTool.
+
+Install extra: pip install agf-sdk[langchain]
+
+Usage::
+
+    from langchain_community.tools import ShellTool
+    from agf.langchain import AGFGuardedTool
+    from agf import AGFClient
+
+    client = AGFClient(api_key="ak_live_...")
+
+    guarded = AGFGuardedTool(
+        tool=ShellTool(),
+        client=client,
+        agent_id="did:agf:my-assistant",
+        action_type="exec:shell",
+        resource="local-shell",
+        chain=[root_jwt, agent_jwt],   # optional delegation chain
+    )
+
+    # In a LangChain agent, use `guarded` in place of the original tool.
+    result = await guarded.arun("ls -la")
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from .exceptions import AGFDeniedError, AGFReviewRequiredError
+
+if TYPE_CHECKING:
+    from .client import AGFClient
+
+try:
+    from langchain_core.tools import BaseTool
+except ImportError as exc:  # pragma: no cover
+    raise ImportError(
+        "langchain-core is required for AGFGuardedTool. "
+        "Install with: pip install agf-sdk[langchain]"
+    ) from exc
+
+
+class AGFGuardedTool(BaseTool):
+    """A LangChain tool wrapper that enforces AGF policy before execution.
+
+    Both the synchronous ``_run`` and asynchronous ``_arun`` paths are
+    guarded — async LangChain agents invoke ``_arun`` directly and would
+    bypass a guard placed only on ``_run``.
+
+    Args:
+        tool:        The underlying LangChain ``BaseTool`` to guard.
+        client:      An initialised :class:`~agf.client.AGFClient`.
+        agent_id:    DID or identifier for the acting agent.
+        action_type: AGF action type, e.g. ``"tool:shell"``.
+                     Defaults to ``"tool:<tool_name>"``.
+        resource:    AGF resource string. Defaults to the tool name.
+        chain:       JWT delegation chain passed to ``/v1/decide``.
+        audience:    AGF audience field (default ``"agf"``).
+
+    Raises:
+        AGFDeniedError:         Decision was DENY.
+        AGFReviewRequiredError: Decision was REVIEW_REQUIRED.
+    """
+
+    # Pydantic fields — BaseTool is a pydantic BaseModel
+    tool: Any
+    client: Any
+    agent_id: str = ""
+    action_type: str = ""
+    resource: str = ""
+    chain: list[str] = []
+    audience: str = "agf"
+
+    class Config:
+        arbitrary_types_allowed = True
+
+    def model_post_init(self, __context: Any) -> None:
+        # Mirror name/description from the wrapped tool
+        if not self.name:
+            object.__setattr__(self, "name", f"agf_guarded_{self.tool.name}")
+        if not self.description:
+            object.__setattr__(self, "description", self.tool.description)
+        if not self.action_type:
+            object.__setattr__(self, "action_type", f"tool:{self.tool.name}")
+        if not self.resource:
+            object.__setattr__(self, "resource", self.tool.name)
+
+    async def _check_policy(self) -> None:
+        await self.client.decide(
+            self.action_type,
+            self.resource,
+            chain=self.chain or None,
+            audience=self.audience,
+        )
+
+    def _run(self, tool_input: str, **kwargs: Any) -> Any:
+        """Sync path — runs policy check via a new event loop or nest_asyncio."""
+        import asyncio
+
+        loop: asyncio.AbstractEventLoop | None = None
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            pass
+
+        if loop and loop.is_running():
+            # Inside a running loop (e.g. Jupyter) — use nest_asyncio
+            try:
+                import nest_asyncio  # type: ignore[import]
+                nest_asyncio.apply()
+            except ImportError:
+                pass
+            loop.run_until_complete(loop.create_task(self._check_policy()))
+        else:
+            asyncio.run(self._check_policy())
+
+        return self.tool._run(tool_input, **kwargs)
+
+    async def _arun(self, tool_input: str, **kwargs: Any) -> Any:
+        """Async path — called by async LangChain agents."""
+        await self._check_policy()
+        if hasattr(self.tool, "_arun"):
+            return await self.tool._arun(tool_input, **kwargs)
+        return self.tool._run(tool_input, **kwargs)

agf/sync.py

@@ -0,0 +1,111 @@
+"""Synchronous wrappers for AGFClient methods.
+
+For use in non-async contexts (scripts, Jupyter notebooks, Django views, etc.).
+In an already-running event loop, ``nest_asyncio`` is applied automatically
+if available; otherwise a ``RuntimeError`` is raised with instructions.
+
+Usage::
+
+    from agf.sync import SyncAGFClient
+
+    client = SyncAGFClient(api_key="ak_live_...")
+    result = client.decide("write:database", "prod-customers")
+    agents = client.list_agents()
+"""
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+from .client import AGFClient, Agent, DecisionResult
+
+
+def _run_async(coro: Any) -> Any:
+    """Run a coroutine, handling both fresh and running event loops."""
+    try:
+        loop = asyncio.get_running_loop()
+    except RuntimeError:
+        loop = None
+
+    if loop and loop.is_running():
+        try:
+            import nest_asyncio  # type: ignore[import]
+            nest_asyncio.apply()
+            return loop.run_until_complete(coro)
+        except ImportError:
+            raise RuntimeError(
+                "Cannot run synchronous AGF calls inside a running event loop. "
+                "Either use the async AGFClient directly, or install nest_asyncio: "
+                "pip install nest_asyncio"
+            ) from None
+    return asyncio.run(coro)
+
+
+class SyncAGFClient:
+    """Synchronous AGF client — thin wrapper around :class:`~agf.client.AGFClient`.
+
+    Args:
+        api_key:  Org-level API key from Settings → API Keys.
+        base_url: Override the default AGF runtime URL.
+        timeout:  HTTP timeout in seconds.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = "https://api.agentgovernancefoundation.com",
+        timeout: float = 15.0,
+    ) -> None:
+        self._async = AGFClient(api_key=api_key, base_url=base_url, timeout=timeout)
+
+    def decide(
+        self,
+        action_type: str,
+        resource: str,
+        *,
+        chain: list[str] | None = None,
+        audience: str = "agf",
+        context: dict[str, Any] | None = None,
+        policy_version: str | None = None,
+    ) -> DecisionResult:
+        return _run_async(
+            self._async.decide(
+                action_type,
+                resource,
+                chain=chain,
+                audience=audience,
+                context=context,
+                policy_version=policy_version,
+            )
+        )
+
+    def list_agents(
+        self,
+        *,
+        status: str | None = None,
+        page: int = 1,
+        per_page: int = 50,
+    ) -> list[Agent]:
+        return _run_async(
+            self._async.list_agents(status=status, page=page, per_page=per_page)
+        )
+
+    def register_agent(
+        self,
+        name: str,
+        did: str,
+        public_key_pem: str,
+        metadata: dict[str, Any] | None = None,
+    ) -> Agent:
+        return _run_async(
+            self._async.register_agent(name, did, public_key_pem, metadata)
+        )
+
+    def close(self) -> None:
+        _run_async(self._async.aclose())
+
+    def __enter__(self) -> "SyncAGFClient":
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.close()

agf/webhook.py

@@ -0,0 +1,87 @@
+"""AGF webhook payload verification and parsing."""
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+from dataclasses import dataclass
+from typing import Any
+
+
+class AGFWebhookVerificationError(Exception):
+    """Raised when the webhook signature does not match."""
+
+
+@dataclass(frozen=True)
+class WebhookEvent:
+    """A parsed and verified AGF webhook payload.
+
+    Attributes:
+        id:        Unique event ID (``evt_...``).
+        type:      Event type, e.g. ``decision.deny``.
+        org_id:    Organisation that generated the event.
+        timestamp: Unix timestamp of the event.
+        data:      Event-specific payload dict.
+    """
+
+    id: str
+    type: str
+    org_id: str
+    timestamp: int
+    data: dict[str, Any]
+
+    @property
+    def decision(self) -> str | None:
+        return self.data.get("decision")
+
+    @property
+    def artifact_id(self) -> str | None:
+        return self.data.get("artifact_id")
+
+    @property
+    def agent_id(self) -> str | None:
+        return self.data.get("agent_id")
+
+
+def verify_signature(payload: bytes, signature_header: str, secret: str) -> None:
+    """Verify the ``X-AGF-Signature`` header on an incoming webhook request.
+
+    Args:
+        payload:           Raw request body bytes.
+        signature_header:  Value of the ``X-AGF-Signature`` header.
+        secret:            The plaintext webhook secret shown at creation.
+
+    Raises:
+        AGFWebhookVerificationError: Signature is invalid or missing.
+
+    Example (FastAPI)::
+
+        @app.post("/agf-webhook")
+        async def handle(request: Request):
+            body = await request.body()
+            agf.verify_signature(body, request.headers["X-AGF-Signature"], SECRET)
+            event = agf.parse_event(body)
+            ...
+    """
+    if not signature_header.startswith("sha256="):
+        raise AGFWebhookVerificationError("Missing or malformed X-AGF-Signature header.")
+
+    expected_hex = signature_header.removeprefix("sha256=")
+    mac = hmac.new(secret.encode(), payload, hashlib.sha256).hexdigest()
+    if not hmac.compare_digest(mac, expected_hex):
+        raise AGFWebhookVerificationError("Webhook signature mismatch — payload may have been tampered with.")
+
+
+def parse_event(payload: bytes | str) -> WebhookEvent:
+    """Parse raw webhook payload bytes into a :class:`WebhookEvent`.
+
+    Does **not** verify the signature — call :func:`verify_signature` first.
+    """
+    raw = json.loads(payload)
+    return WebhookEvent(
+        id=raw.get("id", ""),
+        type=raw.get("type", ""),
+        org_id=raw.get("org_id", ""),
+        timestamp=raw.get("timestamp", 0),
+        data=raw.get("data", {}),
+    )

agf_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,217 @@
+Metadata-Version: 2.4
+Name: agf-sdk
+Version: 0.1.0
+Summary: Agent Governance Foundation — Python SDK
+Project-URL: Homepage, https://agentgovernancefoundation.com
+Project-URL: Documentation, https://agentgovernancefoundation.com/docs
+License: MIT
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Provides-Extra: all
+Requires-Dist: crewai>=0.28; extra == 'all'
+Requires-Dist: langchain-core>=0.2; extra == 'all'
+Provides-Extra: crewai
+Requires-Dist: crewai>=0.28; extra == 'crewai'
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.2; extra == 'langchain'
+Description-Content-Type: text/markdown
+
+# agf-sdk
+
+Python SDK for the [Agent Governance Foundation](https://agentgovernancefoundation.com) authorization service. Enforce identity, trust, and policy controls on every action your AI agents take.
+
+## Installation
+
+```bash
+pip install agf-sdk
+```
+
+With LangChain support:
+
+```bash
+pip install agf-sdk[langchain]
+```
+
+With CrewAI support:
+
+```bash
+pip install agf-sdk[crewai]
+```
+
+## Quick start
+
+```python
+import os
+from agf import AgentGovernance
+
+agf = AgentGovernance(
+    api_key=os.environ["AGF_API_KEY"],
+    org_id="org_acme",
+)
+
+result = agf.authorize(
+    agent_id="did:agf:agt_01abc",
+    action="file:write",
+    resource="s3://corp-data/q2.csv",
+)
+
+if result.allowed:
+    write_file()
+else:
+    raise PermissionError(f"Denied: {result.reason}")
+```
+
+## Authorization results
+
+`authorize()` never raises for deny/review — it always returns an `AuthResult`:
+
+| Field | Type | Description |
+|---|---|---|
+| `allowed` | `bool` | `True` when the PDP issued ALLOW |
+| `denied` | `bool` | `True` when the PDP issued DENY |
+| `review_required` | `bool` | `True` when HITL approval is needed |
+| `reason` | `str` | Human-readable denial reason |
+| `artifact_id` | `str` | Signed audit artifact ID |
+| `risk_score` | `float` | 0.0–1.0 |
+| `trust_score` | `int` | 0–100 |
+| `approval_request_id` | `str` | HITL request ID (review_required only) |
+
+## Async client
+
+For async frameworks (FastAPI, async Django, etc.) use `AGFClient` directly:
+
+```python
+from agf import AGFClient, AGFDeniedError
+
+async def handle_request():
+    async with AGFClient(api_key="agfk_...") as client:
+        try:
+            result = await client.decide(
+                action_type="file:write",
+                resource="s3://corp-data/q2.csv",
+                chain=[root_jwt, agent_jwt],
+            )
+        except AGFDeniedError as exc:
+            print(f"Denied — artifact: {exc.artifact_id}")
+```
+
+## LangChain integration
+
+### Authorization gate tool (recommended for most agents)
+
+Add an authorization tool to your agent's tool list. The agent calls it before performing sensitive operations:
+
+```python
+from agf import AgentGovernance
+from langchain.agents import initialize_agent, AgentType
+from langchain_openai import ChatOpenAI
+
+agf = AgentGovernance(api_key="agfk_...", org_id="org_acme")
+agf_tool = agf.langchain_tool(agent_id="did:agf:agt_01abc")
+
+agent = initialize_agent(
+    tools=[agf_tool, *your_other_tools],
+    llm=ChatOpenAI(),
+    agent=AgentType.OPENAI_FUNCTIONS,
+)
+```
+
+### Per-tool guard (enforces policy on every tool call)
+
+Wrap individual tools so no call can bypass the policy check:
+
+```python
+from langchain_community.tools import ShellTool
+from agf.langchain import AGFGuardedTool
+from agf import AGFClient
+
+client = AGFClient(api_key="agfk_...")
+
+guarded_shell = AGFGuardedTool(
+    tool=ShellTool(),
+    client=client,
+    agent_id="did:agf:my-assistant",
+    action_type="exec:shell",
+    resource="local-shell",
+)
+```
+
+## CrewAI integration
+
+```python
+from crewai import Agent
+from crewai.tools import BaseTool as CrewBaseTool
+from agf.crewai import AGFCrewAITool
+from agf import AGFClient
+
+client = AGFClient(api_key="agfk_...")
+
+class MyDBTool(CrewBaseTool):
+    name: str = "database_query"
+    description: str = "Query the production database"
+
+    def _run(self, query: str) -> str:
+        return db.execute(query)
+
+guarded = AGFCrewAITool(
+    tool=MyDBTool(),
+    client=client,
+    agent_id="did:agf:crew-researcher",
+    action_type="query:database",
+    resource="prod-db",
+)
+
+crew_agent = Agent(tools=[guarded], ...)
+```
+
+## Webhook verification
+
+```python
+from agf import verify_signature, parse_event, AGFWebhookVerificationError
+
+# FastAPI example
+from fastapi import FastAPI, Request, HTTPException
+
+app = FastAPI()
+
+@app.post("/agf-webhook")
+async def handle(request: Request):
+    body = await request.body()
+    try:
+        verify_signature(body, request.headers["X-AGF-Signature"], WEBHOOK_SECRET)
+    except AGFWebhookVerificationError:
+        raise HTTPException(status_code=400, detail="Invalid signature")
+
+    event = parse_event(body)
+    if event.type == "decision.deny":
+        print(f"Agent {event.agent_id} was denied — artifact {event.artifact_id}")
+```
+
+## Sync client
+
+For scripts, Django views, or any non-async context:
+
+```python
+from agf import SyncAGFClient
+
+with SyncAGFClient(api_key="agfk_...") as client:
+    result = client.decide("file:write", "s3://bucket/file.csv")
+    agents = client.list_agents(status="active")
+```
+
+## Environment variable
+
+Set `AGF_API_KEY` in your environment and pass it via `os.environ["AGF_API_KEY"]`. The SDK does not auto-read environment variables — this keeps the dependency graph minimal and the behaviour explicit.
+
+## Requirements
+
+- Python 3.10+
+- `httpx >= 0.27`
+- `langchain-core >= 0.2` (optional, `agf-sdk[langchain]`)
+- `crewai >= 0.28` (optional, `agf-sdk[crewai]`)
+
+## Links
+
+- [Documentation](https://agentgovernancefoundation.com/docs)
+- [Quick start](https://agentgovernancefoundation.com/docs/quick-start)
+- [API reference](https://agentgovernancefoundation.com/docs/api)

agf_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+agf/__init__.py,sha256=eVQVl8SxtrPlHp1QYbPE0XC0DlV9XDj9afbe0YE_cmc,885
+agf/client.py,sha256=WFucCrlmyGuXBJkwINitjxd-YtN9xkErolOI2tQan7M,6829
+agf/crewai.py,sha256=oN8aWwTms3UG1gpsy5JhTNTi22QDyBgW9yWM1vkhyuM,4249
+agf/exceptions.py,sha256=9p2EXFvZLLvndXmlgt3mxF4DGpYtnN15y2zmoEoADcc,1464
+agf/govern.py,sha256=MMW3lV8LK9e_cOmQTfwI9DgLdVxF1ayMVOtdwhCiBa4,8420
+agf/langchain.py,sha256=oJK_rjtUtB8TAeyjziXUfxH1TfazhlCMwqr-4OJur7s,4192
+agf/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agf/sync.py,sha256=lluv6wCeCKImqor8wuoDuxdC_4T-WamurPZJxBHXU0Q,3177
+agf/webhook.py,sha256=RoLOOBrcWKbQN9o8R-hwY_Krtf4o2_RuBdCCvRESmkU,2682
+agf_sdk-0.1.0.dist-info/METADATA,sha256=qFTOLcgqLwmEwkgTtu7qs9qjg1fIMSz-x8YutZk2ud0,5719
+agf_sdk-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+agf_sdk-0.1.0.dist-info/RECORD,,

agf_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any