# GAP minimal reproduction package

This repository contains the generation and verification pipeline for GAP:
four surface-renaming families and one proof-plan-preserving kernel variant.
It is intentionally small and includes one canonical Putnam example for an
end-to-end check.

## One-click reproduction

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

1. installs the package;
2. loads one canonical problem;
3. generates four surface variants;
4. runs the five-stage kernel pipeline;
5. applies five judges until the same candidate receives two consecutive
   unanimous rounds;
6. exports and validates one machine-readable GAP record.

The default live model is `o3`. Set `OPENAI_API_KEY` before starting Jupyter,
or enter it in the notebook's hidden prompt. The key is not written to the
notebook or run artifacts.

To test the complete software path without API calls:

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

Offline smoke mode uses scripted model responses. It validates pipeline wiring,
verification control flow, and release assembly; it does not evaluate generated
mathematical content.

## 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 after both runs complete:

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

## Protocol

The kernel path consists of:

1. reference solution → proof DAG;
2. proof DAG → content-free method plan;
3. guarded replacement at a DAG leaf;
4. replacement diffusion through the fixed DAG;
5. regenerated proof → self-contained problem statement.

Verification uses `J=5` judges, requires `K=2` consecutive unanimous rounds for
the same candidate, and permits at most `T=15` rounds. A non-unanimous round
resets the pass streak and triggers repair.

`STAGE_MAP.md` maps each paper operation to the implementation and its validated
output. Every model call and intermediate stage is saved below the selected run
directory for inspection.

## Reproducibility scope

LLM generation is stochastic, so repeated live runs need not produce identical
wording. This package reproduces the prompts, transformation stages, typed
structural checks, verification state machine, and release format.