# REPLICATION.md — how to reproduce WP39

# Requirements

• Python ≥ 3.12 with uv (uv venv -p 3.12 .venv && uv pip install -e ".[dev]").
• Access to FinData OS (owner-issued key with scopes read:market, read:fundamentals, query, export) exposed as FINDATA_API_KEY or a mode-600 file at FINDATA_API_KEY_FILE. Without access, Phases 2–5 cannot run; the saved evaluation artifacts in artifacts/evaluation/ and results/ allow Phase 6 (tables/figures/paper) to be regenerated.
• Read-only psql access to the FinData Postgres database on the storage node for scripts/01a_extract_node_tables.sh (earnings events, entities, corporate actions — not yet exposed by the API).
• Internet access to sec.gov (CIK/SIC) and the Kenneth French library (daily factors).
• TeX Live with latexmk for the paper.

# Order of execution (compute node, API on localhost)

export FINDATA_BASE_URL=http://127.0.0.1:8600/api/v1 WP39_CACHE=~/wp39-cache
bash scripts/01a_extract_node_tables.sh          # node extracts + manifests
python scripts/00_probe_findata.py               # contract reconciliation -> artifacts/logs/phase0_probe.json
python scripts/01_audit_universe.py              # universe.parquet, results/universe_audit.json
python scripts/02_build_pit_panel.py             # quarters.parquet (labels), design freeze hash
python scripts/03_build_features.py --workers 8  # streaming exports -> session features -> rolling windows
python scripts/04_build_labels.py                # sample_event.parquet, sample_calendar.parquet, cascades
python scripts/05_train_baselines.py             # B0-B5 logistic, ridge, firm hold-out, walk-forward
python scripts/06_train_advanced.py              # LightGBM equal-budget, horizon ladder, OOF signals
python scripts/07_evaluate.py                    # metrics, paired contrasts, GW tests, Holm, power
python scripts/08_run_robustness.py              # placebos, subgroups, panel regressions, H5
python scripts/09_make_manuscript.py             # tables, figures, results_macros.tex
cd paper && make                                 # main.pdf
pytest -q                                        # 29 tests; WP39_LIVE=1 adds the live API contract tests

Runtime on a Mac Studio M3 Ultra (28 cores): see PROGRESS.md for measured wall-times of each step.

# What is and is not in the package

• In: code, configs, docs, tests, manifests (hashes/versions/counts), derived evaluation tables, figures, paper.
• Out: raw bars and fundamentals (FirstRate Data license), the per-symbol feature cache (derived from licensed data; regenerable), model binaries.
• Determinism: all seeds come from configs/research.yaml (seed: 20261102); LightGBM uses n_jobs=12 with deterministic histogram construction at the default settings, so results are reproducible to numerical precision on the same architecture.