# Suite26 rewrite: Memory-Interacting Neural Trees (MINT)

This is a new experiment, separate from `suite26_tree_native_student_memory`. The user explicitly requested a complete implementation of a unified model in which memory changes tree learning internally, before prediction. Primary score: `suite26_mint`. Performance superiority is a hypothesis, not a guarantee.

## Architecture contract

A full binary differentiable forest supplies the final prediction. Each internal node selects a current-state feature, queries the student's available history, and uses the retrieved evidence to set its conditional split threshold. Path probabilities lead to trainable leaf probabilities. The forest averages its tree probabilities. There is no external teacher probability, tree-logit offset, residual risk head, calibrator, or Committee input in the primary forward path.

For node j in tree t:

1. A straight-through categorical feature selector chooses one standardized input feature for the forward pass. Its softmax surrogate supplies gradients to feature-choice logits.
2. The node's feature identity, selected value minus base threshold, target-course context, current-state context, and incoming path reach determine a memory query.
3. Attention reads only available earlier-semester events for the same student. Keys describe historical state/course and recency; values include observed outcome, grade, and missingness.
4. The effective threshold is base_threshold + static_context_shift + memory_shift + readiness_gap_shift. These are threshold adjustments in standardized feature units, not corrections to a risk score. The two history terms vanish for empty history.
5. A sigmoid split, with a positive bounded learnable temperature, produces left/right routing. Reach probabilities propagate top-down. The next level's query includes its actual incoming reach.
6. At the leaves, p_tree = sum(path_mass * sigmoid(leaf_logit)); p = mean(p_tree). All selector logits, thresholds, temperatures, leaf logits, embeddings, memory projections and readiness parameters are optimized by the same final-label loss.

A conventional ExtraTrees fit is initialization only. Balanced class weights guide split discovery for this rare-failure task; leaf probabilities are then re-estimated from unweighted training counts with Jeffreys smoothing (0.5 positive and 0.5 negative pseudocount). Weighted tree probabilities never enter the model. Depth-limited splits are copied into the differentiable forest. Float64 seed thresholds are rounded downward to preserve sklearn branches for every float32 input, including adjacent-value boundaries. The initialization never uses validation or target labels. No OOB or leaf-coordinate alignment is required because the tree is now part of one jointly optimized estimator. Refitting constructs a fresh seed forest and a fresh neural model; complete preprocessing and forest state are saved together.

Default tree geometry: 64 trees, maximum depth 6 (63 internal nodes / 64 leaves per tree). Compact CPU smoke uses 2 trees and depth 2. Feature choice remains hard in the forward pass; routing is soft during both normal training and normal inference. Hard routing is a diagnostic, not silently substituted at deployment. Hard-converted trees with context disabled must reproduce the seed leaf probabilities.

## Memory and readiness

Use course ID embeddings plus 17 course metadata/statistics and their missingness indicators. Fit the ID vocabulary on selection-training rows only; new courses map to 0. Faculty is explicit one-hot input to every forest variant. A small shared projection encodes historical current-state features and course metadata.

Primary candidate selection is outcome independent: retain the most recent 32 strictly earlier-semester events. Preserve full eligible count separately from retained count. Never prioritize failures in the primary bank. Course and student identity must use consistent canonical strings; course IDs are treated as globally unique unless data metadata explicitly establishes otherwise.

Readiness is target independent. Learned positive course-to-dimension weights pool observed historical performance per dimension; performance is grade/10 when present, otherwise 1-failure. A small prior prevents undefined empty dimensions. Target course produces requirements r in (0,1) and nonnegative normalized importance a. The vector a*(r-theta) describes a capability deficit. It enters internal split conditioning only; there is no independent ability classifier or regression head. Conditional on association weights, better historical performance increases readiness. Latent dimensions are not claimed to be identified academic skills.

Variants share feature access, seed forest, initialization seed, and training budget:
- `suite26_seed_forest`: seed forest with its natural-prevalence leaf probabilities, before joint optimization.
- `suite26_tree_only`: jointly optimized forest with static/current course context and no history.
- `suite26_memory`: forest with node-conditioned episodic memory, without readiness conditioning.
- `suite26_mint`: PRIMARY, node-conditioned memory plus readiness–requirement conditioning.

All predictions come from forest leaves; there is no auxiliary unrestricted neural head or prediction blending. The conventional seed baseline is a capacity-matched baseline, not an assertion that this shallow forest is as strong as every previous Committee member.

## Data and time contract

