refactor(PR3): split model/_model.py into scvi-style modules + explicit __all__

[nceglia]

Stacked on #31 (PR2). Base = refactor/pr2-safe-deletions — GitHub retargets as the stack merges.

Mechanical split — no behavior change. Breaks the 1074-line model/_model.py into scvi-tools-style sibling modules. import tcri green; full suite 36 passed / 1 skipped.

The split

file	holds	lines
_model.py	TCRIModel (BaseModelClass API: setup_anndata, init, train, get_latent_representation, get_cell_phenotype_probs, get_p_ct, …)	462
_module.py	TCRIModule — the Pyro model/guide	326
_priors.py	MixtureDirichlet, VampPrior	147
_classifier.py	PhenotypeClassifier	21
_training.py	UnifiedTrainingPlan, build_archetypes	154

Extraction used ast.get_source_segment (formatting-preserving), so each class body is byte-identical to the original modulo the one sanctioned rename. Clean dependency DAG: _classifier/_priors → _module → _training → _model. Every module declares an explicit __all__ (a Phase-3 deliverable): tcri.model.* is pinned to exactly {TCRIModel} — the public API the frozen contract promises. (The old import * incidentally leaked ~17 third-party names — pyro, dist, Encoder, KMeans, … — none tcri-defined and none referenced anywhere; those are no longer surfaced.)

Rename

c2p_mat → clone_phenotype_prior (plan-sanctioned, Phase 3) — 13 word-boundary sites; the unrelated local c2p_torch and the module register_buffer("clone_phen_prior") are untouched.

Incidental cleanup

Rebuilding per-file import headers surfaced 3 provably-dead top-level imports, now dropped: setup_anndata_dsp, cosine_similarity, and the torch.distributions Categorical/Dirichlet/MixtureSameFamily trio (every real use is dist.-prefixed pyro).

New coverage

The construct/train path was entirely uncovered (the trained_model fixture was defined but unused). Added tests/test_model_smoke.py: construct → train (2 epochs) → get_latent_representation / get_p_ct / get_cell_phenotype_probs (asserts shapes + probability normalization), and asserts the rename landed and build_archetypes returns centers and labels. ~1s in-suite.

Deferred (logged)

M5 — build_archetypes default K=4 vs TCRIModel K=10. Behavior-neutral (the model always passes K=10 explicitly); reconciled with persisted labels when diag.archetypes lands (Phase 8). Not touched here to keep the split purely mechanical.

Audit

A workflow audit ran on this branch — 3 lenses (doc↔code · behavior preservation · plan/contract), each finding adversarially verified (8 agents total). The behavior lens confirmed the split is a pure refactor: class bodies byte-identical to the pre-split monolith (AST diff, modulo the sanctioned rename), zero undefined-names (F821) across all 5 files — proving every per-file import header is complete — and the suite + smoke green.

Verdict: 2 lenses PASS, plan-contract FIX. 5 findings, all confirmed, all LOW/MED — no behavior or correctness defect. Fixed in this branch: the MED — explicit __all__ per module (plan §Phase 3) was omitted — now added to all 5 files, which also resolves the two LOW "surface not byte-for-byte" wording findings (surface pinned to {TCRIModel}).

One LOW item deferred (on the auditor's own recommendation): stale c2p_mat descriptors in the contract generator (build_tcri_contract.py) — bundled with the Phase-8 diag.archetypes/M5 reconciliation, since they describe that future function. Tracked in docs/contract/REFACTOR_NOTES.md.

Stacked so the diff shows only PR3's changes. Living agenda + audit log: docs/contract/REFACTOR_AGENDA.md.

🤖 Generated with Claude Code