Arcocat in sintesi: sette scelte tecniche e perche' contano

Questa pagina e' pensata per chi conosce abbastanza un chatbot AI da apprezzarne le scelte, ma non l'ha mai costruito da zero. L'audience tipica sono un amministratore, un capo, un cliente esterno: gente sveglia tecnicamente che vuole capire perche' un sistema e' costruito in un certo modo, senza dover leggere il codice.

Arcocat e' un chatbot tecnico interno per la consultazione di sei cataloghi prodotto di brand reali, sviluppato dentro una PMI manifatturiera italiana del Nordest, successore diretto di BlumCat (che restava su un singolo brand). La sua audience sono i commerciali, gli addetti al magazzino e i tecnici di showroom: persone che tollerano un'interfaccia testuale ma non tollerano codici articolo inventati, regole fisiche sbagliate o tempi di risposta lunghi.

Il punto centrale di questa pagina e' uno: un modello AI generico, da solo, non basta. Per costruire un chatbot tecnico affidabile su un dominio reale serve incollare sette mattoncini specifici sopra al modello. Ogni mattoncino risolve un problema concreto che, se ignorato, manda in errore silenzioso il sistema.

In un colpo d'occhio

#	Cosa farebbe un chatbot AI normale	Scelta di arcocat	Perche' importa
1	Inventa codici prodotto sui cataloghi grezzi	Wiki narrativo curato + grafo di link offline	2107 SKU verificati, zero codici inventati
2	Vede tutti gli strumenti sempre, e' lento e sbaglia	Routing per brand davanti al modello	-57% lunghezza prompt, -46% costo per turno
3	Cerca filtri che non esistono e ritorna risultati sbagliati	Discovery enforcement con suggerimento dei valori reali	Filtri errati silenziosi dimezzati (da 14% a 7%)
4	Puo' suggerire cose fisicamente impossibili	Quattro regole fisiche eseguite fuori dal prompt	Sicurezza non delegata all'AI, sempre verificata
5	L'utente aspetta 8 secondi prima della prima parola	Streaming + cache del prompt riusabile	Tempo alla prima parola 8s a 1.5s, -90% costo prefisso
6	Aggiungere un brand richiede toccare 10 file di codice	Otto file YAML come fonte unica delle policy	Onboarding di un nuovo brand = 5 file YAML + 1 check automatico
7	Cambi una cosa, non sai se ne rompi dieci	27 conversazioni di test + 6 health check in un comando	Ogni intervento chiude con regression OK/WARN/FAIL

1. Wiki narrativo curato + grafo di link

Un chatbot AI generico, se gli dai un PDF di catalogo come e', inventa i codici articolo che non esistono o li sbaglia di una cifra. Non per cattiveria del modello: per come funzionano i modelli, "indovinano" la cifra mancante con la stessa naturalezza con cui completano una frase.

Per evitarlo, arcocat non legge il PDF al volo quando l'utente chiede qualcosa. Prima costruisce un "manuale di consultazione" interno: file di testo organizzati per brand con regole (R), famiglie di prodotto (F), distinte (D), schede di categoria (C), curati a mano da un esperto interno con l'aiuto del modello stesso. Ogni regola e ogni famiglia ha un identificatore (R001, F005) e i link tra parti sono espliciti.

Da questi file di testo, un programma offline costruisce un piccolo grafo (166 entita' e oltre 557 link, in crescita coi brand). Quando l'utente chiede qualcosa, il modello consulta il grafo, non il PDF grezzo. Il risultato e' che i codici articolo che cita sono sempre verificabili: 2107 SKU controllati, zero codici inventati. Il "manuale" e' editabile dall'esperto interno senza toccare codice. Per cataloghi voluminosi (sopra le mille pagine) si aggiunge un secondo indice parallelo che permette al modello di citare la pagina esatta del PDF nella risposta.

2. Routing per brand davanti al modello

Quando il modello AI ha 16 strumenti da scegliere ad ogni turno, e' piu' lento, costa di piu' (perche' deve "leggere" le descrizioni di tutti) e sbaglia piu' spesso quale chiamare. Tipico problema dei chatbot generici che vogliono fare tutto in un unico flusso.