Load canonical caches and existing Suite12 course-target cache. Use the raw feature intersection across all requested faculties and folds, plus 17 course features. Preserve canonical features for covered rows and targets. Include all earlier labeled canonical training rows in the historical event bank. For uncovered historical rows, reconstruct prior course statistics using strictly earlier semesters; take static metadata only from that row when available, otherwise mark missing. Do not borrow future metadata. Report reconstruction/missingness counts.

Training queries may use all valid historical rows; this differs transparently from the original CF-covered-only Suite26. Course field presence is encoded explicitly. Require binary labels, valid student/course/semester IDs, finite labels, grade range 0..10, and grade/failure consistency wherever a grade is known.

Shared models use global semester cutoffs across faculties. Assert max(training semester) < min(validation semester) and max(all history semester) < min(target semester). Fail with actionable offending ranges when caches violate the contract. Do not substitute random row splitting or numeric local CF block IDs.

Selection: seed/scalers/vocabulary and model training use older semesters. The last **one** historical semester selects epoch count by macro faculty AP. Its memory bank is restricted to the training partition. One-semester validation avoids using earlier validation outcomes to reconstruct later validation course features. An explicit `--val-semesters > 1` retains a fixed training-origin memory bank but preserves row-time current features; it is a different mixed-origin protocol and prints/saves that caveat. Arbitrary canonical raw or covered course features cannot be retroactively origin-frozen by this package. Their as-of-query provenance remains an input-cache assumption. Refit rebuilds everything on all permissible history and trains the selected epoch count with the **same sampled examples per epoch as selection**, even below the sampling cap. Target memory uses all permissible history and never target-fold outcomes.

Observed previous-semester grades are assumed available by the next semester because the supplied cache contract lacks grade-release timestamps. Print this assumption; no claim of timestamp-level verification. Earlier target-fold labels never enter another query's episodic history within that fold. Canonical target features are presumed to obey the original forecasting protocol, which cannot be verified from their numeric arrays alone. Target labels are used only for reporting after inference.

## Training and output

Unweighted BCE on the natural within-faculty prevalence, faculty-balanced query sampling; optional within-faculty pair ranking weight 0.05. No class-weighted neural BCE. AdamW, lr 0.001, weight decay 0.0001, gradient clip 5; up to 15 selection epochs with patience 4 and minimum 3 epochs before stopping; the best epoch can be earlier. Samples per epoch cap 180000; batch 128, evaluation batch 128. Refit preserves selection's sampled-example budget and uses a fresh model. A reach-weighted squared penalty on memory and readiness threshold shifts (0.0001) limits instability without fixing tree predictions. Log sampling counts and ranking pair participation. BCE defines the principal proper probability objective; the optional pair loss trades calibration for ranking and can be disabled with `--rank-weight 0`.

Save all model bundles by default. Save atomic checkpoints and completed fold outputs; `--resume` validates configuration/input fingerprints before reusing completed folds. Refuse an existing nonempty result directory without `--resume`; never overwrite the original Suite26 directory. CLI must support root/cache/structured/out/device/folds/faculties overrides. Main shell script uses `PYTHON` if set, otherwise the existing Huy environment if present, otherwise python3. Preflight honors the same arguments as training. No dependency installation by the run script.

Diagnostics: per-faculty/fold and matched macro AP/AUC; calibration metrics and fixed warning budgets; dev-selected F2 thresholds; IT confusion matrices; component uplifts; bootstrap of paired macro faculty-fold AP clustered by student; same-student history shuffle; no-memory, direct-outcome masking, no-readiness, uniform attention, and hard-routing interventions; history strata; attention outcomes/grades/recency; readiness gap distributions; static/memory/gap threshold shifts; route entropy; node feature changes and threshold changes; gradient norms from main loss to tree and memory parameters; model size/time; cold/unknown course regimes; reference alignment audit. Label interventions are sensitivity analyses; they do not prove causal importance.

Load previous scores only after keyed one-to-one alignment. If legacy files lack enough keys, skip with an explicit reason rather than equating label arrays. Committee from canonical cache is already aligned. Never select architecture, epoch, threshold or calibration from target-fold scores. Historical F6/F7 remain comparative benchmarks with acknowledged prior project-level reuse.

## Public module interfaces

`mint_data.Table`: dataclass fields x[N,D], course_meta[N,17], y[N], grade[N] (0..10 or NaN), semester[N] (ordered integer), student[N], course[N], faculty[N] (integer), sample_id[N], committee[N] (NaN allowed), faculty_names tuple[str], feature_names tuple[str]. `len(table)` and `subset(indices)` accept integer indices or boolean mask.

