# Suite22 — Shared Faculty-Time Relational TabM (SFTR-TabM)

Suite22 is the post-Suite21 architecture reset for the AQ early-warning project. It trains one shared model over all faculties and treats time as **feature context / concept drift**, not as the main sequence backbone.

## Scientific questions

The run trains five controlled variants under the same chronological protocol:

1. `suite22_shared_tabm` — shared direct TabM control; faculty/time are ordinary context.
2. `suite22_faculty_mod_tabm` — adds feature-wise faculty modulation.
3. `suite22_faculty_time_tabm` — adds continuous time and faculty×time feature modulation.
4. `suite22_relational_ft_tabm` — adds target-conditioned student-course relational evidence from the existing Suite12 structured cache.
5. `suite22_sftr_tabm` — **primary** model; adds a sparse learned feature-relation graph.

A secondary `suite22_safe_blend` is selected only on chronological development validation from a logit blend of Committee and the primary model. It is a deployability diagnostic, not the primary scientific result.

## Key safeguards

- F1–F5 are development; F6–F7 remain untouched holdout.
- Latest 3 historical blocks are chronological validation for each target fold.
- One shared cross-faculty model; no per-faculty model training.
- Faculty-balanced sampling only; **no class-balanced sampler**.
- No Suite19-style neural OOF or contrastive representation reconstruction.
- No student-ID embedding and no learned semester-ID lookup.
- Time uses a trend plus Fourier periods 3/6/12 and therefore extrapolates to future folds.
- Feature modulation is low-rank and starts at exact identity.
- Sparse feature graph starts with low authority.
- Relational evidence is a target-conditioned set representation; there is no semester Transformer.
- Production backend fails loudly unless official `tabm==0.0.3` is available.

## Existing data reused

Canonical shared cache:

`/root/disk_3tb/earlywarning/30072026/results/cross_faculty_residual_moe/cache`

Structured relational cache:

`/root/disk_3tb/earlywarning/30072026/results/suite12_structured_cache`

The structured cache supplies previous-semester states, target-course statistics, course/prerequisite neighbors, relation events, and component/mastery events. Suite22 never rebuilds the raw database.

## Run

```bash
cd /root/disk_3tb/earlywarning/30072026/suite22_sftr_tabm
chmod +x run_suite22.sh
./run_suite22.sh
```

The launcher first runs the cache/environment checker, then streams the complete run to:

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

Results are written to:

`/root/disk_3tb/earlywarning/30072026/results/suite22_sftr_tabm`

Extra arguments are forwarded, e.g. a single-fold diagnostic run:

```bash
./run_suite22.sh --folds 1 --samples_per_epoch 50000
```

## Main outputs

- `all_metrics.csv`
- `fold_macro_summary.csv`
- `holdout_macro_summary.csv`
- `primary_holdout_head_to_head.csv`
- `all_component_uplift.csv`
- `all_relational_support_uplift.csv`
- `all_primary_ablation_diagnostics.csv`
- `all_time_counterfactual_diagnostics.csv`
- `all_modulation_vs_drift.csv`
- `all_feature_graph_edges.csv`
- `drift_modulation_correlations.csv`
- `holdout_paired_bootstrap_ap.csv`
- `operational_policies_from_dev_f1_f5.csv`
- `operational_holdout_metrics.csv`
- `operational_pooled_confusions_by_faculty.csv`
- `operational_overall_confusions.csv`
- per-fold score files for every faculty

The console prints fold/faculty AP/AUC/Brier/ECE/F2, the A→E component gains, full earlier-suite comparisons, frozen-threshold and drift operational results, IT and overall confusion matrices, temporal/faculty/relational/graph ablations, learned graph edges, drift↔modulation correlations, and paired bootstrap AP intervals.

## Dependency

The production implementation is pinned to `tabm==0.0.3`, matching the already-tested Suite19 environment. The `internal_smoke` backend exists only for unit/synthetic tests and is never a silent production fallback.
