The reference architecture
Twelve work units, nine gates, typed return edges with bounded budgets.
Click a node to isolate it and its edges; press Esc to clear. Open it full screen for the readable version.
What it is, who it is for
A verifier, not an orchestrator.
What is it?
A contract-gated verification layer for multi-agent research pipelines. It reads a directory of versioned artifacts, validates each against a JSON Schema, walks the provenance hash chain, checks that the reviewer was not the producer, and returns an exit code. It orchestrates nothing and calls no model API.
Who is it for?
Technical researchers and mixed-experience research teams that care about traceable outputs but should not need to edit artifact JSON to begin. It verifies mechanical integrity; it does not establish scientific correctness, orchestrate models, or guarantee reviewer independence.
Try it in 30 seconds
One install, one clean run, nine gates.
uv tool install rgraph==0.5.0 rgraph demo --scenario 1
The clean scenario exits 0 after checking nine gates, schemas, the SHA-256 provenance chain, recorded reviewer separation and revision budgets. The bundled run is a synthetic fixture; its provider identities and review decisions are illustrative.
No Python of your own required: uv fetches an
interpreter that satisfies the kit and keeps it isolated from everything else
on your machine. Without uv yet, the README
gives separate macOS, Linux and Windows installation paths.
Working on the kit itself instead? git clone it,
make a venv, and pip install -e . — the README
has that path.
rgraph demo
See the staged failures
rgraph demo exits 1 on purpose — scenarios 2 and 3
are failures staged to show what the verifier catches. The CLI identifies this
as expected and points back to rgraph demo --scenario 1; it is not
an installation failure.
A clean run. Nine gates, no missing artifact, no broken hash chain.
exit 0A fabricated citation: a source with no resolvable DOI. Gate E1 names it and says how to fix it.
exit 1Data changed after the freeze. The manifest was rewritten post-freeze; the stale chain invalidates T2, V1 and M1.
exit 1Scenarios 2 and 3 are the point. Neither can be prevented by a prompt; both are caught by a file digest.
Start your own study, without editing JSON
Three commands from an empty directory to a run you can manage locally.
rgraph setup rgraph init rgraph ui
Gate H1 needs a problem spec and a governance record, and no
agent produces them — they are yours. rgraph init asks for their
contents in ordinary language, previews the answers, then writes and seals all
three setup files. rgraph ui opens the loopback-only evidence
desk, lists the waiting human gate and shows the terminal command that can
record its decision; the browser cannot record human or final decisions. For scripts,
rgraph init --from study.yaml supplies the setup answers without a
prompt.
A human gate needs a human
Four of the nine gates require an attributable terminal decision; a terminal cannot distinguish a person from software controlling a pseudo-terminal.
Four of the nine gates are human gates, and check
cannot decide one. It reads files, recomputes digests and compares strings —
all of which it can do while nobody is watching. So the gate stays
AWAITING until somebody answers it, one declared claim at a
time.
The questions are not invented — they are the
proves entries already written in gates.yaml. The
answers and who gave them go into the gate record. A no sends the
gate back; walking away records nothing. And because the attestation is pinned
to the digests that were on the table, a later edit retires it: resealing
repairs the hash, but it cannot repair the reading.
This gate proves 2 thing(s). It cannot prove them for you.
1/2 Scope and constraints recorded
Have you read problem_spec, governance_record and does this hold?
[y] yes [n] no [s] stop > y
What it does not do
The boundary is printed on every gate screen, passed or failed.
[----] Scientific correctness was not determined
A separate session, model, or provider is reported as a reviewer-separation
level; none guarantees epistemic or statistical independence.
Four files, four concerns
Configuration is data. The code knows no provider.
graph.yaml -> architecture (which nodes, which edges, which gates) assignment.yaml -> your wallet (who runs which role) providers.yaml -> the registry (which providers exist, what they can do) gates.yaml -> the contracts (what each gate requires, at what separation)
The same graph runs on anyone's combination
of subscriptions. Adding a provider is a few lines of YAML; no code changes, because
rgraph knows no provider — it only carries identity strings.
Which roles can you actually run?
Pick a provider and a model per role. Options your subscription cannot support are struck through with the reason.
This answers the question you have before installing anything — I only have ChatGPT; what do I get?