| # Migration and model-family roadmap |
|
|
| ## Frozen ROOT-GNN baseline |
|
|
| The `root-gnn-parity-baseline` tag records the completed migration of the |
| active ROOT-GNN behavior into `src/gnn4colliders.models.root_gnn`. The |
| campaign covered full event preprocessing and graph parity, binary objectives |
| and metrics, deterministic fine-tuning, full-split training, checkpoint reload |
| and resume, reproducibility, and serialized graph-cache checks. |
|
|
| The historical implementation is no longer in the active source tree. Its |
| observable behavior is represented by committed fixtures, tests, and the |
| one-way checkpoint/metadata compatibility adapters. New work must not add |
| imports from historical implementation paths. |
|
|
| ## Shared contracts |
|
|
| New model families should consume these boundaries: |
|
|
| - `EventSample` and named `EventMetadata` from `data`; |
| - shared collider feature builders from `features`; |
| - a representation-specific sample/batch type from the relevant adapter; |
| - task-owned loss, score, prediction, and metric semantics; |
| - the shared `Trainer`, checkpoint, reproducibility, and inference APIs. |
|
|
| The graph path is the current ROOT-GNN representation. A sequence or token |
| model should add a separate representation boundary rather than placing |
| sequence behavior in graph modules or generic data code. |
|
|
| ## Transformer model-family milestone |
|
|
| The first `root_transformer` vertical slice is implemented with: |
|
|
| 1. Define a small `SequenceSample` contract and deterministic fixture. |
| 2. Implement token construction using shared event/features infrastructure. |
| 3. Add the transformer model under `models/root_transformer/`. |
| 4. Connect it to the existing binary task and trainer on a tiny fixture. |
| 5. Add checkpoint, prediction, and reproducibility tests. |
|
|
| The first implementation is available as |
| `model=root_transformer/transformer`. It can train on an existing graph cache |
| by adapting node features into ordered sequence tokens; this is a migration |
| bridge while a native sequence cache and DDP sequence loader are evaluated. |
|
|
| Native sequence-cache storage and distributed sequence loading remain follow-up |
| work; do not generalize shared interfaces until those use cases require it. |
|
|
| ## Validation requirements |
|
|
| Every new model family must provide unit tests for its representation and |
| model, a small end-to-end integration test, checkpoint reload coverage, and a |
| deterministic repeatability check. Scientific behavior that is intentionally |
| shared with ROOT-GNN should be compared against the frozen reference fixture; |
| architecture-specific behavior should have its own reference outputs. |
|
|
