cyber-tesi/README.md

# 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

_Il diagramma mostra i tre ingredienti del sistema e come arrivano alla risposta: le fonti (blu) vengono compilate nella wiki (verde); l'agente (rosa) legge la wiki e segue le regole (giallo) per produrre la risposta._

```mermaid
flowchart LR
    R["raw/<br/>fonti immutabili"] -->|"compilate in"| W["wiki/<br/>pagine collegate"]
    W -->|"consultata da"| A["Agente LLM"]
    S["CLAUDE.md + skill<br/>regole di consultazione"] -->|"guidano"| A
    A -->|"produce"| U["Risposta citata<br/>con figure"]
    classDef fonte fill:#dbeafe,stroke:#1e40af,color:#111
    classDef wiki fill:#dcfce7,stroke:#166534,color:#111
    classDef regole fill:#fef9c3,stroke:#854d0e,color:#111
    classDef agente fill:#fce7f3,stroke:#9d174d,color:#111
    classDef script fill:#e5e7eb,stroke:#374151,color:#111
    class R fonte
    class W wiki
    class S regole
    class A,U agente
```

**Legenda colori (valida per tutti i diagrammi):** 🟦 fonti in `raw/` · 🟩 wiki in `wiki/` · 🟨 regole e skill · 🟪 agente e risposta · ⬜ script. Le frecce con etichetta indicano l'azione che collega due blocchi.

| 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, tesi-narrate
.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), `tesi-narrate` (briefing, spiegazione o lezione citati).

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

_Il diagramma segue il materiale dal documento originale alla wiki, in quattro passi da sinistra a destra._

```mermaid
flowchart LR
    T["1 Tesi<br/>docx / PDF"] -->|"estrazione"| M["2 MinerU"]
    M -->|"Markdown + figure"| R["3 raw/<br/>testo, immagini,<br/>catalogo, bibliografia"]
    R -->|"lettura per capitolo"| L["4 Ingest LLM"]
    L -->|"scrive"| W["wiki/<br/>pagine per argomento"]
    classDef fonte fill:#dbeafe,stroke:#1e40af,color:#111
    classDef wiki fill:#dcfce7,stroke:#166534,color:#111
    classDef regole fill:#fef9c3,stroke:#854d0e,color:#111
    classDef agente fill:#fce7f3,stroke:#9d174d,color:#111
    classDef script fill:#e5e7eb,stroke:#374151,color:#111
    class T,R fonte
    class M script
    class L agente
    class W wiki
```

1. **Tesi:** il documento di partenza. 2. **MinerU:** lo converte in Markdown e ritaglia le figure. 3. **`raw/`:** raccoglie il risultato (testo, immagini, catalogo delle figure, bibliografia) e non si modifica più. 4. **Ingest:** un LLM legge `raw/` capitolo per capitolo e scrive la 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.

_Il diagramma mostra come i file immagine diventano schede ricercabili: due ingressi (le immagini e il testo della tesi) confluiscono nel catalogo, da cui uno script genera le schede._

```mermaid
flowchart LR
    F["1a File immagine<br/>da MinerU"] -->|"descritti"| C["2 Catalogo<br/>immagini.json"]
    T["1b raw/tesi.md<br/>righe e didascalie"] -->|"collegate"| C
    C -->|"letto da"| G["3 gen_figures.py"]
    G -->|"genera"| N["4 wiki/figures/<br/>una scheda per figura"]
    classDef fonte fill:#dbeafe,stroke:#1e40af,color:#111
    classDef wiki fill:#dcfce7,stroke:#166534,color:#111
    classDef regole fill:#fef9c3,stroke:#854d0e,color:#111
    classDef agente fill:#fce7f3,stroke:#9d174d,color:#111
    classDef script fill:#e5e7eb,stroke:#374151,color:#111
    class F,T,C fonte
    class G script
    class N wiki
```

1. **Ingressi:** i file immagine (1a) e il testo della tesi con posizione e didascalia di ogni figura (1b). 2. **Catalogo:** unisce descrizione, testo visibile, composti, concetti e righe di citazione per ogni figura. 3. **Script:** legge il catalogo. 4. **Schede:** una per figura, pronta da cercare e da incorporare in Obsidian.

- **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

_Il diagramma va letto dall'alto in basso: l'agente prima cerca e legge, poi verifica, poi (solo se serve) guarda le figure, infine scrive._

```mermaid
flowchart TD
    Q["Domanda"] --> N["1 Naviga<br/>indice, glossario, dati, campioni"]
    N --> L["2 Legge le pagine intere<br/>e segue i link"]
    L --> V["3 Verifica i valori<br/>su raw/tesi.md e difetti noti"]
    V --> F{"Servono figure?"}
    F -->|"sì"| G["4 Apre la scheda<br/>e guarda l'immagine"]
    F -->|"no"| S
    G --> S["5 Sintesi<br/>tesi prima, poi conoscenza del modello"]
    S --> O["Risposta con citazioni"]
    classDef fonte fill:#dbeafe,stroke:#1e40af,color:#111
    classDef wiki fill:#dcfce7,stroke:#166534,color:#111
    classDef regole fill:#fef9c3,stroke:#854d0e,color:#111
    classDef agente fill:#fce7f3,stroke:#9d174d,color:#111
    classDef script fill:#e5e7eb,stroke:#374151,color:#111
    class Q,O agente
    class N,L,S,G agente
    class V fonte
```

Esempio illustrativo (non è una risposta registrata) con la domanda «Perché il PCL evita l'ACQ allo stato solido?»:

| Passo | Cosa fa l'agente |
|---|---|
| 1 | Dall'indice individua le pagine su ACQ (`acq-e-stato-solido`), PCL (`rop-pcl`) e bottle brush. |
| 2 | Le legge per intero e segue i link verso le sottopagine su aggregati H/J e caratterizzazione allo stato solido. |
| 3 | Controlla i valori su `raw/tesi.md` alle righe indicate da `tesi_loc` e verifica che non ci siano difetti noti. |
| 4 | Trova la figura pertinente, apre il file in `raw/immagini/` e ne descrive il contenuto. |
| 5 | Spiega prima ciò che dice la tesi, con citazioni, poi il meccanismo con la conoscenza generale marcata. |

- **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).