# 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`.

Prompt-A's ordered core steps instantiate a path-structured proof-plan DAG:
each step is a typed node and each edge records the dependency on the preceding
step. `ProofPlanDAG` validates unique node IDs, known dependencies, acyclicity,
connectivity to the terminal node, and the extracted order. This path structure
is the precise graph induced by an ordered minimal proof chain. Judges receive
the same method-label sequence with stable node IDs and must report a check for
every node before their verdict is counted.

## 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.