agf-sdk 0.1.0__tar.gz

agf_sdk-0.1.0/PKG-INFO

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

@@ -0,0 +1,199 @@
+# 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/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_sdk-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", ""),
+        )