Getting Started¶

Prerequisites¶

Python 3.14+ (managed via uv)
xsltproc — required for MARCXML → BIBFRAME conversion via marc2bibframe2
Git with submodule support (the marc2bibframe2 XSLT is a git submodule)

Install system dependencies¶

# Debian/Ubuntu
sudo apt-get update && sudo apt-get install -y xsltproc

# macOS (Homebrew)
brew install libxslt

Clone & setup¶

git clone --recursive https://github.com/mikkovihonen/bffi-conversion-pipeline.git
cd bffi-conversion-pipeline
uv sync --frozen

The --recursive flag initializes the third_party/marc2bibframe2 submodule. If you cloned without it:

git submodule update --init --recursive

Run the pipeline¶

1. Create a run directory¶

RUN=$(bffi-pipeline new-run)
echo "$RUN"
# → runs/20260805-1630-a1b2c3/

The run directory is the atomic output boundary for one pipeline invocation.

2. Stage MARCXML input¶

mkdir -p "$RUN/marc"
cp /path/to/records.xml "$RUN/marc/"

3. Convert MARCXML → BIBFRAME¶

bffi-pipeline marc-to-bibframe \
  --input-dir "$RUN/marc" \
  --output-dir "$RUN/bibframe"

4. Convert BIBFRAME → BFFI¶

bffi-pipeline bibframe-to-bffi \
  --input-dir "$RUN/bibframe" \
  --output-dir "$RUN/bffi"

5. Convert BFFI → MARCXML (round-trip)¶

bffi-pipeline bffi-to-marc \
  --input-dir "$RUN/bffi" \
  --output-dir "$RUN/marc-reconstructed"

6. Evaluate round-trip¶

bffi-pipeline roundtrip-eval \
  --source-dir "$RUN/marc" \
  --reconstructed-dir "$RUN/marc-reconstructed" \
  --html "$RUN/eval/review.html"

CLI reference¶

All subcommands accept --help for full option listings:

bffi-pipeline --help
bffi-pipeline marc-to-bibframe --help
bffi-pipeline bibframe-to-bffi --help
bffi-pipeline bffi-to-marc --help
bffi-pipeline roundtrip-eval --help
bffi-pipeline melinda-sync --help
bffi-pipeline new-run --help