Vai al contenuto

AI Besant Safecondo Integration Plan - 2026-07-10

Scopo

Usare il motore AI locale come assistente operativo su tenant_besant e tenant_safecondo, mantenendo produzione protetta.

L'AI deve suggerire, spiegare e segnalare anomalie. Non deve modificare dati, categorie, documenti, checklist o file MinIO senza workflow approvativo.

Stato Attuale

Configurazione rilevata:

Tenant Stato AI attuale Note
tenant_besant abilitato in .env solo utente emma
tenant_safecondo abilitato in .env il 2026-07-10 solo utente emma
tenant_echos abilitato in .env solo utente emma, se presente

Utente pilota:

  • username: emma;
  • email rilevata: emanuele.matteucci@besantsrl.it;
  • username: jeme;
  • email rilevata: formazione@besantsrl.it;
  • abilitazione AI: solo se tenant e utente sono entrambi autorizzati.

Endpoint gia' disponibili:

  • /ai/assistant;
  • /api/ai/status;
  • /api/ai/chat.

Ingresso UI:

  • menu Produttivita -> Assistente AI;
  • visibile solo per tenant con AI abilitata e utente autorizzato;
  • attualmente limitato agli utenti emma e jeme su tenant_besant, tenant_echos, tenant_safecondo.

Provider configurato:

  • ollama;
  • base URL: http://192.168.192.162:11434;
  • modello: llama3.1:8b.

Principio Operativo

L'AI lavora come secondo livello di analisi:

  1. legge contesto gia' filtrato dal tenant;
  2. propone classificazioni o warning;
  3. restituisce motivazione leggibile;
  4. non applica la decisione;
  5. l'utente approva o corregge.

Besant

Priorita' Besant:

Area Uso AI Azione ammessa
Formazione riassunto corso, documenti, discenti, scadenze suggerimento
Archivio docenti descrizione dispense, appunti, materiali corso suggerimento
Documentazione corso riconoscimento tipo documento proposta categoria
DVR/documenti tecnici warning se fuori contesto formazione manual review
Evidence Hub spiegazione anomalie e documenti non categorizzati readonly

Regole Besant:

  • nessuna modifica automatica perche' Besant e' produzione;
  • non ricategorizzare automaticamente documenti formazione;
  • non collegare automaticamente file a corsi o discenti;
  • usare l'AI per preparare una proposta leggibile all'operatore.

Safecondo

Priorita' Safecondo:

Area Uso AI Azione ammessa
RAS Evidence Hub spiegare categorie tecniche RAS suggerimento
Immagini RAS segnalare ambiguita' e possibili incoerenze warning
Checklist dinamiche proporre sezioni o anomalie proposta
Documenti condominio individuare documento caricato in categoria errata warning
Extrabit descrizione pacchetti e payload solo Safecondo

Regole Safecondo:

  • prima abilitazione tenant in .env, poi restart controllato;
  • nessuna modifica automatica su categorie, documenti o MinIO;
  • Extrabit resta solo Safecondo;
  • i casi local:* e mapping ambiguo restano bloccati per scelta manuale.

Prompt Operativi Iniziali

Besant - Formazione

Input minimo:

  • tenant;
  • tipo oggetto;
  • nome documento/corso;
  • categoria attuale;
  • eventuale collegamento corso/discente/docente;
  • stato documento.

Output AI atteso:

  • sintesi;
  • categoria suggerita;
  • warning;
  • motivazione;
  • livello confidenza;
  • azione consigliata: nessuna, manual_review, proposta_categoria.

Safecondo - Evidence Hub

Input minimo:

  • tenant;
  • documento;
  • cliente/condominio;
  • minio key o tipo file;
  • categoria attuale;
  • classificazione dry-run;
  • warning gia' deterministico.

Output AI atteso:

  • descrizione operativa;
  • categoria tecnica proposta;
  • warning utente;
  • motivazione;
  • blocco se dato ambiguo;
  • nessuna azione automatica.

Sequenza Consigliata

  1. Usare Besant subito in lettura, perche' e' gia' abilitato.
  2. Preparare una vista o chiamata controllata che invia all'AI solo record gia' filtrati per tenant.
  3. Validare output su 5-10 casi Besant formazione/documenti.
  4. Abilitare tenant_safecondo in .env solo dopo conferma.
  5. Validare Safecondo su Evidence Hub, partendo da report dry-run e non da scritture.
  6. Solo dopo introdurre pulsanti tipo Suggerisci con AI, mai Applica con AI.

