# Reproducibility — WP41 CHRONOS-X

## What is needed
- A FinData OS API key with scopes `read:market, query, export` (private FirstRate Data license; the owner can issue one
  with `findata create-key`). Without it, the synthetic example below reproduces the software path only.
- Python 3.12, `uv`; an Apple Silicon Mac (MPS) or a CUDA/CPU machine (slower). Measured budgets: `docs/PHASE_4_REPORT.md`.

## Environment
```bash
make install                                    # uv venv + editable install (torch, polars, pyarrow, lightgbm, arch, ...)
make test                                       # 26 offline tests (+ 1 slow synthetic pipeline test with -m slow)
WP41_LIVE=1 make test-live                      # 5 live contract tests against FinData
```

## License-free example (no FinData access)
```bash
.venv/bin/python scripts/make_synthetic.py                       # 4 synthetic instruments, FinData schema
.venv/bin/python scripts/run_experiment.py --config configs/synthetic_smoke.yaml
.venv/bin/python scripts/evaluate.py --exps synthetic_smoke      # LaTeX tables from the results
```

## Full study (in order; every step writes its artifacts under results/ and its provenance under results/logs/)
```bash
export FINDATA_API_KEY_FILE=~/findata-secrets/api-key-wp41.txt FINDATA_BASE_URL=https://findata.spboucher.ai/api/v1
.venv/bin/python scripts/audit_api.py                                                   # P0
.venv/bin/python scripts/build_universe.py                                              # P1 universe v1 (PIT rules)
.venv/bin/python scripts/audit_coverage.py --candidates --workers 4                     # P1 coverage audit
.venv/bin/python scripts/build_universe.py --min-coverage 0.8 \
   --coverage-file results/metrics/coverage_audit_candidates.csv --out universe_main_v2.json   # -> data/manifests/universe_main.json
.venv/bin/python scripts/download_pilot.py --config configs/pilot.yaml --symbols-from pilot    # P1 pilot bars + grids
.venv/bin/python scripts/run_experiment.py --config configs/pilot.yaml                          # P2/P3 pilot
.venv/bin/python scripts/benchmark.py --config configs/pilot.yaml                               # P4 profiling
.venv/bin/python scripts/download_pilot.py --config configs/main.yaml --symbols-from all        # P4 main bars + grids
.venv/bin/python scripts/run_experiment.py --config configs/main.yaml                           # P5 main (dev test 2024)
.venv/bin/python scripts/run_experiment.py --config configs/ablations.yaml --skip-baselines     # P5/P6 ablations + copula
.venv/bin/python scripts/run_experiment.py --config configs/main.yaml --heldout --skip-baselines   # zero-shot instruments
.venv/bin/python scripts/run_experiment.py --config configs/final.yaml --eval-split final --models-from results/metrics/main   # P7 untouched 2025
.venv/bin/python scripts/evaluate.py --exps pilot,main,ablations,final                          # P8 tables + macros
cd paper && make                                                                                 # P9 PDF
```
Seeds: `train.seed` in each config (1; seeds 2 and 3 in `configs/ablations.yaml`); DataLoader generator seeded with
`seed + step`; evaluation sampling seeded. Checkpoints (`best.pt`, `last.pt`) resume automatically.

## Artifact map
| Artifact | Path |
|---|---|
| Universe manifest (hash inside) | `data/manifests/universe_main.json` |
| API audit, coverage audit, download/grid stats | `results/metrics/p0_api_audit.json`, `coverage_audit_candidates.csv`, `download_*.json`, `grids_*.json` |
| Per-experiment outputs | `results/metrics/<exp>/` (summaries, per-origin scores, leaderboards, comparisons, train logs, checkpoints) |
| Benchmarks | `results/metrics/benchmark_<node>.json` |
| Provenance | `results/logs/provenance_*.jsonl`, `~/wp41-cache/manifests/bars_manifest.jsonl` (node) |
| Paper tables/macros | `paper/tables/*.tex`, `paper/results_macros.tex` (generated by `scripts/evaluate.py`) |
| Phase reports | `docs/PHASE_0..9_REPORT.md` |