Come funziona la Bottega virtuale di Giuseppe Maggiolini

1. Scopo del sistema

La Bottega virtuale non è una chat generalista. È un assistente storico tematico dedicato a Giuseppe Maggiolini da Parabiago, alla sua arte dell’intarsio, alla sua bottega, ai luoghi della città e alla memoria conservata dalle fonti.

Lo scopo è rendere interrogabile una base di conoscenza curata: l’utente pone una domanda in linguaggio naturale, il sistema cerca i passaggi storici pertinenti e il modello linguistico li rielabora in prima persona, come se a rispondere fosse Maggiolini.

2. Le fonti di partenza

La base storica nasce da quattro fonti principali. In una prima fase erano conservate separatamente; poi sono state fuse in un unico distillato tematico per eliminare ripetizioni e migliorare la pertinenza delle risposte.

3. Come le fonti sono state distillate

In origine le fonti erano molto estese e in parte ridondanti. L’invio integrale dei testi a ogni domanda avrebbe causato risposte meno precise e consumo eccessivo di token. Per questo i contenuti sono stati trasformati in blocchi tematici.

Struttura di un blocco

{
  id: "riale-verri",
  title: "Il conservatore Verri e la riapertura provvisoria",
  category: "Riale di Parabiago",
  priority: "alta",
  sources: ["Officina Maggiolini 2014"],
  keywords: ["verri", "riale", "riapertura", "provvisoria", "fabbrica"],
  text: "Dopo la richiesta di Maggiolini, il conservatore Verri concesse..."
}

Il testo non è un riassunto casuale: è una scheda redazionale costruita per essere cercabile e riutilizzabile dal sistema.

4. Schema generale del funzionamento

5. Come avviene la selezione del contesto

priorità alta      +3
priorità media     +1.5
priorità dettaglio +0.5

termine nelle keyword   +7
termine nel titolo      +5
termine nella categoria +3
termine nel testo       +1.5
corrispondenza generica +0.5
boost tematico          +4

6. Quale prompt viene utilizzato

Il prompt applicativo viene costruito nella pagina HTML. Contiene identità del personaggio, regole di risposta, base storica selezionata, conversazione recente e domanda dell’utente.

Tu sei Giuseppe Maggiolini, il celebre ebanista e intarsiatore di Parabiago vissuto dal 1738 al 1814.

Regole di risposta:
1. Rispondi in prima persona, come se fossi Giuseppe Maggiolini.
2. Usa un tono cortese, colto, sobrio e leggermente settecentesco, ma comprensibile.
3. Usa esclusivamente le informazioni presenti nella base storica fornita qui sotto.
4. Se l'informazione non è presente nei testi, dillo con garbo senza inventare.
5. Se le fonti risultano discordanti, segnala la discordanza senza scegliere arbitrariamente.
6. Non riportare lunghi brani testuali: rielabora in forma divulgativa.
7. Mantieni la risposta abbastanza breve, salvo richiesta esplicita di approfondimento.

Base storica selezionata:
[4 o 5 blocchi scelti dal sistema]

Conversazione recente:
[ultimi scambi, se presenti]

Domanda dell'utente:
[testo della domanda]

7. Come avviene la richiesta a Groq

Il browser non contatta direttamente Groq. La pagina invia il prompt a askGroq.php, che agisce come proxy server. La chiave API resta quindi sul server e non è visibile nel codice della pagina.

fetch('askGroq.php', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  cache: 'no-store',
  body: JSON.stringify({ prompt })
});

askGroq.php inoltra a Groq la richiesta con il modello configurato lato server e restituisce alla pagina soltanto il testo della risposta.

8. Il caso speciale del Riale

La vicenda del Riale di Parabiago riceve un trattamento specifico perché è uno degli episodi più significativi del rapporto fra Maggiolini, il paese, la chiesa e la corte.

• Il sistema distingue che cos’era il Riale.
• Recupera la chiusura del 27 luglio 1780.
• Collega la vicenda al bisogno d’acqua per la fabbrica della chiesa.
• Richiama la richiesta all’arciduca Ferdinando.
• Include il ruolo del conservatore Verri e la riapertura provvisoria.
• Può citare la gioia popolare per il ritorno dell’acqua.

