Python SDK

The official Python SDK for the ARQERA governance API.

pip install arqera

Requirements: Python 3.9+

Quick Start

from arqera import ArqeraClient

client = ArqeraClient(api_key="ak_your_key_here")

# Evaluate a governance decision
result = client.governance.evaluate(
    "email.send",
    description="Send welcome email to new user",
)

if result.passed:
    print("Safe to proceed")
    send_email()
elif result.needs_approval:
    print(f"Needs review: {result.explanation}")
    queue_for_approval()
elif result.blocked:
    print(f"Blocked: {result.explanation}")
    log_blocked()

client.close()

Installation

pip install arqera

Or with your preferred package manager:

# Poetry
poetry add arqera

# PDM
pdm add arqera

# uv
uv add arqera

Client Configuration

from arqera import ArqeraClient

client = ArqeraClient(
    api_key="ak_your_key_here",       # Required
    base_url="https://api.arqera.io",  # Optional (default)
    timeout=30,                        # Request timeout in seconds
)

Environment Variable

The client automatically reads ARQERA_API_KEY from the environment:

import os
os.environ["ARQERA_API_KEY"] = "ak_your_key_here"

client = ArqeraClient()  # Reads from ARQERA_API_KEY

Governance Evaluation

Basic Evaluation

result = client.governance.evaluate(
    "data.read",
    description="Read dashboard metrics",
)

print(result.verdict)       # "proceed", "escalate", or "block"
print(result.explanation)   # Human-readable explanation
print(result.duration_ms)   # Evaluation time in milliseconds
print(result.passed)        # True if verdict is "proceed"

With Context

result = client.governance.evaluate(
    "payment.process",
    description="Process $4,200 vendor payment",
    context={
        "risk_level": "medium",
        "is_irreversible": True,
        "has_approval": True,
        "estimated_cost_usd": 4200,
    },
)

Inspecting Law Evaluations

result = client.governance.evaluate("data.delete", description="Delete user data")

for evaluation in result.evaluations:
    print(f"{evaluation.law_name}: {evaluation.result.value}")
    print(f"  Reason: {evaluation.reason}")
    print(f"  Time: {evaluation.duration_ms:.2f}ms")

Result Properties

Property	Type	Description
result.verdict	str	"proceed", "escalate", or "block"
result.passed	bool	True if verdict is "proceed"
result.needs_approval	bool	True if verdict is "escalate"
result.blocked	bool	True if verdict is "block"
result.explanation	str	Human-readable summary
result.duration_ms	float	Total evaluation time
result.action	str	The action that was evaluated
result.evaluations	list	Per-law evaluation results

Law Evaluation Properties

Property	Type	Description
eval.law_id	str	Law identifier
eval.law_name	str	Human-readable law name
eval.result	LawCheckResult	pass, warn, or fail
eval.reason	str	Why this law passed or failed
eval.details	dict	Additional metadata
eval.duration_ms	float	Evaluation time for this law

Ara Action Execution

Execute governed actions through the Ara agent system:

# Execute an action (governance is checked automatically)
action = client.ara.execute(
    "email.send",
    description="Send weekly status report",
    context={"recipient_count": 8},
)

print(action.id)      # Action ID for tracking
print(action.status)  # "completed", "pending_approval", or "blocked"

Governance as a Decorator

Wrap your functions with governance checks:

def govern(action: str, description: str, **context):
    """Governance gate — raises if blocked."""
    result = client.governance.evaluate(action, description=description, context=context)
    if result.blocked:
        raise PermissionError(f"Blocked by governance: {result.explanation}")
    if result.needs_approval:
        raise PermissionError(f"Needs approval: {result.explanation}")
    return result

# Usage
try:
    govern("ai.generate", "Generate quarterly report", estimated_cost_usd=0.15)
    generate_report()
except PermissionError as e:
    print(f"Governance prevented action: {e}")

Error Handling

from arqera.exceptions import (
    ArqeraAuthError,
    ArqeraRateLimitError,
    ArqeraValidationError,
    ArqeraError,
)

try:
    result = client.governance.evaluate("data.delete")
except ArqeraAuthError:
    print("Invalid or expired API key")
except ArqeraRateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")
except ArqeraValidationError as e:
    print(f"Invalid request: {e.detail}")
except ArqeraError as e:
    print(f"API error: {e}")

Full Example

See the Governed AI Chatbot guide for a complete working example.