# Suite25 — Structure-Aware Chronological Retrieval (SACR)

This package implements the complete Suite25 AQ early-warning experiment.

## What changed after Suites22–24

The previous experiments established that student-course relational identity is useful, while global GNN propagation, explicit time modules, faculty graph nodes, and Committee-anchored residual corrections did not provide a reliable project-level improvement. Suite25 converts the useful relational information into a **retrieval prior**.

The primary `suite25_sacr` model is fully standalone. It does **not** receive Committee predictions. Committee is loaded only as a reference and for the optional `suite25_committee_blend` ablation.

## Three trained models

| Output | Purpose |
|---|---|
| `suite25_mlp` | Shared current-state neural baseline, no retrieval |
| `suite25_tabr` | Direct chronology-safe TabR-like state retrieval |
| `suite25_sacr` | **PRIMARY**: same-student + same-course + structural + state retrieval |
| `suite25_committee_blend` | Secondary validation-selected blend, never primary |

## Retrieval safety

For every candidate used by every query:

```text
candidate semester < query semester
```

During epoch selection, the retrieval memory is the **selection-training partition only**. In particular, labels from the latest validation blocks are never available as candidate labels to another validation query. During production refit, all historical rows are allowed as memory for strictly later historical/target queries.

Any chronology violation aborts the run.

## Core TabR-style mechanism

The implementation follows the important retrieval design of TabR rather than importing its old environment:

```text
current row ─► shared encoder ─► query key
                                  │
chronological candidate rows ─► candidate keys
                                  │
                         learned squared-L2 retrieval
                                  │
                   historical labels + key differences
                                  │
                         weighted retrieval context
                                  │
                         current representation + context
                                  │
                              failure probability
```

Candidate preselection is implemented with SciPy `cKDTree` over a training-only PCA space. This avoids the old TabR repository's Faiss/Python/CUDA version constraints while retaining a learned neural re-ranking stage.

## Run

```bash
cd /root/disk_3tb/earlywarning/30072026
unzip suite25_structure_aware_chronological_retrieval.zip
cd suite25_structure_aware_chronological_retrieval
chmod +x run_suite25.sh
./run_suite25.sh
```

Default result directory:

```text
/root/disk_3tb/earlywarning/30072026/results/suite25_structure_aware_chronological_retrieval
```

Default log:

```text
/root/disk_3tb/earlywarning/30072026/log/suite25_structure_aware_chronological_retrieval.log
```

## Default frozen settings

- current-state dimensions: common raw intersection + 17 course-target features (expected 153)
- hidden width: 128
- key width: 64
- encoder blocks: 2
- predictor blocks: 2
- faculty embedding: 8
- state PCA dimensions: 24
- same-student pool: 16
- same-course pool: 24
- structural pool: 24
- state-neighbour pool: 32
- maximum union candidates: 96
- direct TabR context: 24
- SACR context per pool: 8
- AdamW: lr `1e-3`, weight decay `1e-4`
- BCE + `0.10` within-faculty pairwise ranking loss
- faculty-balanced sampling, natural class prevalence within each faculty
- batch size: 256
- max epochs: 10, patience: 3
- samples per epoch: 180,000

Do not tune these before the first complete F1–F7 run.

## Printed diagnostics

The final report contains:

- all-fold and F6/F7 macro summaries;
- direct comparisons with Committee, V2, Council, Suites14/16/17/18/20/21/22/23/24;
- per-faculty head-to-head AP;
- fixed and drift operational policies and IT confusion matrices;
- student-cluster bootstrap confidence intervals;
- A→B retrieval gain and B→C structure-aware retrieval gain;
- retrieval support/zero rates per pool and faculty;
- candidate failure-rate enrichment per pool;
- no-retrieval, no-label, no-student, no-course, no-structure, no-state, no-relation-metadata and fixed-pool-gate ablations;
- candidate-label shuffle intervention preserving faculty prevalence;
- pool gate authority per faculty;
- weighted retrieved failure rate for true failures vs normal rows;
- cross-faculty attention mass and retrieved-case recency;
- course-relation attention by relation code;
- context-size sensitivity (4/8/16 per pool);
- retrieval-support strata and new/seen student-course regimes;
- Committee false-negative rescue / false-alarm correction as a complementarity diagnostic;
- support-vs-gain correlations;
- frozen premise / Council success audit.

## Key methodological distinction

Suite25 does **not** assume that graph message passing is necessary to use graph knowledge. Academic relations determine *which historical rows should be available for retrieval* and provide metadata to the learned retriever. The prediction model remains a single standalone retrieval-augmented architecture.
