docs: README complet + ROADMAP phases 1-9, points critiques, décisions archi

2026-06-16 10:37:51 +00:00
parent cf57c84dd1
commit efe66026ad
2 changed files with 457 additions and 0 deletions
@@ -0,0 +1,273 @@
+# Fallout: Venice of Wasteland — Moteur de simulation JDR
+
+Simulation autonome d'un univers **Fallout 2D20** situé en Louisiane post-nucléaire.  
+Le moteur simule des PNJ, des factions, des rencontres et une économie — sans MJ humain permanent.  
+Un LLM joue le rôle de MJ narrateur, un second LLM anime les PNJ.
+
+**Dashboard** → [fallout.coyoteos.ovh](https://fallout.coyoteos.ovh) (PipBoy)  
+**Gitea** → [git.coyoteos.ovh](https://git.coyoteos.ovh) — repo `Corback/fallout-venice`
+
+---
+
+## Architecture générale
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    AMPÈRE (Oracle ARM)                   │
+│  82.70.224.131                                          │
+│                                                         │
+│  ┌──────────────┐   ┌───────────────┐  ┌────────────┐  │
+│  │  run.py S1   │   │  run.py S2    │  │   PipBoy   │  │
+│  │  (sim engine)│   │  (sim engine) │  │   Flask    │  │
+│  └──────┬───────┘   └───────┬───────┘  └─────┬──────┘  │
+│         │                   │                │          │
+│  ┌──────▼───────────────────▼────────────────▼──────┐   │
+│  │              Ollama (localhost:11434)             │   │
+│  │    qwen2.5:14b (MJ)  +  qwen2.5:7b (PNJ)        │   │
+│  └───────────────────────────────────────────────────┘   │
+│                                                         │
+│  ┌────────────────────────────────────────────────────┐  │
+│  │  ChromaDB :8800  — collection fallout_lore         │  │
+│  │  1403 chunks : règles 2D20, lore canon, ambiance   │  │
+│  └────────────────────────────────────────────────────┘  │
+└────────────────────────────┬────────────────────────────┘
+                             │ SSH tunnel :15432
+┌────────────────────────────▼────────────────────────────┐
+│                  VIGILE (OVH)  79.72.30.231              │
+│              PostgreSQL — base "fallout"                 │
+└─────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Infra & accès
+
+| Serveur | IP | Rôle | Clé SSH |
+|---------|----|------|---------|
+| Ampère | 82.70.224.131 | Calcul — LLM, sim, dashboard | `oracle.key` |
+| Vigile | 79.72.30.231 | PostgreSQL | `vigile_backup` |
+
+**Tunnel DB actif sur Ampère** : `localhost:15432` → Vigile:5432  
+**ChromaDB** : `localhost:8800` — API v2 uniquement (`/api/v2/...`)  
+**Ollama** : `localhost:11434`  
+**PipBoy (Docker)** accède à Ollama via `host.docker.internal:11434`
+
+---
+
+## Stack technique
+
+| Composant | Technologie | Détail |
+|-----------|------------|--------|
+| Moteur sim | Python 3.11 | `src/engine/` |
+| Dashboard | Flask + Jinja2 | Docker `fallout-visu` |
+| LLM MJ | qwen2.5:14b via Ollama | ~30s/réponse warm |
+| LLM PNJ | qwen2.5:7b via Ollama | ~5s/réponse warm |
+| Base de données | PostgreSQL 15 (Vigile) | SSH tunnel depuis Ampère |
+| RAG | ChromaDB v1.0.0 (API v2) | collection `fallout_lore` |
+| Proxy | nginx-proxy-manager | SSL Let's Encrypt auto |
+| Gitea | git.coyoteos.ovh:2222 | repo Corback/fallout-venice |
+
+---
+
+## Structure du projet
+
+```
+fallout-venice/
+├── src/
+│   ├── engine/
+│   │   ├── run.py              # Lanceur principal (hot-reload config, status check loop)
+│   │   ├── tick.py             # Orchestration d'un tick
+│   │   ├── encounter.py        # Rencontres (safe zones, raids, commerce PNJ)
+│   │   ├── combat_engine.py    # Résolution combats 2D20
+│   │   ├── sim_config.py       # Chargement + deep-merge config JSON
+│   │   ├── init_pnj.py         # Initialisation PNJ en DB
+│   │   ├── lore_enricher.py    # Enrichissement lore via LLM + RAG Chroma
+│   │   └── db.py               # Accès PostgreSQL
+│   ├── config/
+│   │   ├── sim_001.json        # Config session 1 (référence des 5 modes)
+│   │   ├── sim_002.json        # Config session 2
+│   │   └── crash_results.json  # Résultats derniers tests LLM (lu par PipBoy)
+│   └── data/
+│       └── encounter_tables.json  # Tables rencontres, zones sûres, pools entités
+├── dashboard/
+│   └── app.py                  # Source PipBoy — copier dans /home/ubuntu/fallout-visu/
+├── tools/
+│   ├── llm_crash_test.py       # Stress test LLM (modes: simultane/decale/solo)
+│   └── capacity_test.py        # Test capacité N joueurs simultanés
+├── README.md
+└── ROADMAP.md
+```
+
+> ⚠️ Le dashboard actif est `/home/ubuntu/fallout-visu/app.py` (monté dans Docker).  
+> `dashboard/app.py` est la source de vérité — toujours synchroniser les deux après modification.
+
+---
+
+## Système de PNJ — 4 tiers
+
+| Tier | Label | Comportement | LLM actuel |
+|------|-------|-------------|-----------|
+| 0 | BOSS | Immortel, chef de faction | Non (prévu 14b) |
+| 1 | ACTIFS SIM | Simulés chaque tick, mémoire persistante | Non (prévu 7b) |
+| 2 | PNJ+ | Réagissent aux événements importants | Non (prévu 7b) |
+| 3 | PASSAGE | Décor narratif | Jamais |
+
+Actuellement tous les PNJ sont animés par le **moteur Python seul**.  
+Le LLM PNJ sera déclenché uniquement sur **interaction joueur directe** (V2).
+
+---
+
+## Zones sûres
+
+`independance` | `nola_vieux_carre` | `baton_rouge` | `laplace`
+
+Règles : pas de rencontres lambda/groupe. Seuls les raids de faction (faible probabilité) et le commerce PNJ-à-PNJ sont possibles. Les marchands peuvent s'y retrouver sans rencontrer de bêtes.
+
+---
+
+## Modes de simulation
+
+Configurables depuis le PipBoy — prise en compte au **prochain jour** (hot-reload).
+
+| Mode | Rencontres | Drain | Économie | Usage |
+|------|-----------|-------|---------|-------|
+| `pacifiste` | ×0.4 | ×0.7 | normal | Test/debug |
+| `politique` | ×0.6 | ×1.0 | normal | Intrigues factions |
+| `guerre_commerciale` | ×1.2 | ×1.5 | ×1.5 caps | Blocus, routes coupées |
+| `guerre` | ×2.0 | ×1.8 | pénurie | Front de guerre actif |
+| `survie_extreme` | ×1.8 | ×2.5 | ×0.3 | Stress test pur |
+
+---
+
+## ChromaDB — collection `fallout_lore`
+
+**1403 chunks** — source de vérité en lecture seule.
+
+| Catégorie | Chunks | Contenu |
+|-----------|--------|---------|
+| `regles_core` | ~934 | Règles 2D20 Fallout (avec 299 chunks migrés depuis `type` → `category`) |
+| `regles_supplement` | 279 | Suppléments et extensions |
+| `lore_inspiration` | 86 | Inspiration univers Fallout |
+| `ambiance` | 43 | Descriptions atmosphériques |
+| `aventure` | 29 | Scénarios de référence |
+| `lore_canon` | 32 | **Bible Venice of Wasteland v1.1 & v2.0** |
+
+`fallout_lore_enriched` → reçoit les propositions lore **acceptées** depuis le PipBoy.
+
+---
+
+## Performances LLM mesurées (16/06/2026, Ampère ARM)
+
+| Joueurs simultanés | Tick complet | Actions/heure | Viable tick 10min |
+|-------------------|-------------|---------------|-----------------|
+| 1 | 35s | 103 | ✓ |
+| 5 | 57s | 62 | ✓ |
+| 10 | 1m17 | 46 | ✓ |
+| 50 | 3m32 | 16 | ✓ (8 timeouts) |
+
+MJ 14b : constant ~30s indépendamment du nombre de joueurs (commence après tous les PNJ).  
+Cold start : ~90s si Ollama a déchargé les modèles (inactivité prolongée).  
+**Plafond recommandé V1 : 10-15 joueurs actifs simultanés.**
+
+---
+
+## Lancement des simulations
+
+```bash
+# SSH sur Ampère
+cd /home/ubuntu/fallout-venice/src/engine
+
+# Session 1
+nohup env SESSION_ID=1 TICK_SLEEP_SEC=60 PYTHONUNBUFFERED=1 \
+  python3 -u run.py > ~/fallout_sim_s1.log 2>&1 &
+
+# Session 2
+nohup env SESSION_ID=2 TICK_SLEEP_SEC=60 PYTHONUNBUFFERED=1 \
+  python3 -u run.py > ~/fallout_sim_s2.log 2>&1 &
+
+tail -f ~/fallout_sim_s1.log
+```
+
+**Reset propre d'une session :**
+1. PipBoy → Paramètres → **STOP** (attendre max 5 ticks)
+2. PipBoy → Paramètres → **Reset Jour/Tick**
+3. Relancer via terminal
+
+---
+
+## Enrichissement lore
+
+```bash
+cd /home/ubuntu/fallout-venice/src/engine
+
+python3 lore_enricher.py --faction grand_krewe   # une faction
+python3 lore_enricher.py --faction all            # toutes
+python3 lore_enricher.py --list-factions          # liste
+```
+
+Valider les propositions → PipBoy onglet **ENRICHISSEMENT**  
+Les propositions acceptées sont indexées dans `fallout_lore_enriched` (Chroma).
+
+---
+
+## Tests LLM
+
+```bash
+cd /home/ubuntu/fallout-venice/tools
+
+# Stress test simple
+python3 llm_crash_test.py --mode simultane --rounds 5 --pnj-count 2
+
+# Test capacité (1 / 5 / 10 / 50 joueurs)
+python3 capacity_test.py
+python3 capacity_test.py --quick   # sans le test 50 joueurs
+```
+
+Les résultats sont écrits dans `src/config/crash_results.json` et lisibles depuis le PipBoy (onglet OUTILS → Charger les résultats).
+
+---
+
+## Variables d'environnement clés
+
+| Variable | Défaut | Description |
+|----------|--------|-------------|
+| `SESSION_ID` | 1 | Session simulée |
+| `TICK_SLEEP_SEC` | 60 | Durée d'un tick (secondes) |
+| `PYTHONUNBUFFERED` | — | `1` pour logs temps réel |
+| `OLLAMA_URL` | `http://localhost:11434` | Endpoint Ollama |
+| `MODEL_MJ` | `qwen2.5:14b` | Modèle MJ narrateur |
+| `MODEL_PNJ` | `qwen2.5:7b` | Modèle animation PNJ |
+| `DB_HOST` / `DB_PORT` | `127.0.0.1` / `15432` | PostgreSQL via tunnel SSH |
+| `SIM_CONFIGS_DIR` | `/app/src/config` | Répertoire configs JSON |
+| `CRASH_RESULTS_PATH` | `src/config/crash_results.json` | Sortie tests LLM |
+
+---
+
+## ⚠️ Points critiques — à ne jamais oublier
+
+**ChromaDB**
+- API v2 uniquement — `/api/v1/` retourne `{"error":"Unimplemented"}`
+- Requêtes par **UUID**, pas par nom de collection (récupérer l'UUID d'abord via `GET /collections`)
+- La collection `fallout_vst` **n'existe pas** — c'est `fallout_lore`
+- 299 chunks avaient le champ `type` au lieu de `category` — corrigé en juin 2026
+
+**Dashboard**
+- Le fichier actif est `/home/ubuntu/fallout-visu/app.py` (monté Docker), pas `dashboard/app.py`
+- Toujours copier les deux après modification : `scp dashboard/app.py ubuntu@82.70.224.131:/home/ubuntu/fallout-visu/app.py`
+
+**Simulation**
+- `run.py` vérifie le statut DB toutes les **5 ticks** — STOP depuis PipBoy n'est pas instantané
+- Hot-reload config JSON au **début de chaque jour** (tick 0), pas immédiatement
+- `init_pnj.py` lit `SESSION_ID` depuis l'env (plus hardcodé)
+
+**Réseau Docker**
+- Le container PipBoy accède à Ollama via `host.docker.internal:11434`
+- Une règle iptables autorise 172.20.0.0/16 → port 11434. Si elle disparaît après reboot :
+  ```bash
+  sudo iptables -I INPUT 1 -s 172.20.0.0/16 -p tcp --dport 11434 -j ACCEPT
+  sudo iptables-save | sudo tee /etc/iptables/rules.v4
+  ```
+
+**Tunnel SSH DB**
+- Le container PipBoy crée son propre tunnel au démarrage (clé `/ssh/vigile.key`)
+- Si DB inaccessible : `docker restart fallout-visu`
@@ -0,0 +1,184 @@
+# ROADMAP — Fallout: Venice of Wasteland
+
+État au **16 juin 2026**. Projet : moteur de simulation JDR Fallout 2D20 autonome, Louisiane post-nucléaire.
+
+---
+
+## ✅ Phase 1 — Moteur de base (TERMINÉ)
+
+- [x] Moteur de tick Python (survie, économie, rencontres)
+- [x] Système PNJ 4 tiers (Tier 0 Boss / Tier 1 Actifs / Tier 2 PNJ+ / Tier 3 Passage)
+- [x] Combats 2D20 (combat_engine.py)
+- [x] Sessions multiples isolées (session_id sur toutes les tables)
+- [x] Config JSON par session avec deep-merge par mode
+- [x] Hot-reload config au début de chaque jour (sans redémarrer)
+- [x] Vérification statut DB dans la boucle principale (stop depuis dashboard)
+- [x] Zones sûres (safe zones) — pas de rencontres lambda, commerce PNJ-à-PNJ
+- [x] Système de raids de faction dans les zones sûres (faible probabilité)
+- [x] Relations factions avec score de volatilité
+
+---
+
+## ✅ Phase 2 — RAG & Lore (TERMINÉ)
+
+- [x] ChromaDB avec 1403 chunks (règles 2D20 + lore canon Venice of Wasteland)
+- [x] Bible Venice of Wasteland v1.1 & v2.0 indexée (lore_canon, 32 chunks)
+- [x] Correction des 299 chunks avec métadonnée `type` → `category`
+- [x] Pipeline d'enrichissement lore (lore_enricher.py)
+  - RAG depuis fallout_lore (lore_canon + regles_core + lore_inspiration)
+  - Appel qwen2.5:14b avec prompt structuré JDR
+  - Propositions stockées dans `lore_proposals` (PostgreSQL)
+  - Validation manuelle depuis le PipBoy
+  - Propositions acceptées → `fallout_lore_enriched` (Chroma)
+
+---
+
+## ✅ Phase 3 — Dashboard PipBoy (TERMINÉ)
+
+- [x] Dashboard Flask accessible sur fallout.coyoteos.ovh
+- [x] Onglet **SIM LIBRE** : état temps réel (PNJ, events, world state, factions, rencontres)
+- [x] Onglet **OUTILS** : génération commandes + stress test LLM avec console live
+- [x] Onglet **ENRICHISSEMENT** : validation propositions lore (accept/reject/modifier)
+- [x] Onglet **PARAMÈTRES** : config session, modes, reset jour/tick, statut DB
+- [x] Switcher de sessions (S1/S2)
+- [x] Auto-refresh 30s sur l'onglet simulation
+- [x] Métriques cards (PNJ vivants/morts, combats, rencontres)
+- [x] Bouton "Exécuter" stress test avec console live (polling 1.5s)
+- [x] Accès Ollama depuis le container Docker (iptables + host.docker.internal)
+
+---
+
+## ✅ Phase 4 — Tests de performance (TERMINÉ)
+
+- [x] Script stress test LLM (llm_crash_test.py) — modes simultane/decale/solo
+- [x] Script capacity test (capacity_test.py) — simulation N joueurs simultanés
+- [x] Résultats mesurés : 1/5/10/50 joueurs, tick 35s → 3m32
+- [x] Conclusion : 10-15 joueurs actifs simultanés recommandés sur l'infra actuelle
+
+---
+
+## 🔄 Phase 5 — LLM intégré à la simulation (EN COURS / PROCHAIN)
+
+### 5a — Animation PNJ par LLM (priorité haute)
+- [ ] Appel LLM 7b uniquement sur interaction joueur directe avec Tier 0/1
+- [ ] Contexte RAG injecté : lore_canon faction + règles pertinentes
+- [ ] Mémoire courte terme : 3 derniers échanges du PNJ en contexte
+- [ ] Réponse stockée en DB (events table) avec attribution actor_id
+- [ ] Limit : max N appels LLM PNJ simultanés par tick (configurable)
+
+### 5b — MJ narrateur par LLM (priorité haute)
+- [ ] Synthèse narrative du tick par le 14b (résumé de ce qui s'est passé)
+- [ ] Stockée comme événement `narrative_tick` en DB
+- [ ] Affichage dans PipBoy onglet SIM
+- [ ] Contexte : world_state + top 10 événements du tick + relations factions
+
+### 5c — Onglet SIM LLM dans PipBoy
+- [ ] Vue dédiée pour les sessions avec LLM actif
+- [ ] Feed narratif du MJ en temps réel
+- [ ] Indicateur de charge LLM (requêtes en queue)
+
+---
+
+## 🔮 Phase 6 — Arbitre & Cohérence (CONÇU, NON IMPLÉMENTÉ)
+
+Système de vérification automatique entre les ticks, utilisant la marge de 6m30 disponible.
+
+### Architecture
+```
+Tick N (3m30)          →  Résultats en DB
+Arbitre LLM (3m00)     →  Vérification cohérence + règles
+                            ├── Auto-correction (patterns connus)
+                            └── File manuelle → PipBoy validation
+Tick N+1               →  Démarre sur une base cohérente
+```
+
+### Tables à créer
+- `tick_validations` — anomalies détectées par tick
+- `correction_patterns` — patterns appris, score de confiance
+
+### Logique d'apprentissage
+- Chaque validation manuelle augmente la confiance du pattern (+delta)
+- Chaque rejet diminue la confiance (-delta)
+- Seuil configurable (défaut 0.8) → bascule en auto-correction
+- Types de patterns : `stat_check` | `location` | `economy` | `narrative`
+
+### Ce que l'arbitre vérifie
+- **Auto (confiance rapide)** : caps négatifs, HP > max, PNJ mort qui agit, localisation impossible
+- **Manuel (confiance lente)** : cohérence narrative, comportement faction vs lore, conflits de traités
+
+---
+
+## 🔮 Phase 7 — Ticks temps réel (IDÉE VALIDÉE, NON IMPLÉMENTÉ)
+
+Synchroniser les ticks sur l'heure réelle de la Louisiane (UTC-5/UTC-6).
+
+### Principe
+- 1 tick = 1 heure réelle (timezone `America/Chicago`)
+- `run.py` calcule le tick courant depuis `datetime.now(tz)` au lieu d'incrémenter
+- Résout la dérive en cas de redémarrage
+- Nuit en jeu = vraiment la nuit (20h-8h Louisiana = 2h-14h France)
+
+### Impact joueur
+- Action possible toutes les X minutes réelles
+- Le MJ et les PNJ "vivent" même quand le joueur est absent
+- Journées réelles = journées en jeu
+
+### Config à ajouter dans sim_XXX.json
+```json
+"tick": {
+  "mode": "realtime",
+  "realtime_timezone": "America/Chicago",
+  "fixed_tick_sleep_sec": 60
+}
+```
+
+### Considération fuseau horaire
+- France UTC+2 vs Louisiane UTC-5/6 → 7-8h de décalage
+- Midi à NOLA = 18h-19h en France → créneau jouable en soirée
+- Nuit à NOLA se passe pendant les heures de travail en France → cohérent narrativement
+
+---
+
+## 🔮 Phase 8 — Météo procédurale (IDÉE, NON IMPLÉMENTÉ)
+
+Système météo calé sur la météo réelle de la Louisiane.
+
+- API météo New Orleans → injectée dans le contexte LLM chaque jour
+- Impact mécanique : pluie = -visibilité, chaleur extrême = drain eau ×1.5
+- Événements saisonniers : saison des ouragans (juin-novembre), Mardi Gras
+- Stocké dans `world_state` par zone avec colonne `weather_json`
+
+---
+
+## 🔮 Phase 9 — Joueurs réels (VISION LONG TERME)
+
+Interface pour que de vrais joueurs envoient des actions.
+
+- API REST ou bot Discord → reçoit les actions joueur
+- Action validée par l'arbitre (Phase 6) avant d'être exécutée
+- Réponse PNJ via LLM 7b dans la foulée (<10s)
+- Résumé MJ 14b envoyé à la fin du tick
+- Gestion des absences : le PNJ joueur survit en mode automatique (Tier 1)
+
+---
+
+## Backlog technique (bugs connus / dettes)
+
+- [ ] `fallout-visu/app.py` et `dashboard/app.py` sont deux fichiers séparés à synchroniser manuellement → à unifier avec un mount symlink ou CI
+- [ ] Le container PipBoy se réinstalle à chaque restart (pip install au démarrage) → créer une image Docker dédiée
+- [ ] `capacity_test.py` écrit en root depuis le container (permission denied) → monter le volume avec le bon uid
+- [ ] 8 timeouts sur 50 joueurs simultanés → augmenter timeout à 300s ou implémenter une queue avec backpressure
+- [ ] Pas de persistance de l'iptables après reboot complet du host → vérifier que `netfilter-persistent` est installé
+
+---
+
+## Décisions d'architecture à retenir
+
+| Décision | Raison |
+|----------|--------|
+| LLM PNJ déclenché sur interaction seulement (pas chaque tick) | Évite de saturer Ollama sur les 100+ PNJ de la sim |
+| `fallout_lore` en lecture seule | Source de vérité immuable — les enrichissements vont dans `fallout_lore_enriched` |
+| Validation manuelle avant auto (Phase 6) | Constituer un corpus de corrections avant d'automatiser |
+| Ticks temps réel en option (pas par défaut) | Handicap pour les joueurs français si activé sans réflexion |
+| PostgreSQL sur Vigile (OVH) séparé d'Ampère | Résilience — si Ampère tombe, les données persistent |
+| Sessions isolées par `session_id` | Permet tests en parallèle sans collision de données |