docs: allinea README alla struttura reale del progetto

Corregge struttura progetto (step-N/ invece di scripts/ e processed/), aggiorna script, comandi e path per step 1–3, rimuove riferimenti a marker-pdf (sostituito da pymupdf4llm), snellisce step 7 e 9 con rimando ai README dedicati, segna step 10 come da implementare
2026-04-14 15:57:49 +02:00
parent f27ebfa101
commit 8fa07784ae
1 changed files with 80 additions and 111 deletions
@@ -3,7 +3,7 @@
 Sistema RAG (Retrieval-Augmented Generation) costruito da zero, senza framework di alto livello.
 Funziona su qualsiasi PDF digitale. Gira interamente in locale, senza GPU, senza cloud.

-**Stack:** Python · Ollama · nomic-embed-text · Qwen3 8B · ChromaDB  
+**Stack:** Python · Ollama · nomic-embed-text · Qwen3.5 · ChromaDB  
 **Compatibile con:** Linux · macOS · Windows (WSL2) · CPU Only · ~8 GB RAM libera

 ---
@@ -72,25 +72,54 @@ rag-from-scratch/
 ├── sources/                        # PDF originali — non modificare mai
 │   └── documento.pdf
 │
-├── processed/                      # Output di ogni step per ogni documento
-│   └── documento/
-│       ├── raw.md                  # MD grezzo da marker (non toccare)
-│       ├── clean.md                # MD revisionato a mano
-│       ├── structure_profile.json  # Profilo struttura da step 3
+├── step-0/
+│   └── check_pdf.py                # Verifica requisiti del PDF
+│
+├── step-1/
+│   └── inspect_pdf.py              # Ispezione automatica del PDF
+│
+├── step-2/
+│   ├── convert_pdf.py              # Conversione PDF → Markdown grezzo
+│   └── <stem>/
+│       └── raw.md                  # MD grezzo (non toccare)
+│
+├── step-3/
+│   ├── detect_structure.py         # Rilevamento struttura MD
+│   └── <stem>/
+│       └── structure_profile.json  # Profilo struttura
+│
+├── step-4/
+│   ├── revise.py                   # Pre-processing automatico MD
+│   ├── revision_log.md             # Log modifiche manuali
+│   └── <stem>/
+│       ├── clean.md                # MD revisionato
+│       └── structure_profile.json  # Profilo aggiornato
+│
+├── step-5/
+│   ├── chunker.py                  # Chunking adattivo
+│   └── <stem>/
 │       └── chunks.json             # Chunk pronti per la vettorizzazione
 │
-├── scripts/
-│   ├── inspect.py                  # Step 1 — ispezione PDF
-│   ├── detect_structure.py         # Step 3 — analisi struttura MD
-│   ├── chunker.py                  # Step 5 — chunking adattivo
-│   ├── verify_chunks.py            # Step 6 — verifica chunk
-│   ├── ingest.py                   # Step 8 — vettorizzazione
-│   ├── rag.py                      # Step 9 — pipeline RAG
-│   └── test_pipeline.py            # Step 10 — test automatici
+├── step-6/
+│   ├── verify_chunks.py            # Verifica chunk
+│   ├── fix_chunks.py               # Fix chunk problematici
+│   └── <stem>/
+│       └── chunks.json             # Chunk verificati
 │
-├── chroma_db/                      # Vector store — generato da ingest.py
-├── notes/
-│   └── revision_log.md             # Log delle modifiche manuali al MD
+├── step-7/
+│   ├── check_env.py                # Verifica ambiente locale
+│   └── README.md                   # Guida installazione Ollama e dipendenze
+│
+├── step-8/
+│   └── ingest.py                   # Vettorizzazione → ChromaDB
+│
+├── step-9/
+│   ├── config.py                   # Configurazione pipeline RAG ← modifica qui
+│   ├── rag.py                      # Pipeline RAG interattiva
+│   ├── test_ollama.py              # Test chat Ollama senza RAG
+│   └── README.md
+│
+├── chroma_db/                      # Vector store — generato da step-8
 ├── requirements.txt
 ├── .gitignore
 └── README.md
