# JJ - Strato agentico

Domande in italiano sui dati aziendali.

**Cosa ci guadagni.** Chi non sa usare un database ottiene numeri affidabili, con tabella e grafico.

# JJ1 - A cosa serve

# JJ1.1 - Fare una domanda e avere un numero

**In una frase.** L'Assistente dei dati risponde in italiano alle domande sui dati dell'azienda, con un testo, una tabella e un grafico.

«Quanto abbiamo ordinato a quel fornitore quest'anno?» Per saperlo, prima serviva qualcuno che conoscesse le tabelle del gestionale e sapesse interrogarle. Con l'Assistente dei dati scrivi la domanda come la faresti a un collega. Lui la trasforma in una ricerca, la esegue e ti mostra il risultato.

L'assistente non indovina. Lavora su una copia dei dati fatta apposta per lui, i **Dati spiegati**, dove ogni tavola ha un nome chiaro e un significato scritto e controllato da persone. Ogni numero della risposta viene da una ricerca fatta davvero su quei dati.

![Alcuni degli argomenti che l'assistente conosce: consegne, ordini, acquisti, vendite. A schermo l'assistente è chiamato «agente»](https://gsdoc.genesyssoftware.eu/uploads/images/gallery/2026-11/alcuni-degli-argomenti-che-lassistente-conosce-consegne-ordini-acquisti-vendite-a-schermo-lassistente-e-chiamato-agente.png)

*Alcuni degli argomenti che l'assistente conosce: consegne, ordini, acquisti, vendite. A schermo l'assistente è chiamato «agente»*

<p class="callout success">**Cosa ci guadagni.**  
• **Numeri senza saper usare un database.** Scrivi in italiano. Ricevi il numero, la tabella con le righe e, se serve, un grafico a linee o a barre.  
• **Numeri affidabili.** L'assistente dice quale definizione ha usato, per quale periodo e a che data sono aggiornati i dati. Se i dati non bastano, lo dice.  
• **Significati scritti dalle persone.** Cosa vuol dire «acquisto» o «giacenza» sta in un catalogo che si legge e si corregge. Una correzione approvata vale per tutte le domande che seguono. </p>

Il primo argomento coperto è il **riordino**: acquisti, ordini a fornitori e di clienti, consegne, giacenze, volantini. Altri argomenti si aggiungono chiedendo un dato nuovo dal catalogo.

<div drawio-diagram="2794"><img src="https://gsdoc.genesyssoftware.eu/uploads/images/drawio/2026-11/da-una-domanda-a-una-risposta-chi-lavora-in-ordine.png" alt="Da una domanda a una risposta: chi lavora, in ordine"/></div>

*Da una domanda a una risposta: chi lavora, in ordine*

<p class="callout warning">**Attenzione.** La chat dell'assistente è ancora da accendere nell'ambiente di prova interno. I Dati spiegati e il catalogo ci sono già e si usano. Come si accende: [Accendere la chat](https://gsdoc.genesyssoftware.eu/link/37905).</p>

<p class="callout info">**Nota.** L'assistente legge soltanto. Non può cambiare nessun dato, né nei Dati spiegati né nel gestionale.</p>

<p class="callout info">**Per chi sviluppa.** L'assistente è SigeAgent, un servizio Python in `backend/middleware/sigeagent`. Un solo agente con tre strumenti: eseguire una ricerca, mostrare il risultato, proporre di salvare una domanda riuscita. Il codice è in `backend/middleware/sigeagent/src/sigeagent/agente.py`.</p>

<p class="callout info">**Per approfondire.**  
• SigeAgent, cos'è e dove guardare: `backend/middleware/sigeagent/README.md`</p>

# JJ1.2 - Dove sta nella mappa

**In una frase.** Lo Strato agentico è fatto di tre tessere: l'Assistente dei dati, l'intelligenza artificiale che capisce la domanda e i Dati spiegati.

Sapere dove sta spiega due cose: perché l'assistente non può rovinare niente, e da dove vengono i suoi numeri.

<div drawio-diagram="2795"><img src="https://gsdoc.genesyssoftware.eu/uploads/images/drawio/2026-11/la-mappa-di-adswnext-con-lo-strato-agentico-e-i-dati-spiegati-accesi.png" alt="La mappa di ADSWnext con lo Strato agentico e i Dati spiegati accesi"/></div>

*La mappa di ADSWnext con lo Strato agentico e i Dati spiegati accesi*

**Chi lo chiama.** Lo chiami tu, dalla chat delle pagine nuove (SIGEAnext). La domanda passa dal Gateway, che controlla chi sei e la consegna all'assistente. Dallo stesso ingresso passano le pagine del catalogo, dove si legge e si corregge quello che l'assistente sa.

**Chi chiama lui.** Due soli: l'**intelligenza artificiale**, a cui manda la domanda e i significati del catalogo per farsi preparare la ricerca, e i **Dati spiegati**, dove esegue la ricerca in sola lettura.

**Cosa non fa.** Non legge i Dati aziendali e non li modifica mai. I Dati spiegati li riempie una copia notturna, che dai Dati aziendali legge soltanto: vedi [I dati spiegati: la copia notturna](https://gsdoc.genesyssoftware.eu/link/37896).

<p class="callout info">**Nota.** Se l'assistente è spento, il resto di ADSWnext lavora come sempre: nessun altro servizio dipende da lui.</p>

<p class="callout info">**Per chi sviluppa.** Il Gateway manda a SigeAgent la chat (`/api/sigea-cop/ai/agent/stream`) e `/api/sigeagent/**` solo con `SIGEAGENT_ENABLED=true`(classe `GatewayConfig` in `backend/middleware/it_gsba_api_gateway`). I Dati spiegati sono un MySQL 8.4 proprio del servizio, senza porte pubblicate.</p>

# JJ2 - Come ragiona

# JJ2.1 - I dati spiegati: la copia notturna

**In una frase.** Ogni notte i dati del gestionale vengono copiati in un archivio ordinato, con nomi in italiano: l'assistente legge solo quello.

Le tabelle del gestionale non si spiegano da sole. Hanno nomi in sigla, centinaia di colonne e nessun collegamento dichiarato fra una tabella e l'altra. Chi ci fa una ricerca senza conoscerle sbaglia senza accorgersene. Per questo l'assistente non le tocca: lavora su una copia già riordinata.

<div drawio-diagram="2796"><img src="https://gsdoc.genesyssoftware.eu/uploads/images/drawio/2026-11/dai-dati-aziendali-ai-dati-spiegati-la-copia-notturna.png" alt="Dai Dati aziendali ai Dati spiegati: la copia notturna"/></div>

*Dai Dati aziendali ai Dati spiegati: la copia notturna*

**Cosa fa la copia.** Legge i Dati aziendali, senza scrivere niente. Tiene solo le righe che in azienda si chiamano davvero con quel nome: per esempio, fra tutti i movimenti di magazzino, solo i carichi da acquisto. Dà a tavole e colonne nomi chiari (`articolo`, `fornitore`, `giacenza_giornaliera`) e scrive i collegamenti fra loro. Le regole sono applicate qui, una volta, e non a ogni domanda.

**Quando.** La copia parte da sola ogni notte, alle 02:30 se non si sceglie un altro orario. Alla fine scrive un riepilogo: per ogni gruppo di dati dice se è andato bene o se è stato saltato perché nel gestionale quelle tabelle non ci sono.

**Come sai se i dati sono freschi.** Per ogni tavola resta scritta la data fino a cui i dati sono caricati. L'assistente la conosce e la dichiara nella risposta.

![La pagina «Da dove viene (ERP)» del catalogo: per ogni tabella del gestionale, quale tavola dell'assistente alimenta](https://gsdoc.genesyssoftware.eu/uploads/images/gallery/2026-11/la-pagina-da-dove-viene-erp-del-catalogo-per-ogni-tabella-del-gestionale-quale-tavola-dellassistente-alimenta.png)

*La pagina «Da dove viene (ERP)» del catalogo: per ogni tabella del gestionale, quale tavola dell'assistente alimenta*

<p class="callout info">**Nota.** I Dati spiegati sono indietro al massimo di un giorno. Per una domanda sul «proprio adesso» vale ancora la schermata del gestionale.</p>

<p class="callout info">**Per chi sviluppa.** La copia è l'ETL in `backend/middleware/sigeagent/etl` (`python -m etl tutto`). Legge SIGEA2 con la stessa connessione di SIGEAnext, in transazioni di sola lettura. L'orario è `SIGEAGENT_ETL_ORA_NOTTURNA`. I caricamenti sono registrati nella tavola `caricamento_etl`.</p>

<p class="callout info">**Per approfondire.**  
• Lo schema dei Dati spiegati: `backend/middleware/sigeagent/docs/SCHEMA.md`</p>

# JJ2.2 - Cosa sa e cosa non sa

**In una frase.** L'assistente sa quello che è scritto nel catalogo: tavole, significati e regole. Quello che non è scritto, non lo inventa.

Un numero sbagliato detto con sicurezza fa più danni di un «non lo so». Per questo l'assistente ha confini chiari, e li dichiara.

**Cosa sa.** Il primo argomento è il riordino: articoli, fornitori e clienti; acquisti; ordini a fornitori e ordini dei clienti; consegne ai clienti; vendite mensili; giacenze giorno per giorno; volantini e prezzi di listino. Per ognuno il catalogo dice a cosa serve, cosa rappresenta una riga e cosa **non** contiene.

**Le regole.** Le parole del lavoro hanno una definizione scritta: cosa conta come «acquisto», quando un ordine a fornitore è «aperto», come si misura la «copertura» o la «rottura di stock». Se la tua domanda usa una di queste parole, l'assistente applica la regola e la dichiara in una frase.

![Una regola del catalogo aperta: il testo che l'assistente applica, con lo stato «verificato»](https://gsdoc.genesyssoftware.eu/uploads/images/gallery/2026-11/una-regola-del-catalogo-aperta-il-testo-che-lassistente-applica-con-lo-stato-verificato.png)

*Una regola del catalogo aperta: il testo che l'assistente applica, con lo stato «verificato»*

**Cosa non sa.**

- Quello che non è nei Dati spiegati. Se una tavola o una colonna non c'è, l'assistente spiega cosa manca.
- I significati non verificati. Nel catalogo un significato può essere ignoto, un'ipotesi, verificato o smentito. All'assistente arriva solo ciò che è verificato.
- Il presente esatto. I dati sono quelli dell'ultima copia notturna.
- I dati delle persone. I Dati spiegati sono pensati senza email, telefoni e indirizzi.

**Quanto può cercare.** Per ogni domanda fa poche ricerche mirate, ognuna con un tempo massimo e un numero massimo di righe. Se la domanda è troppo larga, conviene restringerla.

<p class="callout info">**Nota.** Un dato che manca si può chiedere: vedi [Chiedere un dato nuovo](https://gsdoc.genesyssoftware.eu/link/37901).</p>

<p class="callout info">**Per chi sviluppa.** Le regole sono in `backend/middleware/sigeagent/semantica/regole.md` (R-01 e seguenti), le schede delle tavole nella stessa cartella. Limiti di una ricerca: una sola `SELECT`, al massimo 1000 righe, 30 secondi; al massimo 20 passi per domanda (`backend/middleware/sigeagent/src/sigeagent/config.py`).</p>

# JJ2.3 - Perché non vede i dati grezzi

**In una frase.** L'assistente e l'intelligenza artificiale non entrano mai nei Dati aziendali: lavorano solo sui Dati spiegati, in sola lettura.

È una scelta di sicurezza e di qualità insieme. Di sicurezza, perché fra l'assistente e il gestionale non c'è nessuna strada. Di qualità, perché sui dati grezzi le risposte sarebbero spesso sbagliate.

**Tre protezioni, una sopra l'altra.**

1. **Un archivio a parte.** I Dati spiegati sono separati dai Dati aziendali. L'assistente conosce solo quelli.
2. **Un utente che può solo leggere.** L'assistente entra nei Dati spiegati con un utente a cui scrivere non è permesso.
3. **Un controllo su ogni ricerca.** Prima di eseguirla, l'assistente verifica che sia una sola ricerca di lettura, con un limite di righe. Tutto il resto viene rifiutato.

**Cosa vede l'intelligenza artificiale.** Riceve la tua domanda e i significati del catalogo, e prepara la ricerca. Poi, per scrivere la risposta, riceve un'anteprima del risultato: le prime righe. La tabella completa arriva alla tua pagina direttamente dall'assistente. Le tabelle del gestionale il modello non le vede mai.

**Perché i dati grezzi darebbero risposte peggiori.** Nel gestionale il nome di una colonna può ingannare. Una che sembra «marca» è compilata solo su una piccola parte degli articoli: una classifica delle vendite per marca costruita lì sarebbe sbagliata, e nessuno se ne accorgerebbe. Nei Dati spiegati una colonna entra solo quando una persona ne ha verificato il significato.

<p class="callout info">**Nota.** La domanda che scrivi parte verso il modello così com'è. Non metterci nomi di persone o altri dati riservati che non servono.</p>

<p class="callout info">**Per chi sviluppa.** Utente di database di sola lettura; controllo delle ricerche in `backend/middleware/sigeagent/src/sigeagent/sql_sicuro.py`; il modello vede le prime 50 righe di ogni risultato (`backend/middleware/sigeagent/src/sigeagent/strumenti.py`). Fornitore del modello e spesa: [Tetto di spesa e riservatezza](https://gsdoc.genesyssoftware.eu/link/37906).</p>

# JJ3 - Il catalogo

# JJ3.1 - Cosa sa l'assistente, tavola per tavola

**In una frase.** Il catalogo è la pagina dove leggi, tessera per tessera, quello che l'assistente conosce e quello che gli manca.

Un assistente che risponde sui dati vale quanto ciò che sa dei dati. Qui quel sapere non è nascosto in un programma: è scritto in schede che chiunque può leggere, e che le persone correggono.

1. **Apri il catalogo.** Si chiama **Catalogo semantico**. La prima linguetta è **Cosa sa l'agente**: a schermo l'assistente è chiamato «agente».
2. **Leggi le tessere.** Ogni tessera è una tavola dei Dati spiegati. Sono divise in tre gruppi: **Dimensioni** (chi, dove, cosa: articolo, fornitore, cliente), **Fatti** (quanto e quando: consegne, ordini, giacenze) e **Viste** (risposte già pronte per una regola). La tessera dice in due righe cos'è la tavola e cosa le manca, per esempio «2 colonne senza significato».
    
    ![La pagina «Cosa sa l'agente»: una tessera per ogni tavola, con quello che manca](https://gsdoc.genesyssoftware.eu/uploads/images/gallery/2026-11/la-pagina-cosa-sa-lagente-una-tessera-per-ogni-tavola-con-quello-che-manca.png)
    
    *La pagina «Cosa sa l'agente»: una tessera per ogni tavola, con quello che manca*
3. **Guarda la riga in alto.** Dice quale rilascio l'assistente sta usando, quante correzioni approvate aspettano il prossimo rilascio e quante proposte aspettano una decisione.
4. **Apri una scheda.** Un clic sulla tessera apre la scheda della tavola. In alto, «Come la legge l'agente»: a cosa serve, cosa rappresenta una riga, i sinonimi che capisce, le note d'uso, a quali tavole si collega e quali regole la citano. A destra, «Da dove viene»: da quali tabelle del gestionale nasce e quando è stata caricata l'ultima volta. Sotto, le colonne, ognuna con il suo significato e il suo stato.
    
    ![La scheda della tavola «articolo»: come la legge l'assistente e da dove viene. Dati di prova](https://gsdoc.genesyssoftware.eu/uploads/images/gallery/2026-11/la-scheda-della-tavola-articolo-come-la-legge-lassistente-e-da-dove-viene-dati-di-prova.png)
    
    *La scheda della tavola «articolo»: come la legge l'assistente e da dove viene. Dati di prova*

<p class="callout info">**Nota.** Le altre linguette: **Da dove viene (ERP)** mostra le tabelle del gestionale e quanto se ne è capito; **Regole** le definizioni delle parole del lavoro; **Proposte** e **Rilasci** come cambia il catalogo.</p>

<p class="callout info">**Per chi sviluppa.** Lo Studio del catalogo è in `frontend/ade-next/src/studio/catalogo-semantico`; i dati arrivano da `/api/sigeagent/catalogo`, servito da `backend/middleware/sigeagent/src/sigeagent/catalogo_api.py`.</p>

<p class="callout info">**Per approfondire.**  
• Il disegno del catalogo: `backend/middleware/sigeagent/docs/DISEGNO_CATALOGO.md`</p>

# JJ3.2 - Correggere un significato

**In una frase.** Se una scheda dice una cosa sbagliata o poco chiara, la correggi sul posto: la correzione entra nel prossimo rilascio.

L'assistente risponde in base a quello che legge nelle schede. Una nota d'uso imprecisa diventa una risposta imprecisa, ogni volta. Correggerla una volta sistema tutte le domande che seguono.

1. **Scrivi il tuo nome in «Firmi come».** Resta scritto chi corregge.
2. **Apri la scheda e premi «Correggi».** Vale per la scheda di una tavola, per una colonna e per una regola. I testi diventano campi da modificare.
3. **Cambia il testo.** Sotto il campo vedi la differenza evidenziata: parola per parola, con barrato quello che togli. Così controlli la modifica prima di salvarla.
    
    ![«Correggi» aperto sulla scheda di una tavola: sotto il testo, la differenza evidenziata](https://gsdoc.genesyssoftware.eu/uploads/images/gallery/2026-11/correggi-aperto-sulla-scheda-di-una-tavola-sotto-il-testo-la-differenza-evidenziata.png)
    
    *«Correggi» aperto sulla scheda di una tavola: sotto il testo, la differenza evidenziata*
4. **Scegli come chiudere.**
    
    
    - **Salva**: la correzione è proposta e approvata nello stesso momento, con la tua firma.
    - **Chiedi a un collega**: crei solo la proposta. Serve scrivere il perché, in una riga. Decide un'altra persona.
    - **Annulla**: non cambia niente.
5. **Fai il rilascio.** Dopo «Salva» un avviso dice: «Entra nel prossimo rilascio: da lì l'agente la usa». Finché il rilascio non c'è, l'assistente continua a leggere il testo di prima. Vedi [Proposte e rilasci](https://gsdoc.genesyssoftware.eu/link/37902).

<p class="callout info">**Nota.** Correggere un testo non rende la scheda meno sicura: una scheda «verificata» resta verificata.</p>

<p class="callout warning">**Attenzione.** Cambiare il significato è una cosa. Cambiare **da dove nasce** un dato è un'altra: tocca la copia notturna e passa da chi sviluppa. Vedi [Chiedere un dato nuovo](https://gsdoc.genesyssoftware.eu/link/37901).</p>

<p class="callout info">**Per chi sviluppa.** Il componente è `frontend/ade-next/src/studio/catalogo-semantico/ui/correggi.component.ts`. «Salva» crea e decide la proposta in una sola transazione; le proposte sono gestite in `backend/middleware/sigeagent/catalogo`.</p>

# JJ3.3 - Chiedere un dato nuovo

**In una frase.** Se all'assistente manca un dato, lo chiedi dal catalogo con un percorso guidato: la richiesta diventa una proposta che qualcuno decide e chi sviluppa realizza.

L'assistente risponde solo su quello che ha. Quando una domanda utile resta senza risposta perché il dato non c'è, la strada non è una telefonata: è una richiesta scritta, con il perché, che non si perde.

1. **Premi «Chiedi un dato nuovo».** Il pulsante è in alto in ogni pagina del catalogo.
2. **Scegli cosa ti serve.** Le strade sono due:
    
    
    - **concetto nuovo**: una cosa che l'assistente oggi non conosce, cioè una tavola intera;
    - **dato in più**: una colonna in più su una tavola che ha già.
    
    Se non sai quale, parti dalla domanda a cui vuoi una risposta.
3. **Segui i passi.** Per un dato in più sono cinque: su quale concetto, cos'è, da dove viene nel gestionale, a cosa punta, perché serve. A destra il riquadro «La proposta finora» si riempie mentre scrivi.
    
    ![Il percorso «Chiedi un dato nuovo», al passo «Cos'è»: a destra la proposta che si riempie e le regole del catalogo](https://gsdoc.genesyssoftware.eu/uploads/images/gallery/2026-11/il-percorso-chiedi-un-dato-nuovo-al-passo-cose-a-destra-la-proposta-che-si-riempie-e-le-regole-del-catalogo.png)
    
    *Il percorso «Chiedi un dato nuovo», al passo «Cos'è»: a destra la proposta che si riempie e le regole del catalogo*
4. **Invia.** Nasce una proposta. La trovi nella pagina **Proposte**, fra quelle da decidere.
5. **Aspetta chi sviluppa.** Un dato nuovo cambia la struttura dei Dati spiegati. Dopo l'approvazione, chi sviluppa lo aggiunge alla copia notturna e ai suoi controlli. Solo allora entra in un rilascio e l'assistente lo usa.

<p class="callout info">**Nota.** Le regole del catalogo sono scritte nel riquadro a destra: il nome di una colonna non è una prova; decide una persona e resta scritto chi; nei Dati spiegati entra solo ciò che è verificato.</p>

<p class="callout info">**Nota.** Nel catalogo c'è anche la pagina **Assistente**: una chat che indaga sul catalogo e sui dati e prepara la proposta. La proposta la scrivi comunque tu, con **Procedi** e la tua firma. Senza la sua chiave la pagina dice «non configurato».</p>

<p class="callout info">**Per chi sviluppa.** Dalla proposta approvata, **Esporta l'incarico per chi sviluppa** scarica un file con il lavoro da fare: migrazione, passo della copia notturna con il suo controllo, test. A lavoro finito, in **Proposte** si preme **Segna applicata**. Il percorso è in `frontend/ade-next/src/studio/catalogo-semantico/proponi`.</p>

# JJ3.4 - Proposte e rilasci

**In una frase.** Nel catalogo niente cambia da solo: ogni modifica è una proposta, una persona la decide, un rilascio numerato la porta all'assistente.

È quello che rende affidabili le risposte. Sai sempre chi ha cambiato un significato, quando e perché. E sai con quale versione del catalogo l'assistente sta rispondendo.

<div drawio-diagram="2803"><img src="https://gsdoc.genesyssoftware.eu/uploads/images/drawio/2026-11/proposta-decisione-rilascio-la-strada-di-ogni-modifica-del-catalogo.png" alt="Proposta, decisione, rilascio: la strada di ogni modifica del catalogo"/></div>

*Proposta, decisione, rilascio: la strada di ogni modifica del catalogo*

1. **Guarda la linea delle proposte.** Nella pagina **Proposte** ogni proposta va da sinistra a destra: da decidere, approvate, in assestamento (quelle che aspettano chi sviluppa), nel rilascio. A parte, le chiuse: rifiutate o ritirate.
    
    ![La pagina «Proposte»: una proposta va da sinistra a destra e si ferma dove serve una persona](https://gsdoc.genesyssoftware.eu/uploads/images/gallery/2026-11/la-pagina-proposte-una-proposta-va-da-sinistra-a-destra-e-si-ferma-dove-serve-una-persona.png)
    
    *La pagina «Proposte»: una proposta va da sinistra a destra e si ferma dove serve una persona*
2. **Decidi una proposta.** Aprila. In alto c'è la domanda che ti viene fatta. Sotto, «Cosa cambia»: il testo di oggi e quello che avresti se approvi, uno accanto all'altro. Poi la prova e il perché. Premi **Approva**, oppure **Rifiuta** scrivendo il motivo. Chi l'ha proposta può anche ritirarla.
    
    ![Una proposta da decidere: la domanda, cosa cambia, la prova](https://gsdoc.genesyssoftware.eu/uploads/images/gallery/2026-11/una-proposta-da-decidere-la-domanda-cosa-cambia-la-prova.png)
    
    *Una proposta da decidere: la domanda, cosa cambia, la prova*
3. **Crea il rilascio.** Nella pagina **Rilasci** leggi in parole cosa conterrebbe il prossimo rilascio. Premi **Crea il rilascio** con il suo numero: da quel momento l'assistente lo usa.
    
    ![La pagina «Rilasci»: cosa conterrebbe il prossimo rilascio e il pulsante per crearlo](https://gsdoc.genesyssoftware.eu/uploads/images/gallery/2026-11/la-pagina-rilasci-cosa-conterrebbe-il-prossimo-rilascio-e-il-pulsante-per-crearlo.png)
    
    *La pagina «Rilasci»: cosa conterrebbe il prossimo rilascio e il pulsante per crearlo*
4. **Controlla la riga in alto.** In ogni pagina del catalogo dice «L'agente usa il rilascio» con numero e data. Un rilascio raccoglie più correzioni insieme.

<p class="callout info">**Nota.** L'intelligenza artificiale può preparare una proposta, ma non decide mai: decide una persona.</p>

<p class="callout info">**Per chi sviluppa.** Nella pagina **Rilasci**, la sezione chiusa «Per il low-code» pubblica un rilascio intero nel registro di ADEnext. Prima il rilascio va misurato sul banco: un insieme di domande con la risposta attesa già nota, in `backend/middleware/sigeagent/banco`. Si pubblica se il risultato non peggiora. Decisioni in `backend/middleware/sigeagent/docs/DECISIONI.md`.</p>

<p class="callout info">**Per approfondire.**  
• Il disegno del catalogo: `backend/middleware/sigeagent/docs/DISEGNO_CATALOGO.md`</p>

# JJ4 - Usarlo

# JJ4.1 - Fare una buona domanda

**In una frase.** Una domanda precisa su cosa, quando e dove riceve un numero giusto al primo colpo.

L'assistente capisce l'italiano di tutti i giorni. Ma più la domanda è chiara, meno deve scegliere lui al posto tuo. Bastano cinque abitudini.

<p class="callout warning">**Attenzione.** La chat è ancora da accendere: questa pagina descrive come si comporta l'assistente, non una schermata che puoi già aprire. Manca per questo la schermata della chat.</p>

1. **Scrivi tutto in una domanda.** Ogni domanda vale per sé: l'assistente non ricorda quella di prima. Non scrivere «e l'anno scorso?», ma la domanda intera.
2. **Di' il periodo.** «Nel 2026», «a marzo», «negli ultimi 30 giorni». Senza periodo ne sceglie uno lui, e lo dichiara: controlla che sia quello che volevi.
3. **Usa i codici.** Articoli, fornitori e clienti si riconoscono dal loro codice del gestionale. «Il fornitore 33000123» è sicuro, un nome scritto a memoria no.
4. **Usa le parole del lavoro.** «Rottura di stock», «copertura», «ordini aperti», «giacenza»: per queste parole il catalogo ha una regola scritta, e l'assistente la applica. La trovi nella linguetta **Regole**del catalogo.
5. **Chiedi una cosa per volta.** Una domanda stretta ha una risposta completa. Una domanda larghissima («tutto sui fornitori») può fermarsi a metà.

Qualche esempio sul riordino, il primo argomento coperto:

- «Cosa stiamo aspettando dal fornitore 33000123?»
- «Quali articoli hanno avuto la giacenza a zero a ottobre 2026?»
- «Quanto abbiamo comprato per mese nel 2026? Fammi un grafico.»
- «Quali articoli erano in volantino a settembre e quanto hanno venduto?»

<p class="callout info">**Nota.** Per le giacenze, se non indichi un deposito, l'assistente usa quello principale della ditta e lo scrive nella risposta.</p>

<p class="callout info">**Nota.** Non scrivere nella domanda nomi di persone o dati riservati che non servono: il testo parte verso il modello così com'è.</p>

<p class="callout info">**Per chi sviluppa.** Le istruzioni che l'assistente segue sono in `backend/middleware/sigeagent/src/sigeagent/agente.py`. Una domanda può essere lunga al massimo 4000 caratteri. Il deposito principale è la regola R-13 in `backend/middleware/sigeagent/semantica/regole.md`.</p>

# JJ4.2 - Leggere la risposta

**In una frase.** La risposta ha tre parti: i passi che l'assistente ha fatto, la tabella o il grafico, e un testo che dice come è stato calcolato il numero.

Un numero da solo non basta per decidere. Serve sapere cosa conta, per quale periodo e a che data. La risposta dell'assistente porta sempre queste informazioni: leggerle richiede dieci secondi.

<p class="callout warning">**Attenzione.** La chat è ancora da accendere: manca per questo la schermata di una risposta. Quello che segue è ciò che il servizio produce.</p>

**I passi.** Mentre lavora, la chat mostra cosa sta facendo, per esempio «Sto interrogando i dati». Di solito bastano da una a quattro ricerche.

**Il risultato.** Può essere un valore solo, una tabella o un grafico a linee o a barre. La tabella porta tutte le righe trovate, fino a mille. Sotto può esserci una nota con le definizioni usate, il periodo e il deposito.

**Il testo.** Poche righe con cinque cose:

- la risposta;
- la definizione usata, se la domanda conteneva una parola come «rottura» o «copertura»;
- il periodo considerato;
- il deposito;
- la data a cui sono aggiornati i dati.

**Cosa controllare.** Che periodo e definizione siano quelli che intendevi. Che la data dei dati sia recente: se è vecchia di giorni, la copia notturna non sta girando. Che i codici in tabella siano quelli che ti aspetti.

**Se la risposta è parziale.** Quando la domanda è troppo larga l'assistente si ferma e lo dice: quello che ha mostrato è parziale. Riprova con una domanda più circoscritta.

**Se i dati non bastano.** L'assistente lo dice e spiega cosa manca. È il momento di [chiedere un dato nuovo](https://gsdoc.genesyssoftware.eu/link/37901).

<p class="callout info">**Nota.** Prima della prima domanda la chat mostra un avviso: quale servizio di intelligenza artificiale viene usato, in quale regione, e che i risultati sono suggerimenti da verificare prima di usarli.</p>

<p class="callout info">**Per chi sviluppa.** Tabella, valore e grafico sono i widget della chat, prodotti da `backend/middleware/sigeagent/src/sigeagent/widget.py`. Un grafico disegna una serie sola: con più serie la chat mostra un grafico per serie.</p>

# JJ5 - Per chi amministra

# JJ5.1 - Accendere la chat

**In una frase.** L'assistente si accende in due tempi: prima il servizio con i suoi dati e il catalogo, poi, con un interruttore sul Gateway, la chat.

L'assistente è spento finché non lo accendi tu. I due tempi servono a non mostrare a nessuno una chat che risponde su dati vuoti: prima si preparano e si controllano i dati, poi si apre la porta.

<p class="callout warning">**Attenzione.** Nell'ambiente di prova interno il servizio, i Dati spiegati e il catalogo sono accesi. La chat è ancora da accendere: l'ultimo passo qui sotto.</p>

1. **Prepara i segreti.** Nel file dei segreti del server metti il blocco dell'assistente: le password dei suoi archivi e la chiave del servizio di intelligenza artificiale. L'interruttore della chat resta spento.
2. **Accendi il servizio.** Con il rilascio del server partono due programmi: l'assistente e il suo archivio. Nessuno dei due è raggiungibile da fuori. Se manca una password, il rilascio si ferma subito e dice quale.
3. **Crea gli archivi vuoti.** Una volta sola: le tavole dei Dati spiegati e quelle del catalogo.
4. **Carica i dati.** Il primo caricamento si lancia a mano. In fondo scrive un riepilogo: controlla che dica «ok». Da lì in poi parte da solo ogni notte.
5. **Riempi il catalogo e fai un rilascio.** Il catalogo rilegge i Dati spiegati e le schede; poi si crea il primo rilascio numerato. Apri il catalogo e controlla che le tessere ci siano.
6. **Accendi la chat.** Metti l'interruttore `SIGEAGENT_ENABLED` a `true` e rilancia il rilascio del server. Il Gateway riparte e manda la chat all'assistente.

**Come controlli.** Nel registro del Gateway compare «SigeAgent acceso». I due programmi risultano in salute. Nella chat l'etichetta del servizio di intelligenza artificiale è quella dell'assistente.

**Per spegnere.** Rimetti l'interruttore a `false` e rilancia: la chat torna com'era prima. I dati e il catalogo restano.

<p class="callout info">**Nota.** Il catalogo contiene il lavoro delle persone: va salvato con una copia di sicurezza. I Dati spiegati no: si ricostruiscono con un nuovo caricamento.</p>

<p class="callout info">**Per chi sviluppa.** Profilo `sigeagent` del compose di deploy, servizi `sigeagent` (porta interna 8765) e `sigeagent-mysql`. Con l'interruttore acceso il Gateway instrada `/api/sigea-cop/ai/agent/stream`, `/ai/agent/fornitore` e `/api/sigeagent/**`. Con l'interruttore acceso ma il profilo spento, la chat dice «AI non abilitata». Comandi, uno per uno: `devops/deploy/README.md`, paragrafo 3.6. Variabili: `docs/devops/ENVIRONMENT.md`.</p>

<p class="callout info">**Per approfondire.**  
• Deploy, paragrafo 3.6 «SigeAgent: l'agente dei dati»: `devops/deploy/README.md`</p>

# JJ5.2 - Tetto di spesa e riservatezza

**In una frase.** L'assistente ha un tetto di spesa al giorno e regole precise su quali dati possono arrivare al servizio di intelligenza artificiale.

Ogni domanda costa qualcosa, perché usa un servizio esterno a pagamento. E ogni domanda manda fuori un po' di testo. Chi amministra deve poter rispondere a due domande: quanto si spende al massimo, e cosa esce.

**Il tetto di spesa.** L'assistente registra per ogni domanda modello, consumo, costo e durata. Prima di ogni nuova domanda somma la spesa del giorno: se ha raggiunto il tetto, non parte e la chat dice «Per oggi è stato raggiunto il tetto di spesa: riprova domani o chiedi di alzarlo». Il tetto predefinito è 5 dollari al giorno. C'è anche un limite di lavoro per singola domanda e un numero massimo di domande insieme.

**Cosa esce verso il modello.**

- La domanda, così come l'hai scritta.
- I significati del catalogo: nomi di tavole e colonne, regole.
- Un'anteprima dei risultati delle ricerche sui Dati spiegati: le prime righe.

**Cosa non esce.**

- I Dati aziendali: il modello non li vede e l'assistente non li legge.
- Dati di persone: i Dati spiegati sono pensati senza email, telefoni e indirizzi.

**Dove sta il modello.** La regola di ADSWnext per i dati dei clienti è: intelligenza artificiale spenta in partenza, e solo fornitori nell'Unione europea. L'assistente dichiara alla chat, prima di ogni invio, quale servizio usa e in quale regione: se non risponde, la chat non invia.

<p class="callout warning">**Attenzione.** Oggi l'assistente gira solo nell'ambiente di prova interno, con dati fittizi, e lì usa un instradamento non garantito nell'Unione europea: la chat lo dichiara. Prima di usarlo con i dati di un cliente vanno chiuse due cose: passare all'instradamento europeo e decidere come trattare i nomi scritti nelle domande, che oggi partono senza essere sostituiti.</p>

<p class="callout info">**Nota.** L'assistente che nel catalogo aiuta a preparare le proposte ha un tetto di spesa suo, separato.</p>

<p class="callout info">**Per chi sviluppa.** Tetto: `SIGEAGENT_TETTO_SPESA_GIORNALIERO_USD`. Instradamento europeo: l'impostazione `OPENROUTER_BASE_URL` del servizio va portata a `https://eu.openrouter.ai/api/v1`; il compose di deploy oggi non la passa. La dichiarazione del fornitore è l'endpoint `/ai/agent/fornitore` in `backend/middleware/sigeagent/src/sigeagent/web.py`. Regole generali e l'eccezione dell'assistente: `docs/ai/AI-CONFORMITA.md`.</p>

<p class="callout info">**Per approfondire.**  
• Informativa sull'intelligenza artificiale per il cliente: `docs/ai/INFORMATIVA-AI-CLIENTE.md`</p>

# JJ5.3 - Se qualcosa non va

**In una frase.** I problemi più comuni con l'assistente e con il catalogo, come «vedo questo, faccio questo», e le parole da sapere.

Quasi sempre l'assistente dice già cosa non va, in italiano. Qui trovi cosa fare dopo averlo letto.

## Nella chat

- **La chat non invia, o dice «AI non abilitata».** L'assistente è spento o acceso a metà. Avvisa chi amministra: vedi [Accendere la chat](https://gsdoc.genesyssoftware.eu/link/37905).
- **«Per oggi è stato raggiunto il tetto di spesa».** Riprova domani, o chiedi a chi amministra di alzarlo: vedi [Tetto di spesa e riservatezza](https://gsdoc.genesyssoftware.eu/link/37906).
- **«Ci sono già troppe domande in corso».** Aspetta qualche secondo e riprova.
- **«Ho raggiunto il limite di lavoro per una domanda».** Quello che vedi è parziale. Fai una domanda più stretta: un periodo, un fornitore, un gruppo di articoli.
- **Dice che i dati non bastano.** Il dato non è nei Dati spiegati. Chiedilo: vedi [Chiedere un dato nuovo](https://gsdoc.genesyssoftware.eu/link/37901).
- **Il numero non mi torna.** Leggi nel testo la definizione, il periodo e il deposito usati. Se la definizione è sbagliata, si corregge la regola nel catalogo.
- **I dati sono vecchi.** La risposta dice a che data sono aggiornati. Se è indietro di più giorni, la copia notturna non è riuscita: avvisa chi amministra.

## Nel catalogo

- **Ho corretto una scheda ma l'assistente risponde come prima.** Manca il rilascio. La riga in alto dice quante correzioni aspettano: premi **Rilascia** e crea il rilascio.
- **«Chiedi a un collega» non parte.** Scrivi il perché, in una riga.
- **La mia proposta è ferma «in assestamento».** È un dato nuovo: aspetta il lavoro di chi sviluppa.
- **La pagina «Assistente» dice «non configurato».** Manca la sua chiave: avvisa chi amministra.

## Per chi amministra

- **Il servizio non parte.** Di solito manca una password del suo archivio: il registro dell'archivio dice quale.
- **Il riepilogo della copia notturna segna un gruppo «saltato».** Nel gestionale mancano quelle tabelle. Gli altri dati sono caricati.

## Parole da sapere

- **Assistente dei dati.** Il servizio che risponde alle domande. A schermo, nel catalogo, è «l'agente».
- **Dati spiegati.** La copia ordinata dei dati aziendali, con nomi in italiano. L'assistente legge solo questa.
- **Copia notturna.** Il lavoro che ogni notte riempie i Dati spiegati.
- **Catalogo.** Le schede che dicono cosa significa ogni tavola e ogni colonna.
- **Tavola.** Un argomento dei Dati spiegati: articolo, fornitore, giacenza.
- **Regola.** La definizione scritta di una parola del lavoro, come «acquisto» o «copertura».
- **Stato.** Quanto è sicuro un significato: ignoto, ipotesi, verificato, smentito.
- **Proposta.** La richiesta di cambiare qualcosa nel catalogo. La decide una persona.
- **Rilascio.** Una versione numerata del catalogo. L'assistente usa l'ultima.
- **Tetto di spesa.** Il massimo che l'assistente può spendere in un giorno.

<p class="callout info">**Per chi sviluppa.** Esito dei caricamenti notturni: cartella dei log del servizio e tavola `caricamento_etl`. Messaggi della chat: `backend/middleware/sigeagent/src/sigeagent/flusso.py` e `backend/middleware/sigeagent/src/sigeagent/agente.py`. Stati a metà dell'accensione: `devops/deploy/README.md`, paragrafo 3.6.</p>