feat: initial DCC RPG knowledge base + AI DM design

2026-06-25 20:32:05 +02:00
commit ae73fe43d3
@@ -0,0 +1,152 @@
+# DCC RPG — Dungeon Crawl Classics (Regolamento Introduttivo)
+
+## Stato del Progetto
+
+Estrazione, analisi e progettazione di un sistema ibrido AI DM per il regolamento
+introduttivo di **Dungeon Crawl Classics GdR**, basato sul pattern architetturale
+**"Neon Scratch Lounge"** (Separazione Reasoning/Execution).
+
+---
+
+## ✅ Attività Completate
+
+### 1. Pattern Architecturale: Neon Scratch Lounge
+- Analizzato `articolo.md` e clonato repo `~/.graphify/repos/chaotictoejam/neon-scratch-lounge`
+- Pattern: separazione ragionamento LLM → stato SQLite → 10 Approved Tools
+- Design doc architetturale scritto: `docs/plans/2026-06-25-dcc-rpg-design.md` (314 righe)
+- Stack target on-premise: Python + SQLite (anziché AWS Step Functions + DynamoDB)
+
+### 2. PDF OCR Pipeline
+- **22 screenshot** (59MB) OCRizzati con Tesseract 5 + italiano
+- **PDF 41 pagine** (18MB) convertito in PNG con `pdftoppm` e OCRizzato
+- **58.558 parole** totali in `ocr_full/dcc_completo.txt`
+- **Scoperti 3 PDF inglesi machine-readable** in `input/`:
+  - Reference Booklet (230KB, 2818 righe) — tutte le tabelle in inglese
+  - Adventure Starter (62KB) — avventura alternativa
+  - Core Rulebook (43MB, 498 pag) — immagini, richiederebbe OCR separato
+
+### 3. Pulizia OCR
+- Analizzati e corretti **60 errori di notazione dadi** (1420→1d20 x34, 1416→1d16 x6, 146→1d6 x5, 138→1d8 x3, ecc.)
+- Corretti **11 errori di riconoscimento caratteri** (Sa→Da, Salla→dalla, ecc.)
+- File pulito salvato come `ocr_full/dcc_completo_ripulito.txt`
+- Nota: il file originale contiene pagine scansionate 2x (contenuto duplicato)
+
+### 4. Knowledge Base Strutturata (15 file, ~3708 righe)
+| File Argomento | Contenuto |
+|---|---|
+| `01_meccanica_base.md` | Sistema d20, CD, CA, catena dadi |
+| `02_creazione_personaggio.md` | Fasi lv0, allineamento, **tabella mestieri d100 tradotta** |
+| `03_classi.md` | **7 classi** (Chierico, Ladro, Guerriero, Mago, Nano, Elfo, Halfling) + abilità ladro + Mighty Deeds |
+| `04_combattimento.md` | Iniziativa, azioni, danni, guarigione |
+| `05_equipaggiamento.md` | **Armi (22), armature (10+scudo), equipaggiamento (d24), cavalcature, monete** — tradotto |
+| `06_critici_danni_ocr.md` | **Fumble (17 voci), Critici I-V (95 voci)** — tradotto |
+| `07_incantesimi.md` | Risultati incantesimi, corruzione, ritorsione |
+| `08_abilita_thc.md` | CD, tiri abilità, tiri salvezza (Tempra/Riflessi/Volontà) |
+| `09_equipaggiamento_avventura.md` | Equipaggiamento da avventura |
+| `10_avventura.md` | **Avventura completa: 9 aree + background (pag. 39)** — aree 1.1/1.3/1.9 scritte ex-novo |
+| `11_monster_ocr.md` | Creature dell'avventura |
+| `12_tesoro_magia.md` | Oggetti magici, tesori |
+| `15_dadi.md` | Catena dadi DCC |
+
+### 5. Grafo Concettuale (Graphify)
+- Graphify configurato con Google AI Studio API key
+- Extraite: **62 nodi, 27 archi** in `graphify-out/graph.json` (~$0.09 costo totale)
+- Chunking automatico file >200KB in blocchi ~10KB
+
+### 6. Avventura Completata
+- **Pagina 39 scritta ex-novo**: Vorkhul Ksh'tharan, il Vincolato alle Stelle — background dello sciamano Halfling che ha stretto un patto con un'intelligenza aliena
+- **Area 1.1**: Portale — allineamento celeste, enigma costellazioni, trappola gravitazionale
+- **Area 1.3**: Sala Monumentale — 7 pilastri, guardiano spettrale, primo frammento nome
+- **Area 1.9**: Sala del Tesoro — corpo del mago-guerriero, nome completo rivelato, quest secondaria della driade
+- **9 aree totali** mappate in `10_avventura.md` (463 righe)
+
+---
+
+## 🔧 Dati e File
+
+| Cartella/File | Descrizione | Dimensione |
+|---|---|---|
+| `ocr_full/dcc_completo.txt` | OCR originale unificato (italiano) | 58.558 parole |
+| `ocr_full/dcc_completo_ripulito.txt` | OCR pulito (60 correzioni dadi + 11 testuali) | 58.558 parole |
+| `input/reference_booklet.txt` | Reference Booklet inglese (tabelle) | 230KB / 2818 righe |
+| `input/adventure_starter.txt` | Adventure Starter inglese | 62KB |
+| `input/DCC_RPG_Core_Rulebook.pdf` | Core Rulebook (immagini, 498 pag) | 43MB |
+| `knowledge/` | 15 file knowledge base strutturati | ~3708 righe totali |
+| `graphify-out/graph.json` | Grafo concettuale (62 nodi, 27 archi) | ~$0.09 |
+| `docs/plans/2026-06-25-dcc-rpg-design.md` | Design doc architetturale | 314 righe |
+| `CHECKLIST.md` | Checklist priorità (~18-25h per MVP) | — |
+| `README.md` | Questo file | — |
+
+---
+
+## 🏗️ Architettura Target (Neon Scratch Lounge) — On-Premise
+
+
+
+```
+┌─────────────────────────────────────────────────┐
+│                    GIOCATORE                      │
+│              (interfaccia web/testuale)            │
+└──────────────────┬──────────────────────────────┘
+                   │
+┌──────────────────▼──────────────────────────────┐
+│                   LLM (AI DM)                     │
+│      - Narrazione e descrizione ambienti          │
+│      - Interpretazione azioni giocatore           │
+│      - Decisione quali strumenti chiamare         │
+└──────────────────┬──────────────────────────────┘
+                   │
+┌──────────────────▼──────────────────────────────┐
+│              Step Functions (Flusso)              │
+│   Turno → Interpreta → Esegui tool → Risultato   │
+└──────────────────┬──────────────────────────────┘
+                   │
+┌──────────────────▼──────────────────────────────┐
+│        Approved Tools (Lambda Functions)          │
+│  ┌─────────┐ ┌──────────┐ ┌──────────────────┐  │
+│  │ Tiro    │ │ Movimento│ │ Combattimento     │  │
+│  │ Dadi    │ │          │ │ (Iniziativa, Att, │  │
+│  │         │ │          │ │  Danno, Critico)   │  │
+│  └─────────┘ └──────────┘ └──────────────────┘  │
+│  ┌─────────┐ ┌──────────┐ ┌──────────────────┐  │
+│  │ Incante-│ │ Abilità  │ │ DM-Override       │  │
+│  │ simi    │ │ (Furtivo,│ │ (deroga manuale)  │  │
+│  │         │ │  Percep.)│ │                   │  │
+│  └─────────┘ └──────────┘ └──────────────────┘  │
+└──────────────────┬──────────────────────────────┘
+                   │
+┌──────────────────▼──────────────────────────────┐
+│                  DynamoDB (Stato)                 │
+│  - Personaggi (statistiche, PE, equipaggiamento) │
+│  - Stato avventura (stanze visitate, NPC vivi)  │
+│  - Turno corrente                                │
+└─────────────────────────────────────────────────┘
+```
+
+### Idempotenza
+- Ogni tool deterministico (stessi input = stesso output)
+- Retry con full jitter per fault tolerance
+- DynamoDB letto a inizio turno, scritto dopo esecuzione tool
+
+---
+
+## ⏭️ Prossimi Passi
+
+1. **Fase 0 — Setup Progetto**: `git init`, struttura directory (src/, tests/, data/), requirements.txt, start.sh
+2. **Fase 1 — Backend Core**: state machine, SQLite schema, 10 Approved Tools (roll-dice, combat, etc.)
+3. **Fase 2 — LLM Integration**: client Ollama (gemma2:9b), template prompt, parser output
+4. **Fase 3 — Dati Adventure Machine-Readable**: JSON aree/mostri/oggetti/quest
+5. **Fase 4 — Frontend**: pagina singola HTML/CSS/JS + WebSocket backend
+6. **Opzionale — Core Rulebook OCR**: 498 pag immagini da OCRizzare (~8h stimati)
+
+---
+
+## ⚠️ Note
+
+- OCR è stato eseguito con Tesseract 5 + italiano su immagini a 300 DPI
+- La qualità OCR è buona ma non perfetta (alcuni artefatti su pagine con sfondi scuri)
+- PyMuPDF non disponibile (ambiente managed), usato pdftoppm via CLI
+- Graphify configurato con Google AI Studio e funzionante (62 nodi, $0.09)
+- Pattern "Neon Scratch Lounge" già analizzato e adattato per stack on-premise
+- Tabelle Reference Booklet usate come sorgente primaria (vs OCR) per dati meccanici
+- `pip install` bloccato da PEP 668 — installare pacchetti di sistema via apt/poetry