diff --git a/README.md b/README.md new file mode 100644 index 0000000..902684c --- /dev/null +++ b/README.md @@ -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` diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 0000000..7f528f4 --- /dev/null +++ b/ROADMAP.md @@ -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 |