LLM-wiki della tesi — prototipo dimostrativo

Prototipo dimostrativo, non un prodotto. Mostra come trasformare uno o più documenti tecnici (qui una sola tesi) in una base di conoscenza che un agente LLM può interrogare, con risposte che citano la posizione nella fonte e mostrano le figure. Le risposte vanno verificate sulla fonte (vedi Limiti).

La tesi è «Sintesi e caratterizzazione di copolimeri bottle brush foto-elettro attivi» (Chimica Industriale, Università di Bologna, Dip. «Toso Montanari», a.a. 2025-2026; candidata Aurora Luzi, relatore Dr. Stefano Scurti): semiconduttori polimerici emissivi π-coniugati con scheletro DPP-3HT e catene laterali di PCL.

In breve

• Il repository segue lo schema della LLM Wiki di Karpathy ed è compatibile con Obsidian.
• Non usa un RAG vettoriale: la conoscenza è compilata in pagine Markdown collegate e l'agente la consulta navigando.
• Anche le figure sono indicizzate, così l'agente le trova, le guarda e le usa per spiegare.

Indice

Idea · Architettura · Come si usa · Come è costruito · Le figure · Come risponde · Limiti

Idea

Perché non un RAG classico. Un RAG richiede di spezzare i documenti in chunk, trasformarli in vettori (embedding) e mantenere un indice vettoriale: passaggi dispendiosi, da rifare a ogni modifica delle fonti. Qui la conoscenza è compilata una volta in pagine Markdown collegate (concetti, composti, tecniche, figure, dati, difetti noti). L'agente la interroga navigando indice, link e ricerca testuale, legge le pagine intere e compone la risposta, senza vettorizzazione né chunking.

Aggiornabile. La wiki si estende o si corregge (nuove fonti, nuove versioni della tesi) con i flussi della LLM Wiki (ingest, lint, riallineamento), toccando solo le pagine interessate e senza ricostruire alcun indice. Questo approccio tende a essere più semplice da mantenere di un RAG.

Compromesso. La navigazione per indice funziona su una wiki di queste dimensioni (una tesi); su corpora molto grandi potrebbe non scalare (inferenza).

Architettura

flowchart LR
    R["raw/<br/>fonti immutabili"] --> W["wiki/<br/>pagine collegate"]
    W --> A["Agente LLM"]
    S["CLAUDE.md + skill<br/>regole di consultazione"] --> A
    A --> U["Risposta citata<br/>con figure"]

Livello	Cartella	Ruolo
Fonti	raw/	Tesi, riassunto, immagini, catalogo figure, bibliografia. Sola lettura.
Wiki	wiki/	Concetti, composti, tecniche, figure, dati, analisi dei difetti. Scritta e mantenuta dall'LLM.
Regole	CLAUDE.md, .agents/skills/	Come l'agente recupera, integra e cita.

CLAUDE.md                schema di consultazione (regole RAG)
AGENTS.md  GEMINI.md     puntatori a CLAUDE.md per Codex, Antigravity, Gemini CLI
.agents/skills/          tesi-query, tesi-figure, tesi-dati, tesi-fonti
.claude/skills           link simbolico a .agents/skills (per Claude Code)
index.md   log.md        catalogo delle pagine e registro delle modifiche
raw/                     tesi.md, immagini/, immagini.json, bibliografia.json, fonti/, riassunto
wiki/                    overview, concepts/, compounds/, techniques/, figures/, analyses/, dati.md, ...
scripts/                 gen_figures.py, gen_bibliografia.py, lint.py

wiki/ si apre anche con Obsidian (link [[wikilink]], configurazione in .obsidian/).

Come si usa

1. Clona il repository e aprilo con un agente a riga di comando: Claude Code, Codex o Antigravity CLI. Skill e file di schema (CLAUDE.md, AGENTS.md) vengono trovati da soli. Obsidian è facoltativo, serve solo per sfogliare la wiki.
2. Fai una domanda in italiano, per esempio:
   • «Perché il PCL evita l'ACQ allo stato solido?»
   • «Confronta il band gap elettrochimico dei campioni bottle brush e mostrami i voltammogrammi.»
   • «Come si ottiene lo scheletro DPP-3HT? Mostrami lo schema di sintesi.»
   • «Chi ha proposto il meccanismo di formazione del DPP citato nella tesi?»
3. Puoi invocare una skill per nome: tesi-query (domande generali), tesi-figure (immagini), tesi-dati (valori e tabelle esatti), tesi-fonti (bibliografia).

La wiki è usata in sola lettura: l'agente non la modifica salvo richiesta esplicita. Lo schema di manutenzione (ingest, riallineamento, lint) resta nella cronologia git di CLAUDE.md, fino al commit eb672df.

Come è costruito

flowchart LR
    T["Tesi<br/>(docx / PDF)"] --> M["MinerU"]
    M --> R["raw/<br/>testo, immagini,<br/>catalogo, bibliografia"]
    R --> L["Ingest LLM<br/>per capitolo"]
    L --> W["wiki/"]

