Feat/cuda graph training

[EHxuban11]

Code provenance

Original implementation written for this PR. CUDA graph capture is built entirely on PyTorch public API (torch.cuda.make_graphed_callables, torch.cuda.is_current_stream_capturing) following PyTorch documented capture recipes. No third-party training framework code was consulted or referenced.

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}

Greptile Summary

Implements opt-in, single-GPU CUDA graph training while retaining eager loss computation and fallback behavior.

• Adds graph capture, shape-based dispatch, buffer restoration, and eager fallback infrastructure.
• Integrates capture specifications for YOLO9 and RF-DETR.
• Exposes the feature through training configuration and the CLI.
• Adds CUDA parity, routing, fallback, and AMP tests plus usage documentation.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains; the previously reported BatchNorm warm-up drift is addressed by snapshotting buffers before capture, restoring them in place before the first replay, and testing exact YOLO9 buffer parity.

Important Files Changed

Filename	Overview
libreyolo/training/cuda_graph.py	Adds graph capture management, output-tree adaptation, shape dispatch, in-place buffer restoration, and permanent eager fallback after capture failures.
libreyolo/training/trainer.py	Integrates optional graph routing into both training loops while retaining eager execution for unsupported configurations and shape misses.
libreyolo/models/yolo9/trainer.py	Defines the captured-network/eager-loss boundary for the plain YOLO9 detection head.
libreyolo/models/rfdetr/trainer.py	Defines the captured RF-DETR network path while keeping target conversion and Hungarian criterion execution eager.
libreyolo/models/rfdetr/transformer.py	Avoids capture-time host synchronization and caches fixed spatial-shape tensors by shape and device.
tests/unit/test_cuda_graph_training.py	Covers dispatch and fallback behavior and verifies YOLO9 loss, parameter, and buffer parity between eager and graphed execution.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  Batch[Training batch] --> Enabled{CUDA graph enabled and supported?}
  Enabled -- No --> Eager[Eager model forward]
  Enabled -- Yes --> Shape{Captured shape?}
  Shape -- No --> Warmup{Shape repeated enough?}
  Warmup -- No --> Eager
  Warmup -- Yes --> Snapshot[Snapshot model buffers]
  Snapshot --> Capture[Warm up and capture network]
  Capture --> Restore[Restore buffers in place]
  Restore --> Replay[Replay captured network]
  Shape -- Yes --> Replay
  Replay --> Loss[Eager family loss]
  Eager --> Loss
  Loss --> Backward[Backward and optimizer step]

Loading

_{Reviews (2): Last reviewed commit: "Restore module buffers after capture war..." | Re-trigger Greptile}

Context used (3)

• Knowledge Base — Training Pipeline
• Knowledge Base — Model zoo, architectures, and inference backends
• Knowledge Base — CLI entrypoint