Knowledge base AI con regole di business live-editabili e double-pass ingest

Contesto

Cliente nel settore ferramenta, catalogo tecnico ampio e complesso: 3.900 codici articolo commerciali (struttura a 12 caratteri con semantica posizionale — famiglia / direzione / serie / finitura), 164 pagine di manuale tecnico con disegni quotati, una quindicina di regole di compatibilità tra componenti (accoppiamenti bandella-cardine con vincoli di diametro, regole su boccole di riduzione con eccezioni per serie, condizioni di applicazione per materiale).

Il sapere tecnico dell'azienda viveva nelle teste di poche persone esperte. I dealer chiamavano il commerciale per domande che si ripetevano ogni settimana: "questa bandella è compatibile con quel cardine?", "per persiane in legno marine cosa mi consigli?", "qual è l'eccezione sulla serie Monza?". Un commerciale nuovo impiegava mesi per diventare autonomo. Il manuale tecnico esisteva ma veniva consultato poco.

L'idea iniziale del cliente era "un ChatGPT che sa del nostro catalogo". Quello che serviva in realtà era più profondo: un sistema che trasformasse la conoscenza aziendale in un asset vivo, editabile dal tecnico interno, verificabile in audit, e che non allucinasse mai dati tecnici critici.

Sfida

Rispetto a un RAG "fai-da-te" servivano tre garanzie che la maggior parte dei chatbot AI non offre:

1. Nessuna risposta oracolare: ogni affermazione deve citare regola applicata + documento sorgente. Se un dealer contesta una risposta, si risale al paragrafo esatto.
2. Nessuna allucinazione silenziosa in fase di estrazione dati dal manuale PDF — errori tipo "misura A2 letta come A" che un ingest single-pass lascia passare senza accorgersene.
3. Autonomia del tecnico interno sulle regole di business. Quando una nuova eccezione emerge da un caso cliente, deve poterla codificare da solo, senza passare da sviluppatori e senza aspettare rilasci.

Approccio

Architettura a quattro strati — fonti autoritative, knowledge base compilata, indici derivati, agente conversazionale — costruita in AI-assisted development con Claude Code. Di seguito le sei cose che fanno davvero la differenza.

Ingest Gemini double-pass con voting e confidence queue

Per estrarre dati dal manuale PDF uso Gemini 2.5 Pro in doppia passata sullo stesso contenuto (pagina renderizzata come PNG). Confronto gli output, assegno un punteggio di confidenza basato sulle divergenze, e ciò che sta sotto la soglia 0.7 finisce in una cartella _review/ per validazione manuale del tecnico. Questa disciplina ha catturato errori silenziosi che un estrattore single-pass aveva lasciato passare (caso reale: A2 letto come A in layout tabellare spread, 44% di errore su una versione intermedia della pipeline).

Agente con 12 tool specializzati e prompt caching aggressivo

Il runtime è Claude Sonnet 4.6 con tool calling. 12 funzioni esposte: sql_query sul mirror SQLite, read_wiki per lettura fresh dal disco, list_regole per il catalogo delle regole tipizzate, calcolo_esposizione che chiama in diretta le WebAPI Mexal per saldo/fido/insoluti, get_kit_giotto_plus per lookup atomico kit, e altri. Il system prompt (~1.500 token con glossario di dominio, regole operative, few-shot) è in prompt cache ephemeral: cache-read a €0,30/1M token invece dei €3/1M dell'input full. Costo reale a regime: €0,04-0,08 per domanda complessa con 3-8 tool call per query.

FAQ memoization con similarity vettoriale e anti-fossilization

Le domande ben risolte vengono promosse a FAQ persistenti in una tabella SQLite con embedding Gemini 3072d (via sqlite-vec). Alla query successiva, il tool search_faq è la prima mossa dell'agente: se la distanza coseno è sotto 0.55 cita testualmente la FAQ (costo marginale zero, zero latenza di ragionamento); tra 0.55-0.80 la usa come traccia; sopra 0.80 ignora.

Il problema noto con le FAQ compilate — che cristallizzano errori se non revisionate — è risolto via schema: ogni FAQ ha last_reviewed_at, reviewed_by, review_note. Un endpoint admin /admin/faq-stale?min_days=90 elenca le FAQ non revisionate, evidenziate in rosso nella dashboard interna. Mitigazione nata dopo aver letto i 632 commenti alla proposta originale del pattern — critica trasformata in schema.

Editor admin live con volume :rw e hot-reload delle regole

Il tecnico del cliente modifica le regole tipizzate (R1-R15) da un'interfaccia web PHP+SQLite separata dal backend dell'agente, con layout "foglio manuale" che gli è familiare. Il volume Docker del wiki è montato :rw, ogni save scrive direttamente sul filesystem con backup .bak-{timestamp} automatico. L'agente legge fresh dal disco al tool call successivo — nessun rebuild, nessun restart, nessun deploy richiesto per un cambio di regola. Cambio condizione commerciale speciale per cliente: 30 secondi dalla modifica all'applicazione in produzione.

Webhook nativi Mexal per reattività event-driven

Feature poco nota di Passepartout: il gestionale ha un sistema di notifiche HTTP native per eventi sugli archivi (PUTPC / DELPC per clienti, PUTAR / DELAR per articoli, PUTMM / DELMM per movimenti magazzino, PUTDE per deleghe). Combinato con le WebAPI in scrittura, il sistema è completamente bidirezionale: nuovo movimento magazzino in Mexal → webhook al backend AI → verifica sotto-scorta contro regola R-MAG-04 → alert automatico al responsabile acquisti. Niente polling, niente cron job: il sistema reagisce in tempo reale agli eventi del gestionale.

Log audit JSONL append-only e analisi costi puntuale

Ogni conversazione finisce in conversations.jsonl con timestamp, IP, user-agent, session_id, query, risposta, tool chiamati, usage token in/out, durata, eventuali errori. Append-only, immutabile. Materiale per tre scopi contemporanei: candidate FAQ da promuovere, eventuali verifiche di conformità normativa, analisi puntuale del costo (token per query × listino modello = costo reale).

Risultato

In produzione HTTPS dal 19 aprile 2026 — dealer B2B che interrogano il sistema in linguaggio naturale, tecnico interno che mantiene autonomamente le regole, log audit che cresce. Costo operativo a regime: ~€60/mese con 50 domande/giorno — ordine di grandezza enterprise-ready su budget PMI.

Il messaggio tecnico più importante di questo progetto, per chi lo guarda da fuori: oggi una PMI italiana può costruire un sistema AI di questa complessità senza adottare prodotti enterprise da decine di migliaia di euro all'anno. Serve disciplina d'architettura (double-pass voting, confidence queue, citation obbligatorie, anti-fossilization delle FAQ, fallback chain espliciti) più gli strumenti giusti. Non AI buttata sopra un catalogo: un sistema in cui ogni pezzo sa cosa fare quando qualcosa va storto, e dove l'errore di produzione più probabile — un'allucinazione silenziosa dell'AI — è intercettato già in fase di ingest.