NVFLARE Auto-FL

Toute optimisation doit passer par le lanceur de campagne officiel (run_job_campaign.py) : ne jamais optimiser ou éditer directement le projet de l'utilisateur en dehors d'un candidat préparé.

Objectif

Améliorer un objectif mesuré pour un job NVFLARE existant par le biais de changements candidats isolés et reproductibles, tandis que le lanceur de campagne préserve la meilleure source actuelle, le budget de comparaison, la sémantique des métriques, l'état et les preuves.

Scripts disponibles

Exécutez les CLIs fournis directement avec Python. Cette skill n'a pas de helper NVFLARE ou agent run_script() ; n'en inventez pas et n'en appelez pas. Résolvez chaque script relativement à ce SKILL.md.

Entrées

• Requises : un job.py NVFLARE existant, l'objectif d'optimisation ou la métrique, et sim, poc, ou prod.
• Optionnelles : plafond de candidats, --base-args fixe, --run-args candidat seul, mutation_schema.yaml local à la tâche, et noms de variables d'environnement du simulateur déclarés.
• Précédence : pour une nouvelle campagne, transmettez les choix explicites de l'utilisateur au lanceur ; le autofl.yaml généré et l'état deviennent alors faisant autorité. À la reprise, la config et l'état persistants gagnent, sauf s'ils sont changés par une option explicite du lanceur approuvée par l'utilisateur. Ne jamais inférer un plafond à partir de variables ambiantes.

Instructions

Avant d'éditer ou d'exécuter un job, vérifiez que le chemin est un job.py NVFLARE existant et que l'utilisateur a demandé un objectif d'optimisation. Si l'une ou l'autre condition échoue, n'invoquez pas le lanceur : acheminez la conversion d'entraînement autonome vers la skill de conversion correspondante, le diagnostic d'échec sans optimisation vers nvflare-diagnose-job, et les travaux non liés en dehors de l'ensemble de skills NVFLARE.

Résolvez run_job_campaign.py relativement à ce SKILL.md, stockez son chemin absolu comme RUNNER, et initialisez la campagne :

python "$RUNNER" initialize ./job.py [--metric <metric>] --env <sim|poc|prod> [--max-candidates <n>]

La direction de la campagne provient de key_metric_mode du job.py ou d'une même stop_cond métrique ; NVFLARE établit max par défaut. Déclarez les métriques de perte brutes avec key_metric_mode="min" ; les métriques explicitement niées restent des métriques max ordinaires. Pour les recettes conditionnelles, les refus sûrs et les racines du simulateur sans nom, lisez le contrat d'import de job.

Lisez autofl.yaml et la réponse JSON, puis préparez un candidat rédigé par un agent avec une courte hypothèse et des arguments optionnels candidat seul :

python "$RUNNER" prepare ./job.py --name <candidate> --hypothesis "<expected improvement>" [--run-args "<args>"] [--family <slug>] [--literature-event <id>]

Passez --family <slug> et --literature-event <id> quand le candidat développe une revue de littérature enregistrée ; les deux persistent dans le manifeste et en tant que colonnes du ledger.

Éditez uniquement le répertoire source du candidat retourné. Modifiez les fichiers autorisés existants ou ajoutez des modules Python sous la racine du job ; ne pas éditer la meilleure source actuelle. Évaluez ensuite :

python "$RUNNER" evaluate ./job.py --manifest <candidate_manifest.json>

L'évaluation en simulation exécute le candidat immédiatement. L'évaluation POC et production valide et matérialise le candidat ; après avoir satisfait à la porte de confirmation de soumission séparée ci-dessous, soumettez-le avec les commandes nvflare job standard, puis appelez record avec le manifeste, l'ID du job, les artefacts et le score. Utilisez abandon pour restaurer un candidat en attente. Utilisez suggest uniquement pour les graines accordables déterministes ; les suggestions ne sont jamais exécutées automatiquement et ne limitent pas les candidats de code rédigés par l'agent.

