Metadata-Version: 2.4
Name: swiftapi-python
Version: 1.3.0
Summary: SwiftAPI Python SDK - AI Action Verification Gateway
Author-email: Rayan Pal <rayan@swiftapi.ai>
License-Expression: MIT
Project-URL: Homepage, https://swiftapi.ai
Project-URL: Documentation, https://getswiftapi.com/docs
Keywords: swiftapi,ai,verification,attestation,security,governance,enforcement
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests<3,>=2.32.3
Requires-Dist: pynacl<2,>=1.5.0
Requires-Dist: colorama<1,>=0.4.6
Requires-Dist: tomli<3,>=2; python_version < "3.11"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: hypothesis<7,>=6; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: types-requests<3,>=2.32.3; extra == "dev"
Dynamic: license-file

# 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.

```bash
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

```bash
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:

```python
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](https://getswiftapi.com/pccg-2) and
[research library](https://getswiftapi.com/research) preserve the empirical,
causal, theoretical, and protocol boundaries.

## Documentation

Start with [Quickstart](docs/QUICKSTART.md). See [concepts](docs/CONCEPTS.md),
[local brake](docs/LOCAL_BRAKE.md), [Codex](docs/CODEX.md),
[Claude Code](docs/CLAUDE_CODE.md), [Python SDK](docs/PYTHON_SDK.md),
[conditions](docs/CONDITIONS.md), [action envelopes](docs/ACTION_ENVELOPES.md),
[receipts](docs/RECEIPTS.md), [verification](docs/VERIFICATION.md),
[remote authority](docs/REMOTE_SWIFTAPI.md), [BYOK](docs/BYOK.md),
[security](docs/SECURITY_MODEL.md), [threat model](docs/THREAT_MODEL.md),
[native noncontinuation](docs/NATIVE_NONCONTINUATION.md),
[benchmarking](docs/BENCHMARKING.md), and [provenance](docs/RESEARCH_PROVENANCE.md).

[Migration from 1.2.2](MIGRATION_1_2_2.md) 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.
