# Suite20 — Semester-Aware Target-Conditioned Academic Transformer

## Research question

Does **explicit semester-level longitudinal modeling** add predictive information beyond the strong flat engineered AQ representation when we retain the fast **shared cross-faculty** training paradigm?

Suite20 deliberately avoids the expensive Suite19 representation-audit recipe. It trains the failure predictor directly and uses the same broad chronology philosophy as Suites 13–18: older historical blocks for training, latest historical blocks for epoch selection, one production refit on all available history, then prediction of the target fold.

## Three jointly evaluated variants

1. `suite20_flat` — shared cross-faculty flat neural ensemble control.
2. `suite20_gru` — the same flat branch plus an explicit semester-sequence GRU.
3. `suite20_transformer` — **primary model**. Semester Transformer + target-course-conditioned cross-attention + flat branch + faculty-conditioned fusion.

The Transformer therefore has to earn its complexity against both the flat control and a much cheaper recurrent temporal model.

## Primary architecture

For each student-course target row:

```
chronological prior-semester summaries
          |
          v
  Semester Transformer
          |
          |        target-course representation + faculty embedding
          +------------------- query -------------------+
                                                       |
                                              Cross Attention
                                                       |
                                                  z_temporal
                                                       |
136 shared flat features --> shared flat branch --> z_flat
                                                       |
                                    learned temporal gate + interaction fusion
                                                       |
                                  parameter-efficient ensemble prediction heads
                                                       |
                                             P(grade < 5)
```

Courses from the target semester are never inserted into the historical semester sequence. The existing structured cache contains only semesters strictly before the target semester.

## Important methodological boundary

Suite20 still reuses the **chronology-safe eligible historical row universe** from the canonical cross-faculty cache and the Suite12 structured cache. These rows are identified by the old `cf_covered_mask`, because that is the row universe for which the structured tensors were built. **Suite20 does not consume the Committee/OOF probabilities as an input.** The Committee is loaded only for post-hoc result comparison.

This is very different from Suite19: no deep representation is repeatedly refit to manufacture OOF latent spaces, no contrastive objective is used, and no downstream probe is trained on learned latent coordinates.

## Training recipe

For each target fold:

1. Concatenate all faculties into one shared training population.
2. Within each faculty, reserve the latest 3 historical blocks for chronological epoch selection.
3. Fit scalers on the older training portion only.
4. Select training duration by macro-faculty AP (with a small pooled-AP term).
5. Fit fresh scalers on all historical rows.
6. Reinitialize the network and refit for the selected number of epochs on all history.
7. Evaluate the target fold.

Folds 1–5 remain development folds; folds 6–7 are the primary holdout folds.

## Imbalance handling

Training batches use faculty-balanced + effective-number class-balanced weighted sampling (`beta=0.9999`). This prevents large faculties and the normal class from dominating a shared model without introducing a separate per-faculty model.

## Diagnostics written by the run

- per-fold/per-faculty AP, AUC, Brier, P/R/F1/F2 at 10/15/20/25% warning budgets;
- direct comparison against Committee, Council, V2 and available Suites 7–18;
- F6/F7 macro summary and head-to-head win rates;
- Transformer-vs-flat temporal uplift per faculty;
- Transformer-vs-GRU comparison through the ordinary metric tables;
- prior-semester coverage and missing-history rate;
- learned temporal-gate strength by faculty and outcome;
- target-conditioned attention by semester position;
- ensemble disagreement/uncertainty quartiles;
- post-hoc **reverse-history** and **zero-history** perturbation diagnostics to verify whether the Transformer actually uses temporal information.

The perturbation diagnostics are never used for model selection.

## Run

Copy the `suite20_semester_target_transformer` directory under:

`/root/disk_3tb/earlywarning/30072026/`

Then:

```bash
cd /root/disk_3tb/earlywarning/30072026/suite20_semester_target_transformer
chmod +x run_suite20.sh
./run_suite20.sh
```

Log:

`/root/disk_3tb/earlywarning/30072026/log/suite20_semester_target_transformer.log`

Results:

`/root/disk_3tb/earlywarning/30072026/results/suite20_semester_target_transformer`

## Runtime controls

The default run evaluates three variants across all seven folds. If this is still heavier than desired, the fastest scientifically valid first pass is:

```bash
python3 train_suite20_semester_target_transformer.py \
  --folds 1,2,3,4,5 \
  --variants flat,gru,transformer \
  --samples_per_epoch 150000
```

Do **not** select the architecture using F6/F7.

For a pure smoke test:

```bash
python3 train_suite20_semester_target_transformer.py \
  --folds 1 \
  --faculties khoa_cong_nghe_thong_tin,khoa_quan_tri_kinh_doanh_va_du_lich \
  --epochs 2 \
  --patience 1 \
  --samples_per_epoch 10000 \
  --batch_size 512
```

## Interpretation

The key scientific comparison is not merely Suite20 vs Suite17/18. It is:

`Suite20 Transformer - Suite20 Flat`

If that delta is broadly positive on F6/F7, raw semester history contains information not adequately summarized by the flat engineered features. If GRU gains similarly, recurrence may be sufficient. If the Transformer clearly exceeds GRU, target-conditioned attention is adding value. If neither temporal model improves, we should not invest in a more elaborate temporal architecture.
