SDK API

This is the canonical reference for the Python SDK. For tutorial-style introductions see Quickstart; for framework-specific patterns see the Framework adapters.

`arclasp.init()`

Configure the SDK. Call once at application startup before opening any chains.

arclasp.init(
    api_key: str,
    *,
    environment: str = "production",
    backend_url: str = "http://localhost:8000",
    backend_timeout_seconds: float = 5.0,
    fail_modes: dict[str, str] | None = None,
    fail_mode: str | None = None,
    financial_approval_threshold_usd: float = 5000.0,
    cumulative_financial_threshold_usd: float = 10000.0,
    external_domains_allowlist: list[str] | None = None,
    high_risk_agents: list[str] | None = None,
    default_approval_timeout_hours: float = 24,
    fallback_approvers: list[str] | None = None,
    sensitive_field_patterns: list[str] | None = None,
    sensitive_value_patterns: list[str] | None = None,
    max_payload_string_length: int = 1000,
    enable_local_fast_path: bool = True,
    offline_buffer_max_events: int = 100,
)

Required

Parameter	Type	Description
`api_key`	`str`	Your Arclasp API key, prefixed `prail_`. Treated as a secret.

Common

Parameter	Type	Default	Description
`environment`	`str`	`"production"`	Tag attached to every chain. Common values: `"production"`, `"staging"`, `"development"`.
`backend_url`	`str`	`"http://localhost:8000"`	Defaults to local development. Pass `"https://api.proofrail.dev"` explicitly to reach hosted Arclasp.
`backend_timeout_seconds`	`float`	`5.0`	Per-request timeout when calling the backend. Should be raised for high-latency networks.

Failure handling

Parameter	Type	Default	Description
`fail_modes`	`dict[str, str]`	See Configuration	Per-action-class behavior when the backend is unreachable. Keys are action categories (`financial`, `external_communication`, etc.); values are `"deny"` or `"allow"`. A `default` key sets the fallback for unmatched categories.
`fail_mode`	`str`	None	Legacy single-string parameter. Treated as `{"default": fail_mode}`. Don’t pass both `fail_modes` and `fail_mode`.
`offline_buffer_max_events`	`int`	`100`	Legacy/deprecated compatibility setting. It does not enable offline governed execution in the current backend-authoritative path — a backend-unavailable action raises `BackendUnavailableError` rather than being buffered. Retained only for call-signature compatibility.

Policy thresholds

Parameter	Type	Default	Description
`financial_approval_threshold_usd`	`float`	`5000.0`	Single transactions above this require approval.
`cumulative_financial_threshold_usd`	`float`	`10000.0`	Chain cumulative financial exposure above this requires approval on the next financial action.
`external_domains_allowlist`	`list[str]`	None	Domains agents may communicate with without triggering exfiltration alerts.
`high_risk_agents`	`list[str]`	None	Agent names treated as high-risk; every action by these agents requires approval.
`default_approval_timeout_hours`	`float`	`24`	How long approval requests stay valid before timing out.
`fallback_approvers`	`list[str]`	None	Email addresses that receive escalations if primary approvers don’t respond within half the timeout.

Privacy

Parameter	Type	Default	Description
`sensitive_field_patterns`	`list[str]`	See Sanitization defaults	Field-name substrings that get redacted in payloads sent to the backend. Match is case-insensitive substring against keys.
`sensitive_value_patterns`	`list[str]`	See Sanitization defaults	Value prefixes that get redacted. Match uses `str.startswith()` against string values.
`max_payload_string_length`	`int`	`1000`	Strings longer than this are truncated before being sent.

Performance

Parameter	Type	Default	Description
`enable_local_fast_path`	`bool`	`True`	Deprecated. Setting this to `True` emits a `DeprecationWarning` and has no effect — governed `record_agent_action()` execution always requires backend authority; there is no local decision path. Retained only for call-signature compatibility.

Returns

A ChainConfig instance. Configuration is also stored globally for the process so subsequent arclasp.Chain(...) calls use it.

Sanitization defaults

The SDK uses two separate default lists for redacting sensitive data: sensitive_field_patterns (default — matches against dict keys by case-insensitive substring):

["api_key", "password", "secret", "_token", "credit_card", "ssn", "private_key"]

sensitive_value_patterns (default — matches against string values using str.startswith()):

["sk_", "pk_", "ghp_", "hf_", "eyJ", "AKIA", "prail_"]

Custom patterns you pass via the corresponding kwarg are appended to the defaults.

`arclasp.Chain`

Context manager that opens a chain and records every action within it. Use as an async or sync context manager depending on your code.

class Chain:
    def __init__(
        self,
        name: str,
        metadata: dict | None = None,
        policy_config: dict | None = None,
    ): ...

    async def __aenter__(self) -> "Chain": ...
    async def __aexit__(self, exc_type, exc_val, exc_tb) -> bool: ...

    def __enter__(self) -> "Chain": ...
    def __exit__(self, exc_type, exc_val, exc_tb) -> bool: ...

    def add_financial_threshold(
        self, usd: float, notify: list[str] | None = None, deny: bool = False,
    ) -> None: ...

    async def record_agent_action(...) -> PolicyDecision: ...

