davide/cyber-tesi
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
dev
cyber-tesi/README.md
T

18 KiB
Raw Permalink Blame History

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

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 · Architettura · Come si usa · Come è costruito · Le figure · Come risponde · Limiti

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.

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
                         (tesi-query/references/: protocollo di retrieval, mappa, ricette di ricerca, checklist)
.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) oppure con il frontend grafico agent-wiki-ui. 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.

Interfaccia grafica (agent-wiki-ui)

Per interrogare la wiki senza terminale si può usare agent-wiki-ui 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.

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/"]
    E -->|"consulta"| W["wiki/ e raw/"]
    E -->|"risposta in Markdown<br/>con immagini"| G
    G -->|"testo e figure"| U
    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 U,E agente
    class G script
    class S regole
    class W wiki

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).
  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 ![descrizione](raw/immagini/<hash>.<ext>): 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.

Come è costruito

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

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

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

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.

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

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 (Creative Commons Attribution 4.0 International).

Reference in new issue View Git Blame Copy Permalink