MBQuality: MusicBrainz Metadata Quality Platform

MBQuality checks a manageable sample of MusicBrainz recordings for likely title, artist, and metadata problems, then helps a human reviewer decide what is safe to change.

It uses a bounded DuckDB/Parquet pipeline with edit-derived labels, aligned MusicBrainz records, XGBoost detectors, calibration, remediation gates, and a FastAPI/Next.js console.

This repository demonstrates the workflow on a bounded local sample, not the full MusicBrainz catalog; the model results below are not catalog-wide accuracy claims.

The verified local run is a bounded slice, not a full-catalog audit:

Profile:        20260801-002250-local-100000-50000
Core cap:       100,000 rows per selected member
Retained edits: 50,000
Aligned D1 rows: 2,135 recording examples

The independent core/edit caps initially left most edit-linked recordings out of the core sample. The alignment step now scans the preserved core archive for only the recording IDs referenced by the retained edits and creates:

data/warehouse/20260801-002250-local-100000-50000-aligned.duckdb

This aligned warehouse resolved 2,083 of 2,135 D1 training rows with real titles and artist credits.

MusicBrainz archives
        │ bounded extraction
        ▼
base DuckDB warehouse ── targeted edit-linked alignment ──┐
        │                                                  │
        └──────────── compressed Parquet intermediates ◄───┘
                           │
                           ▼
              corpus → grouped splits → D1–D4 detectors
                           │
                           ▼
                 calibration → quality → remediation gate
                           │
                           ▼
                     FastAPI + Next.js console

1. Ingest: stream the pinned MusicBrainz archives and cap selected core/edit members for local execution.
2. Align: append only edit-linked/corpus-referenced recordings and artist-credit rows from the preserved core archive with tools/align_local_recordings.py.
3. Corpus: mine edit-derived labels, build stable negatives, and assign deterministic entity-grouped 70/15/15 train/validation/test splits.
4. Detect: train D1–D4 models. D1 uses text, structural, and graph features; multiclass training uses capped square-root class weighting to reduce clean-class dominance.
5. Measure and remediate: calibrate D1 probabilities, calculate bounded quality artifacts, and route non-clean proposals through monitor/review/auto-apply gates.
6. Serve: expose run artifacts through FastAPI and render the Run Analytics, Live Auditor, Recording Clusters, and Human Review views.

These are held-out results from the aligned local sample and must not be read as catalog-wide metrics:

The multiclass head currently covers clean, version_token_in_title, featured_artist_in_title, title_typo, and wrong_artist. Rare classes remain less reliable than the aggregate weighted score suggests.

The console uses in-slice examples whose labels match D1-compatible detector classes:

Star (remix) (instrumental) — Black Lagoon
El dinero — Sindicato Argentino del Hip Hop feat. Alex Batista
Bonkit Go Johtit (Here and There) — Girls of Angeli
Laetamini in domino — Sarah Pillow, Dongsok Shin, Mary Anne Ballard
Muohtačalmmit (Snowflakes) — Girls of Angeli

Their intended D1 scenarios are, respectively: version token, featured artist, title typo, wrong artist, and clean control. merge_duplicate and artist_credit_formatting are not D1 multiclass outputs; they belong to other pipeline logic and should not be presented as D1 Live Auditor classes.

Use the project virtual environment and install the declared dependencies:

python3 -m venv .venv
.venv/bin/python -m pip install -e '.[all,dev]'

Set a MacBook-sized profile and preserve archives for alignment/resume:

MB_LOCAL_RECORDINGS=100000
MB_LOCAL_EDITS=50000
MBQUALITY_MEMORY_LIMIT=8GB
MB_LOCAL_CLEANUP=0

Run the complete bounded profile:

./tools/run_local_sample_pipeline.sh

If extraction and warehouse loading have already completed:

./tools/resume_local_sample_pipeline.sh

The runner now performs alignment before corpus generation and passes the aligned warehouse explicitly to D1–D4 training and D1 calibration. The alignment utility can also be run directly:

.venv/bin/python tools/align_local_recordings.py \
  --warehouse data/warehouse/20260801-002250-local-100000-50000.duckdb \
  --archive data/raw/archives/20260801-002250/mbdump.tar.bz2 \
  --output data/warehouse/20260801-002250-local-100000-50000-aligned.duckdb \
  --force

Start the local API and frontend:

.venv/bin/python -m uvicorn serving.app:app --host 127.0.0.1 --port 8000
cd frontend && npm run dev -- --hostname 127.0.0.1 --port 3000

Useful API checks:

curl http://127.0.0.1:8000/health
curl http://127.0.0.1:8000/summary
curl http://127.0.0.1:8000/examples/recordings

Runtime artifacts are intentionally excluded from Git:

data/       local warehouses, Parquet, corpora, and reports
models/     trained model bundles
logs/       runner and service logs
.env        local operator settings

The source code, tests, runner scripts, and documentation are the reproducible project surface; generated data and models must be rebuilt locally from the pinned profile.

1. Bounded and biased sample: The verified run is a 100k-core/50k-edit local slice, not the full MusicBrainz catalog. First-N extraction plus edit-linked alignment is still not a representative random catalog sample.
2. Edit-derived labels: Positive labels come primarily from historical edits and can encode editor noticeability bias. They are not an independent gold standard.
3. Small rare classes: Version-token and featured-artist validation counts are small; per-class results are unstable. The reported aggregate scores should not be generalized beyond this run.
4. External verification: A few examples were manually checked against MusicBrainz web metadata, but no large independent human-labeled evaluation set has been completed.
5. Coverage: Lyrics, audio semantics, and complete Cover Art Archive validation are outside the current bounded D1 scope; D3/D4 may have sparse data in this slice.
6. Remediation safety: Wrong-artist changes remain review-only. Offline fallback logic does not invent artist replacements, and clean predictions do not create remediation proposals.