# Suite16 — Sequential Conditional Gradient-Tree Boosting

Suite16 is the first post-MoE redesign of the academic early-warning project. Its immutable Stage 0 is the existing RF/ET/HGB Committee. There is no neural E0, router, gating network, expert authority, responsibility label, or mixture-of-experts fusion.

## Research hypothesis

A specialist should not independently re-learn failure risk. It should only explain prediction error that remains after the current shared model. Suite16 therefore applies optional conditional boosting stages:

1. **S1 Student–Curriculum Compatibility** — prior student-course relation events, prerequisite readiness/coverage, course-relative ability gaps, and chronology-safe latent student×course factors learned only from grades before the row semester.
2. **S2 Student Dynamics** — deltas, slopes, acceleration, volatility, drawdown and recent-vs-long-run changes. Absolute GPA/state levels are deliberately excluded.
3. **S3 Relative Mastery Phenotype** — component performance normalized against prior-only course×component peer distributions, then summarized by component type, recency and target-course relevance.

Every stage has an exact identity/no-op candidate. A stage is admitted only when multi-window temporal meta-validation shows broad positive AP and no material F1/F2 or recent-window deterioration.

## Two tree families

- `suite16_hgb_final`: reference Newton/logistic conditional booster using `HistGradientBoostingRegressor` on the stage pseudo-residual.
- `suite16_grande_final`: primary self-contained **GRANDE-style** hard axis-aligned differentiable tree ensemble. It uses straight-through hard feature/split decisions and leaf-specific instance-wise estimator weighting. It is inspired by GRANDE/GradTree but is not a vendored or exact reproduction of the official package.

Official GRANDE reference: https://github.com/s-marton/GRANDE
ICLR 2024 paper: https://proceedings.iclr.cc/paper_files/paper/2024/hash/109cf25cbc36037deecdbeabfa199956-Abstract-Conference.html

## Default run

```bash
cd /root/disk_3tb/earlywarning/30072026/suite16
bash run_suite16.sh
```

Results:
`/root/disk_3tb/earlywarning/30072026/results/suite16_conditional_tree_boosting`

Log:
`/root/disk_3tb/earlywarning/30072026/log/suite16.log`

The existing Suite12 schema-v4 structured cache is reused. Suite16 additionally needs its `raw_index` for latent-factor and peer-normalized mastery features; if absent, the launcher supplies the raw database path so it can be rebuilt chronology-safely.

## Key diagnostics

Per fold the log prints redesigned-view coverage, single-stage HGB audits versus Committee and Suite15 old-view tree gains, multi-window selection statistics, stage acceptance/skip reason, cross-fit coverage, cumulative AP gain, top tree features, per-faculty target AP, and correction behavior.

Final CSVs include:
- `primary_holdout_comparison.csv`
- `mean_fold_holdout.csv`
- `operational_metrics.csv`
- `redesigned_view_audit.csv`
- `redesigned_view_audit_faculty.csv`
- `stage_decisions.csv`
- `correction_diagnostics.csv`
- `feature_usage.csv`
- `suite16_hgb_final_faculty_comparison.csv`
- `suite16_grande_final_faculty_comparison.csv`

Each `fold_N/` directory also contains aligned `{faculty}_scores.csv` files for future suites.
