tao-artifacts

Quatre artefacts typés circulent dans chaque job TAO. Leurs schémas vivent ici et nulle part ailleurs — les producteurs (skills modèle/données) et les consommateurs (skills plateforme) valident tous deux contre la references/ de ce skill.

Démarrage rapide — valider un artefact

python - <<'PY'
import json, yaml, jsonschema, pathlib
ref = pathlib.Path("${TAO_SKILL_BANK_PATH:?}/skills/core/tao-artifacts/references")
schema = json.loads((ref / "spec_bundle.schema.json").read_text())
bundle = yaml.safe_load(open("/path/to/bundle.yaml"))   # ou un dict construit en contexte
jsonschema.validate(bundle, schema)                      # lève une exception en cas de violation
print("bundle OK")
PY

Validez le bundle avant la gate verify-before-launch ; validez un job-record seulement lors du débogage (le script rédacteur applique déjà le schéma).

Les deux règles que les schémas appliquent structurellement

1. Imbriqué, pas pointé. Un spec est un dict imbriqué qui reflète la forme de la config du conteneur — {"train": {"num_epochs": 12}}. Toute clé contenant . à n'importe quelle profondeur est rejetée ({"train.num_epochs": 12} est l'erreur d'authoring #1). Notez la distinction : declared_inputs[].spec_key et gpu_spec_key sont des pointeurs pointés/indexés dans le spec (dataset.train_data_sources[0].image_dir) — les points y sont corrects.
2. Discrimination de mode. mode: config nécessite spec + config_format et une command contenant {config_path}, et interdit args. mode: args nécessite args et interdit spec. Il n'y a pas d'autre mode.

Cycle de vie optionnel des actions

Utilisez execution quand une action nécessite plus que sa commande principale. C'est la couture partagée modèle-vers-plateforme ; n'ajoutez pas un renderer Docker, Kubernetes ou SLURM spécifique au modèle juste pour porter l'environnement d'exécution, les attestations, le post-traitement ou les dépendances assistantes.

• Le skill modèle/données producteur possède environment, les pre_commands ordonnés, les post_commands ordonnés, l'intent de lancement distribué et la preuve d'achèvement.
• La plateforme possède les montages de conteneurs, la syntaxe scheduler/conteneur, la liaison tâche/rang, les timeouts, les chemins de logs et la préservation du vrai code de sortie enfant.
• environment n'est pas secret. Les valeurs de credentials continuent à utiliser le contrat secret/sidecar de la plateforme sélectionnée et n'entrent jamais dans un spec-bundle.
• Les commandes, les valeurs d'environnement et les valeurs string dans spec peuvent utiliser {config_path}, {job_id} et {results_dir}. La plateforme les lie seulement après que le job record a été ouvert ; le results_dir du job record est autoritaire sur tout chemin d'affichage pré-révision. Persistez les hashes du bundle producteur et de la config d'exécution liée.
• Les noms supporting_files sont des helpers orchestration archivés relatifs à la racine du skill producteur. La plateforme prépare l'ensemble fermé, vérifie chaque SHA256 déclaré, et rejette la traversal, les frères non déclarés ou la réécriture d'un bundle différent. Les fichiers de support orchestrent une action ; ils ne doivent jamais masquer ou patcher le code à l'intérieur de l'image sélectionnée.
• Une déclaration torchrun exprime la topologie des processus, non la syntaxe SLURM/Kubernetes. Chaque plateforme la mappe à son lanceur distribué natif.

Vocabulaire de statut fixe

Tout état de job n'importe où dans le pipeline est exactement l'un de :

PENDING · RUNNING · COMPLETE · ERROR · CANCELED · UNKNOWN

Les sous-états natifs de la plateforme (ImagePullBackOff, PENDING-faute-de-ressources, Insufficient-GPU, slurm COMPLETING…) ne sont jamais des états nouveaux — ils circulent dans le champ message de la transition. Terminal = COMPLETE | ERROR | CANCELED. C'est ce qui permet à la loop de poll in-turn et au poller détaché de partager un chemin de code unique entre docker/slurm/kubernetes/brev.

Invariants d'ordre (appliqués à la couture, énoncés ici)

• La gate verify-before-launch s'exécute sur le spec-bundle, avant qu'aucun job id n'existe.
• tao_job_record.py open écrit PENDING + le results_dir résolu en premier et retourne l'id — l'unique handle qu'un lancement peut utiliser. Une soumission qui a sauté la gate n'a pas d'id, donc elle ne peut pas être lancée.
• transitions est append-only ; .tao/ vit en dehors de chaque arbre results synchronisé.