Aggiunge README: prototipo, architettura, preparazione con MinerU, indicizzazione figure e flusso di una query
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
davideandClaude Sonnet 5.5 committed
1 parent
cee30e7ba0
commit
e54e83eb77
1 file changed
+130
@@ -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/<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
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
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](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<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`](.agents/skills/tesi-figure/SKILL.md).
|
||||||
|
|
||||||
|
## Come risponde a una domanda
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
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](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).
|
||||||
Reference in new issue
Block a user