SwiftAPI Python SDK

A prerequisite before a protected action. Local Swift Brake verifies explicit permission, executes its registered capability once, and creates signed receipts. Codex or Claude Code remains the coding agent. No second model is involved.

pip install swiftapi-python
swiftapi doctor
swiftapi brake test
swiftapi brake install --dry-run
swiftapi brake install

Python 3.9+, macOS and Linux. The local test needs no account, API key, model, or cloud service. Restart the coding agent after installing the MCP integration.

Try the brake

swiftapi brake propose hello.txt "Hello from Swift Brake"
# Copy the returned request_id into the following commands.
swiftapi brake execute REQUEST_ID
# GATE_BLOCK: no marker is written.
swiftapi brake authorize REQUEST_ID
swiftapi brake execute REQUEST_ID
# AUTHORIZED_EXECUTION: exact marker bytes are written once.
swiftapi brake execute REQUEST_ID
# GATE_BLOCK: the authorization cannot execute again.
swiftapi status
swiftapi receipts
swiftapi verify RECEIPT_PATH --public-key PUBLIC_KEY_PATH

status prints the sandbox and public-key path. execute returns the receipt path. The operator authorizes in a separate terminal; authorization is deliberately absent from the MCP tool surface. A signature requires an independently trusted verification key, never a key blindly accepted from the receipt itself.

swiftapi brake presents swiftapi> and delegates ordinary input to the existing Codex CLI. swiftapi brake --agent claude uses Claude Code. These host calls use your existing account; the local test itself makes no model calls.

Python

The old imports remain available: from swiftapi import SwiftAPI, Enforcement. The new local API does not require a remote account:

from pathlib import Path
from tempfile import mkdtemp
from swiftapi import ActionEnvelope, BindingCondition, LocalAuthority, LocalGuard

action = ActionEnvelope("example.append", {"value": "verified"}, "Append one value")
state = {"operator_approved": True}  # Supplied by trusted application code.
condition = BindingCondition(action.action_hash, state)
guard = LocalGuard(LocalAuthority(), Path(mkdtemp()) / "ledger")
values = []
guard.run(
    lambda: values.append("verified"),
    action=action.capability, params=action.params, intent=action.intent,
    condition=condition, state=state,
)
assert values == ["verified"]

A callback's code must actually implement its supplied action description. For an untrusted agent, use a registered broker operation that constructs and executes the same canonical parameters. The bundled MCP operation creates a new small UTF-8 marker in its own sandbox; it cannot run a shell or overwrite files.

What is enforced

An authorization binds an action hash, capability, condition hash, state hash, nonce, issue time, and expiry. Ed25519 verification and a durable SQLite replay claim happen before execution. Execution is never retried. Missing, malformed, forged, expired, replayed, or mismatched authorization fails closed.

This guarantee applies to mediated capabilities. Arbitrary host tools are outside the broker. Local same-user key storage supports development and CI; a malicious process able to read the signer, change the gate, or mutate the ledger can bypass that trust boundary. Production credentials and signing authority require process or account isolation from untrusted agent code. Instructions and hooks are not a universal security boundary.

Research is measured separately

GATE_BLOCK is deterministic enforcement, not native EOS. Successful empty provider output is classified as a black-box PROVIDER_VOID with V0/V1/V2/VU subtypes. Only exposed native token evidence can qualify as NATIVE_VOID. The package does not download or retrain research models. The frozen PCCG-2 release and research library preserve the empirical, causal, theoretical, and protocol boundaries.

Documentation

Start with Quickstart. See concepts, local brake, Codex, Claude Code, Python SDK, conditions, action envelopes, receipts, verification, remote authority, BYOK, security, threat model, native noncontinuation, benchmarking, and provenance.

Migration from 1.2.2 documents security corrections and termination-metadata changes. Historical 1.2.2 bytes remain immutable on PyPI.

MIT license. Research and software by Rayan Pal / SwiftAPI Labs.