Add anonymous KAFT MVP reproduction

1 files changed, 100 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..422ebed
--- /dev/null
+++ b/README.md
@@ -0,0 +1,100 @@
+# Anonymous KAFT MVP reproduction
+
+This repository is a minimal, self-contained reproduction of two core
+observations for deep message-passing GNNs:
+
+1. a plain deep GCN can lose usable backward transport even when a
+   standardized hidden-state probe remains informative; and
+2. Kronecker-Aligned Feedback Training (KAFT) improves training while leaving
+   the forward GCN unchanged.
+
+The package intentionally contains only the code needed for this MVP. It does
+not include manuscript files, review material, cached datasets, private paths,
+or repository history.
+
+## One-click notebook
+
+Open `reproduce_mvp.ipynb` and choose **Run All**. The first cell installs the
+local package, the experiment downloads Cora automatically, and the remaining
+cells train BP and KAFT, run the gradient diagnostic, display the result
+tables, and save machine-readable artifacts.
+
+The same notebook can be executed non-interactively:
+
+```bash
+python -m pip install -r requirements.txt
+jupyter nbconvert \
+  --to notebook \
+  --execute reproduce_mvp.ipynb \
+  --output reproduce_mvp.executed.ipynb \
+  --ExecutePreprocessor.timeout=1200
+```
+
+## Command-line reproduction
+
+```bash
+python -m pip install -e .
+python run_mvp.py
+```
+
+The default CPU protocol uses:
+
+- Cora with the public Planetoid split;
+- an identical six-layer, width-64, bias-free GCN forward model for BP and
+  KAFT;
+- seeds 0, 1, and 2;
+- Adam, learning rate 0.01, weight decay \(5\times10^{-4}\), 200 epochs;
+- KAFT diffusion \(\alpha=0.5\), 10 fixed linear propagation steps;
+- hop cap \(K=3\), 64 Gaussian probes, and alignment every 10 steps;
+- a separate ten-layer, 100-epoch BP diagnostic.
+
+KAFT changes only the hidden-layer backward rule. Its graph-side feedback is
+\(P_\ell(\hat A)D(\hat A)\), and its feature-side matrix is aligned to the
+chain-normalized suffix-weight probe target. The output layer uses the true
+cross-entropy error.
+
+## Outputs
+
+Running either entry point writes:
+
+```text
+artifacts/
+├── mvp_results.json
+├── mvp_summary.csv
+└── training_curves.png
+```
+
+The JSON file contains the full configuration, every seed-level result,
+training histories, and the ten-layer gradient diagnostic. Test accuracy is
+reported at the validation peak; the test labels are never used for
+selection.
+
+## Expected behavior
+
+Exact numbers can vary slightly with library versions and hardware. The
+checked-in executed notebook and artifacts record the environment used for
+the release. The intended qualitative checks are:
+
+- KAFT exceeds BP test accuracy in the six-layer comparison;
+- the ten-layer BP diagnostic reaches exact-zero weight gradients;
+- the output-adjacent preactivation error remains finite; and
+- the standardized penultimate hidden-state probe remains above chance.
+
+The checked end-to-end CPU run produced:
+
+| Method | Test accuracy at validation peak |
+|---|---:|
+| BP | \(68.87\pm1.20\%\) |
+| KAFT | **\(78.53\pm1.33\%\)** |
+
+For the separate ten-layer BP diagnostic, all ten weight gradients were
+exactly zero in 3/3 seeds. The output-adjacent error remained between
+\(1.26\times10^{-4}\) and \(1.60\times10^{-4}\), while the standardized
+penultimate probe obtained 51.4--57.8% accuracy (seven classes).
+
+## Scope
+
+This is a compact verification path, not the complete experimental suite.
+It covers the diagnostic and the central BP-versus-KAFT mechanism on one
+standard benchmark. The full evaluation uses additional datasets, backbones,
+depths, normalizers, and ablations.