# Suite23 — Chronology-Safe Heterogeneous Academic Graph Transformer (CS-HAGT)

Suite23 is the graph-first successor to Suite22. It is intentionally **not** another TabM, temporal-sequence, MoE, or contrastive experiment.

The experiment tests whether the large relational signal exposed by Suite22 can be modeled more faithfully through a typed academic graph, while preserving the strong Committee through a chronology-selected safety fusion.

## Frozen scientific questions

1. **A — Bipartite Graph:** Does explicit Student↔Course graph propagation add value over a flat/local representation?
2. **B — Heterogeneous Academic Graph:** Do prerequisite/course-structure, structural-group and faculty relations improve A?
3. **C — Full CS-HAGT:** Do relative-time edge features and target-conditioned two-sided relational readouts improve B?
4. **Primary deployment system:** Can C complement Committee through a faculty-safe, development-selected fusion without materially regressing any faculty?

F6/F7 never select architecture, epochs, calibration, or fusion authority.

## What is actually represented

For each `(student, target course, target semester)` query, Suite23 samples a fixed-size chronology-safe neighborhood from the global historical interaction index:

- root student;
- root target course;
- up to 8 historical courses taken by the student;
- up to 12 historical students who previously took the target course;
- up to 6 prerequisite/related courses;
- up to 2 database-native structural course-group nodes, each initialized from aggregate member-course statistics;
- the current faculty context.

Historical Student↔Course edges carry grade, pass/fail, credits and relative recency. Structural course relations come from the same `MMONTQ/MMHTQ` evidence used by the Suite12 structured cache. Relation direction is retained explicitly (forward/reverse typed codes), and repeated attempts of the exact target course receive a dedicated same-course relation code.

### Curriculum/group node note

The available raw schema does not expose a universally guaranteed program-curriculum identifier in the canonical cache contract. Therefore Suite23 does **not invent latent curriculum clusters**. It uses database-native `MMHTQ` relation groups as structural curriculum/group nodes. If those raw tables are unavailable, it falls back to deterministic connected components of family-2 structural course edges and prints that mode explicitly.

## Architecture

```text
Historical graph strictly before query semester

   student ──grade/time──> historical courses
      │                         │
      │                         └── prerequisite/related ──> target course
      │
      └── faculty

   target course ──grade/time──> historical cohort students
       │
       ├── prerequisite/related courses
       ├── structural course-group nodes
       └── faculty

                     ↓
        Edge-aware heterogeneous attention × 2
                     ↓
            h_student      h_course
                  \         /
        target-course-conditioned history readout
        target-student-conditioned cohort readout
                     ↓
              graph risk probability
```

The GNN is implemented in **pure PyTorch**; PyTorch-Geometric is not required. Attention is relation-specific and edge attributes participate in both attention keys and messages.

There are no student-ID embeddings and no course-ID embeddings in the prediction model. IDs are only used to retrieve chronology-safe graph neighborhoods.

## Three trained variants

| Variant | Student-course edges | Structural/prerequisite/group/faculty edges | Relative time | Dual target-conditioned readouts |
|---|---:|---:|---:|---:|
| `suite23_bipartite_graph` | ✓ | – | – | – |
| `suite23_heterogeneous_graph` | ✓ | ✓ | – | – |
| `suite23_cs_hagt` | ✓ | ✓ | ✓ | ✓ |

`B-A` measures heterogeneous academic-structure gain. `C-B` measures the extra contribution of recency-aware edges plus target-conditioned relational retrieval.

## Primary result: faculty-safe Committee fusion

The standalone `suite23_cs_hagt` remains an explicit scientific result. The **predeclared primary deployable result** is:

` suite23_faculty_safe_fusion `

For graph probability `p_G` and Committee probability `p_C`, logits are blended. The candidate alpha grid is:

`0, 0.10, 0.25, 0.50, 0.75`

`alpha=0` is exact Committee fallback.

