# 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](#limiti-e-avvertenze)). 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](#idea) · [Architettura](#architettura) · [Come si usa](#come-si-usa) · [Come è costruito](#come-è-costruito) · [Le figure](#le-figure) · [Come risponde](#come-risponde-a-una-domanda) · [Limiti](#limiti-e-avvertenze) ## 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 ```mermaid flowchart LR R["raw/
fonti immutabili"] --> W["wiki/
pagine collegate"] W --> A["Agente LLM"] S["CLAUDE.md + skill
regole di consultazione"] --> A A --> U["Risposta citata
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 ```mermaid flowchart LR T["Tesi
(docx / PDF)"] --> M["MinerU"] M --> R["raw/
testo, immagini,
catalogo, bibliografia"] R --> L["Ingest LLM
per capitolo"] L --> W["wiki/"] ``` - **Estrazione con [MinerU](https://github.com/opendatalab/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. ```mermaid flowchart LR F["File immagine
da MinerU"] --> C["Catalogo
immagini.json"] T["raw/tesi.md
righe e didascalie"] --> C C --> G["gen_figures.py"] G --> N["wiki/figures/
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-` 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`](.agents/skills/tesi-figure/SKILL.md). ## Come risponde a una domanda ```mermaid flowchart TD Q["Domanda"] --> N["1 Naviga: indice, glossario,
dati, campioni"] N --> L["2 Legge le pagine intere
e segue i link"] L --> V["3 Verifica i valori su
raw/tesi.md e i difetti noti"] V --> F{"Servono figure?"} F -->|sì| G["4 Apre la scheda e
guarda l'immagine"] F -->|no| S G --> S["5 Sintesi: tesi prima,
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](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](LICENSE) (Creative Commons Attribution 4.0 International).