Workflows¶

NERB is built around a small loop: author a bank, validate it, scan documents, inspect diagnostics, and promote changes with diff/eval/benchmark evidence.

Bank Lifecycle¶

Stage	Command	Output
Validate structure	`nerb validate-bank --bank company.json`	Schema and runtime diagnostics
Extract evidence	`nerb extract-text --bank company.json --text "..."`	Deterministic extraction records
Report matches	`nerb extract-report --bank company.json --file email.txt`	Report-oriented records and metadata
Patch safely	`nerb apply-patches --bank company.json --patch patches.json`	Validated candidate response
Compare versions	`nerb diff-banks old.json new.json`	Added, removed, and changed bank elements
Evaluate	`nerb eval-bank --bank company.json`	Eval records and metric summaries
Benchmark	`nerb benchmark-bank --bank company.json`	Compile/cache/scan timing evidence
Promote	`nerb regress-bank --old-bank old.json --new-bank new.json`	Combined promotion gate

Authoring Guidance¶

Keep entity IDs stable and machine-readable.
Put human-readable labels in name, canonical, and description fields.
Prefer literal patterns for exact aliases; reserve regex patterns for real variability.
Set statuses deliberately. Extraction includes active banks, entities, names, and patterns by default.
Store review metadata on the nearest relevant object: bank, entity, name, or pattern.

Validation Strategy¶

Use validation before extraction in automation:

nerb validate-bank --bank company.json

Validation catches schema errors, runtime regex problems, unsafe eval references, overly large metadata, and extraction scope issues before they become ambiguous scan results.

Patching And Promotion¶

Agents and services can propose RFC 6902 JSON Patch operations instead of rewriting entire banks:

nerb apply-patches --bank company.json --patch proposed-patch.json

NERB validates the patched candidate and returns diagnostics alongside the candidate response. Use that result as the review surface, then run regress-bank before promotion.

Evaluation And Regression¶

Evaluation references live in eval_refs on bank objects. Local eval execution requires relative paths under the eval base path; absolute paths, parent traversal outside the base, remote URIs, non-regular files, and invalid UTF-8 are rejected.

nerb eval-bank --bank company.json
nerb regress-bank --old-bank old-company.json --new-bank company.json

Regression combines diff, eval, and benchmark checks so the promotion decision is based on behavior, not just schema validity.

Large Source Banks¶

For large corpora, treat bank construction as an evidence pipeline:

profile the corpus and privacy constraints;
mine aliases into candidate banks;
split eval/train/test references intentionally;
benchmark compile and scan behavior at the expected scale;
keep handoff artifacts reproducible and privacy-safe.

The Enron Benchmark, verified decision, private preparation workflow, train-only bank construction guide, evaluation guide, and large-source bank skill document that deeper workflow.

Measure Enron cache value¶

After a verified train/validation bank build, freeze and smoke-test the private workload before starting the long decision profile:

install -d -m 700 .nerb/enron-scratch
nerb prepare-enron-performance \
  --bank-build-run .nerb/enron/bank-build \
  --development-run .nerb/enron/development \
  --output-dir .nerb/enron/performance-plan \
  --scratch-root .nerb/enron-scratch
nerb run-enron-performance \
  --prepared-run .nerb/enron/performance-plan \
  --output-dir .nerb/enron/performance-smoke \
  --profile smoke
nerb verify-enron-performance --run-dir .nerb/enron/performance-smoke

The commands expose neither a preparation-source nor sealed-test path; profiling is confined to the verified train artifact. Outputs remain private and ignored; only privacy-scanned aggregate evidence is suitable for a later reviewed handoff. The smoke profile is non-promotable. See Performance for the decision command, measurement boundaries, scale semantics, and sample policy.

Verify the published Enron evidence¶

The committed publication needs no private .nerb artifacts:

nerb verify-enron-evidence --bundle evidence/enron
nerb render-enron-evidence \
  --bundle evidence/enron \
  --output-dir /tmp/nerb-enron-render

The normal verifier authenticates the known-bank, natural-text, coverage, standalone-redaction, and performance results. A workflow that specifically requires a comprehensive standalone redaction bank can add --require-standalone-redaction-eligible; that application check fails for the committed bank. It does not gate NERB package releases.