Criteri di Accettazione

  • l'AI non vede dati cross-tenant;
  • l'AI non scrive su DB;
  • l'AI non tocca MinIO;
  • l'AI produce sempre motivazione;
  • l'utente vede se il suggerimento e' manuale, tecnico o bloccante;
  • Safecondo non viene abilitato prima di una conferma esplicita;
  • Besant non subisce ricategorizzazioni automatiche.

Decisione

Il collegamento va fatto prima su Besant in modalita' assistente readonly.

Safecondo e' stato aggiunto alla configurazione AI dopo verifica di raggiungibilita' del motore Ollama.

Esito Abilitazione Safecondo - 2026-07-10

Verifiche eseguite:

  • Ollama attivo sulla macchina NVIDIA 192.168.192.162;
  • servizio in ascolto su porta 11434;
  • modello disponibile: llama3.1:8b;
  • SafeOps raggiunge http://192.168.192.162:11434/api/tags;
  • tenant_safecondo aggiunto a SAFEOPS_AI_ENABLED_TENANTS;
  • SAFEOPS_AI_ENABLED_USERS=emma;
  • voce menu Produttivita -> Assistente AI aggiunta per tenant abilitati;
  • safeops-web.service riavviato e tornato active.

Configurazione AI tenant:

SAFEOPS_AI_ENABLED_TENANTS=tenant_besant,tenant_echos,tenant_safecondo

SAFEOPS_AI_ENABLED_USERS=emma,jeme

Abilitazione Jeme Formazione - 2026-07-10

Richiesta:

  • abilitare anche l'utente che gestisce formazione Besant.

Utente rilevato:

  • username corretto: jeme;
  • email: formazione@besantsrl.it;
  • ruolo: ROLE_PROFILE_FORMAZIONE_OPERATORE.

Correzione:

  • aggiunto jeme a SAFEOPS_AI_ENABLED_USERS;
  • aggiunto ROLE_PROFILE_FORMAZIONE_OPERATORE ai permessi menu Produttivita -> Assistente AI;
  • estesa guardrail: Besant ha sia RAS sia formazione, quindi l'AI non deve applicare automaticamente logiche Safecondo/Extrabit a Besant.

Correzione Guardrail Besant DVR - 2026-07-10

Problema rilevato:

  • su un documento Besant DVR, il modello ha interpretato DVR come Video Recording Device;
  • ha citato Safecondo anche se il prompt era nel contesto Besant.

Correzione:

  • nel contesto SafeOps/Besant, DVR significa Documento di Valutazione dei Rischi;
  • se il prompt indica Besant, l'AI non deve citare Safecondo salvo richiesta esplicita;
  • per i documenti Besant DVR del cliente Cat - Baha Bajram, DVR_Agricoltori puo' essere citata solo come categoria candidata/manuale da confermare.

Seconda correzione:

  • il modello ha ancora suggerito RAS / Legacy Dynamic per un DVR Besant;
  • aggiunta regola esplicita: su Besant non usare categorie Safecondo RAS / ... salvo documento esplicitamente RAS;
  • per un DVR Besant non suggerire mai RAS / Legacy Dynamic.

Terza correzione:

  • il modello ha suggerito DVR_Agricoltori per un ristorante;
  • corretto: la categoria DVR non va dedotta solo dal cliente, ma dal settore/oggetto del documento;
  • categorie DVR esistenti rilevate: DVR_Agricoltori, DVR_Azienda, DVR_Condominio;
  • per ristorante/bar/attivita' commerciale non suggerire DVR_Agricoltori;
  • per DVR ristorante l'AI puo' citare DVR_Azienda solo come categoria candidata/manuale da confermare, oppure revisione manuale se serve categoria piu' specifica.

Prossima verifica applicativa:

  • accedere come utente Besant e Safecondo autorizzato;
  • aprire /ai/assistant;
  • verificare /api/ai/status;
  • inviare prompt breve;
  • validare che l'output resti solo suggerimento, senza scritture.

Correzione Menu Emma - 2026-07-10

Problema rilevato:

  • Emma era loggata ma non vedeva Produttivita -> Assistente AI.

Causa:

  • la voce era stata aggiunta al menu, ma non ancora registrata come label strutturale per i permessi menu AppBuilder;
  • Emma ha ruolo ROLE_PROFILE_TECNICO.

Correzione:

  • registrata label strutturale Assistente AI sotto Produttivita;
  • assegnato menu_access a ROLE_PROFILE_TECNICO, ROLE_PROFILE_ADMIN_TECNICO, ROLE_PROFILE_ADMIN_TENANT, ROLE_PROFILE_OPERATORE_ADMIN;
  • eseguita sync permessi AppBuilder;
  • riavviato safeops-web.service;
  • servizio verificato active.

