vaara

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/vaaraio/vaara/main/docs/vaara-wordmark-dark.png">
    <img src="https://raw.githubusercontent.com/vaaraio/vaara/main/docs/vaara-wordmark-light.png" alt="Vaara" width="900">
  </picture>
</p>

<p align="center">
  <a href="https://pypi.org/project/vaara/"><img src="https://raw.githubusercontent.com/vaaraio/vaara/badges/pypi.svg" alt="PyPI"></a>
  <a href="https://github.com/vaaraio/vaara/blob/main/LICENSE"><img src="https://img.shields.io/pypi/l/vaara.svg" alt="License"></a>
  <a href="https://github.com/vaaraio/vaara/actions/workflows/ci.yml"><img src="https://github.com/vaaraio/vaara/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="https://scorecard.dev/viewer/?uri=github.com/vaaraio/vaara"><img src="https://github.com/vaaraio/vaara/actions/workflows/scorecard.yml/badge.svg" alt="OpenSSF Scorecard"></a>
  <a href="https://www.bestpractices.dev/projects/12612"><img src="https://www.bestpractices.dev/projects/12612/badge" alt="OpenSSF Best Practices"></a>
  <a href="https://huggingface.co/spaces/vaaraio/vaara"><img src="https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-Space-blue" alt="Hugging Face Space"></a>
</p>

<p align="center">
  <img src="https://raw.githubusercontent.com/vaaraio/vaara/badges/downloads.svg" alt="Downloads">
</p>

<p align="center"><b>Accountable Autonomy.</b></p>

<p align="center">A verifiable receipt for every autonomous action, checkable by anyone.</p>

Your AI agent transferred the funds, wrote the file, called the tool. Later, someone who does not trust you asks you to prove exactly what it did and why: a regulator, an auditor, a customer after an incident. Your own logs will not settle it, because you could have edited them.

<p align="center">
  <a href="https://github.com/vaaraio/vaara/releases/tag/v1.50.0"><img src="https://raw.githubusercontent.com/vaaraio/vaara/main/docs/vaara-v150-launch.gif" width="720" alt="Vaara for macOS launch demo"></a>
</p>

<p align="center"><a href="https://github.com/vaaraio/vaara/releases/tag/v1.50.0">&#9654;&nbsp; Watch the launch video (24s)</a> &middot; Vaara for macOS is in public beta</p>

## Quick start

```bash
pip install vaara                            # Python: CLI, MCP proxy, server
brew tap vaaraio/tap && brew install vaara   # macOS: CLI + menu-bar app (built from source)
npm install @vaara/client                    # TypeScript client for the HTTP API
```

```python
import vaara

@vaara.govern
def transfer_funds(to: str, amount: float) -> str:
    ...
```

That is the whole thing. Every call to a governed function is risk-scored and decided against your policy before the body runs. A blocked call raises `vaara.Blocked`; an allowed call runs, and the decision, the call, and the outcome land in a signed record anyone can verify offline. Python 3.10+, zero runtime dependencies.

<details>
<summary><b>Prefer the explicit pipeline?</b></summary>

The decorator drives the same engine you can call directly when you want the decision object in hand.

```python
from vaara.pipeline import InterceptionPipeline

pipeline = InterceptionPipeline()
result = pipeline.intercept(
    agent_id="agent-007",
    tool_name="fs.write_file",
    parameters={"path": "/etc/service.yaml", "content": "..."},
    agent_confidence=0.8,
)
if result.allowed:
    pipeline.report_outcome(result.action_id, outcome_severity=0.0)
else:
    print(result.reason)
```

Every call gets a risk score and an allow / block / escalate decision against your policy, then the call, the decision, and the real outcome are written to the audit trail. `report_outcome` closes the loop: the scorer reweights based on which signals actually predicted the outcome. Releases ship SLSA Build Level 3 provenance, verifiable with `slsa-verifier verify-artifact`. Optional ML classifier: `pip install 'vaara[ml]'`.
</details>

<details>
<summary><b>Verify it without trusting the producer</b></summary>

Writing a trail is the easy half. The half that matters is letting someone who does not trust you check it, with no key, no access, and none of your code. Every Vaara record is content-addressed and fail-closed on authenticity, and ships with public conformance vectors plus a standalone checker that imports no Vaara code, so an independent party reproduces every verdict offline.

```bash
vaara verify-bundle evidence-bundle.json
```

