# Suite27 — memory-conditioned native gradient boosting

Complete standalone training/reload/reporting package. Read `DESIGN.md` for the finalized model contract and `evidence/production_analysis.md` for the verified Suite26 diagnosis and full faculty comparisons. `VALIDATION.md` records actual software checks; synthetic checks do not establish academic AP improvement.

## Run on your server

Extract the ZIP, enter `suite27_memory_conditioned_boosting`, and use the environment that ran Suite26. Dependencies are listed in `requirements.txt`; the wrapper does not install or change them. Your existing PyTorch environment can be selected explicitly:

```bash
export PYTHON=/root/miniconda3/envs/Huy/bin/python3
bash run_suite27.sh --device cuda --preflight-only
bash run_suite27.sh --device cuda
```

Use `--device cpu` if CUDA is unavailable. CUDA accelerates course-reader operations; custom histogram growth and stock GBDT use CPU. Defaults are all seven folds, all discovered faculties, all six variants, seed 20261002, two supported earlier origins, depth 3/4, 32/64/96/128 trees and path strengths 0/1.5. Full origin/grid/co-adaptation fitting can be expensive. First run the included small software smoke workflow and then a development-fold pilot if resources need measuring:

```bash
PYTHON=python3 bash smoke_test.sh
bash run_suite27.sh --device cuda --folds 2 --out-dir /root/disk_3tb/earlywarning/30072026/results/suite27_pilot
```

The pilot uses production support thresholds and the real recipe. It is not a basis for changing settings using F6/F7 outcomes. Optional paired seeds cost additional complete fits:

```bash
bash run_suite27.sh --device cuda --seeds 20261002 20261003 20261004 \
  --out-dir /root/disk_3tb/earlywarning/30072026/results/suite27_three_seeds
```

Default inputs are unchanged from Suite26:

| Purpose | Default path |
|---|---|
| Canonical caches | `/root/disk_3tb/earlywarning/30072026/results/cross_faculty_residual_moe/cache` |
| Structured course metadata | `/root/disk_3tb/earlywarning/30072026/results/suite12_structured_cache` |
| Results/checkpoints | `/root/disk_3tb/earlywarning/30072026/results/suite27_memory_conditioned_boosting` |
| Combined stdout/stderr log | `/root/disk_3tb/earlywarning/30072026/log/suite27_memory_conditioned_boosting.log` |

`--root`, `--cache-dir`, `--structured-dir` and `--out-dir` override paths. The log appends timestamps, unbuffered printings, errors and tracebacks. Watch it with:

```bash
tail -f /root/disk_3tb/earlywarning/30072026/log/suite27_memory_conditioned_boosting.log
```

`SUITE27_LOG_DIR` or `SUITE27_LOG_FILE` override the log location. The bash wrapper preserves failure exit status through `tee`. It does not overwrite Suite26 results. Results must be empty for a new run.

## Selection and the six comparisons

`stock` is a same-information current-only scikit-learn HGB control. `native` checks the custom current-only backbone. `deterministic` adds fixed recency evidence. `global` learns course relevance. `path` permits completed raw ancestor feedback. `mcgb` additionally selects whether a surrogate reader proposal followed by complete regrowth improves development AP. MCGB is the prespecified research primary; simpler methods can win and are fully reported.

Each candidate uses the same supported faculty/origin/seed cells. By default each origin must match target term, have 2,000 total validation rows, every faculty at least 30 validation rows/five positives/twenty negatives and 30 earlier training rows, plus 5,000 total earlier training rows. These are CLI-configurable with `--origin-*`; all changes are fingerprinted. Every rejected faculty/origin is printed. If none qualifies, training stops with `fold_N/origin_support_failure.csv`; inspect that audit before choosing an explicit policy change. Preflight prints audits and creates no result files. The wrapper still writes its log.

Prior grades are assumed available next semester; timestamps are absent. `--history-embargo 1` excludes the immediately previous semester from memory and cumulative priors, but does not regenerate externally cached raw/course features. Cache provenance and availability remain input assumptions. See `data_audit.json`.

## Monitoring and artifacts

