# Reproducibility

Version 0.1 · 2026-11-09. All commands run from the repository root. PY=.venv/bin/python.

# 1. Environment

Reference machine (recorded in every run header):

• Apple M5 Max, 48 GB, macOS 27.0, arm64, 18 CPUs;
• Python 3.14.4;
• .venv on Homebrew Python with system site-packages.

Library versions (logged by htr.utils.provenance.run_header):

Other packages present on the reference machine:

• sentence-transformers 5.5.0, with all-MiniLM-L6-v2 cached locally. It is loaded with HF_HUB_OFFLINE=1 and never downloaded.
• PyMuPDF 1.27.
• pandoc and TeX Live (xelatex, latexmk, biber) for the paper.

Clean environment:

python3 -m venv .venv
.venv/bin/pip install -e ".[api,hf,dev]"     # pyproject.toml; Python >= 3.12
.venv/bin/python -m pytest tests -q -m "not network"

Run headers. Every summary or manifest JSON starts with a run header containing created_at (UTC), git{commit,branch,dirty}, libraries and hardware. The pilot artefacts record a dirty tree (git.dirty = true). Confirmatory runs must be made from a clean, committed tree. A run with dirty = true is development evidence only.

# 2. Pipeline commands

Notes on the commands.

• Rewrite selection. rewrite.py selects passages stratified by (discipline, section role) with --seed. Only splits listed in --allowed-splits are eligible.
• Spend. No money is spent without --live.
• Corpus default path. The --corpus default in several scripts is data/parsed/pilot. The existing pilot directory is data/parsed/pilot_pmc, so pass it explicitly.

# 3. Seeds and determinism

What else is deterministic.

• Request ids are deterministic, so re-running a job skips completed requests.
• Inference is deterministic: greedy or beam, no sampling.
• MPS kernels are not guaranteed bit-identical across OS or torch versions. Report three training seeds instead of relying on bitwise reproducibility.

# 4. Data hashes and provenance

Per document:

• raw_sha256;
• the provider MD5 and its verification (provider_md5_ok; 0 failures in 1 300 fetches);
• the licence record with its evidence;
• the date with its evidence;
• acquired_at.

Other identifiers and hashes:

• Passages: text_sha256, and ids derived from (doc, paragraph index, text hash).
• Rewrites: provider, model, prompt_version (rw-1.0), prompt fingerprint (sha256 of system + preserve + variants), request id, usage and cost.
• Pairs: validator_version (val-1.0).
• Gutenberg catalog: sha256 recorded in its manifest.

# 5. What is committed and what is not

Consequence. Third parties regenerate the data from the manifests and the commands above. Release-eligible parsed text is distributed only through the benchmark bundle (LICENSE_MATRIX.md). The API key is read from the environment (ANTHROPIC_API_KEY) and is never written to disk by the code.

# 6. From a clean environment to Gate F

1. Clone gitsrv:srv/git/wpai0002_uqo.git.
2. Create the venv as in §1 and run the unit tests.
3. Run scripts/vertical_slice.sh (no network, no cost) to check the pipeline end to end.
4. Load a released checkpoint:
   pythonCopy

   HTRReconstructor.from_pretrained(dir).reconstruct(text, metadata)

   Or run scripts/predict.py --checkpoint <dir>.
5. Gate F re-runs step 4 on a machine that never saw the training data, and compares outputs bit-for-bit with the release's reference outputs on CPU.

# Known test-environment issue (2026-11-09)

On the laptop, running the full unit suite while a PyTorch MPS training process is active can crash the test interpreter with a native stack trace in embedding (observed with torch 2.12 / Python 3.14 when tests/unit/test_models.py runs after another module; test_models.py alone passes). The suite passes (47 tests) when no MPS training is running. Run pytest on an idle machine or on CPU-only nodes; this is an environment interaction, not a test failure of the code under test.