9. Aggiornamenti introdotti nella versione corretta

La versione aggiornata mantiene la stessa logica generale della Bottega virtuale — base storica distillata, selezione del contesto, prompt compatto e passaggio tramite askGroq.php — ma aggiunge alcuni correttivi per rendere le risposte meno ripetitive, più pertinenti al contesto della conversazione e più fedeli ai blocchi storici dominanti.

Riconoscimento dei follow-up

Alcune domande non sono autonome, ma dipendono da ciò che è stato appena detto. Per esempio, dopo una risposta sullo stile, domande come solo questo stile? o hai usato altri stili? devono essere interpretate come richieste di approfondimento sull’evoluzione stilistica, non come nuova domanda generica.

detectLastTopic()
- stile: stile, neoclassico, rococò, barocchetto, Impero
- legni: legni, essenze, specie, 86
- parabiago: Parabiago, Riale, piazza, Ravello

Questa funzione permette alla chat di riconoscere il tema recente della conversazione e di evitare risposte ripetitive o fuori fuoco.

Stile: risposta non ripetitiva

La domanda Qual è il tuo stile? può ricevere una risposta breve e diretta: il mio stile maturo fu pienamente neoclassico. Tuttavia, se l’utente chiede se vi furono altri stili, il sistema deve spiegare l’evoluzione: fase iniziale con influssi barocchetti e rococò, maturità neoclassica e, dopo il 1800, parziale accoglienza di elementi del gusto Impero e delle mode francesi.

Se la domanda contiene: solo, altri, altro, evoluzione
E il tema recente è: stile
Allora rispondere sull’evoluzione stilistica, non ripetere soltanto “neoclassico”.

Legni: elenco completo quando richiesto

Quando l’utente chiede genericamente quali legni fossero usati, il sistema può proporre una sintesi. Ma se l’utente chiede elenca tutte le specie, fammi l’elenco completo o formule analoghe dopo una domanda sui legni, la risposta deve fornire direttamente l’elenco delle 86 essenze. Non deve rispondere che l’elenco potrà essere fornito in seguito.

Se l’utente chiede:
- elenca
- lista
- tutte / tutti
- specie / essenze

E il tema recente è: legni
Allora fornire direttamente l’elenco completo degli 86 legni.

Parabiago e Ravello: più precisione storica

Per le domande su ciò che Maggiolini fece per Parabiago, la risposta non deve restare generica. Deve preferire fatti documentati e riconoscibili: servizio come fabbriciere della chiesa parrocchiale, vicenda del Riale, ampliamento della piazza, anticipo di 14.000 lire e interessamento per la chiesa di Ravello dedicata alla Madonna della Neve.

È stata introdotta una correzione specifica: non usare la formula gestione del Ravello, perché ambigua e poco corretta. La formulazione da preferire è realizzazione o ricostruzione della chiesa di Ravello dedicata alla Madonna della Neve.

Per Parabiago preferire sempre fatti concreti:
- Riale
- chiesa parrocchiale
- piazza davanti alla chiesa
- chiesa di Ravello / Madonna della Neve
- ruolo di fabbriciere

Verità dominanti rafforzate

Alcune risposte devono prevalere sulle alternative plausibili ma meno corrette. Per esempio, alla domanda su chi disegnasse gli intarsi, il sistema deve indicare prima Giuseppe Levati, perché fu per lunghi anni uno dei principali fornitori di disegni e cartoni preparatori della bottega. Altri artisti di corte possono essere ricordati dopo, ma non devono sostituire il nome principale.

Aggiornamento delle regole del prompt

Il prompt conserva le regole originarie, ma aggiunge indicazioni operative più esplicite:

11. Se l’utente chiede un elenco completo, fornisci direttamente l’elenco completo.
12. Non usare formule generiche se la base contiene azioni precise.
13. Per Ravello usa “realizzazione o ricostruzione della chiesa di Ravello dedicata alla Madonna della Neve”; non dire “gestione del Ravello”.

10. Limiti e trasparenza