@@ -136,15 +165,15 @@ Se ottieni caratteri strani o testo nell'ordine sbagliato, il PDF ha problemi.
 ### Step 1 — Ispezione automatica

 **Tipo:** automatico  
-**Input:** `sources/documento.pdf`  
-**Output:** report testuale con score e lista problemi  
-**Script:** `scripts/inspect.py`
+**Input:** tutti i PDF in `sources/`  
+**Output:** `step-1/<stem>_step1_report.txt`  
+**Script:** `step-1/inspect_pdf.py`

 ```bash
-python scripts/inspect.py sources/documento.pdf --save
+python step-1/inspect_pdf.py
 ```

-Lo script analizza il PDF pagina per pagina e produce un report.
+Lo script scansiona automaticamente tutti i PDF in `sources/`, analizza ogni documento pagina per pagina e produce un report.
 Serve per capire la qualità del documento e mappare i problemi
 prima di affrontare la revisione manuale.

@@ -186,33 +215,29 @@ PROSSIMI PASSI:
 ### Step 2 — Conversione in Markdown grezzo

 **Tipo:** automatico  
-**Input:** `sources/documento.pdf`  
-**Output:** `processed/documento/raw.md`  
-**Tool:** marker-pdf
+**Input:** tutti i PDF in `sources/` (o uno solo con `--pdf`)  
+**Output:** `step-2/<stem>/raw.md` + `step-2/<stem>/clean.md`  
+**Script:** `step-2/convert_pdf.py`

 ```bash
-marker_single sources/documento.pdf processed/documento/raw.md
+python step-2/convert_pdf.py                         # tutti i PDF in sources/
+python step-2/convert_pdf.py --pdf sources/doc.pdf   # un solo PDF
 ```

-Converte il PDF in Markdown. Il risultato non è perfetto — è la base
+Converte il PDF in Markdown usando `pymupdf4llm`. Il risultato non è perfetto — è la base
 su cui lavorerai nello step 4.

-**Regola fondamentale:** `raw.md` non va mai modificato.
-È il punto di partenza di riferimento. Se qualcosa va storto
-nella revisione, puoi sempre ripartire da qui.
+Lo script crea due file:
+- `raw.md` — conversione grezza, **non modificare mai**. È il punto di partenza di riferimento.
+- `clean.md` — copia di lavoro che verrà modificata negli step successivi.

-```bash
-# Crea subito la copia su cui lavorare
-cp processed/documento/raw.md processed/documento/clean.md
-```
-
-**Cosa produce marker:**
+**Cosa produce la conversione:**

 - Titoli riconosciuti e convertiti in `#` `##` `###`
 - Paragrafi separati da righe vuote
 - Sillabazione parzialmente risolta

-**Cosa non produce marker:**
+**Cosa non produce:**

 - Rimozione intestazioni e piè di pagina
 - Correzione completa del layout a colonne
@@ -223,15 +248,17 @@ cp processed/documento/raw.md processed/documento/clean.md
 ### Step 3 — Rilevamento struttura

 **Tipo:** automatico  
-**Input:** `processed/documento/raw.md`  
-**Output:** `processed/documento/structure_profile.json`  
-**Script:** `scripts/detect_structure.py`
+**Input:** `step-2/<stem>/`  
+**Output:** `step-3/<stem>/structure_profile.json`  
+**Script:** `step-3/detect_structure.py`

 ```bash
-python scripts/detect_structure.py processed/documento/raw.md
+python step-3/detect_structure.py                    # tutti i documenti in step-2/
+python step-3/detect_structure.py --stem <nome>      # un solo documento
+python step-3/detect_structure.py --force            # riesegui anche se già presente
 ```

-Analizza la struttura del Markdown grezzo senza modificarlo.
+Copia `raw.md` e `clean.md` da `step-2/<stem>/` e analizza la struttura del Markdown senza modificarla.
 Il profilo prodotto guida sia la revisione manuale che il chunker.

 **I quattro livelli strutturali:**