All fold/faculty metrics, support audits, origin selection scores, reader/adaptation gradient summaries, tree usage/gains, history/course regimes, memory interventions, resource timings, keyed prior-reference alignment and coverage are printed and saved. Root reports include AP/AUC, Brier/ECE, warning budgets, matched component/reference comparisons, student-cluster bootstrap intervals, fixed development-policy confusions for every faculty, and unique-student warning workload. Calibration is evaluated; no probability calibrator is added.

Each fold includes selected recipes, all origin/seed selection cells, per-seed keyed scores, whole-model checkpoints, reader/forest logs, tree nodes and memory diagnostics. Root `seed_variation.csv` reports every faculty/fold/seed. Predictions average seeds only if multiple are requested. Prior suite directories are discovered under `root/results`; missing scores remain missing. `--reference-dirs name=/path` can specify exact reference names. `--no-diagnostics` skips postfit intervention/regime runs when profiling, while keeping training/selection/metrics; retain default diagnostics for a full research report.

Postfit removal/shuffle probes measure fitted sensitivity. They are not retrained causal ablations. In Suite27, `no_outcomes` removes both explicit grade and failure history values; permissible priors and metadata remain. `no_memory` uses the explicit empty history state. `uniform_attention` removes course relevance and path bias. `no_path` leaves course relevance intact. A chosen path strength zero or cycle zero is printed as a legitimate selection outcome.

## Resume and reload

Resume with exactly the same arguments plus `--resume`:

```bash
bash run_suite27.sh --device cuda --resume
```

Completed folds are reused only after inventory and hash verification. Incomplete folds rerun. Changes to code, data, runtime versions, schema or settings require a new output directory. Copying the package preserves source hashes; editing its Python/shell files invalidates saved run signatures. Do not mix checkpoints from different packages.

Reload one trusted local checkpoint against its original canonical fold:

```bash
"$PYTHON" predict_suite27.py \
  --checkpoint /root/disk_3tb/earlywarning/30072026/results/suite27_memory_conditioned_boosting/fold_6/model_mcgb_seed_20261002.pt \
  --device cuda \
  --out-file /root/disk_3tb/earlywarning/30072026/results/suite27_memory_conditioned_boosting/reloaded_mcgb_f6.csv
```

The same input fingerprints and feature schema are required. Checkpoints use trusted Python serialization; load your own files. Same-runtime/device reload should reproduce hard scores. Changing CPU/GPU can affect floating-point decisions near hard thresholds. Per-seed checkpoint output differs from an averaged multi-seed score by definition.

## Collect the next report

```bash
"$PYTHON" collect_suite27_reports.py \
  --results-dir /root/disk_3tb/earlywarning/30072026/results/suite27_memory_conditioned_boosting \
  --out-file /root/disk_3tb/earlywarning/30072026/results/suite27_review_reports.zip
```

Default collection includes the compact diagnostics, metrics, audits, settings and fingerprints while excluding weights and row-level predictions. Add `--include-predictions` when keyed reanalysis is needed. Keep the main log alongside the report. Collector paths can also point to pilot results.

## Software checks

```bash
"$PYTHON" -m pip install pytest
"$PYTHON" -m pytest -q tests
PYTHON="$PYTHON" bash smoke_test.sh
```

The smoke workflow runs all six variants on small synthetic canonical caches, preflight, full reports, checkpoint reload, resume and report collection. Its origin minima are intentionally tiny for software testing; do not copy those minima into a production comparison. See `--help` for every option and `VALIDATION.md` for verified versions and remaining empirical limitations.

Optional cost probe (synthetic, frozen untrained reader; no academic metric claim):

```bash
"$PYTHON" benchmark_suite27.py --rows 20000 --trees 4 --out-file suite27_cost_probe.json
```

Reported host RSS is a process-lifetime peak. CUDA peaks are reset per refit. Zero-row requested target faculties appear explicitly in startup support and per-seed/reload printings; ranking macro tables use actual eligible scored cells. Operational thresholds reject development semesters that are not strictly earlier than the first held semester. Legacy metric fixtures without `semester` use numeric fold order, documented in the report conventions.
