docs/agent-workflows/gnn4colliders-workflow.md

# 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:

```text
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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](../configuration.md) for source
fields, cache behavior, labels, and split semantics.

The CLI has five subcommands:

```bash
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:

```bash
uv run python -m validation.run_public_validation
```

Focused checks should run before broad checks:

```bash
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.