Virtualenv — exécution locale Python sans docker

Installation autonome ? Si cette session n'a pas été initialisée par le plugin skill bank TAO, exécutez d'abord le skill tao-setup (vérification préalable de l'hôte, identifiants, découverte inter-skills).

La plateforme virtualenv exécute un script Python nativement dans un venv existant — en tant que vecteur argv dont le premier élément est <venv>/bin/python, jamais via un shell, jamais en activant quoi que ce soit. Le runner fourni (references/virtualenv_runner.py) est le « CLI natif » de cette plateforme — le rôle que jouent docker/kubectl/sbatch ailleurs — et contrôle uniquement le cycle de vie du processus. Les enregistrements de job restent avec tao_job_record.py ; les specs sont rédigées par l'agent, exactement comme sur toute autre plateforme.

Quand l'utiliser

• La charge de travail est un script Python simple (ses dépendances installées avec pip dans un venv), pas une action container TAO.
• Pas de docker sur l'hôte, ou le coût de démarrage du conteneur ne le justifie pas (tests rapides, boucles AutoML sur modèles légers).
• Un seul nœud. Pour les actions container TAO, utilisez tao-run-on-docker ; pour les clusters, utilisez -slurm / -kubernetes.

Vérification préalable

# 1. Le venv est réel et possède un interpréteur exécutable.
[ -f "$VENV/pyvenv.cfg" ] && [ -x "$VENV/bin/python" ] || echo "MISSING: $VENV is not a venv"
# 2. Les imports de niveau supérieur du script se résolvent dedans (détecte le mauvais venv tôt) ;
#    remplacez par les vrais modules que votre script importe.
"$VENV/bin/python" -c "import torch" || echo "MISSING: script dependency not in $VENV"
# 3. Visibilité GPU seulement si le script a besoin de CUDA.
nvidia-smi >/dev/null 2>&1 || echo "note: no GPU visible (fine for CPU scripts)"

Aucune identifiant n'est requis par la plateforme elle-même ; les variables d'environnement spécifiques au modèle (ex. HF_TOKEN) passent par NOM avec -e (les valeurs ne se retrouvent jamais sur argv).

Stockage

Tier A par définition — tout est des chemins locaux. Les datasets doivent déjà être sur le disque local (préparez-les avec tao-data-io s'ils sont dans S3). Les sorties se retrouvent dans le results_dir de l'enregistrement de job, qui EST le --job-dir du runner.

Exécution — les quatre verbes

$BANK = ${TAO_SKILL_BANK_PATH} ; $RUNNER = $BANK/skills/platform/tao-run-on-virtualenv/references/virtualenv_runner.py.

submit

1. Rédigez la spec (si le script en prend une) à un chemin local — dicts imbriqués, jamais clés pointées plates — et validez la commande assemblée avec redact_secrets.py lint.
2. Ouvrez l'enregistrement — génère l'id, associe results_dir AVANT le lancement :

   JOB_ID=$("$BANK/scripts/tao_job_record.py" open --platform virtualenv \
     --image "$VENV/bin/python" --network-arch "$ARCH" --action "$ACTION" \
     --storage-tier A --results-root "$RESULTS_ROOT")
   RESULTS_DIR="$RESULTS_ROOT/$JOB_ID"

3. Lancez en détaché (le runner écrit un wrapper durable qui gère le démarrage, enregistre l'identité et nettoie le groupe de processus à la sortie) :

   set -a; source /path/to/.env; set +a   # omit if already exported
   python3 "$RUNNER" submit --job-dir "$RESULTS_DIR" --venv "$VENV" \
     --script train.py --job-id "$JOB_ID" --config-path "$SPEC" \
     --arg train --arg=--config={config_path} --arg=--out={results_dir} \
     --gpu-ids 0 -e HF_TOKEN

   Les placeholders {config_path} {results_dir} {job_id} se rendent à l'intérieur des jetons --arg. Un jeton commençant par - doit utiliser la forme --arg=TOKEN (argparse). --gpu-ids définit CUDA_VISIBLE_DEVICES ; --gpus 0 cache les GPUs ; ni l'un ni l'autre ne réserve rien.

4. Enregistrez RUNNING avec le pid que le runner a imprimé :

   "$BANK/scripts/tao_job_record.py" mark "$JOB_ID" --state RUNNING --backend-ref "pid:<pid>"

Un submit par job dir — une retry obtient un NOUVEL enregistrement (--retry-of), jamais un re-submit dans le même dir.

status

python3 "$RUNNER" status --job-dir "$RESULTS_DIR"   # {"status": "...", ...}

Imprime directement le vocabulaire fixe : PENDING RUNNING COMPLETE ERROR CANCELED UNKNOWN — aucune table de mapping nécessaire. Le statut est dérivé de fichiers durables (exit_status.json, identité du launcher) et peut être sondé en toute sécurité depuis n'importe quel processus, à tout moment, y compris après redémarrages de l'agent de polling. Sur un statut terminal, mark l'enregistrement.

logs

python3 "$RUNNER" logs --job-dir "$RESULTS_DIR" --tail 200

cancel

python3 "$RUNNER" cancel --job-dir "$RESULTS_DIR"
"$BANK/scripts/tao_job_record.py" mark "$JOB_ID" --state CANCELED --source agent

Cancel marque d'abord (un wrapper pas encore démarré s'auto-annule à sa porte de démarrage), vérifie l'identité du processus (ne tue jamais un PID réutilisé), puis SIGTERM→SIGKILLs le groupe de processus entier. already_terminal dans la réponse signifie que le job s'est terminé avant l'annulation — marquez l'enregistrement avec le statut qu'il rapporte à la place.

Mises en garde de la plateforme

• Linux première classe. L'identité et le nettoyage de groupe utilisent /proc ; sur macOS le runner bascule à ps/pgrep — correct pour les tests locaux, mais les cibles d'entraînement GPU visent les hôtes Linux.
• Pas de multi-nœud, pas de résolution d'image — il n'y a pas de conteneur. L'« image » enregistrée est le chemin de l'interpréteur du venv.
• Le runner ne télécharge jamais rien. Les entrées distantes sont le travail de l'agent de préparer d'abord (tao-data-io).