`load_fold(cache_dir, structured_dir, faculties, fold, common_features=None) -> (history Table, target Table, audit dict)`; `discover_faculties(cache_dir, fold=1)`; `common_feature_names(cache_dir, faculties, fold=1)`.

`chronological_split(table, val_semesters=3) -> (train_indices, val_indices, audit)`; `assert_future(history, target)`.

`Preprocessor.fit(table, indices) -> Preprocessor`; `.transform(table) -> Prepared` where Prepared has `.x` standardized numeric plus faculty one-hot, `.course_meta` standardized 17 metadata plus 17 presence flags, `.course_id` train-vocabulary codes (unknown 0), and `.table`. `.n_courses` and `.to_dict()` / `.from_dict(state)` are public. Fit statistics use selected training rows only. `Prepared` supports len.

`build_history(bank: Table, query: Table, max_history=32, allowed=None) -> HistoryIndex` with `.indices[N,H]` (-1 padding), `.recency[N,H]`, `.same_course[N,H]`, `.full_count[N]`, `.retained_count[N]`. `shuffle_history(bank, query, history, seed) -> (HistoryIndex, audit)` must avoid same-student donors where possible and preserve time.

`MemoryDataset(query: Prepared, bank: Prepared, history: HistoryIndex, indices=None)` returns tensors: x, course_meta, course_id, faculty, y, sample_index; h_x, h_meta, h_course_id, h_y, h_grade (0..1), h_grade_present, h_mask, h_recency, h_same. Padded values must be finite and ignored.

`mint_seed.fit_seed_forest(x, y, n_trees=64, depth=6, min_leaf=8, seed=42, n_jobs=-1) -> blueprint dict`. Contains feature_index[T,N], thresholds[T,N], leaf_prob[T,L], active_nodes[T,N], n_features, n_trees, depth. `seed_predict(blueprint,x)` returns natural leaf-mixture probabilities under hard routing.

`mint_model.MemoryIntegratedForest(blueprint, n_course_meta, n_courses, variant='mint', hidden=32, ability_dim=16, dropout=0.1)`; `.forward(batch, intervention=None, return_details=False) -> dict`. Required keys: prob[B], tree_prob[B,T], attention[B,H], route_entropy[B], memory_shift_abs[B], static_shift_abs[B], gap_shift_abs[B], readiness[B,K], requirement[B,K], gap_score[B]. With return_details add routes[B,T,N], leaf_mass[B,T,L], effective_thresholds[B,T,N]. Interventions are strings `no_memory`, `no_outcomes`, `no_ability`, `uniform_attention`, `hard_routing`, `no_context`; a set/list may combine them. `config()` serializes constructor dimensions/variant.

`mint_metrics.metrics(y,score)`; `macro_ap(frame, score_column)`; `add_references(frame, reference_dirs) -> (wide_frame, audit_frame)`; `write_report(frame, out_dir, dev_folds=(1,2,3,4,5), holdout_folds=(6,7), bootstrap=200, seed=42) -> dict`. Score frame columns: fold,faculty,sample_id,student_id,course_id,semester,actual,committee, suite26_seed_forest, suite26_tree_only,suite26_memory,suite26_mint (subset permitted). Per-row score NaNs imply missing reference coverage; never fill them silently.

## Verification gates

Test chronology with uneven faculty windows, full-bank coverage, unknown courses, missing grades and inconsistent grades, future-label independence, same-semester exclusion, and meaningful keyed alignment. Test path mass normalization, hard seed equivalence, empty-history finiteness/invariance, real gradient flow into split selectors/thresholds/leaf logits and memory parameters, changed historical outcomes changing routes, and state serialization parity. Run a small synthetic canonical-cache experiment through selection/refit/reporting/checkpoint reload and resume; a run command that only imports is insufficient.

The package will include design, implementation plan, source, tests, synthetic-cache generator, requirements, run script, prediction/reload utility, and a validation report distinguishing CPU synthetic verification from unexecuted real AQ/V100 performance.

## Research precedents

Differentiable forest learning is established in Deep Neural Decision Forests (ICCV 2015): https://openaccess.thecvf.com/content_iccv_2015/html/Kontschieder_Deep_Neural_Decision_ICCV_2015_paper.html . Hard axis-aligned feature selection with surrogate gradients has precedent in GRANDE (ICLR 2024): https://arxiv.org/abs/2309.17130 . This implementation is custom, not an official reproduction. Its proposed research contribution is student-memory-conditioned internal routing under the AQ temporal protocol, which requires empirical validation.