La scelta di arcocat e' netta: prima che il modello veda la query, un piccolo programma deterministico (un classificatore basato su espressioni regolari, niente AI) legge la query e capisce di che brand parla. Solo allora il modello viene attivato, con esposti solo i 7-9 strumenti relativi a quel brand invece dei 16 totali. Se la query non e' brand-specifica, il modello vede tutto.

Risultato misurato: lunghezza del prompt iniziale crollata del 57%, costo per turno meno 46%, tempo di risposta meno 13-18%. Un piccolo gesto deterministico davanti al modello vale molto piu' di una "ottimizzazione" interna al modello.

3. Discovery enforcement

Questo e' il problema piu' insidioso che ho incontrato in due anni di chatbot tecnici. L'utente chiede "forni pirolitici", il modello sceglie autonomamente di filtrare nel database per l'attributo "pirolitico=true". Pero' nel database l'attributo si chiama "autopulizia" con valori "pirolitica" o "vapore". Il filtro "pirolitico=true" e' tecnicamente valido (non da' errore), ritorna 21 prodotti, ma di questi solo 11 sono effettivamente pirolitici. Silent wrong: l'utente non vede l'errore.

La scelta di arcocat: un piccolo guardiano deterministico tra il modello e il database. Quando il modello sta per filtrare su un attributo, il guardiano controlla che l'attributo esista davvero nel database. Se non esiste, blocca la richiesta e ritorna al modello un errore strutturato con il sample dei valori realmente disponibili. Il modello impara nel turno successivo e ritenta.

Misurato sui 27 test reali: errori "silenziosi" sui filtri scesi dal 14% al 7%, attributi inventati a 0%, recupero automatico nel 19% dei casi bloccati. Senza che l'utente debba accorgersene.

4. Quattro regole fisiche fuori dal prompt

Un modello AI non conosce, in modo affidabile, la norma EN 60335 (distanza minima cappa-piano cottura). Non sa che un meccanismo di sollevamento ha un range di peso ammesso per anta. Puo' "dirti" le regole se gliele scrivi nel prompt, ma puo' anche "dimenticarle" su una conversazione complessa. In contesti dove la regola serve davvero (sicurezza, regolamento, garanzia), il prompt non basta.

Arcocat ha quattro regole fisiche codificate in file di testo come regole eseguibili. Dopo che il modello ha formulato una risposta, un piccolo motore controlla la risposta contro le regole. Se viola, il modello viene chiamato a riformulare con scuse e suggerimento alternativo. La regola e' deterministica, citabile (porta il numero della norma), e non aggirabile.

Esempio reale: il modello suggerisce un meccanismo di sollevamento per un'anta da 14 kg, ma quel modello ha range fino a 12 kg. La regola fisica blocca, il modello riformula: "il pezzo che ti avevo proposto non regge 14 kg, ecco i due adatti".

La responsabilita' fisica diventa deterministica, non delegata alla "memoria" dell'AI. Per un'azienda che si gioca la reputazione su consigli tecnici, e' la differenza tra fidarsi e non fidarsi.

5. Streaming + cache del prompt riusabile

Prima dell'intervento, l'utente aspettava otto secondi prima di vedere la prima parola della risposta. Inaccettabile per una chat.

Due interventi insieme. Primo, il prompt iniziale (le istruzioni di sistema, le descrizioni degli strumenti, le regole base: circa 9600 token) viene marcato come "riusabile" verso il provider AI. Dal secondo turno in poi, il sistema riceve uno sconto del 96% sul costo di rilettura di quel pezzo. Secondo, la risposta arriva parola per parola (streaming) come in ChatGPT, non in un colpo solo.

Risultato: tempo alla prima parola sceso da 8 secondi a 1.5 secondi percepiti, costo per call sulla parte iniziale crollato da circa 96 millesimi di dollaro a circa 8 millesimi. La differenza in bolletta si vede, ma soprattutto cambia la percezione: la chat sembra una chat, non un form.

6. Otto file di policy come fonte unica

Un sistema che cresce per brand finisce sempre nello stesso modo: regole sparse in dieci file di codice diversi. Aggiungere un brand nuovo diventa un esercizio di archeologia.

