# Suite20 design specification

## Frozen hypothesis

The previous AQ suites model temporal drift well, but most prediction functions still consume one flattened target row. Suite20 tests a separate hypothesis: **individual academic state is sequential across semesters, and target-course risk depends on which parts of that history are relevant to the current course.**

## Why this experiment comes next

It attacks a data property that has not been isolated cleanly by Suites 13–18 while preserving their efficient shared-faculty training recipe. It also avoids conflating temporal benefit with generic neural modernization because the run contains a flat shared control and a GRU control.

## Primary model components

### Shared flat state branch

Consumes the common 136-ish aligned engineered features, target-course vector, faculty embedding and target-semester scalar. It captures the information already available to previous flat approaches.

### Semester Transformer

Consumes the chronology-safe `student_seq` tensor from the structured cache. The cache is ordered by semester and only includes semesters strictly before the target. Learned positional embeddings represent order among the retained prior semesters.

### Target-course query

The structured `course_target` vector and faculty embedding produce a query. Multi-head cross-attention uses this query to select the relevant portions of the student's prior semester trajectory.

### Faculty conditioning

One shared model is trained across all faculties. A small learned faculty embedding conditions both the flat branch and the temporal query rather than creating 14 separate models.

### Gated fusion

A learned gate decides how much temporal evidence to admit for each row, using history availability/length, target-course state and faculty context. Rows with no prior semester history force the temporal gate to zero.

### Efficient ensemble head

Eight cheap affine-modulated prediction members share the same representation. Their mean is the prediction and their standard deviation is an uncertainty diagnostic.

## Ablation hierarchy

- `flat`: no explicit semester sequence.
- `gru`: recurrence over the same semester sequence plus target-conditioned attention.
- `transformer`: self-attention over semester history plus target-course cross-attention.

This makes the temporal claim falsifiable.

## Acceptance criteria

Primary evidence is F6/F7 mean-fold macro AP across all available faculties. We also track F2@20 and per-faculty regressions.

Suggested interpretation thresholds (not hard statistical significance claims):

- Transformer vs flat < +0.003 macro AP: negligible/incremental.
- +0.003 to +0.010: useful temporal signal, but not a breakthrough.
- >= +0.010 with broad faculty support and both holdout folds: strong evidence.
- >= +0.020 with no widespread regressions: major result worthy of deeper architecture work.

## Leakage rules

- Structured semester history must be strictly earlier than the target semester.
- Latest historical blocks, not target folds, select training duration.
- F6/F7 never choose architecture or hyperparameters.
- Committee/Council/older-suite predictions are comparison-only and are never model inputs.
- Reverse/zero-history perturbations are post-hoc only.
