Compétence : tao-run-deft-aoi

Quand utiliser cette compétence

Utilise cette compétence quand l'utilisateur veut qu'un agent exécute la boucle DEFT AOI complète pour un modèle NVIDIA TAO VisualChangeNet / ChangeNet d'inspection de circuits imprimés : évaluation de base, RCA, ingestion de défauts synthétiques pré-générés, extraction de données, ré-entraînement et gating de déploiement jusqu'à ce qu'une cible KPI soit atteinte. AnomalyGen n'est pas exécuté en ligne dans cette variante EA — le client pré-génère des paires NG/OK hors bande et les place sous <workspace>/augmentation/anomalygen/.

• « Exécute la boucle DEFT »
• « Affine jusqu'à FAR < 0,1 % au rappel=100 % »
• « Améliore mon modèle ChangeNet AOI en utilisant RCA et les défauts synthétiques »
• « Itère l'entraînement jusqu'à ce que le taux de faux acceptations atteigne la cible »

N'utilise pas cette compétence pour une seule exécution TAO autonome, une inférence unique, une génération d'anomalies générique ou une analyse RCA seule. Utilise l'agent pertinent directement quand l'utilisateur ne demande que cette étape.

Modèle de base

La boucle fonctionne sur NVIDIA TAO Visual ChangeNet classify avec le backbone NVIDIA C-RADIOv2-B, affiné de bout en bout. L'architecture est définie dans specs/baseline_spec.yaml — ce fichier est la source de vérité. Tous les poids pré-entraînés proviennent de HuggingFace (token HF_TOKEN requis) ; NGC_API_KEY_* gate uniquement les pulls de conteneurs. La résolution du backbone ChangeNet et le fallback fichier-temporaire/HF-URL pour model.backbone.pretrained_backbone_path sont gérés par references/visual-changenet.md. SigLIP pour l'extraction k-NN est géré par references/tao-mine-aoi-images.md. Aucun checkpoint du côté AnomalyGen n'est requis dans cette variante EA — les paires synthétiques pré-générées sont ingérées directement depuis <workspace>/augmentation/anomalygen/{reconstructed_image,original_image}/ ; voir l'étape Pipeline 3 dans references/pipeline.md.

Politique AutoML d'entraînement

DEFT AOI possède la boucle itérative d'amélioration des données, la cadence de ré-entraînement et la sélection des checkpoints KPI. Pour ce workflow uniquement, contourne AutoML au niveau du modèle même quand les métadonnées du modèle Visual ChangeNet sous-jacent ont automl_enabled: true. Invoque chaque étape d'entraînement Visual ChangeNet, y compris la base et le ré-entraînement itératif, avec l'override d'exécution automl_policy: off / entraînement simple. Ceci est uniquement un override au niveau du workflow ; ne modifie pas les métadonnées du modèle et n'applique pas cette politique à d'autres workflows.

Lancement de l'admission

Après que l'utilisateur confirme qu'il veut exécuter ce workflow, demande sur quelle plateforme prise en charge il compte s'exécuter. Génère les choix de plateforme avec :

${TAO_SKILL_BANK_PATH:-~/tao-skills-external}/scripts/list_tao_platforms.py \
  --skill-bank ${TAO_SKILL_BANK_PATH:-~/tao-skills-external} --format text

Après la sélection de la plateforme, exécute :

${TAO_SKILL_BANK_PATH:-~/tao-skills-external}/scripts/list_tao_platforms.py \
  --skill-bank ${TAO_SKILL_BANK_PATH:-~/tao-skills-external} \
  --platform <platform> --format text

Demande uniquement les identifiants pertinents pour cette plateforme, plus les identifiants spécifiques au modèle requis par le workflow sélectionné.

Comportement de l'agent