Arcocat ha una cartella con otto file di testo (formato YAML, leggibile a occhio): la lista dei brand, le regole del classificatore di routing, le espressioni per riconoscere i codici articolo di ogni brand, i sinonimi commerciali (esempio: "pirolitico" e "Autopulizia pirolitica" sono la stessa cosa), le quattro regole fisiche, i range di peso e dimensioni, gli attributi nativi del database, i tipi di legame nel grafo.

Sopra a questa cartella un controllo automatico esegue 14 verifiche su database reale: la regex SKU di ogni brand becca davvero codici esistenti? Gli alias rimandano davvero ad attributi che esistono? Le regole fisiche fanno riferimento ad attributi presenti?

Onboardare un nuovo brand passa da "dieci file di codice da modificare" a "cinque file YAML da editare + un comando di check che ti dice OK". Editabile da un amministratore non sviluppatore.

7. Refresh orchestrator + 27 test reali

L'ultima scelta e' di metodo, non di architettura: come faccio a sapere che un cambiamento non rompe qualcos'altro?

Esiste un singolo comando che lancia in sequenza sei controlli: l'indicizzatore del wiki narrativo, l'ingestore dei PDF voluminosi, l'audit dei codici articolo contro i range fisici, il check di coerenza wiki vs database, il check di allineamento dei sinonimi, il cross-validator delle otto policy. Sopra a questi sei, una suite di 27 conversazioni di test che simula query reali con assertion non solo sul "tool e' stato chiamato" ma sull'effettivo match degli attributi sui prodotti ritornati.

Severity aggregata, exit code 0 (tutto OK) / 1 (warning) / 2 (errore). Ogni intervento sul sistema e' chiuso con una run di questo refresh, non con un "secondo me funziona". E' la differenza che mi permette di toccare cinque punti del sistema in due settimane senza paura.

Le scelte che ho NON fatto, e perche'

Tre esempi.

Non ho lasciato la safety check al modello AI. Avevo inizialmente uno strumento che l'AI poteva chiamare per chiedere conferma su un consiglio. L'ho deprecato: il motore di guardrail deterministico copre l'intera classe di problemi senza dipendere dalla scelta del modello di "chiamare lo strumento al momento giusto".

Non ho centralizzato i dati in un database di scala industriale da subito. Il design teorico lo suggerirebbe per scalabilita'. La realta' operativa: SQLite e' sufficiente per il primo brand e per i successivi finche' restano sotto i 100.000 chunks. Il database industriale entra solo quando arriva un PIM cross-brand reale, non al day 1.

Non ho adottato un framework agent "completo" (LangGraph, Microsoft Agent Framework, DSPy). Per un singolo sviluppatore in-house in una PMI, l'overhead di astrazione di questi framework e' superiore al beneficio. Ho costruito i pezzi minimi necessari (strumenti standalone, supervisor leggero, contratti tipizzati) sapendo che un giorno potrei migrare, ma senza pagarne il prezzo oggi.

Per chi vuole approfondire

Le sette scelte sopra hanno ognuna uno studio tecnico dedicato. In ordine di profondita':

• Agentizzare una PMI: stack, architettura, strumenti (v2.4): la mappa architetturale completa, 40 minuti di lettura. Per capire come si combinano i sette mattoncini.
• Wiki narrativo AI-maintained (v1.2): il pattern del wiki + grafo, 27 minuti. Per capire come si costruisce il "manuale di consultazione".
• Agentizzare un'azienda: timeline e flussi reali (v1.4): cinque flussi end-to-end, 20 minuti. Per vedere il sistema in azione.
• Onboarding catalogo PDF: playbook 7 fasi (v1.3): come si onboarda un nuovo brand, 25 minuti. Per capire l'effort di manutenzione.

E nel diario tecnico, il post Arcocat, due settimane di hardening racconta in presa diretta le ultime due settimane di lavoro.

Registro aggiornamenti

1. 2026-05-26v1.1

   Aggiornato il brand count (sei cataloghi) e aggiunto il rimando al nuovo studio infrastrutturale "Arcocat come piattaforma agentica", che racconta la svolta a piattaforma e il confine client/server.

2. 2026-05-14v1.0

   Prima stesura. Pagina di sintesi per audience non sviluppatori (amministratori, capi, clienti esterni). Sette scelte tecniche distintive di arcocat in tabella sinottica + sette sezioni narrative. Tre scelte alternative scartate. Cross-link ai quattro studi tecnici di approfondimento.