GNN4Colliders agent workflow

This runbook is the shared operational reference for Codex and Claude when working in this repository.

Start here

Before a non-trivial change, read:

AGENTS.md
docs/architecture.md
docs/migration.md

Production Python belongs under src/gnn4colliders/. Keep collider physics features in features/, graph topology in graphs/, architecture code in models/, and lifecycle code in training/. Use the frozen parity fixtures and compatibility adapters for historical behavior; do not add historical implementation imports.

Environment

The normal development environment is:

uv sync --dev --extra root-gnn

Use the root-gnn extra for DGL-backed tests and ROOT-GNN workflows. ONNX checks additionally need the onnx extra.

For the shortest end-to-end check, use the repository's temporary ROOT fixture:

uv run python scripts/dev/smoke_end_to_end.py

This creates a temporary ROOT file, prepares a graph cache, trains one CPU epoch, evaluates, predicts, and removes its temporary files.

Public data and configurations

The supported public source is the pinned HWresearch/Delphes dataset. The Hub resolver caches files locally and verifies configured checksums before ROOT ingestion.

Use the small deterministic fixture first:

uv run gnn4colliders prepare --config-name config_hf_smoke
uv run gnn4colliders train --config-name config_hf_smoke

For the full 12-process pretraining source:

uv run gnn4colliders prepare --config-name config_hf_delphes

The full configuration can download a large dataset. Do not use it for an ordinary smoke check. See configuration.md for source fields, cache behavior, labels, and split semantics.

The CLI has five subcommands:

uv run gnn4colliders prepare ...
uv run gnn4colliders train ...
uv run gnn4colliders evaluate ...
uv run gnn4colliders predict ...
uv run gnn4colliders export ...

Use semantic Hydra overrides such as model=root_gnn/edge_network and task=binary_classification; keep implementation module paths out of user configuration. A run writes its resolved configuration and checkpoints below environment.output_root.

Validation and testing

Run the portable scientific regression before claiming a data or physics change is correct:

uv run python -m validation.run_public_validation

Focused checks should run before broad checks:

uv run pytest tests/unit/<relevant-area> -q
uv run pytest -q
GNN4COLLIDERS_REQUIRE_ROOT_GNN=1 uv run pytest tests/parity -q
uv run ruff check .
uv run ruff format --check .

The strict parity command must fail when DGL is unavailable; do not replace it with a command that permits parity tests to skip. A CUDA-only skip is expected on CPU hosts and must be reported.

Change discipline

Preserve event ordering, feature ordering, tensor shapes, dtypes, labels, weights, fold semantics, and graph topology unless the change explicitly updates a documented contract.
Use named metadata fields; do not introduce new public APIs based on positional tracking columns.
Keep CLI modules thin. Put reusable behavior in the package or validation modules.
Avoid private filesystem paths, hidden global state, and untracked generated validation output.
Do not import or recreate a historical runtime backend. The old behavior is represented by frozen reference fixtures and the root-gnn-parity-baseline tag; compatibility code is limited to explicit checkpoint/metadata/output boundaries.
For a parity difference, characterize it with a deterministic test and state whether it is intentional.

Reporting

At handoff, report files changed, behavior implemented, exact checks run, passed/failed/skipped counts, parity status, intentional deviations, and unresolved questions. Never describe a check as passed unless it was executed.