feat: initial DCC RPG knowledge base + AI DM design
This commit is contained in:
truetype committed
commit
ae73fe43d3
89 files changed
+37405
No files matched your search
@@ -0,0 +1,314 @@
|
||||
# DCC RPG - Architettura Sistema Ibrido AI DM
|
||||
|
||||
**Data**: 2026-06-25
|
||||
**Pattern**: Neon Scratch Lounge (Separazione Reasoning/Execution)
|
||||
**Gioco**: Dungeon Crawl Classics - Regolamento Introduttivo
|
||||
**Avventura**: La Tomba del Mago Guerriero (9 aree)
|
||||
|
||||
---
|
||||
|
||||
## 1. Visione
|
||||
|
||||
Sistema **ibrido AI DM** per DCC: un LLM gestisce narrativa e interpretazione azioni,
|
||||
mentre un motore deterministico (Step Functions + Lambda) esegue le meccaniche di gioco.
|
||||
Il giocatore interagisce via interfaccia testuale/web. Un umano può intervenire
|
||||
con DM-Override per derogare alle regole.
|
||||
|
||||
**Target**: On-premise (CPU-only), interfaccia web locale, nessuna dipendenza cloud.
|
||||
|
||||
---
|
||||
|
||||
## 2. Architettura
|
||||
|
||||
```
|
||||
+------------------------------------------+
|
||||
| CLIENT (Web UI) |
|
||||
| Chat testuale + pannello stato |
|
||||
+--------------------+---------------------+
|
||||
| HTTP/WebSocket
|
||||
+--------------------v---------------------+
|
||||
| LLM ORCHESTRATOR (Python) |
|
||||
| - Mantiene contesto sessione |
|
||||
| - Invia prompt: regole + stato + azione |
|
||||
| - Riceve: narrazione + tool calls |
|
||||
| - Filtra tool contro allowlist |
|
||||
+--------------------+---------------------+
|
||||
|
|
||||
+--------------------v---------------------+
|
||||
| STATE MACHINE (Python) |
|
||||
| Leggi stato -> Esegui tool -> Scrivi |
|
||||
| Retry: 3 tentativi, backoff + jitter |
|
||||
| Idempotenza: cache per turnId |
|
||||
| Fallback: narrazione safe |
|
||||
+--------------------+---------------------+
|
||||
|
|
||||
+--------------------v---------------------+
|
||||
| APPROVED TOOLS (Python) |
|
||||
| roll-dice | combat | ability-check |
|
||||
| saving-throw | movement | spellcasting |
|
||||
| update-inventory | award-xp | quest |
|
||||
| dm-override |
|
||||
+--------------------+---------------------+
|
||||
|
|
||||
+--------------------v---------------------+
|
||||
| STATO (SQLite / JSON locale) |
|
||||
| Personaggi | Avventura | Turni | Quest |
|
||||
+------------------------------------------+
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Stack Tecnologico (On-Premise)
|
||||
|
||||
| Componente | Tecnologia | Motivo |
|
||||
|-----------|-----------|--------|
|
||||
| LLM | Ollama (gemma2:9b) | On-premise, CPU-only, IT |
|
||||
| Backend | Python + FastAPI | Leggero, on-premise |
|
||||
| Frontend | HTML+JS vanilla | Semplice, no build |
|
||||
| Stato | SQLite | Zero dipendenze |
|
||||
| Tools | Python functions | Deterministici, testabili |
|
||||
| Orchestratore | State machine Python | Equivalente NSL on-prem |
|
||||
| Embedding | nomic-embed-text (Ollama) | Retrieval KB (opzionale) |
|
||||
|
||||
**Deviazioni NSL**: Step Functions AWS e DynamoDB sostituiti da state machine Python + SQLite.
|
||||
Pattern architetturale (Separazione Reasoning/Execution) identico.
|
||||
|
||||
---
|
||||
|
||||
## 4. Flusso del Turno
|
||||
|
||||
```
|
||||
1. INPUT GIOCATORE -> "Cerco nella stanza"
|
||||
|
|
||||
2. LLM REASONING: analizza azione, consulta regole,
|
||||
decide tool da chiamare
|
||||
Output: narrazione + ["ability-check: cercare CD 12"]
|
||||
|
|
||||
3. VALIDATE: filtra tool contro allowlist
|
||||
|
|
||||
4. EXECUTE TOOLS (sequenziale/parallelo):
|
||||
- ability-check("cercare", CD 12, agilita)
|
||||
- Risultato: successo (15 >= 12), trova leva segreta
|
||||
|
|
||||
5. PERSIST STATO: aggiorna SQLite
|
||||
|
|
||||
6. LLM NARRATION: "Scorgi una lieve fessura nella parete
|
||||
nord. Sembra esserci una leva nascosta..."
|
||||
|
|
||||
7. OUTPUT GIOCATORE -> messaggio di risposta
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Approved Tools
|
||||
|
||||
### 5.1 roll-dice
|
||||
- **Parametri**: dado (d20, d%, d24), quantita (default 1), modificatore
|
||||
- **Output**: risultati numerici, successo/fallimento vs CD
|
||||
- **Esempi**: 1d20+2, 1d24 (catena dadi), 3d6, 1d100
|
||||
|
||||
### 5.2 combat
|
||||
- **Sotto-operazioni**:
|
||||
- `initiative`: 1d20 + Agilita, ordina creature
|
||||
- `attack`: d20 + mod vs CA, danni se colpito
|
||||
- `mighty-deed`: attacco + deed (guerriero)
|
||||
- `sneak-attack`: attacco furtivo (ladro)
|
||||
- `critical-hit`: tabella critici
|
||||
- `fumble`: tabella fallimenti critici
|
||||
|
||||
### 5.3 ability-check
|
||||
- **Parametri**: abilita, CD, caratteristica
|
||||
- **Ladro**: usa dado abilita + modificatore
|
||||
- **Altri**: d20 + modificatore caratteristica
|
||||
|
||||
### 5.4 saving-throw
|
||||
- **Parametri**: tipo (Tempra/Riflessi/Volonta), CD, bonus
|
||||
- **Output**: successo/fallimento, effetti
|
||||
|
||||
### 5.5 movement
|
||||
- **Parametri**: destinazione/area, modalita
|
||||
- **Output**: tempo, incontri, ostacoli
|
||||
|
||||
### 5.6 spellcasting
|
||||
- **Parametri**: incantesimo, livello, modificatori
|
||||
- **Output**: prova incantesimo, tabella, manifestazione, corruzione
|
||||
|
||||
### 5.7 update-inventory
|
||||
- **Parametri**: azione (aggiungi/rimuovi/equipaggia), oggetto, qta
|
||||
- **Output**: inventario aggiornato
|
||||
|
||||
### 5.8 award-xp
|
||||
- **Parametri**: PE (0-4), motivo
|
||||
- **Output**: PE totali, eventuale avanzamento livello
|
||||
|
||||
### 5.9 update-quest
|
||||
- **Parametri**: quest ID, stato (attiva/completata/fallita)
|
||||
- **Output**: log quest aggiornato
|
||||
|
||||
### 5.10 dm-override (solo DM)
|
||||
- **Parametri**: modifica (set-pf, forza-risultato, ignora-regola)
|
||||
- **Output**: stato modificato
|
||||
|
||||
---
|
||||
|
||||
## 6. Stato del Gioco (SQLite Schema)
|
||||
|
||||
```sql
|
||||
CREATE TABLE campaign (
|
||||
id TEXT PRIMARY KEY,
|
||||
name TEXT NOT NULL,
|
||||
turn_id INTEGER DEFAULT 0,
|
||||
current_area TEXT,
|
||||
created_at TIMESTAMP,
|
||||
updated_at TIMESTAMP
|
||||
);
|
||||
|
||||
CREATE TABLE characters (
|
||||
id TEXT PRIMARY KEY,
|
||||
campaign_id TEXT REFERENCES campaign(id),
|
||||
name TEXT NOT NULL, player TEXT,
|
||||
level INTEGER DEFAULT 0, xp INTEGER DEFAULT 0,
|
||||
class TEXT, alignment TEXT,
|
||||
occupation TEXT,
|
||||
str INTEGER, agi INTEGER, con INTEGER,
|
||||
int INTEGER, sag INTEGER, car INTEGER, lck INTEGER,
|
||||
hp_current INTEGER, hp_max INTEGER,
|
||||
ac INTEGER, equipment TEXT, inventory TEXT,
|
||||
active_effects TEXT, is_alive BOOLEAN DEFAULT 1
|
||||
);
|
||||
|
||||
CREATE TABLE adventure_state (
|
||||
id TEXT PRIMARY KEY,
|
||||
campaign_id TEXT REFERENCES campaign(id),
|
||||
area_id TEXT NOT NULL, area_name TEXT NOT NULL,
|
||||
visited BOOLEAN DEFAULT 0,
|
||||
npc_status TEXT, notes TEXT
|
||||
);
|
||||
|
||||
CREATE TABLE quest_log (
|
||||
id TEXT PRIMARY KEY,
|
||||
campaign_id TEXT REFERENCES campaign(id),
|
||||
quest_name TEXT NOT NULL,
|
||||
status TEXT DEFAULT 'active',
|
||||
description TEXT, objectives TEXT
|
||||
);
|
||||
|
||||
CREATE TABLE turn_log (
|
||||
id TEXT PRIMARY KEY,
|
||||
campaign_id TEXT REFERENCES campaign(id),
|
||||
turn_id INTEGER NOT NULL,
|
||||
player_action TEXT, narrative TEXT,
|
||||
tools_called TEXT, results TEXT,
|
||||
created_at TIMESTAMP
|
||||
);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Knowledge Base
|
||||
|
||||
### 7.1 Contesto System Prompt
|
||||
Il prompt system del LLM contiene:
|
||||
1. **Regole fondamentali**: d20, catena dadi, CD/CA
|
||||
2. **Approved Tools**: descrizione e parametri
|
||||
3. **Mappa avventura**: aree, CD, statistiche mostri
|
||||
4. **Regole classe**: Dado Cimento, abilita ladro, ecc.
|
||||
5. **Tabelle critici/fumble**
|
||||
6. **Allineamento e deta**
|
||||
|
||||
### 7.2 Retrieval (opzionale)
|
||||
Embedding con nomic-embed-text su Ollama per retrieval regole specifiche.
|
||||
|
||||
---
|
||||
|
||||
## 8. DM-Override
|
||||
|
||||
### 8.1 Operazioni
|
||||
- Modifica diretta stato (PF, statistiche, equip)
|
||||
- Forzatura risultati (successo/fallimento automatico)
|
||||
- Deroga regole (es. ignora caduta)
|
||||
- Spawn NPC e mostri
|
||||
- Rewind turno
|
||||
|
||||
### 8.2 Accesso
|
||||
- Pulsante "DM Mode" nell'interfaccia
|
||||
- Comando testuale /dm <comando>
|
||||
- LLM puo richiedere override: "Situazione non coperta. DM?"
|
||||
|
||||
### 8.3 Logging
|
||||
Ogni override registrato in turn_log con flag is_dm_override.
|
||||
|
||||
---
|
||||
|
||||
## 9. Mappa Avventura (Area Graph)
|
||||
|
||||
```
|
||||
[Foresta (quest driade)]
|
||||
|
|
||||
[1.1 Portale]
|
||||
|
|
||||
[1.2 Sala Guardiano] -- statua lanciafiamme
|
||||
|
|
||||
[1.3 Sala Monumentale]
|
||||
|
|
||||
[1.4 Sala Visioni] --- [1.5 Sepoltura Capo]
|
||||
| |
|
||||
[1.6 Vasca Osservazione] ----+
|
||||
| |
|
||||
[1.7 Stanza Strategia] ------+
|
||||
|
|
||||
[1.8 Esercito Terracotta]
|
||||
|
|
||||
[1.9 Sala Tesoro]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 10. Idempotenza e Retry
|
||||
|
||||
### 10.1 Idempotenza
|
||||
```
|
||||
cache_key = campaign_id:turn_id:tool_name:args_hash
|
||||
if cache_key in result_cache:
|
||||
return result_cache[cache_key]
|
||||
result = execute_tool(args)
|
||||
result_cache[cache_key] = result # TTL: 3600s
|
||||
return result
|
||||
```
|
||||
|
||||
### 10.2 Retry
|
||||
```
|
||||
max_attempts: 3
|
||||
backoff_base: 2 # esponenziale
|
||||
jitter: full # random 0..interval
|
||||
interval_seconds: 2
|
||||
```
|
||||
|
||||
### 10.3 Safe Fallback
|
||||
Se tutti i retry falliscono: narrazione safe. "Un'esitazione perplessa
|
||||
attanaglia l'ambiente mentre le forze arcane si riassestano..."
|
||||
Nessuna perdita di stato. Turno recuperabile.
|
||||
|
||||
---
|
||||
|
||||
## 11. Sicurezza e Robustezza
|
||||
|
||||
- **Tool allowlist**: LLM non puo chiamare funzioni non autorizzate
|
||||
- **Validazione input**: ogni tool valida i parametri ricevuti
|
||||
- **DM-Override loggato**: trail audit per ogni modifica manuale
|
||||
- **Backup SQLite**: copia del database a ogni sessione
|
||||
- **Niente dipendenze cloud**: tutto on-premise su Proxmox
|
||||
|
||||
---
|
||||
|
||||
## 12. Prossimi Step Implementativi
|
||||
|
||||
1. Setup progetto Python (FastAPI + SQLite + state machine)
|
||||
2. Implementazione Approved Tools (10 funzioni core)
|
||||
3. Integrazione Ollama (gemma2:9b per narrazione IT)
|
||||
4. Prompt engineering: system context + tool calling
|
||||
5. Interfaccia web (chat + pannello stato personaggi)
|
||||
6. DM-Override: pulsante e comandi
|
||||
7. Mappatura avventura: 9 aree + quest driade
|
||||
8. Test: run-through completo dell'avventura
|
||||
9. Documentazione utente
|
||||
Reference in new issue
Block a user