# KAFT minimal reproduction

Run from the repository root. The experiment downloads Cora automatically and
uses CPU by default.

## Entry points

| Path | Command | Purpose |
|---|---|---|
| Notebook | `python -m pip install -r requirements.txt`<br>`jupyter nbconvert --to notebook --execute reproduce_mvp.ipynb --inplace --ExecutePreprocessor.timeout=1200` | One-click end-to-end reproduction with assertions and displayed tables |
| CLI | `python -m pip install -e .`<br>`python run_mvp.py` | Equivalent non-interactive run |

## Protocol

| Field | Value |
|---|---|
| Dataset / split | Cora / public Planetoid split |
| Forward model | Identical bias-free GCN for BP and KAFT |
| Accuracy run | 6 layers, width 64, seeds 0--2, 200 epochs |
| Diagnostic run | 10-layer BP, seeds 0--2, 100 epochs |
| Optimizer | Adam, learning rate 0.01, weight decay \(5\times10^{-4}\) |
| KAFT graph feedback | Fixed linear diffusion, \(\alpha=0.5\), 10 steps; hop cap \(K=3\) |
| KAFT feature feedback | 64 Gaussian probes; alignment every 10 steps |
| Selection | Test accuracy at the validation peak; test labels are not used for selection |

## Checked reference output

| Method | Test accuracy at validation peak |
|---|---:|
| BP | \(68.87\pm1.20\%\) |
| KAFT | **\(78.53\pm1.33\%\)** |

| Ten-layer BP diagnostic | Checked result |
|---|---:|
| Seeds with all weight gradients exactly zero | 3/3 |
| Output-adjacent error | \(1.26\times10^{-4}\)--\(1.60\times10^{-4}\) |
| Standardized penultimate probe accuracy | 51.4--57.8% |
| Seven-class chance accuracy | 14.3% |

## Verification contract

| Assertion in `reproduce_mvp.ipynb` | Expected |
|---|---:|
| KAFT mean test accuracy exceeds BP | `True` |
| All ten-layer BP weight gradients are exactly zero | `True` |
| Output-adjacent error is finite and nonzero | `True` |
| Standardized hidden probe is above chance | `True` |

## Outputs

| File | Contents |
|---|---|
| `artifacts/mvp_results.json` | Configuration, environment, seed-level results, histories, diagnostics |
| `artifacts/mvp_summary.csv` | BP/KAFT mean, standard deviation, and seed count |
| `artifacts/training_curves.png` | Median training loss and test-accuracy curves |

## Repository contents

| Path | Role |
|---|---|
| `reproduce_mvp.ipynb` | Executed one-click reproduction |
| `run_mvp.py` | Command-line entry point |
| `kaft_mvp/data.py` | Dataset download and normalized sparse adjacency |
| `kaft_mvp/trainers.py` | Matched BP and KAFT trainers |
| `kaft_mvp/experiment.py` | Protocol, aggregation, and artifact generation |
| `THIRD_PARTY.md` | Dependency and license summary |

This MVP covers the central diagnostic and matched BP-versus-KAFT mechanism on
one benchmark; it is not the complete experimental suite.