# Suite3 Composite Academic-Warning Design

## Goal
Build one evidence-driven composite model that preserves the stable three-tree committee while exploiting the three Suite2 signals that transferred most consistently: global full-feature HGB meta-learning, multi-window temporal HGB learning, and relational signal for history-rich students. Prevent auxiliary score-scale drift from destroying threshold transfer by unsupervised, rank-preserving alignment to the committee scale.

## Fixed protocol
- Target is grade < 5.
- Faculty defaults to `khoa_cong_nghe_thong_tin`.
- Development folds 1-5; holdout folds 6-7.
- RF, ExtraTrees, HistGradientBoosting base experts and simple-mean committee stay unchanged from `train_v3.py`.
- Cross-fitted historical expert probabilities are used for every learned meta component.
- Holdout labels never tune model, fusion, calibration, threshold, or warning budget.

## Components
### Stable anchor
`q` is the unchanged three-tree simple-mean committee probability.

### Global HGB meta expert (A1)
Input: all prepared raw features + original V2 probability/logit/uncertainty meta features + chronology-safe support features. Fit a strong HGB on all eligible historical OOF rows.

### Temporal HGB experts
Fit the same HGB family on the latest 6 and latest 4 supported historical temporal blocks. `last2` is excluded because Suite2 showed materially worse transfer. Produce a recent-window mean from last6 and last4.

### History-rich relational expert
Reuse the hybrid relational factorization model. It is eligible to affect predictions only when `history_semesters >= 3`. History0/history1_2 retain the tabular composite.

## Rank-preserving score alignment
For each temporal block independently, map each auxiliary score to the empirical quantile distribution of the committee score in that same block. This uses no labels. The mapping preserves the auxiliary ranking (apart from ties) while inheriting the committee's score scale.

Historical prequential predictions are aligned block-by-block. Target predictions are aligned using only the target batch's auxiliary and committee scores, separately for each target temporal block.

## Prequential fusion selection
Use recent eligible historical temporal transitions. For each validation block, train component models strictly on earlier blocks, predict the block, then align predictions to that block's committee distribution.

Search a small convex grid:
- `w_a1` in {0, .25, .5, .75, 1}
- `w_recent` in {0, .25, .5, .75, 1} with `w_a1 + w_recent <= 1`
- committee weight is `1 - w_a1 - w_recent`
- history-rich relational alpha in {0, .1, .2, .3, .4}

The relational adjustment is applied only to history-rich rows.

Select a non-committee candidate only when historical forward evidence is robust: positive median AP uplift, majority AP win rate, and bounded worst-block degradation. Otherwise use the committee exactly.

## Evaluation and diagnostics
For every temporal test fold print and save:
- committee AP/AUC and 20%-budget F2
- raw and aligned A1 AP/AUC
- raw and aligned recent-window AP/AUC
- raw and aligned relational AP/AUC
- composite without relational and final composite
- selected weights and historical per-block deltas
- score mean/std/q10/q50/q90 before and after alignment
- Spearman/rank-preservation diagnostic
- history-regime rows, prevalence, AP/AUC, and relational uplift
- component disagreement/correlation matrix
- committee counterfactual under fixed development threshold and drift-aware warning budget

After folds 1-5, tune one frozen F2 threshold and warning ratio from final Suite3 development predictions. Apply unchanged to folds 6-7 and print fixed/drift-aware confusion matrices and pooled metrics.

## Success interpretation
Primary evidence is forward-fold AP/AUC and operational F2 at comparable workload. Concatenated pooled AP is retained but explicitly interpreted alongside per-semester metrics because Suite2 demonstrated cross-semester score-scale artifacts.
