AutoGineer
Generated banner for Nvflare Convert Pytorch
Generated logo for Nvflare Convert Pytorch

Nvflare Convert Pytorch

NVIDIAOfficialCreated by NVIDIA FLARE Team

  • Skill
  • Workflow
  • Software development
  • Apache-2.0
  • Medium risk
  • Has scripts
Download ZIP

From the author

Convert existing plain or manual PyTorch training code into an NVFLARE federated job using Client API model exchange, local validation, and job export; use when the user names plain PyTorch or preliminary source inspection identifies one plain-PyTorch owner, and not for Lightning, other frameworks, deployment, POC/production lifecycle, or experiment workflows.
— the description by NVIDIA FLARE Team

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides a structured procedure for migrating existing, manual PyTorch training code into an NVFLARE federated learning environment. It focuses on wrapping standard PyTorch training loops, models, and data loaders to support federated model exchange, local validation, and job export. The process emphasizes maintaining the integrity of the original training logic while integrating it into the NVFLARE Client API, ensuring that model parameters, metrics, and optimizer steps are correctly handled across federated rounds.

What it does

  • Inspects existing PyTorch source code to extract training, model, and data loading logic.
  • Generates a federated training client using the NVFLARE Client API.
  • Configures federated jobs using standard recipes like FedAvg.
  • Implements model exchange patterns for PyTorch state_dict objects.
  • Validates the converted job through local simulation and artifact inspection.
  • Exports the final federated job structure for deployment.

When to use it

  • When you have a working, plain PyTorch training script that you want to run in a federated learning setting.
  • When you need to implement model aggregation across multiple sites using PyTorch.
  • When you require local validation of federated training rounds before full-scale deployment.
  • When you need to convert manual training loops into a structured NVFLARE job format.

Advantages

  • Automates the boilerplate required to transition from local to federated training.
  • Ensures consistent handling of model parameters and metric reporting.
  • Provides a validated path for job construction and configuration.
  • Maintains compatibility with standard PyTorch workflows and data structures.

Usage examples

“Convert my existing PyTorch training script to an NVFLARE job.”
The agent will inspect your script, identify the model and training loop, and generate the necessary client.py and job.py files to run it as an NVFLARE federated task.
“How do I add local validation to my PyTorch federated job?”
The agent will guide you through integrating your existing evaluation logic into the NVFLARE Client API, ensuring metrics are correctly reported back to the server.

Install

  1. Download the skill as a ZIP:

    https://mp-staging.autogineer.com/agent-skills/nvidia/nvflare-convert-pytorch/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip nvflare-convert-pytorch.zip -d .agents/skills

Documentation by NVIDIA FLARE Team

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.

Requirements

  • Must audit model constructor arguments before writing job.py by reading the model module's __init__ and the selected recipe's model parameter from nvflare recipe show <recipe-name> --format json, not by reading NVFLARE library source. Emit the selected recipe's documented class_path or path key plus complete args for every required or overridden constructor value; a direct torch.nn.Module is allowed only when unchanged zero-argument defaults reconstruct it. Values must be statically clear from literal source, configuration, or supplied metadata. Otherwise ask one semantic question when an answer channel exists or fail closed.

  • Must follow ../nvflare-shared/references/pytorch-model-exchange.md and references/pytorch-client-api-conversion.md for the canonical plain-PyTorch payload and round-loop pattern.

  • Must apply ../nvflare-shared/references/pytorch-family-recipe-construction.md after recipe show; it is the canonical policy for optional recipe parameters, model selection, tensor transport, server disk offload, and execution mode. Never patch a framework-neutral runtime module or register FOBS handlers in client.py.

  • Must convert source evaluation alongside training and return metrics through FLModel.metrics; must not synthesize metric semantics without source evidence.

  • Must count completed local optimizer steps in each generated training round and send that positive value as MetaKey.NUM_STEPS_CURRENT_ROUND. This is the FedAvg aggregation weight; do not omit it, reuse a cumulative count, or invent a value when the source loop cannot establish it.

  • Must load checkpoints with torch.load(..., weights_only=True); a checkpoint that needs full unpickling is ask/fail, per references/pytorch-client-api-conversion.md.

  • Must not make non-PyTorch-family skills load ../nvflare-shared/references/pytorch-model-exchange.md; that reference is for plain PyTorch, PyTorch Lightning, and Hugging Face Trainer model/state-dict exchange only.

  • Site partitioning, custom aggregation, the Source Of Truth Boundary, and user input/authorization follow ../nvflare-shared/references/conversion-common.md.

