Metadata-Version: 2.4
Name: swarrm
Version: 1.1.3
Summary: A flight recorder for AI agents: signed receipts, tamper-evident history, and local verification
Author-email: Swarrm AI <proof@swarrm.ai>
License-Expression: LicenseRef-Swarrm-Proprietary AND Apache-2.0
Project-URL: Homepage, https://swarrm.ai
Project-URL: Install guide, https://swarrm.ai/quickstart
Project-URL: Browser verifier, https://swarrm.ai/verify
Project-URL: Open verifier & specs, https://github.com/capxholding/swarrm-verify
Project-URL: Artifact integrity, https://swarrm.ai/INTEGRITY.txt
Keywords: ai-agents,agent-observability,audit-trail,evidence,tamper-evident,verification
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: LICENSE-APACHE-2.0.txt
Requires-Dist: certifi>=2026.7.22
Requires-Dist: cryptography>=42
Requires-Dist: uvicorn>=0.29
Requires-Dist: rfc8785>=0.1
Requires-Dist: httpx>=0.27
Requires-Dist: fastapi>=0.110
Requires-Dist: web3<8,>=7.16
Requires-Dist: asn1crypto>=1.5
Requires-Dist: cbor2==6.1.4
Requires-Dist: jinja2>=3.1
Requires-Dist: python-multipart>=0.0.9
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: anyio>=4; extra == "dev"
Requires-Dist: ruff<0.16,>=0.15; extra == "dev"
Requires-Dist: detect-secrets>=1.5; extra == "dev"
Requires-Dist: lizard==1.23.0; extra == "dev"
Requires-Dist: pathspec==1.1.1; extra == "dev"
Dynamic: license-file

# Swarrm

**A flight recorder for AI agents. Capture what your AI did. Verify the record.**

Swarrm turns supported AI-agent actions into signed receipts, links them into a
checkpointed, tamper-evident history, and exports portable evidence bundles.
When a decision is questioned, the record can be checked locally by the people
you share it with—without a Swarrm account or a live Swarrm service.

## Start in two minutes

Run the built-in local example from start to finish:

```bash
pipx install swarrm==1.1.3            # Python 3.11+; or: pip install swarrm==1.1.3
swarrm demo                            # generate an original and an altered sample
swarrm verify demo_out/bundle.json     # VERDICT: VERIFIED
swarrm verify demo_out/bundle_tampered.json  # VERDICT: NOT VERIFIED
```

Next, reproduce the live E2 path against the public Base Sepolia sample:

```bash
curl -fsSLO https://swarrm.ai/samples/sample_bundle.json
curl -fsSLO https://swarrm.ai/samples/sample_sigstore_tsa_trust.json
swarrm verify sample_bundle.json \
  --trust sample_sigstore_tsa_trust.json \
  --live --rpc https://sepolia.base.org
```

The five sample receipts should report E2. Use the downloaded trust file to
reproduce this public sample. For production, import and pin TSA roots your
organization has reviewed.

## What you get

- **Signed action receipts.** Capture model calls, tool calls, approvals,
  payments, policy decisions, data access, guardrails, lifecycle changes, and
  namespaced custom events.
- **Tamper-evident history.** Receipts are included in an append-only Merkle log
  with signed checkpoints and witnessed key history.
- **Portable evidence.** Export self-contained bundles, readable Evidence
  Reports, incident packets, and selective disclosures.
- **Local verification.** Check a bundle with the Python CLI or the open
  Rust/WASM verifier in a browser.
- **Visible evidence health.** Known capture and persistence gaps surface through
  warnings, health state, journals, and report findings.
- **Flexible deployment.** Run locally, self-host the service, use the managed
  gateway, or sign and spool receipts inside your network with the edge recorder.

## Capture from the path that fits your system

