# Suite28 — Dynamic Readiness–Requirement Model (DRRM)

**Main research model:** `suite28_drrm`, a standalone dynamic multidimensional course-readiness predictor. No Committee predictions, GNN, TabM, TabR, or other prior-score anchors are input to the primary model.

This package implements and tests the user's attached **Suite28_research_and_design(1).md** specification. The independent comparison arms are contextual-only DRRM, compensatory dynamic MIRT, and a full-feature HGB current-state model. It reports prior-suite score comparisons wherever actual reference files exist. Read `DESIGN.md` for the final specification and explicit assumptions.

## Quick start on the AQ server

```bash
cd /root/disk_3tb/earlywarning/30072026
unzip suite28_dynamic_readiness_requirement.zip
cd suite28_dynamic_readiness_requirement
chmod +x run_suite28.sh run_suite28_pilot.sh
./run_suite28.sh
```

The wrapper uses `/root/miniconda3/envs/Huy/bin/python3` by default; set `PYTHON=/path/to/python` to override. Logs append to `/root/disk_3tb/earlywarning/30072026/log/suite28_dynamic_readiness_requirement.log`. Results go to `results/suite28_dynamic_readiness_requirement`.

The driver checks all seven canonical/structured folds for compatible student-semester context features and outputs detailed preflight evidence before training. **F6/F7 were already involved in prior research; they are historical comparisons, not untouched prospective validation.**

### Recommended two-phase execution

1. **Environment and data contract** (no expensive training):

```bash
/root/miniconda3/envs/Huy/bin/python3 check_suite28_environment.py
/root/miniconda3/envs/Huy/bin/python3 train_suite28_drrm.py --preflight-only
```

2. **Compute/cost pilot** on IT plus Japanese faculties, with a unique output directory (never treat this as project results):

```bash
./run_suite28_pilot.sh
```

If runtime and memory fit the available V100-SXM2-32GB machine, execute `./run_suite28.sh` for the complete frozen F1–F7 experiment.

### Optional ablations

Run an additional `K=1` dimensionality control and a *retrained* binary-only likelihood control with `--extended`. They incur extra training time. Do not decide to run them based on F6/F7 metrics: the intended staged research gate is F4/F5 development evidence.

The `--max-epochs`, `--steps-per-epoch`, `--min-dev-coverage`, `--tau`, and other overrides are explicit changes to the scientific recipe; **record those changes** if used. A nonzero `--steps-per-epoch` is an approximate training budget, not a full pass through the data.

## Input files

- `results/cross_faculty_residual_moe/cache/{faculty}_fold_{f}.joblib`
- `results/suite12_structured_cache/{faculty}_fold_{f}.joblib`

Required canonical keys: `Xtr`, `Xte`, `ytr`, `yte`, `feature_names`, `train_frame`, `test_frame`, `cf_covered_mask`, `cf_probabilities` and `pte`/`qte`; `train_frame` needs `IDSV`, `IDMH`, `target_NHHK`, `target_grade10`. Required structured keys: `train_row_index`, `train/target.course_target` with 17 dimensions. The original raw data generators are not included and their complete as-of provenance cannot be certified from these caches. The code reconstructs the **five course history aggregates** from allowable earlier outcomes and asserts source alignment.

Numerical grades outside `[0,10]` count as missing, with grade/failure disagreement raising a hard error. Target labels and grades are always withheld from the inference tensors, even though they remain available for reporting.

## Main outputs

- `development_epoch_grid.csv`, `development_support.csv`, `frozen_epochs.json`
- `all_fold_metrics.csv`, `paired_comparisons.csv`, `reference_coverage.csv`
- `fold_N_scores.csv`, `faculty_fold_N_scores.csv` (student/course/semester/source-row identifiers included)
- `fold_N_readiness_uncertainty.csv`, `fold_N_grade_likelihood.csv`
- `requirement_geometry.csv`, `state_geometry_samples.csv`, `filter_parameters.json`
- `postfit_interventions.csv`, `support_strata.csv`
- `historical_council_overlap_not_row_aligned.csv`
- `student_cluster_bootstrap.csv`, `frozen_operational_thresholds.csv`, `operational_holdout.csv`
- `timings.csv`, `frozen_premise_audit.json`, `manifest.json`, `fold_N/*.pt` plus preprocessing caches

Historical Council archival reference covers **13 faculties**; English has no comparable Council archive. It is reported separately from actual per-row reference scores and cannot support row-level bootstrap. Positional score matches are clearly identified in `reference_coverage.csv`.

## What result counts as success?

Evaluate **the standalone DRRM**, not any mixture with Committee. A meaningful result would improve both F6 and F7, many of 14 faculties, the IT Council gap, F2 warning policies, and the best historical all-faculty blends by **approximately +.02 macro AP**. The smaller but scientifically essential tests are DRRM vs retrained contextual-only and DRRM vs compensatory MIRT. A model that improves grade NLL but loses AP has not solved the risk-ranking objective. A model whose requirements have effective rank ~1 has not established a multidimensional readiness mechanism.

## Validation

See `VALIDATION.md`. Unit tests and synthetic fixtures test *software contracts*, not real AQ predictive results. Real caches must be tested on the server before claiming experimental success.
