diff --git a/docs/phase-2-llm-architecture.md b/docs/phase-2-llm-architecture.md index a94bff9..45a20b7 100644 --- a/docs/phase-2-llm-architecture.md +++ b/docs/phase-2-llm-architecture.md @@ -108,7 +108,7 @@ Moteur (règles inchangées ; frontière additive) \-- SUPPORT |- view.py : ObservationView (objet structuré, versionné) + render() |- candidates.py : actions plausibles dérivées des pairs - |- prompt.py : prompt versionné + |- prompt.py : chargement EXTERNE (pack séparé) + versionnage |- client.py : LLMClient + cache composite + FakeLLMClient scripté + coût |- replay.py : JSONL clé call_seq + replay() \-- sweep.py : exécution parallèle des runs (substrat commun) @@ -153,6 +153,8 @@ tour en sweep (faite par l'étage A). ## 9. Décisions +> Toutes les décisions ci-dessous sont **arbitrées** (voir §13) ; le tableau +> conserve la recommandation validée. Les prompts sont traités au §14. | # | Décision | Recommandation | |---|---|---| | D1 | Entrée : `(observation, state)` ou `(observation)` ? | **`(observation)`** + adaptateur. **À trancher en P0.0.** | @@ -228,13 +230,59 @@ cartographie** sur une rencontre type, en comparant `default_policy` contre une politique de monstres renforcée — ce dernier point prouve immédiatement la valeur « prédire où sont les difficultés », avant toute LLM. -## 13. Questions ouvertes +## 13. Décisions arbitrées -1. Fournisseur/modèle (API distante ou local) ? -2. Budget (tokens/coût) par sweep / par optimisation ? -3. Reproductibilité : cache obligatoire (runs rejouables) ? -4. Priorité v1 : **optimiseur** (meilleure stratégie) ou **cartographie** - (où est le danger) ? -5. Prompts dans le dépôt ou externes ? -6. Valides-tu **D1** (observation seule), **D9** (deux étages), **D12** - (danger mesuré en adversaire) et **D14** (cartographie non exhaustive) ? +| # | Décision | Choix retenu | +|---|---|---| +| D1 | Entrée de la politique | **`(observation)` seule** + adaptateur de compatibilité | +| D9 | Exécution | **Deux étages** (compilé pour les sweeps, per-tour pour la vitrine) | +| D12 | Mesure du danger | **Contre un adversaire optimisé** (`AdversarySpec` + meilleure réponse) | +| D14 | Cartographie | **Non exhaustive** : région d'échec + frontière + sensibilité | +| — | Priorité v1 | **Cartographie d'abord**, puis optimiseur (mêmes briques) | +| — | Fournisseur/modèle | **Client agnostique** ; implémentation distante d'abord, locale ensuite ; **mode JSON/schéma requis** | +| — | Budget | **Plafonds petits** (≤ 50 appels de compilation/campagne, ≤ 20 combats en vitrine) + coupe-circuit dans le client | +| — | Reproductibilité | **Cache obligatoire** ; clé composite incluant le modèle ; replay `call_seq` | +| — | Prompts | **Externes / dépôt séparé** (voir §14) | + +Reste à préciser au fil des lots (non bloquant) : forme exacte des leviers de +`StrategySpec`/`AdversarySpec`, choix de l'algorithme d'optimisation, seuils +statistiques par défaut, et le fournisseur distant concret. + +## 14. Prompts externes (décision utilisateur) + +Les prompts **ne vivent pas dans ce dépôt** : ce dépôt ne doit contenir que le +**code du simulateur** (calcul + couche LLM + rapport). Conséquences : + +- **Chargement configurable** : le code lit les prompts depuis un **chemin + externe** (variable d'environnement / fichier de configuration), jamais codés + en dur. +- **Versionnage côté pack** : le dépôt de prompts porte sa propre version + (semver ou hash de commit) ; chaque prompt a un hash individuel. +- **Traçabilité** : le `prompt_version` (version du pack + hash du prompt) + entre dans la **clé du cache**, dans le `ReplayRecord` et dans les rapports de + sweep — sinon une campagne n'est pas reproductible après modification d'un + prompt. +- **Tests** : le pack externe est **épinglé** pour l'intégration (version fixée) ; + les tests unitaires utilisent un **fixture de prompt minimal** local pour que + la CI ne dépende pas du dépôt externe. +- **Validation** : un prompt manquant/invalide doit produire une **erreur + claire** au démarrage (pas de fallback silencieux). + +## 15. Périmètre du dépôt et backlog de détachement + +Décision utilisateur : à terme, **seul le code** doit rester ici. Sont +concernés par un détachement (données et contenu) : fiches de personnages +(`fiches_personnages/`), données de monstres/PJ/sorts/cartes (`data/`), et les +fichiers de prompts. + +**Pour l'instant : laissé en place** (rattrapage prévu en fin de projet). +Contrainte de conception à respecter dès maintenant pour ne pas se peindre dans +un coin : + +- **Aucun chemin de données en dur** dans le nouveau code (couche phase 2) : + centraliser la résolution des chemins (config/env) pour préparer le + déplacement. +- Les prompts sont **déjà** conçus comme externes (§14) — pas de régression. +- Le détachement final devra fournir un **jeu de données d'exemple** et une + documentation de configuration (chemins) pour que le dépôt code reste utilisable + seul.