Nvflare Convert Pytorch

NVFLARE Convert PyTorch

Use When

Use when converting an existing plain PyTorch training script, torch.nn.Module, manual training loop, state_dict workflow, data loader, checkpoint, or metric loop into an NVFLARE federated training job. Supports horizontal FL, Client API model exchange with FLModel, recipe aggregator= hooks, validation, and export.

Do Not Use When

Do not use for PyTorch Lightning (route to nvflare-convert-lightning), Hugging Face Trainer (route to nvflare-convert-huggingface), TensorFlow, XGBoost, scikit-learn, failed jobs (route to nvflare-diagnose-job), federated statistics without training (route to nvflare-fed-stats), or generic PyTorch debugging without FLARE intent. Out of scope: production deployment, Kubernetes, POC lifecycle, privacy/security policy design, controller/workflow rewrites outside recipe or Job APIs, experiment search, and data distribution experiments beyond minimal validation setup. Privacy-protection requests — HE/encrypted aggregation, differential privacy, and privacy filters — need provisioning/deployment policy; route onward rather than substituting an unprotected recipe or adding only a 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. Load ../nvflare-shared/references/conversion-common.md and apply it for the whole conversion; this SKILL.md states only the framework-specific deltas. Load ../nvflare-shared/references/conversion-workflow.md only for a non-standard rerun, authorization, or missing-semantics case; it no longer holds the data-location or partitioning contracts, whose invariants conversion-common.md owns. Load ../nvflare-shared/references/site-data-and-paths.md for generated partitions, relative paths, or per-site data locations.
2. Inspect before editing with nvflare agent inspect source <path> --format json plus direct reading. Fact extraction is static; do not import or execute user training modules to discover fields. Extract: training entrypoint, model class path and constructor args, checkpoint behavior, train/eval functions, data loading, metric names and denominators, local epochs/steps, requested client and round counts, source data split or partition evidence, tracking evidence, DDP evidence, and any custom aggregation intent.
3. Apply the dependency-install ordering rule in ../nvflare-shared/references/conversion-common.md before any Python command imports user, PyTorch, NVFLARE, or declared dependency modules.
4. Select the recipe from the requested FL workflow, not from PyTorch alone. For the standard case — the user explicitly requests FedAvg and inspection identifies PyTorch — run nvflare recipe show fedavg-pt --format json directly and construct it; do not add per-site recipe config unless sites actually differ. Load ../nvflare-shared/references/pytorch-family-recipe-selection.md (discovery, algorithm guide, catalog-based selection, HE-not-supported rule) only for ambiguous or non-FedAvg algorithms, reserving nvflare recipe list for those cases. Use the module, class, and parameters returned by recipe show for standard job.py construction; for fedavg-pt, import FedAvgRecipe from nvflare.app_opt.pt.recipes.fedavg, never from nvflare.recipe. After every recipe show, load ../nvflare-shared/references/pytorch-family-recipe-construction.md and derive the recipe's construction capabilities. Load references/recipe-selection.md only when non-FedAvg or execution-mode details are needed.
5. Convert training and evaluation as a pair using references/pytorch-client-api-conversion.md: initialize FLARE, receive an FLModel, load params, evaluate the received global model, train, and send an FLModel with updated params, metrics, and the actual completed local optimizer-step count in NUM_STEPS_CURRENT_ROUND. Adapt the user's evaluation code into the packaged evaluation template; if evaluation is required but missing, ask or fail closed. Apply the step-1 data-location rules to the generated client's data argument.
6. Add or update job.py under the shared constructor-serialization rule: use explicit class_path (or documented path alias) plus complete args whenever reconstruction needs values. Add requested aggregator= wiring, metric, tensor-transport, server offload, and execution settings derived from the shared PyTorch-family construction profile.
7. Validate in a ladder per ../nvflare-shared/references/validation-evidence.md: compile checks, recipe construction, one final full-run path chosen by the artifact being validated, with export and package inspection only for the selected exported-artifact path. For a local target, inspect the materialized configs and packaging evidence after that run. Use references/job-validation.md for PyTorch-specific failures. Stop at the first failed rung and report the product error. Use the environment and permission mechanisms supplied by the agent host; do not inspect or enforce its security boundary.
8. Report the recipe, changed files, validation status, metrics, and exact artifact paths. Load ../nvflare-shared/references/metrics-and-artifact-reporting.md only when normal metric artifacts are absent or inconsistent.