Gestionnaire d'expériences multi-dimensionnelles

multi-dim-manager

Une compétence autonome qui apporte de l'ordre à l'état des expériences computationnelles

longues et multi-dimensionnelles. Votre plugin de calcul fait les

mathématiques ; cette compétence gère le chaos environnant : itération, instantanés,

audit et retour en arrière.

La compétence orchestre seulement. Elle ne calcule jamais de résultat elle-même – chaque

nombre provient de votre plugin.

Quand l'utiliser

• Un workflow exécute plusieurs tours sur un espace de paramètres (une grille cartésienne de

  dimensions) et a besoin que l'état de chaque tour soit enregistré.

• Des instantanés par tour des fichiers critiques déclarés sont nécessaires avant et

  après chaque tour.

• Une piste d'audit complète (paramètres, hachages, timestamps, statut) doit exister pour

  chaque tour.

• L'utilisateur doit pouvoir revenir à n'importe quel tour passé, de manière non destructive.

• Formes typiques : études longitudinales, balayages de paramètres, ou explorations

  symboliques/numériques faisant appel à des solveurs externes (Mathematica, GAP, SymPy,

  scripts personnalisés).

WORKFLOW OBLIGATOIRE

Dépendance d'amorçage (exécuter lors de la première utilisation)

Avant la première exécution, vérifiez les dépendances d'exécution de cette compétence :

• Core : bibliothèque standard pure – aucune installation requise.
• Optionnel : PyYAML (uniquement lorsque la configuration est un .yaml ; les configurations JSON fonctionnent avec la bibliothèque standard seule).

Si PyYAML est manquant et que la configuration de l'utilisateur est YAML, informez-le et demandez s'il faut pip install pyyaml ; n'installez que s'il confirme. N'installez jamais dans l'environnement global sans consentement explicite.

Suivez ces étapes dans l'ordre à chaque fois que l'utilisateur demande d'exécuter, inspecter ou

récupérer une expérience multi-dimensionnelle.

1. Charger la configuration. Lisez la configuration de l'expérience (config.example.yaml

   est le modèle). Confirmez que param_space.dimensions, critical_paths,

   et plugin.command sont présents. Si YAML est utilisé, PyYAML doit être

   installé ; sinon utilisez JSON.

2. Développer l'espace. Énumérez le produit cartésien de toutes les

   dimensions. Signalez le nombre total de tours à l'utilisateur avant d'exécuter.

3. Privilégier une simulation. Exécutez python scripts/run.py dryrun --config <cfg>

   pour que l'utilisateur voie le plan complet (chaque combinaison de paramètres) sans

   aucun effet secondaire. Ne passez à l'exécution qu'après confirmation.

4. Exécuter le balayage. Exécutez python scripts/run.py run --config <cfg>.

   Pour chaque tour, dans l'ordre : prenez un instantané des chemins critiques déclarés avant, invoquez le plugin, prenez un instantané après et ajoutez un enregistrement d'audit.

5. Réagir correctement aux échecs. Si le plugin d'un tour se termine avec un code non nul,

   enregistrez son statut (failed/error). Lorsque auto_rollback est activé,

   récupérez l'état postérieur du dernier tour réussi dans le répertoire de travail pour que les tours suivants démarrent proprement ; cette récupération est elle-même audité. N'arrêtez pas tout le balayage à cause d'une seule mauvaise combinaison.

6. Résumer. Après le balayage, la compétence écrit results_summary.csv,

   results_summary.md, report_draft.md et run_metadata.json dans le répertoire de sortie. Dirigez l'utilisateur vers ces fichiers.

7. Récupérer sur demande. Pour restaurer un tour passé, exécutez

   python scripts/run.py rollback --config <cfg> --round <N>. Par défaut, il restaure dans un NOUVEAU répertoire ; n'ajoutez --force que lorsque l'utilisateur souhaite explicitement écraser le répertoire de travail actif.

Contraintes strictes

• Ne calculez jamais le résultat vous-même. Toute mathématique de domaine appartient au

  plugin utilisateur. La compétence l'appelle et enregistre le résultat du contrat.

• Instantanés uniquement des chemins critiques déclarés. Une copie complète du répertoire

  de travail n'est jamais effectuée ; le contenu est stocké adressé par hachage, donc les fichiers inchangés ne coûtent rien de plus.

• Le retour en arrière est non destructif par défaut. Sans --force, le répertoire de

  travail actif n'est jamais modifié ; l'état restauré atterrit dans un nouveau répertoire. Chaque retour en arrière (manuel ou automatique) est écrit dans le journal d'audit.

• Le déterminisme est la promesse de l'utilisateur. La compétence garantit que

  l'orchestration est reproductible (mêmes paramètres -> même plan enregistré, mêmes hachages). Elle ne peut pas rendre un plugin non déterministe déterministe ; voir les Limitations.

Exemples d'utilisation

# Afficher le plan complet des tours sans aucun effet secondaire (faites toujours cela en premier).

python scripts/run.py dryrun --config config.example.yaml



# Exécuter le balayage.

python scripts/run.py run --config config.example.yaml



# Restaurer un tour passé (dans un NOUVEAU répertoire sauf --force).

python scripts/run.py rollback --config config.example.yaml --round 7



# Régénérer les résumés, ou vérifier le résultat d'un tour.

python scripts/run.py summary --config config.example.yaml

python scripts/run.py verify --config config.example.yaml --round 7

Contrat du plugin

Le gestionnaire lance exactement une commande shell par tour :

python your_plugin.py --params {PARAMS} --out {OUT}

• {PARAMS} - chemin vers un fichier JSON contenant la combinaison de paramètres de ce tour.

• {OUT} - chemin dans lequel le plugin DOIT écrire son JSON de résultat.

• Codes de sortie : 0 succès, 1 assertion échouée / vérification échouée, 2 erreur ou ignoré.

Tout solveur externe (Mathematica, GAP, un script Python LMM) est enveloppé pour respecter ce contrat : il lit le fichier de paramètres et écrit un fichier de résultat. La compétence ne se soucie pas de ce qui est calculé.

Gestion des échecs

• Un tour dont le plugin se termine avec 1 est marqué failed ; sortie 2 est error. Les deux sont conservés dans le journal d'audit ; le balayage continue.
• Les erreurs de config (espace manquant, YAML invalide, {OUT} manquant) annulent avant tout effet secondaire et affichent un message clair (code de sortie 2).
• Un rollback vers un tour qui n'a jamais été enregistré, ou qui n'a pas d'instantané postérieur, échoue avec une erreur claire plutôt que de corrompre l'état.

Limitations

• Le déterminisme est seulement au niveau de l'orchestration. Le gestionnaire enregistre les hachages et rejoue le même plan pour les mêmes paramètres, mais il ne peut pas garantir que le plugin est déterministe. Si le plugin touche le réseau, utilise des graines aléatoires ou lit l'horloge système, les mêmes entrées peuvent produire des sorties différentes. Déclarez ce non-déterminisme dans le plugin vous-même.
• Les chemins critiques doivent être déclarés à l'avance. Les fichiers non listés dans critical_paths ne sont jamais instantanés et ne peuvent donc pas être restaurés.
• La vérification des sorties dorées est v0.2. Le vérificateur actuel ne vérifie que le contrat du plugin (sortie 0 + fichier résultat présent). La comparaison avec une sortie attendue connue est prévue mais pas encore implémentée.
• Les configurations YAML nécessitent PyYAML. Les configurations JSON fonctionnent avec la bibliothèque standard seule.