Always read this converter SKILL.md together with ../nvflare-shared/references/conversion-common.md. The standard routing, recipe selection, and reporting path is inline, so common FedAvg does not load broad policy or algorithm-selection references. Load the client template, model-exchange reference, validation reference, and aggregator asset only when their phase needs them. Load other detailed references only for exceptions:

  • ../nvflare-shared/references/conversion-workflow.md for the full conversion contract when a case is non-standard;

  • ../nvflare-shared/references/site-data-and-paths.md only for generated site partitions, relative-path resolution, or per-site data locations;

  • ../nvflare-shared/references/pytorch-family-recipe-selection.md only for ambiguous or non-FedAvg algorithms, and references/recipe-selection.md only for non-FedAvg or execution-mode construction details not supplied by recipe show;

  • ../nvflare-shared/references/pytorch-family-recipe-construction.md after every recipe show;

  • ../nvflare-shared/references/dependency-install.md only when an install is needed;

  • ../nvflare-shared/references/runtime-output-guidance.md only for read-only source roots or user-chosen output destinations;

  • ../nvflare-shared/references/metrics-and-artifact-reporting.md only when metrics are absent or inconsistent;

  • ../nvflare-shared/references/validation-evidence.md before validation, and ../nvflare-shared/references/pytorch-model-exchange.md only for PyTorch-family exchange;

  • references/pytorch-client-api-conversion.md for Client API conversion, and references/job-validation.md for PyTorch-specific validation failures.

Do not load every reference preemptively, and do not depend on NVFLARE repository examples being present in the user's environment.

Files

references/pytorch-client-api-conversion.md

PyTorch Client API Conversion

This reference covers standard PyTorch training loops that already have a torch.nn.Module, optimizer, data loaders, and metrics. Load ../../nvflare-shared/references/pytorch-model-exchange.md for PyTorch-family state-dict and tensor payload rules before changing model exchange code.

Canonical Path

Use this path for plain PyTorch conversion:

  1. Confirm PyTorch routing with nvflare agent inspect source.

  2. Select a PyTorch-family recipe with nvflare recipe list/show.

  3. Generate client.py with nvflare.client receive / send and FLModel(params=...) as the model exchange path.

  4. Generate job.py that builds the selected recipe and calls recipe.execute(SimEnv(...)).

  5. Select exactly one final target: run python job.py and inspect its materialized simulation workspace for local validation, or, only when the user requests an exported/deployable artifact, export and run that folder with the simulator CLI. Do not run both targets after one succeeds.

HE is not supported at steps 4–5: follow the HE-not-supported rule in ../../nvflare-shared/references/pytorch-family-recipe-selection.md.

Follow the Source Of Truth Boundary and the generated-entry rule in ../../nvflare-shared/references/conversion-workflow.md: client.py is an FL-only Client API entry point, not a standalone/FL auto-detecting launcher.

Conversion Pattern

  • Import nvflare.client as flare.

  • Build the model, optimizer, loss, and data loaders once before the loop, not inside it, per the shared "Setup Outside The Round Loop" rule in ../../nvflare-shared/references/conversion-workflow.md.

  • Call flare.init() before setup hooks that need Client API context, such as flare.get_config() or flare.get_site_name(), while still keeping setup outside the federated round loop.

  • Loop while flare.is_running().

  • Call flare.receive() to get the incoming FLModel.

  • Load input_model.params into the PyTorch model with load_state_dict.

  • Train or evaluate using the user's existing data loader and optimizer.

  • Count only optimizer steps completed in the current round. The generated train_one_round helper must return this positive count; do not use an estimated, cumulative, or default value.

  • Send the trained weights with the canonical plain-PyTorch payload pattern in ../../nvflare-shared/references/pytorch-model-exchange.md. Do not call model.cpu(), which moves the persistent model off the training device.

PyTorch Parameter Payload Type

Use the exact outbound payload contract and send snippet in ../../nvflare-shared/references/pytorch-model-exchange.md. Apply the separate recipe-capability policy in ../../nvflare-shared/references/pytorch-family-recipe-construction.md; its server disk-offload optimization does not change the client payload contract or execution mode.

Source Layout

Use the canonical FLARE source layout defined in ../../nvflare-shared/references/conversion-workflow.md ("Generated Job Layout"): client.py, model.py, job.py, and the optional aggregators.py, data-setup, and requirements files. Avoid ad hoc entry-point names such as fl_train.py unless the user explicitly requests that naming, and use ../../nvflare-shared/references/runtime-output-guidance.md for runtime workspaces, exported job directories, and validation output locations. During export inspection, verify generated or project-local modules referenced by server-side class_path config are packaged into the server app with recipe.add_server_file(...) or an equivalent server-targeted API. The train_script import closure packages client apps and is not enough for per-site exports that create app_server separately. Installed NVFLARE, framework, and third-party class paths stay runtime dependencies and are validated through requirements installation plus import/preflight checks.