• Estrazione con MinerU. Strumento open source che converte documenti in Markdown strutturato, con tabelle, formule in LaTeX e figure ritagliate come file immagine. Il suo output è la base di raw/tesi.md (1446 righe) e di raw/immagini/ (file con nome = hash). Il testo è stato poi riallineato alla versione Word della tesi con le convenzioni dello schema di manutenzione. I parametri usati non sono registrati nel repository.
• Catalogo delle figure e bibliografia. Un catalogo (raw/immagini.json) e 63 riferimenti (raw/bibliografia.json, schede in raw/fonti/ con citazione verificata, DOI, abstract e frasi della tesi che li citano).
• Compilazione della wiki. Un LLM legge la tesi capitolo per capitolo e scrive le pagine organizzate per argomento, con il localizzatore tesi_loc (sezione e righe di raw/tesi.md) in ogni pagina.
• Parti generate da script. gen_figures.py (schede figura e indice) e gen_bibliografia.py (bibliografia) rigenerano le pagine derivate dai cataloghi; lint.py controlla link rotti, pagine orfane, frontmatter, coerenza di figure e riferimenti, e che i numeri nelle pagine compaiano in raw/tesi.md.

Le figure

Schemi di sintesi, strutture, spettri e voltammogrammi non si trovano cercando parole, quindi ogni figura è stata resa ricercabile e collegata al testo.

flowchart LR
    F["File immagine<br/>da MinerU"] --> C["Catalogo<br/>immagini.json"]
    T["raw/tesi.md<br/>righe e didascalie"] --> C
    C --> G["gen_figures.py"]
    G --> N["wiki/figures/<br/>una scheda per figura"]

• Figure logiche. I file sono raggruppati in 80 figure della tesi e 11 del riassunto (una figura può avere più pannelli, quindi più file: per questo i conteggi di file e figure non coincidono). Id stabile fig-NNN, oppure fig-x-<hash> per gli schemi di §3.2 senza numero.
• Catalogo raw/immagini.json. Per figura: posizione nella tesi, didascalia stampata, descrizione e testo visibile per pannello (scritti guardando l'immagine), composti, concetti, parole chiave, tipo (struttura, schema di reazione, meccanismo, spettro, voltammogramma, grafico, foto…), righe che la citano, confidenza e note di revisione.
• Revisione. Una verifica indipendente segnala le discrepanze (es. didascalia che non descrive l'immagine: Fig. 26, 27, 29, 58, 66, 67, 69); sono segnalate, non corrette. Dopo ogni nuova versione della tesi le immagini sono state confrontate con il Word e quelle vecchie sostituite.
• Schede derivate. gen_figures.py genera wiki/figures/fig-NNN.md (con l'immagine incorporata in Obsidian) e figure-indice.md, e aggiunge in fondo le pagine wiki che usano la figura. Non si modificano a mano: si corregge il catalogo e si rigenera.

Solo la didascalia stampata è testo della tesi; il resto deriva dall'immagine e non è verificato. Non è registrato nel repository quale modello abbia prodotto descrizioni e revisione.

Uso nelle risposte. L'agente arriva alla figura dai link nelle pagine già lette, da figure-indice.md o cercando per composto o concetto nelle schede. Poi apre il file in raw/immagini/ e lo guarda davvero, perché la sola descrizione generata non basta a spiegare un grafico; infine lo commenta (cosa guardare e perché) citando percorso e scheda [[fig-NNN]]. I valori letti da un grafico vanno confermati sulla tesi. Regole complete in tesi-figure.

Come risponde a una domanda

flowchart TD
    Q["Domanda"] --> N["1 Naviga: indice, glossario,<br/>dati, campioni"]
    N --> L["2 Legge le pagine intere<br/>e segue i link"]
    L --> V["3 Verifica i valori su<br/>raw/tesi.md e i difetti noti"]
    V --> F{"Servono figure?"}
    F -->|sì| G["4 Apre la scheda e<br/>guarda l'immagine"]
    F -->|no| S
    G --> S["5 Sintesi: tesi prima,<br/>poi conoscenza del modello"]
    S --> O["Risposta con citazioni"]

• Prima la tesi, poi l'integrazione. I dati vengono dalla wiki e dalla tesi, con posizione (§4.2, Tab. 14, r.812) e riferimento bibliografico. La conoscenza generale del modello spiega perché e come, ed è marcata (conoscenza generale); le deduzioni sono (inferenza).
• Perimetro. L'integrazione resta dentro gli argomenti della tesi; fuori perimetro l'agente dice che la tesi non li tratta.
• Fedeltà dei dati. Valori, unità e condizioni copiati alla lettera; valori di condizioni diverse non sono confrontati senza avviso.

Dettagli in CLAUDE.md.

Limiti e avvertenze

• Prototipo. Dimostra il metodo su una sola tesi; nessuna garanzia di correttezza.
• Contenuto derivato dalle immagini non verificato. Descrizioni, testo visibile e didascalie generate possono contenere errori.
• Difetti della tesi segnalati, non corretti. In wiki/analyses/difetti-noti.md: per esempio PDI di 3b (Tab. 9) incoerente con Mw/Mn, % DPP di 3c (35 o 36), band gap delle Conclusioni incoerente con la Tab. 14, voci bibliografiche duplicate o con DOI errato.
• Integrazione del modello. Le parti marcate (conoscenza generale) o (inferenza) non provengono dalla tesi.
• Link simbolico. .claude/skills è un link simbolico: su Windows può richiedere un checkout con supporto ai symlink.

Licenza

Vedi LICENSE (Creative Commons Attribution 4.0 International).