Il y a exactement une porte utilisateur : confirmation avant décollage. Affiche le résumé avant décollage (voir Résumé avant décollage dans references/pre-flight.md), puis STOP et attends que l'utilisateur tape « go », « yes », « looks good » ou une approbation explicite similaire. Ne lance aucune étape avec effets secondaires (docker run, entraînement, SDG, mutations sous ${RESULTS_DIR}/) avant cette approbation — la lecture de specs, l'énumération de fichiers, docker image inspect et le remplissage du tableau récapitulatif sont acceptables. « Autonome » décrit le comportement après cette porte, pas avant. Ne saute pas la porte même si le prompt original de l'utilisateur semblait urgent (« just run it », « go ahead ») — le résumé lui-même est l'artéfact qu'il doit voir avant approbation.

Après la porte, la compétence est entièrement autonome. Exécute la boucle complète sans demander de confirmation. Ne fais pas de pause entre les étapes. Ne demande pas « veux-tu que je continue ? » — continue simplement. Arrête-toi uniquement si une étape échoue avec une erreur irrécupérable ou si une porte hard-stop se déclenche. Affiche une mise à jour d'état d'une ligne à chaque étape clé pour que l'utilisateur puisse suivre la progression.

Workflow

Exécute la boucle dans cet ordre. Le détail complet se trouve dans les fichiers de référence cités par étape.