`ok` only when a signature is actually established, not merely present in a log. The same property drives the standards work behind [the Vaara Receipt Internet-Draft](https://datatracker.ietf.org/doc/draft-sirkkavaara-vaara-receipt/): evidence that holds up for someone who runs none of your software. The full verifier set, the trust model for each verb, and where trust comes from in each case are in [docs/verifying-evidence.md](docs/verifying-evidence.md).

To check that claim yourself, without installing Vaara, run the standalone checker against the published vectors. Its only dependencies are `cryptography` and `rfc8785`:

```bash
git clone https://github.com/vaaraio/vaara
cd vaara
pip install cryptography rfc8785        # the checker's only dependencies
python tests/vectors/external_evidence_v0/_check_independent.py
```

It re-derives every verdict from the receipt bytes and the public key alone. The output shows the property the trail is built for: a receipt dropped from inside a declared boundary is a provable gap from the held set, with no issuer access and no external witness.

For the whole loop in one runnable file, produce a signed record, verify it yourself, then watch a single forged byte get caught, see [examples/prove-it-yourself/](examples/prove-it-yourself/). The logs-versus-evidence argument behind it is in [docs/logs-vs-evidence.md](docs/logs-vs-evidence.md).

The aggregate runner grades every suite at once, and grades another implementation's vectors the same way:

```bash
python scripts/conformance_runner.py                                 # grade the reference corpus
python scripts/conformance_runner.py --vectors-dir ./your_vectors    # grade your own
```

The named, versioned rule set, what a pass does and does not establish, and the full suite list are in [docs/conformance-profile.md](docs/conformance-profile.md).
</details>

<details>
<summary><b>What the evidence looks like</b></summary>

`vaara compliance report --format json` against a real trail produces an article-level evidence record an auditor reads directly. Articles with no recorded events return `evidence_insufficient`, not a rubber stamp.

```json
{
  "system_name": "Acme HR Assistant",
  "overall_status": "evidence_insufficient",
  "trail_integrity": {"size": 105, "chain_intact": true},
  "articles": [
    {"article": "Article 12(1)", "title": "Record-Keeping (Logging)",
     "status": "evidence_sufficient", "strength": "strong", "evidence_count": 105},
    {"article": "Article 15(1)", "title": "Accuracy, Robustness and Cybersecurity",
     "status": "evidence_insufficient", "strength": "absent", "evidence_count": 0}
  ]
}
```

Each verdict carries the threshold-versus-observed snapshot, the rationale, and the underlying records, so a reviewer traces `status` back to a concrete event. The same data renders as a Notified-Body PDF, a static HTML dashboard, or a Sigstore-signed handoff envelope. See [docs/COMPLIANCE.md](docs/COMPLIANCE.md).
</details>

<details>
<summary><b>What you get</b></summary>

- **Gate every tool call** against your own policy: allow, block, or escalate.
- **A tamper-evident trail** an outside party verifies without trusting your stack, with the chain head anchorable to an external RFC 3161 / eIDAS timestamp so its existence is provable against a clock you do not control.
- **Article-level EU AI Act evidence**, honest about the gaps instead of papering over them.
- **Governance of the model call itself**, not only the tools around it: a hardware-rooted inference receipt that a second, different local model cross-checks. This is the sovereign inference harness, new in v1.0.
- **Enforcement, not only a record** (v1.1.0): a credential broker mints a signed, short-lived credential bound to the attestation digest and scoped to one tool, its argument commitment, and tenant, with typed capability scopes that bound what a call may do. A gateway in front of a protected tool refuses any call without a valid, attestation-bound grant, so a bypass stops being silent. Off by default.
- **Gap-evident completeness** (v1.4.0): each authorization receipt can carry a signed per-boundary sequence and running count, so a dropped receipt inside a declared boundary is a provable gap from the held receipts alone, with no issuer access and no external witness (`vaara verify-contiguity`). Off by default.
- **Independent re-mint** (v1.14.0): a second generator in each public vector set reproduces the signed carrier byte-exact from the declared canonicalization alone, with no Vaara import. A verifier that has never run Vaara software reproduces the same bytes.
</details>

<details>
<summary><b>Where it plugs in</b></summary>

Native adapters route the major Python agent frameworks through the same pipeline, each via the framework's own hook, emitting identical audit events:

| Framework | Entry point |
|---|---|
| LangChain | `VaaraCallbackHandler`, `vaara_wrap_tool` |
| CrewAI | `VaaraCrewGovernance` |
| OpenAI Agents SDK | `VaaraToolGuardrail`, `vaara_wrap_function` |
| MCP server | `vaara.integrations.mcp_server` |

To put Vaara **in front of** an MCP server, run it as a proxy. Every `tools/call` routes through the pipeline before reaching the upstream; allowed calls forward transparently, blocked calls return an MCP error.

```bash
vaara-mcp-proxy \
  --upstream npx --upstream-arg -y --upstream-arg @sap/mdk-mcp-server \
  --db ./mcp_audit.db --shadow
```

Start with `--shadow`: every call is classified, scored, and recorded, nothing is blocked. Af