@@ -472,35 +499,14 @@ Distribuzione lunghezze:
 **Output:** ambiente locale funzionante  
 **Script:** `step-7/check_env.py`

+Installa Ollama, scarica i modelli e verifica l'ambiente. Si esegue una volta sola.
+
+Vedi [`step-7/README.md`](step-7/README.md) per istruzioni dettagliate e scelta dei modelli.
+
 ```bash
-# Installa Ollama
-curl -fsSL https://ollama.com/install.sh | sh
-
-# Scarica un modello di embedding e un LLM
-ollama pull nomic-embed-text   # Embedding — ~274 MB (consigliato)
-ollama pull qwen3.5:4b         # LLM — ~3.4 GB (consigliato per 8 GB RAM)
-
-# Installa dipendenze Python nel venv
-source .venv/bin/activate
-pip install -r requirements.txt
-
-# Verifica tutto
 python step-7/check_env.py
 ```

-**Modelli consigliati per 8 GB RAM:**
-
-| Modello | Ruolo | Dimensione |
-|---|---|---|
-| `nomic-embed-text` | Embedding | ~274 MB |
-| `qwen3.5:4b` | LLM | ~3.4 GB |
-
-Per guide dettagliate su modelli alternativi, installazione e disinstallazione
-di Ollama e ChromaDB, vedi [`step-7/README.md`](step-7/README.md).
-
-Questo step si esegue una volta sola. Da questo momento
-Ollama è sempre disponibile sul sistema.
-
 ---

 ### Step 8 — Vettorizzazione
@@ -575,53 +581,16 @@ Non è necessario ripetere questo step a meno che il documento cambi.
 **Tipo:** interattivo  
 **Input:** `chroma_db/` + domanda dell'utente  
 **Output:** risposta basata sul documento  
-**Script:** `scripts/rag.py`
+**Script:** `step-9/rag.py`

 ```bash
-python scripts/rag.py
+source .venv/bin/activate
+python step-9/rag.py --stem <nome>
 ```

-Mette insieme retrieval e generation in un loop interattivo.
+Loop interattivo che risponde a domande sul documento. Configura i parametri in `step-9/config.py` prima di avviare.

-**Flusso per ogni domanda:**
-
-```
-La tua domanda in testo
-    │
-    ▼  embedding della domanda (nomic-embed-text)
-vettore 768 dimensioni
-    │
-    ▼  ricerca per similarità coseno in ChromaDB
-top 3 chunk semanticamente più vicini
-    │
-    ▼  costruzione del prompt
-"Rispondi SOLO dal contesto:
- [chunk 1]
- [chunk 2]
- [chunk 3]
- Domanda: ..."
-    │
-    ▼  Ollama (Qwen3 8B)
-risposta generata
-```
-
-**Come si usa:**
-
-```
-Domanda: La tua domanda qui
-Domanda: La tua domanda qui -v    ← aggiunge i chunk recuperati
-Domanda: exit
-```
-
-**La similarità coseno:**
-Misura l'angolo tra due vettori — non la distanza ma l'orientamento.
-Due testi semanticamente simili puntano nella stessa direzione
-nello spazio a 768 dimensioni, indipendentemente dalla loro lunghezza.
-
-**Regola del prompt:**
-Il LLM risponde SOLO dal contesto fornito.
-Se la risposta non è nel documento lo dice esplicitamente.
-Non inventa, non integra con conoscenza esterna.
+Vedi [`step-9/README.md`](step-9/README.md) per la configurazione completa.

 ---

@@ -630,10 +599,10 @@ Non inventa, non integra con conoscenza esterna.
 **Tipo:** automatico  
 **Input:** sistema completo  
 **Output:** tutti i test verdi  
-**Script:** `scripts/test_pipeline.py`
+**Script:** `step-10/test_pipeline.py` *(da implementare)*

 ```bash
-python scripts/test_pipeline.py
+python step-10/test_pipeline.py --stem <nome>
 ```

 Verifica ogni componente in isolamento e poi nel sistema completo.