Authority is selected from the latest chronology-safe historical policy block(s), never F6/F7. Each faculty receives a raw authority, shrunk toward a global authority according to its historical failure count (`kappa=50`). A faculty authority is rejected back to zero if validation AP falls more than `.002` below Committee or F2@20 falls more than `.005` below Committee.

Before fusion, graph logits receive positive-slope Platt calibration fitted only on earlier validation blocks.

## Training

- one model shared across all 14 faculties;
- faculty-balanced sampling only;
- natural within-faculty class prevalence retained;
- `BCE + 0.15 × within-faculty pairwise ranking loss`;
- AdamW, `lr=1e-3`, weight decay `1e-4`;
- hidden dimension 64;
- 4 attention heads;
- 2 graph layers;
- dropout `.10`;
- maximum 12 epochs, minimum 3, patience 3;
- default 240,000 sampled training queries per epoch;
- latest three historical blocks per faculty are validation;
- selected epoch count is refit once on all permitted history.

There is **no neural OOF retraining loop**.

## Chronology contract

For every query, all grade-bearing graph edges satisfy:

`edge_semester < query_semester`

The graph materializer records the maximum historical interaction semester for every row and aborts the run if any violation exists.

Structural edges with a known creation semester are also filtered by availability. Structural relations with no source timestamp are treated as static curriculum metadata, matching the prior structured-cache assumption.

## Diagnostics generated automatically

Suite23 writes and prints:

- per-fold/per-faculty AP, AUC, Brier, ECE and 10/15/20/25% budget metrics;
- F1–F7 macro summary and F6/F7 holdout summary;
- aligned comparisons with Committee, Suites14/16/17/18/20/21/22, Council and V2 when their score files are available;
- 13-faculty Council overlap automatically, with missing English kept explicit;
- frozen F1–F5 threshold and drift/rate operational policies;
- TP/FP/FN/TN confusion matrices, including IT pooled F6/F7;
- `B-A` and `C-B` component uplift;
- graph support strata by historical-course/cohort/structural support and support-vs-gain correlations;
- graph-coldness regimes (`returning/new student × seen/new course`);
- chronology audit for every target row;
- post-hoc graph ablations: no structural edges, no group edges, no faculty edges, no time, no history readout, no cohort readout;
- relational perturbations: zero/shuffled student history and zero/shuffled target-course cohort;
- Committee false-negative rescue / false-alarm correction analysis;
- top target-conditioned history/cohort inspection paths;
- faculty-safe fusion authorities per fold;
- paired bootstrap AP confidence intervals against Committee, Suite18, Suite21, Suite22 and Council where aligned scores exist;
- an automatic predeclared premise/success audit, including the Council-overlap breakthrough criterion;
- direct comparison against Suite22's local relational model when its aligned score file is available.

Post-hoc ablations measure **dependency of the trained model**. The trained A→B→C comparisons are the stronger evidence for component value.

## Run

Extract this directory directly under:

`/root/disk_3tb/earlywarning/30072026/`

Then:

```bash
cd /root/disk_3tb/earlywarning/30072026/suite23_cs_hagt
chmod +x run_suite23.sh
./run_suite23.sh
```

Log:

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

Results:

`/root/disk_3tb/earlywarning/30072026/results/suite23_cs_hagt`

## Resource note

Graph neighborhoods are materialized once per fold in RAM and reused by all three variants. At the largest fold this can require roughly 1.5–2.5 GB of additional host RAM depending on NumPy/Pandas overhead. Only one fold is retained at a time.

## Interpretation bar

Suite23 is not considered a project-wide breakthrough merely for beating Committee on average. The intended bar is:

- Council-overlap macro AP improvement around `+0.010` or better;
- no meaningful faculty regression (`ΔAP < -0.003`);
- IT non-negative versus Council;
- F6 and F7 macro improvements both positive;
- no material F2 degradation.

If the full graph and safe fusion fail to improve over Suite22 safe blend, the larger graph is not justified and this graph line should be reconsidered rather than enlarged automatically.