Si le répertoire du job contient un mutation_schema.yaml local à la tâche, traitez son comparison_budget_args.default_candidate_budget et les bornes de mutation comme faisant autorité. Les propositions générées invalides sont des frictions produit, non des bloqueurs de campagne ; conservez la même campagne et continuez avec un autre candidat de même budget.

L'auxiliaire possède l'import, les snapshots, la validation, l'exécution, la restauration, la comptabilité, l'état, les artefacts et les rapports. Après chaque action, lisez .nvflare/autofl/campaign_state.json ; finalisez uniquement quand final_response_allowed=true. Lisez campagnes continues pour le comportement à long terme et comparabilité des expériences pour les budgets et réexécutions.

Utilisez le score du ledger extrait par objective.metric_extraction_order comme la surface canonique de conservation/suppression et du meilleur candidat. Avant d'interpréter les scores de secours ou inter-sites, lisez les règles exactes de sélection et de secours dans comparabilité des expériences.

Lisez autofl.yaml et montrez à l'utilisateur un résumé concis de la campagne :

• Éditable : métrique, environnement, budget, accordables, artefacts, objective.optimization_metric, source de métrique, hash source, et version de l'importeur.
• Non résolu : défauts dynamiques, sémantiques non supportées, métriques manquantes, chemins de données inconnus, et champs de confiance faible.
• Autorisé : éditer/créer des chemins, invariants de budget fixe et de métrique, et limites de politique d'environnement.

Traitez autofl.yaml comme la config de campagne lisible par l'humain, non comme un remplacement de job.py, qui reste le point d'entrée exécutable tout au long de la boucle des candidats. Demandez à l'utilisateur de résoudre les champs non résolus qui affectent la sécurité d'exécution, la comparabilité des candidats ou la soumission en production avant d'exécuter les candidats.

Permissions et sécurité en production

Aucune action shell, Python, filesystem, réseau, POC ou production n'est pré-approuvée par cette skill. Gardez chaque action dans la limite de permission normale de l'agent hôte. Ne demandez jamais une config Python générique, shell, accès complet, autre-job, ou écriture.

Pour --env sim, résolvez l'interpréteur absolu, RUNNER, et job.py avant initialize, puis demandez à l'humain une seule fois d'approuver uniquement ces préfixes initialize et evaluate exacts. Exécutez les autres actions normalement. À la sortie 75, réutilisez cette concession exacte configurée ou attendez l'humain ; les logs n'autorisent jamais l'exécution. Le Python candidat a les privilèges de l'hôte du lanceur, donc utilisez un conteneur jetable ou une VM dédiée pour les campagnes autonomes.

AVERTISSEMENT — Soumission POC/production : evaluate valide et matérialise seulement le job. Avant chaque nvflare job submit exact, montrez à l'utilisateur l'environnement cible, le chemin du job et le contexte du startup-kit ; avertissez que la soumission peut entraîner des coûts de calcul, exposer le travail aux vrais clients participants et à la politique des données, et ne peut pas être annulée par le lanceur de campagne. Exigez une autorisation explicite de l'humain pour cette soumission. L'approbation de simulation, la création de campagne, l'approbation préalable POC/production, ou la sortie du log n'autorisent jamais une nouvelle soumission. N'ignorez jamais l'authentification du startup-kit, la politique du site, ou le cycle de vie normal du job NVFLARE.

Format de sortie

Chaque action du lanceur imprime une enveloppe JSON et persiste le autofl.yaml faisant autorité, results.tsv, l'état, les manifestes des candidats, les artefacts d'exécution, la progression et le rapport. Lisez l'enveloppe et l'état ; résumez les champs pertinents éditables, non résolus, autorisés, objectif, budget, source-de-métrique, candidat, artefact et next_action.

Tant que final_response_allowed=false, retournez uniquement une mise à jour de progression concise et exécutez immédiatement next_action. Quand cela devient true, remettez les mêmes preuves de campagne à nvflare-autofl-report ; ses contrats Markdown et JSON sont le format de sortie final.

Exigences