| Integration | Use it for |
|---|---|
| Python SDK and `@swarrm.evidenced` | Typed receipts around consequential application actions |
| OpenAI-compatible gateway | Routed model calls with a `base_url` change |
| LangChain, LangGraph, and OpenAI Agents hooks | Model and tool callbacks from supported framework events |
| MCP wrapper and OpenTelemetry intake | Tool traffic and existing telemetry pipelines |
| Edge recorder and Evidence Node | Customer-local capture plus source-side observation and reconciliation |

```python
import swarrm

prompt = "Summarize the approved refund policy."
answer = "Refunds require manager approval above $500."

swarrm.init()
with swarrm.session("case-7781"):
    swarrm.model_call(model="gpt-4o", prompt=prompt, output=answer)
    swarrm.approval(decision="approved", approver="u_88", role="manager")
    swarrm.payment(amount=4732.19, currency="USD", counterparty="acct_9f2")
```

Use `swarrm doctor` to confirm the active profile, effective configuration, last
receipt, and recording health.

## How the record becomes verifiable

1. **Capture.** An enabled integration observes a supported action and records
   selected content as cryptographic commitments plus bounded metadata.
2. **Sign.** The recorder creates a canonical Ed25519/DSSE receipt for the
   captured action.
3. **Checkpoint.** The receipt enters an RFC 6962 Merkle log with inclusion,
   consistency, checkpoint, and key-history evidence.
4. **Export and verify.** A bounded set of receipts becomes a portable bundle.
   The verifier recomputes the checks from the supplied artifact and trust inputs.

## Evidence levels, in plain language

The levels are cumulative, post-action properties—not a score.

| Level | What it establishes |
|---|---|
| **E0 · Signed receipt** | The receipt signature verifies under the named key. |
| **E1 · Presented history** | E0 plus Merkle inclusion, key-history replay, and signed-checkpoint consistency for the history presented. |
| **E2 · Public commitment** | E1 plus a live-confirmed covering Base or Base Sepolia checkpoint and an RFC 3161 timestamp verified to a TSA root supplied by the relying party. |
| **E3 · Dual attestation** | E2 plus matching evidence-issuer and active recorder signatures verified under recorder trust supplied by the relying party. |

The browser file-drop verifier establishes E1 entirely offline. The live report
profile can establish E2; the current public example demonstrates it on Base
Sepolia staging. E3 builds on the complete E2 basis when the dual-attestation
evidence and recorder trust are supplied.

## Machine-verifiable agent identity and authority

Counterparty Assurance lets two agents exchange a nonce-bound presentation for
organization-rooted identity, current mandate, exact-action authority, and replay
protection. Verification runs locally against trust roots and durable state
controlled by the relying party. The structured result is an advisory input to
the relying party's own execution policy.

## Data and deployment boundary

The evidence log contains cryptographic commitments and bounded operational
metadata. Payload bodies stay outside the evidence log. Local, self-hosted, and
edge deployments keep payload handling in your environment; the managed gateway
handles model traffic in transit. Plaintext metadata selected by an integration
remains part of the record and should be classified accordingly.

Verification answers a precise question: whether the signed receipts and the
presented authenticated history are intact under the supplied trust material.
Capture coverage follows the integrations and evidence sources you enable.

## Open verification

The package includes the Python verifier. A separate Apache-2.0 Rust/WASM
implementation and the wire-format specifications are published in
[swarrm-verify](https://github.com/capxholding/swarrm-verify). Both implementations
run the same adversarial fixture families to detect semantic drift.

- [Verify a bundle in your browser](https://swarrm.ai/verify)
- [Install and integration guide](https://swarrm.ai/quickstart)
- [Public verifier source and specifications](https://github.com/capxholding/swarrm-verify)
- [Verifier artifact integrity](https://swarrm.ai/INTEGRITY.txt)

## License

The `swarrm` package is proprietary—© 2026 Capx Holding, all rights reserved.
The published wire-format specifications and Rust/WASM verifier are Apache-2.0.
