# DCC RPG — AI Dungeon Master: Documentazione

## Panoramica

Questo progetto implementa un **Dungeon Master virtuale** per il gioco di ruolo
**Dungeon Crawl Classics** (regolamento introduttivo italiano). Il sistema usa un
LLM (Ollama/OpenRouter) per la narrazione e l'interpretazione delle azioni,
mentre un motore Python deterministico gestisce le meccaniche di gioco
(tiri, combattimento, inventario).

**Pattern architetturale**: Neon Scratch Lounge (separazione Reasoning/Execution)
**Avventura**: La Tomba del Mago Guerriero (9 aree)
**Target**: On-premise, CPU-only, singolo giocatore, browser

## Documenti

| File | Contenuto |
|---|---|
| `architecture.md` | Architettura, pattern NSL, data flow, flusso turno |
| `codebase-reference.md` | Tutti i moduli, API pubbliche, entry point |
| `database-schema.md` | Schema SQLite, tabelle, migrazioni, CRUD |
| `setup-guide.md` | Come avviare, configurare, connettere LLM |
| `adventure-data.md` | Struttura dati avventura, aree, mostri, enigmi |
| `game-mechanics.md` | Regole DCC implementate (dadi, classi, combattimento) |
| `development-guide.md` | Come estendere: nuovi tool, provider, aree |

## Stack Tecnologico

| Componente | Tecnologia |
|---|---|
| LLM | Ollama (gemma2:9b) / OpenRouter / OpenAI-compatible |
| Backend | Python 3.10+ + FastAPI + uvicorn |
| Frontend | HTML + CSS + JS vanilla |
| Database | SQLite (WAL mode) |
| HTTP | httpx (LLM calls) |
| WebSocket | FastAPI WebSocket (real-time game) |

## Scheletro del Turno

```
Giocatore "Cerco nella stanza"
  → LLM reasoning (prompt + contesto)
  → LLM risponde: {"tool": "ability_check", "params": {...}, "narration": "..."}
  → Esecuzione tool deterministico
  → Persistenza stato (SQLite)
  → Risposta al giocatore (narrazione + meccaniche)
```

## Struttura Directory

```
rpg/
├── src/
│   ├── engine/       # Core game engine (DM, LLM, tools, dice, DB)
│   └── web/          # FastAPI server + frontend statico
├── data/             # SQLite DB, avventura JSON, tabelle critici
├── docs/             # Design doc originale
├── docs_dev/         # Questa documentazione
├── knowledge/        # 15 file knowledge base DCC
├── input/            # PDF sorgente, reference booklet
├── ocr_full/         # OCR output files
├── graphify-out/     # Grafo concettuale (62 nodi)
└── tests/            # Test (da popolare)
```

## Stato Progetto (CHECKLIST.md)

**Fasi completate:**
- ✅ Pattern architetturale NSL analizzato e documentato
- ✅ OCR pipeline (22 screenshot + 41 pagine PDF = ~58K parole)
- ✅ Pulizia OCR (60 correzioni dadi, 11 testuali)
- ✅ Knowledge Base strutturata (15 file, ~3708 righe)
- ✅ Grafo concettuale (Graphify, 62 nodi, 27 archi)
- ✅ Avventura completata (9 aree + background)

**Fase 0-4 implementata (codice):**
- ✅ Backend core: DM cycle, tool registry, dice engine
- ✅ LLM integration: multi-provider, prompt template, parser
- ✅ Dati adventure machine-readable: JSON aree/mostri/quest
- ✅ DB schema: 8 tabelle, CRUD, migrazioni
- ✅ Frontend: WebSocket, chat, stato personaggio, mappa
- ✅ Heuristic fallback: keyword parser per quando LLM fallisce