# Suite25 — Structure-Aware Chronological Retrieval (SACR)

## Frozen research question

Can a **standalone** retrieval-augmented model outperform the current AQ systems by using the right historical analogues instead of global graph message passing?

Suite25 is inspired by TabR's retrieval formulation, but it is **not a verbatim copy of the official TabR implementation**. The official TabR mechanism is preserved at the neural level: shared query/candidate encoder, learned squared-L2 key similarity, historical label embeddings, a learned `T(k_query-k_candidate)` value term, weighted retrieved context, and a feed-forward predictor. Suite25 changes candidate generation to make retrieval chronology-safe and academically structured.

## Scientific contract

- **A — `suite25_mlp`**: shared current-state MLP. No retrieval.
- **B — `suite25_tabr`**: direct TabR-like chronological retrieval from a current-state nearest-neighbour pool.
- **C — `suite25_sacr`**: **PRIMARY**, fully standalone. Multi-view retrieval from four chronology-safe pools:
  1. same-student history,
  2. same target course,
  3. prerequisite / structural neighbour courses,
  4. global current-state analogues.
- **`suite25_committee_blend`**: secondary ablation only. Committee is not used by A/B/C during training or inference.

F6/F7 never select architecture, epoch, calibration, candidate rules, context size, or blend coefficient.

## Input

`136 common current-state features + 17 target-course features = 153 variables` (the exact common-feature count is asserted at runtime).

Ordinary faculty identity and normalized semester are context inputs to the shared encoder. They are not feature-wise modulators and do not control routing.

## Candidate generation

All candidate labels come from the historical memory bank. For every query `q`:

`candidate_semester < query_semester`

is asserted. Selection validation memory contains **training rows only**; validation labels never become retrieval candidates during model selection.

### Pool 1: same student

Recent earlier rows for the same student, prioritizing:

1. previous attempt of the exact target course,
2. structurally related courses,
3. other recent courses.

### Pool 2: same target course

Recent historical student-course rows for the exact target course.

### Pool 3: structural courses

Historical rows for prerequisite / curriculum-relation neighbour courses available before the query semester.

### Pool 4: state analogues

Training-only standardization + training-only PCA creates a coarse retrieval coordinate frame. For each query semester a `scipy.cKDTree` is built only from earlier memory rows. The nearest state candidates are a **preselection** step; the neural model subsequently re-ranks them with learned TabR keys.

No Faiss dependency is required.

## Neural retrieval

For query `x` and candidate `x_i`:

- shared encoder: `h = E(x)`
- learned keys: `k = K(LN(h))`
- similarity: `s_i = -||k-k_i||²/sqrt(d_k)`
- historical label embedding: `L(y_i)`
- TabR-style difference transform: `T(k-k_i)`

Base TabR value:

`v_i = L(y_i) + T(k-k_i)`

SACR additionally injects **candidate metadata** (pool identity, same-faculty flag, recency, coarse distance, course-relation type) into both value and retrieval bias. These metadata heads are zero-initialized so the model begins from feature-similarity retrieval rather than a hand-coded preference.

Each academic pool is aggregated separately. A low-capacity query-conditioned gate combines the available pool contexts. The context is added to the current-state representation before the predictor head.

## Why this differs from Suites23–24

Suite23 showed that global graph propagation was not stronger than Suite22's local relational representation. Suite24 showed that forcing relation evidence to act as a Committee residual reduced diversity and that direct structural corrections were weak.

Suite25 therefore keeps **relations as candidate-selection and retrieval metadata**, but removes GNN message passing and makes Committee independent from the primary architecture.

## Frozen hypotheses

1. B > A: learned historical analogue retrieval adds signal beyond a shared MLP.
2. C > B: academic structure improves generic TabR retrieval.
3. Candidate labels matter: removing or shuffling historical outcomes should hurt.
4. Correct same-student / same-course / structural pools should contribute non-redundant signal.
5. C should be complementary with Committee, but C must be judged first as a standalone model.
6. The project breakthrough criterion remains Council-oriented: substantial macro improvement with no material faculty regressions, including IT.
