acr-sdk 0.1.0__tar.gz

acr_sdk-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+dist/
+*.egg-info/

acr_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,229 @@
+Metadata-Version: 2.4
+Name: acr-sdk
+Version: 0.1.0
+Summary: Python SDK for Agent Capability Runtime — runtime-enforced capability permissions for AI agents
+Project-URL: Homepage, https://github.com/agent-capability-runtime/Agent_Capability_Runtime
+Project-URL: Documentation, https://github.com/agent-capability-runtime/Agent_Capability_Runtime/tree/main/packages/sdk-python
+Project-URL: Repository, https://github.com/agent-capability-runtime/Agent_Capability_Runtime
+Project-URL: Issues, https://github.com/agent-capability-runtime/Agent_Capability_Runtime/issues
+Author: Agent Capability Runtime Contributors
+License-Expression: MIT
+Keywords: ai-agents,authorization,capability-token,governance,runtime
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: langchain
+Requires-Dist: acr-langchain>=0.1.0; extra == 'langchain'
+Description-Content-Type: text/markdown
+
+# ACR Python SDK
+
+**Python client for [Agent Capability Runtime](https://github.com/agent-capability-runtime/Agent_Capability_Runtime)** — runtime-enforced capability permissions for AI agents.
+
+[![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](../../LICENSE)
+
+## Install
+
+From source (PyPI publish pending):
+
+```bash
+cd Agent_Capability_Runtime/packages/sdk-python
+pip install -e ".[dev]"
+```
+
+When published:
+
+```bash
+pip install acr-sdk
+```
+
+## Quick Start
+
+### Embedded mode — zero infrastructure
+
+No gateway, no Docker, no Node. Policy enforcement runs inside your process:
+
+```python
+from acr import LocalAcrClient, can
+
+client = LocalAcrClient()  # in-process runtime
+
+grant = client.grant_sync(
+    can("gmail.send").only_domain("company.com").limit(5).to_grant_input(agent_id="a1")
+)
+
+result = client.execute_sync(
+    token=grant.token, tool="gmail.send",
+    payload={"to": "user@company.com", "subject": "Hello"},
+)
+print(result.decision)  # "ALLOW"
+
+result = client.execute_sync(
+    token=grant.token, tool="gmail.send",
+    payload={"to": "attacker@gmail.com", "subject": "Exfil"},
+)
+print(result.decision)  # "DENY"
+```
+
+Or let the environment decide (gateway when `ACR_GATEWAY_URL` is set, embedded otherwise):
+
+```python
+from acr import create_client
+
+client = create_client()
+```
+
+### Async (FastAPI / LangChain) — gateway mode
+
+```python
+from acr import AcrClient, can
+
+async with AcrClient(base_url="http://localhost:3000") as client:
+    # Grant a scoped capability
+    grant = await client.grant(
+        can("gmail.send")
+        .only_domain("company.com")
+        .limit(5)
+        .expires_in("10m")
+        .to_grant_input(agent_id="support_agent")
+    )
+
+    # Execute — ALLOW (internal domain)
+    result = await client.execute(
+        token=grant.token,
+        tool="gmail.send",
+        payload={"to": "user@company.com", "subject": "Hello"},
+    )
+    print(result.decision)  # "ALLOW"
+
+    # Execute — DENY (external domain blocked)
+    result = await client.execute(
+        token=grant.token,
+        tool="gmail.send",
+        payload={"to": "attacker@gmail.com", "subject": "Exfil"},
+    )
+    print(result.decision)  # "DENY"
+```
+
+### Sync
+
+```python
+from acr import AcrClient, can
+
+client = AcrClient(base_url="http://localhost:3000")
+
+grant = client.grant_sync(
+    can("gmail.send")
+    .only_domain("company.com")
+    .to_grant_input(agent_id="agent_1")
+)
+
+result = client.execute_sync(
+    token=grant.token,
+    tool="gmail.send",
+    payload={"to": "user@company.com", "subject": "Hello"},
+)
+client.close()
+```
+
+## Fluent DSL
+
+The `can()` builder mirrors the TypeScript DSL:
+
+```python
+from acr import can
+
+# Email constraints
+can("gmail.send").only_domain("company.com").limit(5).no_attachments()
+
+# HTTP constraints
+can("http.request").where(method.in_(["GET", "POST"])).where(url.in_(["https://api.example.com"]))
+
+# Spending limit with approval
+can("gmail.send").max_spend(100_00).require_approval()
+
+# Intent-based governance
+can("gmail.send").when_intent("customer_support").when_intent_action("support", "reply")
+
+# Time-based
+can("gmail.send").allowed_hours(9, 17)
+```
+
+## Full API
+
+| Method | Async | Sync |
+|--------|-------|------|
+| Grant capability | `client.grant(input)` | `client.grant_sync(input)` |
+| Execute tool | `client.execute(...)` | `client.execute_sync(...)` |
+| Delegate capability | `client.delegate(parent_token, input)` | `client.delegate_sync(...)` |
+| Revoke capability | `client.revoke(capability_id)` | `client.revoke_sync(...)` |
+| List approvals | `client.list_approvals()` | `client.list_approvals_sync()` |
+| Approve | `client.approve(approval_id)` | `client.approve_sync(...)` |
+| Reject | `client.reject(approval_id)` | `client.reject_sync(...)` |
+| Audit log | `client.list_audit()` | `client.list_audit_sync()` |
+| Verify audit chain | `client.verify_audit_chain()` | `client.verify_audit_chain_sync()` |
+| Health check | `client.health()` | `client.health_sync()` |
+
+## Admin Authentication
+
+```python
+client = AcrClient(
+    base_url="http://localhost:3000",
+    admin_api_key="your-admin-secret",
+)
+```
+
+## LangChain integration
+
+```bash
+pip install "acr-sdk[langchain]"
+```
+
+```python
+from acr import can
+from acr.langchain import protect
+
+tools = protect(my_tools, agent_id="my_agent", policy=can("http.request").limit(50))
+```
+
+See [packages/integrations/langchain](../integrations/langchain).
+
+## Requirements
+
+- Python 3.10+
+- Embedded mode: nothing else
+- Gateway mode: a running ACR gateway (`pnpm dev:gateway`)
+
+## Gateway e2e
+
+With the gateway running:
+
+```bash
+python packages/sdk-python/examples/demo_wow.py   # deny / approval / revoke narrative
+python packages/sdk-python/examples/e2e_gateway.py
+# or
+ACR_RUN_E2E=1 pytest packages/sdk-python/tests/test_e2e_gateway.py -v
+```
+
+## License
+
+MIT — see [LICENSE](../../LICENSE)

acr_sdk-0.1.0/README.md

@@ -0,0 +1,193 @@
+# ACR Python SDK
+
+**Python client for [Agent Capability Runtime](https://github.com/agent-capability-runtime/Agent_Capability_Runtime)** — runtime-enforced capability permissions for AI agents.
+
+[![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](../../LICENSE)
+
+## Install
+
+From source (PyPI publish pending):
+
+```bash
+cd Agent_Capability_Runtime/packages/sdk-python
+pip install -e ".[dev]"
+```
+
+When published:
+
+```bash
+pip install acr-sdk
+```
+
+## Quick Start
+
+### Embedded mode — zero infrastructure
+
+No gateway, no Docker, no Node. Policy enforcement runs inside your process:
+
+```python
+from acr import LocalAcrClient, can
+
+client = LocalAcrClient()  # in-process runtime
+
+grant = client.grant_sync(
+    can("gmail.send").only_domain("company.com").limit(5).to_grant_input(agent_id="a1")
+)
+
+result = client.execute_sync(
+    token=grant.token, tool="gmail.send",
+    payload={"to": "user@company.com", "subject": "Hello"},
+)
+print(result.decision)  # "ALLOW"
+
+result = client.execute_sync(
+    token=grant.token, tool="gmail.send",
+    payload={"to": "attacker@gmail.com", "subject": "Exfil"},
+)
+print(result.decision)  # "DENY"
+```
+
+Or let the environment decide (gateway when `ACR_GATEWAY_URL` is set, embedded otherwise):
+
+```python
+from acr import create_client
+
+client = create_client()
+```
+
+### Async (FastAPI / LangChain) — gateway mode
+
+```python
+from acr import AcrClient, can
+
+async with AcrClient(base_url="http://localhost:3000") as client:
+    # Grant a scoped capability
+    grant = await client.grant(
+        can("gmail.send")
+        .only_domain("company.com")
+        .limit(5)
+        .expires_in("10m")
+        .to_grant_input(agent_id="support_agent")
+    )
+
+    # Execute — ALLOW (internal domain)
+    result = await client.execute(
+        token=grant.token,
+        tool="gmail.send",
+        payload={"to": "user@company.com", "subject": "Hello"},
+    )
+    print(result.decision)  # "ALLOW"
+
+    # Execute — DENY (external domain blocked)
+    result = await client.execute(
+        token=grant.token,
+        tool="gmail.send",
+        payload={"to": "attacker@gmail.com", "subject": "Exfil"},
+    )
+    print(result.decision)  # "DENY"
+```
+
+### Sync
+
+```python
+from acr import AcrClient, can
+
+client = AcrClient(base_url="http://localhost:3000")
+
+grant = client.grant_sync(
+    can("gmail.send")
+    .only_domain("company.com")
+    .to_grant_input(agent_id="agent_1")
+)
+
+result = client.execute_sync(
+    token=grant.token,
+    tool="gmail.send",
+    payload={"to": "user@company.com", "subject": "Hello"},
+)
+client.close()
+```
+
+## Fluent DSL
+
+The `can()` builder mirrors the TypeScript DSL:
+
+```python
+from acr import can
+
+# Email constraints
+can("gmail.send").only_domain("company.com").limit(5).no_attachments()
+
+# HTTP constraints
+can("http.request").where(method.in_(["GET", "POST"])).where(url.in_(["https://api.example.com"]))
+
+# Spending limit with approval
+can("gmail.send").max_spend(100_00).require_approval()
+
+# Intent-based governance
+can("gmail.send").when_intent("customer_support").when_intent_action("support", "reply")
+
+# Time-based
+can("gmail.send").allowed_hours(9, 17)
+```
+
+## Full API
+
+| Method | Async | Sync |
+|--------|-------|------|
+| Grant capability | `client.grant(input)` | `client.grant_sync(input)` |
+| Execute tool | `client.execute(...)` | `client.execute_sync(...)` |
+| Delegate capability | `client.delegate(parent_token, input)` | `client.delegate_sync(...)` |
+| Revoke capability | `client.revoke(capability_id)` | `client.revoke_sync(...)` |
+| List approvals | `client.list_approvals()` | `client.list_approvals_sync()` |
+| Approve | `client.approve(approval_id)` | `client.approve_sync(...)` |
+| Reject | `client.reject(approval_id)` | `client.reject_sync(...)` |
+| Audit log | `client.list_audit()` | `client.list_audit_sync()` |
+| Verify audit chain | `client.verify_audit_chain()` | `client.verify_audit_chain_sync()` |
+| Health check | `client.health()` | `client.health_sync()` |
+
+## Admin Authentication
+
+```python
+client = AcrClient(
+    base_url="http://localhost:3000",
+    admin_api_key="your-admin-secret",
+)
+```
+
+## LangChain integration
+
+```bash
+pip install "acr-sdk[langchain]"
+```
+
+```python
+from acr import can
+from acr.langchain import protect
+
+tools = protect(my_tools, agent_id="my_agent", policy=can("http.request").limit(50))
+```
+
+See [packages/integrations/langchain](../integrations/langchain).
+
+## Requirements
+
+- Python 3.10+
+- Embedded mode: nothing else
+- Gateway mode: a running ACR gateway (`pnpm dev:gateway`)
+
+## Gateway e2e
+
+With the gateway running:
+
+```bash
+python packages/sdk-python/examples/demo_wow.py   # deny / approval / revoke narrative
+python packages/sdk-python/examples/e2e_gateway.py
+# or
+ACR_RUN_E2E=1 pytest packages/sdk-python/tests/test_e2e_gateway.py -v
+```
+
+## License
+
+MIT — see [LICENSE](../../LICENSE)

acr_sdk-0.1.0/acr/__init__.py

@@ -0,0 +1,55 @@
+"""ACR SDK — Python client for Agent Capability Runtime."""
+
+from acr.client import AcrClient
+from acr.dsl import can, domain, method, url, hours, intent, PolicyBuilder
+from acr.exceptions import AcrError, GrantError, ExecuteError, ApprovalError
+from acr.local import LocalAcrClient, create_client
+from acr.models import (
+    ConstraintSet,
+    ExecuteInput,
+    ExecuteResult,
+    ExecuteSuccess,
+    ExecuteDenied,
+    ExecuteApprovalRequired,
+    ExecuteSimulated,
+    GrantCapabilityInput,
+    GrantResponse,
+    ApprovalRequest,
+    AuditEvent,
+    DelegateCapabilityInput,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Client
+    "AcrClient",
+    "LocalAcrClient",
+    "create_client",
+    # DSL
+    "can",
+    "domain",
+    "method",
+    "url",
+    "hours",
+    "intent",
+    "PolicyBuilder",
+    # Exceptions
+    "AcrError",
+    "GrantError",
+    "ExecuteError",
+    "ApprovalError",
+    # Models
+    "ConstraintSet",
+    "ExecuteInput",
+    "ExecuteResult",
+    "ExecuteSuccess",
+    "ExecuteDenied",
+    "ExecuteApprovalRequired",
+    "ExecuteSimulated",
+    "GrantCapabilityInput",
+    "GrantResponse",
+    "ApprovalRequest",
+    "AuditEvent",
+    "DelegateCapabilityInput",
+]

acr_sdk-0.1.0/acr/_jwt.py

@@ -0,0 +1,64 @@
+"""Minimal HS256 JWT encode/decode using only the standard library.
+
+Used by the embedded local runtime (``acr.local``). Tokens are interoperable
+with the gateway's HS256 signing when the same secret is configured.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import json
+from typing import Any
+
+
+def _b64url_encode(data: bytes) -> str:
+    return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")
+
+
+def _b64url_decode(data: str) -> bytes:
+    padding = "=" * (-len(data) % 4)
+    return base64.urlsafe_b64decode(data + padding)
+
+
+def encode_hs256(payload: dict[str, Any], secret: str) -> str:
+    """Sign a JWT payload with HS256."""
+    header = {"alg": "HS256", "typ": "JWT"}
+    header_b64 = _b64url_encode(json.dumps(header, separators=(",", ":")).encode("utf-8"))
+    payload_b64 = _b64url_encode(json.dumps(payload, separators=(",", ":")).encode("utf-8"))
+    signing_input = f"{header_b64}.{payload_b64}".encode("ascii")
+    signature = hmac.new(secret.encode("utf-8"), signing_input, hashlib.sha256).digest()
+    return f"{header_b64}.{payload_b64}.{_b64url_encode(signature)}"
+
+
+def decode_hs256(token: str, secret: str) -> dict[str, Any]:
+    """Verify an HS256 JWT signature and return the payload.
+
+    Raises ValueError for malformed tokens or signature mismatch.
+    Expiry is NOT checked here — callers decide how to surface it.
+    """
+    parts = token.split(".")
+    if len(parts) != 3:
+        raise ValueError("malformed token")
+
+    header_b64, payload_b64, signature_b64 = parts
+    signing_input = f"{header_b64}.{payload_b64}".encode("ascii")
+    expected = hmac.new(secret.encode("utf-8"), signing_input, hashlib.sha256).digest()
+
+    try:
+        actual = _b64url_decode(signature_b64)
+    except Exception as exc:
+        raise ValueError("malformed signature") from exc
+
+    if not hmac.compare_digest(expected, actual):
+        raise ValueError("invalid signature")
+
+    try:
+        payload = json.loads(_b64url_decode(payload_b64))
+    except Exception as exc:
+        raise ValueError("malformed payload") from exc
+
+    if not isinstance(payload, dict):
+        raise ValueError("invalid payload")
+    return payload