From e54e83eb77e1b2565768e282953adb5f67fc5e13 Mon Sep 17 00:00:00 2001 From: Davide Grilli Date: Tue, 20 Oct 2026 14:30:29 +0200 Subject: [PATCH] Aggiunge README: prototipo, architettura, preparazione con MinerU, indicizzazione figure e flusso di una query Co-Authored-By: Claude Sonnet 5.5 --- README.md | 130 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 130 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..008279c --- /dev/null +++ b/README.md @@ -0,0 +1,130 @@ +# 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).