For standard FedAvg, package shared generated files for all clients. Do not replace all-client deployment with explicit per-site deployment unless the conversion has real per-site differences such as different scripts, arguments, data-split settings, or launch behavior.

For multi-site conversion from a single-node PyTorch source, the generated client or data-loader setup must filter the local training data by site. Do not let every simulated site train on the full source training set unless the user explicitly asks for shared training data or the source already provides site-specific data that resolves to that behavior. Validation/test loaders may remain shared only when that matches the source's validation/test semantics. For generated Pandas partition code, follow ../../nvflare-shared/references/site-data-and-paths.md.

Model Construction Consistency

Follow the shared model-config and construction-consistency rule in ../../nvflare-shared/references/conversion-workflow.md ("Recipe Model Config"): same class and constructor args on server and client, explicit config whenever reconstruction needs a constructor value, and derive-or-ask/fail-closed for it.

PyTorch-specific delta: the client loads input_model.params into the model with load_state_dict, so the server-initial model and the client model must have matching state-dict shapes (same parameter names and tensor shapes), not only matching constructor args.

Acceptable patterns include:

  • a shared model_args dict imported by both job.py and client.py;

  • an explicit recipe model config such as {"class_path": "model.ModelClass", "args": model_args} (prefer class_path; path is the normalized job-config key);

  • a small JSON/config file read by both sides;

  • explicit CLI arguments passed through recipe train_args and parsed by client.py, with the same values used in job.py.

Before simulation, validate the generated model construction path when possible by instantiating the server-side and client-side model with the same arguments and checking that load_state_dict can accept the initial parameters. Treat a state-dict key or tensor-shape mismatch as a conversion bug, not as a reason to change the model architecture without user approval.

Paired Evaluation Template

Training and evaluation are a pair: every converted training loop that has source evaluation evidence must also convert that evaluation, and its metrics must reach the server through FLModel.metrics. Adapt the user's existing evaluation code into this template. Do not synthesize metric semantics, validation loaders, label mappings, or averaging denominators from scratch without source evidence; when evaluation is required but the source has none, ask in interactive mode or fail closed in unattended mode.

Follow the "Best-Model Metric" contract in ../../nvflare-shared/references/pytorch-family-recipe-construction.md. It owns metric-name matching and lower-is-better direction; this reference owns where evaluation occurs in the plain-PyTorch round loop.

The self-contained runnable template ships at ../assets/client_with_eval.py; adapt it rather than duplicating its code here or depending on repository examples/. It initializes setup once, receives and loads the global model, evaluates that received model, handles evaluation-only tasks, trains, and sends the canonical model payload, source-backed metric, and the actual completed optimizer-step count for FedAvg weighting. If the source loop cannot establish that count, ask in interactive mode or fail closed in unattended mode instead of silently using equal client weights.

The round FLModel.metrics is this pre-training evaluation of the received global model, not a post-training metric — see ../../nvflare-shared/references/metrics-and-artifact-reporting.md ("Received-Model Metric Ownership").

When the task is evaluation-only or cross-site evaluation, use flare.is_evaluate() to send flare.FLModel(metrics=...) without local training and without params.

Checkpoint Loading Safety

Generated code that loads PyTorch checkpoint files must use safe weight-only loading: torch.load(..., weights_only=True). A checkpoint that requires full pickle unpickling or custom executable deserialization is not statically safe; ask in interactive mode or fail closed in unattended mode instead of loading it.

Scope Boundaries

  • Keep user model architecture and loss function unless the user asks for a change.

  • Keep data loading local to the site and do not add code that copies private data into generated artifacts.

  • For checkpoints, preserve user checkpoint semantics and document what is federated versus site-local.

  • For metrics, send scalar summaries in the metrics field. Use ../../nvflare-shared/references/metrics-and-artifact-reporting.md for generic final metrics, round metrics, model artifact paths, and missing-evidence reporting.

Job Pattern Reference

Load recipe-selection.md before creating or updating job.py so the selected recipe matches the user's requested FL workflow. Do not assume NVFLARE repository examples are available in the user's environment.

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs Python

Security

What our scanner noticed· Medium risk

  • Phrasing that asks for actions without confirmation
  • Large base64-encoded blobs
  • Scripts that your agent may run

This skill includes scripts that your agent may run. Read them before you use it.

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by
NVIDIA FLARE Team
Publisher
NVIDIA (Official)
Source
NVIDIA/skills · skills/nvflare-convert-pytorch · commit fce3cca
Licence
Apache License 2.0 (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE-APACHE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by NVIDIA FLARE Team or NVIDIA.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download nvflare-convert-pytorch.zip