SDK API

Arclasp deliberately exposes a small supported top-level API. The current arclasp.__all__ contains exactly 14 symbols.

Top-level supported API

Symbol	Purpose
`init`	Configure the SDK runtime.
`verify_approval_v2`	Authenticated approval verification helper.
`verify_public_token`	Verify an opaque public verification token.
`verify_receipt_v2`	Authenticated receipt verification helper.
`Chain`	Workflow-level governance context.
`ArclaspPolicyError`	Base policy-family exception.
`ActionDeniedError`	Policy or human approval denial.
`BackendUnavailableError`	Governed backend operation cannot obtain authority.
`ChainCompletionError`	Chain completion cannot be confirmed.
`ChainAutoPausedError`	Backend auto-pause surfaced to the SDK.
`ChainTimeoutError`	Local approval polling window expired.
`ArclaspKillSwitchError`	Organization kill switch denied a governed action.
`ArclaspVerificationError`	Verification helper failed safely.
`__version__`	Installed SDK version.

The package contains additional adapter methods, models, and compatibility helpers. Do not describe the package’s larger callable inventory as the supported top-level public API.

`arclasp.init()`

Current call signature:

arclasp.init(
    api_key: str,
    *,
    environment: str = "production",
    backend_url: str = "https://api.arclasp.com",
    backend_timeout_seconds: int = 5,
    financial_approval_threshold_usd: float = 5000.0,
    cumulative_financial_threshold_usd: float = 10000.0,
    external_domains_allowlist: list[str] = [],
    high_risk_agents: list[str] = [],
    registered_agents: list[str] | None = None,
    default_approval_timeout_hours: int = 24,
    fallback_approvers: list[str] = [],
    drain_timeout_seconds: int | None = None,
    offline_buffer_max_events: int = 100,
    max_retries: int = 3,
    retry_backoff_base_ms: int = 100,
    sensitive_field_patterns: list[str] = [...],
    sensitive_value_patterns: list[str] = [...],
    max_payload_string_length: int = 1000,
)

Active runtime configuration

Parameter	Meaning
`api_key`	Arclasp API key. Current keys use the compatibility prefix `prail_`.
`environment`	Environment tag attached to Chains.
`backend_url`	Arclasp backend URL. Hosted production is `https://api.arclasp.com`.
`backend_timeout_seconds`	Backend request timeout.
`max_retries`	Retry count for transient backend transport failures before failing closed.
`retry_backoff_base_ms`	Base delay for exponential backoff between transient retry attempts.
`default_approval_timeout_hours`	Local approval wait window / approval configuration input.
`fallback_approvers`	Fallback approver configuration input.
`sensitive_field_patterns`	Extra field-name patterns for SDK payload sanitization.
`sensitive_value_patterns`	Extra value-prefix patterns for SDK payload sanitization.
`max_payload_string_length`	SDK payload string truncation limit.

Compatibility parameters

These accepted arguments should not be presented as the current backend-authoritative control surface:

Parameter	Current guidance
`financial_approval_threshold_usd`	Does not change the current backend-enforced single-action threshold.
`cumulative_financial_threshold_usd`	Do not use this init argument as the current per-Chain backend override; use `Chain.add_financial_threshold()`.
`external_domains_allowlist`	SDK-side compatibility input; do not present it as a customer control for the backend policy allowlist.
`high_risk_agents`	SDK-side compatibility input; use the backend/dashboard Agent Registry for enforced registered-agent risk.
`offline_buffer_max_events`	Compatibility setting; it does not enable offline governed execution.

The current public SDK configuration model rejects unknown init() keywords.

`arclasp.Chain`

A Chain is the workflow-level governance context.

chain = arclasp.Chain(
    "vendor-workflow",
    metadata={"workflow_version": "1"},
)

Use it as an async context manager:

async with chain:
    ...

or as a synchronous context manager in synchronous code.

Supported customer-usable Chain surface

Symbol	Purpose
`chain_id`	Backend-assigned Chain ID after start.
`add_financial_threshold(usd, notify=None, deny=False)`	Configure a per-Chain cumulative financial threshold before start.
`record_agent_action(...)`	Submit a governed action and receive/enforce the backend decision.
`detail()`	Fetch current Chain detail.
`events(limit=100, offset=0, sequence_after=None)`	Fetch Chain event history.
`receipt()`	Fetch the receipt for a completed Chain when available.

`record_agent_action()`

await chain.record_agent_action(
    agent_name: str,
    action_type: str,
    action_name: str,
    payload: dict | None = None,
    parent_agent_name: str | None = None,
)

The SDK sanitizes the payload and sends the governed event to the backend. Typical outcomes:

allow-style decision object returned;
approval required — SDK waits, then returns or raises;
deny — ActionDeniedError;
active kill switch — ArclaspKillSwitchError;
auto-pause — ChainAutoPausedError;
backend unavailable — BackendUnavailableError.

The returned decision object can include fields such as policy_decision, decision_reason, decision_source, policy_name, evaluation_mode, shadow_decision, estimated_cost_usd, and remediation context. The decision model itself should not be advertised as an extra top-level public symbol unless it is actually exported by arclasp.__all__.

Completion

Exiting the Chain context requests backend completion. If completion cannot be confirmed, the SDK can raise:

arclasp.ChainCompletionError

Do not assume a receipt exists when completion failed.

Verification helpers

approval = await arclasp.verify_approval_v2("approval-id")
receipt = await arclasp.verify_receipt_v2("receipt-id")
public = await arclasp.verify_public_token("opaque-token")

Verification errors surface through:

arclasp.ArclaspVerificationError

Framework adapters

Framework-specific integration APIs live in their modules rather than the 14-symbol top-level list:

arclasp.langchain
arclasp.langgraph
arclasp.crewai
arclasp.mcp

See the framework pages for their supported integration patterns.

​SDK API

​Top-level supported API

​arclasp.init()

​Active runtime configuration

​Compatibility parameters

​arclasp.Chain

​Supported customer-usable Chain surface

​record_agent_action()

​Completion

​Verification helpers

​Framework adapters