# GAP minimal reproduction package

This repository provides a one-item end-to-end reproduction of GAP: four
surface-renaming families and one verified kernel variant.

## One-click reproduction

Open `GAP_End_to_End.ipynb` and choose **Run All**. The notebook:

1. installs the package;
2. loads one canonical Putnam problem;
3. generates the four surface variants;
4. extracts the kernel proof plan and mutable slots;
5. generates a new question and complete solution with the same plan;
6. runs five judges until the unchanged candidate receives two consecutive
   unanimous rounds;
7. exports and validates one machine-readable GAP record.

The default model is `o3`. Set `OPENAI_API_KEY` before starting Jupyter, or
enter it in the notebook's hidden prompt. The key is never saved.

For a no-API software check:

```bash
GAP_OFFLINE_SMOKE=1 jupyter notebook GAP_End_to_End.ipynb
```

Offline smoke mode uses fixed responses. It validates pipeline wiring,
verification control flow, and release assembly; it does not assess generated
mathematics.

## Prompt fidelity

Generation, surface-renaming, judge, and repair prompts are copied verbatim
from the original author source and the prompt listing in the paper. Their
UTF-8 SHA-256 digests are pinned in `PROMPT_SHA256SUMS` and enforced by
`tests/test_prompts.py`.

The OpenAI adapter does not send `temperature`; this is compatible with `o3`,
whose supported value is its default.

The conceptual five stages are represented explicitly in saved artifacts.
The original implementation batches stages 1–3 into Prompt-A and stages 4–5
into Prompt-B; the wrapper does not change those prompts. See `STAGE_MAP.md`.

## Install and test

```bash
python -m pip install -e '.[api,test]'
pytest
```

Without installation:

```bash
PYTHONPATH=src pytest
PYTHONPATH=src python -m gap_pipeline.cli --help
```

## Live one-item commands

Generate the kernel variant:

```bash
export OPENAI_API_KEY=...
PYTHONPATH=src python -m gap_pipeline.cli generate-kernel \
  --dataset examples/sample_data \
  --item-id 1998-B-1 \
  --run-dir runs/kernel \
  --proposer-model o3 \
  --judge-model o3
```

Generate all surface variants:

```bash
PYTHONPATH=src python -m gap_pipeline.cli generate-surfaces \
  --dataset examples/sample_data \
  --item-id 1998-B-1 \
  --run-dir runs/surface \
  --proposer-model o3
```

Assemble the final record:

```bash
PYTHONPATH=src python -m gap_pipeline.cli export-release \
  --source-dataset examples/sample_data \
  --surface-run-dir runs/surface \
  --kernel-run-dir runs/kernel \
  --output-root release \
  --item-id 1998-B-1
```

## Verification protocol

Kernel verification uses `J=5` judges, requires `K=2` consecutive unanimous
rounds for the same candidate, and allows at most `T=15` rounds. A rejected
round resets the streak and triggers a complete question-and-solution repair.
Every call, stage output, iteration, and final record is saved under the chosen
run directory.