nora causal

Nora has two causal-graph surfaces, and the causal CLI covers both:

Folder-based (paper-ver6 flow) attach a graph to a document folder, extract triples into a staged area, approve them to live. Optimised for authoritative graphs curated from a document corpus.
Instance-based (canvas-shaped model) pipelines with an out_kg / out_causal_graph block auto-mint graph instances; use the CLI to inspect, rewire, and audit them, or edit edges atomically.

Both stay honest to a Pearl DAG (spec v3.1): variables, causes edges, backdoor / adjustment-set analysis.

Command groups

Folder extraction: causal get, causal settings show/set, causal bootstrap, causal refresh, causal approve, causal reject
Instance CRUD: causal graphs list/get/upsert/delete
Wire-ups: causal bindings list/add/remove
Provenance: causal evidence node/graph
Edges (atomic): causal edges add/remove/update
Auto-proposals: causal staged-proposals <graph-id>

Folder identifiers are the document folder tag (e.g. billing, product-docs). Graph instance ids are kg_<uuid>.

`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

Instance CRUD (`graphs`)

Pipelines with an out_kg / out_causal_graph block auto-mint graph instances. Use these verbs to inspect, rename, and delete them.

# List
nora causal graphs list

# Fetch metadata + full surfaces JSONB
nora causal graphs get kg_abc

# Create or update. `--surfaces` accepts inline JSON, @file, or @-
nora causal graphs upsert \
  --id kg_regulations \
  --name "Regulations map" \
  --surfaces @surfaces.json \
  --vector-store pgvector      # honoured on INSERT only

# Delete permanently
nora causal graphs delete kg_abc

Deleting is permanent. Attached chunks keep their kg_instance_id reference (become orphans). Clean them up first if you don’t want the reference dangling. --lifecycle is JSON and optional; omit to keep the server-side default.

Bindings (`bindings`)

Which pipelines land in which graph instance. Auto-written when a pipeline with an out_kg block executes; use these verbs for manual wire-ups.

# Which pipelines are bound to this graph?
nora causal bindings list kg_regulations

# Wire a pipeline into the graph (idempotent)
nora causal bindings add kg_regulations --pipeline-id p_ingest_regs

# Unbind (existing chunks keep their attachment)
nora causal bindings remove kg_regulations --pipeline-id p_ingest_regs

Evidence trails (`evidence`)

Reader view over which chunks back a node (or the whole graph).

# Every chunk the pipeline attached to one node, ordered by attach score
nora causal evidence node --node-id n_alice

# Every chunk scoped to a graph: attached + orphan
nora causal evidence graph kg_regulations

Great for audit (“why did the graph decide this?”) and for spotting orphan chunks (attached to a deleted node) that should be re-linked or dropped.

Atomic edge CRUD (`edges`)

Read/modify/write one edge at a time without shipping the whole surfaces blob. See spec docs/mcp/temporal-retrieval-setup.md §G4 for the precedence-predicate family (defers_to / overrides / …).

# Append an edge (server mints e_<uuid> when --id is omitted; idempotent on --id)
nora causal edges add kg_regulations \
  --src n_reg_a --dst n_reg_b \
  --predicate defers_to

# Update predicate and/or metadata (at least one required; --metadata replaces wholesale)
nora causal edges update kg_regulations \
  --edge-id e_abc \
  --predicate overrides \
  --metadata '{"reason":"court ruling 2026-05"}'

# Delete (no-op when the edge doesn't exist)
nora causal edges remove kg_regulations --edge-id e_abc

Unknown predicates are accepted but flagged with predicateWarning: true in the response so custom vocabulary works while you migrate to the whitelist.

Auto-proposals (`staged-proposals`)

Lists the STAGED (unreviewed) nodes + edges in an instance. These are typically auto-proposals from Foundry out_causal_graph runs with propose_hierarchy=true.

nora causal staged-proposals kg_regulations

Approve or reject with the folder-scoped causal approve / reject verbs above.

The STAGED / LIVE model

The two-stage model exists because causal extraction is best-effort: the model proposes, you dispose. Folder-based approve / reject handle bulk decisions; edges handles single-edge surgical fixes; the app’s graph canvas handles free-form hand editing.

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

CLI

SDK

Local App

nora causal

Command groups

`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

Instance CRUD (`graphs`)

Bindings (`bindings`)

Evidence trails (`evidence`)

Atomic edge CRUD (`edges`)

Auto-proposals (`staged-proposals`)

The STAGED / LIVE model

​Command groups

​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

​Instance CRUD (graphs)

​Bindings (bindings)

​Evidence trails (evidence)

​Atomic edge CRUD (edges)

​Auto-proposals (staged-proposals)

​The STAGED / LIVE model

​Related

Command groups

`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

Instance CRUD (`graphs`)

Bindings (`bindings`)

Evidence trails (`evidence`)

Atomic edge CRUD (`edges`)

Auto-proposals (`staged-proposals`)

The STAGED / LIVE model

Related