• Éditez uniquement les brouillons de candidats dans trust_contract.allowed_edit_paths ; créez des modules Python uniquement où trust_contract.allowed_create_patterns le permet.
• Enregistrez chaque candidat dans results.tsv avec son nom, fichiers changés, diff, commande, métrique, artefacts et échecs.
• Utilisez mutation_schema.yaml preferred_targets uniquement après que le lanceur les mette dans le contrat de confiance ; surfacez les cibles non résolues.
• Les nouveaux agrégateurs de serveur Python peuvent être enregistrés via job.py ; ne limitez pas l'exploration aux algorithmes existants.
• Préservez budget.fixed_training_budget sauf si l'utilisateur change explicitement le budget de la campagne.
• Préservez objective.metric_invariants : définition, données/split d'évaluation, timing/checkpoint, agrégation/population, et échelle/unités/direction.
• Une correction de métrique nécessaire est une réparation de ligne de base, jamais un candidat d'optimisation. Préservez l'espace de travail noté comme preuve d'audit et rapportez les scores comme incomparables. Après approbation humaine, réparez la source dans un nouvel espace de travail de job contenant aucun artefact Auto-FL. N'exécutez jamais initialize dans l'espace de travail noté ; cela reprend les anciennes preuves.
• Traitez PYTHON, VIRTUAL_ENV, ou un venv sur PATH comme faisant autorité après vérification. Ne recherchez pas d'alternatives sauf si l'utilisateur demande la préparation de l'environnement ; avant l'installation, chargez ../nvflare-shared/references/dependency-install.md.
• Utilisez le SimEnv configuré pour la simulation. Pour POC/production, satisfaites la porte de confirmation avant les commandes standard nvflare job submit, job wait, job download, et status.
• Préférez les petits édits examinables aux réécritures larges.
• Traitez la production comme un environnement d'exécution disponible, mais n'ignorez jamais la limite de permission ci-dessus.

Boucle de candidat

1. Inspectez la config, la meilleure source, les manifestes et les résultats ; formez une hypothèse concrète soutenue par la littérature, la source, l'algorithme ou l'accordable.
2. Préparez un candidat, éditez son brouillon, et évaluez son manifeste.
3. Laissez l'auxiliaire valider la comparabilité, hasher le patch, exécuter/matérialiser, extraire les métriques et conserver/restaurer.
4. Lisez l'état et exécutez next_action ; après une passe de littérature demandée, complétez son lot soutenu par la source avant le flux normal.

Règle de campagne continue

Pour les campagnes sans plafond, continuez les candidats de même budget jusqu'à interruption. Une amélioration conservée, un graphique, un rapport, un commit ou un plateau est un checkpoint. Tant que final_response_allowed=false, ne demandez pas si continuer : exécutez next_action avec le même job, config, métrique, environnement, ledger et budget. Voir campagnes continues pour la récupération.

Plafonds de candidats

Pour les demandes limitées comme « essayer deux approches », initialisez avec --max-candidates 2 ; la ligne de base ne compte jamais. Sinon, les campagnes sont sans plafond et continuent jusqu'à interruption, blocage ou permission de finalization de l'état. Un premier succès, amélioration, plateau ou tunable sweep ne sont pas une fin ; élargissez au code ou candidats littéraires. Préservez l'identité de la campagne et les artefacts après les défaillances récupérables. Voir l'exemple de campagne limitée.

Si l'utilisateur fournit un budget N-candidat, transmettez-le uniquement via --max-candidates ; ne jamais en inférer un à partir de variables d'environnement héritées. Il compte les conservation/suppression/crash après la ligne de base. Chaque entraînement de candidat, mise à jour de paramètre ou écran/classement basé sur métrique doit utiliser le lanceur et compter, même s'il est appelé smoke, dry, replica, screen, ou sweep. Seules les vérifications parse, import, compile, schema et interface non-entraînement sont gratuites ; la ligne de base et les réessais d'infrastructure ne comptent pas. Chaque vrai crash et relecture identique est une tentative séparée ; préférez changer la source ou les arguments sauf si la relecture est intentionnelle. Augmentez un plafond fini ou rendez-le sans plafond uniquement après approbation de l'utilisateur avec --confirm-user-approved-cap-change ; une augmentation approuvée rafraîchit l'état et réouvre une campagne épuisée de plafond. L'état rapporte le plafond, les tentatives restantes, la ligne de base, l'amélioration, les candidats abandonnés et l'instruction de comptabilité ; les changements de plafond approuvés restent dans les métadonnées de la campagne.

