nora causal

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.

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

Setup

Flows

Blocks

Data & knowledge

Reliability

Workspace

Reference

nora causal

Commands

`causal get`

`causal settings show` / `set`

`causal bootstrap`

`causal refresh`

`causal approve` / `reject`

Recipes

Bootstrap a folder end-to-end from CLI

CI: fail if STAGED is too large

Selective approve after human review

Snapshot the LIVE graph for audit

The STAGED / LIVE model

​Commands

​causal get

​causal settings show / set

​causal bootstrap

​causal refresh

​causal approve / reject

​Recipes

​Bootstrap a folder end-to-end from CLI

​CI: fail if STAGED is too large

​Selective approve after human review

​Snapshot the LIVE graph for audit

​The STAGED / LIVE model

​Related

Commands

`causal get`

`causal settings show` / `set`

`causal bootstrap`

`causal refresh`

`causal approve` / `reject`

Recipes

Bootstrap a folder end-to-end from CLI

CI: fail if STAGED is too large

Selective approve after human review

Snapshot the LIVE graph for audit

The STAGED / LIVE model

Related