> **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)_.
_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._
**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.
1. Clona il repository e aprilo con un agente a riga di comando (**Claude Code**, **Codex** o **Antigravity CLI**) oppure con il frontend grafico [agent-wiki-ui](#interfaccia-grafica-agent-wiki-ui). Skill e file di schema (`CLAUDE.md`, `AGENTS.md`) vengono trovati da soli. Obsidian è facoltativo, serve solo per sfogliare la wiki.
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`.
Per interrogare la wiki senza terminale si può usare **[agent-wiki-ui](https://santantonio.sytes.net/davide/agent-wiki-ui.git)** come frontend: un eseguibile C# (.NET 10, Windows e Linux) con una chat in stile claude.ai, che lancia **Claude Code** (`claude -p`) o **Codex** (`codex exec`) nella cartella in cui si trova l'eseguibile. _Antigravity non è ancora supportato dal frontend._
```mermaid
flowchart LR
U["Utente<br/>chat della GUI"] -->|"domanda"| G["agent-wiki-ui<br/>nella radice del repo"]
G -->|"claude -p / codex exec"| E["Motore<br/>Claude Code o Codex"]
E -->|"legge schema e skill"| S["CLAUDE.md / AGENTS.md<br/>.agents/skills/"]
_Il frontend è un semplice contenitore: non ha logica propria sulla wiki. Passa la domanda al motore, che lavora nella radice del repo e quindi trova da solo schema, skill e wiki, poi mostra la risposta._
**Come configurarlo**
1.**Motore.** Installa e autentica `claude` e/o `codex` nel PATH (guida: `docs/INSTALL.md` nel [repository del frontend](https://santantonio.sytes.net/davide/agent-wiki-ui.git)).
2.**Eseguibile.** Ottienilo dal repository del frontend (serve il .NET SDK 10 per compilarlo: `scripts/publish.sh` su Linux/macOS/WSL, `scripts/publish.ps1` su Windows; risultato in `dist/<sistema>/agent-wiki-ui[.exe]`).
3.**Posizione.** Copia l'eseguibile **nella radice di questo repository**, accanto a `CLAUDE.md` e `AGENTS.md`. È fondamentale: il motore parte nella cartella dell'eseguibile, non in quella da cui lo avvii. Gli eseguibili in radice sono ignorati da git.
4.**Avvio.** Doppio clic (Windows) o `./agent-wiki-ui` (Linux, serve X11 o XWayland). Senza argomenti si apre la chat; con argomenti funziona da riga di comando (`./agent-wiki-ui "domanda"`, `--engine codex` per Codex).
**Cose da sapere**
- **Modello e effort.** All'avvio e a ogni cambio di motore il frontend sceglie il modello più piccolo ed effort `low`, per risposte rapide ed economiche. Per le risposte **approfondite e complete** che questo schema richiede, scegli nel riquadro **Impostazioni** un modello più capace e un effort più alto. Le impostazioni non sono salvate su disco: vanno ripetute a ogni avvio.
- **Figure.** Le risposte incorporano le immagini con ``: il frontend le mostra se il file è locale e leggibile (png, jpg, gif, webp, bmp; fino a 20 MB). Gli URL web non vengono caricati.
- **Sola lettura.** Il frontend lancia Codex con sandbox in sola lettura; Claude Code parte senza bypass dei permessi. Coerente con la wiki usata in sola lettura.
- **Chat.** Una chat usa un solo motore; cambiare motore apre una nuova chat. Le conversazioni sono salvate su disco e l'ultima si riapre all'avvio. La risposta compare a fine generazione (nessuno streaming).
- **Stato del frontend.** È un MVP dichiarato tale nel suo repository: i test automatici sono ancora da scrivere e la GUI non è provata su Windows nativo.
- **Non verificato qui.** Non ho provato l'insieme frontend e questo repo: né l'avvio, né che Codex riesca a guardare le immagini in sola lettura.
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._
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 la incorpora nella risposta come immagine e la commenta (cosa guardare e perché), senza stampare percorsi o nomi di schede. I valori letti da un grafico vanno confermati sulla tesi. Regole complete in [`tesi-figure`](.agents/skills/tesi-figure/SKILL.md).
- **Prima la tesi, poi l'integrazione.** I dati vengono dalla wiki e dalla tesi, con la posizione in forma breve (`§4.2, Tab. 14`) e il riferimento bibliografico. Link e nomi di pagine della wiki, percorsi e numeri di riga restano interni e non compaiono nel testo. 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.
