From 9dd841575039e545a45d1f58849f6c96264396e2 Mon Sep 17 00:00:00 2001 From: at24_bioeng625-pc Date: Wed, 5 Aug 2026 15:24:56 +0100 Subject: [PATCH 1/3] docs: correct Model Files and Training Configuration in the user guide The user guide's "Model Files" section stated a fixed minimum file set (validator.py, trainer.py) for NVFLARE apps and described config.json as optional. Both are wrong: required files are declared per job type in fl-apps///required_files.json, config.json is required for every NVFLARE job type, and standard_client_api does not require validator.py while evaluation requires evaluator.py instead of a trainer. The "Training Configuration" subsection also carried a full NVFLARE key reference in a page that is meant to be backend-neutral, with several inaccuracies: the round range is 1-1000 (not "greater than 0, less than 100") and out-of-range values are discarded in favour of the default rather than rejected; AGGREGATION_WEIGHTS keys are FL client site names (the kit slot each Trust occupies, e.g. Trust_1), not Trust codes such as KCH, so the documented example would have had no effect. Rework the user guide to describe the job-type-driven contract and point at where the UI surfaces the applicable list, and move the corrected per-backend reference to the FL nodes component page, which is already the documented home for framework-specific file requirements and job types. The new reference covers the required-files manifests for both backends, the validated NVFLARE config.json keys (including AGGREGATE_ONLY_REGEX and the BEST_MODEL_METRIC pair) and Flower's pyproject.toml/config.toml run configuration. Also correct the FL nodes page's claim that pyproject.toml is a researcher-supplied file for Flower apps: it comes from the platform's base template, and per-run overrides go in config.toml. Signed-off-by: at24_bioeng625-pc --- docs/source/components/component-fl-nodes.rst | 184 +++++++++++++++++- docs/source/user-guides/user-common.rst | 100 ++++------ .../create-flip-app-from-flower.rst | 2 +- 3 files changed, 215 insertions(+), 71 deletions(-) diff --git a/docs/source/components/component-fl-nodes.rst b/docs/source/components/component-fl-nodes.rst index a1214d9fa..fe413858e 100644 --- a/docs/source/components/component-fl-nodes.rst +++ b/docs/source/components/component-fl-nodes.rst @@ -41,12 +41,13 @@ More job types will be added in the future, adjusting to the community's needs. **How to choose a job type?** A federated learning job is an ensemble of files (among which we can find `python`, `json` or `toml` files) -we call an app. Some of these files are required to run the app (for instance, the `pyproject.toml` file in a Flower app), -and some are optional. +we call an app. Some of these files are required to run the app, and some are optional — which ones +are required depends on the job type (see :ref:`fl-required-files` below). The job type is passed as key `job_type` in the `config.json` file (for both NVFLARE and Flower apps). +An unrecognised value is rejected at submission; a missing one falls back to ``standard``. -Once uploaded, the UI will indicate which files are required for the specific job. +Once uploaded, the UI will indicate which files are required for the specific job. Then, the Central Hub API will take care of bundling together: - The files the user has uploaded @@ -83,6 +84,183 @@ These tutorials run on the local NVFLARE simulator from the repo root — e.g. Workflow of how the user uploads files for a specific job type. +.. _fl-required-files: + +Required files per job type +--------------------------- + +Each job type declares its own set of required files. A submission missing any of them is rejected +before anything is shipped to a Trust, with a message naming the missing files. + +The lists below are reproduced from the manifests in the repository +(``fl-apps///required_files.json``, aggregated into +``fl-apps//required_files.json``), which are the source of truth. The FLIP UI reads the +same manifests through the ``/model/job-types`` endpoint and shows the applicable list on the model +page — so the UI, not this table, is what to trust if the two ever disagree. + +**NVFLARE job types** + +.. list-table:: + :header-rows: 1 + :widths: 32 68 + + * - Job type + - Required files + * - ``standard`` + - ``trainer.py``, ``validator.py``, ``models.py``, ``config.json`` + * - ``standard_client_api`` + - ``trainer.py``, ``models.py``, ``config.json`` (no ``validator.py`` — the Client API script + does its own validation) + * - ``fed_opt`` + - ``trainer.py``, ``validator.py``, ``models.py``, ``config.json`` + * - ``diffusion_model`` + - ``trainer.py``, ``validator.py``, ``models.py``, ``config.json`` + * - ``diffusion_model_client_api`` + - ``trainer.py``, ``validator.py``, ``models.py``, ``config.json`` + * - ``evaluation`` + - ``evaluator.py``, ``config.json`` + * - ``evaluation_client_api`` + - ``evaluator.py``, ``models.py``, ``config.json`` + +**Flower job types** + +.. list-table:: + :header-rows: 1 + :widths: 32 68 + + * - Job type + - Required files + * - ``standard`` + - ``client_app.py``, ``models.py`` + * - ``evaluation`` + - ``client_app.py``, ``models.py`` + +.. note:: + + ``config.json`` is a required file for every NVFLARE job type, because it carries ``job_type`` + along with the training configuration below. It is *not* required for Flower job types, but + uploading one is still how a Flower app selects a job type other than ``standard``. + + ``pyproject.toml`` is **not** a file the researcher supplies for a Flower app. It is part of the + platform's base template for the job type and is bundled automatically; a ``pyproject.toml`` + uploaded as a model file does not become the app's project file. Per-run overrides go in + ``config.toml`` instead (see below). + +Beyond the required set, any additional file uploaded with the model is bundled into the app, which +is how apps ship helper modules, transforms and pre-trained checkpoints. + +.. _fl-training-configuration: + +Training configuration +---------------------- + +NVFLARE ``config.json`` +~~~~~~~~~~~~~~~~~~~~~~~ + +For NVFLARE job types, ``config.json`` carries both the job type and the platform-recognised +training settings. Every setting has a default, so an app that declares only ``job_type`` is valid. + +.. code-block:: json + + { + "job_type": "standard", + "GLOBAL_ROUNDS": 5, + "LOCAL_ROUNDS": 2, + "IGNORE_RESULT_ERROR": false, + "AGGREGATOR": "InTimeAccumulateWeightedAggregator", + "AGGREGATION_WEIGHTS": { + "Trust_1": 1.0, + "Trust_2": 0.5 + } + } + +**GLOBAL_ROUNDS** + Number of global (server-side) rounds — how many times the server distributes the global model, + collects client updates and aggregates them. Accepted range 1–1000 inclusive. + + *Default = 1* + +**LOCAL_ROUNDS** + Number of local training iterations performed at each client site per global round. Accepted + range 1–1000 inclusive. + + *Default = 1* + + .. note:: + + A ``GLOBAL_ROUNDS`` or ``LOCAL_ROUNDS`` value that is not a number, or that falls outside the + accepted range, does not fail the job — it is discarded and the default of 1 is used instead. + A single-round job is easy to mistake for a broken one, so check the value that reached the + job if training finishes sooner than expected. + +**IGNORE_RESULT_ERROR** + Whether training should proceed when a client returns an error. + + *Default = false* + +**AGGREGATOR** + The NVFLARE aggregation component used to combine client updates. FLIP only supports aggregator + components built into NVFLARE; allowed values are ``InTimeAccumulateWeightedAggregator`` and + ``AccumulateWeightedAggregator``. Any other value fails config validation and prevents training + from starting. + + *Default =* ``InTimeAccumulateWeightedAggregator`` + +**AGGREGATION_WEIGHTS** + JSON object mapping a client site to the weight its update carries in aggregation. Weights must + be numbers between 0 and 1 inclusive; a non-object value, or a weight outside that range, fails + config validation. + + .. warning:: + + The keys are **FL client site names** — the FL kit slot each Trust occupies (``Trust_1``, + ``Trust_2``, …), which is what the FL server knows a client by. They are not the Trust's + hub-side name or code. A key that matches no participating client is simply unused, so a + mistyped key produces no error and no effect. + + *Default = no weights supplied, which NVFLARE treats as a weight of 1.0 for every participating + client* + +**AGGREGATE_ONLY_REGEX** + Regular expression matching the model-parameter names to keep in each client update. When set, + only matching parameters are sent back to the server — for example, a fine-tune with a frozen + backbone can ship just its head instead of the full model. Must be a valid regular expression. + + *Default = unset, i.e. the full model update is sent* + +**BEST_MODEL_METRIC** / **BEST_MODEL_METRIC_MINIMIZE** + Validation-metric label driving best-global-model selection. When set, the best global model is + saved alongside the final one and included in the results, and the client trainer must report a + metric under this label. Set ``BEST_MODEL_METRIC_MINIMIZE`` to ``true`` for loss-like metrics + where lower is better. Because selection cannot happen before the first aggregate exists, + ``BEST_MODEL_METRIC`` requires ``GLOBAL_ROUNDS`` of at least 2, and setting + ``BEST_MODEL_METRIC_MINIMIZE`` on its own is rejected. + + *Default = unset, i.e. only the final model is saved* + +Keys the platform does not recognise are passed through to the app untouched, for the uploaded code +to read at runtime. This is how the tutorials carry app-specific settings such as ``LEARNING_RATE`` +or ``VAL_SPLIT`` — those are conventions of individual apps, not platform settings, and they are +neither validated nor defaulted. A misspelled key of this kind is therefore silently absent at +runtime rather than reported as an error. + +Flower run configuration +~~~~~~~~~~~~~~~~~~~~~~~~ + +Flower apps do not use the NVFLARE keys above. Their run configuration lives in the +``[tool.flwr.app.config]`` table of the base template's ``pyproject.toml``, which the platform +supplies. An app overrides those values with a ``config.toml`` file uploaded alongside its code: +the FL API passes it to ``flwr run --run-config`` at submission, and the FLIP runtime parameters +(model id, project id, cohort query, job directory) are injected into it automatically. + +``config.toml`` can only override keys that the template's ``pyproject.toml`` already declares — it +cannot introduce new ones. Round counts follow Flower's naming rather than NVFLARE's, as +``num-server-rounds`` (global rounds) and ``local-epochs`` (local rounds). + +For a worked example of both files, see the Flower tutorials under +`fl-tutorials/flower/ `_ +and :doc:`/working-with-flip-apps/create-flip-app-from-flower`. + Data access and communication with external services ---------------------------------------------------- diff --git a/docs/source/user-guides/user-common.rst b/docs/source/user-guides/user-common.rst index 55b80cedd..6628fcd13 100644 --- a/docs/source/user-guides/user-common.rst +++ b/docs/source/user-guides/user-common.rst @@ -351,16 +351,28 @@ Model Files A model must be created before proceeding to upload model files and prepare the model for training. -**For NVIDIA FLARE apps**, the minimum required files are: +There is no single list of required files. What a model must contain depends on its **job type** +— the kind of federated job it runs, such as federated averaging or evaluation — and on which FL +backend your platform is running. An app declares its job type with the ``job_type`` key in +``config.json``; if that key is absent, the ``standard`` job type is assumed. -- ``validator.py`` -- ``trainer.py`` +**You do not need to look this up.** FLIP tells you which files your model needs, in two places on +the model page: -Additional files may be uploaded, especially if these are referenced by the validator or trainer. A config file may also be uploaded (see :ref:`training-configuration` section for more information), in which optional variables can be defined. +- The Model Files panel shows the job type currently detected from your uploaded ``config.json``. +- The Training panel lists the files that job type requires, and highlights any that are still + missing. -**For Flower apps**, the required files differ (e.g. ``client_app.py``, ``pyproject.toml``). See the :ref:`FL nodes documentation ` for Flower-specific file requirements and job types. +Both update as soon as you upload or replace ``config.json``, and training cannot be initiated +until every required file has been uploaded. -For more information on model training and model files, please see the `FLIP tutorials `_. +Files beyond the required set may be uploaded freely — anything your code imports (helper modules, +transforms, pre-trained checkpoints) is bundled with the app and shipped to the participating +Trusts. + +The full per-job-type file lists, and the configuration each backend accepts, are documented on +the :ref:`FL nodes component page `. For worked examples of complete, working apps, +see the `FLIP tutorials `_. .. warning:: @@ -417,71 +429,25 @@ If model files need to be managed further after uploading, the uploader function Training Configuration ---------------------- -.. note:: - - The following configuration applies to **NVIDIA FLARE** apps. For Flower apps, training configuration is managed via ``pyproject.toml``. See the :ref:`FL nodes documentation ` for details. - -Prior to commencing training you may also upload an optional ``config.json`` file (see example below). The config file defines variables which are used during FLIP training (e.g. ``GLOBAL_ROUNDS``, ``LOCAL_ROUNDS``, ``AGGREGATION_WEIGHTS``, ``AGGREGATOR``). - -.. code-block:: json - - { - "GLOBAL_ROUNDS": 5, - "LOCAL_ROUNDS": 2, - "IGNORE_RESULT_ERROR": false, - "AGGREGATOR": "InTimeAccumulateWeightedAggregator", - "AGGREGATION_WEIGHTS": { - "KCH": 1.0, - "UCLH": 0.5 - } - } - -.. note:: - - All config properties have default values. If a ``config.json`` file is not uploaded, or some properties are missing from the file, default values will be utilised at runtime. - See default values specified below. - -**GLOBAL_ROUNDS** - Number of global training iterations. How many times the server should execute the ``trainer.py``. - Must be greater than 0. Less than 100. - - *Default=1* +Alongside your code, an app carries a small configuration file that sets how the federated run +behaves — how many rounds it trains for, how client updates are combined, and any settings your +own code reads. -**LOCAL_ROUNDS** - Number of local training iterations at client sites. - Must be greater than 0. Less than 100. - - *Default=1* - -**IGNORE_RESULT_ERROR** - Whether training should proceed if a client returns an error. - - *Default=false* - -**AGGREGATOR** - The nvflare aggregation component used to aggregate training results from each client. - - .. warning:: - Allowed values are "InTimeAccumulateWeightedAggregator" or "AccumulateWeightedAggregator". As of v4, FLIP only supports aggregator components built into nvflare. Specifying any other value will cause - a config validation error and prevent training from initiating. - - *Default="InTimeAccumulateWeightedAggregator"* - -**AGGREGATION_WEIGHTS** - Weight dictionary passed into the aggregator component to define its aggregation behaviour. - - .. warning:: - Client sites *must* be referenced via their common abbreviation e.g KCH=Kings College Hospital, UCLH=University College London Hospital. - Weights must be provided as a valid json object. +Where that configuration lives, and which settings are available, depends on the FL backend: - *Default=1.0 applied to each client site* +- **NVIDIA FLARE apps** are configured through ``config.json``, which is one of the required files + for every NVFLARE job type. As well as declaring ``job_type``, it may set platform-recognised + keys such as ``GLOBAL_ROUNDS`` and ``LOCAL_ROUNDS``. +- **Flower apps** take their run configuration from the platform's app template, which your app + can override with a ``config.toml`` file. Flower apps do not use the NVFLARE keys. -.. code-block:: json +Any key the platform does not recognise is passed through untouched, for your own code to read at +runtime — which is how the tutorials carry app-specific settings such as learning rate or +validation split. - { - "KCH": 1.0, - "UCLH": 1.0 - } +Every platform-recognised key has a default, so an app that sets only ``job_type`` will still run. +For the full list of keys, their accepted values and defaults per backend, see +:ref:`fl-training-configuration` on the FL nodes component page. View Files ---------- diff --git a/docs/source/working-with-flip-apps/create-flip-app-from-flower.rst b/docs/source/working-with-flip-apps/create-flip-app-from-flower.rst index 4f833ffb0..e680c2695 100644 --- a/docs/source/working-with-flip-apps/create-flip-app-from-flower.rst +++ b/docs/source/working-with-flip-apps/create-flip-app-from-flower.rst @@ -375,7 +375,7 @@ Abridged from ``fl-tutorials/flower/3d_spleen_segmentation/pyproject.toml``: Submitting the app to FLIP ************************************ -Once your app runs locally (see the next section), upload it through the FLIP UI's model page the same way you would upload a FLARE app. FLIP validates the required files for a Flower app (which differ from those required for a FLARE app — see the "Model Files" subsection of :doc:`/user-guides/user-common` and the :ref:`flip-fl-nodes` page for the canonical list) and then lets you click **Initiate Training**. +Once your app runs locally (see the next section), upload it through the FLIP UI's model page the same way you would upload a FLARE app. FLIP validates the required files for a Flower app (which differ from those required for a FLARE app, and depend on the job type — see :ref:`fl-required-files` for the canonical list) and then lets you click **Initiate Training**. At submit time, the FLIP FL API: From 10b9e70464e84aee7a598fc13e621f0a8a8df099 Mon Sep 17 00:00:00 2001 From: at24_bioeng625-pc Date: Wed, 5 Aug 2026 15:24:56 +0100 Subject: [PATCH 2/3] docs: clarify that config.json is optional for Flower job types MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Both edited pages described the job type as declared by the job_type key in config.json without noting that config.json is itself a required file only for the NVFLARE job types. A Flower app may omit it entirely — the bundler falls back to job_type=standard when no config.json is present — so the previous wording ("if that key is absent") covered a missing key but read as though the file were mandatory for every app. Signed-off-by: at24_bioeng625-pc --- docs/source/components/component-fl-nodes.rst | 4 +++- docs/source/user-guides/user-common.rst | 4 +++- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/source/components/component-fl-nodes.rst b/docs/source/components/component-fl-nodes.rst index fe413858e..9b35f23c0 100644 --- a/docs/source/components/component-fl-nodes.rst +++ b/docs/source/components/component-fl-nodes.rst @@ -45,7 +45,9 @@ we call an app. Some of these files are required to run the app, and some are op are required depends on the job type (see :ref:`fl-required-files` below). The job type is passed as key `job_type` in the `config.json` file (for both NVFLARE and Flower apps). -An unrecognised value is rejected at submission; a missing one falls back to ``standard``. +An unrecognised value is rejected at submission. A missing one falls back to ``standard``, as does an +app carrying no ``config.json`` at all — which is a valid Flower submission, since ``config.json`` is a +required file for the NVFLARE job types but not for the Flower ones (see :ref:`fl-required-files`). Once uploaded, the UI will indicate which files are required for the specific job. diff --git a/docs/source/user-guides/user-common.rst b/docs/source/user-guides/user-common.rst index 6628fcd13..900fdf83e 100644 --- a/docs/source/user-guides/user-common.rst +++ b/docs/source/user-guides/user-common.rst @@ -354,7 +354,9 @@ Model Files There is no single list of required files. What a model must contain depends on its **job type** — the kind of federated job it runs, such as federated averaging or evaluation — and on which FL backend your platform is running. An app declares its job type with the ``job_type`` key in -``config.json``; if that key is absent, the ``standard`` job type is assumed. +``config.json``. Every NVFLARE app carries a ``config.json``, because it is itself a required file +for those job types; a Flower app only needs one in order to run a job type other than the default. +Where the key — or the file itself — is absent, the ``standard`` job type is assumed. **You do not need to look this up.** FLIP tells you which files your model needs, in two places on the model page: From bfca0385ab63776b5f4b5450a8177f1652b25fe0 Mon Sep 17 00:00:00 2001 From: at24_bioeng625-pc Date: Wed, 5 Aug 2026 15:59:40 +0100 Subject: [PATCH 3/3] docs: correct rounds-validation note and app-bundling claims MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Review of the new reference sections surfaced six inaccuracies, five of them in prose this branch adds. The invalid-rounds note claimed a discarded GLOBAL_ROUNDS or LOCAL_ROUNDS is replaced by the default of 1. That holds only for GLOBAL_ROUNDS, which the platform reads and writes into the server's job configuration. LOCAL_ROUNDS is read by the app's own trainer straight out of config.json, and configure_config fills in the default only when the key is absent — a key that is present but invalid is left as written and reaches the trainer verbatim, so the documented safety net does not exist for it. Also note the BEST_MODEL_METRIC exception, where a discarded GLOBAL_ROUNDS fails the job rather than defaulting, and that neither key is rewritten in the deployed config.json. 'Any additional file is bundled into the app' omitted two carve-outs: a model file colliding with a base-template name is skipped with only a server-side log line (which for Flower silently drops server_app.py, strategy.py and __init__.py — exactly what the Flower tutorials ship), and a checkpoint named by SERVER_CHECKPOINT or an evaluation job's models entries is staged server-side and never reaches a client. Drop 'pre-trained checkpoints' as an example of what gets shipped, since it is the case with the carve-out. 'Keys the platform does not recognise are passed through untouched' skipped three keys FLIP's own NVFLARE components do read: SERVER_CHECKPOINT, GLOBAL_ROUNDS_AE/GLOBAL_ROUNDS_DM and models. In the user guide, the same pass-through sentence sat under a both-backends bullet list but is backwards for Flower, where flwr rejects a run-config key the template does not declare instead of ignoring it. Scope it to NVFLARE. Finally, the page's own Disclaimer section still told Flower users to upload server_app.py (the template supplies it, and an uploaded copy is dropped) and listed evaluation among the job types taking trainer/validator/models/config. Both contradicted the new tables on the same page, so point that bullet at fl-required-files and remove the obsolete Flower one. Signed-off-by: at24_bioeng625-pc --- docs/source/components/component-fl-nodes.rst | 57 ++++++++++++++----- docs/source/user-guides/user-common.rst | 15 +++-- 2 files changed, 54 insertions(+), 18 deletions(-) diff --git a/docs/source/components/component-fl-nodes.rst b/docs/source/components/component-fl-nodes.rst index 9b35f23c0..31b98484a 100644 --- a/docs/source/components/component-fl-nodes.rst +++ b/docs/source/components/component-fl-nodes.rst @@ -148,8 +148,19 @@ page — so the UI, not this table, is what to trust if the two ever disagree. uploaded as a model file does not become the app's project file. Per-run overrides go in ``config.toml`` instead (see below). -Beyond the required set, any additional file uploaded with the model is bundled into the app, which -is how apps ship helper modules, transforms and pre-trained checkpoints. +Beyond the required set, additional files uploaded with the model are bundled into the app, which is +how apps ship helper modules and transforms. Two exceptions are worth knowing: + +- **A file whose name collides with one the base template already provides is silently dropped.** + The template's copy wins and the upload is skipped with only a server-side log line — no error + reaches the UI. For Flower this covers ``server_app.py``, ``strategy.py``, ``__init__.py`` and + ``pyproject.toml``, which matters in practice because the Flower tutorials ship the first three in + their app directories; for NVFLARE it covers whatever the chosen job type's template already + contains. +- **A checkpoint declared for server-side use is not shipped to the Trusts.** A file named by + ``SERVER_CHECKPOINT``, or by an evaluation job's ``models`` entries, is staged on the FL server + rather than placed in the app bundle, so it never travels to a client. This is deliberate: it + keeps large weights off the client deployment path. .. _fl-training-configuration: @@ -190,10 +201,24 @@ training settings. Every setting has a default, so an app that declares only ``j .. note:: - A ``GLOBAL_ROUNDS`` or ``LOCAL_ROUNDS`` value that is not a number, or that falls outside the - accepted range, does not fail the job — it is discarded and the default of 1 is used instead. - A single-round job is easy to mistake for a broken one, so check the value that reached the - job if training finishes sooner than expected. + A value that is not a number, or that falls outside the accepted range, is discarded rather + than reported. What happens next differs between the two keys, because the platform consumes + them differently. + + ``GLOBAL_ROUNDS`` is read by the platform and written into the server's job configuration, so + a discarded value really does produce a **one-round run**. A single-round job is easy to + mistake for a broken one, so check the value that reached the job if training finishes sooner + than expected. The exception is ``BEST_MODEL_METRIC``: because it requires at least two global + rounds, a discarded ``GLOBAL_ROUNDS`` fails the job outright instead of defaulting. + + ``LOCAL_ROUNDS`` is **not** read by the platform — it is read by your own trainer, straight out + of ``config.json``. The default of 1 is filled in only when the key is *absent*; a key that is + present but invalid is left exactly as written, so the value reaches your trainer verbatim. + ``"LOCAL_ROUNDS": 5000`` will run 5000 local iterations, and a non-numeric value will fail + inside your own code rather than at validation. + + Neither key is rewritten in the ``config.json`` deployed with the app, so app code that reads + ``GLOBAL_ROUNDS`` from that file sees the value you wrote, not the value the server is using. **IGNORE_RESULT_ERROR** Whether training should proceed when a client returns an error. @@ -240,11 +265,18 @@ training settings. Every setting has a default, so an app that declares only ``j *Default = unset, i.e. only the final model is saved* -Keys the platform does not recognise are passed through to the app untouched, for the uploaded code -to read at runtime. This is how the tutorials carry app-specific settings such as ``LEARNING_RATE`` -or ``VAL_SPLIT`` — those are conventions of individual apps, not platform settings, and they are -neither validated nor defaulted. A misspelled key of this kind is therefore silently absent at -runtime rather than reported as an error. +Three further keys are read by FLIP's own NVFLARE components rather than by the FL API's validator, +so they are unvalidated but are not simply passed through either: ``SERVER_CHECKPOINT`` (names a +model file to stage on the FL server instead of bundling it into the app — a string or a list of +strings), ``GLOBAL_ROUNDS_AE`` and ``GLOBAL_ROUNDS_DM`` (per-phase round counts for the two-phase +``diffusion_model`` job types, which bypass the range check applied to ``GLOBAL_ROUNDS``), and +``models`` (the checkpoints an evaluation job loads, each entry naming a ``checkpoint`` file). + +Any other key the platform does not recognise is passed through to the app untouched, for the +uploaded code to read at runtime. This is how the tutorials carry app-specific settings such as +``LEARNING_RATE`` or ``VAL_SPLIT`` — those are conventions of individual apps, not platform +settings, and they are neither validated nor defaulted. A misspelled key of this kind is therefore +silently absent at runtime rather than reported as an error. Flower run configuration ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -323,8 +355,7 @@ Disclaimer: some things are still under construction! There are currently some elements that are still under construction, and might not adjust exactly to the description above: -- for the Flower framework, users have to upload the `server_app.py` in addition to the `client_app.py` and additional auxiliary code, but in the future, this will not be the case. -- for the class-based NVFLARE job types (`standard`, `evaluation`, `fed_opt`, `diffusion_model`) the user upload is intentionally minimal — `trainer.py` / `validator.py` / `models.py` / `config.json` — and the rest of the app is filled in from +- for the class-based NVFLARE job types (``standard``, ``evaluation``, ``fed_opt``, ``diffusion_model``) the user upload is intentionally minimal — see :ref:`fl-required-files` for the per-job-type set — and the rest of the app is filled in from the static (non-modifiable) templates baked into the flip-api image at `FL_APP_BASE_DIR` (`fl-apps/`, see FLIP#724). These templates used to be published to an S3 bucket; that path has been removed. You can check what a fully bundled app looks like by consulting the per-job-type implementations under `fl-apps/ `_. diff --git a/docs/source/user-guides/user-common.rst b/docs/source/user-guides/user-common.rst index 900fdf83e..2abe90826 100644 --- a/docs/source/user-guides/user-common.rst +++ b/docs/source/user-guides/user-common.rst @@ -369,8 +369,11 @@ Both update as soon as you upload or replace ``config.json``, and training canno until every required file has been uploaded. Files beyond the required set may be uploaded freely — anything your code imports (helper modules, -transforms, pre-trained checkpoints) is bundled with the app and shipped to the participating -Trusts. +transforms) is bundled with the app and shipped to the participating Trusts. Two things do not +follow that rule: a file whose name matches one the platform's own app template supplies is quietly +dropped in favour of the template's copy, and a checkpoint declared for server-side use stays on the +FL server rather than travelling to the Trusts. Both are covered under +:ref:`fl-required-files` on the FL nodes component page. The full per-job-type file lists, and the configuration each backend accepts, are documented on the :ref:`FL nodes component page `. For worked examples of complete, working apps, @@ -443,9 +446,11 @@ Where that configuration lives, and which settings are available, depends on the - **Flower apps** take their run configuration from the platform's app template, which your app can override with a ``config.toml`` file. Flower apps do not use the NVFLARE keys. -Any key the platform does not recognise is passed through untouched, for your own code to read at -runtime — which is how the tutorials carry app-specific settings such as learning rate or -validation split. +For NVFLARE apps, any key the platform does not recognise is passed through untouched, for your own +code to read at runtime — which is how the tutorials carry app-specific settings such as learning +rate or validation split. Flower works the other way round: ``config.toml`` may only override keys +the app template already declares, and a key it does not declare fails the run at submission rather +than being ignored. Every platform-recognised key has a default, so an app that sets only ``job_type`` will still run. For the full list of keys, their accepted values and defaults per backend, see