Interfaces¶

NERB exposes the same extraction behavior through a shell CLI, Python helpers, and a local stdio MCP server. Use the surface that matches the caller, and keep shared behavior in the bank itself.

Equivalent Extraction Paths¶

nerb extract-text \
  --bank company.json \
  --text "Send this to Acme Corp today."
nerb extract-text --bank company.json --file email.txt
nerb extract-file --bank company.json --file email.txt
nerb extract-report --bank company.json --file email.txt

from nerb import extract_file, extract_report_file, extract_text, load_bank

bank = load_bank("company.json")
result = extract_text(bank, "Send this to Acme Corp today.")
file_result = extract_text(bank, file_path="email.txt")
dedicated_file_result = extract_file(bank, "email.txt")
report = extract_report_file(bank, "email.txt")

{
  "mcpServers": {
    "nerb": {
      "command": "nerb-mcp"
    }
  }
}

CLI¶

The CLI is the best surface for CI, local bank authoring, and shell-driven reports:

nerb validate-bank --bank company.json
nerb diff-banks old-company.json new-company.json
nerb regress-bank \
  --old-bank old-company.json \
  --new-bank new-company.json

Config-backed YAML detector commands are also available for compact regex detector authoring:

nerb init --config detectors.yaml
nerb add ARTIST "Pink Floyd" 'Pink\sFloyd' --config detectors.yaml
nerb extract --all \
  --text "Pink Floyd played progressive rock." \
  --config detectors.yaml \
  --format json

Python API¶

Use JSON-bank helpers for agent, service, and test integrations:

from nerb import benchmark_bank, extract_text, load_bank, validate_bank

bank = load_bank("company.json")
assert validate_bank(bank)["valid"]
records = extract_text(bank, "Acme Corp renewed.")["records"]
file_records = extract_text(bank, file_path="email.txt")["records"]
timings = benchmark_bank(bank)

Use Bank directly when you want the Rust-backed source-bank API:

from nerb import Bank

bank = Bank.from_source_bytes(b'{"CODE":{"Alpha":"Alpha"}}', format_hint="json")
records = bank.scan_text("Alpha")

MCP Server¶

Run the local stdio server:

nerb-mcp --version

Installed-package client config:

{
  "mcpServers": {
    "nerb": {
      "command": "nerb-mcp"
    }
  }
}

From a source checkout:

{
  "mcpServers": {
    "nerb": {
      "command": "uv",
      "args": ["run", "nerb-mcp"],
      "cwd": "/path/to/nerb"
    }
  }
}

MCP tools read explicit config/document paths or provided text. Write tools require explicit output paths, and extraction tools read exactly one source: provided text or an explicit document file_path.

Record Contract¶

Rust-backed records include:

JSON-bank extraction enriches records with entity_id, name_id, pattern_id, pattern_kind, and captures.