Constructor parameters

Parameter	Type	Description
`name`	`str`	Human-readable identifier shown in the dashboard. Conventional: hyphen-separated lowercase (`"vendor-purchase"`, `"customer-onboarding"`).
`metadata`	`dict`	Arbitrary JSON-serializable key/value pairs. Attached to the chain and visible in receipts. Stored as opaque data — the SDK does not interpret keys within it.
`policy_config`	`dict`	Per-chain policy override, merged key-by-key over the org-wide config (chain value wins where set). Build it with `add_financial_threshold()`, or pass the recognized keys directly. Must be set before the chain is started.

Lifecycle

On __aenter__ / __enter__: a chain record is created on the backend; the chain ID is available as chain.chain_id after entry. On __aexit__ / __exit__: the SDK calls POST /v1/chains/{chain_id}/complete, which seals the chain and triggers receipt generation on the backend. If exit was triggered by an exception, the chain is marked accordingly and the receipt reflects the failure mode.

Methods

`record_agent_action()` (async)

async def record_agent_action(
    self,
    agent_name: str,
    action_type: str,
    action_name: str,
    payload: dict | None = None,
    parent_agent_name: str | None = None,
) -> PolicyDecision

Record an action and receive a policy decision. There is no metadata parameter on this method — action-level metadata is not currently supported; chain-level metadata is set once on Chain(...).

Parameter	Type	Description
`agent_name`	`str`	Identifier for the agent taking the action.
`action_type`	`str`	Category of action. Common values: `tool_call`, `llm_call`, `state_update`.
`action_name`	`str`	Specific name within the type. For `tool_call`, the tool name (e.g., `search_web`, `send_email`).
`payload`	`dict`	The action’s inputs. Sanitized before sending.
`parent_agent_name`	`str`	Agent that delegated to this one, if any. Used for tracking hierarchical workflows.

Returns a PolicyDecision object with policy_decision="allow". Blocks until resolution on require_approval (returns allow with decision_source="human_approval" once approved). Raises ActionDeniedError on deny or human denial, ChainTimeoutError if the local polling window expires, and ChainAutoPausedError if the backend halts the chain for a runaway-limit trigger.

`chain.chain_id`

The backend-assigned chain UUID. Available after __aenter__ / __enter__. Useful for logging or cross-system references:

async with arclasp.Chain("workflow") as chain:
    logger.info("Started chain", extra={"chain_id": chain.chain_id})

`arclasp.PolicyDecision`

Returned by record_agent_action when the action is allowed (including after a human approval resolves).

@dataclass
class PolicyDecision:
    policy_decision: str                          # "allow" | "allow_with_flag" | "require_approval" | "deny"
    decision_reason: str = ""
    decision_source: str = "backend_evaluation"
    policy_name: str | None = None
    kill_switch_active: bool = False
    pause_reason: str | None = None
    remediation: str | None = None
    docs_url: str | None = None
    evaluation_mode: str | None = None
    shadow_decision: str | None = None
    estimated_cost_usd: float | None = None
    auto_paused: bool = False

Attribute	Type	Description
`policy_decision`	`str`	The field can hold `"allow"`, `"allow_with_flag"`, `"require_approval"`, or `"deny"` — but `record_agent_action` only ever returns the object with `"allow"` or `"allow_with_flag"` here: it raises on `deny`, and blocks until resolution (then returns with `"allow"`) on `require_approval`.
`decision_reason`	`str`	Human-readable explanation if a policy matched. Empty string when no reason applies.
`decision_source`	`str`	Where the decision came from: `"backend_evaluation"` for a direct policy decision, or `"human_approval"` once a `require_approval` gate has been resolved by a reviewer.
`policy_name`	`str`	Name of the matched policy, if any.
`kill_switch_active`	`bool`	True if the org’s kill switch was found active during evaluation (in which case denials raise `ArclaspKillSwitchError`).
`pause_reason`	`str`	If the org was paused, the reason supplied at activation.
`remediation`	`str`	Suggested fix when a policy matched.
`docs_url`	`str`	Link to docs for this kind of decision.
`evaluation_mode`	`str`	`"enforce"` or `"shadow"` for the matching policy.
`shadow_decision`	`str`	When `evaluation_mode` is `"shadow"`, the decision the policy would have made in enforce mode.
`estimated_cost_usd`	`float`	For LLM call events, the computed cost.
`auto_paused`	`bool`	True if the chain auto-paused at this action (event-count, duration, or token-budget limit).

Framework adapters

Each adapter exposes a govern() function that wraps an existing framework object. See the framework-specific pages for usage details.

`arclasp.langgraph.govern()`

def govern(
    compiled_graph,
    chain_name: str = "langgraph_workflow",
    metadata: dict | None = None,
) -> GovernedGraph

See LangGraph adapter.

`arclasp.langchain.govern()`

def govern(
    agent_executor_or_chain,
    chain_name: str = "langchain_workflow",
    metadata: dict | None = None,
) -> GovernedChain

