nora causal

Per-folder causal graphs — settings, bootstrap, staged review, live approval.

Causal graphs in Nora are per-folder: attach a graph to a document folder, extract causal triples from those documents into a staged area, then approve them to live.

The causal CLI is the surface for the staged/live workflow. Graphs bootstrap from documents; you approve the good triples; only the approved (live) ones are used for verification and reasoning.

Commands

Command	Description
causal get <folder>	Fetch the folder’s full graph (LIVE + STAGED).
causal settings show <folder>	Print folder graph settings + stage stats.
causal settings set <folder>	Update graph settings.
causal bootstrap <folder>	Extract causal triples into STAGED.
causal refresh <folder>	Recompute deltas into STAGED.
causal approve <folder>	Promote STAGED rows to LIVE.
causal reject <folder>	Drop STAGED rows without promoting.

Folder identifiers are the document folder tag (e.g. billing, product-docs).

causal get

nora causal get billing

Prints the whole graph:

• live_nodes and live_edges — used in verification and reasoning.
• staged_nodes and staged_edges — waiting for review.

Add --json for structured output.

Common quick check:

nora causal get billing --json | jq '{live: .live_nodes | length, staged: .staged_nodes | length}'

causal settings show / set

nora causal settings show billing

Shows settings + stage counts.

nora causal settings set billing \
  --connection documents_folder:billing \
  --retrieval-preset high-precision \
  --dedup-policy merge \
  --auto-restage true

Only flags passed change.

• --connection <kind:id> — link the graph to a specific data source (e.g. documents_folder:billing).
• --retrieval-preset <preset-id> — the preset extraction uses to pull context.
• --dedup-policy <policy> — how duplicates are handled (merge, keep_newer, keep_older, keep_all).
• --auto-restage true|false — automatically re-bootstrap when the linked source changes.

causal bootstrap

nora causal bootstrap billing --model gpt-4o

Extracts causal triples from every document in the folder into STAGED. Nothing goes to LIVE until you approve.

• --model <m> — model used for extraction. Defaults to workspace default.

Bootstrap is idempotent — re-running on an already-populated folder doesn’t lose LIVE data. Re-extraction produces new STAGED rows; existing LIVE stays as-is.

For a fresh folder: bootstrap → review the STAGED area in the app → approve the good ones. For an existing folder: refresh is usually what you want.

causal refresh

nora causal refresh billing

Recomputes only the deltas — new documents added, existing documents changed since the last bootstrap. Cheaper than a full bootstrap.

Refresh output lands in STAGED. Existing LIVE stays intact.

Run on a schedule (or triggered by document changes) if --auto-restage isn’t your fit.

causal approve / reject

# Approve all STAGED rows
nora causal approve billing

# Approve specific rows only
nora causal approve billing --ids node_1,edge_a,node_5

# Reject the rest
nora causal reject billing

• --ids <id,…> — the specific staged row IDs. Omit to act on all STAGED.

After approve:

• The rows move to LIVE.
• Verification starts using them immediately.
• STAGED still contains anything not touched by this command.

reject drops the rows without promoting. They can be re-created by the next bootstrap or refresh.

Recipes

Bootstrap a folder end-to-end from CLI

folder="billing"

# 1. Configure
nora causal settings set $folder \
  --connection documents_folder:$folder \
  --retrieval-preset high-precision \
  --auto-restage true

# 2. Extract into STAGED
nora causal bootstrap $folder

# 3. Review (usually in the app), then bulk-approve everything staged
nora causal approve $folder

# 4. Verify a query uses the graph
nora retrieval search "some question" --filters '{"tag":"'$folder'"}' --include-subgraph

CI: fail if STAGED is too large

Prevents unbounded backlog:

threshold=200
staged=$(nora causal get billing --json | jq '.staged_nodes | length')
if [ "$staged" -gt "$threshold" ]; then
  echo "STAGED backlog too large ($staged > $threshold). Review needed."
  exit 1
fi

Selective approve after human review

Suppose your review workflow marks approvals in an external system with the row IDs. Bulk-approve them:

ids=$(cat approved-ids.txt | tr '\n' ',' | sed 's/,$//')
nora causal approve billing --ids "$ids"

Snapshot the LIVE graph for audit

nora causal get billing --json | jq '{live_nodes, live_edges}' > audit/billing-graph-$(date +%Y%m%d).json

The STAGED / LIVE model

The two-stage model exists because causal extraction is best-effort — the model proposes, you dispose. Direct edits to LIVE aren’t allowed from the CLI (use the app’s graph canvas for those). But bulk approval/rejection is what the CLI is for.

If you want to hand-edit a live graph — add a specific edge, remove a wrong node — do it in the app. The CLI’s role is bulk bootstrap/refresh/approve.

Related

• Causal graph overview — concepts and use cases.
• Verify agent answers — how LIVE graphs are used.
• nora retrieval — --include-subgraph expands search using the graph.