Aragora

# Aragora

**Aragora is an auditable execution control plane for AI-assisted decisions:
multi-model review in, a verifiable Decision Receipt out.**

It coordinates heterogeneous models to adversarially review a change or a
decision, preserves the dissent and provenance, stops truthfully when evidence
is thin, and emits a portable receipt anyone can verify offline with the
standalone verifier ([`pip install -U 'aragora-verify>=0.1.1'`](https://pypi.org/project/aragora-verify/)).

[![PyPI](https://img.shields.io/pypi/v/aragora)](https://pypi.org/project/aragora/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)

> **New here?** The [Quickstart](docs/quickstart.md) gets you a working debate in
> under a minute. Auditors should start with the [Cold Reviewer Guide](docs/COLD_REVIEWER_GUIDE.md).

| I want to… | Command |
|------------|---------|
| Run the standalone debate engine | `pip install aragora-debate` |
| Verify an Open Decision Receipt with the standalone verifier | `pip install -U 'aragora-verify>=0.1.1' && aragora-verify receipt.odr.json` |
| Run the current PyPI zero-key receipt demo | `pip install aragora && aragora demo --offline --receipt aragora-demo-receipt.json && aragora receipt verify aragora-demo-receipt.json` |
| Audit this source checkout's exact CLI | `python3 -m pip install -e . && aragora demo --offline --receipt aragora-demo-receipt.json && aragora receipt verify aragora-demo-receipt.json` |
| Call the Aragora API from Python | `pip install aragora-sdk` |
| Self-host the full platform | `docker compose -f deploy/demo/docker-compose.yml up` |

PyPI `aragora` 2.9.0 supports the explicit offline demo receipt round trip.
Use the source checkout path when you need to audit this exact branch or
unreleased local changes.

## The problem

Individual LLMs are unreliable. Their personas shift with context, their
confidence does not correlate with accuracy, and they often optimize for
plausible agreement instead of truth. Aragora treats that as a systems problem:
it makes consequential AI-assisted decisions **inspectable and verifiable**
instead of asking you to trust one model's say-so.

- **Disagreement becomes evidence.** Heterogeneous models challenge each other before work advances; dissent is preserved, not averaged away.
- **Every decision has a receipt.** Verdict, the reviewing models and their independence, dissent, confidence, and provenance stay inspectable.
- **It stops truthfully.** When the quorum can't be formed or evidence is thin, the receipt says so — it never fabricates a consensus.
- **Receipts are portable and verifiable.** A receipt is a schema-conformant artifact (the [Open Decision Receipt](docs/specs/OPEN_DECISION_RECEIPT.md)) that `aragora-verify` checks offline, with no dependency on Aragora.

## The wedge: a governance gate for AI-written code

Drop Aragora into CI. A multi-model quorum reviews each PR and posts a grounded
PR comment — your second opinion, with the same review surface that feeds the
Decision Receipt path.

```yaml
# .github/workflows/aragora-review.yml
name: Aragora Review
on:
  pull_request:
    types: [opened, synchronize, reopened]
permissions:
  contents: read
  pull-requests: write
  issues: write
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: synaptent/aragora@8b600a3a8dbf076f4027ae27f3dcbbf48e75409f
        with:
          anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
          openai-api-key: ${{ secrets.OPENAI_API_KEY }}
          post-comment: 'true'
          emit-receipt: 'true'
```

The action posts a PR review comment, uploads the machine-readable review
artifact, and (with `emit-receipt: 'true'` shown above) emits a Decision
Receipt artifact from a second, independent quorum pass. Anyone — a teammate,
an auditor, a customer — can then verify that receipt independently with the
standalone `aragora-verify` verifier (no Aragora dependency):

```bash
pip install -U 'aragora-verify>=0.1.1'
aragora-verify decision-receipt.odr.json

# Add a public key when you need issuer authenticity, not just structure/digest:
aragora-verify decision-receipt.odr.json --pubkey signing-key.pem

# or build from source (this repo, aragora-verify/):
pip install ./aragora-verify
```

> Use **0.1.1+** (`pip install -U 'aragora-verify>=0.1.1'`): it binds each
> signature's recorded `key_id` to the key you supply, so a relabeled signer
> fails as tampering. 0.1.0 lacks that binding — upgrade if you have it.

See the [full Action setup guide](docs/GITHUB_ACTION_SETUP.md#emitting-a-verifiable-decision-receipt)
for the receipt-specific inputs/outputs, secret-dependent limits (receipts are
unsigned; reviewer defaults need reachable provider keys), and a committed
example receipt you can verify right now without running any CI.

We run this gate on our

... (truncated)