1. Avant décollage. Exécute tous les contrôles dans references/pre-flight.md. Résout l'espace de travail, les specs, les CSV, les checkpoints, les images conteneurs, étape la pool pré-gen une seule fois, et affiche le résumé avant décollage. Arrêt strict sur toute entrée manquante.
2. Baseline. Si deft_state.json a déjà iterations.baseline.stage_completed == "train" et une best_ckpt_path pointant vers un fichier existant (le tao-run-automl-deft-pipeline en amont pré-remplit ceux-ci à partir de son gagnant AutoML Phase 1 — voir son handoff Phase 1 → Phase 2), saute la sous-étape train et reprends à inference -> evaluate contre le checkpoint pré-rempli. Sinon, exécute train -> inference -> evaluate en invoquant la compétence tao-skill-bank:tao-train-visual-changenet. Dans les deux cas, puis rca en invoquant tao-skill-bank:tao-analyze-gaps-visual-changenet. Lis d'abord references/visual-changenet.md et references/tao-analyze-gaps-visual-changenet.md pour les args spécifiques à la boucle DEFT (montages, répertoires de sortie, mises à jour deft_state.json).
3. Itération. Pour chaque itération jusqu'à max_iterations, exécute les étapes Pipeline 1-7 dans references/pipeline.md. Entre chaque étape, relis la queue de results/loop_log.jsonl + results/deft_state.json depuis le disque — le disque est canonique.
4. Arrête quand la cible KPI est atteinte, max_iterations est atteint, ou une porte hard-stop se déclenche (silent-drop, désadéquation d'allocation AMP, fuite train/val). Ne réessaye jamais automatiquement les arrêts hard.
5. Rend results/DEFT_Loop_Report.html après chaque itération complétée (et une fois de plus à la fin de la boucle) en spawning du sous-agent reporter (agents/reporter.md). Les rendus par étape ne sont pas effectués — chaque étape ajoute déjà une ligne à loop_log.jsonl, ce qui suffit pour un utilisateur regardant la queue ; le rendu HTML porte l'état d'une itération et un rendu par itération maintient le coût en tokens par boucle approximativement linéaire en nombre d'itérations, pas en nombre d'étapes. Ne rend pas en ligne.

Toutes les étapes du pipeline s'exécutent en ligne dans le contexte parent — le parent invoque les compétences tao-skill-bank:* sous-jacentes directement via l'outil Skill, superposant les conventions de boucle DEFT via le fichier references/*.md correspondant. Le seul travail délégué est le rendu de rapport HTML, géré par le sous-agent reporter dans un contexte frais pour qu'un rendu de fin de boucle ne soit jamais silencieusement supprimé quand le contexte du parent est saturé.

Valeurs par défaut

Définies uniquement quand l'utilisateur ne les fournit pas ; ne pose jamais de question sur un paramètre ayant une valeur par défaut. Liste complète dans references/pre-flight.md.

• max_iterations: 3 — top_k_per_target: 5 — min_similarity: 0,9 (cutoff cosinus)
• racine d'espace de travail : prompt utilisateur, sinon ~/workspace

Carte de référence

Lis la référence pertinente au début de chaque étape, puis agis. Si un fichier de référence est manquant, arrête-toi et demande à l'utilisateur de réinstaller le plugin — ne substitue pas de commandes shell génériques.

Contrat de données

Entrées (tous les chemins sous <workspace> sauf s'ils sont absolus) :

<workspace>/
├── .env                                     # NGC_API_KEY (pulls d'images nvcr.io/*), HF_TOKEN (pulls HuggingFace avant décollage). Aucun identifiant AnomalyGen requis — cette variante EA ingère des paires pré-générées.
├── specs/baseline_spec.yaml                 # spec train/eval ChangeNet
├── train/base/
│   ├── training_set.csv                     # lignes d'entraînement de base ; schéma siamois ChangeNet 14-colonnes
│   └── validation_set.csv                   # lignes mises de côté ; contrôlées pour fuite contre tous les CSV train
├── kpi/
│   ├── images/                              # images test KPI (données réelles uniquement — pas d'images générées ici)
│   └── testing_set.csv                      # les étiquettes vivent dans le CSV
├── augmentation/
│   ├── mining_pool/
│   │   ├── mining_pool.csv                  # exemples append-only de la chaîne de production ; chemins relatifs à ce répertoire
│   │   └── images/                          # images source référencées par mining_pool.csv (ex. *_SolderLight.jpg)
│   └── anomalygen/                          # paires synthétiques pré-générées fourni par le client (cette variante EA n'exécute pas AnomalyGen)
│       ├── reconstructed_image/             # images NG (deviendront chemin ChangeNet input_path) ; répertoire plat de *.jpg ou *.png
│       ├── original_image/                  # images partner OK, mêmes stems que reconstructed_image/ (deviendront chemin ChangeNet golden_path)
│       └── defect_spec.jsonl                # OPTIONNEL — une entrée par defect_type si comptabilité de type de défaut souhaitée dans deft_state.json
│                                            # Les stems dans reconstructed_image/ et original_image/ doivent correspondre 1-à-1 ; les extensions peuvent différer.
└── results/run_<YYYYMMDD_HHMMSS>/           # créé/repris par ce workflow (= ${RESULTS_DIR})

Schéma CSV ChangeNet (VCN). Colonnes obligatoires : input_path, golden_path, label, object_name (changement siamois détecteur — une ligne sans golden_path est inutilisable). Préserve boardname, scores et champs de provenance quand présents. TAO construit le chemin image complet comme {images_dir}/{input_path}/{object_name}_{light}{image_ext} — input_path est un répertoire, pas un fichier.

Disposition de sortie

Relative à <workspace> :

results/run_<YYYYMMDD_HHMMSS>/               # = ${RESULTS_DIR}
├── deft_state.json                          # snapshot de reprise courant (schéma : references/deft_state.json)
├── loop_log.jsonl                           # journal d'étape append-only ; source de vérité unique
├── DEFT_Loop_Report.html                    # re-rendu après chaque étape par agents/reporter.md
├── best_model.json                          # métadonnées handoff inférence (voir references/prepare-for-inference.md)
├── best_model_inference_spec.yaml           # spec TAO inférence prête à l'exécution construite depuis config d'entraînement
├── iter${ITER}_summary.md                   # ≤300-mots résumé par itération
├── synth_pool/                              # construit UNE SEULE FOIS à l'étape avant décollage 10 via scripts/prestage_pregen.py
│   ├── manifest.json                        # chemins + comptages pour la boucle à référencer
│   ├── images/synth_{ng,ok}/                # paires pré-gen ChangeNet-mises en étapes (copie unique, partagée entre itérations)
│   ├── sdg_rows.csv                         # 14-col + provenance + chemin ; la moitié SDG de source_pool
│   ├── source_pool.{csv,parquet}            # pool unifié réel (mining_pool) + sdg avec provenance
│   ├── source_embeddings.parquet            # écrit uniquement quand --embed-with-siglip a été passé à prestage_pregen.py
│   └── source_embed.log                     # log data-services pour l'embedding source (si exécuté)
├── baseline/
│   ├── train/                               # sortie TAO train : model_epoch_<EEE>_step_<SSS>.pth × N, status.json, experiment.yaml, train.log
│   ├── inference/{best_val,latest}/         # inference.csv par checkpoint + tracés KPI depuis scripts/analyze_kpi.py
│   └── rca_results/<TS>/                    # kpi_gaps.parquet, threshold.txt, weak_samples_breakdown.txt
└── iter${ITER}/
    ├── routing_results/<TS>/                # mining_gaps.parquet, anomalygen_gaps.parquet, routing_summary.txt
    ├── anomalygen/                          # comptabilité par itération (enregistre juste le chemin synth_pool/manifest.json)
    │   └── ingest_summary.json              # audit par itération : quel manifeste synth_pool a été réutilisé, comptages au démarrage itération
    ├── mining_filter/
    │   ├── mining_pool.csv                  # survivants k-NN top-K-par-cible depuis synth_pool/source_pool (synth + réel soumis à même filtre)
    │   ├── knn_summary.csv                  # candidate_count, kept_count, rejected_count, similarity_threshold=0,9
    │   ├── target_embeddings.parquet        # embeddings d'images faibles-cibles (par itération — cibles changent chaque itération)
    │   └── mining_summary.txt               # ventilation par étiquette émise par conteneur extraction
    ├── dataset/
    │   ├── train_combined_iter${ITER}.csv
    │   └── train_combined_iter${ITER}_provenance.csv  # source ∈ {base_train, previous_iter_train, mining_pool}
    ├── train/                               # sortie TAO train pour iter${ITER}
    ├── inference/{best_val,latest}/
    └── rca_results/<TS>/                    # RCA de l'itération suivante lit inference/{best_val|latest}/inference.csv

Les lignes d'un CSV combiné précédent incluent déjà chaque contribution antérieure — assemble itération N+1 depuis train_combined_iter${N}.csv plus le nouveau mining_filter/mining_pool.csv, pas depuis train/base/training_set.csv à nouveau.

Sécurité et gating

• Une seule porte utilisateur. Le résumé avant décollage dans references/pre-flight.md est le seul point de confirmation. Arrête-toi et attends l'approbation explicite avant toute étape avec effets secondaires ; autonome après.
• Règle de chemin. Chaque étape écrit des chemins hôte absolus sous ${RESULTS_DIR}/iter${ITER}/ ; rejette toute config avec output: /results/... ou tout chemin en dehors de <workspace>. Voir Invariants dans references/stage-execution.md.
• Le disque est canonique. Relis la queue de loop_log.jsonl + deft_state.json avant chaque étape ; ajoute exactement une entrée loop_log.jsonl par étape via scripts/log_stage.py (jamais echo/inline jq). Voir references/state-logging.md.
• Arrêts hard, jamais auto-réessayés : répertoires pré-gen manquants/vides/non appairés, mining_pool.csv manquant ou zéro-ligne, mutation pré-gen en cours de cycle, fuite train/val (vérifications mid-itération et post-assemblage), silent-drop, désadéquation d'allocation AMP, validation CSV échouée, fichier de référence manquant.
• Pas de bypass SDG. Les lignes synthétiques passent par le même k-NN que les lignes réelles ; la boucle ne lance jamais de conteneur SDG/AnomalyGen dans cette variante EA.