Correzione Template AI - 2026-07-10

Problema rilevato:

  • accesso diretto a https://safecondo.nxt-sense.eu/ai/assistant generava errore 500.

Causa:

  • la route blueprint renderizzava un template che estende appbuilder/baselayout.html;
  • il contesto appbuilder non veniva passato al template.

Correzione:

  • importato appbuilder nella blueprint AI;
  • passato appbuilder=appbuilder a render_template;
  • test gateway AI passati;
  • servizio web riavviato;
  • controllo anonimo locale /ai/assistant ora restituisce redirect login 302, non errore 500.

Guardrail Prompt AI - 2026-07-10

Problema rilevato nel primo test:

  • il modello rispondeva correttamente, ma in modo troppo generico;
  • proponeva azioni non ammesse in produzione, come sostituzione/correzione immagini, aggiornamento mapping e nuovi campi.

Correzione:

  • aggiunto prompt di sistema server-side SAFEOPS_AI_SYSTEM_PROMPT;
  • il prompt viene anteposto automaticamente a ogni richiesta chat;
  • l'assistente deve rispondere sempre con: sintesi, categoria suggerita, warning, motivazione, azione consigliata;
  • l'assistente non deve proporre modifiche automatiche a DB, categorie, checklist, mapping, documenti o MinIO;
  • sui mapping ambigui deve indicare revisione manuale, blocco dell'applicazione automatica e audit della decisione.

Verifiche:

  • test gateway AI passati: 6;
  • servizio web riavviato e attivo.

Controllo Qualita' RAS AI - 2026-07-10

Decisione:

  • il controllo qualita' RAS e' fattibile, ma deve partire in modalita' report/warning;
  • il primo livello deve controllare testo, coerenza logica, completezza risposte, riferimenti foto/gallery e presenza di immagini sincronizzate;
  • l'analisi reale del contenuto visivo delle foto richiede un modello vision o pipeline immagine dedicata e va trattata come fase successiva;
  • nessuna correzione automatica su testo, foto, categorie, mapping, documenti o MinIO.

Documento di dettaglio:

  • docs/processo/report/ai_ras_quality_control_plan_2026-07-10.md.

Stato implementazione:

  • creato endpoint read-only POST /api/ai/ras-quality;
  • creato servizio app/services/ai_ras_quality.py;
  • controlli fase 1 metadata/text-only implementati;
  • aggiunto pulsante Controllo AI in Incarichi Tecnici per RAS compilati ma non completati/chiusi;
  • test gateway AI passati: 10.

Retrieval Documentale Autorizzato - 2026-07-10

Obiettivo:

  • preparare il primo canale AI per cercare documenti senza superare i permessi dell'utente;
  • gestire correttamente utenti con piu' ruoli, usando lo scope documentale gia' esistente.

Implementazione:

  • aggiunto servizio read-only app/services/ai_retrieval.py;
  • aggiunto endpoint POST /api/ai/search-documents;
  • l'endpoint e' disponibile solo se l'AI e' abilitata per tenant e utente;
  • la ricerca usa il tenant corrente e riusa lo scope documentale esistente:
  • accesso globale solo per profili admin previsti;
  • lista clienti visibili per operatori/tecnici/condomini;
  • default deny se non ci sono clienti autorizzati;
  • filtro tecnico aggiuntivo tramite visibility documentale esistente;
  • il risultato restituisce solo metadati autorizzati: documento, clienti, categorie, date e stato;
  • nessun contenuto MinIO viene letto o passato al modello in questa fase.

Verifiche:

  • test gateway AI passati: 8;
  • compilazione sintattica di gateway e retrieval eseguita;
  • servizio web riavviato e attivo.

Guardrail Tassonomia Safecondo - 2026-07-10

Problema rilevato nel secondo test:

  • il modello ha mantenuto un comportamento prudente;
  • pero' ha inventato una categoria non prevista: RAS/Safecondo - Supporto e Risoluzione Anomalie.

Correzione:

  • aggiunte al prompt di sistema le categorie tecniche Safecondo ammesse:
  • RAS / Legacy Dynamic;
  • RAS / Pacchetti Extrabit;
  • RAS / Payload Extrabit;
  • RAS / Schede NC;
  • esplicitato che Extrabit e' ammesso solo su Safecondo;
  • vietato inventare nomi categoria;
  • se nessuna categoria ammessa e' coerente, l'AI deve indicare revisione manuale.

Verifiche:

  • test gateway AI passati: 6;
  • servizio web riavviato e attivo.