agp-sdk 0.5.0__tar.gz

agp_sdk-0.5.0/.gitignore

@@ -0,0 +1,7 @@
+**/.DS_Store
+.vscode/
+_site/
+.vercel/
+**/__pycache__/
+**/*.pyc
+.vercel

agp_sdk-0.5.0/PKG-INFO

@@ -0,0 +1,25 @@
+Metadata-Version: 2.4
+Name: agp-sdk
+Version: 0.5.0
+Summary: Python SDK for the Agent Governance Protocol
+Project-URL: Homepage, https://agp.dev
+Project-URL: Repository, https://github.com/cunardai/agp
+Project-URL: Bug Tracker, https://github.com/cunardai/agp/issues
+License: Apache-2.0
+Keywords: accountability,agents,agp,ai,compliance,governance
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.7.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'

agp_sdk-0.5.0/agp/__init__.py

@@ -0,0 +1,79 @@
+"""
+AGP Python SDK — Agent Governance Protocol
+
+https://agp.dev
+"""
+from .client import AGPClient
+from .exceptions import (
+    AGPApprovalRequiredError,
+    AGPBadRequestError,
+    AGPConflictError,
+    AGPConnectionError,
+    AGPError,
+    AGPNotFoundError,
+    AGPPolicyDeniedError,
+    AGPServerError,
+    AGPTokenExpiredError,
+    AGPTokenRevokedError,
+    AGPUnprocessableError,
+)
+from .models import (
+    ActionEnvelope,
+    ApprovalArtifact,
+    AsyncOperation,
+    AttestedContext,
+    CapabilityToken,
+    DecisionRecord,
+    DelegationChain,
+    EscalationNotice,
+    EvidenceBundle,
+    EventLedgerRecord,
+    ExecutionReceipt,
+    GovernanceAttestation,
+    LiabilityBinding,
+    PagedResult,
+    PolicyDecision,
+    PolicySet,
+    RevocationNotice,
+    SkillManifest,
+    Task,
+)
+from .session import TaskSession
+
+__version__ = "0.5.0"
+__all__ = [
+    "AGPClient",
+    "TaskSession",
+    # Exceptions
+    "AGPError",
+    "AGPNotFoundError",
+    "AGPBadRequestError",
+    "AGPConflictError",
+    "AGPUnprocessableError",
+    "AGPPolicyDeniedError",
+    "AGPTokenRevokedError",
+    "AGPTokenExpiredError",
+    "AGPApprovalRequiredError",
+    "AGPConnectionError",
+    "AGPServerError",
+    # Models
+    "Task",
+    "LiabilityBinding",
+    "CapabilityToken",
+    "DelegationChain",
+    "SkillManifest",
+    "PolicySet",
+    "RevocationNotice",
+    "AttestedContext",
+    "EvidenceBundle",
+    "DecisionRecord",
+    "PolicyDecision",
+    "ApprovalArtifact",
+    "EscalationNotice",
+    "ActionEnvelope",
+    "ExecutionReceipt",
+    "EventLedgerRecord",
+    "GovernanceAttestation",
+    "AsyncOperation",
+    "PagedResult",
+]

agp_sdk-0.5.0/agp/client.py

@@ -0,0 +1,124 @@
+"""
+AGP SDK — AGPClient
+
+Top-level entry point. Composes RegistryClient, DecisionClient,
+ExecutionClient, and TaskSession into a single object.
+
+Usage:
+    from agp import AGPClient
+
+    client = AGPClient("http://localhost:8099")
+
+    # High-level session API
+    with client.task_session(
+        principal_id="my-agent",
+        requested_outcome="analyse sentiment",
+        risk_tier="low",
+    ) as session:
+        session.bind(sponsoring_entity="acme", accountable_owner="cto@acme.com",
+                     jurisdiction="EU")
+        session.decide(agent_id="my-agent", selected_action="analyse",
+                       rationale="safe", uncertainty_score=0.05)
+        session.evaluate(verdict="allow")
+        receipt = session.execute(agent_id="my-agent", tool_id="nlp",
+                                  operation={}, capability_token_ref="cap_xxx")
+
+    # Low-level direct API
+    task = client.registry.create_task(...)
+    decision = client.decision.create_decision(...)
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from .decision import DecisionClient
+from .execution import ExecutionClient
+from .http import Transport
+from .models import RiskTier, Task
+from .registry import RegistryClient
+from .session import TaskSession
+
+
+class AGPClient:
+    """
+    Main AGP client. Thread-safe for concurrent use.
+
+    Args:
+        base_url:  URL of the AGP server (e.g. "http://localhost:8099")
+        timeout:   HTTP request timeout in seconds (default 30)
+        headers:   Additional headers to send with every request
+                   (e.g. {"Authorization": "Bearer <token>"})
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        timeout: float = 30.0,
+        headers: dict[str, str] | None = None,
+    ):
+        self._transport = Transport(base_url, timeout=timeout, headers=headers)
+        self.registry  = RegistryClient(self._transport)
+        self.decision  = DecisionClient(self._transport)
+        self.execution = ExecutionClient(self._transport)
+
+    def close(self) -> None:
+        self._transport.close()
+
+    def __enter__(self) -> "AGPClient":
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.close()
+
+    # ── TaskSession factory ────────────────────────────────────────────────
+
+    def task_session(
+        self,
+        *,
+        principal_id: str,
+        requested_outcome: str,
+        risk_tier: RiskTier,
+        expires_at: str | None = None,
+        sponsoring_entity: str | None = None,
+        governance_requirements: dict[str, Any] | None = None,
+        jurisdictions: list[str] | None = None,
+        regulatory_frameworks: list[str] | None = None,
+        idempotency_key: str | None = None,
+    ) -> TaskSession:
+        """
+        Create a new task and return a TaskSession bound to it.
+
+        The session can be used as a context manager — on unhandled exception
+        it will attempt to mark the task FAILED.
+        """
+        task = self.registry.create_task(
+            principal_id=principal_id,
+            requested_outcome=requested_outcome,
+            risk_tier=risk_tier,
+            expires_at=expires_at,
+            sponsoring_entity=sponsoring_entity,
+            governance_requirements=governance_requirements,
+            jurisdictions=jurisdictions,
+            regulatory_frameworks=regulatory_frameworks,
+            idempotency_key=idempotency_key,
+        )
+        return TaskSession(
+            registry=self.registry,
+            decision=self.decision,
+            execution=self.execution,
+            task=task,
+        )
+
+    def resume_session(self, task_id: str) -> TaskSession:
+        """
+        Resume a TaskSession for an existing task (e.g. after a restart
+        or when picking up an APPROVAL_PENDING task from a queue).
+        """
+        task = self.registry.get_task(task_id)
+        return TaskSession(
+            registry=self.registry,
+            decision=self.decision,
+            execution=self.execution,
+            task=task,
+        )

agp_sdk-0.5.0/agp/decision.py

@@ -0,0 +1,181 @@
+"""
+AGP SDK — Decision API client
+
+Wraps: /agp/decision/contexts, /evidence-bundles, /decisions,
+       /policy-evaluations, /approvals, /escalations
+"""
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any
+
+from .http import Transport, new_idempotency_key
+from .models import (
+    ApprovalArtifact, ApprovalDecision, AttestedContext, DecisionRecord,
+    EscalationNotice, EvidenceBundle, PolicyDecision, Verdict,
+)
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+class DecisionClient:
+    def __init__(self, transport: Transport):
+        self._t = transport
+
+    # ── Attested Contexts ──────────────────────────────────────────────────
+
+    def create_context(
+        self,
+        *,
+        task_id: str,
+        trust_class: str,
+        idempotency_key: str | None = None,
+        **extra: Any,
+    ) -> AttestedContext:
+        body = {"task_id": task_id, "trust_class": trust_class,
+                "created_at": _now(), **extra}
+        raw = self._t.post("/agp/decision/contexts", body,
+                           idempotency_key=idempotency_key or new_idempotency_key())
+        return AttestedContext.model_validate(raw)
+
+    def get_context(self, context_id: str) -> AttestedContext:
+        return AttestedContext.model_validate(
+            self._t.get(f"/agp/decision/contexts/{context_id}")
+        )
+
+    # ── Evidence Bundles ───────────────────────────────────────────────────
+
+    def create_evidence_bundle(
+        self,
+        *,
+        task_id: str,
+        items: list[dict[str, Any]],
+        idempotency_key: str | None = None,
+    ) -> EvidenceBundle:
+        body = {"task_id": task_id, "items": items, "created_at": _now()}
+        raw = self._t.post("/agp/decision/evidence-bundles", body,
+                           idempotency_key=idempotency_key or new_idempotency_key())
+        return EvidenceBundle.model_validate(raw)
+
+    # ── Decisions ──────────────────────────────────────────────────────────
+
+    def create_decision(
+        self,
+        *,
+        task_id: str,
+        agent_id: str,
+        selected_action: str,
+        rationale: str,
+        uncertainty_score: float,
+        idempotency_key: str | None = None,
+        **extra: Any,
+    ) -> DecisionRecord:
+        body = {
+            "task_id": task_id,
+            "agent_id": agent_id,
+            "selected_action": selected_action,
+            "rationale": rationale,
+            "uncertainty_score": uncertainty_score,
+            "created_at": _now(),
+            **extra,
+        }
+        raw = self._t.post("/agp/decision/decisions", body,
+                           idempotency_key=idempotency_key or new_idempotency_key())
+        return DecisionRecord.model_validate(raw)
+
+    def get_decision(self, decision_id: str) -> DecisionRecord:
+        return DecisionRecord.model_validate(
+            self._t.get(f"/agp/decision/decisions/{decision_id}")
+        )
+
+    # ── Policy Evaluations ─────────────────────────────────────────────────
+
+    def evaluate_policy(
+        self,
+        *,
+        task_id: str,
+        decision_ref: str,
+        verdict: Verdict,
+        rationale: str | None = None,
+        policy_set_ref: str | None = None,
+        jurisdiction: str | None = None,
+        matched_rules: list[str] | None = None,
+        obligations: list[str] | None = None,
+        idempotency_key: str | None = None,
+    ) -> PolicyDecision:
+        body: dict[str, Any] = {
+            "task_id": task_id,
+            "decision_ref": decision_ref,
+            "verdict": verdict,
+            "evaluated_at": _now(),
+        }
+        if rationale:
+            body["rationale"] = rationale
+        if policy_set_ref:
+            body["policy_set_ref"] = policy_set_ref
+        if jurisdiction:
+            body["jurisdiction"] = jurisdiction
+        if matched_rules:
+            body["matched_rules"] = matched_rules
+        if obligations:
+            body["obligations"] = obligations
+        raw = self._t.post("/agp/decision/policy-evaluations", body,
+                           idempotency_key=idempotency_key or new_idempotency_key())
+        return PolicyDecision.model_validate(raw)
+
+    def get_policy_evaluation(self, policy_evaluation_id: str) -> PolicyDecision:
+        return PolicyDecision.model_validate(
+            self._t.get(f"/agp/decision/policy-evaluations/{policy_evaluation_id}")
+        )
+
+    # ── Approvals ──────────────────────────────────────────────────────────
+
+    def create_approval(
+        self,
+        *,
+        task_id: str,
+        approver_id: str,
+        decision: ApprovalDecision,
+        notes: str | None = None,
+        idempotency_key: str | None = None,
+    ) -> ApprovalArtifact:
+        body: dict[str, Any] = {
+            "task_id": task_id,
+            "approver_id": approver_id,
+            "decision": decision,
+            "approved_at": _now(),
+        }
+        if notes:
+            body["notes"] = notes
+        raw = self._t.post("/agp/decision/approvals", body,
+                           idempotency_key=idempotency_key or new_idempotency_key())
+        return ApprovalArtifact.model_validate(raw)
+
+    def get_approval(self, approval_id: str) -> ApprovalArtifact:
+        return ApprovalArtifact.model_validate(
+            self._t.get(f"/agp/decision/approvals/{approval_id}")
+        )
+
+    # ── Escalations ────────────────────────────────────────────────────────
+
+    def escalate(
+        self,
+        *,
+        task_id: str,
+        raised_by: str,
+        concern_type: str,
+        description: str,
+        idempotency_key: str | None = None,
+    ) -> EscalationNotice:
+        body = {
+            "task_id": task_id,
+            "raised_by": raised_by,
+            "concern_type": concern_type,
+            "description": description,
+            "raised_at": _now(),
+        }
+        raw = self._t.post("/agp/decision/escalations", body,
+                           idempotency_key=idempotency_key or new_idempotency_key())
+        return EscalationNotice.model_validate(raw)

agp_sdk-0.5.0/agp/exceptions.py

@@ -0,0 +1,129 @@
+"""
+AGP SDK — Exception hierarchy
+
+Every AGP error response carries:
+  { "error": { "code": "AGP_*", "message": "..." } }
+
+This module maps HTTP status codes + AGP error codes to typed exceptions
+so callers can catch specific failure modes without parsing raw JSON.
+"""
+from __future__ import annotations
+
+
+class AGPError(Exception):
+    """Base class for all AGP SDK errors."""
+
+    def __init__(self, message: str, code: str = "AGP_ERROR",
+                 http_status: int | None = None, retryable: bool = False):
+        super().__init__(message)
+        self.message = message
+        self.code = code
+        self.http_status = http_status
+        self.retryable = retryable
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}(code={self.code!r}, message={self.message!r})"
+
+
+class AGPNotFoundError(AGPError):
+    """404 — The requested resource does not exist."""
+    def __init__(self, message: str):
+        super().__init__(message, code="AGP_NOT_FOUND", http_status=404)
+
+
+class AGPBadRequestError(AGPError):
+    """400 — Request is malformed or missing required fields."""
+    def __init__(self, message: str, code: str = "AGP_INVALID_REQUEST"):
+        super().__init__(message, code=code, http_status=400)
+
+
+class AGPConflictError(AGPError):
+    """409 — Request conflicts with current resource state."""
+    def __init__(self, message: str, code: str = "AGP_CONFLICT"):
+        super().__init__(message, code=code, http_status=409)
+
+
+class AGPUnprocessableError(AGPError):
+    """422 — Semantically invalid (e.g. illegal state transition)."""
+    def __init__(self, message: str, code: str = "AGP_INVALID_REQUEST"):
+        super().__init__(message, code=code, http_status=422)
+
+
+class AGPPolicyDeniedError(AGPUnprocessableError):
+    """422 AGP_POLICY_DENIED — Execution blocked by policy verdict."""
+    def __init__(self, message: str):
+        super().__init__(message, code="AGP_POLICY_DENIED")
+
+
+class AGPTokenRevokedError(AGPUnprocessableError):
+    """422 AGP_TOKEN_REVOKED — Capability token has been revoked."""
+    def __init__(self, message: str):
+        super().__init__(message, code="AGP_TOKEN_REVOKED")
+
+
+class AGPTokenExpiredError(AGPUnprocessableError):
+    """422 AGP_TOKEN_EXPIRED — Capability token has expired."""
+    def __init__(self, message: str):
+        super().__init__(message, code="AGP_TOKEN_EXPIRED")
+
+
+class AGPApprovalRequiredError(AGPUnprocessableError):
+    """422 AGP_APPROVAL_REQUIRED — Human approval artifact missing or pending."""
+    def __init__(self, message: str):
+        super().__init__(message, code="AGP_APPROVAL_REQUIRED")
+
+
+class AGPServerError(AGPError):
+    """5xx — Server-side error, may be retryable."""
+    def __init__(self, message: str, http_status: int = 500):
+        super().__init__(message, code="AGP_SERVER_ERROR",
+                         http_status=http_status, retryable=True)
+
+
+class AGPConnectionError(AGPError):
+    """Network-level failure reaching the AGP server."""
+    def __init__(self, message: str):
+        super().__init__(message, code="AGP_CONNECTION_ERROR", retryable=True)
+
+
+# ── Error code → exception mapping ────────────────────────────────────────────
+
+_CODE_MAP: dict[str, type[AGPError]] = {
+    "AGP_NOT_FOUND":        AGPNotFoundError,
+    "AGP_POLICY_DENIED":    AGPPolicyDeniedError,
+    "AGP_TOKEN_REVOKED":    AGPTokenRevokedError,
+    "AGP_TOKEN_EXPIRED":    AGPTokenExpiredError,
+    "AGP_APPROVAL_REQUIRED": AGPApprovalRequiredError,
+    "AGP_SCOPE_VIOLATION":  AGPConflictError,
+}
+
+_STATUS_MAP: dict[int, type[AGPError]] = {
+    400: AGPBadRequestError,
+    404: AGPNotFoundError,
+    409: AGPConflictError,
+    422: AGPUnprocessableError,
+}
+
+
+def raise_for_response(status: int, body: dict) -> None:
+    """Parse an AGP error body and raise the appropriate exception."""
+    error = body.get("error", {})
+    code = error.get("code", "AGP_ERROR")
+    message = error.get("message", f"HTTP {status}")
+
+    # Specific code takes priority
+    if code in _CODE_MAP:
+        exc_cls = _CODE_MAP[code]
+        if exc_cls is AGPNotFoundError:
+            raise exc_cls(message)
+        raise exc_cls(message)  # type: ignore[call-arg]
+
+    # Fall back to status code
+    exc_cls_by_status = _STATUS_MAP.get(status)
+    if exc_cls_by_status:
+        raise exc_cls_by_status(message)  # type: ignore[call-arg]
+
+    if status >= 500:
+        raise AGPServerError(message, http_status=status)
+
+    raise AGPError(message, code=code, http_status=status)