# Setup Guide

## Prerequisiti

- Python 3.10+
- Ollama (opzionale, per LLM locale) OPPURE una API key di OpenRouter
- Browser moderno

## Installazione

### 1. Clona il repository

```bash
git clone <repo-url> rpg
cd rpg
```

### 2. Crea ambiente virtuale

```bash
python3 -m venv .venv
source .venv/bin/activate
```

### 3. Installa dipendenze

```bash
pip install fastapi uvicorn httpx
```

## Configurazione LLM

### Opzione A: Ollama (locale, CPU-only)

```bash
# Installa Ollama (se non già presente)
curl -fsSL https://ollama.com/install.sh | sh

# Scarica il modello
ollama pull gemma2:9b
```

Configurazione (tramite env var):
```bash
export DCC_LLM_PROVIDER=ollama
export DCC_OLLAMA_URL=http://192.168.0.50:11434  # default
export DCC_OLLAMA_MODEL=gemma2:9b                # default
```

### Opzione B: OpenRouter

```bash
export DCC_LLM_PROVIDER=openrouter
export DCC_OPENROUTER_KEY=sk-or-v1-...
export DCC_OPENROUTER_MODEL=openrouter/free      # default
```

### Opzione C: OpenAI-compatible (LLM server locale)

```bash
export DCC_LLM_PROVIDER=local
export DCC_LOCAL_URL=http://<host>:<port>/v1
export DCC_LOCAL_KEY=...
export DCC_LOCAL_MODEL=<model-name>
```

## Avvio

### Sviluppo

```bash
python -m src.web.server
```

Il server parte su `http://0.0.0.0:8300`.

Oppure direttamente con uvicorn:
```bash
uvicorn src.web.server:app --host 0.0.0.0 --port 8300 --reload
```

### Prima campagna

1. Apri `http://localhost:8300` nel browser
2. Inserisci nome campagna e clicca "Crea"
3. Verrà creato automaticamente un PG di default (guerriero lv1)
4. Inizia a giocare! Scrivi "Cerco nella stanza" o "Attacco" o "Esploro"

## CLI Interattiva (senza browser)

Per test rapidi senza browser:

```bash
python -c "
from src.engine import dm, db
db.init_db()
camp_id = db.create_campaign('Test', 'Tomba del Mago-Guerriero')
char_id = db.create_character(camp_id, 'Marco il Fidato', 'guerriero', 'soldato')
db.update_character(char_id, level=1, str=15, agi=11, sta=14, per=9, int=8, lck=10, hp_current=12, hp_max=12, ac=15)
dm.interactive(camp_id)
"
```

## Health Check

```bash
curl http://localhost:8300/health
# → {"status":"ok","provider":"ollama"}
```

## Environment Variables (riepilogo)

| Variabile | Default | Descrizione |
|---|---|---|
| `DCC_LLM_PROVIDER` | `"openrouter"` | Provider LLM: ollama, openrouter, local |
| `DCC_OLLAMA_URL` | `http://192.168.0.50:11434` | URL server Ollama |
| `DCC_OLLAMA_MODEL` | `"gemma2:9b"` | Modello Ollama |
| `DCC_OPENROUTER_KEY` | `""` | API key OpenRouter |
| `DCC_OPENROUTER_MODEL` | `"openrouter/free"` | Modello OpenRouter |
| `DCC_OR_FREE_FALLBACK` | `"1"` | Fallback a modelli free |
| `DCC_LOCAL_URL` | `http://192.168.0.240/v1` | URL server locale |
| `DCC_LOCAL_KEY` | `""` | API key server locale |
| `DCC_LOCAL_MODEL` | `"big-pickle"` | Modello locale |
| `DCC_LLM_TIMEOUT` | `60` | Timeout chiamate LLM (s) |

## Troubleshooting

### "Nessuna campagna" all'avvio
- Creare una campagna dal frontend (form "Crea")
- Il database viene creato automaticamente

### LLM non risponde
- Verificare che Ollama sia in esecuzione: `ollama list`
- Verificare timeout: potrebbe servire `DCC_LLM_TIMEOUT=120`
- Il fallback heuristico interviene automaticamente se LLM fallisce

### WebSocket non si connette
- Verificare che il server sia raggiungibile
- Il frontend ha auto-reconnect ogni 3 secondi

### "pip install" bloccato da PEP 668
Usare ambiente virtuale (`.venv`) o:
```bash
pip install --break-system-packages fastapi uvicorn httpx
```