# GAP minimal reproduction package

This repository provides a one-item end-to-end reference implementation of
GAP: four surface-renaming families and one verified kernel variant. The
default kernel path executes the manuscript's five conceptual operations as
five typed, separately saved model calls.

## 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. constructs a concrete proof DAG whose nodes are intermediate claims;
5. abstracts one content-free method label per DAG node;
6. records guarded old/new replacements and propagates them node by node;
7. renders the diffused terminal claim into a new question and solution;
8. runs five judges until the unchanged full-provenance bundle receives two consecutive
   unanimous rounds;
9. exports and validates one machine-readable GAP record.

The default model is `o3`. Set `OPENAI_API_KEY`, place
`OPENAI_API_KEY=...` in the gitignored `.env` file, or enter it in the
notebook's hidden prompt. The key is never written to run artifacts.

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

The historical two-call Prompt-A/Prompt-B, surface-renaming prompts, and
review/repair prompts recovered from `PutnamVariants@c3bed737` remain byte
pinned in `src/gap_pipeline/prompts.py`, `PROMPT_SHA256SUMS`, and
`tests/test_prompts.py`. They document the actual original generator.

The executable manuscript-aligned prompts are in
`src/gap_pipeline/kernel_prompts.py`. They refine the historical intent into
five explicit contracts because the recovered original generator only made
two calls and did not emit a concrete DAG, applied replacement map, or
node-by-node diffusion trace. This distinction is deliberate and auditable,
not hidden as prompt identity.

The OpenAI adapter does not send `temperature`; this is compatible with `o3`,
whose supported value is its default. See `STAGE_MAP.md` for the exact
paper-to-code and historical-source maps.

`ProofDAG` supports branching dependencies and validates topological order,
known dependencies, acyclicity, and terminal connectivity. Replacement plans
record the exact old/new value, source node, guard condition, and guard
justification. Diffusion must preserve every node ID, dependency, and method
label. Judges must cover every proof-node ID and replacement-slot ID before
their verdict counts.

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

PowerShell equivalents:

```powershell
$env:PYTHONPATH = "src"
python -m pytest
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
```

In PowerShell, use `$env:OPENAI_API_KEY = "..."` and backticks for line
continuation, or use the gitignored `.env` file through the notebook.

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 complete provenance bundle, and allows at most `T=15`
rounds. A rejected round resets the streak and reruns stages 3--5 from a new
guarded replacement plan using the judge feedback. Every call, stage output,
iteration, and final record is saved under the chosen run directory.

## Scope

This package demonstrates and tests the one-item software path. It does not
reconstruct unavailable proposal/rejection logs from the original 1,051-item
generation run, and a successful LLM verification loop is not a substitute for
the separate blinded mathematical audit described in the rebuttal plan.