# Guida utente AgilePersona (AgileTavA)

AgilePersona è un avatar conversazionale sovrano: ascolto, cervello, voce, volto e vista
girano **solo su motori nostri** (pesi aperti, licenze commerciali in `docs/LICENZE.md`),
senza alcuna chiamata a servizi esterni. Questa guida permette di verificare TUTTO dal
sito pubblico e dalle API, senza leggere il codice.

Sito pubblico: `https://agiletava.agile.software` (stessa macchina che serve questa pagina:
`GET /help`).

## 1. Percorso di giuria nel sito (cinque passi, senza registrarsi)

1. **Landing** — apri `https://agiletava.agile.software/`: pagina commerciale con il
   pulsante **Accedi** e l'anteprima della galleria.
2. **Accesso** — in `/accedi` entra con l'utente demo pre-creato: nome utente `demo`
   (va bene anche `demo@agile.software`), password `AgileTavA` (il nome del prodotto).
3. **Conto** — `/conto` mostra: la **galleria** delle tre persone digitali inventate
   (ritratto fotorealistico, ruolo, tono e **video di presentazione** di ciascuna) più gli
   avatar creati da te; il pulsante **Crea il mio avatar**; la sezione **La tua chiave
   API** (l'utente demo ha già un acquisto attivo, quindi la chiave si genera subito);
   la sezione **Usa la tua chiave da fuori** con esempi curl / Python / JavaScript già
   con la tua chiave inserita; il **registro d'uso** della chiave.
4. **Crea il mio avatar** — `/crea` è la sala di registrazione dentro il sito:
   «Accendi camera e microfono», «● Registra» per 20-30 s mentre parli, poi «Crea
   l'avatar»: cloniamo volto e voce da quel video e l'avatar resta salvato nel conto
   (riaprendo il sito è ancora lì). In alternativa si carica un file: video `webm`/`mp4`
   registrati dal browser, oppure una foto `jpg`/`png` (qualità inferiore) con un audio
   `wav`/`mp3` di voce. Se nella registrazione parlano più voci, il sistema le separa e
   dichiara quante ne ha trovate prima di clonare.
5. **Parla con gli avatar** — dalla galleria («Conversa in videochat») o da `/demo/`:
   videochat con microfono, videocamera, sottotitoli e pulsante Termina; l'avatar
   ascolta, risponde in video e tiene conto di ciò che vede dalla tua webcam. La demo è
   pilotata SOLO dalle API pubbliche con `X-API-Key` (nessun CDN).

## 2. Percorso self-service (registrazione → promo → chiave)

Chi non usa l'utente demo si registra da solo; l'acquisto è **fittizio** (nessun
pagamento reale), sbloccato da un codice promo:

```bash
SITO=https://agiletava.agile.software
# 1. registrazione: restituisce un token di sessione
curl -s -X POST $SITO/registrazione -H 'Content-Type: application/json' \
     -d '{"email":"mia@mail.example","nome":"Mia","password":"password123"}'
# 2. acquisto fittizio con codice promo (listino 49,00 EUR; PROMO123 e AGILE2026 lo
#    azzerano, PROVA50 sconto 50%): servono il token del passo 1
curl -s -X POST $SITO/applica-promo -H "Authorization: Bearer $TOKEN" \
     -H 'Content-Type: application/json' -d '{"codice":"PROMO123"}'
# 3. chiave API: mostrata UNA sola volta (nel database resta solo l'hash)
curl -s -X POST $SITO/genera-api-key -H "Authorization: Bearer $TOKEN" \
     -H 'Content-Type: application/json' -d '{"nome":"mia chiave","quota_giorno":200}'
```

Senza acquisto attivo `/genera-api-key` risponde `403`; i codici accettati sono elencati
da `GET /promo`.

## 3. Contratto API (prefisso `/v1`, intestazione `X-API-Key`)

Tutte le chiamate sotto `/v1` (e le scorciatoie `/parla`, `/conversa`, `/vede`) vogliono
`X-API-Key: <chiave>`; senza chiave → `401`. `GET /salute` è pubblico.

```bash
K='X-API-Key: la-tua-chiave'
# elenco persone (le tre inventate + i tuoi avatar salvati)
curl -s -H "$K" $SITO/v1/persone
# carica un riferimento (foto o breve video): resta sul nostro disco, mai all'esterno
curl -s -H "$K" -F "file=@volto.jpg" $SITO/v1/riferimenti
# sessione
curl -s -H "$K" -H 'Content-Type: application/json' \
     -d '{"persona":"alex","riferimento":"ID_DEL_RIFERIMENTO","voce":"it","lingua":"it"}' \
     $SITO/v1/sessioni
# parla: testo → mp4 con il volto che parla
curl -s -H "$K" -H 'Content-Type: application/json' -d '{"testo":"Ciao, sono AgilePersona."}' \
     $SITO/v1/sessioni/ID/parla --output parla.mp4
# conversa: audio della domanda → mp4 con la risposta (ascolto→cervello→voce→volto)
curl -s -H "$K" -F "riferimento=@volto.jpg" -F "audio=@domanda.wav" $SITO/conversa \
     --output conversa.mp4 -D intestazioni.txt
# vede: fotogramma webcam → descrizione breve con filtro di non identificazione
curl -s -H "$K" -F "immagine=@fotogramma.jpg" $SITO/vede
# eventi della sessione (SSE): pronto, parla, fine, errore
curl -s -N -H "$K" $SITO/v1/sessioni/ID/eventi
# chiude e cancella i riferimenti dal volume di lavoro
curl -s -X DELETE -H "$K" $SITO/v1/sessioni/ID
```

Il CORS è abilitato su tutto `/v1`: gli esempi JavaScript del conto girano nel browser.
Le risposte di `/conversa` e `/v1/sessioni/{id}/conversa` portano intestazioni vere di
misura: `X-Tempo-Ascolto`, `X-Tempo-Cervello`, `X-Tempo-Voce`, `X-Tempo-Volto`,
`X-Tempo-Totale`, `X-Testo-Ascoltato`, `X-Risposta`, `X-Motore-Volto`
(`leggero-cpu` sul box, `latentsync-1.5` dove c'è una GPU con i pesi), `X-Voce-Clonata`.

## 4. Cosa aspettarsi (misurato sul box, 4 CPU senza GPU)

- Formato video: `video/mp4`, h264 + aac, 25 fps, lato 512 px.
- `/parla` con una frase: circa 4 s.
- `/conversa` con una domanda di ~4 s: circa 9 s totali (ascolto ~2 s, cervello ~3 s,
  voce ~2 s, volto ~2 s: i valori esatti sono nelle intestazioni di ogni risposta).
- `/vede`: meno di 1 s.
- Sul pod GPU la stessa catena usa LatentSync-1.5 per il labiale e chiude in meno tempo;
  il box senza GPU resta pienamente funzionante (è il motore leggero, dichiarato).
- Se un motore non ha i pesi, l'endpoint risponde `503` con il motivo: **nessun
  contenuto finto viene mai spacciato per vero**.

## 5. Errori e cosa significano

| codice | significato |
|---|---|
| 400 | richiesta incompleta (manca testo/audio/riferimento, file vuoto o illeggibile) |
| 401 | chiave assente, non valida o revocata (oppure token di sessione scaduto) |
| 403 | azione non permessa con questa chiave (es. generare chiavi senza acquisto attivo) |
| 404 | sessione o risorsa inesistente |
| 429 | quota giornaliera della chiave esaurita |
| 503 | motore non pronto: pesi mancanti (`make pesi`), mai un video di ripiego |

## 6. Rete chiusa: come si verifica

Dopo `make pesi` il sistema non scarica nulla a runtime. La prova vera si esegue sul pod
dentro un namespace di rete senza rotte verso l'esterno (`banco/rete-chiusa.sh`, con
`HF_HUB_OFFLINE=1 TRANSFORMERS_OFFLINE=1`): `make prova` sincronizza il repo, scarica i
pesi, avvia l'API nella rete chiusa, esegue percorso utente + `/parla` + `/conversa` +
`/vede` + metrica labiale e riporta in `banco/risultati/` il video e `prova.json`
(hostname del pod, uscita di `nvidia-smi`, tempi per anello, esito della rete chiusa).
Senza pod, `make prova` esegue le prove leggere sul box e scrive
`banco/risultati/prova-locale.json` (non tocca `prova.json`, che è la prova del pod).

## 7. Collaudo robotizzabile

Il piano eseguibile senza mani è `banco/collaudo-pubblico.yaml` (17 passi: registrazione,
promo, chiave, accesso demo, conto, landing, galleria, sala di registrazione, demo, uso
esterno della chiave, sessione, parla, conversa, vede, revoca → 401, quota → 429):

```bash
make collaudo-pubblico SITO=https://agiletava.agile.software
```

Stampa una riga verde/rossa per passo e l'esito finale; le variabili `${USER_TOKEN}`,
`${DEMO_TOKEN}`, `${API_KEY}` e `${SESSION_ID}` si popolano da sole dalle risposte dei
passi precedenti.

## 8. Motori e licenze (sintesi)

Voce Kokoro-82M (Apache-2.0) · ascolto faster-whisper small (MIT) · cervello
Qwen2.5-0.5B-Instruct (Apache-2.0) · vista Qwen3-VL-2B-Instruct (Apache-2.0, con visione
classica OpenCV di riserva sul box) · volto: motore leggero CPU sempre attivo e
LatentSync-1.5 (Apache-2.0) dove c'è una GPU · clonazione del timbro OpenVoice v2 (MIT) ·
separazione delle voci ECAPA-VoxCeleb + VAD (Apache-2.0) · volti delle persone inventate
generati con Stable Diffusion XL base 1.0 (OpenRAIL++-M) con seme fisso riproducibile
(`banco/dataset/persone/`). Tabella completa con fonti: `docs/LICENZE.md`; architettura e
motivazioni: `docs/ARCHITETTURA.md`.

## 9. Supporto

Documentazione OpenAPI (Swagger) su `/docs`; portale sviluppatori su `/portale`;
registro d'uso di ogni chiave nel conto e in `/v1/registro`.