# Module interfaces

SSL data tensors are dictionaries of numpy arrays; downstream histories use IndexedHistory with unique prefix tensors and an enrollment-to-prefix map. Explicit column access remains compatible with aligned arrays, while production training indexes unique tensors only within each minibatch. Frozen/evaluation encoders process unique prefixes once, then expand only the compact embedding vectors. Array shapes when materialized are:
course int64 [N,S,C] (PAD 0, UNK 1, MASK 2; vocabulary real courses >=3), grade_band int64 [N,S,C] (PAD 0, UNK 1, MASK 2, bands 3..7), numeric float32 [N,S,C,3] (grade/10, credits/10, attempt/5), event_mask bool [N,S,C], semester_mask bool [N,S], gaps float32 [N,S] (elapsed calendar ranks since first retained semester). Left aligned, padding at end. No history all masks false. Prefix data are already leakage-audited. Masking a grade must set numeric[...,0]=0 and grade_band=2; masking course must zero numeric[...,1:3] and course=2. SSL uses local event + causal semester context; no batch cross-row coupling.

`pace.models.HistoryEncoder(vocab_size, arch, dim=128, layers=2, heads=4, dropout=.1)` arch in mlp,gru,transformer. `.forward(batch: dict[str,torch.Tensor]) -> [N,dim]`. `.dim` and `.arch` available.

`pace.training.train_ssl(train_batch, val_batch, vocab_size, arch, task, cfg, seed, device, log, fixed_epochs=None)` returns object with `.encoder`, `.epochs`, `.history` (list dict), `.diagnostics` dict, `.model` full SSL module. task grade/course/joint. cfg fields dim,layers,heads,dropout,ssl_epochs,ssl_patience,ssl_lr,weight_decay,batch_size,mask_rate,grade_weight,course_weight. fixed_epochs skips validation and fresh full-corpus refit. val_batch None allowed only when fixed_epochs supplied. `log(str)` emits one line.

`pace.training.fit_neural(xtr,ytr,btr,xval,yval,bval,encoder,mode,cfg,seed,device,log,fixed_epochs=None)` returns `.model`, `.epochs`, `.history`. mode none,scratch,frozen,finetune; encoder None when mode none. x are preprocessed float32 numeric arrays. cfg fields neural_epochs,neural_patience,neural_lr,batch_size,weight_decay,dropout,hidden_dim. fixed_epochs full refit, no val. `predict_neural(model,x,batch,device,batch_size=256)` returns numpy [N] probabilities. `.model` can torch.save/load with weights_only=False for trusted checkpoints. Training never fits preprocessing.

`pace.metrics.evaluate(y,p,thresholds=None,row_ids=None)` flat metrics dict; `tune_thresholds(y,p)` returns {f1:threshold,f2:threshold}; `report_results(results_df,predictions_df,outdir,log,bootstrap=200)` writes/prints complete tables and paired contrasts, returns decision dict. results rows have faculty,fold,seed,arm,arch,task,ap,...; pred rows row_id,student_id,faculty,fold,seed,arm,arch,task,y,p,n_history,n_semesters,oov_rate. All target labels used only after model fit. Reporting must separate development folds <=5 from retrospective >5. Primary aggregation averages seeds within faculty-fold then equal-weights cells. Bootstrap is descriptive faculty-fold cluster resampling after seed average.

## Native AQ sources

`pace.aq_native.load_native_inputs(cfg,base)` returns `(events,calendar,entries,fingerprints,audit)`. `entries` is a re-iterable Sequence of fresh LazyCohort dict handles; metadata access never loads raw matrices, while train/test access loads one cohort. `course_target` is17 numeric features. Canonical data use feature_names/Xtr/Xte/ytr/yte/train_frame/test_frame; sidecar train_row_index equals the set of finite CF-covered rows, in any validated permutation. Target order is canonical or explicitly indexed.

`pace.aq_history.extend_history(root,canonical_events,database_dir=None,history_index=None)` reconciles numeric transcript events and returns `(events,audit,fingerprints)`. Optional grade_record_id comes from target_IDCongDiem. Native identity-only target student/faculty memberships travel temporarily in DataFrame attrs to support earlier-history joins, then are discarded before prefix grouping.

`python -m pace aq-run` (and the default shell command) builds the native configuration automatically. Semester-order mode is the inherited availability assumption, with internal comparison carriers rather than real timestamps. `EventCorpus.describe_origin` formats native cutoffs as semester codes. `pace.archival.compare` matches metric-only historical faculty/fold cells and reports population counts without claiming row-paired support.
