kermt-infer

Exécuter des prédictions avec un checkpoint KERMT finalisé sur un CSV contenant uniquement des SMILES. La skill est l'orchestrateur du workflow : valider le ckpt, valider le CSV, préparer les données, lancer le runner de façon bloquante, retourner le CSV des prédictions.

Chemins de la skill et du runtime

Définir SKILL_DIR sur le chemin absolu du répertoire de cette skill installée. Exporter KERMT_REPO comme le chemin absolu vers le checkout KERMT utilisé pour l'exécution du modèle. Le helper de conteneur fourni monte ce checkout à /workspace et cette skill à /skill (lecture seule). Les commandes à l'intérieur du conteneur utilisent /skill/scripts/; les valeurs par défaut sont fournies dans config/.

Exigences matérielles

GPUs : 1 (single-GPU). L'inférence multi-GPU n'est actuellement pas supportée.
VRAM : ≥ 4 GB pour le batch_size 32 par défaut.
Disque : quelques centaines de MB par exécution (CSV nettoyé + features + prédictions).
Driver / CUDA : tout hôte supportant CUDA 12.6 (la base de l'image kermt).

Entrées

Obligatoires :

--ckpt <path> — checkpoint finalisé (doit avoir des heads FFN de tâche). Le validateur refuse les ckpts pretrain avec une redirection vers kermt-finetune.
--csv <path> — CSV contenant uniquement des SMILES. La première colonne est smiles; les autres colonnes sont ignorées.

Optionnels :

--batch-size N — remplacer la valeur par défaut configurée (32).
--seed N — seed aléatoire pour l'inférence (chemins de featurization déterministes).
--gpus 0 — id GPU unique (par défaut 0). Multi-GPU rejeté.
--from-prepare <dir> — ignorer l'étape de préparation et réutiliser un prepare_data.json existant dans <dir>.

Workflow

Soit $KERMT_REPO le chemin vers votre checkout du repo kermt, et supposons que kermt-setup a construit kermt:latest.

Pré-vol : vérifier le conteneur + sonde système.
```
"$SKILL_DIR/scripts/kermt_container.sh" check_system
```
Refuser de continuer si ok: false.

Calculer le répertoire d'exécution.

RUN_DIR=$KERMT_REPO/runs/infer_$(date -u +%Y-%m-%dT%H-%M-%SZ)

Valider le checkpoint.
```
"$SKILL_DIR/scripts/kermt_container.sh" run --ckpt <user-ckpt> -- \
    "python /skill/scripts/check_checkpoint.py --mode inference --ckpt /ckpt"
```
Analyser le JSON. Abandonner si ok: false. Le validateur refuse les ckpts pretrain (has_task_ffn: false) avec une redirection vers kermt-finetune.

Valider les données.

"$SKILL_DIR/scripts/kermt_container.sh" run --data <user-csv> -- \
    "python /skill/scripts/check_data.py --mode inference --csv /data/<basename>"

Abandonner si ok: false.

Préparer les données.

"$SKILL_DIR/scripts/kermt_container.sh" run --data <user-csv> --run-dir $RUN_DIR -- \
    "python /skill/scripts/prepare_data.py --mode inference \\
         --csv /data/<basename> --out /runs/data"

Les sorties aboutissent à $RUN_DIR/data/prepare_data.json avec les chemins clean_csv + clean_npz (features rdkit_2d_normalized).

Lancer le runner (bloquant).

"$SKILL_DIR/scripts/kermt_container.sh" run \\
    --ckpt <user-ckpt> --run-dir $RUN_DIR -- \\
    "python /skill/scripts/run_inference.py \\
         --ckpt /ckpt \\
         --prepare-manifest /runs/data/prepare_data.json \\
         --out /runs \\
         [--gpus 0 --batch-size N --seed N]"

Retourne le chemin du CSV de prédictions en cas de succès.

Rapporter à l'utilisateur. Afficher un court résumé :
- Prédictions : $RUN_DIR/out/predictions.csv (smiles + colonnes par cible)
- Manifest : $RUN_DIR/run.json (cmd_replay + digest image + args appliqués)
- Log : $RUN_DIR/logs/inference.log
- Nombre de lignes : <N> molécules prédites sur <K> cibles

Règles immuables

Ne jamais modifier le ckpt de l'utilisateur. Le runner crée un symlink du ckpt vers un sous-répertoire unique <out>/ckpt_link/ afin que main.py predict --checkpoint_dir le trouve; le fichier source reste inchangé.
L'architecture provient du ckpt, jamais de la CLI/defaults. Le runner enregistre le bloc architecture du validateur dans run.json mais ne passe pas de flags architecture dans main.py predict — predict les lit à partir des saved_args du ckpt chargé.
Single-GPU uniquement. L'inférence multi-GPU n'est actuellement pas supportée.
Afficher les valeurs par défaut appliquées. Le champ args_applied de run.json enregistre la valeur de chaque flag + source (user / default-config). Afficher un court résumé de tout flag rempli par défaut.

Erreurs courantes

inference requires a finetuned ckpt with task FFN heads → le ckpt est un ckpt pretrain; utiliser kermt-finetune d'abord.
prepare_data manifest reports ok=False → vérifier le manifest errors pour l'étape échouée (généralement clean_smiles ou save_features).
could not convert string to float: '<value>' depuis save_features ou main.py predict → le CSV d'entrée a une colonne non-numérique passthrough (ex. un label 'split'). L'étape de préparation réduit désormais le CSV à SMILES-only à l'inférence; si cette erreur réapparaît, le CSV est lu par un runner qui a contourné prepare_data. Relancer via la skill, pas main.py directement.
--gpus '0,1' is single-GPU only → passer un seul id.

Reproductibilité

Le champ cmd_replay de run.json est une commande d'une seule ligne qui relance l'inférence avec les mêmes entrées. Pour rejouer à l'intérieur du conteneur kermt :

$(jq -r .cmd_replay $RUN_DIR/run.json)

Si ok_to_replay: false (arborescence kermt repo sale au lancement), épingler le commit via repo.commit et git checkout d'abord.