AgileTavs — Guida operativa (HELP)

Questa guida permette di verificare tutto senza leggere il codice. È servita

anche su /help. Base URL pubblica: https://agiletavs.agile.software (in locale:

http://localhost:8000). Negli esempi usiamo BASE come segnaposto.

---

Percorso di giuria (in una sola sessione, dalla landing page)

Il copione della seduta finale. Un utente demo è già pronto: nome utente demo

(accettato anche demo@agile.software), password AgileTavs. La giuria NON si

registra: entra.

1. Landing page → Accedi. Apri https://agiletavs.agile.software/: è la landing

commerciale (cos'è, cosa fa, invito ad accedere). Clicca «Accedi» e inserisci

demo / AgileTavs. Via API:

```bash

curl -X POST "$BASE/account/login" -H "Content-Type: application/json" \

-d '{"utente":"demo","password":"AgileTavs"}'

# -> {"ok":true,"email":"demo@agile.software","nome":"Demo","username":"demo","token":"..."}

```

**Il token restituito dal login (o dalla registrazione, che fa auto-accesso) va

passato alle chiamate del conto** (/account/avatar, /account/conto): senza

token rispondono 401. Password errata → 401 (non 200) con il motivo.

2. Galleria degli avatar. Dopo il login sei nell'area del conto (/account): la

galleria mostra le tre persone digitali inventate (volto fotorealistico, nome,

ruolo, tono, voce) con ritratto e breve video di presentazione, e i tuoi avatar

salvati. Per ciascuna c'è il pulsante «Conversa» che apre la videochat.

3. Crea il tuo avatar (salvato). Dal pulsante «Crea il mio avatar» si apre la

sala di registrazione nel sito (/registra): registra 20–30 s di video parlando

(webcam + microfono), oppure carica una foto (campo foto) con un eventuale

campione voce (campo audio, alias accettato voce: prima il solo voce

veniva ignorato in silenzio), e con un clic il sistema clona volto e voce e **salva

l'avatar nel conto**, con un nome scelto da te. Riaprendo il sito l'avatar è ancora

lì. Via API (da una sola foto, con o senza campione voce; TOKEN è quello del

login):

```bash

curl -X POST "$BASE/account/avatar" \

-F "email=demo@agile.software" -F "token=$TOKEN" -F "nome=Il mio avatar" \

-F "foto=@foto.jpg" -F "audio=@voce.wav"

# -> {"ok":true,"avatar":{"id":"av_...","nome":"Il mio avatar",...}, "voci":{...}}

curl -s "$BASE/account/avatar?email=demo@agile.software&token=$TOKEN"

# -> {"ok":true,"avatar":[...]}

```

Cancellare un avatar dal conto (volto + voce + derivati, senza sporcare la

galleria):

```bash

curl -X DELETE "$BASE/account/avatar/AV_ID?email=demo@agile.software&token=$TOKEN"

# -> {"ok":true,"avatar":"av_..."}

```

Pulire il conto demo (rimuove avatar e chiavi di collaudo, idempotente):

```bash

curl -X POST "$BASE/account/pulisci-demo"

# -> {"ok":true,"avatar_rimossi":N}

```

4. Conversa con gli avatar. Dalla galleria (i tre + il tuo) scegli un avatar e

conversa a voce in videochat (/demo): ascolta, risponde in video con

sottotitoli, e la vista (webcam) è attiva — l'avatar tiene conto di ciò che vede.

Il tuo avatar parla con il tuo volto e la tua voce. Con un avatar salvato la

sessione si apre così:

```bash

curl -X POST "$BASE/v1/sessioni" -H "X-API-Key: <tua-chiave>" \

-F "avatar=AV_ID" -F "voce=if_sara" -F "lingua=it"

# -> {"id":"sess_...","stato":"pronto"}

```

5. Scarica la API key e usala da applicazioni esterne. Nell'area conto, sezione

API: genera/scarica la propria chiave e trova esempi pronti in curl, Python

e JavaScript (browser, CORS abilitato) per elenco persone, sessione, parla, conversa

e vede. La chiave è mostrata una sola volta.

---

Inizia in 5 minuti

1. Ottieni una chiave API: il percorso pubblico è self-service (vedi sotto

«Percorso utente self-service»): registrati, applica il codice promo AGILE2026

e genera la chiave dal tuo conto. Per il collaudo esiste già una chiave di prova

seminata: agiletavs-demo-2026.

2. Apri una sessione avatar:

```bash

curl -X POST "$BASE/v1/sessioni" -H "X-API-Key: agiletavs-demo-2026" \

-F "persona=aria-volta" -F "voce=if_sara" -F "lingua=it"

# -> {"id":"sess_...","stato":"pronto"}

```

3. Fai parlare l'avatar (testo → video):

```bash

curl -X POST "$BASE/v1/sessioni/SESS_ID/parla" -H "X-API-Key: agiletavs-demo-2026" \

-F "testo=Ciao! Sono AgileTavs." -o parla.mp4

```

4. Fai conversare l'avatar (audio → risposta video):

```bash

curl -X POST "$BASE/v1/sessioni/SESS_ID/conversa" -H "X-API-Key: agiletavs-demo-2026" \

-F "audio=@banco/dataset/domanda.wav" -o conversa.mp4

```

5. Prova la vista (fotogramma → descrizione filtrata):

```bash

curl -X POST "$BASE/v1/sessioni/SESS_ID/vede" -H "X-API-Key: agiletavs-demo-2026" \

-F "fotogramma=@banco/dataset/persona.jpg"

# -> {"descrizione":"Rilevo una persona di fronte alla telecamera."}

curl -X POST "$BASE/v1/sessioni/SESS_ID/vede" -H "X-API-Key: agiletavs-demo-2026" \

-F "fotogramma=@banco/dataset/documento.jpg"

# -> {"descrizione":"Rilevo un documento, non ne leggo il contenuto."}

```

---

Percorso utente self-service (in un'unica sessione)

Non serve l'amministratore: un visitatore del sito si registra da solo, sceglie la

persona digitale, la «acquista» con un codice promo (checkout simulato, nessun

pagamento reale) e genera la propria API key. Tutto dalla pagina /account (UI)

oppure via curl.

1. Registrati (email + nome, dati fittizi ammessi):

```bash

curl -X POST "$BASE/account/registra" -H "Content-Type: application/json" \

-d '{"email":"cliente@esempio.it","nome":"Mario Rossi"}'

# -> {"ok":true,"email":"cliente@esempio.it","nome":"Mario Rossi",...}

```

2. Scegli la persona fra le tre inventate (senza chiave):

```bash

curl -s "$BASE/account/persone"

# -> {"persone":[{"id":"aria-volta","nome":"Aria Volta","ruolo":"assistente commerciale",...}, ...]}

```

3. Acquista con il codice promo AGILE2026 (azzera il prezzo di listino 19 EUR/mese):

```bash

curl -X POST "$BASE/account/acquista" -H "Content-Type: application/json" \

-d '{"email":"cliente@esempio.it","persona":"aria-volta","codice_promo":"AGILE2026"}'

# -> {"ok":true,"prezzo":"0 EUR (azzerato dal promo)",...}

```

4. Genera la tua API key (dal tuo conto, dopo l'acquisto; mostrata una sola volta):

```bash

curl -X POST "$BASE/account/chiave" -H "Content-Type: application/json" \

-d '{"email":"cliente@esempio.it"}'

# -> {"ok":true,"chiave":"agiletavs_...","quota":1000}

```

5. Usala su /v1 (persone, sessione, parla, conversa, vede):

```bash

curl -s "$BASE/v1/persone" -H "X-API-Key: agiletavs_..."

```

Il riepilogo del conto (senza chiavi in chiaro): GET /account/conto?email=...&token=...

(serve il token del login). Il codice promo accettato è AGILE2026 (vedi api/account.py).

---

1. Ottenere una chiave (portale amministratore o self-service)

conto (vedi «Percorso utente self-service»): non serve l'amministratore.

le chiavi. Le credenziali dell'amministratore non sono pubblicate (vengono

generate al primo avvio e salvate in api/data/portale.json): il percorso pubblico

è quello self-service, senza admin.

qualsiasi momento. Il registro d'uso mostra ogni chiamata (ora, chiave, percorso, esito).

Ogni chiamata a /v1/* richiede l'intestazione X-API-Key: <chiave>.

2. Persone digitali (tutte inventate)

GET /v1/persone (con chiave) elenca le persone disponibili:

curl -s "$BASE/v1/persone" -H "X-API-Key: agiletavs-demo-2026"

curl -X POST "$BASE/v1/riferimenti" -H "X-API-Key: agiletavs-demo-2026" \
  -F "file=@foto.jpg"   # -> {"id":"rif_..."}

curl -X DELETE "$BASE/v1/sessioni/SESS_ID" -H "X-API-Key: agiletavs-demo-2026"
# -> {"stato":"chiusa"}

curl -s -o /dev/null -w "%{http_code}\n" "$BASE/v1/riferimenti/RIF_ID" \
  -H "X-API-Key: agiletavs-demo-2026"   # 200 = esiste ancora · 404 = cancellato

./banco/su-pod.sh        # rsync + make pesi + unshare -n banco/prova.py

make collaudo-pubblico SITO=https://agiletavs.agile.software

curl -X POST "$BASE/v1/registrazione" -H "X-API-Key: agiletavs-demo-2026" \
  -F "video=@registrazione.webm"
# -> {"id":"sess_...","riferimento_id":"rif_...","voce_riferimento_id":"rif_...","motion_id":"rif_..."}

curl -X POST "$BASE/v1/sessioni/SESS_ID/parla" -H "X-API-Key: agiletavs-demo-2026" \
  -F "testo=Ciao, sono io!" -o clonato.mp4

curl -X POST "$BASE/v1/sessioni" -H "X-API-Key: agiletavs-demo-2026" \
  -F "riferimento=RIF_FOTO_ID" -F "voce_riferimento=@voce.wav"

{
  "voci": {"voci": 2, "dominante": 1,
           "parlanti": [{"indice":1,"durata_s":18.4,"percentuale":70.1,"segmenti":5},
                        {"indice":2,"durata_s":7.8,"percentuale":29.9,"segmenti":3}],
           "report": "Ho trovato 2 voci: uso la voce dominante (70.1% del parlato)."}
}

# sala di registrazione via API: scegli la voce 2
curl -X POST "$BASE/v1/registrazione" -H "X-API-Key: agiletavs-demo-2026" \
  -F "video=@registrazione.webm" -F "parlante=2"

# sessione con campione voce separato e scelta della voce
curl -X POST "$BASE/v1/sessioni" -H "X-API-Key: agiletavs-demo-2026" \
  -F "riferimento=RIF_FOTO_ID" -F "voce_riferimento=@voce.wav" -F "parlante=2"

curl -X POST "$BASE/account/avatar/AV_ID/parlante" -H "Content-Type: application/json" \
  -d '{"parlante": 2}'
# oppure null per tornare alla scelta automatica (dominante):
# curl -X POST "$BASE/account/avatar/AV_ID/parlante" -H "Content-Type: application/json" \
#   -d '{"parlante": null}'