# Butterfly Foundation Paper

Reproducible theory and experiment package for:

> From Autoregressive Generation to Decision Readouts under Exogenous Chance

## Intended workflow

1. Read `CLAIMS.md` and `EXPERIMENT_PROTOCOL.md`.
2. Run exact identity tests.
3. Run the tabular pilot and full suite.
4. Install the optional neural dependency and run the causal-Transformer suite.
5. Generate figures and tables.
6. Compile `paper/main.tex`.

All reported numbers must be generated beneath `results/`; figures used by the
paper are generated beneath `paper/figures/`.

## One-command reproduction

The exact and tabular experiments require Python 3.11+ with the packages in
`requirements.txt`. The neural experiment additionally requires the CPU
PyTorch environment in `.venv-cpu`.

```bash
python3 -m pip install -r requirements.txt
python3 -m venv .venv-cpu
.venv-cpu/bin/python -m pip install -r requirements.txt -r requirements-neural.txt
bash scripts/run_full.sh
python3 scripts/make_figures.py
cd paper && latexmk -pdf -interaction=nonstopmode -halt-on-error main.tex
```

## Fast verification

```bash
PYTHONPATH=src python3 -m unittest discover -s tests -v
python3 -m py_compile src/butterfly/*.py scripts/*.py
```

## Package map

- `CLAIMS.md`: claim hierarchy frozen before the new results.
- `EXPERIMENT_PROTOCOL.md`: pre-specified interventions, metrics, and rejection rules.
- `src/butterfly/`: environment, exact dynamic programs, identities, and estimators.
- `scripts/`: exact, tabular, neural, figure, and full-run entry points.
- `results/`: row-level outputs and Transformer learning curves.
- `paper/`: canonical English LaTeX manuscript, references, and generated figures.
- `tests/`: numerical identity and estimation-bound tests.

The experiments are synthetic. They validate implementation and predictions
of the theory, not causal claims about human lives.
