# Suite12 — Collaborative Evidence MoE

Suite12 is a direct, end-to-end heterogeneous Mixture-of-Experts experiment for course-failure early warning (`grade < 5`). It deliberately removes the previous `committee + residual correction` constraint.

## Architecture

- **Tree Committee (RF / ExtraTrees / HGB)**: frozen teacher and evaluation reference only; not part of the deployed differentiable forward path.
- **E0 — distilled global expert**: full common flat feature view; multi-head distillation of RF/ET/HGB plus direct failure prediction.
- **E1 — student trajectory expert**: semester-level history through GRU + attention.
- **E2 — course/curriculum expert**: course history + prerequisite/curriculum neighborhood. Its private encoder intentionally receives **no target-student faculty embedding, warning, conduct, workload, or student-history context**.
- **E3 — student-course compatibility expert**: history of student-course outcomes with same-course/prerequisite-aware relation encoding.
- **E4 — mastery expert**: historical assessment/component events with type embeddings and attention.

Private evidence is encoded independently. Only after private encoding do the experts exchange latent evidence. The final prediction is direct:

`P(failure) = Fusion(Collaborate(E0, E1, E2, E3, E4))`

There is no `committee_logit + residual` term and no hard Top-K ownership router.

## Context isolation

Suite12 uses separate context contracts:

- **E0 context**: broad chronology-safe global/support context.
- **Fusion context**: support/availability only (`history_semesters`, `history_rows`, `course_prior_rows`, `new_student`, `new_course`). It intentionally excludes warning, conduct, and workload so the final head cannot become an unintended sixth predictor.
- **E1 context**: student-centric warning/conduct/workload/history context.
- **E2 context**: course-history missingness/support/new-course only.
- **E3 context**: pair-support/history-depth only.
- **E4 context**: mastery-history availability only.

## Hybrid cache

Suite12 reuses the existing Suite5+ canonical cache for:

- flat common features;
- OOF RF/ET/HGB teacher probabilities;
- labels;
- temporal blocks;
- support metadata;
- baseline evaluation alignment.

A separate structured cache is built once from the extracted raw database directory (preferred: `/root/disk_3tb/earlywarning/database`; legacy `data1.zip` / `data2.zip` remains supported) for information the flat cache cannot represent faithfully:

- `DDTBHK` → E1 semester sequence;
- `KDMMH`, `MMONTQ`, `MMHTQ`, `MMHTQCT`, chronology-safe `DDTBHP` population statistics → E2;
- chronology-safe `DDTBHP` student-course history → E3;
- chronology-safe `DDiemTPTG` component events → E4.

Every dynamic event satisfies `event_NHHK < target_NHHK`. Curriculum edges with creation timestamps are also unavailable until a strictly earlier semester.

The first run builds `structured_cache_dir/raw_index` and fold caches. Later runs reuse them automatically.

### Expanding-fold provenance and alignment

The files under `data/splits/expanding` are **already feature-engineered modeling tables**. They contain historical GPA/course/component aggregates, warning features, workload features, course clusters, one-hot course-status features, and the target registration identifiers/grade. Suite12 does **not** rebuild these rows from the raw database.

The existing cross-faculty canonical cache was originally produced by calling `load_fold()` directly on those expanding CSVs; it stores the resulting `train_frame` and `test_frame` and therefore remains Suite12's authoritative row universe and target definition. The raw database is used only to attach richer structured evidence that the flat folds cannot preserve.

On the first raw-index build, Suite12 performs a strict alignment audit before training:

- `IDKQDK -> MKQDK`: registration student, class and target semester must agree exactly;
- `IDToHoc -> KToHoc`: target course and semester must agree exactly;
- `target_IDCongDiem -> DDTBHP`: student/course/semester and `target_grade10` must agree exactly;
- previous-semester `DTBHK` is checked against the engineered `prev_semester_gpa10`. `DDTBHK` duplicates are resolved by the latest `NgayThem` record, matching the expanding-fold preprocessing semantics.

Any identity/target disagreement aborts the raw-index build. The audit is written to `structured_cache_dir/raw_index/alignment_audit.json`. This guarantees that E1-E4 add only chronology-safe historical structure to the same registrations used by V2/Council/Suites7-11.

## Training

Four stages are used:

1. E0 distillation warm-up.
2. Independent E1–E4 private pretraining.
3. Collaboration/fusion training while private encoders are frozen.
4. Joint end-to-end fine-tuning of every neural evidence path.

Expert dropout includes explicit E0 dropout to prevent the distilled shared expert from becoming another mandatory anchor.

## Reporting

The run writes/prints:

- AP, AUC;
- P/R/F1/F2 at 10/15/20/25% warning budgets;
- fixed-development-threshold metrics;
- drift-aware warning metrics;
- TP/FN/FP/TN confusion matrices;
- comparison against available Committee, V2, Council, Suite7–11 score files through the same evaluator;
- cross-faculty win rates;
- E0 and E1–E4 private AP;
- Committee-teacher fidelity per RF/ET/HGB head;
- expert evidence availability;
- gate entropy and gate utilization on failures vs normals;
- expert ablation ΔAP / ΔF2@20;
- top-20% rescued/lost failures and FP transitions;
- private and collaborative representation cosine diagnostics;
- private→collaborative same-expert cosine shift;
- all/failure/normal expert-attention matrices.

## Outputs

Per fold:

- `suite12_model.pt`
- `suite12_standardizers.joblib`
- `training_history.csv`
- `historical_selection.csv`
- `<faculty>_scores.csv`
- `suite12_diagnostics.csv`
- `representation_cosine.csv`
- `mean_expert_attention.csv`
- `mean_expert_attention_failures.csv`
- `mean_expert_attention_normals.csv`
- `suite12_fold_summary.json`

Global summaries include `suite12_fold_metrics.csv`, `suite12_warning_metrics.csv`, `suite12_holdout_mean_fold.csv`, `suite12_macro_model_comparison.csv`, and `suite12_run_config.json`.

## Run

On the server, the preferred raw source is the extracted database directory:

```bash
cd /root/disk_3tb/earlywarning/30072026/suite12
bash run_suite12.sh
```

`run_suite12.sh` defaults to `DATABASE_DIR=/root/disk_3tb/earlywarning/database`. If needed, override it with `DATABASE_DIR=/another/path bash run_suite12.sh`. Legacy ZIP input is used only when the database directory is absent and both `DATA1_ZIP` and `DATA2_ZIP` exist.
