# Manuale operativo per integrare Gemini API nel sistema AT Scuole

## 1. Obiettivo

Questo manuale spiega come collegare il sito “Manuale operativo Amministrazione Trasparente per le scuole” a un’intelligenza artificiale di proprietà o sotto controllo della scuola, ipotizzando l’uso delle API Google Gemini.

Il principio tecnico è semplice: l’AI deve rispondere usando la knowledge base `knowledge.md`, che resta modificabile dalla scuola.

## 2. Regola fondamentale di sicurezza

Non inserire mai la chiave API Gemini dentro `index.html` o in codice JavaScript pubblico.

La chiave deve stare solo lato server, per esempio:

- variabile d’ambiente `GEMINI_API_KEY`;
- file di configurazione non pubblico;
- secret manager del provider cloud;
- Apps Script / Cloud Run / server PHP protetto.

### 2.1 Proteggere l’endpoint dagli abusi (importante)

Un endpoint proxy pubblico, anche se non espone la chiave, può essere chiamato da chiunque conosca l’URL: in pratica terzi possono usare il credito/quota Gemini della scuola come servizio gratuito. Il proxy fornito (`gemini-proxy.php`) include alcune protezioni di base, configurabili tramite variabili d’ambiente:

- `ALLOWED_ORIGINS` — elenco delle origini autorizzate a chiamare l’endpoint, separate da virgola (es. `https://www.scuolaesempio.edu.it`). Se valorizzata, le richieste da altre origini vengono bloccate. Se vuota, sono ammesse solo richieste same-origin.
- `RL_MAX_REQUESTS` e `RL_WINDOW_SECONDS` — rate limiting per indirizzo IP (default: 20 richieste ogni 60 secondi).

Raccomandazioni aggiuntive per ambienti più esposti: collocare l’endpoint dietro autenticazione (area riservata) o un meccanismo anti-bot (es. captcha), servire sempre il sito in HTTPS, e monitorare i log e i consumi della console Google.

## 3. Architettura consigliata

Utente → sito web → endpoint server `/api/gemini-proxy.php` → Gemini API → risposta al sito

Il sito invia solo la domanda. Il server legge `knowledge.md`, seleziona i blocchi pertinenti e passa a Gemini un prompt limitato alla knowledge.

## 4. Passaggi operativi

1. Caricare sul server:
   - `index.html`
   - `knowledge.md`
   - cartella `assets`
   - cartella `api`
2. Creare una chiave Gemini in Google AI Studio o secondo le procedure Google/Workspace adottate dall’ente.
3. Salvare la chiave come variabile d’ambiente:
   - nome: `GEMINI_API_KEY`
4. Verificare che il file `api/gemini-proxy.php` non esponga la chiave.
5. Aprire il sito e impostare come endpoint:
   - `/api/gemini-proxy.php`
6. Fare una domanda di prova:
   - “Chi è il responsabile della pubblicazione in Amministrazione Trasparente?”
7. Verificare che la risposta indichi:
   - Dirigente scolastico;
   - fonte interna dal file `knowledge.md`;
   - eventuale necessità di verifica normativa.

## 5. Prompt istituzionale consigliato

Il proxy usa un prompt di questo tipo:

“Rispondi come assistente operativo per una scuola italiana. Usa esclusivamente la knowledge fornita. Se l’informazione non è presente o è incerta, dichiara che serve verifica su fonte ufficiale. Non inventare norme, scadenze o responsabilità. Ricorda che il responsabile della pubblicazione in Amministrazione Trasparente è il Dirigente scolastico.”

## 6. Privacy e cautele

Non inviare a Gemini:

- dati sanitari;
- dati di minori;
- dati giudiziari;
- graduatorie complete con codici fiscali o informazioni L. 104/1992;
- documenti interni non anonimizzati;
- segnalazioni disciplinari;
- dati personali non necessari.

Per richieste concrete, usare esempi anonimi.

## 7. Aggiornamento della knowledge

Quando cambia una fonte normativa o viene corretto un errore:

1. modificare `knowledge.md`;
2. salvare il file;
3. ricaricare il sito;
4. ripetere una domanda di test.

Il sito e Gemini devono leggere la stessa knowledge, evitando copie divergenti.

## 8. Modalità senza Gemini

Il sito funziona anche senza API. In questo caso usa la ricerca locale sul file `knowledge.md` e restituisce le voci più pertinenti. È meno discorsivo, ma più semplice e non comporta invio di dati a servizi esterni.

## 9. Nota didattica DM 219

Questo sistema può essere presentato come esempio di laboratorio formativo per personale ATA e scuole: partire da un bisogno amministrativo reale, costruire una knowledge base controllabile, generare un sito consultabile, integrare una AI controllata e mantenere sempre una revisione umana.