/nvflare-convert-lightning

name: nvflare-convert-lightning
description: "Convert existing PyTorch Lightning training code into an NVFLARE federated job using the Lightning Client API patch, local validation, and job export; use only when the request names federated/NVFLARE conversion or asks multiple sites to train collaboratively while keeping each site's data local, and either names PyTorch Lightning or preliminary source inspection identifies one Lightning owner; do not use for non-federated Lightning work such as DDP, profiling, inference serving, or training-loop changes, nor for plain PyTorch, TensorFlow/Keras, other frameworks, deployment, POC/production lifecycle, or experiment workflows."
license: Apache-2.0
metadata:
  version: "0.1.0"
  author: "NVIDIA FLARE Team <federatedlearning@nvidia.com>"
  min-flare-version: "2.9.0"
  blast-radius: runs_simulator
  category: Conversion
  tags: "nvflare, federated-learning, pytorch-lightning, conversion"
  languages: "python"
  frameworks: "pytorch-lightning, pytorch, nvflare"
  domain: ml

NVFLARE Convert PyTorch Lightning

Use When

Use only when the user asks to convert PyTorch Lightning code into an NVFLARE federated training job; require both federation intent and Lightning ownership. Treat requests for multiple sites or institutions to train collaboratively while each site's data remains local as federation intent, even when the request does not say "federated" or "NVFLARE." Lightning source evidence alone is not sufficient. Relevant source may contain a `LightningModule`, `LightningDataModule`, a `Trainer` fit/validate/test loop, Lightning callbacks, checkpointing, or loggers. Supported: the PyTorch recipe family with `flare.patch(trainer)` as the model exchange integration, Lightning-native evaluation, custom aggregation through the same recipe `aggregator=` hook, and local validation and export.

Standard Path

Always read this converter SKILL.md with `../nvflare-shared/references/conversion-common.md`. For an explicit-FedAvg conversion, load only these references, in workflow order:

1. During inspection, `references/lightning-detection.md`. 2. For generated splits, relative paths, or per-site data locations, `../nvflare-shared/references/site-data-and-paths.md`. 3. After `nvflare recipe show fedavg-pt --format json`, `../nvflare-shared/references/pytorch-family-recipe-construction.md`. 4. During conversion, `references/lightning-conversion.md`, then `../nvflare-shared/references/pytorch-model-exchange.md`. 5. Only after generated files exist, `../nvflare-shared/references/validation-evidence.md`, then `references/lightning-validation.md`.

Complete each workflow phase before loading the next phase's reference. Do not enumerate reference directories or preload validation, DDP/tracking, broad workflow, dependency, runtime-output, or reporting references. Do not depend on NVFLARE repository examples.

Do Not Use When

Do not use for non-federated Lightning changes such as DDP-only configuration, profiling, inference serving, callbacks, early stopping, or schedulers; or for plain `torch.nn.Module` manual training loops without Lightning (route to `nvflare-convert-pytorch`), Hugging Face Trainer (route to `nvflare-convert-huggingface`), TensorFlow, XGBoost, scikit-learn, a failed job (route to `nvflare-diagnose-job`), federated statistics without training (route to `nvflare-fed-stats`), or generic Lightning debugging without FLARE intent; when the inspected project actively contains both Lightning and Hugging Face Trainer entrypoints, route to `nvflare-orient`. Out of conversion scope: production deployment, Kubernetes, POC lifecycle, deployment privacy/security policy design, custom distributed launch policies not expressible by product APIs, experiment tracking redesign, and experiment search across recipes. Privacy-protection requests — homomorphic encryption (HE) / encrypted aggregation, differential privacy, and privacy filters — are not supported: they require provisioning or deployment policy beyond conversion scope, so report such a request as unsupported and route it to provisioning/deployment, never substituting an unprotected recipe or disclaimer. If a request combines federated statistics and model-training conversion, treat it as two independent jobs and workflows: do not merge or automatically chain them, do not route the combination to `nvflare-orient`, and ask which workflow to run first before generating or running either job. Recommend `nvflare-fed-stats` first only when the user's purpose is to understand data distribution; handle conversion later as a separate request.

Workflow

1. Apply `../nvflare-shared/references/conversion-common.md` for the whole conversion; this SKILL.md states only the framework-specific deltas. 2. Inspect before editing with `nvflare agent inspect source <path> --format json` plus direct reading; fact extraction is static. Confirm Lightning versus plain PyTorch and hand off to `nvflare-convert-pytorch` when no Lightning evidence exists. If inspection recommends `nvflare-orient` for active Lightning and Hugging Face Trainer owners, stop and hand off before editing. 3. Apply the dependency-install ordering rule in `../nvflare-shared/references/conversion-common.md` before any Python command imports user, Lightning, NVFLARE, or declared dependency modules. Determine applicable dependencies from the selected execution path first. If required data artifacts already exist and static inspection shows that the selected path will not reach a download helper or its imports, treat its download-only requirements as inapplicable: do not install or import-probe them. Probe only modules the generated conversion and selected validation path will execute, and keep an optional probe separate and exit-zero when unavailable. 4. Identify the existing `LightningModule`, `LightningDataModule`, trainer construction, callbacks, checkpointing, `validation_step