docs/adding-a-released-interview.md

Adding a released interview to the demo

Goal: two or three interviews the museum has already released, each with video and a catalogue record, so the demo shows CuratorBot on real material and the back-test shows how its headings compare with the cataloguers'.

1. Choose and clear the interviews

• Pick interviews that differ: one mostly English, one with another language (Yiddish, Polish, Hungarian), one from a less represented region.
• Confirm with the museum, in writing, that you may process them and show the resulting brief to the partners you name (or publicly). Record the agreement in private/<ID>/permissions.md.

2. Gather the material (kept out of git)

private/<ID>/media/<ID>.01.03.mp4 ...     the parts, in order
private/<ID>/catalogue.json                {"id": "<ID>", "title": "...", "subjects": ["...", "..."]}
private/<ID>/donor.json                    optional donor-style fields to test the donor check

Copy subject headings from the catalogue record exactly, one string per heading. Add any of them that are missing from curatorbot/data/vocabulary.txt, so the back-test is fair; better, replace the vocabulary with the museum's authority export.

3. Transcribe on a GPU

Colab: open notebooks/prepare_on_colab.ipynb. Workstation:

python scripts/prepare_interview.py --id <ID> --media private/<ID>/media/* --catalogue private/<ID>/catalogue.json --device cuda

The first run stops after writing work/<ID>/transcript.txt.

4. Review the transcript (about 20 minutes per hour of audio, skimming)

• Fix speaker roles (Q: interviewer, A: narrator).
• Fix names of people and places Whisper got wrong; do not rewrite testimony.
• Mark non-English passages: keep the original line and add a translation in a following line A: (Translation: ...), or leave them for the flags.

5. Build the brief and back-test

python scripts/prepare_interview.py --id <ID> --transcript work/<ID>/transcript.txt --catalogue private/<ID>/catalogue.json

This writes data/interviews/<ID>/brief.json and backtest.json and prints recall against the catalogue.

6. Check, then deploy

• Open the brief locally (curatorbot serve), read the summary, spot-check every heading quote and every contradicted donor claim.
• Commit data/interviews/<ID>/brief.json only if the release terms allow; push, and the Space updates.
• Put the back-test figures in the pitch: "CuratorBot suggested N of the M headings your cataloguers assigned, each with the moment it was said."