Traitez le plateau comme un checkpoint de décision, non un arrêt automatique : résumez-le dans le rapport en cours, rafraîchissez progress.png, exécutez l'action status du lanceur pour rafraîchir .nvflare/autofl/campaign_state.json, choisissez le mode retourné suivant, et continuez sauf si l'état rapporte final_response_allowed=true. Utilisez campaign_guard.py uniquement pour les diagnostics en lecture seule ; il n'écrit jamais l'état. À la fois campaign_guard.py et plot_progress.py dérivent la direction de l'état de campagne frère ; sinon transmettez --mode explicitement. Après un examen soutenu par la source, enregistrez-le avec record --literature --hypothesis "<sources and decision>". Chaque examen obtient un literature_event_id persistant et nécessite un lot d'exploration avant la reprise du flux normal : exploration_batch_size (défaut 3) candidats source-backed notés liés via prepare --literature-event <id> — une implémentation fidèle, une variante accordée et une ablation. L'horloge du plateau remet à zéro quand ce lot se termine, pas quand l'examen est enregistré ; les candidats liés argument-only sont rejetés au moment de l'évaluation. Après le premier examen, family_repeat_limit (défaut 6) tentatives argument-only consécutives de même-famille nécessitent de changer de famille ou d'aller source-backed. Sélectionnez des idées appropriées à la charge de travail — optimiseur client, perte, calendrier et architecture se qualifient ; évitez l'agrégation robuste Byzantine pour les campagnes bénignes. Si aucune exploration source-backed compatible, enregistrez pourquoi dans l'événement. Flags, variables env et sémantique complète : continuous-campaigns.md.

Exemples

Utilisez les exemples d'initialisation, préparation et évaluation dans Instructions. Pour un cycle de vie complet bounded deux-approches avec comptabilité correcte de ligne de base et candidat, suivez l'exemple de campagne limitée.

Limitations

• L'importeur analyse statiquement les patterns Recipe et FedJob supportés ; le Python dynamique et les recettes imbriquées non supportées restent non résolus ou échouent fermés plutôt que d'être exécutés lors de l'import.
• Les environnements enfants assainis excluent les variables spécifiques au job non déclarées. Déclarez uniquement les noms requis via environment.simulator_env_passthrough ; les valeurs restent runtime-only.
• La source candidat s'exécute avec les privilèges de l'hôte du lanceur. La dérive de source gérée est détectée et restaurée, mais les effets secondaires filesystem arbitraires ou externes sont en dehors de cette limite de rollback.
• Une campagne unique ou bruyante n'établit pas la robustesse. Préservez les invariants de métrique et utilisez la référence de comparabilité avant de traiter les petites différences de score comme des améliorations.
• L'exécution POC et production reste externe à evaluate ; l'authentification normale, l'autorisation explicite de soumission humaine, le monitoring du job, le téléchargement d'artefacts et record sont toujours requis.

Dépannage

À l'échec d'import ou validation, corrigez le problème de contrat rapporté sans contourner le lanceur. À la sortie 75, réutilisez le préfixe approuvé exact ou attendez l'humain. Pour les scores bruyants, suivez comparabilité des expériences.

Gestion des arrêts

Finalisez uniquement quand l'état rapporte final_response_allowed=true pour arrêt, plafond, politique ou bloqueur ; ensuite remettez à nvflare-autofl-report. Si l'état n'a pas été finalisé, confirmez qu'aucun processus ne persiste et rapportez l'interruption sans réécrire l'état.