The agent_name for recorded events is derived from type(executor).__name__ at wrap time — it isn’t a govern() parameter. See LangChain adapter.

`arclasp.crewai.govern()`

def govern(
    crew,
    chain_name: str = "crewai_workflow",
    metadata: dict | None = None,
) -> GovernedCrew

See CrewAI adapter.

`arclasp.mcp.ArclaspMcpAdapter`

class ArclaspMcpAdapter:
    def __init__(
        self,
        chain: arclasp.Chain,       # an already-entered chain
        agent_name: str = "mcp-agent",
        parent_agent_name: str | None = None,
    ): ...

    async def handle_tool_call(self, tool_name: str, arguments: dict, handler) -> Any: ...
    def tool(self, tool_name: str): ...  # decorator
    def install(self, server) -> None: ...  # unsupported — always raises RuntimeError

install() is not supported with mcp >= 1.0 and always raises RuntimeError; it is kept only for signature compatibility. Wire governance through handle_tool_call() inside your own @server.call_tool() handler instead. See MCP adapter.

`arclasp.client.verify_receipt_v2()`

Verify receipt integrity through the authenticated v2 API.

async def verify_receipt_v2(receipt_id: str) -> AuthenticatedReceiptVerificationResponse

Receipt verification is server-attested integrity verification. It is not an independent offline proof export.

`arclasp.client.verify_approval_v2()`

Verify an approval through the authenticated role-aware v2 API.

async def verify_approval_v2(approval_id: str) -> AuthenticatedApprovalVerificationResponse

The response separates integrity, signature, key-trust, timestamp-anchor, and overall status. Member and admin responses differ based on role.

Public verification token helpers

async def list_public_verification_tokens(...) -> PublicVerificationTokenListResponse
async def issue_public_verification_token(...) -> PublicVerificationTokenIssueResponse
async def revoke_public_verification_token(...) -> PublicVerificationTokenRevokeResponse
async def verify_public_token(token: str) -> PublicVerificationTokenVerifyResponse

issue_public_verification_token() returns the plaintext public token once. List and revoke helpers do not return plaintext tokens or token hashes. verify_public_token() calls GET /public/v2/verify/{opaque_token} and raises a sanitized verification error if the token is unavailable.

`arclasp.client.verify_receipt()`

Legacy receipt verification helper.

async def verify_receipt(receipt_id: str) -> ReceiptVerifyResponse

This helper remains temporarily available for compatibility with the legacy GET /v1/receipts/{receipt_id}/verify route and emits a deprecation warning. New callers should use verify_receipt_v2().

See Verification for current verification routes and migration guidance.

Exceptions

All exceptions live in arclasp.exceptions. The base for policy-driven errors is ArclaspPolicyError.

ArclaspPolicyError                # base for policy denials
├── ActionDeniedError               # Policy or human reviewer denied
├── PolicyViolationError            # Policy condition violated outside main eval path
└── ArclaspKillSwitchError        # Org kill switch is active

Exception
├── BackendUnavailableError         # Backend unreachable, fail_mode=deny
├── ChainTimeoutError               # Chain exceeded configured timeout
└── ChainAutoPausedError            # Auto-pause rule fired (events, duration, tokens)

See Exceptions reference for attributes and handling patterns.

Version compatibility

The SDK requires Python 3.10 or later (enforced at install time by pip). Supported framework version ranges are pinned in sdk/pyproject.toml; install Arclasp with a compatible version of your framework already installed. See Limitations for the current compatibility matrix.

Where to go next

Configuration

Detailed walkthrough of every init() option.

Exceptions

All exception types and how to handle them.

Framework adapters

Per-framework usage and edge cases.

Limitations

What Arclasp does and doesn’t do at current version.

​SDK API

​arclasp.init()

​Returns

​Sanitization defaults

​arclasp.Chain

​Constructor parameters

​Lifecycle

​Methods

​record_agent_action() (async)

​chain.chain_id

​arclasp.PolicyDecision

​Framework adapters

​arclasp.langgraph.govern()

​arclasp.langchain.govern()

​arclasp.crewai.govern()

​arclasp.mcp.ArclaspMcpAdapter

​arclasp.client.verify_receipt_v2()

​arclasp.client.verify_approval_v2()

​Public verification token helpers

​arclasp.client.verify_receipt()

​See Verification for current verification routes and migration guidance.

​Exceptions

​Version compatibility

​Where to go next

Configuration

Exceptions

Framework adapters

Limitations

SDK API

`arclasp.init()`

Returns

Sanitization defaults

`arclasp.Chain`

Constructor parameters

Lifecycle

Methods

`record_agent_action()` (async)

`chain.chain_id`

`arclasp.PolicyDecision`

Framework adapters

`arclasp.langgraph.govern()`

`arclasp.langchain.govern()`

`arclasp.crewai.govern()`

`arclasp.mcp.ArclaspMcpAdapter`

`arclasp.client.verify_receipt_v2()`

`arclasp.client.verify_approval_v2()`

Public verification token helpers

`arclasp.client.verify_receipt()`

See Verification for current verification routes and migration guidance.

Exceptions

Version compatibility

Where to go next